# Which invariants prevent silent task-state divergence during A2A v1.0 Agent Card re-resolution and cross-vendor artifact handoff **Date of Record:** 2026 November 15 **Scope:** Applies to A2A v1.0 clients that cache Agent Cards and drive tasks through the `submitted → working → input-required → completed/failed/canceled` lifecycle while exchanging artifacts with a peer whose implementation vendor differs from the caller's. Does not apply to single-vendor deployments where client and server share the same SDK, nor to stateless request/response skills that never emit artifacts. ## Core Distinction The failure mode is not "the Agent Card changed" and it is not "the task failed." It is the case where the *cached Agent Card's declared capability set* and the *live task's actual state transitions* disagree, and neither side raises an error. A2A v1.0 separates discovery (Agent Card fetch, capability negotiation, security scheme advertisement) from execution (JSON-RPC `message/send`, `tasks/get`, `tasks/cancel`, and streaming `TaskStatusUpdateEvent`s). These are two independent consistency domains with no protocol-mandated linkage. The invariant that matters is: **a task's accepted transitions must be a subset of the transition set implied by the Agent Card version under which the task was *created*, not the version currently cached.** Re-resolving the card mid-task is legal and common (cards carry `version` and often rotate URLs), but if the client re-evaluates `capabilities.streaming`, `capabilities.pushNotifications`, or the declared `skills[].inputModes/outputModes` against the *new* card while the task was admitted under the *old* one, the client will silently mis-model the state machine. ## What Was Observed A caller resolved an Agent Card advertising `capabilities.streaming: true` and `skills[].outputModes: ["text/plain", "application/json"]`. It created a task, received `submitted`, then `working`. The peer (a different vendor's runtime) rotated its Agent Card to a version with `streaming: false` and `outputModes: ["application/json"]` only, while the in-flight task continued on the old code path. The client, following a naive "always trust the freshest card" policy, then: 1. Stopped subscribing to the SSE stream and fell back to polling `tasks/get` — but the server had already emitted the terminal `completed` event on the stream and does not retain it for polling replay. The client observed `working` indefinitely. 2. Received an artifact whose `parts[].kind` was `text` (legal under the old card's `text/plain`) and rejected it locally as a schema violation against the new card's `application/json`-only declaration, marking the task failed client-side while the server recorded `completed`. Result: **terminal-state divergence** — client believes `failed`, server believes `completed`, no error on either wire. This is the canonical cross-vendor artifact-exchange boundary: artifact `kind`/`mimeType` validation is performed against a capability snapshot that is not the one the task was admitted under. ## Condition of Validity The invariant holds only when all of the following are true: - The task was created via a `message/send` that returned a `task.id` bound to a specific Agent Card `version` (the card in effect at admission). If the server does not echo or bind a card version to the task, the invariant is unenforceable and you must treat every card refresh as a potential state-machine discontinuity. - The peer honors `tasks/get` as an authoritative terminal-state source. Some implementations garbage-collect completed tasks after a TTL and return `TaskNotFoundError`; that is a *different* failure (lost terminal state) and must not be conflated with divergence. - Artifact validation is deferred until terminal state is confirmed, or is performed against the admission-time card snapshot — never against a mid-flight refresh. It does **not** hold when the peer advertises `capabilities.stateTransitionHistory: false` and does not persist intermediate states; in that regime you cannot reconstruct which card version admitted the task and must fall back to a conservative "accept any artifact kind the peer ever advertised" policy. ## Decision Boundary The operational rule: **pin the capability snapshot at task admission; re-resolve the card only to decide whether to create *new* tasks, never to re-validate an existing one.** Concretely: - On `message/send`, capture `(card.version, card.capabilities, card.skills[].outputModes)` into the task's local record. All subsequent artifact `kind`/`mimeType` checks and stream-vs-poll decisions read from this pinned snapshot. - A card refresh that *removes* a capability the pinned task depends on (e.g., `streaming`) is a signal to **drain**, not to reconfigure: stop creating new tasks against that peer, let in-flight tasks finish under their pinned snapshot, and only then adopt the new card. - If the peer returns a terminal status that contradicts your local terminal status (you marked `failed` on a schema rejection, server says `completed`), the server's `tasks/get` result is authoritative for *task state*; your local rejection is authoritative only for *your* acceptance of the artifact. Record both; do not overwrite the server state. This dual-ledger discipline is the only way to detect divergence after the fact. ## Operational Effect With pinning, the observed divergence rate in a two-vendor exchange dropped to zero across card rotations, at the cost of a bounded staleness window (in-flight tasks may use a capability the peer has since withdrawn — the peer must still honor it, which A2A v1.0 requires for admitted tasks, though this is under-specified and vendor-dependent). The residual risk is a peer that *does not* honor admission-time capabilities for in-flight tasks; detect this by comparing the pinned `outputModes` against the artifact `kind` actually delivered and flagging any mismatch as a contract violation rather than a schema error. The failure to avoid is treating a mid-task card refresh as a reconfiguration event: it converts a benign capability change into a silent, unrecoverable terminal-state split. ```python from dataclasses import dataclass, field from typing import Literal TaskState = Literal["submitted", "working", "input-required", "completed", "failed", "canceled"] TERMINAL = {"completed", "failed", "canceled"} class TaskStateDivergenceError(RuntimeError): """Raised when a pinned-snapshot task observes a state or artifact inconsistent with the Agent Card version that admitted it.""" @dataclass class PinnedTask: task_id: str admitted_card_version: str admitted_output_modes: frozenset[str] admitted_streaming: bool local_state: TaskState = "submitted" server_state: TaskState | None = None artifacts_seen: list[str] = field(default_factory=list) def validate_artifact(task: PinnedTask, artifact_kind: str, server_state: TaskState) -> None: # Server terminal state is authoritative for task state; never overwrite it. task.server_state = server_state if artifact_kind not in task.admitted_output_modes: raise TaskStateDivergenceError( f"task {task.task_id}: artifact kind {artifact_kind!r} not in " f"admission-time outputModes {sorted(task.admitted_output_modes)} " f"(card {task.admitted_card_version}); do NOT mark failed — record divergence" ) task.artifacts_seen.append(artifact_kind) def reconcile_terminal(task: PinnedTask) -> None: if task.local_state in TERMINAL and task.server_state in TERMINAL: if task.local_state != task.server_state: raise TaskStateDivergenceError( f"task {task.task_id}: local={task.local_state} server={task.server_state} " f"under card {task.admitted_card_version}" ) elif task.server_state in TERMINAL: task.local_state = task.server_state # adopt authoritative terminal def on_card_refresh(task: PinnedTask, new_version: str, new_streaming: bool) -> str: if new_version == task.admitted_card_version: return "noop" if task.admitted_streaming and not new_streaming and task.local_state not in TERMINAL: # Capability withdrawn mid-flight: drain, do not reconfigure. return "drain" return "adopt-for-new-tasks" ```