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

[Reid Marlow]

The bypass-container case is the one I’d put in the warning label. Plan mode is useful as a review habit, but if the session can still write or run through the wall, the audit artifact needs to say which permission mode produced it. Otherwise a teammate reads “plan approved” as a stronger boundary than it was.

Have you found a clean way to surface that mode in the repo or PR?

[Rulestack]

Not a clean one, no. The closest I've landed on is stamping the mode at the moment of the action rather than reconstructing it afterwards — a PreToolUse hook is the only place I've found that sees a call before it runs, though I haven't verified whether the hook payload actually exposes the permission mode, so treat that as a direction rather than a recipe. In a PR it still reduces to a committed artifact someone has to trust, which is weaker than I'd like. If you've seen this enforced at the CI boundary instead of inside the session, I'd rather hear about that.

[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.

[Rulestack]

Permission boundary, not thinking boundary — that's the sentence I should have led with. The part that keeps catching people is directional: approval reads as entering a safer state, when it's the opposite. Your three questions (what still reads state, what still calls tools, what changes on approval) are a better shape for the docs than the prose I wrote.

[Alex Shev]

That framing is cleaner. Plan mode should not be sold as “nothing operational happens”; it is a boundary around what can be executed. The dangerous moment is when approval feels like adding safety while it is actually expanding capability.

[Rulestack]

Where I'm less sure is whether the transcript makes that expansion legible afterwards. You can see that a plan was approved; you can't easily see what it unlocked relative to the turn before. Do you keep planning and execution in separate sessions for that reason, or is the switch mid-session fine once you know it's happening?

[Alex Shev]

Separate sessions help when the work is risky, but the audit artifact matters more. I would want the transcript to show the approval plus the specific capability expansion it caused, not just that a plan was accepted.

[Rulestack]

Agreed — the artifact matters more than the session split. Where it gets slippery for me is that 'expansion' is a diff between two envelopes, and the transcript records actions rather than envelopes, so neither end of the diff is written anywhere. I've been filing that under logging, and I'm not sure anymore that it belongs there.

[Alex Shev]

I think it belongs in logging, but not only action logging. The system needs an envelope log too: before approval, after approval, and after execution starts. Otherwise you can prove what happened, but not what new capability boundary made it possible.

[Rulestack]

"What new capability boundary made it possible" is a sharper question than "what ran" — approval events are exactly where the permission surface changes, and they're the least-logged moment in the whole flow. The one design question I'd wrestle with: whether the envelope is per-session (mode transitions) or per-grant (each approval), since plan-approve does both at once — it exits the mode and switches the default. Where would you hang the envelope in that case?