Plan mode: the four ways in, and what it actually blocks

Lesson 4.1 argued that exploration is the phase you skip by accident. Deciding to explore first is a resolution, and resolutions do not survive an agent already allowed to edit. Plan mode holds the decision in place — a harness control, not a request you make of the model.

What plan mode is, stated exactly

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. Except in sessions with bypass permissions available, edits stay blocked until you approve the plan. — Choose a permission mode

Read it for the verbs. Three things still happen — reading, exploring by shell, writing a plan. One does not: editing your source. Plan mode is a gate on edits, not a general muzzle, and most confusion about it comes from expecting the second. Approving is Lesson 4.3; the bypass clause is the last section here.

Four ways in

The two in-session routes are documented in one sentence: "Enter plan mode by pressing Shift+Tab or prefixing a single prompt with /plan" (Choose a permission mode). /plan takes an argument, which is the part people miss — the command reference describes it as entering plan mode "and immediately start with that task", and gives /plan fix the auth bug as the example, one line that does both.

At launch it is the same --permission-mode flag that selects any other mode: it accepts default, acceptEdits, plan, auto, dontAsk and bypassPermissions, and overrides defaultMode from settings files (CLI reference). Level 10 owns the other values.

The cycle, and where the next press lands you

The order is fixed: from auto, the first press switches to default, and the cycle then runs default → acceptEdits → plan → back to default (Choose a permission mode). So the presses are countable:

That count holds for the default three-mode ring. Optional modes slot in after plan, with bypassPermissions first and auto last, so an enabled extra changes where you land coming out of plan mode, not how you get in. None of it needs memorising: the documented instruction is to press Shift+Tab until the status bar shows ⏸ plan mode on (Best practices) — the line Lesson 1.1 introduced, now deciding something.

What still runs while you are planning

The per-mode table gives plan mode one line — "Reads, plus classifier-approved commands when auto mode is available" (Choose a permission mode):

The conditional depends on the session, not on plan mode:

When auto mode is available and the useAutoModeDuringPlan setting is on, which it is by default, the classifier reviews shell commands during planning instead of prompting you. Approved commands run, and rejected ones are blocked. Otherwise, commands outside the built-in read-only set prompt for approval, including when the sandbox's auto-allow mode is enabled. — Choose a permission mode

Read the last clause of that quotation twice, because it names a hole that used to be open. Sandboxing's auto-allow mode runs a sandboxable command without asking you anywhere else; inside plan mode it stopped widening approvals at v2.1.212 — "Before v2.1.212, auto-allow ran sandboxed commands without a prompt in plan mode too" (Sandboxing). So the prompting branch is now genuinely a prompting branch: turning the sandbox up no longer quietly turns planning's gate down. The branch itself has moved too — in v2.1.212 through v2.1.217, sessions without bypass permissions prompted for every command outside the read-only set, whether or not auto mode was available.

Which branch you are on is a property of your model, your provider, your organization's settings and useAutoModeDuringPlan — not of your plan, since auto mode is documented as available on all plans, and not of the mode you just entered. The provider term used to be heavier than the current docs make it look: in v2.1.158 through v2.1.206, auto mode on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry and Claude apps gateway sessions required setting CLAUDE_CODE_ENABLE_AUTO_MODE=1, and v2.1.207 removed the requirement (Auto mode configuration). The variable is still accepted and now does nothing. What still bites on those same providers is the model: only Claude Sonnet 5, Opus 4.7 or later and the Fable models support auto mode there at all, so the wrong model puts you on the prompting branch whatever your settings say. So do not learn "in plan mode I get prompts" or "commands just run"; learn that an exploratory command is constrained somehow — by a classifier or by you — and read your session to see which. No branch touches the edit.

Leaving without approving

"Press Shift+Tab again to leave plan mode without approving a plan" (Choose a permission mode). There are two exits, and they are not interchangeable:

The second is the underused move. Plan mode is a fine way to ask a question you do not want acted on: read the answer, cycle out. Nothing obliges a planning session to end in an implementation, and getting back in costs a keypress. Lesson 4.4 argues the harder version — some tasks should never be planned.

Making it the project default

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

That goes in .claude/settings.json. Terminal sessions honour a project defaultMode for every value except auto and bypassPermissions, and plan is neither. The bypassPermissions half of that exception is recent, and worth knowing about because of what it used to allow: before v2.1.257, "bypassPermissions took effect from any file" (Settings reference), so a checked-in project settings file could start your session with bypass permissions available and hand the last section of this lesson to a value somebody else committed. That route is closed; user, --settings and managed files still open it. One surface ignores the project file entirely: "Conversations the VS Code extension starts don't read project settings for the starting permission mode" (Choose a permission mode). The fix there is per-person — set claudeCode.initialPermissionMode to plan in VS Code user settings. So "we always plan first" is enforceable from the repo for everyone except the extension's users, who set it once themselves.

The one session where plan mode does not hold

In sessions with bypass permissions available, Claude Code also doesn't enforce plan mode's blocks. Claude is still instructed to plan without editing, but a file edit or shell command it attempts during planning runs without prompting. — Choose a permission mode

Note the shape of that failure. Claude is still told to plan without editing, so a well-behaved session looks identical: it explores, it proposes, you approve. The mode has become an instruction to the model rather than a gate in the harness, and the difference shows only on the run where the model does the wrong thing — the run the gate existed for. (Explicit ask rules and rm/rmdir aimed at a critical path still prompt.) Nor is this exotic: the CLI reference describes --allow-dangerously-skip-permissions as adding bypassPermissions to the Shift+Tab cycle without starting in it, and gives this as the example:

claude --permission-mode plan --allow-dangerously-skip-permissions

Start in plan, switch to bypass later. It reads like caution followed by convenience. It is a session in which the caution half is advisory.

What you have

Plan mode is not a sandbox, not a review of the plan's content, and where bypass permissions are available not a gate at all. What it gates is source edits, and the plan it produces is still a document somebody has to read — the next lesson, and where most of planning's value lives.