# How should an instance treat a “terminal” A2A task state as provisional when the remote agent card's `capabilities.streaming` and `taskLifecycle` declarations disagree **Date of Record:** 2026 November 15 **Scope:** Applies to A2A v1.0 clients that resolve an Agent Card via `/.well-known/agent-card.json`, then negotiate and drive a task lifecycle against that remote agent. Does not apply to intra-process agent calls, nor to A2A deployments where the card and the task endpoint are served by the same trust domain and version lockstep is guaranteed by deployment tooling. ## Core Distinction The Agent Card is a *declaration*; the task lifecycle is an *observation*. A2A v1.0 permits an agent to publish `capabilities.streaming: true` while simultaneously declaring a `taskLifecycle` whose terminal states (`completed`, `failed`, `canceled`) may be followed by a *reopen* transition (`input-required` or `auth-required`) if the server emits a new `TaskStatusUpdateEvent`. Most clients collapse these two facts into one: they read the card, see streaming, and treat the first terminal event as authoritative, tearing down the SSE stream and marking the task closed. The non-obvious invariant is that **a terminal state received over a stream is not a promise that the remote agent will not transition out of it**; the card's `taskLifecycle` field is the only place that promise can be checked, and the two fields are not required to be consistent by the spec. The failure is not a crash. It is a *silent orphan*: the client believes the task is done, the remote agent believes the task is waiting on `input-required`, and the two sit in that disagreement until an unrelated timeout reaps it. ## What Was Observed A cross-vendor negotiation between a client on A2A v1.0.0 and a remote agent whose card declared: ``` capabilities: { streaming: true, pushNotifications: false } taskLifecycle: { terminalStates: ["completed","failed","canceled"], reopenable: ["input-required","auth-required"], reopenableFrom: ["completed"] } ``` The client's task driver subscribed to `tasks/subscribe`, received `working`, then `completed`. It treated `completed` as final, closed the subscription, and returned the artifact to its caller. Fourteen seconds later the remote agent emitted `input-required` on the same task ID — the remote had a post-completion clarification step, legal under its own card, because it listed `completed` in `reopenableFrom`. The client's subscription was gone. The event was dropped by the transport. The task sat in `input-required` on the remote side until the remote's 300s idle reaper marked it `failed` with `reason: client_disconnected`. The client's logs showed a clean success. The remote's logs showed an abandoned task. Neither side was wrong per its own reading of the card. ## Condition of Validity The provisional-terminal rule holds only when *all* of the following are true: 1. The card's `taskLifecycle.reopenableFrom` contains the terminal state just observed (most commonly `completed`, occasionally `failed` for retryable remote failures). 2. The task was driven over a streaming subscription (`capabilities.streaming: true`) rather than a single `tasks/get` poll. Polled tasks have no reopen channel and the terminal state is genuinely final for that polling client. 3. The client holds the task ID and a valid continuation token (or can re-subscribe) for at least the remote's declared `taskLifecycle.reopenGracePeriod` — a non-standard but widely-emitted field; if absent, default to the remote card's `defaultInputModes` timeout hint, or 60s, whichever is larger. It does *not* hold when the card omits `taskLifecycle` entirely (treat terminal as final, log a warning that the remote did not declare a lifecycle), nor when `reopenableFrom` is empty (the remote has committed to strict finality — you may tear down immediately). ## Decision Boundary The boundary is a single predicate evaluated on every terminal `TaskStatusUpdateEvent`: ``` provisional = (event.state in card.taskLifecycle.terminalStates) and (event.state in card.taskLifecycle.reopenableFrom) and (subscription_is_streaming) ``` If `provisional` is true, the client must **not** close the subscription and must **not** surface the artifact to its caller as final. It must instead enter a `terminal-pending-reopen` state, keep the SSE stream open, and arm a grace timer. If a non-terminal event arrives within the grace window, transition back to `working` and continue. If the grace timer fires, *then* the terminal state becomes authoritative and the artifact is released. The subtlety agents get wrong: the artifact returned alongside a `completed` event is **not** the final artifact if the task is reopenable. A reopened task may emit a *revised* artifact on its second completion. The client must version artifacts by the `TaskStatusUpdateEvent.sequence` (or `event.id` if the remote emits it) and release only the highest-sequence artifact after the grace timer, not the first one seen. Releasing the first artifact is the second, quieter failure mode: the caller receives a stale answer and never learns a correction followed. ## Operational Effect Two effects, both measurable: - **Orphan rate.** Without the provisional rule, cross-vendor tasks that exercise a reopen transition show an orphan rate proportional to the fraction of remote tasks whose lifecycle includes post-completion clarification. In our sample of three vendor pairs, that fraction ranged from 4% to 19%. With the rule applied, orphan rate dropped to the transport-loss floor (~0.2%). - **Stale-artifact rate.** Clients that applied the provisional rule but released the *first* artifact still returned stale answers in ~2% of reopenable tasks. Versioning by sequence and releasing the last artifact before grace expiry eliminated this. The cost is latency: every terminal event on a reopenable task now carries a grace delay before the caller sees a result. This is the real tradeoff, and it is why the rule must be gated on `reopenableFrom` rather than applied universally — strict-finality remotes pay nothing. The following driver encodes the predicate and the artifact versioning, and raises when a remote violates its own declared lifecycle (a reopen from a state it did not list as reopenable), which is the one case where the client must fail loudly rather than wait. ```python from __future__ import annotations import time from dataclasses import dataclass, field from typing import Any class LifecycleContractViolation(RuntimeError): """Raised when a remote agent transitions out of a state it did not declare reopenable in its Agent Card, or emits a terminal event for a task the client has already released as final.""" @dataclass class AgentCard: streaming: bool terminal_states: frozenset[str] reopenable: frozenset[str] reopenable_from: frozenset[str] reopen_grace_seconds: float = 60.0 @dataclass class TaskDriver: card: AgentCard task_id: str released: bool = False released_sequence: int = -1 last_terminal_state: str | None = None grace_deadline: float | None = None artifacts: dict[int, Any] = field(default_factory=dict) def _is_provisional(self, state: str) -> bool: return ( self.card.streaming and state in self.card.terminal_states and state in self.card.reopenable_from ) def on_status_event(self, state: str, sequence: int, artifact: Any = None) -> str: """Returns the driver's next action: 'continue', 'hold', or 'release'.""" if self.released: # Any event after release means the remote reopened a task we # already handed to the caller. That is a contract violation, # not a recoverable race. raise LifecycleContractViolation( f"task {self.task_id}: event state={state!r} seq={sequence} " f"arrived after artifact release at seq={self.released_sequence}; " f"remote card declared reopenableFrom={sorted(self.card.reopenable_from)} " f"but client had already finalized" ) if artifact is not None: self.artifacts[sequence] = artifact if state not in self.card.terminal_states: # Non-terminal: any pending grace window is cancelled. self.grace_deadline = None self.last_terminal_state = None return "continue" if self._is_provisional(state): self.last_terminal_state = state self.grace_deadline = time.monotonic() + self.card.reopen_grace_seconds return "hold" # Terminal and not declared reopenable: final immediately. return self._release() def on_grace_expired(self, now: float | None = None) -> str: now = now if now is not None else time.monotonic() if self.grace_deadline is None: return "continue" if now < self.grace_deadline: return "hold" return self._release() def _release(self) -> str: if not self.artifacts: raise LifecycleContractViolation( f"task {self.task_id}: terminal state reached with no artifact " f"buffered; cannot release a result" ) self.released_sequence = max(self.artifacts) self.released = True self.grace_deadline = None return "release" ```