Configure permissions

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.

How permissions are evaluated

When Claude requests a tool, the SDK checks permissions in this order:

If you pass a canUseTool callback in a configuration where the TypeScript SDK expects the evaluation order to auto-approve calls before the callback is consulted, the 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 apart from the actions no mode auto-approves
• Each bare allowedTools entry such as "Read", which auto-approves that whole tool before the callback is consulted, apart from the actions no mode auto-approves

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.

Allow and deny rules

allowed_tools and disallowed_tools (TypeScript: allowedTools / disallowedTools) add entries to the allow and deny rule lists in the evaluation flow above. If you name one of the task-tracking tools in allowed_tools, Claude Code also opts the session in. Any other tool not listed in allowed_tools is still available to Claude, and a call to it that needs approval falls through to the permission mode. Deny rules behave differently depending on whether they name a tool or scope a pattern within one.

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.

Scoped rules for Read and Edit take a path pattern. Edit(path) rules govern all built-in tools that write files, including Write and NotebookEdit; a Write(path) rule is never matched by the file permission checks.

Use //path for an absolute filesystem path: a deny rule of Edit(//secrets/**) blocks writes anywhere under /secrets on disk. With a single leading slash, Edit(/secrets/**) anchors at the rule's source instead. For rules passed through allowed_tools or disallowed_tools, that means the session's working directory, so the rule doesn't block /secrets on disk. See Read and Edit rules for the four anchor forms and how rules from settings files resolve.

For a locked-down agent, pair allowedTools with permissionMode: "dontAsk":

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk"
};

Listed tools are approved, apart from the actions no mode auto-approves, and every other call that would prompt is denied instead. Calls that need no approval in default mode run whether or not you list them, such as read-only Bash commands, tools like Agent that don't ask before running, and file reads inside your working directories. To put a tool out of Claude's reach entirely, add its bare name to disallowedTools.

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

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.

Available modes

The SDK supports these permission modes:

Set permission mode

You can set the permission mode once when starting a query, or change it dynamically while the session is active.

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())

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();

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())

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();

Mode details

Accept edits mode (acceptEdits)

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. In acceptEdits mode, Claude Code doesn't auto-approve the request when Claude:

• Works on a path outside that scope
• Writes to a protected path
• Removes a critical path with rm or rmdir

Use when: you trust Claude's edits and want faster iteration, such as during prototyping or when working in an isolated directory.

Don't ask mode (dontAsk)

Converts any permission prompt into a denial, without calling canUseTool. Tools pre-approved by allowed_tools, settings.json allow rules, or a hook run as normal, and so do calls that need no approval in default mode, such as file reads inside your working directories and calls to Agent. Connector tools your organization set to ask, tools that require user interaction, and rm and rmdir removals targeting a critical path are denied even when an allow rule matches. A PreToolUse hook allow doesn't clear a critical-path removal either.

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.

Bypass permissions mode (bypassPermissions)

Auto-approves tool uses without prompting, except the cases listed in the warning below. Hooks still execute and can block operations if needed. On Linux and macOS, Claude Code refuses to start in this mode as root or under sudo outside a recognized sandbox, and the query fails before the first turn.

Plan mode (plan)

Claude explores the codebase and produces a plan without editing your source files. Read-only tools run as they do in the default permission mode.

File edits are never auto-approved in plan mode, even when an allow rule matches. They prompt through your canUseTool callback instead. On Claude Code v2.1.212 or later, shell commands that modify files, such as touch and rm, reach your canUseTool callback the same way.

In the TypeScript SDK, if you set allowDangerouslySkipPermissions: true alongside permissionMode: 'plan', file edits and shell commands that modify files still reach your canUseTool callback. The option lets you switch to bypassPermissions later with setPermissionMode().

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.

Related resources

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