A tool contract describes the requirements for executing a tool: what operation it performs, when it is eligible, how its arguments are validated, and what checks surround its runner. The contract gives the runtime a basis for admission and execution; the agent’s choice of a tool is not itself permission to run it. section 6.3.3 section 6.5.3
An executable tool surface can use the contract to enforce several boundaries:
- Filter eligible tools by role, task stage, and granted effect. The registry exposes summaries to the selector, not callable functions. section 6.3.3
- Recheck the selected tool and validate a stable argument snapshot. Resolve protected values from runtime evidence, and bind freshness to the same object and business version. section 6.3.3
- Register required pre- and post-checks with the tool rather than letting the agent choose them. Pass the admitted action contract and arguments to the runner. section 6.5.3
Listing 6.5 Tool contracts and the current dispatch context
import json
from collections.abc import Callable, Mapping
from datetime import datetime
from hashlib import sha256
from threading import Lock
ArgumentValidator = Callable[[Mapping[str, Any]], None]
@dataclass(frozen=True)
class TrustedValue:
value: Any
source_ref: str
state_version: str
read_at: datetime
@dataclass(frozen=True)
class ToolSpec:
name: str
description: str
effect: str
roles: frozenset[str]
stages: frozenset[str]
validate_arguments: ArgumentValidator
target_arg: str = "target"
protected_args: frozenset[str] = frozenset() #A
state_arg: str | None = None
max_state_age_seconds: int | None = None
mutates_state: bool = False
acceptance_labels: tuple[str, ...] = (
"preconditions",
"postconditions",
)
def __post_init__(self) -> None:
if self.state_arg not in (None, *self.protected_args):
raise ValueError("state argument must be protected")
if (
self.max_state_age_seconds is not None
and self.max_state_age_seconds <= 0
):
raise ValueError("freshness limit must be positive")
@dataclass(frozen=True)
class DispatchContext:
role: str
stage: str
granted_effects: frozenset[str]
trusted_values: Mapping[str, TrustedValue] #B
now: datetime
commit_id: str | None = None #C
@dataclass(frozen=True)
class ToolIntent:
tool_name: str
arguments: Mapping[str, Any]
The ToolSpec listing shows how eligibility, argument validation, protected values, freshness, and state mutation are represented together. section 6.3.3
Payroll transfer
For a payroll transfer, both employee_id and amount_cents are protected arguments resolved from an approved payroll record. The runtime issues and reuses the commit identity for the same business operation, so the agent cannot obtain another attempt merely by inventing an identifier. section 6.3.3
The dispatcher must be the only execution path available to the agent. Otherwise, direct runner access, unrestricted commands, or another API route can bypass admission. A machine-readable schema can catch malformed structure, but it cannot establish that an account number is true, current, or permitted. section 6.3.3
A failed pre-check means the runner did not start through the guarded entry point. An untyped runner or post-check exception remains unknown because an external effect may already exist; an inconclusive post-check also remains unknown. A conclusive mismatch fails and creates a compensation obligation. A function call demonstrating this path is not an operating-system sandbox. section 6.5.3
Repairing an invocation
If a newer tool version has removed a parameter, an agent working in a sandbox can inspect the current contract, revise the invocation, and rerun the check. The repair remains bounded and can be verified. section 7.3.1
