[FEATURE] Two-phase slash command — context-aware planning subagent feeding a clean-context async execution subagent, off the main agent's critical path

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

<h3 data-pm-slice="0 0 []">Use case</h3><p>I work in one main session juggling multiple tasks. My current workflow is to <strong>throw several tasks at the main agent and have it delegate subagents</strong>. For example, while the main agent works on task A (refactoring a module), I also want it to delegate task B (adding tests) and task C (researching a dependency alternative).</p><h3>Current pain points</h3><p><strong>1. Main-agent delegation is serial and halts its current work.</strong></p><p>Every delegation requires a full model decision cycle: generate a <code dir="ltr">tool_use</code> → wait for the subagent to start → receive the <code dir="ltr">tool_result</code> (or background notification) → return to task A. Delegating B and delegating C are themselves actions <strong>inserted into task A's execution stream, executed serially</strong>. The main agent must stop to handle "delegation" before it can continue A.</p><p><strong>2. Every delegation carries communication/transfer cost and pollutes the main agent's context.</strong></p><p>To delegate, the main agent must, within its own context, generate the task description, decide who to delegate to, and construct the prompt. These intermediate artifacts <strong>all remain in the main agent's context</strong> — the planning for delegating B, the planning for delegating C, mixed with task A's work. The context window gets diluted with this "managerial" content, task A's coherence is broken, and the main agent's attention is repeatedly pulled away.</p><p><strong>3. There is no mechanism to "launch directly, bypassing the main agent."</strong></p><p>What I want: I type a command in the main session, and the task launches in the background — the main agent is <strong>unaware, uninvolved, uninterrupted</strong>. It keeps working on task A; the command's parsing and delegation are handled directly by the runtime. This requires:</p><ul data-spread="false"><li><p>No <code dir="ltr">tool_use</code> emitted in the main agent's loop (otherwise the main agent is interrupted);</p></li><li><p>The command must understand my task based on the current context (otherwise I must hand-write all the background);</p></li><li><p>Execution must use a clean context (otherwise every command re-sends the full history — token waste);</p></li><li><p>Async execution with a single result injected back (otherwise the main agent waits).</p></li></ul><p>No existing mechanism satisfies all four (see table below).</p><h3>Why this matters</h3><p>It moves <strong>delegation off the main agent's critical path entirely</strong>.</p><p>Today delegation is the <strong>main agent's job</strong>: it stops, thinks, emits a <code dir="ltr">tool_use</code>, waits. I want delegation to become the <strong>runtime's job</strong>: the user types a command, the runtime forks, distills, executes, and injects the result — the main agent's turn is never interrupted.</p><p>Direct benefits:</p><ul data-spread="false"><li><p><strong>Main agent stays uninterrupted</strong>: it stays focused on task A; multiple delegations are no longer serially inserted into its execution stream.</p></li><li><p><strong>Main agent context stays clean</strong>: delegation planning, prompt construction, and subagent intermediate steps never enter the main agent's context window. Only its own task content and <strong>one result message per completed task</strong> remain.</p></li><li><p><strong>Token efficiency</strong>: execution uses a clean context, not the full history. For self-contained tasks, this is an order of magnitude cheaper than a full-context fork like <code dir="ltr">/subtask</code>.</p></li><li><p><strong>Parallel, not serial</strong>: multiple <code dir="ltr">/agent</code> commands can be issued back-to-back, each running in the background, blocking neither each other nor the main agent.</p></li></ul><h3>How the mechanism fails to cover this today</h3>

Mechanism | Inherits context | Tools / executes | Interrupts main agent | Token-efficient | Gap
-- | -- | -- | -- | -- | --
/btw | ✅ | ❌ no tools, single-turn | no | — | can only analyze, not execute
/btw fork (f) | ✅ | ✅ | no | ❌ full history | execution also inherits full history
/subtask | ✅ | ✅ | no | ❌ full history | cannot switch to clean context
clean-context subagent | ❌ | ✅ | no | ✅ | can't see context; briefing must be hand-written
main agent → Agent tool | — | ✅ | yes | ✅ | tool_use pause, serial, pollutes main context
desired /agent | Phase 1 inherits, Phase 2 clean | Phase 1 scoped, Phase 2 full | no | Phase 2 clean = cheap | does not exist

Proposed Solution

A single slash command (name TBD — /agent, /delegate, /isolated) that runs a two-phase, two-context operation atomically, without emitting a tool_use in the main agent's loop:

/agent <short task description>

Phase 1 — Planning / distillation:
  Fork a planning subagent that inherits the current conversation.
  Tool policy: read-only by default (Read, Grep, Glob, read-only Bash
  such as git status / git diff / ls).
  Optional limited write: may persist the briefing to a scratch path
  (e.g. .claude/tasks/<id>.md), but must not modify source code or run
  builds/installs/commits.
  Output: a self-contained, detailed briefing (goals, constraints,
  relevant files, acceptance criteria, suggested steps, risks).

Phase 2 — Execution:
  Spawn a background subagent with a CLEAN context (no inherited
  history, no inherited file reads) and full tools.
  Input: only the briefing from Phase 1.
  Async; intermediate steps never return to the main conversation.
  On completion: inject a single result message into the main conversation.

Neither phase emits a tool_use in the main agent's loop.
The main agent's current turn is not paused.

Open questions:

• Should Phase 1 inherit full history, or a summarized view to reduce cost?
• Should Phase 2 be allowed a bounded follow-up question back to Phase 1 if the briefing is insufficient?
• Should there be a --full-context escape hatch falling back to current /subtask behavior?
• Naming: /agent may collide conceptually with the Agent tool; /delegate or /isolated may be clearer.

Alternative Solutions

I've considered and tried several workarounds:

1. Using the main agent to delegate (Agent tool): This is my current primary workflow, but it's exactly the problem. The main agent has to stop its current task, generate a tool_use, construct the prompt, and wait. Delegating multiple tasks is serial and breaks the main agent's flow and context window.

1. Full-context fork commands (/subtask, /btw with f): These avoid interrupting the main agent, but they fork the entire conversation. Every request re-sends the full history, which is incredibly token-inefficient for self-contained tasks (I've seen forks consume 100k+ tokens for tasks that need 2k).

1. Multiple terminal windows / separate Claude sessions: I currently open a second terminal and start a fresh Claude Code session. I manually copy-paste relevant context and write a detailed prompt. This works but is highly manual, error-prone, and loses the automatic context awareness.

1. Manually writing a clean-context prompt: I ask the main agent to output a briefing, copy that briefing, and manually start a clean subagent. This costs a main-agent tool_use pause and manual copying.

Other tools (e.g., Cursor, custom scripts with Claude API) solve this by allowing a "plan then execute" handoff across different context windows, but none integrate seamlessly into the Claude Code main session without requiring the main agent to orchestrate it.

None of these achieve all of: (1) not interrupting the main agent, (2) automatic context-aware planning, (3) clean-context execution to save tokens, and (4) async execution with a single result injected back.

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

Example scenario:

1. I'm in a long main session where the main agent is refactoring the authentication module (task A). It's a multi-step task that requires sustained focus.

1. I realize I also need two independent tasks done:

• Task B: Update the React login form to use the new /auth/login endpoint.
• Task C: Write integration tests for the new auth API covering edge cases.

Both are self-contained, but they depend on decisions already made in this session (e.g., new endpoint paths, payload shapes, error handling conventions).

1. With this feature, I would type:

/agent Update React login form to use new /auth/login endpoint
/agent Write integration tests for auth API covering edge cases

Each command would:

• Fork a planning subagent that inherits the current conversation, uses read-only tools to verify file paths and current code, and distills a self-contained briefing (endpoint paths, payload shapes, error codes, test framework).
• Launch a background execution subagent with a clean context (no inherited history), receiving only that briefing. It performs the actual code edits and test writing.
• Return only a single result message when done.

1. Meanwhile, the main agent continues refactoring task A without interruption. I don't have to wait for the main agent to finish a tool_use cycle for each delegation. The main agent's context stays clean — no delegation planning, no subagent intermediate outputs mixed in.

1. This saves me time because:

• I can delegate multiple tasks in parallel without serializing them through the main agent.
• The main agent remains focused on task A, so its context window isn't diluted with managerial content.
• Execution uses clean contexts, saving tokens compared to full-context forks like /subtask.
• I don't have to manually write detailed briefings or open separate terminal sessions.

Without this feature, my options today are:

• Interrupt the main agent to delegate (it stops task A, emits a tool_use, waits).
• Use /subtask, which doesn't interrupt but re-sends the entire session history on every turn (token-inefficient).
• Manually copy context and start a new session (error-prone, loses automatic context awareness).

Additional Context

_No response_