AI Assistant

Planning Tools

Claude Code provides tools for structured planning workflows and git worktree isolation. These tools allow Claude to switch into a plan-first mode where it explores and designs before implementing, and to isolate work on separate git branches.

Plan Mode

Plan mode is a permission-restricted state where Claude focuses on exploration and design before making changes. It restricts write operations while allowing reads, searches, and analysis.

EnterPlanModeTool

Switches the session into plan mode.

(no parameters)

This tool takes no input parameters.

Behavior

  1. Records the current permission mode as prePlanMode for later restoration
  2. Updates the permission context mode to 'plan'
  3. Activates plan-mode-specific permission rules that restrict write operations
  4. Returns a confirmation message instructing the model to focus on exploration and design
"Entered plan mode. You should now focus on exploring the codebase and
designing an implementation approach."

Constraints

  • Cannot be used in agent (subagent) contexts: only the main thread can enter plan mode
  • Disabled when --channels is active (the exit dialog requires terminal access)

ExitPlanModeV2Tool

Exits plan mode, optionally requesting specific permissions for the implementation phase.

allowedPromptsAllowedPrompt[]

Prompt-based permissions needed to implement the plan. Each entry describes a category of actions rather than specific commands.

Each AllowedPrompt contains:

toolstringrequired

The tool this prompt applies to (currently only "Bash" is supported).

promptstringrequired

Semantic description of the action (e.g., "run tests", "install dependencies").

Behavior

  1. Reads the plan from disk (written during plan mode exploration)
  2. Presents the plan to the user for approval
  3. If approved, restores the previous permission mode and applies any requested prompt-based permissions
  4. For teammates in a multi-agent setup, sends a plan approval request to the team lead instead of prompting the user directly

The plan is persisted to disk at a deterministic path based on the session. The SDK-facing input schema includes plan and plan_file_path fields that are injected during input normalization, though the internal schema reads the plan from disk directly.

Plan Mode Workflow

User request
    |
    v
[EnterPlanMode] (permission mode -> 'plan')
    |
    v
Claude explores codebase (read-only operations)
    |
    v
Claude writes plan to disk
    |
    v
[ExitPlanMode] (user reviews plan)
    |
    v
Plan approved -> permission mode restored
    |
    v
Claude implements the plan

Worktree Isolation

Worktree tools provide git-based isolation for branches, allowing Claude to work on changes in a separate worktree without affecting the main working directory.

EnterWorktreeTool

Creates an isolated git worktree and switches the session into it.

namestring

Optional name for the worktree. Each /-separated segment may contain only letters, digits, dots, underscores, and dashes. Maximum 64 characters total. A random name is generated if not provided.

Behavior

  1. Validates that no worktree session is already active
  2. Resolves to the main repository root (worktree creation works from the canonical root)
  3. Creates a new git worktree with a dedicated branch using createWorktreeForSession()
  4. Changes the process working directory to the new worktree path
  5. Clears cached system prompt sections so environment info recomputes with the worktree context
  6. Clears memoized memory file caches that depend on CWD

Output

{
  worktreePath: string      // Absolute path to the new worktree
  worktreeBranch?: string   // The branch name created for the worktree
  message: string           // Confirmation message
}

ExitWorktreeTool

Exits the current worktree session and returns to the original working directory.

actionstringrequired

"keep" leaves the worktree and branch on disk. "remove" deletes both.

discard_changesboolean

Required true when action is "remove" and the worktree has uncommitted files or unmerged commits. The tool refuses and lists changes otherwise.

Safety Checks

Before removing a worktree, ExitWorktreeTool counts:

  • Changed files: via git status --porcelain
  • Unmerged commits: via git rev-list against the original HEAD commit

If either is non-zero and discard_changes is not explicitly true, the tool refuses the removal and reports the pending changes so the user can make an informed decision.

When the original HEAD commit is unavailable (e.g., hook-based worktree wrapping), the tool uses a fail-closed approach: it reports that change status cannot be determined and requires explicit discard_changes: true to proceed with removal.

Availability

Worktree tools are only available when worktree mode is enabled via isWorktreeModeEnabled(). Both tools are deferred (require ToolSearch to use).

Key Source Files

  • src/tools/EnterPlanModeTool/EnterPlanModeTool.ts: Plan mode entry
  • src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts: Plan mode exit with prompt-based permissions
  • src/tools/EnterWorktreeTool/EnterWorktreeTool.ts: Worktree creation and session switching
  • src/tools/ExitWorktreeTool/ExitWorktreeTool.ts: Worktree cleanup with safety checks
  • src/utils/worktree.ts: Git worktree creation, validation, and cleanup utilities
Agent & Task Tools PreviousCode IntelligenceNext