Claude Code plan mode: what it really enforces

Plan mode separates exploration from execution: Claude Code reads files and drafts an implementation plan but makes no edits until you approve it. Turn it on with Shift+Tab mid-session or claude --permission-mode plan at startup. Anthropic’s recommended loop is explore → plan → implement → commit. But the read-only promise has edges: Claude Code (the harness - the program that runs the agent and executes its tool calls) blocks the edit tools, while shell commands keep running during planning, and the planning instructions themselves are a short injected prompt.

Definitions

Plan mode - a Claude Code permission mode in which the agent reads, searches, and plans but makes no edits to your codebase until you approve the plan.

Permission mode - the harness setting that governs which actions Claude may take without asking. Plan mode is one; the default (ask-per-write) and auto (a classifier gates writes) are others.

Enable it

In plan mode Claude reads files and proposes a plan but touches nothing on disk. When the plan is drafted, Ctrl+G opens it in your $EDITOR for direct editing before you approve - so you correct the spec, not the diff.

The workflow: explore → plan → implement → commit

Letting Claude jump straight to code risks solving the wrong problem. Anthropic’s recommended four phases separate research from execution:

1 - Explore (plan mode). Point Claude at the relevant code and let it read.

read src/auth and explain how we handle sessions and login.
also check how we load secrets from env.

2 - Plan (plan mode). Ask for a concrete implementation plan, then edit it with Ctrl+G.

I want to add Google OAuth. What files change? What's the session
flow? Write a plan.

3 - Implement (default mode). Exit plan mode and let Claude code against the plan.

implement the OAuth flow from your plan. write tests for the callback
handler, run the suite, and fix any failures.

4 - Commit (default mode).

commit with a descriptive message and open a PR.

Separating the read-heavy explore phase from implementation is the same discipline as delegating research to a subagent: keep exploration out of the window that does the work. For how those reads accumulate in the first place, see how Claude Code’s agentic loop fills your context window.

When to use it - and when to skip

The rule of thumb: if you could describe the diff in one sentence, skip the plan. The garden rule Plan mode decision tree is that table in one place.

Plan mode is useful but adds overhead. Spend it where the uncertainty is highest, not on one-line diffs.

What the harness actually enforces

Plan mode feels hard-locked to read-only. Today that is half true. Anthropic’s permission modes docs say Claude Code blocks edits until you approve a plan, and the block sits in the permission layer - v2.1.136 (2026-05-08) fixed a hole where a matching Edit(...) allow rule let writes through. Two gaps remain. Shell commands still run while planning: with auto mode available a classifier approves them, and without it anything outside the built-in read-only set prompts you. And in interactive terminal sessions with bypass permissions available, neither the classifier nor a prompt applies to planning commands.

The instruction layer is still a prompt. Armin Ronacher’s reverse-engineering of the harness (2025-12-17) found that plan mode is, in his words, “just a rather short predefined prompt that enters plan mode” - “prompt reinforcement that changes the behavior of the tools and also which tools are available.” The agent still edits one file while “read-only”: the plan itself.

The injected prompt does not hedge. It tells the model it “MUST NOT make any edits, run any non-readonly tools … or otherwise make any changes to the system,” and that this “supercedes any other instructions you have received.” Strong wording is still only wording. A March 2026 write-up demonstrated the gap concretely by getting Claude to modify a .zshrc while plan mode was active - the kind of write a shell command makes without ever touching the edit tool. Their summary is the line worth keeping: writing MUST NOT in all caps is not a load-bearing security boundary.

• The plan is a file. It lives as markdown in ~/.claude/plans by default (the plansDirectory setting moves it). While planning, the agent edits exactly that file and nothing else in your tree.
• The injected prompt has its own four phases - distinct from the user-facing workflow above: Initial Understanding (read code, ask clarifying questions) → Design (draft approaches with context) → Review (check alignment with the original intent) → Final Plan (concise, executable steps with the critical file paths).
• Exit reads the plan back. Approving the plan makes the harness read the plan file from disk and start executing against it. Exiting plan mode this way only makes sense for code-implementation tasks - if you were just exploring, there’s nothing to execute against, so the exit step has nothing to do.

The practical takeaway: plan mode blocks Claude’s edit tools, not the shell, and it is not a sandbox. If you need a hard guarantee that nothing is written - an untrusted repo, a destructive tool - reach for OS-level sandboxing or permission rules, not plan mode alone.

Make it actually read-only

A PreToolUse hook makes the edit block hold in every session, including ones with bypass permissions available: deny Write and Edit whenever the session’s permission mode is plan, with one exception for the plan file itself. For shell writes, pair it with the sandbox. See PreToolUse read-only hook.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|NotebookEdit",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/block-plan-writes.sh" }]
      }
    ]
  }
}

The script reads the hook payload on stdin and exits with code 2 (blocking the call - exit code 1 is a non-blocking error) when permission_mode is plan and the target path is outside ~/.claude/plans/. This costs nothing in capability: the agent never legitimately writes anywhere else while planning, which is exactly why the exception list is one directory long. Anything stronger than a hook - an untrusted repo, an unattended run - is the sandbox ladder, where the boundary is enforced by the kernel rather than by the harness.

Plan mode vs a DIY markdown handoff

Because the plan is just a markdown file, Ronacher argues you can approximate it without switching modes: iterate on a visible markdown file on disk, asking Claude clarifying questions until the plan is solid.

The one thing the DIY route can’t cheaply replicate is the built-in approval UI on exit. Everything else - the plan, the phased prompt - is reproducible with a file and a good prompt.

Bottom line

Use plan mode to force a read-only explore-and-plan pass before Claude touches code; it’s the cheapest way to avoid building the wrong thing. Just know the block covers the edit tools, not the shell, and the plan is only a markdown file. Plan mode is one lever in the bigger discipline of controlling what enters the window during that explore pass - context engineering, which beats a bigger window. For daily keyboard shortcuts and in-session slash commands, see Claude Code commands cheatsheet.