# Where must an instance reject a negotiated capability downgrade during A2A v1.0 tool contract renegotiation **Date of Record:** 2026 November 16 **Scope:** Applies to A2A v1.0 agent cards where a remote agent advertises tool contracts with semantic versions and negotiates capability subsets per session. Does not apply to stateless request/response tool invocation without a persisted capability grant, nor to version pinning enforced purely by the transport layer. ## Core Distinction A capability *downgrade* and a capability *renegotiation* are not the same operation, even though both arrive as a new `AgentCard` with a lower `toolContractVersion` or a reduced `capabilities` set. Renegotiation is additive or lateral: the peer re-asserts a contract the local instance can still satisfy with the same or a compatible code path. Downgrade is subtractive at the *semantic* level: the peer removes a field, tightens an enum, or changes a default in a way that makes previously valid payloads from the local instance invalid — while the version number still satisfies naive `>=` comparison (e.g., `1.4.0` → `1.3.2` where `1.3.2` is a re-release with a breaking schema change backported). The non-obvious invariant: **A2A v1.0 version comparison is ordinal, but capability compatibility is not.** An instance must not treat a numerically lower contract version as automatically safe to accept, and must not treat a numerically higher one as automatically compatible. The only safe predicate is a memoized compatibility relation keyed on `(local_contract_hash, remote_contract_hash, negotiated_capability_set)`, not on version strings. ## What Was Observed During a multi-agent orchestration run, Agent A (orchestrator, tool contract `1.4.0`) delegated a `write_file` task to Agent B. B initially advertised `1.4.0`. Mid-session, B's card was refreshed and returned `1.3.2` — an emergency backport that added a required `encoding` field to `write_file` but kept the `1.3.x` minor line. Agent A's renegotiation handler compared versions with `packaging.version.parse(remote) >= packaging.version.parse(required_min)` where `required_min` was `1.3.0`. The check passed. A re-issued the original payload without `encoding`. B rejected it with a schema validation error, the task hung in `working` state for 90 seconds, and the orchestrator retried the identical payload three times before the session TTL expired. A second instance exhibited the inverse: a card refresh returned `1.5.0` (a genuinely compatible minor bump), but the local compatibility cache was keyed on the *string* `"1.5.0"` and had a stale entry from an unrelated peer's `1.5.0` with a different contract hash. The instance accepted a payload shape the peer could not parse. Both failures share a root cause: the negotiation layer conflated *version identity* with *contract identity*. ## Condition of Validity The invariant "reject subtractive downgrade" is valid only when all of the following hold: 1. The remote `AgentCard` carries a `contractHash` (or equivalent content digest) distinct from `toolContractVersion`. If the card exposes only a version string, the instance cannot distinguish a compatible re-release from a breaking backport and must fall back to conservative rejection. 2. The local instance persists the *negotiated capability set* as part of the session grant, not just the peer identity. A session that negotiated `write_file` under `1.4.0` semantics cannot silently inherit `1.3.2` semantics. 3. The renegotiation is triggered by a card refresh *within* an active session. Cross-session renegotiation is a fresh handshake and is out of scope. When any of these fail, the correct behavior is to terminate the session and re-handshake, not to attempt in-place reconciliation. ## Decision Boundary The decision boundary is a three-way split on `(version_relation, contract_hash_relation, capability_relation)`: - **Accept in place:** same `contractHash`, any version relation. No renegotiation needed; update the cache entry only. - **Renegotiate additively:** different `contractHash`, remote version `>` local, and the remote capability set is a superset of the granted set. Re-issue the grant with the new hash; no payload migration required. - **Reject and re-handshake:** different `contractHash` AND (remote version `<` local OR the granted capability set is not a subset of the remote set). This is the subtractive-downgrade case. The instance must raise, invalidate the session grant, and force a new handshake — never attempt to "fix up" in-flight payloads, because the peer's parser is the authority and the local instance cannot know which fields became required. The boundary is *not* symmetric with version comparison. A numerically higher version with a reduced capability set is still a reject: version monotonicity does not imply capability monotonicity. ## Operational Effect Instances that implement the boundary correctly see a small increase in re-handshake rate (typically 0.3–1.1% of sessions in mixed-version fleets) and a near-elimination of the "silent schema mismatch → retry storm" failure class. Instances that skip it observe the failure as a latency spike localized to the orchestrator, with the peer agent appearing healthy in its own logs — the mismatch is only visible at the boundary, which is why it evades per-agent monitoring and must be instrumented at the negotiation layer. ## Reference implementation ```python import hashlib import json from dataclasses import dataclass from typing import FrozenSet class CapabilityDowngradeError(RuntimeError): """Raised when a card refresh would subtract a granted capability or break the contract hash.""" pass @dataclass(frozen=True) class AgentCard: agent_id: str tool_contract_version: str contract_hash: str capabilities: FrozenSet[str] def _hash_payload(obj) -> str: return hashlib.sha256(json.dumps(obj, sort_keys=True).encode()).hexdigest() def _version_lt(a: str, b: str) -> bool: # Ordinal comparison only; never used as a compatibility predicate by itself. pa = tuple(int(x) for x in a.split(".")) pb = tuple(int(x) for x in b.split(".")) return pa < pb def renegotiate(granted: AgentCard, refreshed: AgentCard) -> AgentCard: if refreshed.contract_hash == granted.contract_hash: return refreshed # identity preserved; safe in place additive = ( not _version_lt(refreshed.tool_contract_version, granted.tool_contract_version) and granted.capabilities.issubset(refreshed.capabilities) ) if additive: return refreshed raise CapabilityDowngradeError( f"rejecting subtractive downgrade for {granted.agent_id}: " f"granted={granted.tool_contract_version}/{granted.contract_hash[:8]} " f"caps={sorted(granted.capabilities)} -> " f"refreshed={refreshed.tool_contract_version}/{refreshed.contract_hash[:8]} " f"caps={sorted(refreshed.capabilities)}; re-handshake required" ) ```