Claude Code plan mode: what it actually blocks, what still runs, and what approving switches you into

Plan mode looks simple from the outside: press Shift+Tab a couple of times, Claude stops editing, you get a plan to review. But the mechanics underneath have changed enough in recent releases that most mental models of it are stale — especially around what commands still run while you're planning and which permission mode you land in after you approve.

There's also a deadline that makes this worth re-reading now: starting August 14, 2026, auto mode becomes the default permission mode for new sessions on Pro, Max, and Team plans. One of plan mode's least-known behaviors — classifier-reviewed commands during planning — is tied to auto mode availability, so it's about to become the normal experience rather than the exception.

Everything below is verified against the current official docs (code.claude.com/docs/en/permission-modes, checked 2026-08-13).

What plan mode is

Plan mode tells Claude to research and propose changes without making them. Claude reads files, runs shell commands to explore, and writes a plan — but does not edit your source. Edits stay blocked until you approve the plan (with one important exception covered in the gotchas section).

It's the mode for "I want to understand what Claude intends before anything touches my files." The docs position it for exploring a codebase before changing it, and that's genuinely where it shines: big refactors, unfamiliar repos, changes where the approach matters more than the diff.

One naming collision to clear up early: plan mode (a permission mode) is not the Plan agent (a subagent type). The permission-rule syntax Agent(Plan) targets the Plan subagent, which is a separate mechanism for delegated planning work. This article is about the mode.

Three ways in, one way out

In:

1. Shift+Tab cycles default → acceptEdits → plan in the CLI. The status bar shows ⏸ plan mode on when you're there.
2. /plan as a prompt prefix applies plan mode to a single prompt — useful when you want one planned answer without changing the session's mode.
3. claude --permission-mode plan starts the whole session in it. The same flag works with -p for non-interactive runs.

To make it stick across sessions, set it in a settings file — but see the defaults section below, because there's a VS Code exception.

Out: press Shift+Tab again to leave plan mode without approving a plan. That's the escape hatch people forget exists — you're not committed to producing a plan just because you entered the mode.

What still runs while you plan

This is where most descriptions of plan mode are out of date. There are three cases:

1. Reads and the built-in read-only command set run without prompting. That's the baseline everyone knows.
2. When auto mode is available on your account and the useAutoModeDuringPlan setting is on — which it is by default — other shell commands during planning go to auto mode's classifier instead of prompting you. Approved commands run; rejected ones are blocked. In practice this means plan mode with auto available can run your test suite or a build while planning, without a single prompt.
3. Without auto mode, anything outside the read-only set prompts for approval, one command at a time.

Version footnote, because this bit a lot of people: in v2.1.212 through v2.1.217, commands outside the read-only set prompted either way, even when auto mode was available. Current versions route them to the classifier again.

If you use sandboxing: plan mode deliberately skips the sandbox's "auto-allow if sandboxed" substitution. Sandboxed-but-not-read-only commands still prompt (or go to the classifier) while you're planning.

The approval prompt, decoded

When the plan is ready, Claude presents it and asks how to proceed. The options:

• "Yes, and use auto mode" — approve and continue in auto mode. When auto mode isn't available, this option reads "Yes, auto-accept edits" (→ acceptEdits). Sessions started with bypass permissions enabled show "Yes, and bypass permissions" instead.
• "Yes, manually approve edits" — approve the plan, then review each edit individually.
• "No, keep planning" — stay in plan mode and tell Claude what to change.

The part that surprises people: approving a plan exits plan mode and switches the session's permission mode to whatever the approve option describes. Plan mode is a staging area, not a place you stay. If you want to plan the next task too, you cycle back with Shift+Tab or prefix the next prompt with /plan.

Three conveniences worth knowing:

• Ctrl+G opens the proposed plan in your default text editor so you can edit it directly before Claude proceeds. Editing the plan is often faster than another round of "No, keep planning."
• The showClearContextOnPlanAccept setting adds a first option that approves the plan and clears the planning context — handy when the exploration transcript is large and you want the implementation to start clean.
• Accepting a plan auto-names the session from the plan content, unless you've already named it with --name or /rename.

Making plan mode the default

For a project, set it in .claude/settings.json:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Two interface-specific exceptions:

• VS Code extension: in sessions the extension starts, a settings-file defaultMode doesn't set the starting mode. Set claudeCode.initialPermissionMode to plan in your VS Code user settings instead.
• Desktop app: a mode you pick in the mode selector is remembered per folder and takes precedence over defaultMode — except Plan, which applies to the current session only. You can't "sticky" plan mode from the selector; use the settings file.

The two gotchas that actually bite

1. Bypass-available sessions don't enforce plan mode's blocks. In sessions where bypass permissions are available (started with --dangerously-skip-permissions or equivalent), plan mode becomes an instruction rather than an enforcement: Claude is still told to plan without editing, but a file edit or shell command it attempts during planning runs without prompting. If your workflow is "bypass permissions in a container, plan first", know that the plan phase is advisory there — the walls are down.

2. Protected paths behave differently per availability. Writes to protected paths (.git, .claude, .vscode, shell rc files, .mcp.json, and friends) are never auto-approved in plan mode's normal operation — they prompt. But with auto mode available during planning they're routed to the classifier, and in bypass-available planning sessions they're allowed outright. Same mode name, three different behaviors depending on what else is enabled.

When to reach for it

My own rule of thumb after using it daily:

• Unfamiliar repo or cross-cutting change → plan mode. The forced pause before edits is worth more than the keystrokes it costs.
• Research question, no edits expected → plan mode via /plan prefix, or an Explore subagent. Both keep your session from mutating anything.
• Well-understood task in a repo you trust → skip planning, go straight to acceptEdits or auto mode. Plan mode's value is proportional to your uncertainty, and it's close to zero when you already know the diff you want.

And from August 14: if you're on Pro, Max, or Team and accept the new default, your sessions will start in auto mode — which means entering plan mode becomes the deliberate act of slowing down, with classifier-reviewed exploration while you're there. Worth having the exact semantics loaded in your head before that switch flips.

---

I maintain Rulestack — practical packs of Claude Code skills, hooks, and rules files, kept current against how these tools actually behave. Daily AI-coding-workflow notes on Bluesky: @ai-shop.bsky.social.

Comments

[Alex Shev]

This is a useful distinction because "plan mode" sounds safer than it actually is if people assume nothing operational can happen. I like documenting it as a permission boundary, not a thinking boundary: what can still read state, what can still call tools, and what exactly changes after approval.