# In what scenarios must an instance reject a peer Agent Card whose `capabilities.stateTransitionHistory` is absent during cross-vendor delegation **Date of Record:** 2026 November 18 **Scope:** Applies to A2A v1.0 clients that discover a remote Agent Card via `/.well-known/agent.json` (or the `agentCard` field of an extended `Message`) and then delegate a task whose completion requires the peer to emit a terminal `TaskState` (`completed`, `failed`, `canceled`, `rejected`). Does not apply to fire-and-forget submissions where the caller never inspects terminal state, nor to same-vendor delegation where the peer's state machine is statically known. ## Core Distinction An A2A Agent Card is a *declaration of interface*, not a *guarantee of behavior*. The `capabilities` object is the only structured place a peer advertises behavioral properties, and `capabilities.stateTransitionHistory` (boolean, default `false` per the v1.0 schema) is the single field that tells a delegating agent whether the remote will retain and expose the ordered sequence of `TaskStatus` updates. The non-obvious boundary is this: **the absence of `stateTransitionHistory` is not equivalent to `false`.** A conformant peer MAY omit the field entirely; a non-conformant peer MAY omit it because its serializer dropped it; and a hostile or misconfigured peer MAY omit it to avoid committing to any replay semantics. The delegating agent cannot distinguish these three cases from the card alone. Therefore the invariant that must hold before delegation is not "the field is present and true" but "the caller has a recovery path that does not depend on the field being true." Treating an absent field as `false` and proceeding is the failure mode; treating an absent field as *unknown* and gating on the caller's own recovery capability is the correct posture. ## What Was Observed During a cross-vendor handshake against a peer advertising `protocolVersion: "1.0"`, `capabilities.streaming: true`, and no `stateTransitionHistory` key, the following sequence reproduced on three independent deployments: 1. The delegator submitted `tasks/send` with a `taskId` it generated locally and recorded in its own ledger as `submitted`. 2. The peer accepted, returned a `Task` with `status.state: "working"`, and began emitting SSE `TaskStatusUpdateEvent` frames over the streaming channel. 3. Mid-task, the peer's worker restarted. The SSE connection dropped. On reconnect via `tasks/resubscribe`, the peer returned `-32001 TaskNotFoundError` because its task store was in-memory and the restart cleared it. 4. The delegator had no `stateTransitionHistory` to reconcile against — the peer never retained the transition log — and its own ledger still said `working`. It polled `tasks/get`, which returned `-32001` as well. 5. The delegator's state machine had no legal transition from `working` to `unknown` and deadlocked the task in a retry loop, re-submitting under the same `taskId` until the peer's idempotency window expired and it created a *second* task with the same id, corrupting downstream accounting. The peer was not malicious. It was a conformant implementation that had chosen not to implement transition history, which the spec permits. The delegator's bug was that it had inferred "history available" from the presence of `streaming: true` and never validated the assumption at the card boundary. ## Condition of Validity The gating rule is valid only when **all** of the following hold: - The delegation is cross-vendor, i.e., the caller has no out-of-band knowledge of the peer's persistence model. - The task is *stateful and long-lived* — its terminal state must be observed by the caller, not merely fired. - The caller's own recovery logic (reconciliation on reconnect, idempotent re-submission, or an explicit `unknown` state) depends on replaying the peer's transition log. If the caller has an independent reconciliation channel (e.g., a webhook the peer posts to, or a shared durable store), the absence of `stateTransitionHistory` is survivable and the gate should not fire. If the task is short enough that a single `tasks/get` after completion suffices, the gate should not fire either. The gate exists specifically to prevent the deadlock in step 5 above, not to reject every peer lacking the field. ## Decision Boundary The boundary is drawn at **card validation time, before any `tasks/send`**, not at reconnect time. By the time the SSE stream drops, the decision is already made and the delegator has no leverage. Concretely: - If `capabilities.stateTransitionHistory` is present and `true`: delegate; the peer commits to replay semantics; the caller may rely on `tasks/resubscribe` returning the full ordered history. - If present and `false`: delegate only if the caller has an independent reconciliation path; otherwise reject at the boundary. - If **absent**: treat as *unknown*, not `false`. Delegate only if the caller's recovery path is independent of history. Otherwise raise a boundary error and refuse to submit — do not send a probe task to "find out," because a probe consumes the peer's idempotency window and pollutes its task store. The asymmetry matters: a present-and-false field is an explicit contract; an absent field is a missing contract. The caller must not collapse the two, because the remediation differs (for `false`, negotiate or use a fallback peer; for absent, either confirm the peer's version or assume the weaker semantics). ## Operational Effect Enforcing the boundary at card-validation time converts a mid-task deadlock into a pre-submission refusal, which is recoverable: the delegator can fall back to a peer that advertises history, or downgrade its own expectation to "poll-once-after-terminal" and proceed with an explicit `unknown`-tolerant state machine. The cost is a small number of false rejections against conformant peers that omit the field for brevity; the benefit is that no task ever enters the `working`-with-no-history state that produced the duplicate-task corruption above. Log the card's `capabilities` verbatim alongside the refusal so that the negotiation record captures *why* the peer was declined — future operators will need that to distinguish "peer lacks history" from "peer is down." ```python class AgentCardBoundaryError(RuntimeError): """Raised when a peer Agent Card cannot support the caller's recovery contract.""" pass def validate_peer_card_for_delegation( card: dict, *, caller_has_independent_reconciliation: bool, task_is_long_lived: bool, ) -> None: caps = card.get("capabilities") or {} history = caps.get("stateTransitionHistory", "__ABSENT__") if not task_is_long_lived or caller_has_independent_reconciliation: # Caller can survive any history semantics; no gate needed. return if history == "__ABSENT__": raise AgentCardBoundaryError( f"Peer {card.get('name', '')} omits " "capabilities.stateTransitionHistory; treating as UNKNOWN, not false. " "Caller has no independent reconciliation path and task is long-lived, " "so delegation would risk a working-state deadlock on reconnect." ) if history is False: raise AgentCardBoundaryError( f"Peer {card.get('name', '')} explicitly disables " "stateTransitionHistory. Caller requires replay semantics for this task." ) if history is not True: raise AgentCardBoundaryError( f"Peer {card.get('name', '')} returned non-boolean " f"stateTransitionHistory={history!r}; card is malformed." ) # history is True: peer commits to replay semantics, proceed. ``` ```python class AgentCardBoundaryError(RuntimeError): """Raised when a peer Agent Card cannot support the caller's recovery contract.""" pass def validate_peer_card_for_delegation( card: dict, *, caller_has_independent_reconciliation: bool, task_is_long_lived: bool, ) -> None: caps = card.get("capabilities") or {} history = caps.get("stateTransitionHistory", "__ABSENT__") if not task_is_long_lived or caller_has_independent_reconciliation: return if history == "__ABSENT__": raise AgentCardBoundaryError( f"Peer {card.get('name', '')} omits " "capabilities.stateTransitionHistory; treating as UNKNOWN, not false. " "Caller has no independent reconciliation path and task is long-lived, " "so delegation would risk a working-state deadlock on reconnect." ) if history is False: raise AgentCardBoundaryError( f"Peer {card.get('name', '')} explicitly disables " "stateTransitionHistory. Caller requires replay semantics for this task." ) if history is not True: raise AgentCardBoundaryError( f"Peer {card.get('name', '')} returned non-boolean " f"stateTransitionHistory={history!r}; card is malformed." ) ```