A commit identity is a runtime-issued identifier that lets retries refer to the same state-changing business operation. The runtime reuses it for that operation rather than letting the model invent a new identifier for each attempt. This prevents a model-chosen identifier from turning a retry into an apparently new operation. section 6.3.3 section 6.1.2
The identity is part of an action contract, alongside the intended effect, target, state version, request digest, and acceptance labels. The digest binds the selected tool and effect to the admitted arguments, so the same identity cannot silently acquire a different meaning. Execution attempts remain separate: an attempt can fail, be rejected, or have an uncertain external outcome. section 6.1.2
Listing 6.7 Admission checks for one selected tool call
class AdmissionError(ValueError):
pass
@dataclass(frozen=True)
class AdmittedCall:
spec: ToolSpec
contract: ActionContract
arguments_json: str
provenance: tuple[tuple[str, str], ...]
state_read_at: datetime | None
def arguments(self) -> dict[str, Any]:
return json.loads(self.arguments_json)
class CommitStore:
def __init__(self) -> None:
self._digests: dict[str, str] = {}
self._lock = Lock()
def reserve(self, commit_id: str, digest: str) -> str:
with self._lock: #A
current = self._digests.get(commit_id)
if current is None:
self._digests[commit_id] = digest
return "new"
if current != digest: #B
raise AdmissionError("commit identity changed arguments")
return "repeat"
def release(self, commit_id: str, digest: str) -> None:
with self._lock:
if self._digests.get(commit_id) == digest:
del self._digests[commit_id]
def digest_for(self, commit_id: str) -> str | None:
with self._lock:
return self._digests.get(commit_id)
def canonical_arguments(
arguments: Mapping[str, Any],
) -> str:
try:
document = json.dumps(
dict(arguments),
allow_nan=False,
separators=(",", ":"),
sort_keys=True,
)
except (TypeError, ValueError) as error:
raise AdmissionError("arguments must be JSON values") from error
return document
def request_digest(spec: ToolSpec, arguments_json: str) -> str:
request = json.dumps(
{
"tool": spec.name,
"effect": spec.effect,
"arguments": json.loads(arguments_json),
},
separators=(",", ":"),
sort_keys=True,
)
return sha256(request.encode("utf-8")).hexdigest()
def admit(
registry: ToolRegistry,
intent: ToolIntent,
context: DispatchContext,
) -> AdmittedCall:
eligible = {item.name: item for item in registry.eligible(context)}
spec = eligible.get(intent.tool_name) #C
if spec is None:
raise AdmissionError("tool is not eligible in this context")
document = canonical_arguments(intent.arguments)
digest = request_digest(spec, document)
arguments = json.loads(document) #D
try:
spec.validate_arguments(arguments)
except (TypeError, ValueError) as error:
raise AdmissionError("tool arguments are invalid") from error
provenance: list[tuple[str, str]] = []
for name in spec.protected_args: #E
trusted = context.trusted_values.get(name)
if trusted is None or arguments.get(name) != trusted.value:
raise AdmissionError(f"{name} is not runtime-bound")
if not trusted.source_ref or not trusted.state_version:
raise AdmissionError(
f"trusted evidence is incomplete for {name}"
)
provenance.append((name, trusted.source_ref))
state = (
context.trusted_values.get(spec.state_arg)
if spec.state_arg is not None
else None
)
if spec.state_arg is not None and state is None:
raise AdmissionError("trusted state basis is missing")
if spec.max_state_age_seconds is not None: #F
if state is None:
raise AdmissionError("fresh state is required")
if state.read_at.utcoffset() is None:
raise AdmissionError("state timestamp needs a timezone")
if context.now.utcoffset() is None:
raise AdmissionError("runtime timestamp needs a timezone")
age = (context.now - state.read_at).total_seconds()
if age < 0 or age > spec.max_state_age_seconds:
raise AdmissionError("state snapshot is stale")
if spec.mutates_state and not context.commit_id:
raise AdmissionError("commit identity is required")
target = str(arguments.get(spec.target_arg, "unknown"))
contract = ActionContract(
effect=spec.effect,
target=target,
state_version=(state.state_version if state else "not-required"),
commit_id=context.commit_id or "read-only",
request_digest=digest,
acceptance_labels=spec.acceptance_labels,
)
return AdmittedCall(
spec=spec,
contract=contract,
arguments_json=document,
provenance=tuple(provenance),
state_read_at=(state.read_at if state else None),
)
The commit store reserves an identity against a digest, recognizes a matching repeat, and rejects a repeat with changed arguments. section 6.3.3
A payroll retry
A payroll transfer may use the right tool and valid arguments yet still create an unauthorized second payment. The runtime resolves the protected employee and amount from the approved payroll record and reuses the operation’s commit identity. A pre-check ties the contract to the reserved digest; a post-check accepts only a settled receipt matching the commit, employee, amount, and payroll version. section 6.3.3 section 6.1.2 section 6.5.4
If an external outcome is unknown, query by commit identity rather than replaying blindly. Commit checks work within one identity: detecting a second payment under a different identity also requires authorization and reconciliation across the business operation. In production, reserve commits in a durable store and verify effects against authoritative systems. section 6.5.4
Commit identity is one control in an execution boundary, not proof that an action was authorized or completed. Admission must remain on the only execution path available to the agent; otherwise, a direct runner or alternate API path can bypass the dispatcher. Acceptance depends on independent evidence of the effect. section 6.3.3 section 6.9
