Permission Modes — Claude Code · Engineering Playbook

Summary#

Permission modes are the dial that controls how aggressively Claude Code acts on your machine. There are four canonical modes — default, accept-edits, plan, and bypass — and each one changes what the tool will do without asking. Default asks for confirmation on writes and shell commands; accept-edits auto-approves edits but still prompts on Bash; plan blocks acting entirely and only allows reads; bypass runs everything without confirmation.

Picking the right mode for the task is the most important safety habit you’ll develop. Wrong mode for a job is the difference between “Claude wrote a feature in twenty minutes” and “Claude deleted my working tree and force-pushed.”

Why it matters#

Agentic tools shift the failure mode of “the AI got it wrong.” A chat box that returns wrong code costs you a paste and a retry. An agent in bypass mode that runs wrong shell commands costs you a directory, a branch, or a database. The permission system is the explicit boundary between the model’s ideas and your machine’s state.

Three concrete consequences:

A new contributor in default mode is safe. Every risky action is gated. The worst case is a slow session full of confirmations, not a destroyed working tree.
A senior engineer in accept-edits is fast but bounded. Edits and writes go through without prompts; shell commands still confirm. You trust the model on file changes (which are easily reverted via git) but not on system effects (which may not be).
A bypass-mode session needs a real reason. Long lint sweeps, mechanical refactors with a clean test suite, CI runs — fine. Exploratory work in an unfamiliar repo — not fine. The mental check is “if Claude does the wrong thing here, can I undo it cheaply?”

The allowlist mechanism (covered separately) lets you split the difference at finer granularity — auto-approve git status and pnpm test but still confirm on rm -rf — without dropping mode protections entirely.

How it works#

The four modes#

Each mode is a global session setting. You set it via the TUI, the --permission-mode flag, or in settings.json. Mid-session switching is supported.

default — Confirms on Edit, Write, Bash, MCP tools, and anything that writes outside the working directory. Reads (Read, Grep, Glob) and most informational tools auto-approve. This is the right setting for the first hour with any new repo.
accept-edits — Auto-approves Edit and Write. Still confirms on Bash, MCP, and other side-effecting tools. The daily-driver mode for most engineers on familiar codebases. File changes are trivially revertable via git, so the confirmation friction on edits has low value.
plan — Disallows all acting tools. The model can Read, Grep, Glob, WebFetch, run sub-agents — anything that doesn’t change state. Edits, Writes, and Bash are blocked. Used to explore and produce a plan file before you exit the mode and execute. See the plan mode page.
bypass — Auto-approves everything. Edit, Write, Bash, MCP, all of it. No confirmations. The mode for headless work in CI, long autonomous loops, and tightly-scoped mechanical sessions with good tests. The mode you must never set globally.

Modes layer on top of allowlists, not under them: an allowlisted command auto-approves in default mode too, while a denylisted command stays blocked even in accept-edits.

What “confirm” actually looks like#

A confirmation prompt is a one-line summary of the proposed tool call with three options:

Yes — run this call.
Yes, and don’t ask again for this command — run this call and add it to the session-local allowlist.
No, tell Claude what to do differently — block the call, send a message back to the model.

Option 2 is the productive habit: every time you confirm a routine command, allowlist it. Within an hour your session has a working allowlist and the confirmations drop to a trickle. The session-local allowlist resets when the session ends; persistent allowlists go in settings.json.

Tools that always confirm regardless of mode#

A small set of tools confirm even in bypass mode because their failure cost is catastrophic and recovery is hard:

Destructive git operations: git push --force, git reset --hard origin/..., git branch -D on the current branch.
File system destructors: rm -rf outside the working directory.
Auth-bearing operations: anything that writes credentials, modifies ~/.ssh/, or touches ~/.aws/.

You can override this with explicit allowlist entries, but the override has to be deliberate. The “never confirm anything” promise of bypass mode has these documented exceptions for good reason.

How modes interact with hooks#

PreToolUse hooks (covered in their own page) run before the permission check. A hook can deny a tool call even in bypass mode, or pre-approve it before the mode check is reached. This is how you implement org-level safety policies that survive an engineer choosing bypass on a whim — the hook fires regardless of mode and can block dangerous patterns.

In practice, most teams pair accept-edits mode with a small PreToolUse hook that blocks specific dangerous Bash patterns. That combination is fast in the common case and safe in the dangerous one.

Variants and trade-offs#

Mode-only safety — set permission mode appropriate to the task and rely on confirmations for everything else. Simple, predictable, slow in the steady state. Right for engineers in their first few weeks with the tool.

Mode + allowlist + hooks — accept-edits as the default mode, a session-built allowlist covering routine commands, and PreToolUse hooks for dangerous patterns. Fast in the steady state, safe at the edges. Right for engineers who’ve been on the tool for a month or more.

The progression most engineers follow over their first month:

Week 1 — default mode everywhere. Confirm-heavy, slow, safe. Learn what tools fire when.
Week 2 — accept-edits in trusted repos, default in unfamiliar ones. Start building a session-local allowlist.
Week 3 — persistent allowlist in settings.json for routine commands. Bypass mode for explicit batch jobs.
Week 4+ — accept-edits + persistent allowlist + a couple of hooks. Bypass is a per-task choice for headless work, not a default.

There’s a fourth, advanced option some teams adopt: a custom mode profile defined in settings.json that combines a base mode with explicit allow / deny lists for a project. This is heavier than the default modes but lets a team encode “in this repo, never run terraform apply without confirmation” as a project-level rule.

When this is asked in interviews#

Security and safety of agentic tools is a hot topic; permission modes come up reliably.

Developer-tooling / platform loops — “How does this tool prevent destructive actions?” is a stock question. Naming the four modes, the allowlist mechanism, and the PreToolUse hook layer in one breath is a strong answer.
Security engineering interviews at AI companies — the depth gets higher. Expect questions about how a malicious prompt could escape the permission model (prompt injection causing the model to request rm -rf), what the mitigations are, and where the boundaries are weakest (the human clicking through prompts without reading is the perennial weak spot).
Senior backend interviews at teams building internal agents — the framing is usually “how would you design a permission model for an internal agent?” The four-mode pattern, plus allowlists and hooks, is a defensible reference design.

Less common in classic frontend / mobile / SRE loops, but it does come up in any team that’s started thinking about an agent for ops work.

The most underrated mode is plan

Most engineers think of plan as a niche feature — “for big changes only.” It’s also the right mode for any session where you don’t yet know whether you’ll let Claude act. You read, you grep, you ask questions, you produce a plan. If the plan looks right, you exit and execute. If it doesn’t, you’ve spent a few minutes and zero side-effects rather than half an hour and a partially-broken branch. Use plan mode as your default for anything genuinely unfamiliar.