Permission Model

How Claude Code controls what the AI can and cannot do — permission modes, rules, classifiers, and the approval flow.

Permission Modes

Every session operates in one of several permission modes:

Mode	Behavior	Use Case
default	Ask user for each tool use	Normal interactive use
acceptEdits	Auto-approve file edits only	Trust file changes, still ask for shell
bypassPermissions	Allow everything	Fully trusted automation
dontAsk	Auto-approve all tools	Headless/CI mode
plan	Structured planning mode	Plan before execute
auto (internal)	Classifier-based auto-approval	Smart auto-mode with safety net

Permission Resolution Flow

🤖

Model wants to use a tool

✅

Validate input schema

🔒

Check permission rules

Rule: allow

Rule: deny → Return denial

No matching rule

Check permission mode

default

❓

Show approval dialog

Approved

Denied

auto

⚙️

Bash classifier

Safe → Proceed

Unsafe → Ask user

acceptEdits

❓

Is file edit?

Yes → Proceed

No → Ask user

🔧

Pre-tool hooks

Hook vetoed — Denied

Proceed — Execute tool

Permission Rules

Rules are pattern-based matchers that pre-authorize or block specific tool uses:

Bash(git *)              # Allow all git commands
Bash(npm test)           # Allow npm test specifically
FileEdit(/src/*)         # Allow edits in src/
FileEdit(/node_modules/*) # (would deny edits in node_modules)
MCPTool(mcp__github__*)  # Allow all GitHub MCP tools

Rule Sources

Rules come from multiple places, evaluated in order:

1. CLI flags — --allow Bash(git *), --deny FileEdit(*)
2. User settings — ~/.claude/settings.json
3. Project settings — .claude.json in repo root
4. Local settings — .claude/local.json
5. Enterprise policies — managed by org admin, cannot be overridden

Rule Precedence

Highest Priority

Enterprise Policy

Project Settings

User Settings

Local Settings

Lowest Priority

CLI Flags

Enterprise policies always win — if an admin blocks Bash(rm -rf *), no local setting can override it.

Bash Classifier

In auto mode, the Bash tool has an additional safety layer — a classifier that evaluates commands before execution:

What the Classifier Checks

• Destructive commands — rm -rf, git reset --hard, etc.
• Network commands — curl to unknown hosts, wget, etc.
• Privilege escalation — sudo, su, etc.
• System modification — chmod, chown, systemctl, etc.

Classifier Decision

• Allow — command is clearly safe (e.g., git status, ls, cat)
• Ask — command might be risky, ask the user
• Deny — command is clearly dangerous

User Approval Dialog

When permission mode requires approval, the REPL shows an interactive dialog:

Illustration

This mockup is a stylized explainer for the approval flow, not a pixel-accurate reproduction of the current Claude Code CLI UI.

Permission Request

Approval Required

Claude wants to run a shell command

Bash

~/claude-code-anatomy rm -rf dist/

Mode: defaultSandbox: workspace-writeRisk: destructive

This command deletes the generated build output and needs your approval before execution.

Y

Allow once

Run this command for this prompt only.

N

Deny

Block execution and return to the REPL.

A

Always allow

Persist a permission rule for future matches.

Options:

• Allow — permit this one time
• Deny — block this one time
• Always allow — add a permanent permission rule

Decision Handlers

The permission system supports different decision handlers depending on context:

Context	Handler	How It Works
Interactive REPL	Interactive	Shows UI dialog to user
Coordinator mode	Coordinator	Delegates to coordinator worker
Swarm worker	Swarm	Syncs with leader via mailbox
Background task	Background	Auto-deny (no UI available)

How Other Frameworks Compare

Claude Code's permission model is unusually integrated: approval policy, rule sources, interactive UI, and resume behavior all live in the same runtime layer.

Framework	Approval Primitive	Runtime Shape	Who Resolves It
Claude Code	Permission modes + rules + classifier + hooks	Tool gate before execution	Built-in REPL / coordinator / SDK callback
Google ADK	Per-tool require_confirmation; bash prefix policy	Tool asks through ToolContext	Host app / tool confirmation handler
OpenAI Agents	Tool approval callbacks + ToolApprovalItem interruptions	Pending approvals for shell, patch, MCP, or nested agent-tool runs	Caller records decision and resumes run
LangChain / LangGraph	interrupt_before checkpoints	Graph pauses before selected nodes	Caller inspects state and resumes the graph

Key difference

Claude Code treats permissions as a first-class runtime subsystem. The other frameworks expose approval points, but the surrounding policy engine, UI, and resume loop are usually left to the host application or graph client.

Key Source Files

File	Purpose
src/types/permissions.ts	Permission type definitions
src/utils/permissions/permissions.ts	Core permission resolution and approval reasons
src/utils/permissions/permissionSetup.ts	Rule loading and permission bootstrapping
src/hooks/toolPermission/handlers/interactiveHandler.ts	Interactive approval UI handler
src/hooks/toolPermission/handlers/swarmWorkerHandler.ts	Worker-side approval forwarding in swarm mode
src/entrypoints/sdk/controlSchemas.ts	SDK can_use_tool approval protocol
src/hooks/useCanUseTool.tsx	Permission check React hook