Page history
permission-policies
managed-agents/permission-policies
History
managed-agents/permission-policies Changed · +42 / -30 lines
from line 50
}') ``` - ```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 - ``` + <MultiFileExample language="cli" label="CLI"> + ```bash CLI + ant beta:agents create < agent.yaml + ``` + <File filename="agent.yaml"> + ```yaml + name: Coding Assistant + model: claude-opus-5 + tools: + - type: agent_toolset_20260401 + default_config: + permission_policy: + type: always_ask + ``` + </File> + </MultiFileExample> + ```python Python agent = client.beta.agents.create( name="Coding Assistant",
from line 240
}') ``` - ```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 - ``` + <MultiFileExample language="cli" label="CLI"> + ```bash CLI + ant beta:agents create < agent.yaml + ``` + <File filename="agent.yaml"> + ```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 + ``` + </File> + </MultiFileExample> + ```python Python agent = client.beta.agents.create( name="Dev Assistant",
from line 573
}, }, }, - Configs: []anthropic.BetaManagedAgentsAgentToolConfigUnionParamsUnion{{ - OfBetaManagedAgentsBashToolConfigs: &anthropic.BetaManagedAgentsBashToolConfigParams{ + Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{{ + OfBash: &anthropic.BetaManagedAgentsBashToolConfigParams{ PermissionPolicy: anthropic.BetaManagedAgentsBashToolConfigParamsPermissionPolicyUnion{ OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{ Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk,
managed-agents/permission-policies Changed · +10 / -12 lines
from line 541
}, Configs = [ - new() + new BetaManagedAgentsBashToolConfigParams { - Name = "bash", PermissionPolicy = new BetaManagedAgentsAlwaysAskPolicy { Type = "always_ask" }, }, ],
from line 561
}, }, }, - Configs: []anthropic.BetaManagedAgentsAgentToolConfigParams{{ - Name: anthropic.BetaManagedAgentsAgentToolConfigParamsNameBash, - PermissionPolicy: anthropic.BetaManagedAgentsAgentToolConfigParamsPermissionPolicyUnion{ - OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{ - Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk, + Configs: []anthropic.BetaManagedAgentsAgentToolConfigUnionParamsUnion{{ + OfBetaManagedAgentsBashToolConfigs: &anthropic.BetaManagedAgentsBashToolConfigParams{ + PermissionPolicy: anthropic.BetaManagedAgentsBashToolConfigParamsPermissionPolicyUnion{ + OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{ + Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk, + }, }, }, }},
from line 593
.build() ) .addConfig( - BetaManagedAgentsAgentToolConfigParams.builder() - .name(BetaManagedAgentsAgentToolConfigParams.Name.BASH) + BetaManagedAgentsBashToolConfigParams.builder() .permissionPolicy( BetaManagedAgentsAlwaysAskPolicy.builder() .type(BetaManagedAgentsAlwaysAskPolicy.Type.ALWAYS_ASK)
from line 607
``` ```php PHP - use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolConfigParams; + use Anthropic\Beta\Agents\BetaManagedAgentsBashToolConfigParams; use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolsetDefaultConfigParams; use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAllowPolicy;
from line 620
permissionPolicy: BetaManagedAgentsAlwaysAllowPolicy::with(type: 'always_allow'), ), configs: [ - BetaManagedAgentsAgentToolConfigParams::with( - name: 'bash', + BetaManagedAgentsBashToolConfigParams::with( permissionPolicy: BetaManagedAgentsAlwaysAskPolicy::with(type: 'always_ask'), ), ],
managed-agents/permission-policies First recorded · 929 lines, first recorded
## 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 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.