Permission Modes

You deploy a Claude agent to CI. It hangs. No error, no timeout — just sitting there, waiting for a permission prompt that nobody is there to answer. The fix is one flag. But pick the wrong flag and you’ve just given Claude unrestricted access to your production server.

Six permission modes control how much autonomy Claude gets — from asking before every action, to executing everything silently. Combined with tool-level allowlists and denylists, they form the permission system that determines exactly what Claude can and cannot do.

The Six 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.

auto is the most sophisticated mode. Instead of static tool-based rules, it uses an AI safety classifier with 7 allow rules (local ops, read-only, declared dependencies…) and 26 deny rules (data exfiltration, production deploys, credential exploration…) plus configurable trust boundaries. Inspect the classifier with claude auto-mode config and claude auto-mode defaults. Currently gated behind an unreleased API beta (afk-mode-2026-01-31) — the CLI is ready but the server-side classifier hasn’t shipped yet.

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 six 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, etc.
• 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.

For details on how permission rules interact across scopes, including precedence, --settings overrides, and merge behavior, see Permission Precedence below.

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.

Permission Precedence

You add an allow rule for Write in your project settings. It doesn’t work — a managed deny rule at the org level overrides it silently. Permission rules have a precedence hierarchy, and the rules you set might not be the rules that actually apply.

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.

--settings Runtime Override

The --settings flag loads additional settings from inline JSON or a file path, creating a new precedence layer above project settings:

# Inline JSON — override a project deny rule for this session
claude -p "Write deployment notes" \
  --settings '{"permissions":{"allow":["Write"]}}' \
  --permission-mode bypassPermissions

# File-based — same effect
claude -p "Write deployment notes" \
  --settings ./ci-overrides.json \
  --permission-mode bypassPermissions

Experimentally confirmed: --settings with allow:["Write"] overrides a project .claude/settings.json that denies Write. The file was created successfully with zero permission_denials. Both inline JSON and file-based formats behave identically.

--settings composes with --allowedTools — both flags work together without conflict. --settings affects the settings precedence layer while --allowedTools operates on the tool filter layer.

Array Settings Merge Behavior

When settings are loaded from multiple scopes (user, project, local, CLI), array values like permissions.allow and permissions.deny are concatenated and deduplicated, not replaced. A project-level allow: ["Read"] combined with a user-level allow: ["Write"] results in allow: ["Read", "Write"].

This merge-and-deduplicate strategy applies to all array-type settings across all scopes.