Two layers, one decision
A policy is resolved from two layers, most specific wins:- Organization default — a baseline every agent in the organization inherits.
- Agent override — per-agent, and per-tool within an agent.
Per-tool permission policy
Each tool resolves to one of three permissions:
Tools are configured with a single toolset object: a
default_config that applies to every tool, and per-tool configs that enable a tool and override its permission. There is no separate flat tools[] array or top-level default field.
TypeScript
CLI
allow is convenient but not automatically the right default. For irreversible or externally-visible tools (payouts, deletes, sending mail) set ask — or deny if the agent should never have the capability — rather than leaning on the permissive baseline.The ask-by-default tools (publishing, paying, filing, changing the company’s settings, a paid data run, training a character) resolve to
ask when configs does not name them — even under a deny default. A per-tool entry is the only thing that denies one.Responding to ask
When a tool is set to ask, the runtime streams a tool.confirm event and holds the turn. The session goes idle with stop_reason: "awaiting_approval". You resolve it by sending a decision back into the session — the same mechanism as any other input:
CLI
ask waits until someone answers it. A held tool consumes no budget while it waits, and — because the loop is durable — an agent can sit on a confirmation for hours at storage cost only. See Events & streaming for the event shapes.
Connection & primitive scoping
Beyond individual tools, a policy scopes which external systems and primitives an agent may reach. This governs the identity surface — connections an agent acts through run under the same allow/ask/deny filter asbash.
object
Which built-in primitives are enabled for the agent — e.g.
computer, browser, files, connections, and (coming soon, as agent tools) email, phone.string
default:"allowlist"
How third-party connections are gated:
•
•
•
•
open — any connection type is allowed.
•
allowlist — only the listed connection types are allowed. Recommended for anything an agent runs unattended.
•
blocklist — every connection type except the listed ones is allowed.
open is permissive by design; prefer allowlist in production so a new connector type is not reachable until you add it.string[]
The connection types the
allowlist / blocklist applies to.forbidden error (a permission denial) before any external request is made.
Why the boundary matters
Because enforcement lives at the tool-call boundary rather than inside a prompt, a policy holds regardless of what the model decides to attempt. Combined with the budget gate — which prices every call before it runs — an agent left running unattended can neither exceed its spend nor touch a system it was not granted.Next: the computer
The sandbox, filesystem, shell, and browser in depth.