[FEATURE REQUEST] Plan Mode: Add "Delegate to Background Agent" option at ExitPlanMode

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Plan execution blocks the main agent, forcing users to choose between productivity and context.

When a user exits plan mode via ExitPlanMode, the current dialog offers:

  1. Yes, clear context and auto-accept edits (shift+tab)
  2. Yes, auto-accept edits
  3. Yes, manually approve edits
  4. [Type here to tell Claude what to change]

All three "yes" options share the same fundamental limitation: the main agent becomes the executor. Whether it clears context or not, whether it auto-accepts or requires manual approval — the main agent is occupied executing the plan. The user cannot interact with Claude until execution finishes.

This creates a forced trade-off:

1. Wait idly while Claude implements a 20-file refactor (10+ minutes)
2. Open a second terminal (losing shared context, plan history, conversation thread)
3. Defer the plan and manually come back later (no first-class support — see #26520)

The plan is already written to disk as a markdown file. The conversation context that produced it — the investigation, design decisions, user constraints — lives in the main agent's context window. Once execution starts, that context is either cleared (option 1) or consumed by implementation work (options 2-3).

The gap: Claude Code has background agents (Agent tool with run_in_background: true), plan files on disk, and TaskOutput for monitoring — but no way to connect them at plan approval time.

Proposed Solution

Add a new option to the ExitPlanMode dialog: "Yes, delegate to background agent."

When selected:

1. Spawns a background subagent via existing Agent tool with run_in_background: true
2. Passes the plan file path as the primary instruction
3. Returns control to the main agent immediately
4. User monitors progress via TaskOutput or TUI status indicator

Proposed Dialog

  1. Yes, clear context and auto-accept edits (shift+tab)
  2. Yes, auto-accept edits
  3. Yes, manually approve edits
  4. Yes, delegate to background agent              (ctrl+b)
  5. [Type here to tell Claude what to change]

ctrl+b is consistent with the existing "background this" shortcut.

What the Background Agent Receives

You are executing a plan. Read the plan file at:
  {plansDirectory}/{planFileName}

Execute every step in order. For each step:
1. Read the relevant files referenced in the plan
2. Implement the change described
3. Verify the change works (run tests if specified)

If you encounter an error or ambiguity, document it in the plan file
under a "## Execution Notes" section and continue with the next step.

The subagent inherits project .claude/CLAUDE.md instructions, MCP server connections, and the session's permission mode.

UX Flow: Before vs After

Current (Blocking)

[Plan mode: investigation + planning]
          |
[ExitPlanMode → user approves]
          |
[Main agent executes: 15 min]  ← USER BLOCKED
          |
[Done — user can interact again]

Proposed (Background Delegation)

[Plan mode: investigation + planning]
          |
[ExitPlanMode → "delegate to background agent"]
          |
+--→ [Background agent executes plan autonomously]
|         |
v         | (parallel)
[Main agent available immediately]
|         |
User: "While that runs, explain        |
       OAuth2 PKCE flow to me"         |
|                                       |
User: "Now plan the email service"     |
|                              [bg agent finishes]
|                                       |
[Notification: "Plan execution complete"]
|
User: "Show me what changed"
Claude: [reviews via TaskOutput]

Technical Implementation (High-Level)

This connects three existing primitives:

| Primitive | Current State | Role in This Feature |
|-----------|--------------|---------------------|
| Plan files | Written to plansDirectory during plan mode | Handoff document to background agent |
| Agent tool | Supports run_in_background: true | Spawns the background executor |
| TaskOutput | Monitors background agent results | User checks execution progress |

The change is localized to the ExitPlanMode handler:

1. Add option to the dialog
2. On selection, call Agent tool internally with run_in_background: true + plan file reference
3. Return control — main agent gets a tool result confirming delegation
4. Optional TUI indicator showing active background plan executions

Permission Model

Configurable via settings.json:

| Setting | Behavior |
|---------|----------|
| "inherit" (default) | Background agent uses same permission mode as session |
| "auto-accept" | Background agent auto-accepts all edits |
| "manual" | Background agent queues permission requests for user |

{
  "planMode": {
    "backgroundAgentPermissions": "inherit",
    "showBackgroundOption": true,
    "defaultToBackground": false
  }
}

Edge Cases

Background agent fails mid-execution:

• Plan file on disk remains intact
• User can re-delegate or execute remaining steps inline
• Partial progress visible via git diff

Concurrent file edits (user + background agent):

• Start with advisory warnings: "Background agent will modify src/auth/*.ts"
• Future: worktree isolation via EnterWorktree for clean separation

Plan references conversation context:

• Good plans are self-contained. This forces plan quality improvement.
• Background agent prompt can include brief context summary
• CLAUDE.md and project instructions are already available

Cancellation:

• Existing mechanisms: TaskOutput to check status, process termination, /tasks command

Related Issues — Community Demand

| Issue | Title | Reactions | Relevance |
|-------|-------|-----------|-----------|
| #18599 | Change Default Plan Mode Exit Option | 26 :+1: | Context loss at plan exit is #1 complaint |
| #12876 | Add "implement using subagents" option after plan generation | 2 :+1: | Directly requests this feature — author writes "I write 'Implement using subagents' in 75% of sessions" |
| #5236 | Asynchronous Task Tool Execution | 17 :+1: | Async execution for subagents |
| #9905 | Background Agent Execution | closed | Detailed API proposal for background agents |
| #7069 | Native Background Task Management | 6 :+1: | Task lifecycle for background work |
| #26148 | Convert plan to task on ExitPlanMode | open | Plans as trackable tasks |
| #26520 | ExitPlanMode lacks defer/abandon option | open | Users want more exit options |
| #25690 | Auto-select ExitPlanMode option via settings | open | Configurable exit behavior |
| #30438 | Rework Plan Mode into 1st-Class Plan System | open | Comprehensive plan system — background delegation is one execution mode |
| #29445 | Plan Manager — named, persistent plans | open | Plan lifecycle management |

Why This is the Right Scope

The comprehensive proposals (#30438, #29445) are ambitious long-term visions requiring new infrastructure. This proposal is the minimal viable version:

• One new option in an existing dialog
• One call to an existing tool
• One existing monitoring mechanism
• Zero new tools, zero new data structures

It is backward compatible, incrementally adoptable, forward compatible with future plan systems, and implementable today.

Priority

High — Significant productivity impact

Feature Category

Interactive mode (TUI), Core agent architecture