Chapter 12

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.

Note: This page covers permission modes and rules. To build interactive approval flows where users approve or deny tool requests at runtime, see the User Input chapter.

How permissions are evaluated

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

Hooks

Run hooks first, which can allow, deny, or continue to the next step

Permission rules

Check rules defined in settings.json: deny rules first (block regardless of other rules), then allow rules (permit if matched), then ask rules (prompt for approval)

Permission mode

Apply the active permission mode (bypassPermissions, acceptEdits, dontAsk, etc.)

canUseTool callback

If not resolved by rules or modes, call your canUseTool callback for a decision

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

Mode	Description	Tool behavior
`default`	Standard permission behavior	No auto-approvals; unmatched tools trigger your `canUseTool` callback
`acceptEdits`	Auto-accept file edits	File edits and filesystem operations (`mkdir`, `rm`, `mv`, etc.) are automatically approved
`bypassPermissions`	Bypass all permission checks	All tools run without permission prompts (use with caution)
`plan`	Planning mode	No tool execution; Claude plans without making changes

Subagent inheritance

When using bypassPermissions, all subagents inherit this mode and it cannot be overridden. Subagents may have different system prompts and less constrained behavior than your main agent. Enabling bypassPermissions grants them full, autonomous system access without any approval prompts.

Set permission mode

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

At query time

Pass permission_mode (Python) or permissionMode (TypeScript) when creating a query. This mode applies for the entire session unless changed dynamically.

set-permission-mode.ts

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

During streaming

Call set_permission_mode() (Python) or setPermissionMode() (TypeScript) to change the mode mid-session. The new mode takes effect immediately for all subsequent tool requests.

dynamic-permission-mode.ts

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, mv, cp

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

Bypass permissions mode`bypassPermissions`

Auto-approves all tool uses without prompts. Hooks still execute and can block operations if needed.

Warning

Use with extreme caution. Claude has full system access in this mode. Only use in controlled environments where you trust all possible operations.

Plan mode`plan`

Prevents tool execution entirely. Claude can analyze code and create plans but cannot make changes. Claude may use AskUserQuestion to clarify requirements before finalizing the plan.

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

Streaming Input

Handle Approvals & User Input