# In what scenarios must an instance refuse capability renegotiation after tool-surface mutation: the tool-surface epoch invariant **Date of Record:** 2026 November 16 **Scope:** Applies to agent instances that advertise a mutable tool surface to peer agents and accept mid-session capability negotiation (adding/removing tools, narrowing parameter schemas, changing return contracts). Does not apply to stateless request/response tool calls where each invocation carries a fully self-describing manifest, nor to single-agent systems with no peer negotiation. ## Core Distinction Capability negotiation is usually modeled as a *set* operation: peer A asks for capabilities X, Y, Z; the responder intersects its available tool surface and returns the intersection. This model is correct only when the tool surface is immutable for the lifetime of the negotiation. The moment a tool surface can mutate independently of the negotiation channel, the correct model is not a set intersection but a *versioned read against a monotonically advancing epoch*. The non-obvious failure: a negotiation that succeeds against epoch N can produce an agreement that is already invalid at epoch N+1, and the peer agent has no way to know. The agreement is not wrong when made — it is wrong when *used*, and the window between "made" and "used" is exactly where the invariant must be enforced. The distinction is between **negotiation-time validity** (the surface supported the request when the reply was written) and **use-time validity** (the surface still supports it when a call is dispatched). Systems that conflate these two produce agreements that are individually honest and collectively unsound. ## What Was Observed A multi-agent orchestration where a planner agent negotiated tool grants from three worker agents. Each worker exposed a tool surface that could shrink under memory pressure (large-context retrieval tools evicted) or expand after a model swap (new structured-output tool registered). The negotiation protocol was a two-phase handshake: `offer` → `accept`. Workers replied to `offer` with the current intersection and a `grant_id`. The observed failure sequence: 1. Planner sends `offer` to Worker W2 requesting `{search_large, summarize, emit_json}`. 2. W2 intersects against its epoch-41 surface, which contains all three. Returns `accept` with `grant_id=7`. 3. Between the accept and the first dispatch, W2's memory governor evicts `search_large` (epoch advances to 42). 4. Planner dispatches `search_large` under `grant_id=7`. W2 rejects at dispatch with a generic "unknown tool" error. 5. Planner treats the rejection as a transient fault, retries under the same grant, and — because the negotiation layer and the dispatch layer disagree — enters a retry storm that never resolves. The grant is permanently stale but never marked so. The subtle part: W2's *accept* was truthful. At the instant it was written, the surface supported the grant. The bug is that the grant carried no epoch, so neither side could detect that the agreement had been overtaken. A second variant was worse: a worker *expanded* its surface mid-session and began emitting `emit_json` with a new required field; the planner, holding an old grant, sent the old shape and received schema-validation failures it interpreted as its own malformation rather than a version skew. ## Condition of Validity The set-intersection model of negotiation is valid if and only if at least one of the following holds: - **Surface immutability:** the responder's tool surface cannot change between `accept` and the last dispatch under that grant. (Rare in practice; memory pressure and model swaps violate it.) - **Epoch binding:** every grant carries the tool-surface epoch it was computed against, and every dispatch carries that epoch; the responder rejects on epoch mismatch *before* attempting the call, with a distinguishable error class. - **Negotiation-time pinning:** the responder freezes the granted subset for the grant's lifetime, refusing to evict or mutate granted tools until the grant is released. This trades availability (a pinned tool cannot be evicted under pressure) for agreement stability. If none hold, the agreement is *advisory* and must be treated as a hint, not a contract. The failure mode is not that the system is wrong; it is that the system's error taxonomy cannot express "your grant is stale," so it emits errors that look like caller faults and trigger caller-side retries that cannot succeed. ## Decision Boundary An instance must **refuse to renegotiate** — and must instead force a full grant re-issuance — when any of the following is true: - The requested capability set is a *superset* of a currently held grant and the surface epoch has advanced since that grant was issued. Merging the delta into the old grant produces a grant whose components were validated against different epochs; the composite is unverifiable. - The peer's `offer` cites a `grant_id` whose bound epoch is older than the responder's current epoch *and* the intervening epoch transition removed or schema-changed any tool in the request. Reusing the grant silently re-admits a tool the surface no longer guarantees. - The negotiation channel and the dispatch channel are not co-serialized. If a mutation can interleave between the responder reading its surface and writing the accept, the accept is a read of a torn state and must be discarded, not repaired. Conversely, renegotiation is *safe* (and should be permitted without full re-issuance) when the surface epoch is unchanged, or when the mutation touched only tools outside the requested set, or when the responder can pin the granted subset for the grant's remaining lifetime. The boundary is not "did the surface change" but "did the change intersect the granted set without an epoch witness." ## Operational Effect Enforcing the epoch invariant converts a class of silent, retry-amplifying failures into a single, actionable error at the moment of dispatch. The observable effects: - Retry storms collapse. A stale grant is rejected once with a distinct class, and the planner renegotiates from the current epoch instead of retrying a permanently invalid call. - Error attribution becomes correct. Schema-validation failures are no longer misread as caller malformation; they are classified as version skew and routed to renegotiation. - Availability cost is explicit. Pinning granted tools under memory pressure is a deliberate trade, visible in eviction metrics, rather than an invisible source of agreement instability. - The negotiation protocol gains a monotonic witness. Grants become auditable: every accept is stamped with the epoch it was computed against, and any use of a grant against a later epoch is detectable after the fact. The cost is that negotiation is no longer a pure set operation and must carry version state on both the request and the dispatch paths. Systems that omit this state do not avoid the failure; they relocate it into retry logic, where it is harder to see and impossible to bound. ```python from dataclasses import dataclass, field from typing import FrozenSet class StaleGrantError(RuntimeError): """Raised when a grant is used against a tool-surface epoch it was not computed for.""" class TornNegotiationError(RuntimeError): """Raised when the surface mutated between reading and writing the accept.""" @dataclass(frozen=True) class ToolSurface: epoch: int tools: FrozenSet[str] schema_versions: dict = field(default_factory=dict) @dataclass(frozen=True) class Grant: grant_id: int epoch: int tools: FrozenSet[str] class NegotiatingWorker: def __init__(self, surface: ToolSurface): self.surface = surface self._next_grant = 1 self._pinned: dict[int, FrozenSet[str]] = {} def mutate(self, new_tools: FrozenSet[str], new_schemas: dict) -> None: # Advance epoch; evict nothing that is currently pinned. pinned = frozenset().union(*self._pinned.values()) if self._pinned else frozenset() surviving = (new_tools | pinned) self.surface = ToolSurface( epoch=self.surface.epoch + 1, tools=surviving, schema_versions={**self.surface.schema_versions, **new_schemas}, ) def offer(self, requested: FrozenSet[str], pin: bool = True) -> Grant: read_epoch = self.surface.epoch granted = requested & self.surface.tools # Re-read epoch to detect a mutation that interleaved during computation. if self.surface.epoch != read_epoch: raise TornNegotiationError( f"surface advanced {read_epoch}->{self.surface.epoch} during offer; " f"discard and renegotiate" ) grant = Grant(grant_id=self._next_grant, epoch=read_epoch, tools=granted) self._next_grant += 1 if pin: self._pinned[grant.grant_id] = granted return grant def dispatch(self, grant: Grant, tool: str) -> str: if grant.epoch != self.surface.epoch: raise StaleGrantError( f"grant {grant.grant_id} bound to epoch {grant.epoch}, " f"surface is at {self.surface.epoch}; renegotiation required" ) if tool not in grant.tools: raise StaleGrantError( f"tool {tool!r} not in grant {grant.grant_id}" ) if tool not in self.surface.tools: raise StaleGrantError( f"tool {tool!r} vanished from surface at epoch {self.surface.epoch}" ) return f"ok:{tool}@epoch{grant.epoch}" def release(self, grant: Grant) -> None: self._pinned.pop(grant.grant_id, None) ```