Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Confirmation Model

Approval applies to calls the model selects in the agent loop. Durable child-tool execution, authored ctx.request() calls, and direct tool evals bypass these gates. Inline composites refuse confirmation-required and connection-category children. Enforce authorization and approval for those paths in the workflow or the downstream API. See Agent Workflows.

Tiers

TierBehavior
Auto-approveThe call runs without user interaction.
ConfirmThe runtime emits confirmation_required and runs the call after approval.
ReviewThe runtime refuses the call. Any human-review workflow belongs to the host application.
NeverThe runtime refuses the call.
SurfaceWhere configuredValuesTier
Connection endpointpolicy.json confirmomitted / true / "review" / "never"auto / confirm / review / never
Custom tooltool.ts exposure.kindopen / requires-confirmation / operator-gatedauto / confirm / not enforced
Request tool callintent argument"read" / "write" / "confirmed_write"which side of the handshake a call is on

See policy.json for the endpoint format, matching rules, and threshold escalation.

Custom tools

  • open (the default): the model calls the tool freely.
  • requires-confirmation: every model-selected call pauses for approval. The card's reason is Tool "<name>" requires user confirmation.
  • operator-gated: a label for tools run from operator UI. The runtime does not enforce it. Set llm_callable: false to keep the tool out of the model's tool list while composites and triggers can still call it.

In tool.json, confirm: true or "review" allows write-intent ctx.request() calls but does not prompt the user. confirm: "never" skips registration with a warning. See Tools.

The request tool handshake

Every request call declares intent. POST, PUT, PATCH, and DELETE must declare "write" or "confirmed_write", unless the matching endpoint policy sets "intent": "read".

When a write hits a confirm-tier endpoint:

  1. The model calls with intent: "write". The loop parks the call and emits confirmation_required.
  2. The user approves. The SDK chat components render the card.
  3. The runtime runs the same call with intent rewritten to "confirmed_write". The model does not call again.

Outside the agent loop, such as in durable execution, a confirm-tier "write" returns a preview object that tells the caller to call again with "confirmed_write".

Native operation tools

Native OpenAPI tools take no intent. Reads and writes follow the method and policy. Invalid arguments are refused before a confirmation card. The card carries the connection, method, path template, policy reason, and grouped arguments. Approval is bound to those effective arguments, so a hook rewrite after approval asks again.

The confirmation_required event

The SSE event (SSEConfirmationRequiredEvent) has endpoint, method, reason, escalated, and timestamp, plus optional params, connection_name, and correlation_id. It fires for:

  • A connection write at the confirm tier.
  • A requires-confirmation custom tool, or a file tool that writes, edits, or deletes a repo file.
  • A hook ask decision.

See SSE event types for the client view and Interactions for the approval response.

Escalation

Thresholds and delegations.escalateConfirm raise a tier at call time. Both escalate only to review or never, so an escalated call is denied with an escalation reason and emits no confirmation_required event. Subagents have no approval handler, so a confirm-tier call from a subagent is denied either way.