| title | Configure permissions |
|---|---|
| source | https://code.claude.com/docs/en/agent-sdk/permissions |
| category | code |
| generated | true |
Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt Use this file to discover all available pages before exploring further.
Control how your agent uses tools with permission modes, hooks, and declarative allow/deny rules.
The Claude Agent SDK provides permission controls to manage how Claude uses tools. Use permission modes and rules to define what's allowed automatically, and the canUseTool callback to handle everything else at runtime.
When Claude requests a tool, the SDK checks permissions in this order:
Run [hooks](./code-agent-sdk/hooks.md) first. A hook can deny the call outright or pass it on. A hook that returns `allow` does not skip the deny and ask rules below; those are evaluated regardless of the hook result. Check `deny` rules (from `disallowed_tools` and [settings.json](./code-settings.md#permission-settings)). If a deny rule matches, the tool is blocked, even in `bypassPermissions` mode. Bare-name deny rules like `Bash` remove the tool from Claude's context before this evaluation begins, so only scoped rules like `Bash(rm *)` are checked at this step. Check `ask` rules from [settings.json](./code-settings.md#permission-settings). If an ask rule matches, the call falls through to your [`canUseTool` callback](./code-agent-sdk/user-input.md) for confirmation, even in `bypassPermissions` mode.Tools that require user interaction behave the same way: `AskUserQuestion` and MCP tools whose server sets [`_meta["anthropic/requiresUserInteraction"]`](./code-mcp.md#require-approval-for-a-specific-tool) always fall through to the callback, even when an allow rule matches. In `dontAsk` mode both cases are denied instead, because that mode never prompts. {/* min-version: 2.1.199 */}The MCP annotation requires Claude Code v2.1.199 or later.
As of v2.1.198, if you pass a canUseTool callback that this evaluation order can never reach, the TypeScript SDK emits a Node.js process warning once when the query is constructed. The warning's code is CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Two configurations trigger it:
permissionMode: 'bypassPermissions', which auto-approves every call that reaches the permission mode step- Each bare
allowedToolsentry such as"Read", which auto-approves that whole tool before the callback is consulted
Entries with a specifier such as Bash(ls *) and the acceptEdits mode don't trigger it, and allow rules coming from settings files aren't visible to the check.
Listen with process.on('warning', ...) and match the code to log or suppress it. To gate every tool call regardless of mode and rules, use a PreToolUse hook instead.
This page focuses on allow and deny rules and permission modes. For the other steps:
- Hooks: run custom code to allow, deny, or modify tool requests. See Control execution with hooks.
- canUseTool callback: prompt users for approval at runtime, when no earlier step resolves the call. See Handle approvals and user input.
allowed_tools and disallowed_tools (TypeScript: allowedTools / disallowedTools) add entries to the allow and deny rule lists in the evaluation flow above. Allow rules only affect approval: a tool not listed in allowed_tools is still available to Claude and falls through to the permission mode. Deny rules behave differently depending on whether they name a tool or scope a pattern within one.
| Option | Effect |
|---|---|
allowed_tools=["Read", "Grep"] |
Read and Grep are auto-approved. Tools not listed here still exist and fall through to the permission mode and canUseTool. |
disallowed_tools=["Bash"] |
The Bash tool definition is removed from the request. Claude does not see the tool and cannot attempt it. |
disallowed_tools=["Bash(rm *)"] |
Bash stays available. Calls matching rm * are denied in every permission mode, including bypassPermissions. Other Bash calls fall through to the permission mode. |
disallowed_tools=["*"] |
Every tool definition is removed from the request. Tool-name globs are supported in deny rules: "*" matches every tool and "mcp__*" matches every MCP tool across all servers. |
Allow rules accept tool-name globs only after a literal mcp__<server>__ prefix. The server segment must be glob-free so the rule names a specific server you configured: mcp__puppeteer__* matches every tool from the puppeteer server, and mcp__github__get_* matches its get_ tools. An unanchored entry like allowed_tools=["*"] or allowed_tools=["mcp__*"] is ignored with a startup warning and does not auto-approve anything.
For a locked-down agent, pair allowedTools with permissionMode: "dontAsk". Listed tools are approved; anything else is denied outright instead of prompting:
const options = {
allowedTools: ["Read", "Glob", "Grep"],
permissionMode: "dontAsk"
};You can also configure allow, deny, and ask rules declaratively in .claude/settings.json. These rules are read when the project setting source is enabled, which it is for default query() options. If you set setting_sources (TypeScript: settingSources) explicitly, include "project" for them to apply. See Permission settings for the rule syntax.
Permission modes provide global control over how Claude uses tools. You can set the permission mode when calling query() or change it dynamically during streaming sessions.
The SDK supports these permission modes:
| Mode | Description | Tool behavior |
|---|---|---|
default |
Standard permission behavior | No auto-approvals; unmatched tools trigger your canUseTool callback |
dontAsk |
Deny instead of prompting | Anything not pre-approved by allowed_tools or rules is denied; canUseTool is never called |
acceptEdits |
Auto-accept file edits | File edits and filesystem operations (mkdir, rm, mv, etc.) are automatically approved |
bypassPermissions |
Bypass permission checks | Tools run without permission prompts, unless an explicit ask rule matches (use with caution) |
plan |
Planning mode | Claude explores and plans without editing your source files; file edits are never auto-approved and prompt through your canUseTool callback |
auto |
Model-classified approvals | A model classifier approves or denies each tool call. See Auto mode for availability |
You can set the permission mode once when starting a query, or change it dynamically while the session is active.
Pass `permission_mode` (Python) or `permissionMode` (TypeScript) when creating a query. This mode applies for the entire session unless changed dynamically.<CodeGroup>
```python Python theme={null}
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Help me refactor this code",
options=ClaudeAgentOptions(
permission_mode="default", # Set the mode here
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
```
```typescript TypeScript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";
async function main() {
for await (const message of query({
prompt: "Help me refactor this code",
options: {
permissionMode: "default" // Set the mode here
}
})) {
if ("result" in message) {
console.log(message.result);
}
}
}
main();
```
</CodeGroup>
<CodeGroup>
```python Python theme={null}
import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
async def main():
async with ClaudeSDKClient(
options=ClaudeAgentOptions(
permission_mode="default", # Start in default mode
)
) as client:
await client.query("Help me refactor this code")
# Change mode dynamically mid-session
await client.set_permission_mode("acceptEdits")
# Process messages with the new permission mode
async for message in client.receive_response():
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
```
```typescript TypeScript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";
async function main() {
const q = query({
prompt: "Help me refactor this code",
options: {
permissionMode: "default" // Start in default mode
}
});
// Change mode dynamically mid-session
await q.setPermissionMode("acceptEdits");
// Process messages with the new permission mode
for await (const message of q) {
if ("result" in message) {
console.log(message.result);
}
}
}
main();
```
</CodeGroup>
Auto-approves file operations so Claude can edit code without prompting. Other tools (like Bash commands that aren't filesystem operations) still require normal permissions.
Auto-approved operations:
- File edits (Edit, Write tools)
- Filesystem commands:
mkdir,touch,rm,rmdir,mv,cp,sed
Both apply only to paths inside the working directory or additionalDirectories. Paths outside that scope and writes to protected paths still prompt.
Use when: you trust Claude's edits and want faster iteration, such as during prototyping or when working in an isolated directory.
Converts any permission prompt into a denial. Tools pre-approved by allowed_tools, settings.json allow rules, or a hook run as normal. Everything else is denied without calling canUseTool.
Use when: you want a fixed, explicit tool surface for a headless agent and prefer a hard deny over silent reliance on canUseTool being absent.
Auto-approves all tool uses without prompts. Hooks still execute and can block operations if needed.
Use with extreme caution. Claude has full system access in this mode. Only use in controlled environments where you trust all possible operations.allowed_tools does not constrain this mode. Every tool is approved, not just the ones you listed. Deny rules (disallowed_tools), explicit ask rules, and hooks are evaluated before the mode check and can still block a tool.
Claude explores the codebase and produces a plan without editing your source files. Read-only tools run as in default mode. File edits are never auto-approved in plan mode, even when an allow rule matches. They prompt through your canUseTool callback instead. Claude may use AskUserQuestion to clarify requirements before finalizing the plan. See Handle approvals and user input for handling these prompts.
Use when: you want Claude to propose changes without executing them, such as during code review or when you need to approve changes before they're made.
For the other steps in the permission evaluation flow:
- Handle approvals and user input: interactive approval prompts and clarifying questions
- Hooks guide: run custom code at key points in the agent lifecycle
- Permission rules: declarative allow/deny rules in
settings.json