Permission Modes

Claude Code has five permission modes that control how much autonomy it gets — from asking before every action, to executing everything without a prompt. The right mode depends on context: interactive coding sessions need guardrails, CI/CD pipelines need full autonomy, and code reviews need read-only access. Combined with tool-level allowlists and denylists, these modes form a layered permission system that determines exactly what Claude can and cannot do.

The Five Modes

Every claude session runs in exactly one permission mode. You set it with --permission-mode MODE or accept the default.

default is what you get when you launch claude with no flags. Every destructive tool — Bash, Edit, Write — requires one-time approval. Once approved, the rule persists for the session (file edits) or permanently per project (bash commands). Read-only tools like Grep and file reads never require permission.

acceptEdits trusts Claude with file modifications inside the project directory. Bash commands still require approval. This is the sweet spot for focused coding sessions where you want speed but not unlimited shell access.

plan is read-only. Claude can read files, search code, and reason — but cannot write files or execute commands. Use this for code review, architecture analysis, or when you want Claude to produce a plan without touching anything.

dontAsk is the inverse of default. Instead of prompting for unknown tools, it silently denies them. Only tools explicitly listed in permission allow rules will work. This is designed for headless or automated workflows where there is no human to answer prompts.

bypassPermissions disables all permission checks. Every tool call succeeds without prompting. This should only be used in isolated environments — CI/CD pipelines, containers, or virtual machines where the blast radius is contained.

Choosing a Mode

The decision comes down to two questions: is a human watching, and how much do you trust the environment?

A common pattern is combining modes with sessions. Plan in plan mode, review the output, then --resume the same session in bypassPermissions to execute. The Session Chains chapter covers this workflow in detail.

—allowedTools / —disallowedTools

Beyond the five modes, you can filter at the individual tool level. These flags accept comma-separated tool names and support pattern matching.

# Only allow file reads and grep — nothing else
claude -p "Analyze auth.py" --allowedTools "Read,Grep,Glob"

# Allow everything except shell access
claude -p "Refactor this module" --disallowedTools "Bash"

# Allow specific bash commands with glob patterns
claude -p "Run the tests" --allowedTools "Bash(npm test *),Read,Edit"

Tool specifiers use the same pattern syntax as permission rules:

• Bash(git *) — matches git status, git commit, but NOT gitk
• Edit(/src/**/*.ts) — matches any TypeScript file under /src/
• mcp__puppeteer__* — matches all tools from the puppeteer MCP server

These flags are temporary and apply only to the current session. They combine with the permission mode — a tool must pass both the mode check and the allowlist/denylist check to execute.

Precedence Rules

Permission rules can be defined at multiple levels. When rules conflict, the higher-precedence level wins. Deny always beats allow at the same level.

The critical rule: deny > ask > allow at every level. If a tool is denied at ANY level, no lower-level allow rule can override it. A team lead can deny Bash(rm -rf *) in shared project settings, and no individual developer’s local settings or CLI flags can re-enable it.

Modes in Action — Same Prompt, Three Outcomes

To see how modes affect behavior, here is the same prompt run under three different modes: “Write hello to /tmp/perm_test.txt” — a write to a path outside the project directory.

default mode blocks the write and reports one denial:

acceptEdits mode also blocks the write — but Claude retries once before giving up, producing two denials and an extra turn:

bypassPermissions mode succeeds immediately — zero denials, lowest cost:

The key insight from these payloads: acceptEdits does NOT auto-approve writes outside the project directory. The sandbox filesystem restriction applies regardless of permission mode. The retry behavior also means higher cost — check permission_denials.length to understand what happened.