How Claude Code Plan Mode Works

Reverse Engineering

6 a @64xt9sqpfb · · 109 views · 9 min read
#claude #reversal

Plan Mode & Plan Sub-Agent Architecture

Complete reverse engineering of Claude Code's planning systems.

Two Different "Plan" Concepts

Claude Code has two distinct planning mechanisms:

Concept Type Description
Plan Mode Behavioral state Main agent enters read-only exploration phase
Plan Sub-Agent Separate agent Specialized agent for designing implementation plans

Key Discovery

Plan mode is NOT a sub-agent - it's a behavioral state of the main agent controlled entirely through a tool_result message containing detailed workflow instructions.

Plan sub-agent IS a real sub-agent - spawned via the Task tool with subagent_type: "Plan".

How Plan Mode Works

┌─────────────────────────────────────────────────────────────┐
│ User: "Enter plan mode and design authentication"          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Main Agent (Opus) calls EnterPlanMode tool                  │
│ EnterPlanMode has NO parameters - just a state trigger      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Tool Result injected with:                                  │
│   1. Plan mode instructions                                 │
│   2. <system-reminder> with 5-phase workflow                │
│   3. Plan file path assignment                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Agent continues with SAME tools, SAME system prompt         │
│ But now follows plan mode behavior from tool_result         │
└─────────────────────────────────────────────────────────────┘

EnterPlanMode Tool

Schema

{
  "name": "EnterPlanMode",
  "description": "Transitions into plan mode for designing implementation approaches...",
  "input_schema": {
    "type": "object",
    "properties": {},
    "additionalProperties": {}
  }
}

No parameters - just a trigger to enter plan mode.

Tool Result

The tool_result contains detailed instructions:

Entered plan mode. You should now focus on exploring the codebase
and designing an implementation approach.

In plan mode, you should:
1. Thoroughly explore the codebase to understand existing patterns
2. Identify similar features and architectural approaches
3. Consider multiple approaches and their trade-offs
4. Use AskUserQuestion if you need to clarify the approach
5. Design a concrete implementation strategy
6. When ready, use ExitPlanMode to present your plan for approval

Remember: DO NOT write or edit any files yet. This is a read-only
exploration and planning phase.

<system-reminder>
Plan mode is active. The user indicated that they do not want you
to execute yet -- you MUST NOT make any edits...
</system-reminder>

The 5-Phase Workflow

The <system-reminder> in the tool_result defines a structured workflow:

Phase 1: Initial Understanding

Goal: Understand the user's request by exploring code and asking questions.

Launch up to 3 Explore agents IN PARALLEL:
- Use 1 agent for isolated tasks with known files
- Use multiple agents when scope is uncertain
- Quality over quantity - 3 agents maximum

Phase 2: Design

Goal: Design an implementation approach.

Launch Plan agent(s) to design based on Phase 1 results.
- Default: At least 1 Plan agent for most tasks
- Skip agents: Only for trivial tasks (typo fixes, single-line)
- Multiple agents: Up to 3 for complex tasks

Phase 3: Review

Goal: Review plans and ensure alignment with user intent.

1. Read critical files identified by agents
2. Ensure plans align with original request
3. Use AskUserQuestion to clarify remaining questions

Phase 4: Final Plan

Goal: Write final plan to the plan file.

- Include only recommended approach, not alternatives
- Be concise but detailed enough to execute
- Include paths of critical files
- Include verification section (how to test)

Phase 5: ExitPlanMode

Goal: Signal completion of planning phase.

Turn should only end with:
- AskUserQuestion (for clarification), OR
- ExitPlanMode (plan is ready)

NEVER ask about plan approval via text - use ExitPlanMode instead.

Plan File System

Location

Plans are stored in: ~/.claude/plans/

Naming Convention

Auto-generated: <adjective>-<verb>ing-<noun>.md

Examples:

  • jolly-dreaming-eich.md
  • witty-stargazing-volcano.md
  • quizzical-conjuring-whistle.md

Contents

# Authentication Implementation Plan

## Project Context
[What kind of project this is]

## Clarification Needed
[Options for user to choose from]

## Recommended Approach
[Detailed implementation plan]

## Critical Files
[List of files to modify]

## Verification
[How to test the changes]

What Doesn't Change

After calling EnterPlanMode:

Aspect Before After
Model Opus Opus (same)
Tool count 30 30 (same)
System prompt 12,794 chars 12,794 chars (same)
Edit tool Available Available
Write tool Available Available
Bash tool Available Available

The only change is the tool_result message with behavioral instructions.

Read-Only Enforcement

Plan mode's read-only restriction is enforced by:

  1. Prompt instructions in tool_result: "DO NOT write or edit any files"
  2. Exception for plan file: "the only file you are allowed to edit"
  3. Social contract: Agent is trusted to follow instructions

No technical enforcement - agent could technically edit files.

Observed Flow (Captured)

Req# | Model | Action
-----|-------|--------------------------------
  2  | Opus  | EnterPlanMode called
 15  | Opus  | Task (Explore) - spawns sub-agent
17-31| Haiku | Explore sub-agent runs (15 requests)
 33  | Opus  | AskUserQuestion - needs clarification
35-36| Opus  | More AskUserQuestion calls
 38  | Opus  | Write plan file
 40  | Opus  | Final response

Sub-Agent Spawning in Plan Mode

Plan mode encourages spawning sub-agents:

Explore Agents (Phase 1)

{
  "subagent_type": "Explore",
  "prompt": "Explore this codebase to understand...",
  "description": "Explore codebase structure and auth patterns"
}

Plan Agents (Phase 2)

{
  "subagent_type": "Plan",
  "prompt": "Design an implementation approach for...",
  "description": "Design authentication implementation"
}

Note: We didn't capture a Plan sub-agent in our traces - the main agent asked clarifying questions before reaching Phase 2.

ExitPlanMode Tool

Schema

{
  "name": "ExitPlanMode",
  "input_schema": {
    "properties": {
      "allowedPrompts": {
        "description": "Prompt-based permissions needed to implement the plan",
        "items": {
          "properties": {
            "tool": { "enum": ["Bash"] },
            "prompt": { "description": "Semantic description of the action" }
          }
        }
      },
      "pushToRemote": { "description": "Whether to push the plan to a remote Claude.ai session" },
      "remoteSessionId": { "description": "The remote session ID if pushed" },
      "remoteSessionUrl": { "description": "The remote session URL if pushed" }
    }
  }
}

Example

{
  "allowedPrompts": [
    { "tool": "Bash", "prompt": "run tests" },
    { "tool": "Bash", "prompt": "install dependencies" }
  ]
}

These pre-approve specific Bash commands for the implementation phase.

Comparison: Plan Mode vs Explore Sub-Agent

Aspect Plan Mode Explore Sub-Agent
Type Behavioral state Separate agent
Model Same (Opus) Different (Haiku)
System prompt Same Different (specialized)
Tool access Full (30 tools) Restricted (21 tools)
Can edit files Technically yes Technically no
Enforcement Prompt-based Tool removal
Duration Until ExitPlanMode Until task completes

Remote Session Push

ExitPlanMode supports pushing plans to Claude.ai:

{
  "pushToRemote": true,
  "remoteSessionId": "abc123",
  "remoteSessionUrl": "https://claude.ai/chat/abc123",
  "remoteSessionTitle": "Authentication Implementation"
}

This likely enables handoff between Claude Code and Claude.ai web interface.

Plan Sub-Agent (Separate from Plan Mode)

Overview

The Plan sub-agent is a separate specialized agent spawned via the Task tool. It is distinct from "Plan mode" (the behavioral state).

{
  "name": "Task",
  "input": {
    "subagent_type": "Plan",
    "prompt": "Design an implementation approach for authentication...",
    "description": "Design authentication implementation"
  }
}

Description (from Task tool)

Plan: Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.

Tool Access

The Plan sub-agent has restricted tools:

Tools: All tools except Task, ExitPlanMode, Edit, Write, NotebookEdit

Available Tools

  • Bash (read-only implied)
  • Glob
  • Grep
  • Read
  • WebFetch
  • WebSearch
  • TodoWrite
  • Skill
  • MCP tools

Explicitly Excluded

Tool Why
Task No sub-sub-agents
ExitPlanMode Not in planning workflow
Edit Read-only exploration
Write Read-only exploration
NotebookEdit Read-only exploration

Plan Sub-Agent vs Explore Sub-Agent

Aspect Plan Sub-Agent Explore Sub-Agent
Purpose Design implementation strategy Find files and understand codebase
Focus Architecture, trade-offs File patterns, code search
Output Step-by-step plans File paths, code snippets
Tools Same restrictions Same restrictions
Model Likely Haiku Haiku

When to Use

The Task tool documentation suggests:

Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.

Typically spawned during Phase 2 of Plan mode workflow.

Comparison: All Three Planning Concepts

Concept Type Model Can Edit Purpose
Plan Mode State Opus (same) Technically yes Orchestrate planning workflow
Plan Sub-Agent Agent Haiku No Design implementation strategy
Explore Sub-Agent Agent Haiku No Find and understand code

Key Insights

  1. No technical sandbox - Plan mode relies entirely on prompt instructions
  2. Same capabilities - Agent keeps all tools, just instructed not to use them
  3. Workflow injection - 5-phase workflow injected via tool_result
  4. Plan file exception - Only file allowed to edit is the plan file
  5. Sub-agent orchestration - Plan mode encourages parallel Explore/Plan agents
  6. Remote handoff - Plans can be pushed to Claude.ai web sessions
  7. Two planning systems - Plan mode (state) vs Plan sub-agent (separate agent)

Reverse engineered from captured API traffic. See experiments/captures-planning/ for raw data.

More from a