Permission Modes & Safety

Claude Code is an agent — it edits files, runs shell commands, and chains many steps without checking in after each one. The permission system is the steering wheel for how much of that it does on its own versus how often it stops to ask you. The key idea: it is a dial, not an on/off switch. You are choosing a point on a spectrum from "ask me before every action" to "skip every check," and the right point depends on the task, the blast radius, and where you are running.

There are two layers, and they work together:

1. Permission modes — a session-wide posture (the dial). One mode is active at a time. It sets the default behavior: ask, auto-accept edits, read-only, and so on.
2. Permission rules — explicit allow / ask / deny entries in your settings that override the mode for specific tools or commands. A deny rule wins no matter what the mode is (with one extreme exception we'll cover).

Think of the mode as the house thermostat and the rules as the per-room overrides. The mode says "generally, behave like this," and the rules carve out exceptions: "always let git status run" or "never touch the secrets file." The rest of this lesson walks every mode, then the rules — because the rules are where the guarantees live.

Every Claude Code session is in exactly one of six modes. Here is the full table — what each auto-approves, and what it still stops to ask about:

A few things that trip people up:

• acceptEdits is about edits, not commands. It auto-accepts file writes, but it still asks before most Bash commands. If you want a command to run unprompted, allow-list it (next section). Don't reach for a more permissive mode when a targeted rule is what you need.
• plan mode runs nothing. It is the cheapest way to let Claude investigate an unfamiliar codebase safely — it can read and search, but it cannot change or break anything. Press Ctrl+G to open the proposed plan in your editor and tweak it before approving.
• dontAsk is not the same as bypass. dontAsk is the strict automation mode: anything not explicitly allowed is denied outright (no prompt). bypass is the permissive one: nothing is checked at all.
• bypassPermissions is the loaded gun. It exists for sandboxed containers and disposable VMs where there is nothing valuable to wreck. Even here, deletions targeting / or your home directory ~ still prompt as a last-ditch guard.

There are two ways to set the mode: cycle it live during a session, or pin it at launch.

Live, mid-session — Shift+Tab. Pressing Shift+Tab cycles through the modes. The core cycle is:

default  →  acceptEdits  →  plan  →  (back to default)

auto and bypassPermissions join the cycle only when they are enabled for your setup (auto needs the right model/provider; bypass needs to be turned on). On some terminal configs the binding is Alt+M instead. The current mode is shown in the status line, so you always know which posture you're in. To leave plan mode, press Shift+Tab again to continue cycling.

At launch — --permission-mode. Pin a mode when you start a session:

claude --permission-mode plan          # start read-only for safe exploration
claude --permission-mode acceptEdits   # start auto-accepting edits
claude --permission-mode dontAsk -p "run the test suite"   # strict headless

The accepted values are exactly: default, acceptEdits, plan, auto, dontAsk, bypassPermissions.

The dangerous shortcut. --dangerously-skip-permissions is a dedicated flag that is identical to --permission-mode bypassPermissions — same effect, scarier name to make you think twice.

You can also enter plan mode with /plan [description] as a slash command, which is handy when you're already mid-conversation and want to drop into read-only planning for the next chunk of work.

auto is the newest and most nuanced mode — a research preview, not a finished feature. Instead of a fixed rule ("accept all edits," "ask for all commands"), a background safety classifier judges each action in context and decides whether to auto-approve it or route it back to you for a prompt. The goal is fewer interruptions on the obviously-safe stuff while still stopping the risky stuff.

What the classifier blocks (routes back to you):

• Scope escalation — actions that reach beyond what the task plausibly needs.
• Unknown infrastructure — touching systems or services it can't identify as safe.
• Hostile content — inputs that look like prompt injection or otherwise adversarial.

What the classifier can and can't see: it reads your messages, the tool calls Claude proposes, and your CLAUDE.md — but it strips tool results before judging. (That's deliberate: tool output is exactly where injected, hostile instructions tend to hide.) If you ever see "cannot determine safety," that's a transient classifier hiccup, not a verdict.

The fallback rule. Auto mode is not a one-way door. It automatically falls back to normal prompting after 3 consecutive denials or 20 total denials in a session — a signal that the classifier keeps disagreeing with the direction of work, so it hands control back to you rather than fighting you.

Requirements (this is strict):

# Cloud-provider example: opt in explicitly
export CLAUDE_CODE_ENABLE_AUTO_MODE=1
claude --model opus --permission-mode auto

Watch the provider gap. Sonnet 4.6 unlocks auto mode on the direct Anthropic API only. On Bedrock, Vertex AI, and Foundry the only supported models are Opus 4.7 and 4.8 — Sonnet 4.6 will not enable auto there no matter the env var. Plan deployments accordingly. (Model support shifts over time, so confirm against the official permission-modes docs.)

If your model or provider doesn't meet the bar, auto simply won't be available in the Shift+Tab cycle.

Two mechanisms sit underneath the modes and shape what actually gets auto-approved.

Protected paths — never auto-approved (except bypass). Some files are sensitive enough that Claude Code will always prompt before writing to them, regardless of mode — the only exception being bypassPermissions, which skips everything (under auto, writes here are routed to the classifier rather than auto-approved; under dontAsk they're denied). The protected set is deliberately broad — it covers VCS internals, your Claude Code config, shell startup files, and a wide range of package-manager and tooling configs that can run code on your behalf:

This list is long and changes over time — treat the table as representative, not exhaustive, and check the official permission-modes docs for the complete, current protected set before assuming a given config file is guarded.

Note the carve-out: .claude itself is protected, but a few subdirectories where Claude routinely creates content — .claude/commands, .claude/agents, .claude/skills, and .claude/worktrees — are not, so Claude can manage things like .claude/skills/ without a prompt while your top-level config stays guarded.

Allow-listing — make safe commands stop prompting. The complement to protection is permission: tell Claude Code which tools and commands it may run without asking. You can do this two ways.

At launch with --allowedTools (permission-rule syntax):

claude --allowedTools "Bash(git log *)" "Bash(git diff *)" "Read"

Or persistently in .claude/settings.json under a permissions block with allow / ask / deny lists:

{
  "permissions": {
    "allow": ["Bash(git status)", "Bash(npm test)", "Read"],
    "ask":   ["Bash(git push *)"],
    "deny":  ["Bash(rm -rf *)", "Read(./.env)"]
  }
}

Manage all of this interactively with /permissions (alias /allowed-tools) — it shows recent denials and lets you turn a denial into a rule (press r to retry). And to build a sensible read-only allow-list automatically, run /fewer-permission-prompts: it scans your transcripts for the safe, repetitive commands you keep approving and proposes an allow-list for settings.json.

This is the single most important habit in this lesson, so it gets its own section.

It is tempting to enforce a boundary by telling Claude: "Never push to main," "Don't run migrations," "Leave the production config alone." In a long session this feels sufficient — Claude agreed, after all. But conversational instructions live in the context window, and the context window is not permanent. When the session compacts (summarizes older turns to free space), the precise wording of a one-off boundary can get dropped or softened. Hours later, Claude no longer reliably "remembers" the rule you stated once at the top.

A deny rule has none of that fragility. It lives in settings.json, it is evaluated on every single tool call, and it wins over the active mode — even acceptEdits, even auto, even dontAsk. It does not depend on Claude's cooperation or memory at all; it's a wall, not a request.

{
  "permissions": {
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

The rule of thumb:

• Advice / preferences ("prefer 2-space indent," "explain before large refactors") → fine in conversation or CLAUDE.md.
• Hard guarantees ("never push," "never read this secret," "never delete that path") → deny rules.

If the cost of the rule being forgotten is real, the rule does not belong in a sentence. It belongs in deny.