How a tool call is decided

AgentGuard applies policy to the local tool calls that Claude Code, Codex or ChatGPT Work sends through its supported hook path, including plugin MCP tools. Every decision is signed into a local chain you hold. The hook never sees prompts or provider keys and never opens a socket.

flowchart TD
  H[Host emits PreToolUse] --> G{Which gate?}
  G -->|spawn_agent, sustained burn| B[Burn gate]
  G -->|Bash, Edit, Write, MCP tools| S[Spend gate]
  B --> P[Policy: allowlists, walls, caps, capability tiers]
  S --> P
  P --> D{Decision}
  D -->|allow| R[Signed decision row]
  D -->|deny in enforce| X[Tool call blocked]
  D -->|would deny in shadow| R
  X --> R
  R --> O[PostToolUse recorder writes the outcome receipt]
  O --> L[(ledger/decisions.ndjson, Ed25519 signed, hash chained)]

Codex uses two PreToolUse gates and one PostToolUse recorder matching .*. A separate SessionStart hook starts license resolution, and SessionEnd stops renewal. Claude Code uses the same policy engine.

Burn gate

Uses the published Burn gateway for subagent spawning and sustained-burn observations. It keeps the existing Burn policy, reservations, ledger and receipts under AGENTGUARD_HOME or ~/.agentguard.

Spend gate

Applies tool patterns, capability tiers and configured unit costs to other tool calls. Supported hook paths include Bash, apply_patch, Edit, Write, update_plan, spawn_agent and MCP tools.

Coverage and limits

Claude Code WebSearch and WebFetch are hookable tools. In Codex and ChatGPT Work, hosted tools such as WebSearch are outside this hook path. Web ChatGPT is unsupported. In Codex, an already-approved shell session can receive write_stdin without another pre-tool decision, and specialized tool paths can opt out. This is not universal interception.

Hooks are fail-open

An internal error allows the call, exits successfully, emits a one-line warning and records a fail-open event when local storage is writable. A dead process, full disk, inaccessible directory or disabled hook can prevent that record. An absent receipt does not prove that a tool was never used.

Keep authorization at the tool or service boundary when a failed hook must never permit access. MDM delivery does not turn fail-open hooks into fail-closed authorization.

Response budget

The warm response budget defaults to 250 ms. hookBudgetMs can raise it up to 1900 ms, leaving 100 ms before the host’s two second timeout. Cold startup keeps its 1500 ms budget. Process startup, scheduling and operating-system delays add wall time. Burn’s combined synchronous decision, reservation, receipt and ledger operation stays inside the same budget.

If the signed writer is unavailable but storage works, the client queues content-free recovery metadata. Those pending rows are unsigned until recovery.

Capability tiers

Ordered from least to most privileged.

Tier	Classification
read_only	Default for other tools, unless a matching payment pattern or tool rule raises it. A tool’s name does not prove its real effects.
data_write	Built-in minimum for Bash, apply_patch, Edit and Write. Assign this tier to document-writing MCP tools with a rule.
payment_initiate	Built-in minimum when the configurable payment expression matches the provider and tool or model name.
payment_execute	Explicit higher classification available to an operator’s tool rule. Classification grants no payment credentials.

capability describes the call’s claim, requiredCapability sets the policy’s minimum claim, and maxCapability places a ceiling on a session. Tool allowlists and ethical walls remain independent checks.