[FEATURE] Promote a subagent to a session and demote back — reclaim context + intervene in orchestrated subagents

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet (nearest is #40694, a different, declined scenario; and #24798 / #79870, which are about messaging between sessions, not promoting/demoting a subagent).
• [x] This is a single feature request (one primitive — bidirectional subagent⇄session — with two motivating use cases).

Problem Statement

The boundary between a subagent (spawned via the Agent/Task tool — Explore, general-purpose, custom types) and a top-level session is one-way and opaque, which creates two pain points:

1. A subagent's accumulated context is stranded and often wasted. A subagent can build a large, expensive context (reading files, tickets, docs; running searches) and then end. Its transcript is stored under the parent session (…/subagents/agent-<id>.jsonl) and is not independently resumable, and there is no way to promote it into a full, user-driveable session. (Confirmed: subagents resume only within their parent via SendMessage; Explore/Plan are one-shot; no promote/fork-to-standalone-session exists.) Concrete cost: a context-blind readiness subagent consumed ~67.5k tokens building an understanding of a repo's roadmap + tickets, then ended — and the only way to act on that understanding was to start a fresh session and re-read everything.

2. You cannot intervene in a live subagent an orchestrator is managing. When a top-level agent is orchestrating subagents, a human who wants to spot-check or course-correct one has no direct channel — you only see a subagent's transcript through the orchestrator's mediation, and any direction must be relayed through the top agent. You can't take over a running subagent directly, give it direction, watch its transcript natively in the terminal, and then hand it back to the orchestrator to keep managing. This friction discourages delegating more work to subagents — precisely because you can't reach in when you need to.

Proposed Solution

Make the subagent⇄session boundary bidirectional — a promote/demote primitive:

• Promote a subagent (completed or running) into a resumable, user-driveable top-level session that inherits its context and renders its transcript natively in the terminal. Least-to-most invasive:

1. Address a subagent transcript via claude --resume <parent-id>:<agent-id> (or a /resume picker entry), seeding a new top-level session from it.
2. A /promote-subagent <agent-id> command that forks the subagent transcript into a standalone session.
3. At minimum, expose/document the transcript so users can do this themselves.

• Demote a promoted session back into a subagent under the original orchestrator, so it resumes being managed after the human's intervention.

Use case 1 (context reclamation) needs only promote-from-completed. Use case 2 (live intervention) needs the full promote-running → intervene/inspect → demote-back round-trip.

Alternative Solutions

• Start a fresh session and re-read everything — the current workaround for use case 1; it re-pays the token cost the subagent already spent (~67.5k in the example).
• Relay all direction through the orchestrating agent — the current workaround for use case 2; slow, lossy, and the human never sees the subagent's raw transcript.
• External multiplexers (cmux — https://github.com/craigsc/cmux, tmux-style orchestrators, herdr — https://github.com/ogulcancelik/herdr) — solve cross-session coordination outside Claude Code, but can't reach into Claude's own subagent transcripts or the orchestration graph.

Priority

Medium - Would be very helpful

Feature Category

Developer tools/SDK

Use Case Example

1. My orchestrating agent spawns several subagents to work a multi-part task; I want to delegate more of this, but I like to spot-check.
2. One subagent looks like it's heading the wrong way. Today I can only nudge it by messaging the orchestrator and hoping it relays correctly.
3. With this feature: I promote that subagent to a live session, watch its transcript natively in my terminal, give it direct direction (or correct a wrong turn), then demote it back so the orchestrator keeps managing it.
4. Separately, a readiness/research subagent finishes with a rich, expensive context. Instead of discarding it and starting fresh, I promote its completed run into a session and continue from where it left off — reclaiming the ~67.5k tokens it already spent.

Additional Context

• Technical feasibility: both a session and a subagent run are jsonl transcripts, so a naive promotion (copy …/subagents/agent-<id>.jsonl and instantiate it as a top-level session) looks plausible as a starting point.
• Distinct from #40694 ("Promote existing sessions to Agent Team teammates w/ preserved context", closed NOT_PLANNED) — that was session→teammate connection for live coordination; this is the subagent⇄session transition itself (context reclamation + human takeover/handback of a managed subagent), which wasn't argued there.
• Related but distinct from #24798 / #79870 (inter-session / cross-session messaging) — this is about promoting/demoting a subagent to/from a session, not messaging between existing sessions.