permission-policies changedmanaged-agents/permission-policies
Nearest release: v2.1.232, published 7 hours before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+929added
Lines−0removed
From line
—
no hunk to open at
First seen
14 Aug 2026
this site's first read of the page
Recorded edits20to this page, all time
## Permission policy types ## Set a policy for a toolset ### Agent toolset permissions ### MCP toolset permissions ## Override an individual tool policy ## Respond to confirmation requests ## Custom tools ## Next steps
The whole hunk
929 lines, first recorded
/
lines
The first capture of this source. The page was already there, and this is what it said.
---
title: Permission policies
url: https://platform.claude.com/docs/en/managed-agents/permission-policies
description: 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.
<Note>
Managed Agents API requests require the `managed-agents-2026-04-01` beta header, except memory store endpoints, which use `agent-memory-2026-07-22` instead. The SDK sets the correct beta header automatically. See [Beta headers](https://platform.claude.com/docs/en/api/beta-headers#endpoint-specific-headers).
</Note>
## Permission policy types
| Policy | Behavior |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `always_allow` | The tool executes automatically with no confirmation. |
| `always_ask` | The session pauses and waits for your approval before executing. See [Respond to confirmation requests](https://platform.claude.com/docs/en/managed-agents/permission-policies#respond-to-confirmation-requests) for the event flow. |
Each toolset kind has its own default: the agent toolset defaults to `always_allow`, and MCP toolsets default to `always_ask`.
A permission policy controls when an enabled tool runs. To remove a tool from the agent entirely, disable it instead. See [Disabling specific tools](https://platform.claude.com/docs/en/managed-agents/tools#disabling-specific-tools).
## Set a policy for a toolset
You set permission policies in the agent's `tools` configuration when you create the agent, and you can change them later by [updating the agent](https://platform.claude.com/docs/en/managed-agents/agent-setup#update-an-agent). Running sessions keep the toolset configuration they were created with. Updates apply to sessions created afterward.
### Agent toolset permissions
When creating an agent, you can apply a policy to every tool in `agent_toolset_20260401` using `default_config.permission_policy`:
<CodeGroup defaultLanguage="CLI">
```bash cURL
agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"name": "Coding Assistant",
"model": "claude-opus-5",
"tools": [
{
"type": "agent_toolset_20260401",
"default_config": {
"permission_policy": {"type": "always_ask"}
}
}
]
}')
```
```bash CLI
ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-5
tools:
- type: agent_toolset_20260401
default_config:
permission_policy:
type: always_ask
YAML
```
```python Python
agent = client.beta.agents.create(
name="Coding Assistant",
model="claude-opus-5",
tools=[
{
"type": "agent_toolset_20260401",
"default_config": {
"permission_policy": {"type": "always_ask"},
},
},
],
)
```
```typescript TypeScript
const agent = await client.beta.agents.create({
name: "Coding Assistant",
model: "claude-opus-5",
tools: [
{
type: "agent_toolset_20260401",
default_config: {
permission_policy: { type: "always_ask" }
}
}
]
});
```
```csharp C#
using Anthropic.Models.Beta.Agents;
var agent = await client.Beta.Agents.Create(new()
{
Name = "Coding Assistant",
Model = BetaManagedAgentsModel.ClaudeOpus5,
Tools =
[
new BetaManagedAgentsAgentToolset20260401Params
{
Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
DefaultConfig = new()
{
PermissionPolicy = new BetaManagedAgentsAlwaysAskPolicy { Type = "always_ask" },
},
},
],
});
```
```go Go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Coding Assistant",
Model: anthropic.BetaManagedAgentsModelConfigParams{
ID: "claude-opus-5",
},
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
DefaultConfig: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParams{
PermissionPolicy: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnion{
OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{
Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk,
},
},
},
},
}},
})
if err != nil {
panic(err)
}
_ = agent
```
```java Java
import com.anthropic.models.beta.agents.*;
var agent = client.beta().agents().create(
AgentCreateParams.builder()
.name("Coding Assistant")
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5)
.addTool(
BetaManagedAgentsAgentToolset20260401Params.builder()
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
.defaultConfig(
BetaManagedAgentsAgentToolsetDefaultConfigParams.builder()
.permissionPolicy(
BetaManagedAgentsAlwaysAskPolicy.builder()
.type(BetaManagedAgentsAlwaysAskPolicy.Type.ALWAYS_ASK)
.build()
)
.build()
)
.build()
)
.build()
);
```
```php PHP
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolsetDefaultConfigParams;
use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAskPolicy;
$agent = $client->beta->agents->create(
name: 'Coding Assistant',
model: 'claude-opus-5',
tools: [
BetaManagedAgentsAgentToolset20260401Params::with(
type: 'agent_toolset_20260401',
defaultConfig: BetaManagedAgentsAgentToolsetDefaultConfigParams::with(
permissionPolicy: BetaManagedAgentsAlwaysAskPolicy::with(type: 'always_ask'),
),
),
],
);
```
```ruby Ruby
agent = client.beta.agents.create(
name: "Coding Assistant",
model: "claude-opus-5",
tools: [
{
type: "agent_toolset_20260401",
default_config: {
permission_policy: {type: "always_ask"}
}
}
]
)
```
</CodeGroup>
`default_config` is optional. If you omit it, the agent toolset is enabled with the default permission policy, `always_allow`.
### MCP toolset permissions
MCP toolsets default to `always_ask`. This ensures that new tools added to an MCP server do not execute in your application without approval. To auto-approve tools from a trusted MCP server, set `default_config.permission_policy` on the `mcp_toolset` entry.
The `mcp_server_name` must match the `name` of a server in the `mcp_servers` array.
This example connects a GitHub MCP server and allows its tools to run without confirmation:
<CodeGroup defaultLanguage="CLI">
```bash cURL
agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d '{
"name": "Dev Assistant",
"model": "claude-opus-5",
"mcp_servers": [
{"type": "url", "name": "github", "url": "https://mcp.example.com/github"}
],
"tools": [
{"type": "agent_toolset_20260401"},
{
"type": "mcp_toolset",
"mcp_server_name": "github",
"default_config": {
"permission_policy": {"type": "always_allow"}
}
}
]
}')
```
```bash CLI
ant beta:agents create <<'YAML'
name: Dev Assistant
model: claude-opus-5
mcp_servers:
- type: url
name: github
url: https://mcp.example.com/github
tools:
- type: agent_toolset_20260401
- type: mcp_toolset
mcp_server_name: github
default_config:
permission_policy:
type: always_allow
YAML
```
```python Python
agent = client.beta.agents.create(
name="Dev Assistant",
model="claude-opus-5",
mcp_servers=[
{"type": "url", "name": "github", "url": "https://mcp.example.com/github"},
],
tools=[
{"type": "agent_toolset_20260401"},
{
"type": "mcp_toolset",
"mcp_server_name": "github",
"default_config": {
"permission_policy": {"type": "always_allow"},
},
},
],
)
```
```typescript TypeScript
const agent = await client.beta.agents.create({
name: "Dev Assistant",
model: "claude-opus-5",
mcp_servers: [{ type: "url", name: "github", url: "https://mcp.example.com/github" }],
tools: [
{ type: "agent_toolset_20260401" },
{
type: "mcp_toolset",
mcp_server_name: "github",
default_config: {
permission_policy: { type: "always_allow" }
}
}
]
});
```
```csharp C#
using Anthropic.Models.Beta.Agents;
var agent = await client.Beta.Agents.Create(new()
{
Name = "Dev Assistant",
Model = BetaManagedAgentsModel.ClaudeOpus5,
McpServers =
Cut at 300 lines. The page has the rest.
No line in this hunk matches that.