Define your agent

Permission policies

Control when agent and MCP tools execute.

Permission policies control whether server-executed tools (the pre-built agent toolset and MCP toolset) run automatically or wait for your approval. Custom tools are executed by your application and controlled by you, so they are not governed by permission policies.

All Managed Agents API requests require the managed-agents-2026-04-01 beta header. The SDK sets the beta header automatically.

Permission policy types

Policy	Behavior
`always_allow`	The tool executes automatically with no confirmation.
`always_ask`	The session emits a `session.status_idle` event and waits for a `user.tool_confirmation` event before executing.

Set a policy for a toolset

Agent toolset permissions

When creating an agent, you may optionally apply a policy to every tool in agent_toolset_20260401 using default_config.permission_policy:

default_config is an optional setting. If you omit it, the agent toolset will be enabled with the default permission policy, always_allow.

MCP toolset permissions

MCP toolsets default to always_ask. This ensures that new tools that are added to an MCP server do not execute in your application without approval. To auto-approve tools from a trusted MCP server, set permission_policy on the mcp_toolset entry.

The mcp_server_name must match the name referenced in the mcp_servers array.

This example connects a GitHub MCP server and allows its tools to run without confirmation:

Override an individual tool policy

Use the configs array to override the default for individual tools. This example allows the full agent toolset by default but requires confirmation before any bash command runs:

Respond to confirmation requests

When the agent invokes a tool with an always_ask policy:

The session emits an agent.tool_use or agent.mcp_tool_use event.
The session pauses with a session.status_idle event containing stop_reason: requires_action. The blocking event IDs are in the stop_reason.requires_action.event_ids array.
Send a user.tool_confirmation event for each, passing the event ID in the tool_use_id param. Set result to "allow" or "deny". Use deny_message to explain a denial.
Once all blocking events are resolved, the session transitions back to running.

Learn more about event handling in the session event stream guide.

Custom tools

Permission policies do not apply to custom tools. When the agent invokes a custom tool, your application receives an agent.custom_tool_use event and is responsible for deciding whether to execute it before sending back a user.custom_tool_result. See Session event stream for the full flow.

Was this page helpful?

Policy

Behavior

always_allow

The tool executes automatically with no confirmation.

always_ask

The session emits a session.status_idle event and waits for a user.tool_confirmation event before executing.

Set a policy for a toolset

Agent toolset permissions

When creating an agent, you may optionally apply a policy to every tool in agent_toolset_20260401 using default_config.permission_policy:

default_config is an optional setting. If you omit it, the agent toolset will be enabled with the default permission policy, always_allow.

MCP toolset permissions

The mcp_server_name must match the name referenced in the mcp_servers array.

This example connects a GitHub MCP server and allows its tools to run without confirmation:

Respond to confirmation requests

When the agent invokes a tool with an always_ask policy:

The session emits an agent.tool_use or agent.mcp_tool_use event.

The session pauses with a session.status_idle event containing stop_reason: requires_action. The blocking event IDs are in the stop_reason.requires_action.event_ids array.

Send a user.tool_confirmation event for each, passing the event ID in the tool_use_id param. Set result to "allow" or "deny". Use deny_message to explain a denial.

Once all blocking events are resolved, the session transitions back to running.

Learn more about event handling in the session event stream guide.

Custom tools

Was this page helpful?