@ferris1225/pi-subagents 0.31.0 → 1.0.0

package/src/dispatch.ts

@@ -1,845 +1,1833 @@
-/**
- * The `subagent` tool: dispatches explore/worker/reviewer agents as isolated pi
- * child processes, single or parallel. Owns the dispatch pipeline: config load
- * + unavailable-model repair, per-run widget tracking, the auto-fix chain
- * (REVIEW_FAIL → worker → re-review), and completion delivery.
- *
- * Vision: a task flagged `vision: true` runs on the configured vision-capable
- * model (config.visionModel); when none is configured it falls back to the main
- * session's current model. If the configured vision model is no longer
- * available, the user is asked (TUI picker) to pick a replacement, which is
- * persisted; outside the TUI it degrades to the main-session model with a
- * warning.
- */
-
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { rm } from "node:fs/promises";
-import { Text } from "@earendil-works/pi-tui";
-import { Type } from "typebox";
-import { discoverAgents, type AgentConfig } from "./agents.ts";
-import {
-	completionTriggersTurn,
-	type CompletionMessageItem,
-} from "./completion.ts";
-import { loadConfig, saveConfig, type SubagentsConfig } from "./config.ts";
-import {
-	dispatchFailedResult,
-	failedStartResult,
-	formatCompletionBlock,
-	formatUsage,
-	modelLevelTakeoverNote,
-	queuedResult,
-} from "./format.ts";
-import {
-	buildFixTaskBrief,
-	buildReReviewBrief,
-	formatChainSummary,
-	shouldTriggerFixLoop,
-	summarizeChainResult,
-	type ChainStep,
-} from "./fixloop.ts";
-import { availableModelRefs, repairUnavailableModelOverrides, resolveVisionModelRef } from "./models.ts";
-import {
-	formatTaskSummary,
-	formatToolActivity,
-	monitor,
-	statusIcon,
-	type RunChainMeta,
-} from "./monitor.ts";
-import type { SubagentRuntime } from "./runtime.ts";
-import {
-	buildFallbackResumeReason,
-	buildResumePrompt,
-	getResultOutput,
-	isFailedResult,
-	isModelLevelFailure,
-	reviewVerdict,
-	runSingleAgentWithModelFallback,
-	type SingleResult,
-	type SubagentDetails,
-	type SubagentLiveEvent,
-} from "./spawn.ts";
-import { promptSelectOne } from "./ui.ts";
-
-const NON_BLANK_TASK_OPTIONS = { minLength: 1, pattern: "\\S" } as const;
-
-const VISION_DESCRIPTION =
-	"Set true when the task may require viewing images (screenshots, mockups, designs) — the sub-agent then runs on the configured vision-capable model, or the main session's current model when none is configured";
-
-const TaskItem = Type.Object({
-	agent: Type.String({ description: "Name of the agent to invoke" }),
-	task: Type.String({
-		...NON_BLANK_TASK_OPTIONS,
-		description: "Self-contained task to delegate (the agent has no memory of this conversation)",
-	}),
-	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
-	vision: Type.Optional(Type.Boolean({ description: VISION_DESCRIPTION })),
-});
-
-const SubagentParams = Type.Object({
-	agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (single mode)" })),
-	task: Type.Optional(
-		Type.String({ ...NON_BLANK_TASK_OPTIONS, description: "Self-contained task to delegate (single mode)" }),
-	),
-	tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
-	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
-	vision: Type.Optional(Type.Boolean({ description: VISION_DESCRIPTION })),
-	resume: Type.Optional(
-		Type.Number({
-			description:
-				"Resume a handed-back run by its id: continue a sub-agent whose model hit a quota/auth limit, picking up its preserved context without re-scanning. Use the run id from a model-level handback message.",
-		}),
-	),
-});
-
-/** True when any dispatched task carries the vision flag. */
-function hasVisionTask(params: { vision?: boolean; tasks?: Array<{ vision?: boolean }> }): boolean {
-	return params.vision === true || (params.tasks ?? []).some((t) => t.vision === true);
-}
-
-/**
- * When the configured vision model is unavailable, ask the user to pick a
- * replacement (TUI) and persist it; outside the TUI, warn and fall back to the
- * main session's model. Returns the repaired vision model (undefined = use the
- * main-session fallback).
- */
-async function repairVisionModelForDispatch(
-	ctx: ExtensionContext,
-	config: SubagentsConfig,
-	configPath: string,
-): Promise<string | undefined> {
-	const configured = config.visionModel?.trim();
-	if (!configured) return undefined;
-	const refs = availableModelRefs(ctx);
-	if (refs.includes(configured)) return configured;
-
-	if (ctx.mode === "tui" && refs.length > 0) {
-		try {
-			const picked = await promptSelectOne(
-				ctx,
-				`Vision model "${configured}" is unavailable. Pick a replacement?`,
-				"Type to filter • ↑/↓ • Enter selects • Esc falls back to the main session's model",
-				refs.map((ref) => ({ value: ref, label: ref })),
-			);
-			if (picked !== undefined) {
-				try {
-					await saveConfig({ ...config, visionModel: picked }, configPath);
-					ctx.ui.notify(`Vision model switched to ${picked}.`, "info");
-				} catch {
-					/* persistence failure is non-fatal; the pick still applies this dispatch */
-				}
-				return picked;
-			}
-		} catch {
-			/* a failed picker must never break the dispatch */
-		}
-		ctx.ui.notify(`Vision model left as "${configured}"; this dispatch runs without the vision override.`, "warning");
-		return undefined;
-	}
-	ctx.ui.notify(
-		`Configured vision model "${configured}" is unavailable; this dispatch uses the main session's model.`,
-		"warning",
-	);
-	return undefined;
-}
-
-export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime): void {
-	pi.registerTool({
-		name: "subagent",
-		label: "Subagent",
-		description: [
-			"Delegate a discrete, self-contained task to a specialized sub-agent running in an ISOLATED context window.",
-			"Agents: explore (read-only codebase recon), worker (implement/fix/refactor/test, full tools), reviewer (adversarial pre-commit review, read-only).",
-			"Modes: single ({agent, task}) or parallel ({tasks: [{agent, task}, ...]}).",
-			"Resume: pass { resume: <runId> } to continue a run that was handed back after its model hit a quota/auth limit — it picks up the preserved context without re-scanning.",
-			"It starts agents in the background and immediately returns control to the main window; completion messages automatically wake the main agent to continue.",
-			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output).",
-			"Results arrive as wake-up messages automatically — you do NOT need to wait. If you must get a result in-turn, subagent_wait is a non-blocking lookup by default (pass timeoutMs to block).",
-			"Vision: set vision: true when the task may require viewing images (screenshots, mockups, design files — e.g. frontend work) — the sub-agent then runs on the vision-capable model configured in /subagents-setup, or the main session's current model when none is configured.",
-		].join(" "),
-		promptSnippet:
-			"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review); completion automatically resumes the main agent. Simple tasks: use direct tools, not subagents.",
-		promptGuidelines: [
-			"Delegate only when an isolated context genuinely pays: broad exploration, a self-contained implementation, or a review gate. Handle simple lookups and one-line edits inline with direct tools — never spawn a sub-agent for them.",
-			"Use subagent with agent 'explore' for broad or open-ended code search before large changes; a targeted 'where is X' is a direct grep/read.",
-			"Use subagent with agent 'worker' for a self-contained implementation task worth a separate context; it plans internally.",
-			"Use subagent with agent 'reviewer' for a fresh read-only review before reporting work done or committing.",
-			"subagent launches work in the background and ends the current turn; when a result arrives, the main agent is automatically resumed with it.",
-			"Run independent tasks in parallel by passing a tasks array to subagent; let the automatically resumed main agent start dependent work after results arrive.",
-			"NEVER sleep or poll, and do NOT call subagent_wait to hold the turn — subagent ends the turn immediately and the result arrives as a message that wakes you automatically (even mid-turn). Ending your turn is the default and the only correct way to wait.",
-			"If you must keep the turn for a result, call subagent_wait with an explicit timeoutMs (non-blocking by default) — never bash sleep/timeout to wait for a sub-agent.",
-			"When a delegated task may require viewing images (frontend screenshots, mockups, design comparisons), pass vision: true and give the sub-agent the exact image paths — it reads them with its read tool. The sub-agent then runs on the configured vision-capable model, or the main session's current model when none is configured.",
-			"When a sub-agent result arrives it is already shown to the user — do NOT restate, paraphrase, or summarize it; reply with only your own conclusion or next action (often just one line), since duplicating the result wastes tokens for nothing.",
-		],
-		parameters: SubagentParams,
-
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			monitor.beginTurn();
-			let config = await loadConfig(runtime.configPath);
-			// Pick up concurrency changes from /subagents-setup without a restart.
-			runtime.backgroundQueue.setConcurrency(config.maxConcurrency);
-			const repairedModels = repairUnavailableModelOverrides(ctx, config.agentModels);
-			if (repairedModels.changed) {
-				config = { ...config, agentModels: repairedModels.agentModels };
-				try {
-					await saveConfig(config, runtime.configPath);
-					ctx.ui.notify(
-						repairedModels.fallbackRef
-							? `Unavailable sub-agent models switched to ${repairedModels.fallbackRef} and saved to config.`
-							: "Unavailable sub-agent model overrides removed; no main-window model is available.",
-						"warning",
-					);
-				} catch (error) {
-					ctx.ui.notify(
-						`Could not persist repaired sub-agent model config: ${error instanceof Error ? error.message : String(error)}`,
-						"warning",
-					);
-				}
-			}
-
-			// Finished runs leave the widget immediately. Their final findings are sent
-			// back as a custom message that automatically starts a follow-up turn.
-			const finishRun = (
-				runId: number,
-				status: "done" | "failed",
-				opts?: { silent?: boolean; retain?: boolean },
-			): void => {
-				monitor.setStatus(runId, status); // stamps endedAt for the elapsed time
-				const run = opts?.retain ? monitor.findRun(runId) : monitor.removeRun(runId);
-				if (!run) return; // already finished — stay idempotent
-				if (opts?.retain) monitor.setRetained(runId, true);
-				if (opts?.silent || !runtime.sessionActive) return;
-				const icon = status === "done" ? "✓" : "✗";
-				ctx.ui.notify(`${icon} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
-			};
-
-			// Live sub-agent activity → concise one-line status ("thinking",
-			// "read src/index.ts", ...), never a raw args blob. The live handler only
-			// updates widget status; finishing (removeRun + notify) is owned by the
-			// queue task / launchInLoop. That keeps a startup retry — which fires a
-			// transient "failed" status before relaunching — from ripping the row out
-			// early, and lets the queue task decide between delivering a reviewer's
-			// result and starting an auto-fix chain (a triggered chain keeps the
-			// parent row annotated until it completes).
-			const makeLiveHandler = (runId: number) => (e: SubagentLiveEvent): void => {
-				switch (e.kind) {
-					case "status":
-						// Only update the widget status here. Finishing (removeRun + notify) is
-						// owned by the queue task / launchInLoop so that a startup retry — which
-						// fires a transient "failed" status before relaunching the child — never
-						// rips the row out from under the retry or emits a premature "✗" toast.
-						monitor.setStatus(runId, e.status);
-						break;
-					case "usage":
-						monitor.setUsage(runId, e.usage, e.model);
-						break;
-					case "tool_start":
-						monitor.recordToolStart(runId, e.toolName, formatToolActivity(e.toolName, e.args));
-						break;
-					case "tool_end":
-						monitor.recordToolEnd(runId, e.toolName, e.isError);
-						break;
-					case "thinking":
-						monitor.setActivity(runId, "thinking");
-						break;
-					case "text":
-						// A text delta is model output, not a filesystem write.
-						monitor.setActivity(runId, "responding");
-						break;
-				}
-			};
-			const discovery = discoverAgents(ctx.cwd, {
-				scope: config.agentScope,
-				enabledNames: config.enabledAgents,
-			});
-
-			// Effective model precedence: setup override > current session model > frontmatter default.
-			const sessionRef = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
-			const agents: AgentConfig[] = discovery.agents.map((agent) => ({
-				...agent,
-				model: config.agentModels[agent.name] ?? sessionRef ?? agent.model,
-			}));
-
-			const hasTasks = (params.tasks?.length ?? 0) > 0;
-			const hasSingle = Boolean(params.agent) && params.task !== undefined;
-			// `resume` is its own exclusive mode (it re-dispatches a handed-back run
-			// from its preserved session), so it bypasses the single/parallel check.
-			const hasResume = typeof params.resume === "number";
-
-			const makeDetails =
-				(mode: "single" | "parallel", background = false) =>
-				(results: SingleResult[]): SubagentDetails => ({ mode, results, background });
-
-			const catalog = agents.map((a) => a.name).join(", ") || "none";
-
-			if (!hasResume && Number(hasTasks) + Number(hasSingle) !== 1) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Invalid parameters. Provide exactly one mode: single {agent, task} or parallel {tasks: [...]}. Enabled agents: ${catalog}.`,
-						},
-					],
-					details: makeDetails("single")([]),
-				};
-			}
-
-			if (hasTasks) {
-				const blankTaskIndex = params.tasks?.findIndex(({ task }) => task.trim().length === 0) ?? -1;
-				if (blankTaskIndex !== -1) {
-					return {
-						content: [
-							{
-								type: "text",
-								text: `Invalid parameters. tasks[${blankTaskIndex}].task must contain at least one non-whitespace character. No background tasks were started. Enabled agents: ${catalog}.`,
-							},
-						],
-						details: makeDetails("parallel")([]),
-					};
-				}
-			} else if (params.task?.trim().length === 0) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Invalid parameters. task must contain at least one non-whitespace character. Enabled agents: ${catalog}.`,
-						},
-					],
-					details: makeDetails("single")([]),
-				};
-			}
-
-			// A vision-flagged dispatch with a stale vision model asks the user for a
-			// replacement before spawning (the persisted pick also fixes future runs).
-			// Runs only after parameter validation, so an invalid call never pops a picker.
-			const visionRequested = hasVisionTask(params);
-			let visionModel = config.visionModel;
-			if (visionRequested && visionModel !== undefined && !availableModelRefs(ctx).includes(visionModel.trim())) {
-				visionModel = await repairVisionModelForDispatch(ctx, config, runtime.configPath);
-			}
-			// Vision-flagged dispatches run on the configured vision model, else the
-			// main session's current model (the documented fallback), else the agent's
-			// own model as the last resort.
-			const visionRef = resolveVisionModelRef(ctx, visionModel);
-			const withVision = (agent: AgentConfig, vision: boolean): AgentConfig =>
-				vision && visionRef ? { ...agent, model: visionRef } : agent;
-
-			/**
-			 * Dispatch one agent inside an auto-fix chain: tracked in the widget with a
-			 * groupId/relationLabel, but NOT delivered through the completion flow — the
-			 * chain owner assembles and delivers the whole group at the end.
-			 */
-			const launchInLoop = async (
-				agentName: string,
-				task: string,
-				signal: AbortSignal,
-				meta: RunChainMeta,
-				vision = false,
-			): Promise<{ runId?: number; result: SingleResult }> => {
-				const agent = agents.find((candidate) => candidate.name === agentName);
-				if (!agent) return { result: failedStartResult(agentName, task, `Unknown agent: "${agentName}".`) };
-				// A vision-flagged chain (e.g. a review of UI screenshots) keeps its rounds
-				// on the vision model: the fix worker and re-review re-read the same images.
-				const effectiveAgent = withVision(agent, vision);
-				const thinkingLevel = config.agentThinkingLevels[agent.name] ?? agent.thinking ?? config.thinkingLevel;
-				const runId = monitor.addRun(agent.name, task, effectiveAgent.model, thinkingLevel, meta);
-				const onLive = makeLiveHandler(runId);
-				try {
-					const result = await runSingleAgentWithModelFallback(
-						{
-							defaultCwd: ctx.cwd,
-							agent: effectiveAgent,
-							agentName,
-							task,
-							thinkingLevel,
-							signal,
-							onLive,
-							makeDetails: makeDetails("single", true),
-							idleTimeoutMs: config.idleTimeoutSec * 1000,
-						},
-						sessionRef,
-					);
-					// Keep the finished round visible in the widget while the chain is
-					// still running, with a one-line summary of what it did; the whole
-					// group is dropped when the chain resolves (see removeChainGroup).
-					monitor.setSummary(runId, summarizeChainResult(result));
-					finishRun(runId, isFailedResult(result) ? "failed" : "done", { retain: true });
-					runtime.registerRunResult(runId, result);
-					return { runId, result };
-				} catch (error) {
-					finishRun(runId, "failed", { retain: true });
-					const errorMessage = error instanceof Error ? error.message : String(error);
-					const crashed = {
-						...queuedResult(agent, task, thinkingLevel),
-						exitCode: 1,
-						stderr: errorMessage,
-						stopReason: signal.aborted ? "aborted" : "error",
-						errorMessage,
-						dispatchFailed: true,
-					};
-					runtime.registerRunResult(runId, crashed);
-					return { runId, result: crashed };
-				}
-			};
-
-			/**
-			 * Run the auto-fix chain in the background: worker (briefed with the review's
-			 * findings) → reviewer re-review, up to maxFixRounds times. The main agent is
-			 * not woken mid-loop; the full chain is delivered as one group at the end.
-			 * Failures short-circuit: a crashed worker skips its re-review and delivers.
-			 * The triggering reviewer's run stays visible in the widget (annotated) until
-			 * the chain resolves, so the ↳ rows have an obvious parent.
-			 */
-			/** Drop every widget row belonging to an auto-fix chain; the retained
-			 * parent row is removed separately (it does not carry the groupId). */
-			const removeChainGroup = (groupId: string): void => {
-				for (const run of [...monitor.getRuns()]) {
-					if (run.groupId === groupId) monitor.removeRun(run.id);
-				}
-			};
-
-			const startFixLoop = (
-				initialReviewerResult: SingleResult,
-				parentGroupId: string,
-				parentRunId: number,
-				vision = false,
-			): void => {
-				runtime.runControllers.set(parentRunId, runtime.backgroundQueue.enqueue(
-					async (signal) => {
-						const chain: ChainStep[] = [
-							{ runId: parentRunId, result: initialReviewerResult, relation: "initial review" },
-						];
-						let lastReviewer = initialReviewerResult;
-						for (let round = 1; round <= config.maxFixRounds; round++) {
-							if (!runtime.sessionActive) break;
-							const fixBrief = buildFixTaskBrief(lastReviewer, round, config.maxFixRounds);
-							const workerStep = await launchInLoop("worker", fixBrief, signal, {
-								groupId: parentGroupId,
-								relationLabel: `fix round ${round}`,
-							}, vision);
-							chain.push({ ...workerStep, relation: `fix round ${round}` });
-							if (!runtime.sessionActive || isFailedResult(workerStep.result)) break;
-							const reReviewBrief = buildReReviewBrief(lastReviewer, round);
-							const reviewStep = await launchInLoop("reviewer", reReviewBrief, signal, {
-								groupId: parentGroupId,
-								relationLabel: `re-review round ${round}`,
-							}, vision);
-							chain.push({ ...reviewStep, relation: `re-review round ${round}` });
-							lastReviewer = reviewStep.result;
-							// A crashed re-review must stop the chain like a crashed worker: its
-							// output (if any) is not a verdict, and feeding it to the next fix
-							// round would brief the worker from garbage.
-							if (!runtime.sessionActive || isFailedResult(reviewStep.result)) break;
-							if (reviewVerdict(getResultOutput(reviewStep.result)) === "pass") break;
-						}
-						// The chain is done (success, exhaustion, or abort): drop the retained
-						// parent row and its retained round rows, then deliver one condensed
-						// summary. Register the parent's final state (the last chain result)
-						// before removal so subagent_wait can resolve it.
-						runtime.registerRunResult(parentRunId, chain[chain.length - 1].result);
-						runtime.runControllers.delete(parentRunId);
-						removeChainGroup(parentGroupId);
-						monitor.removeRun(parentRunId);
-						if (!runtime.sessionActive) return;
-						// One compact message instead of every round's raw output: the summary
-						// lines cover each step (verdict + what changed/found), and the final
-						// step's full report is appended only when its detail is actionable
-						// (a FAIL verdict, a crash, or a model-level failure the main agent
-						// must take over). Everything else stays one `subagent_status #id`
-						// call away.
-						const last = chain[chain.length - 1];
-						let block = formatChainSummary(chain);
-						if (isFailedResult(last.result) && isModelLevelFailure(last.result)) {
-							if (last.result.sessionDir && last.result.sessionId) {
-								runtime.preservedSessions.set(parentRunId, {
-									sessionId: last.result.sessionId,
-									sessionDir: last.result.sessionDir,
-									agentName: last.result.agent,
-									task: last.result.task,
-									vision,
-								});
-							}
-							block = `${block}\n\n${formatCompletionBlock(last.result, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(last.result, { runId: parentRunId })}`;
-						} else if (isFailedResult(last.result) || reviewVerdict(getResultOutput(last.result)) === "fail") {
-							block = `${block}\n\n${formatCompletionBlock(last.result, config.maxResultLines, ctx.cwd)}`;
-						}
-						runtime.sendCompletionGroup([
-							{
-								agent: `auto-fix chain (${last.result.agent})`,
-								block,
-								triggerTurn: true,
-							},
-						]);
-						runtime.completionBatcher.flush();
-					},
-					() => {
-						// Cancelled before delivery: clean up the retained parent row and
-						// every retained chain row (each in-flight chain run was already
-						// finished by its launchInLoop path).
-						runtime.runControllers.delete(parentRunId);
-						removeChainGroup(parentGroupId);
-						monitor.removeRun(parentRunId);
-					},
-					(error) => {
-						// A crash inside the chain orchestration (failed runs are caught by
-						// launchInLoop and delivered as part of the chain) must not vanish:
-						// drop the retained rows, notify, and deliver a failed result
-						// so the main agent knows the chain never completed.
-						runtime.registerRunResult(parentRunId, initialReviewerResult);
-						runtime.runControllers.delete(parentRunId);
-						removeChainGroup(parentGroupId);
-						monitor.removeRun(parentRunId);
-						if (!runtime.sessionActive) return;
-						const errorMessage = error instanceof Error ? error.message : String(error);
-						try {
-							ctx.ui.notify(`✗ auto-fix chain dispatch failed: ${errorMessage}`, "error");
-							// Keep the triggering review's findings: the chain crashed before any
-							// fix round ran, and the main agent needs the review to act on it.
-							runtime.sendCompletionGroup([
-								{
-									agent: initialReviewerResult.agent,
-									block: `${formatCompletionBlock(initialReviewerResult, config.maxResultLines, ctx.cwd)}\n\nAuto-fix chain crashed before completion: ${errorMessage}. The planned fix rounds did not run; the review above is the triggering reviewer's full output.`,
-									triggerTurn: true,
-								},
-							]);
-							runtime.completionBatcher.flush();
-						} catch {
-							/* a second delivery failure must not throw through the queue */
-						}
-					},
-				));
-			};
-
-			const startBackground = (
-				agentName: string,
-				task: string,
-				cwd?: string,
-				vision = false,
-				resumeSession?: { sessionId: string; sessionDir: string; preservedRunId: number },
-			): SingleResult => {
-				const agent = agents.find((candidate) => candidate.name === agentName);
-				if (!agent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
-				// A vision-flagged task runs on the configured vision model (or the main
-				// session's current model), overriding the agent's own model — the
-				// per-agent model may not support images.
-				const effectiveAgent = withVision(agent, vision);
-
-				// Effective strength: config override > agent frontmatter default > global default.
-				const thinkingLevel = config.agentThinkingLevels[agent.name] ?? agent.thinking ?? config.thinkingLevel;
-				const pending = queuedResult(effectiveAgent, task, thinkingLevel);
-				const runId = monitor.addRun(agent.name, task, effectiveAgent.model, thinkingLevel);
-				// Only a main-agent-dispatched reviewer can trigger an auto-fix chain, so
-				// only its finish is deferred to the queue task (see startFixLoop).
-				const onLive = makeLiveHandler(runId);
-
-				runtime.runControllers.set(runId, runtime.backgroundQueue.enqueue(
-					async (backgroundSignal) => {
-						let result: SingleResult;
-						try {
-							result = await runSingleAgentWithModelFallback(
-								{
-									defaultCwd: ctx.cwd,
-									agent: effectiveAgent,
-									agentName,
-									task,
-									cwd,
-									thinkingLevel,
-									signal: backgroundSignal,
-									onLive,
-									makeDetails: makeDetails("single", true),
-									idleTimeoutMs: config.idleTimeoutSec * 1000,
-									// A resume reuses a preserved session (handed back after a
-									// model-level failure) so it continues in-context instead of
-									// re-scanning. The wrapper detects the existing session file and
-									// resumes it; the continuation prompt steers the model to pick up.
-									...(resumeSession
-										? {
-											sessionId: resumeSession.sessionId,
-											sessionDir: resumeSession.sessionDir,
-											stdinText: buildResumePrompt(task, buildFallbackResumeReason()),
-										}
-										: {}),
-								},
-								sessionRef,
-							);
-						} catch (error) {
-							const errorMessage = error instanceof Error ? error.message : String(error);
-							result = {
-								...pending,
-								exitCode: 1,
-								stderr: errorMessage,
-								stopReason: backgroundSignal.aborted ? "aborted" : "error",
-								errorMessage,
-								dispatchFailed: true,
-							};
-							// The dedicated dispatch-failure notification below replaces the generic
-							// failure toast for dispatch crashes, so finish silently here.
-							finishRun(runId, "failed", { silent: true });
-							runtime.registerRunResult(runId, result);
-							runtime.runControllers.delete(runId);
-						}
-
-						if (!runtime.sessionActive) return;
-						// Auto-fix loop: a REVIEW_FAIL from a main-agent-dispatched reviewer
-						// triggers a worker→reviewer chain (up to maxFixRounds) without waking
-						// the main agent. Loop-internal re-reviews never reach here (they are
-						// awaited inside launchInLoop); the initial review is delivered with
-						// the chain at the end. While the chain runs, the triggering review
-						// stays in the widget (annotated) so the chain rows have an obvious
-						// parent; no premature "done" notification is shown.
-						if (shouldTriggerFixLoop(result, config)) {
-							// The session is known active here (checked above), so the chain
-							// always starts: keep the triggering review in the widget
-							// (annotated) without a premature "done" notification, and let
-							// startFixLoop deliver the whole chain and drop the parent row.
-							finishRun(runId, "done", { silent: true, retain: true });
-							monitor.setAnnotation(runId, "auto-fix chain running");
-							startFixLoop(result, `fix-${runId}`, runId, vision);
-							return;
-						}
-						const failed = isFailedResult(result);
-						// Model-level failures and dispatch crashes get their own dedicated
-						// dispatch-failure notification below, so finishRun's generic failure toast is
-						// silenced for them (computed before finishRun for that reason).
-						const modelLevel = failed && isModelLevelFailure(result);
-						const dispatchFailed = result.dispatchFailed === true;
-						finishRun(runId, failed ? "failed" : "done", modelLevel || dispatchFailed ? { silent: true } : undefined);
-						// Register before delivery so a concurrent subagent_wait resolves with
-						// the result even though the run row is already gone from the monitor.
-						runtime.registerRunResult(runId, result);
-						runtime.runControllers.delete(runId);
-						// A successful resume consumed the preserved session: reclaim its temp
-						// dir and drop the id so it cannot be re-resumed. A failed resume keeps
-						// it (still filed under the original preserved run id) for another try.
-						if (resumeSession && !failed) {
-							runtime.preservedSessions.delete(resumeSession.preservedRunId);
-							void rm(resumeSession.sessionDir, { recursive: true, force: true }).catch(() => undefined);
-						}
-						if (!runtime.sessionActive) return;
-						// A model-level failure that preserved a session (the run did real work
-						// before the model quota/auth broke) files it under this run id so a
-						// later `subagent({ resume: <runId> })` can continue in-context. Skipped
-						// for a resume run — its session is already filed under the original id.
-						if (modelLevel && !resumeSession && result.sessionDir && result.sessionId) {
-							runtime.preservedSessions.set(runId, {
-								sessionId: result.sessionId,
-								sessionDir: result.sessionDir,
-								agentName: agent.name,
-								task,
-								vision,
-							});
-						}
-						// Model-level failure: the configured model is unavailable or broke
-						// and the resume on the main-window model (when distinct) also failed.
-						// Hand the task back; when a session was preserved, steer the main agent
-						// to resume it in-context instead of executing it fresh.
-						const handbackRunId = resumeSession ? resumeSession.preservedRunId : runId;
-						const completion: CompletionMessageItem = {
-							agent: result.agent,
-							block: modelLevel
-								? `${formatCompletionBlock(result, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(result, { runId: handbackRunId })}`
-								: formatCompletionBlock(result, config.maxResultLines, ctx.cwd),
-							triggerTurn: completionTriggersTurn(result, config.notifyOnReviewPass),
-						};
-						if (modelLevel) {
-							ctx.ui.notify(`✗ ${result.agent} dispatch failed: model unavailable or broken — task handed to the main window`, "error");
-						} else if (dispatchFailed) {
-							// An exception inside the dispatch layer (spawn infra, temp-file/fs
-							// errors, ...): the main agent must know so it can re-dispatch.
-							ctx.ui.notify(`✗ ${result.agent} dispatch failed: ${result.errorMessage ?? "dispatch crashed"}`, "error");
-						}
-						if (failed) {
-							// Failures never wait and never hide behind a success turn: deliver
-							// first so the wake-up leads with the failure; held successes follow.
-							runtime.sendCompletionGroup([completion]);
-							runtime.completionBatcher.flush();
-						} else {
-							runtime.completionBatcher.push(completion);
-						}
-					},
-					() => {
-						runtime.runControllers.delete(runId);
-						finishRun(runId, "failed");
-					},
-					(error) => {
-						// The task body converts sub-agent failures into delivered results; an
-						// exception escaping it (spawn infra, delivery API, ...) must not
-						// vanish: notify the user and deliver a failed result so the main
-						// agent knows the dispatch failed and can re-dispatch.
-						const crashed = dispatchFailedResult(agent, task, error, thinkingLevel);
-						finishRun(runId, "failed", { silent: true });
-						runtime.registerRunResult(runId, crashed);
-						runtime.runControllers.delete(runId);
-						if (!runtime.sessionActive) return;
-						try {
-							ctx.ui.notify(`✗ ${agent.name} dispatch failed: ${crashed.errorMessage}`, "error");
-							runtime.sendCompletionGroup([
-								{
-									agent: agent.name,
-									block: formatCompletionBlock(crashed, config.maxResultLines, ctx.cwd),
-									triggerTurn: true,
-								},
-							]);
-							runtime.completionBatcher.flush();
-						} catch {
-							/* a second delivery failure must not throw through the queue */
-						}
-					},
-				));
-
-				return pending;
-			};
-
-			// Resume mode (exclusive): continue a handed-back run in its preserved
-			// session on the agent's configured model, picking up the prior context
-			// instead of re-scanning. Triggered by a model-level handback that named
-			// the run id, after the user has a working model again.
-			if (typeof params.resume === "number") {
-				const preserved = runtime.preservedSessions.get(params.resume);
-				if (!preserved) {
-					return {
-						content: [
-							{
-								type: "text",
-								text: `No preservable session for run #${params.resume}. It completed normally, was not a model-level handback, or the session has ended.`,
-							},
-						],
-						details: makeDetails("single")([]),
-						isError: true,
-					};
-				}
-				const resumeAgent = agents.find((a) => a.name === preserved.agentName);
-				if (!resumeAgent) {
-					return {
-						content: [
-							{
-								type: "text",
-								text: `Cannot resume run #${params.resume}: agent "${preserved.agentName}" is not enabled. Re-enable it (or run /subagents-setup) and resume again.`,
-							},
-						],
-						details: makeDetails("single")([]),
-						isError: true,
-					};
-				}
-				const pending = startBackground(preserved.agentName, preserved.task, undefined, preserved.vision, {
-					sessionId: preserved.sessionId,
-					sessionDir: preserved.sessionDir,
-					preservedRunId: params.resume,
-				});
-				if (pending.exitCode !== -1) {
-					return {
-						content: [{ type: "text", text: getResultOutput(pending) }],
-						details: makeDetails("single")([pending]),
-						isError: true,
-					};
-				}
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Resuming ${preserved.agentName} (run #${params.resume}) in the background on its configured model, picking up its preserved context. Its result will automatically resume the main agent when ready.`,
-						},
-					],
-					details: makeDetails("single", true)([pending]),
-					terminate: true,
-				};
-			}
-
-			// Sub-agents intentionally detach from the foreground turn. This makes the
-			// editor available immediately; completion messages later wake the main agent.
-			if (params.tasks && params.tasks.length > 0) {
-				if (params.tasks.length > config.maxConcurrency) {
-					return {
-						content: [
-							{
-								type: "text",
-								text: `Too many parallel tasks (${params.tasks.length}). Max is ${config.maxConcurrency} (configurable via /subagents-setup).`,
-							},
-						],
-						details: makeDetails("parallel", true)([]),
-					};
-				}
-
-				const results = params.tasks.map((task) => startBackground(task.agent, task.task, task.cwd, task.vision === true));
-				const started = results.filter((result) => result.exitCode === -1).length;
-				const failures = results.filter((result) => result.exitCode !== -1);
-				return {
-					content: [
-						{
-							type: "text",
-							text:
-								started > 0
-									? `Started ${started} background subagent${started === 1 ? "" : "s"}. Results will automatically resume the main agent when ready.`
-									: failures.map((result) => getResultOutput(result)).join("\n"),
-						},
-					],
-					details: makeDetails("parallel", true)(results),
-					isError: failures.length > 0,
-					terminate: true,
-				};
-			}
-
-			const result = startBackground(params.agent as string, params.task as string, params.cwd, params.vision === true);
-			if (result.exitCode !== -1) {
-				return {
-					content: [{ type: "text", text: getResultOutput(result) }],
-					details: makeDetails("single")([result]),
-					isError: true,
-				};
-			}
-			return {
-				content: [{ type: "text", text: `Started ${result.agent} in the background. Its result will automatically resume the main agent when ready.` }],
-				details: makeDetails("single", true)([result]),
-				terminate: true,
-			};
-
-		},
-
-		renderCall(args, theme) {
-			if (args.tasks && args.tasks.length > 0) {
-				let text = `${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${args.tasks.length})`)}`;
-				for (const t of args.tasks.slice(0, 4)) {
-					const preview = formatTaskSummary(t.task, 48);
-					text += `\n  ${theme.fg("accent", t.agent)} ${theme.fg("dim", preview)}`;
-				}
-				if (args.tasks.length > 4) text += `\n  ${theme.fg("dim", `… +${args.tasks.length - 4} more`)}`;
-				return new Text(text, 0, 0);
-			}
-			const task: string = args.task ?? "";
-			const preview = formatTaskSummary(task, 60);
-			return new Text(
-				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent ?? "?")} ${theme.fg("dim", preview)}`,
-				0,
-				0,
-			);
-		},
-
-		renderResult(result, _options, theme) {
-			const details = result.details as SubagentDetails | undefined;
-			if (!details || details.results.length === 0) return new Text(theme.fg("dim", "(no output)"), 0, 0);
-
-			if (details.mode === "single") {
-				const r = details.results[0];
-				const pending = r.exitCode === -1;
-				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
-				const usage = formatUsage(r.usage);
-				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (fell back from ${r.modelFallbackFrom})` : ""}`;
-				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`;
-				return new Text(line, 0, 0);
-			}
-
-			// Parallel mode: header + one compact line per agent
-			const lines: string[] = [
-				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${details.results.length})`)}`,
-			];
-			for (const r of details.results) {
-				const pending = r.exitCode === -1;
-				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
-				const usage = formatUsage(r.usage);
-				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (fell back from ${r.modelFallbackFrom})` : ""}`;
-				lines.push(`  ${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`);
-			}
-			return new Text(lines.join("\n"), 0, 0);
-		},
-	});
-}
+/**
+ * The `subagent` tool: dispatches explore/worker/reviewer agents as isolated pi
+ * child processes, single or parallel. Owns the dispatch pipeline: config load,
+ * per-agent model-pool resolution, per-run status tracking, the auto-fix chain
+ * (REVIEW_FAIL → worker → re-review), and completion delivery.
+ *
+ * Vision: a task flagged `vision: true` uses the configured vision model as an
+ * explicit primary, then the agent's configured backup and the current
+ * main-window model. Stale refs remain in the pool and fail normally at runtime.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { existsSync } from "node:fs";
+import { realpath, rm } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Type } from "typebox";
+import { discoverAgents, type AgentConfig } from "./agents.ts";
+import {
+	completionTriggersTurn,
+	type CompletionMessageItem,
+} from "./completion.ts";
+import { loadConfig, type SubagentsConfig } from "./config.ts";
+import {
+	dispatchFailedResult,
+	failedStartResult,
+	formatCompletionBlock,
+	formatUsage,
+	modelLevelTakeoverNote,
+	queuedResult,
+} from "./format.ts";
+import {
+	buildFixTaskBrief,
+	buildReReviewBrief,
+	formatChainSummary,
+	shouldTriggerFixLoop,
+	summarizeChainResult,
+	type ChainStep,
+} from "./fixloop.ts";
+import { currentModelRef, resolveAgentModelPool } from "./models.ts";
+import {
+	formatTaskSummary,
+	formatToolActivity,
+	monitor,
+	statusIcon,
+	type RunChainMeta,
+} from "./monitor.ts";
+import type { SubagentRuntime, SubagentThread, ThreadState } from "./runtime.ts";
+import { persistRecoveryRecords, recoveryRecordFromFinalization } from "./recovery.ts";
+import { forkRetainedSession } from "./session-fork.ts";
+import {
+	buildFallbackResumeReason,
+	buildResumePrompt,
+	RpcRunControl,
+	getResultOutput,
+	isFailedResult,
+	isModelLevelFailure,
+	reviewVerdict,
+	runSingleAgentWithModelFallback,
+	type SingleResult,
+	type SubagentDetails,
+	type SubagentLiveEvent,
+} from "./spawn.ts";
+import { trajectoryStore, summarizeToolArgs } from "./trajectory.ts";
+import {
+	createWorktreeIsolation,
+	resolveWorktreeTarget,
+	type IsolationMode,
+	type WorktreeFinalization,
+	type WorktreeIsolation,
+} from "./worktree.ts";
+
+const NON_BLANK_TASK_OPTIONS = { minLength: 1, pattern: "\\S" } as const;
+export const FORK_CONTINUATION_PROMPT =
+	"Continue from the retained context above. Review the prior work, then take the most useful next step toward completing the existing objective without repeating completed work.";
+export const WORKTREE_ISOLATION_INSTRUCTIONS =
+	"You are running in a temporary detached Git worktree. Work only in the current cwd; do not create another worktree or manually copy/apply changes to the original checkout. The parent dispatcher will integrate your tracked, deleted, and untracked changes when this thread finally settles.";
+
+export function buildWorktreeTaskPrompt(task: string): string {
+	return `${WORKTREE_ISOLATION_INSTRUCTIONS}\n\nTask: ${task}`;
+}
+
+function withWorktreeSystemPrompt(agent: AgentConfig): AgentConfig {
+	return {
+		...agent,
+		systemPrompt: `${agent.systemPrompt.trimEnd()}\n\n${WORKTREE_ISOLATION_INSTRUCTIONS}`.trim(),
+	};
+}
+
+interface DispatchEnvironment {
+	ctx: ExtensionContext;
+	config: SubagentsConfig;
+	agents: AgentConfig[];
+	sessionRef?: string;
+}
+
+const VISION_DESCRIPTION =
+	"Set true when the task may require viewing images (screenshots, mockups, designs) — the configured vision model becomes primary, followed by the agent backup and current main-window model";
+
+const ISOLATION_DESCRIPTION =
+	"Filesystem isolation: shared uses the caller's working tree; worktree creates a detached temporary Git worktree (write-capable agents only)";
+
+const IsolationSchema = Type.Optional(
+	StringEnum(["shared", "worktree"] as const, { description: ISOLATION_DESCRIPTION }),
+);
+
+const TaskItem = Type.Object({
+	agent: Type.String({ description: "Name of the agent to invoke" }),
+	task: Type.String({
+		...NON_BLANK_TASK_OPTIONS,
+		description: "Self-contained task to delegate (the agent has no memory of this conversation)",
+	}),
+	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
+	vision: Type.Optional(Type.Boolean({ description: VISION_DESCRIPTION })),
+	isolation: IsolationSchema,
+});
+
+const SubagentParams = Type.Object({
+	agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (single mode)" })),
+	task: Type.Optional(
+		Type.String({ ...NON_BLANK_TASK_OPTIONS, description: "Self-contained task to delegate (single mode)" }),
+	),
+	tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
+	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
+	vision: Type.Optional(Type.Boolean({ description: VISION_DESCRIPTION })),
+	isolation: IsolationSchema,
+});
+
+export function defaultIsolationMode(mode: "single" | "parallel", agentName: string, requested?: IsolationMode): IsolationMode {
+	if (requested) return requested;
+	return mode === "parallel" && agentName === "worker" ? "worktree" : "shared";
+}
+
+export function isWorktreeCapableAgent(agent: AgentConfig): boolean {
+	if (agent.name === "explore" || agent.name === "reviewer") return false;
+	if (agent.name === "worker") return true;
+	if (!agent.tools) return true;
+	return agent.tools.includes("edit") || agent.tools.includes("write");
+}
+
+const autoFixRootTails = new Map<string, Promise<void>>();
+
+async function canonicalAutoFixRoot(cwd: string): Promise<string> {
+	try {
+		return (await resolveWorktreeTarget(cwd)).originalRoot;
+	} catch {
+		try {
+			return await realpath(resolve(cwd));
+		} catch {
+			return resolve(cwd);
+		}
+	}
+}
+
+/** Keep the complete worker→review loop exclusive for one canonical repository.
+ * Child processes have independent file-mutation queues, so queue concurrency
+ * alone cannot make shared-checkout edits safe. */
+function serializeAutoFixChain(
+	cwd: string,
+	task: (signal: AbortSignal) => Promise<void>,
+): (signal: AbortSignal) => Promise<void> {
+	return async (signal) => {
+		if (signal.aborted) return;
+		const root = await canonicalAutoFixRoot(cwd);
+		const key = process.platform === "win32" ? root.toLowerCase() : root;
+		const previous = autoFixRootTails.get(key) ?? Promise.resolve();
+		let release!: () => void;
+		const gate = new Promise<void>((resolveGate) => {
+			release = resolveGate;
+		});
+		const tail = previous.catch(() => undefined).then(() => gate);
+		autoFixRootTails.set(key, tail);
+		await previous.catch(() => undefined);
+		try {
+			if (!signal.aborted) await task(signal);
+		} finally {
+			release();
+			if (autoFixRootTails.get(key) === tail) autoFixRootTails.delete(key);
+		}
+	};
+}
+
+function resolveDispatchModelPool(
+	agent: AgentConfig,
+	config: SubagentsConfig,
+	mainRef: string | undefined,
+	vision: boolean,
+): { agent: AgentConfig; fallbackModelRefs: string[] } {
+	const pool = resolveAgentModelPool({
+		primaryRef: vision ? config.visionModel : config.agentModels[agent.name],
+		backupRef: config.agentBackupModels[agent.name],
+		mainRef,
+		declaredDefaultRef: agent.model,
+	});
+	return {
+		agent: { ...agent, model: pool.primaryRef },
+		fallbackModelRefs: pool.fallbackModelRefs,
+	};
+}
+
+export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime): void {
+	pi.registerTool({
+		name: "subagent",
+		label: "Subagent",
+		description: [
+			"Delegate a discrete, self-contained task to a specialized sub-agent running in an ISOLATED context window.",
+			"Agents: explore (read-only codebase recon), worker (implement/fix/refactor/test, full tools), reviewer (adversarial pre-commit review, read-only).",
+			"Modes: single ({agent, task}) or parallel ({tasks: [{agent, task}, ...]}).",
+			"Isolation: single tasks default to shared; parallel worker tasks default to detached Git worktrees unless isolation: shared is explicit. explore/reviewer cannot use worktree isolation.",
+			"Use subagent_control to steer, retarget, park, resume, or fork a thread by its stable run id.",
+			"It starts agents in the background and immediately returns control to the main window; completion messages automatically wake the main agent to continue.",
+			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output).",
+			"Results arrive as wake-up messages automatically — you do NOT need to wait. If you must get a result in-turn, subagent_wait is a non-blocking lookup by default (pass timeoutMs to block).",
+			"Vision: set vision: true when the task may require viewing images (screenshots, mockups, design files — e.g. frontend work) — the configured vision model is primary, followed by that agent's backup and the current main-window model.",
+		].join(" "),
+		promptSnippet:
+			"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review); completion automatically resumes the main agent. Simple tasks: use direct tools, not subagents.",
+		promptGuidelines: [
+			"Delegate only when an isolated context genuinely pays: broad exploration, a self-contained implementation, or a review gate. Handle simple lookups and one-line edits inline with direct tools — never spawn a sub-agent for them.",
+			"Use subagent with agent 'explore' for broad or open-ended code search before large changes; a targeted 'where is X' is a direct grep/read.",
+			"Use subagent with agent 'worker' for a self-contained implementation task worth a separate context; it plans internally.",
+			"Use subagent with agent 'reviewer' for a fresh read-only review before reporting work done or committing.",
+			"subagent launches work in the background and ends the current turn; when a result arrives, the main agent is automatically resumed with it.",
+			"Run independent tasks in parallel by passing a tasks array to subagent; parallel worker items default to isolation: worktree so their edits are integrated independently. Pass isolation: shared only when workers intentionally need the caller's live uncommitted tree.",
+			"Use isolation: worktree only for worker/write-capable agents and only inside a Git repository with a committed HEAD; setup or integration failures never silently fall back to shared.",
+			"NEVER sleep or poll, and do NOT call subagent_wait to hold the turn — subagent ends the turn immediately and the result arrives as a message that wakes you automatically (even mid-turn). Ending your turn is the default and the only correct way to wait.",
+			"If you must keep the turn for a result, call subagent_wait with an explicit timeoutMs (non-blocking by default) — never bash sleep/timeout to wait for a sub-agent.",
+			"When a delegated task may require viewing images (frontend screenshots, mockups, design comparisons), pass vision: true and give the sub-agent the exact image paths — it reads them with its read tool. The configured vision model becomes primary; model-level failures continue through the agent's backup pool and current main-window model.",
+			"When a sub-agent result arrives it is already shown to the user — do NOT restate, paraphrase, or summarize it; reply with only your own conclusion or next action (often just one line), since duplicating the result wastes tokens for nothing.",
+		],
+		parameters: SubagentParams,
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			monitor.beginTurn();
+			const config = await loadConfig(runtime.configPath);
+			// Pick up concurrency changes from /subagents-setup without a restart.
+			runtime.backgroundQueue.setConcurrency(config.maxConcurrency);
+
+			// Finished runs leave the active monitor immediately. Their final findings
+			// are sent as a custom message that starts a follow-up turn.
+			const finishRun = (
+				runId: number,
+				status: "done" | "failed",
+				opts?: { silent?: boolean; retain?: boolean },
+			): void => {
+				monitor.setStatus(runId, status); // stamps endedAt for the elapsed time
+				const run = opts?.retain ? monitor.findRun(runId) : monitor.removeRun(runId);
+				if (!run) return; // already finished — stay idempotent
+				if (opts?.retain) monitor.setRetained(runId, true);
+				if (opts?.silent || !runtime.sessionActive) return;
+				const icon = status === "done" ? "✓" : "✗";
+				ctx.ui.notify(`${icon} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
+			};
+
+			// Live sub-agent activity → concise one-line status ("thinking",
+			// "read src/index.ts", ...), never a raw args blob. In parallel, every
+			// live event is appended to the thread's append-only trajectory (status,
+			// model-candidate changes, usage, tool starts/ends with a redacted
+			// args summary). The live handler only updates monitor state; finishing
+			// (removeRun + notify) is
+			// owned by the queue task / launchInLoop. That keeps a startup retry —
+			// which fires a transient "failed" status before relaunching — from
+			// ripping the row out early, and lets the queue task decide between
+			// delivering a reviewer's result and starting an auto-fix chain.
+			const makeLiveHandler =
+				(runId: number, threadId?: number, generation?: number) =>
+				(e: SubagentLiveEvent): void => {
+					if (generation !== undefined && runtime.threads.get(runId)?.generation !== generation) return;
+					switch (e.kind) {
+						case "status":
+							// Only update monitor status here. Finishing (removeRun + notify) is
+							// owned by the queue task / launchInLoop so that a startup retry — which
+							// fires a transient "failed" status before relaunching the child — never
+							// rips the row out from under the retry or emits a premature "✗" toast.
+							monitor.setStatus(runId, e.status);
+							break;
+						case "model":
+							monitor.setModel(runId, e.model, e.fallbackFrom);
+							break;
+						case "usage":
+							monitor.setUsage(runId, e.usage, e.model);
+							break;
+						case "tool_start":
+							monitor.recordToolStart(runId, e.toolName, formatToolActivity(e.toolName, e.args));
+							break;
+						case "tool_end":
+							monitor.recordToolEnd(runId, e.toolName, e.isError);
+							break;
+						case "thinking":
+							monitor.setActivity(runId, "thinking");
+							break;
+						case "text":
+							// A text delta is model output, not a filesystem write.
+							monitor.setActivity(runId, "responding");
+							break;
+					}
+					if (threadId !== undefined) {
+						const trajectory = trajectoryStore.get(threadId).trajectory;
+						switch (e.kind) {
+								case "status":
+									trajectory.append({ kind: "status", status: e.status });
+									break;
+								case "model":
+									trajectory.append({ kind: "candidate", model: e.model, fallbackFrom: e.fallbackFrom });
+									break;
+								case "usage":
+									trajectory.append({ kind: "usage", usage: { ...e.usage }, model: e.model });
+									break;
+								case "tool_start":
+									trajectory.append({
+										kind: "tool_start",
+										tool: e.toolName,
+										toolCallId: e.toolCallId,
+										summary: summarizeToolArgs(e.args),
+									});
+									break;
+								case "tool_end":
+									trajectory.append({ kind: "tool_end", tool: e.toolName, toolCallId: e.toolCallId, isError: e.isError });
+									break;
+							}
+					}
+				};
+
+			const discovery = discoverAgents(ctx.cwd, {
+				scope: config.agentScope,
+				enabledNames: config.enabledAgents,
+				projectTrusted: ctx.isProjectTrusted?.() === true,
+			});
+			const sessionRef = currentModelRef(ctx);
+			const agents = discovery.agents;
+
+			const hasTasks = (params.tasks?.length ?? 0) > 0;
+			const hasSingle = Boolean(params.agent) && params.task !== undefined;
+
+			const makeDetails =
+				(mode: "single" | "parallel", background = false) =>
+				(results: SingleResult[]): SubagentDetails => ({ mode, results, background });
+
+			const catalog = agents.map((a) => a.name).join(", ") || "none";
+
+			if (Number(hasTasks) + Number(hasSingle) !== 1) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Invalid parameters. Provide exactly one mode: single {agent, task} or parallel {tasks: [...]}. Enabled agents: ${catalog}.`,
+						},
+					],
+					details: makeDetails("single")([]),
+				};
+			}
+
+			if (hasTasks) {
+				const blankTaskIndex = params.tasks?.findIndex(({ task }) => task.trim().length === 0) ?? -1;
+				if (blankTaskIndex !== -1) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Invalid parameters. tasks[${blankTaskIndex}].task must contain at least one non-whitespace character. No background tasks were started. Enabled agents: ${catalog}.`,
+							},
+						],
+						details: makeDetails("parallel")([]),
+					};
+				}
+			} else if (params.task?.trim().length === 0) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Invalid parameters. task must contain at least one non-whitespace character. Enabled agents: ${catalog}.`,
+						},
+					],
+					details: makeDetails("single")([]),
+				};
+			}
+
+			/**
+			 * Dispatch one agent inside an auto-fix chain: tracked in monitor state with a
+			 * groupId/relationLabel, but NOT delivered through the completion flow — the
+			 * chain owner assembles and delivers the whole group at the end.
+			 */
+			const launchInLoop = async (
+				agentName: string,
+				task: string,
+				executionCwd: string,
+				signal: AbortSignal,
+				meta: RunChainMeta,
+				vision = false,
+			): Promise<{ runId?: number; result: SingleResult }> => {
+				const agent = agents.find((candidate) => candidate.name === agentName);
+				if (!agent) return { result: failedStartResult(agentName, task, `Unknown agent: "${agentName}".`) };
+				// Vision chains keep the vision override as each round's primary while
+				// retaining that worker/reviewer's own configured backup pool.
+				const pool = resolveDispatchModelPool(agent, config, sessionRef, vision);
+				const thinkingLevel = config.agentThinkingLevels[agent.name] ?? agent.thinking ?? config.thinkingLevel;
+				const runId = monitor.addRun(agent.name, task, pool.agent.model, thinkingLevel, meta);
+				// Chain rounds keep their own lifecycle trajectory.
+				const chainState = trajectoryStore.get(runId);
+				chainState.trajectory.append({
+					kind: "dispatch",
+					agent: agent.name,
+					task,
+					model: pool.agent.model,
+					thinking: thinkingLevel,
+					pool: pool.fallbackModelRefs,
+					vision,
+					isolation: "shared",
+					originalCwd: executionCwd,
+					isolationCwd: executionCwd,
+				});
+				const onLive = makeLiveHandler(runId, runId);
+				try {
+					const result = await runSingleAgentWithModelFallback(
+						{
+							defaultCwd: executionCwd,
+							cwd: executionCwd,
+							agent: pool.agent,
+							agentName,
+							task,
+							thinkingLevel,
+							signal,
+							onLive,
+							makeDetails: makeDetails("single", true),
+							idleTimeoutMs: config.idleTimeoutSec * 1000,
+						},
+						pool.fallbackModelRefs,
+					);
+					result.runId = runId;
+					result.isolation = "shared";
+					result.originalCwd = executionCwd;
+					result.isolationCwd = executionCwd;
+					runtime.retainSession(result);
+					monitor.setModel(runId, result.model, result.modelFallbackFrom);
+					chainState.trajectory.append({
+						kind: "settled",
+						status: isFailedResult(result) ? "failed" : "done",
+						model: result.model,
+					});
+					// Keep the finished round in status state while the chain is
+					// still running, with a one-line summary of what it did; the whole
+					// group is dropped when the chain resolves (see removeChainGroup).
+					monitor.setSummary(runId, summarizeChainResult(result));
+					finishRun(runId, isFailedResult(result) ? "failed" : "done", { retain: true });
+					runtime.registerRunResult(runId, result);
+					return { runId, result };
+				} catch (error) {
+					finishRun(runId, "failed", { retain: true });
+					chainState.trajectory.append({ kind: "settled", status: "failed", model: pool.agent.model });
+					const errorMessage = error instanceof Error ? error.message : String(error);
+					const crashed: SingleResult = {
+						...queuedResult(pool.agent, task, thinkingLevel),
+						runId,
+						isolation: "shared",
+						originalCwd: executionCwd,
+						isolationCwd: executionCwd,
+						exitCode: 1,
+						stderr: errorMessage,
+						stopReason: signal.aborted ? "aborted" : "error",
+						errorMessage,
+						dispatchFailed: true,
+					};
+					runtime.registerRunResult(runId, crashed);
+					return { runId, result: crashed };
+				}
+			};
+
+			/**
+			 * Run the auto-fix chain in the background: worker (briefed with the review's
+			 * findings) → reviewer re-review, up to maxFixRounds times. The main agent is
+			 * not woken mid-loop; the full chain is delivered as one group at the end.
+			 * Failures short-circuit: a crashed worker skips its re-review and delivers.
+			 * The triggering reviewer stays in monitor state until the chain resolves.
+			 */
+			/** Drop every monitor row belonging to an auto-fix chain; the retained
+			 * parent is removed separately (it does not carry the groupId). */
+			const removeChainGroup = (groupId: string): void => {
+				for (const run of [...monitor.getRuns()]) {
+					if (run.groupId === groupId) monitor.removeRun(run.id);
+				}
+			};
+
+			const startFixLoop = (
+				initialReviewerResult: SingleResult,
+				parentGroupId: string,
+				parentRunId: number,
+				executionCwd: string,
+				vision = false,
+			): void => {
+				const parentThreadAtStart = runtime.threads.get(parentRunId);
+				if (!parentThreadAtStart) return;
+				const parentGeneration = parentThreadAtStart.generation;
+				const parentControl = parentThreadAtStart.control;
+				let fixController: AbortController | undefined;
+				const ownsParent = (): boolean => {
+					const current = runtime.threads.get(parentRunId);
+					return fixController !== undefined &&
+						current === parentThreadAtStart &&
+						current.generation === parentGeneration &&
+						current.control === parentControl &&
+						current.queueController === fixController &&
+						runtime.runControllers.get(parentRunId) === fixController;
+				};
+				const clearOwnedController = (): void => {
+					if (!fixController) return;
+					if (runtime.runControllers.get(parentRunId) === fixController) {
+						runtime.runControllers.delete(parentRunId);
+					}
+					const current = runtime.threads.get(parentRunId);
+					if (current === parentThreadAtStart && current.queueController === fixController) {
+						current.queueController = undefined;
+					}
+				};
+				fixController = runtime.backgroundQueue.enqueue(
+					serializeAutoFixChain(executionCwd, async (signal) => {
+						const chain: ChainStep[] = [
+							{ runId: parentRunId, result: initialReviewerResult, relation: "initial review" },
+						];
+						let lastReviewer = initialReviewerResult;
+						for (let round = 1; round <= config.maxFixRounds; round++) {
+							if (!runtime.sessionActive) break;
+							const fixBrief = buildFixTaskBrief(lastReviewer, round, config.maxFixRounds);
+							const workerStep = await launchInLoop("worker", fixBrief, executionCwd, signal, {
+								groupId: parentGroupId,
+								relationLabel: `fix round ${round}`,
+							}, vision);
+							// Preserve the newest sub-step before checking chain ownership. A
+							// destructive stop invalidates ownsParent() while this child is
+							// aborting, and its partial output must become the parent's stopped
+							// result instead of falling back to the old triggering review.
+							if (
+								runtime.threads.get(parentRunId) === parentThreadAtStart &&
+								parentThreadAtStart.generation === parentGeneration
+							) {
+								parentThreadAtStart.lastResult = workerStep.result;
+								parentThreadAtStart.agentName = workerStep.result.agent;
+								parentThreadAtStart.task = workerStep.result.task;
+								parentThreadAtStart.sessionId = workerStep.result.sessionId;
+								parentThreadAtStart.sessionDir = workerStep.result.sessionDir;
+								runtime.retainSession(workerStep.result);
+							}
+							if (!ownsParent()) return;
+							chain.push({ ...workerStep, relation: `fix round ${round}` });
+							if (!runtime.sessionActive || isFailedResult(workerStep.result)) break;
+							const reReviewBrief = buildReReviewBrief(lastReviewer, round);
+							const reviewStep = await launchInLoop("reviewer", reReviewBrief, executionCwd, signal, {
+								groupId: parentGroupId,
+								relationLabel: `re-review round ${round}`,
+							}, vision);
+							if (
+								runtime.threads.get(parentRunId) === parentThreadAtStart &&
+								parentThreadAtStart.generation === parentGeneration
+							) {
+								parentThreadAtStart.lastResult = reviewStep.result;
+								parentThreadAtStart.agentName = reviewStep.result.agent;
+								parentThreadAtStart.task = reviewStep.result.task;
+								parentThreadAtStart.sessionId = reviewStep.result.sessionId;
+								parentThreadAtStart.sessionDir = reviewStep.result.sessionDir;
+								runtime.retainSession(reviewStep.result);
+							}
+							if (!ownsParent()) return;
+							chain.push({ ...reviewStep, relation: `re-review round ${round}` });
+							lastReviewer = reviewStep.result;
+							// A crashed re-review must stop the chain like a crashed worker: its
+							// output (if any) is not a verdict, and feeding it to the next fix
+							// round would brief the worker from garbage.
+							if (!runtime.sessionActive || isFailedResult(reviewStep.result)) break;
+							if (reviewVerdict(getResultOutput(reviewStep.result)) === "pass") break;
+						}
+						// Every parent mutation is guarded by the exact generation, control, and
+						// queue controller that started this chain. A parked/resumed generation or
+						// destructive stop must make this old orchestration a no-op.
+						if (!ownsParent()) return;
+						const controlledParent = parentThreadAtStart;
+						if (controlledParent.retired || controlledParent.state === "stopped") {
+							clearOwnedController();
+							removeChainGroup(parentGroupId);
+							return;
+						}
+						// Parking an auto-fix chain aborts its in-flight child but preserves the
+						// parent's retained checkpoint and suppresses an aborted chain delivery.
+						if (controlledParent.state === "parked") {
+							clearOwnedController();
+							removeChainGroup(parentGroupId);
+							monitor.setRetained(parentRunId, false);
+							monitor.setStatus(parentRunId, "parked");
+							return;
+						}
+						// The chain is done (success, exhaustion, or abort): drop the retained
+						// parent row and its retained round rows, then deliver one condensed
+						// summary. Register the parent's final state (the last chain result)
+						// before removal so subagent_wait can resolve it.
+						const last = chain[chain.length - 1];
+						runtime.registerRunResult(parentRunId, last.result);
+						removeChainGroup(parentGroupId);
+						monitor.removeRun(parentRunId);
+						runtime.retainSession(last.result);
+						const parentThread = parentThreadAtStart;
+						parentThread.agentName = last.result.agent;
+						parentThread.task = last.result.task;
+						parentThread.sessionId = last.result.sessionId;
+						parentThread.sessionDir = last.result.sessionDir;
+						parentThread.state = isFailedResult(last.result) ? "failed" : "completed";
+						// The chain outcome settles the parent thread's trajectory: the
+						// last chain step is its final state.
+						const parentTrajectory = trajectoryStore.get(parentRunId);
+						parentTrajectory.trajectory.append({
+							kind: "settled",
+							status: parentThread.state === "failed" ? "failed" : "done",
+							model: last.result.model,
+						});
+						if (!runtime.sessionActive) {
+							clearOwnedController();
+							return;
+						}
+						// One compact message instead of every round's raw output: the summary
+						// lines cover each step (verdict + what changed/found), and the final
+						// step's full report is appended only when its detail is actionable
+						// (a FAIL verdict, a crash, or a model-level failure the main agent
+						// must take over). Everything else stays one `subagent_status #id`
+						// call away.
+						let block = formatChainSummary(chain);
+						if (isFailedResult(last.result) && isModelLevelFailure(last.result)) {
+							block = `${block}\n\n${formatCompletionBlock(last.result, config.maxResultLines, executionCwd)}\n\n${modelLevelTakeoverNote(last.result, { runId: parentRunId })}`;
+						} else if (isFailedResult(last.result) || reviewVerdict(getResultOutput(last.result)) === "fail") {
+							block = `${block}\n\n${formatCompletionBlock(last.result, config.maxResultLines, executionCwd)}`;
+						}
+						runtime.sendCompletionGroup([
+							{
+								agent: `auto-fix chain (${last.result.agent})`,
+								block,
+								triggerTurn: true,
+							},
+						]);
+						runtime.completionBatcher.flush();
+						clearOwnedController();
+					}),
+					() => {
+						if (!ownsParent()) return;
+						const controlledParent = parentThreadAtStart;
+						clearOwnedController();
+						removeChainGroup(parentGroupId);
+						if (controlledParent.state === "parked") {
+							monitor.setRetained(parentRunId, false);
+							monitor.setStatus(parentRunId, "parked");
+							return;
+						}
+						if (!controlledParent.retired) monitor.removeRun(parentRunId);
+					},
+					(error) => {
+						// A crash inside the chain orchestration (failed runs are caught by
+						// launchInLoop and delivered as part of the chain) must not vanish, but
+						// an obsolete generation/controller must never publish it.
+						if (!ownsParent()) return;
+						if (parentThreadAtStart.retired || parentThreadAtStart.state === "stopped") {
+							clearOwnedController();
+							removeChainGroup(parentGroupId);
+							return;
+						}
+						runtime.registerRunResult(parentRunId, initialReviewerResult);
+						removeChainGroup(parentGroupId);
+						monitor.removeRun(parentRunId);
+						if (!runtime.sessionActive) {
+							clearOwnedController();
+							return;
+						}
+						const errorMessage = error instanceof Error ? error.message : String(error);
+						try {
+							ctx.ui.notify(`✗ auto-fix chain dispatch failed: ${errorMessage}`, "error");
+							// Keep the triggering review's findings: the chain crashed before any
+							// fix round ran, and the main agent needs the review to act on it.
+							runtime.sendCompletionGroup([
+								{
+									agent: initialReviewerResult.agent,
+									block: `${formatCompletionBlock(initialReviewerResult, config.maxResultLines, executionCwd)}\n\nAuto-fix chain crashed before completion: ${errorMessage}. The planned fix rounds did not run; the review above is the triggering reviewer's full output.`,
+									triggerTurn: true,
+								},
+							]);
+							runtime.completionBatcher.flush();
+						} catch {
+							/* a second delivery failure must not throw through the queue */
+						} finally {
+							clearOwnedController();
+						}
+					},
+				);
+				runtime.runControllers.set(parentRunId, fixController);
+				parentThreadAtStart.queueController = fixController;
+				const priorCompletion = parentThreadAtStart.generationCompletion;
+				parentThreadAtStart.generationCompletion = Promise.all([
+					priorCompletion,
+					runtime.backgroundQueue.waitForTask(fixController),
+				]).then(() => undefined);
+			};
+
+			interface SessionSeed {
+				sessionId?: string;
+				sessionDir?: string;
+				prompt?: string;
+				worktree?: WorktreeIsolation;
+				forkedFromRunId?: number;
+				forkObjective?: string;
+				modelPool?: string[];
+				thinkingLevel?: SubagentThread["thinkingLevel"];
+			}
+
+			interface ResumeReservation {
+				version: number;
+				generation: number;
+				sessionId?: string;
+				sessionDir?: string;
+			}
+
+			const ownsResumeReservation = (
+				thread: SubagentThread,
+				reservation: ResumeReservation,
+			): boolean =>
+				runtime.sessionActive &&
+				runtime.threads.get(thread.id) === thread &&
+				!thread.retired &&
+				thread.lifecycleOperation === "resume" &&
+				thread.lifecycleVersion === reservation.version &&
+				thread.generation === reservation.generation &&
+				thread.sessionId === reservation.sessionId &&
+				thread.sessionDir === reservation.sessionDir;
+
+			const beginPreflight = (): (() => void) => {
+				let resolvePreflight!: () => void;
+				const preflight = new Promise<void>((resolve) => {
+					resolvePreflight = resolve;
+				});
+				runtime.preflightOperations.add(preflight);
+				return () => {
+					runtime.preflightOperations.delete(preflight);
+					resolvePreflight();
+				};
+			};
+
+			const startBackground = async (
+				agentName: string,
+				task: string,
+				cwd: string | undefined,
+				vision = false,
+				isolation: IsolationMode = "shared",
+				existingThread?: SubagentThread,
+				newObjectiveOnResume = false,
+				environment?: DispatchEnvironment,
+				seed?: SessionSeed,
+				resumeReservation?: ResumeReservation,
+			): Promise<SingleResult> => {
+				if (!runtime.sessionActive) {
+					return failedStartResult(agentName, task, "Parent session shut down before this subagent generation could start.");
+				}
+				if (existingThread && (!resumeReservation || !ownsResumeReservation(existingThread, resumeReservation))) {
+					return failedStartResult(agentName, task, `Run #${existingThread.id} changed while resume was preparing; no new generation was started.`);
+				}
+				const runCtx = environment?.ctx ?? ctx;
+				const runConfig = environment?.config ?? config;
+				const runAgents = environment?.agents ?? agents;
+				const runSessionRef = environment?.sessionRef ?? sessionRef;
+				const agent = runAgents.find((candidate) => candidate.name === agentName);
+				if (!agent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
+				if (isolation === "worktree" && !isWorktreeCapableAgent(agent)) {
+					return {
+						...failedStartResult(agentName, task, `Agent "${agentName}" is read-only; worktree isolation is available only to worker/write-capable agents.`),
+						isolation,
+					};
+				}
+
+				const originalCwd = resolve(cwd ?? runCtx.cwd);
+				const previousWorktree = existingThread?.worktree;
+				let worktree = seed?.worktree ?? previousWorktree;
+				if (isolation === "worktree") {
+					if (worktree && worktree.state !== "active") {
+						return {
+							...failedStartResult(agentName, task, `Run #${existingThread?.id ?? "?"} has no active continuation worktree.`),
+							isolation,
+							originalCwd,
+							integrationStatus: worktree.state === "finalizing" ? "pending" : worktree.state,
+						};
+					}
+					if (!worktree) {
+						try {
+							worktree = await createWorktreeIsolation(originalCwd);
+						} catch (error) {
+							return {
+								...failedStartResult(agentName, task, error instanceof Error ? error.message : String(error)),
+								isolation,
+								originalCwd,
+							};
+						}
+					}
+				}
+				const executionCwd = worktree?.cwd ?? originalCwd;
+				const resolvedPool = resolveDispatchModelPool(agent, runConfig, runSessionRef, vision);
+				const inheritedPool = seed?.modelPool?.filter((ref) => ref.trim().length > 0) ?? [];
+				const rawPool = inheritedPool.length > 0
+					? {
+						agent: { ...agent, model: inheritedPool[0] },
+						fallbackModelRefs: inheritedPool.slice(1),
+					}
+					: resolvedPool;
+				// Isolation is a persistent system-level invariant, not a one-shot task
+				// prefix: queued retargets, live retargets, resumes, and model fallbacks
+				// all keep the same worktree boundary.
+				const pool = isolation === "worktree"
+					? { ...rawPool, agent: withWorktreeSystemPrompt(rawPool.agent) }
+					: rawPool;
+				const thinkingLevel = seed?.thinkingLevel ?? runConfig.agentThinkingLevels[agent.name] ?? agent.thinking ?? runConfig.thinkingLevel;
+				const modelPool = [pool.agent.model, ...pool.fallbackModelRefs].filter((ref): ref is string => Boolean(ref));
+				const priorTask = existingThread?.task;
+				const priorSessionId = seed?.sessionId ?? existingThread?.sessionId;
+				const priorSessionDir = seed?.sessionDir ?? existingThread?.sessionDir;
+				if (existingThread && resumeReservation && !ownsResumeReservation(existingThread, resumeReservation)) {
+					return failedStartResult(agentName, task, `Run #${existingThread.id} changed while resume was preparing; no new generation was started.`);
+				}
+				const runId = existingThread?.id ?? monitor.addRun(agent.name, task, pool.agent.model, thinkingLevel, {
+					isolation,
+					...(seed?.forkedFromRunId !== undefined ? { forkedFromRunId: seed.forkedFromRunId } : {}),
+				});
+				const generation = (existingThread?.generation ?? 0) + 1;
+				const pending: SingleResult = {
+					...queuedResult(pool.agent, task, thinkingLevel),
+					runId,
+					isolation,
+					originalCwd,
+					isolationCwd: executionCwd,
+					...(isolation === "worktree" ? { integrationStatus: "pending" as const } : {}),
+					...(seed?.sessionId && seed.sessionDir
+						? { sessionId: seed.sessionId, sessionDir: seed.sessionDir, resumed: true }
+						: {}),
+					...(seed?.forkedFromRunId !== undefined ? { forkedFromRunId: seed.forkedFromRunId } : {}),
+				};
+				if (existingThread) {
+					monitor.restartRun(runId, agent.name, task, pool.agent.model, thinkingLevel, isolation);
+					runtime.settledRuns.delete(runId);
+				}
+
+				let thread!: SubagentThread;
+				const control = new RpcRunControl(task, generation, (phase) => {
+					if (runtime.threads.get(runId)?.generation !== generation || phase === "settled") return;
+					// Orchestration transitions are part of the trajectory (retrying →
+					// retry event, park/stop → terminal control events).
+					const trajectory = trajectoryStore.get(runId).trajectory;
+					if (phase === "retrying") trajectory.append({ kind: "retry", reason: "retrying" });
+					else if (phase === "parked") trajectory.append({ kind: "park" });
+					else if (phase === "stopped") trajectory.append({ kind: "stop", reason: control.getStopMessage() });
+					const state: ThreadState =
+						phase === "queued" || phase === "starting"
+							? "queued"
+							: phase === "steering"
+								? "steering"
+								: phase === "interrupting"
+									? "interrupting"
+									: phase === "parked"
+										? "parked"
+										: phase === "stopped"
+											? "stopped"
+											: "running";
+					thread.state = state;
+					if (state === "queued") monitor.setStatus(runId, "queued");
+					else if (state === "steering") monitor.setStatus(runId, "steering");
+					else if (state === "interrupting") monitor.setStatus(runId, "interrupting");
+					else if (state === "parked") monitor.setStatus(runId, "parked");
+					else if (state === "running") monitor.setStatus(runId, "running");
+				});
+
+				// Restart bumps the generation while preserving append-only history.
+				const trajectoryState = trajectoryStore.get(runId);
+				if (existingThread) {
+					trajectoryState.trajectory.restart();
+					trajectoryState.trajectory.append({
+						kind: "resume",
+						objective: newObjectiveOnResume ? task : undefined,
+					});
+				}
+				if (seed?.forkedFromRunId !== undefined) {
+					trajectoryState.trajectory.append({
+						kind: "fork",
+						sourceRunId: seed.forkedFromRunId,
+						childRunId: runId,
+						objective: seed.forkObjective,
+					});
+				}
+				trajectoryState.trajectory.append({
+					kind: "dispatch",
+					agent: agent.name,
+					task,
+					model: pool.agent.model,
+					thinking: thinkingLevel,
+					pool: pool.fallbackModelRefs,
+					vision,
+					resumed: existingThread !== undefined || seed !== undefined,
+					isolation,
+					originalCwd,
+					isolationCwd: executionCwd,
+				});
+				if (worktree && worktree !== previousWorktree) {
+					trajectoryState.trajectory.append({
+						kind: "worktree",
+						status: "created",
+						originalCwd,
+						isolationCwd: executionCwd,
+						worktreePath: worktree.worktreePath,
+					});
+				}
+
+				if (existingThread) {
+					thread = existingThread;
+					thread.generation = generation;
+					thread.agentName = agent.name;
+					thread.task = task;
+					thread.cwd = originalCwd;
+					thread.executionCwd = executionCwd;
+					thread.vision = vision;
+					thread.modelPool = modelPool;
+					thread.thinkingLevel = thinkingLevel;
+					thread.isolation = isolation;
+					thread.worktree = worktree;
+					thread.state = "queued";
+					thread.control = control;
+					// A newly admitted generation owns no output yet. Keeping the prior
+					// generation here would make a queued stop publish stale task,
+					// session metadata as this generation's partial.
+					thread.lastResult = undefined;
+					if (seed?.sessionId && seed.sessionDir) {
+						thread.sessionId = seed.sessionId;
+						thread.sessionDir = seed.sessionDir;
+					}
+					thread.retireOnSettle = false;
+					thread.isolationFailureNotified = false;
+				} else {
+					thread = {
+						id: runId,
+						generation,
+						agentName: agent.name,
+						task,
+						cwd: originalCwd,
+						executionCwd,
+						vision,
+						modelPool,
+						thinkingLevel,
+						isolation,
+						worktree,
+						state: "queued",
+						control,
+						generationCompletion: Promise.resolve(),
+						lifecycleVersion: 0,
+						sessionId: seed?.sessionId,
+						sessionDir: seed?.sessionDir,
+						forkedFromRunId: seed?.forkedFromRunId,
+						forkChildRunIds: [],
+						park: async () => {
+							throw new Error("Thread park was not initialized.");
+						},
+						resume: async () => failedStartResult(agent.name, task, "Thread resume was not initialized."),
+						fork: async () => failedStartResult(agent.name, task, "Thread fork was not initialized."),
+						finalizeIsolation: async () => undefined,
+					};
+					runtime.threads.set(runId, thread);
+				}
+				thread.notifyIsolationFailure = (finalization) => {
+					const paths = [finalization.worktreePath, finalization.patchPath].filter(Boolean).join(" · ");
+					runCtx.ui.notify(
+						`✗ worker worktree ${finalization.integrated ? "cleanup" : "integration"} failed${paths ? ` · retained ${paths}` : ""}: ${finalization.error ?? "unknown Git integration error"}`,
+						"error",
+					);
+				};
+				thread.finalizeIsolation = async (
+					expectedGeneration: number,
+					result?: SingleResult,
+				): Promise<WorktreeFinalization | undefined> => {
+					if (thread.isolation !== "worktree" || !thread.worktree) return undefined;
+					if (thread.generation !== expectedGeneration) return undefined;
+					const finalization = await thread.worktree.finalize();
+					monitor.setIsolation(runId, "worktree", finalization.status);
+					trajectoryState.trajectory.append({
+						kind: "worktree",
+						status: finalization.status,
+						originalCwd: thread.cwd,
+						isolationCwd: thread.executionCwd,
+						worktreePath: finalization.worktreePath,
+						patchPath: finalization.patchPath,
+						integrated: finalization.integrated,
+						error: finalization.error,
+					});
+					if (result) {
+						result.runId = runId;
+						result.isolation = "worktree";
+						result.originalCwd = thread.cwd;
+						result.isolationCwd = thread.executionCwd;
+						result.integrationStatus = finalization.status;
+						result.integrationApplied = finalization.integrated;
+						result.integrationError = finalization.error;
+						result.integrationWorktreePath = finalization.worktreePath;
+						result.integrationPatchPath = finalization.patchPath;
+						result.forkedFromRunId = thread.forkedFromRunId;
+						result.forkChildRunIds = [...thread.forkChildRunIds];
+						if (finalization.status === "retained") {
+							const retained = [
+								finalization.worktreePath ? `worktree ${finalization.worktreePath}` : undefined,
+								finalization.patchPath ? `patch ${finalization.patchPath}` : undefined,
+							].filter(Boolean).join(", ");
+							const integrationMessage = finalization.integrated
+								? `Worktree changes were applied, but cleanup failed${retained ? `; retained ${retained}` : ""}: ${finalization.error ?? "unknown Git cleanup error"}`
+								: `Worktree integration failed${retained ? `; retained ${retained}` : ""}: ${finalization.error ?? "unknown Git integration error"}`;
+							result.exitCode = 1;
+							result.stopReason = "error";
+							result.errorMessage = result.errorMessage
+								? `${result.errorMessage}\n${integrationMessage}`
+								: integrationMessage;
+							result.stderr = result.stderr ? `${result.stderr.trimEnd()}\n${integrationMessage}` : integrationMessage;
+						}
+					}
+					if (finalization.status === "retained") {
+						runtime.retainWorktreeArtifacts(finalization);
+						if (!thread.isolationFailureNotified) {
+							thread.isolationFailureNotified = true;
+							try {
+								thread.notifyIsolationFailure?.(finalization);
+							} catch {
+								/* notification failures do not hide retained artifacts */
+							}
+						}
+					}
+					return finalization;
+				};
+
+				const cleanupTrackedSessionDir = async (sessionDir: string, action: string): Promise<void> => {
+					try {
+						await rm(sessionDir, { recursive: true, force: true });
+						runtime.sessionDirs.delete(sessionDir);
+					} catch (error) {
+						// Keep ownership so shutdown can retry; losing the path here leaks a
+						// cloned session containing retained model context on Windows locks.
+						try {
+							runCtx.ui.notify(
+								`✗ ${action}; retained ${sessionDir} for shutdown cleanup: ${error instanceof Error ? error.message : String(error)}`,
+								"error",
+							);
+						} catch {
+							/* cleanup ownership remains tracked even if the UI is unavailable */
+						}
+					}
+				};
+
+				const discardUnusedWorktree = async (candidate: WorktreeIsolation | undefined): Promise<void> => {
+					if (!candidate) return;
+					try {
+						if (candidate.discard) {
+							await candidate.discard();
+							return;
+						}
+						// Compatibility for externally supplied/test handles. Production handles
+						// expose discard(), so this fallback never integrates a seeded worktree.
+						if (candidate.state === "active") await candidate.finalize();
+					} catch (error) {
+						const retainedPath = existsSync(candidate.worktreePath)
+							? candidate.worktreePath
+							: existsSync(candidate.tempDir)
+								? candidate.tempDir
+								: undefined;
+						const finalization: WorktreeFinalization = {
+							status: "retained",
+							integrated: false,
+							hadChanges: false,
+							...(retainedPath ? { worktreePath: retainedPath } : {}),
+							...(existsSync(candidate.patchPath) ? { patchPath: candidate.patchPath } : {}),
+							error: `Discarding unused continuation failed: ${error instanceof Error ? error.message : String(error)}`,
+						};
+						runtime.retainWorktreeArtifacts(finalization);
+						await persistRecoveryRecords(runtime.configPath, [
+							recoveryRecordFromFinalization(runId, finalization),
+						]).catch(() => undefined);
+						try {
+							thread.notifyIsolationFailure?.(finalization);
+						} catch {
+							/* parent UI may already be shutting down */
+						}
+					}
+				};
+
+				const createContinuationWorktree = async (
+					source: WorktreeIsolation,
+					seedIsIntegrated: boolean,
+				): Promise<WorktreeIsolation> => {
+					if (source.state === "finalizing") {
+						throw new Error(`Run #${runId}'s worktree is still finalizing.`);
+					}
+					const seedCheckpoint = await source.snapshotCheckpoint();
+					return createWorktreeIsolation(thread.cwd, {
+						seedCheckpoint,
+						seedIsIntegrated,
+					});
+				};
+
+				thread.park = async (): Promise<"queued" | "active"> => {
+					if (thread.retired) throw new Error(`Run #${runId} was retired by subagent_stop.`);
+					if (thread.lifecycleOperation) throw new Error(`Run #${runId} is already handling ${thread.lifecycleOperation}.`);
+					if (thread.state === "parked") return "active";
+					const phase = thread.control.getPhase();
+					const queued = thread.state === "queued" && phase === "queued";
+					if (
+						!queued &&
+						((phase === "settled" && thread.state !== "running") ||
+							!["starting", "running", "steering", "interrupting", "retrying", "settled"].includes(phase))
+					) {
+						throw new Error(`Run #${runId} is ${thread.state}; only active work can be parked.`);
+					}
+
+					const version = ++thread.lifecycleVersion;
+					const generation = thread.generation;
+					const completion = thread.generationCompletion;
+					const controller = thread.queueController;
+					thread.lifecycleOperation = "park";
+					try {
+						if (queued) {
+							thread.control.parkPending();
+							runtime.backgroundQueue.cancel(controller);
+						} else {
+							await thread.control.park();
+							// Auto-fix orchestration has no live RPC attempt once its parent
+							// review settled, so cancel its queue owner explicitly.
+							if (phase === "settled") runtime.backgroundQueue.cancel(controller);
+						}
+						await completion;
+						if (
+							thread.generation !== generation ||
+							thread.lifecycleVersion !== version ||
+							thread.lifecycleOperation !== "park"
+						) {
+							throw new Error(`Run #${runId} changed while parking.`);
+						}
+						thread.state = "parked";
+						thread.queueController = undefined;
+						runtime.runControllers.delete(runId);
+						monitor.setStatus(runId, "parked");
+						return queued ? "queued" : "active";
+					} finally {
+						if (thread.lifecycleVersion === version && thread.lifecycleOperation === "park") {
+							thread.lifecycleOperation = undefined;
+						}
+					}
+				};
+
+				thread.resume = async (objective?: string, resumeCtx?: ExtensionContext): Promise<SingleResult> => {
+					const requestedObjective = objective?.trim();
+					if (!runtime.sessionActive || runtime.threads.get(runId) !== thread) {
+						return failedStartResult(thread.agentName, thread.task, `Run #${runId} belongs to a parent session that has shut down.`);
+					}
+					if (objective !== undefined && !requestedObjective) {
+						return failedStartResult(thread.agentName, thread.task, "resume objective must be non-blank when provided.");
+					}
+					if (thread.retired) return failedStartResult(thread.agentName, thread.task, `Run #${runId} was retired by subagent_stop.`);
+					if (thread.lifecycleOperation) {
+						return failedStartResult(thread.agentName, thread.task, `Run #${runId} is already ${thread.lifecycleOperation === "resume" ? "resuming" : "being forked"}.`);
+					}
+					if (!["parked", "completed", "failed"].includes(thread.state)) {
+						return failedStartResult(thread.agentName, thread.task, `Run #${runId} is ${thread.state}; it must be parked or settled before resume.`);
+					}
+
+					// Lifecycle CAS: claim synchronously before the first await, then cancel
+					// and fully quiesce any superseded queue/process before cloning or
+					// reusing its session. A second resume/fork sees this claim immediately.
+					const previousState = thread.state;
+					const previousSessionId = thread.sessionId;
+					const previousSessionDir = thread.sessionDir;
+					const previousExecutionCwd = thread.executionCwd;
+					const reservation: ResumeReservation = {
+						version: ++thread.lifecycleVersion,
+						generation: thread.generation,
+						sessionId: previousSessionId,
+						sessionDir: previousSessionDir,
+					};
+					thread.lifecycleOperation = "resume";
+					thread.state = "resuming";
+					const finishPreflight = beginPreflight();
+					const supersededController = thread.queueController;
+					runtime.backgroundQueue.cancel(supersededController);
+					runtime.runControllers.delete(runId);
+
+					let continuationWorktree: WorktreeIsolation | undefined;
+					let clonedSession: Awaited<ReturnType<typeof forkRetainedSession>> | undefined;
+					try {
+						await thread.generationCompletion;
+						if (!ownsResumeReservation(thread, reservation)) {
+							return failedStartResult(
+								thread.agentName,
+								thread.task,
+								thread.retired
+									? `Run #${runId} was retired by subagent_stop; no new generation was started.`
+									: `Run #${runId} changed while resume was preparing; no new generation was started.`,
+							);
+						}
+						thread.state = "resuming";
+						const currentCtx = resumeCtx ?? runCtx;
+						let seed: SessionSeed | undefined;
+						if (thread.isolation === "worktree" && thread.worktree?.state !== "active") {
+							if (!thread.worktree) throw new Error(`Run #${runId} has no isolated worktree checkpoint.`);
+							const seedAlreadyIntegrated =
+								thread.worktree.state === "integrated" ||
+								thread.worktree.state === "no_changes" ||
+								thread.lastResult?.integrationApplied === true;
+							continuationWorktree = await createContinuationWorktree(thread.worktree, seedAlreadyIntegrated);
+							if (!ownsResumeReservation(thread, reservation)) {
+								throw new Error(`Run #${runId} changed while its continuation worktree was being created.`);
+							}
+							seed = { worktree: continuationWorktree };
+							if (previousSessionId && previousSessionDir) {
+								clonedSession = await forkRetainedSession({
+									cwd: previousExecutionCwd,
+									targetCwd: continuationWorktree.cwd,
+									sessionDir: previousSessionDir,
+									sessionId: previousSessionId,
+								});
+								runtime.sessionDirs.add(clonedSession.sessionDir);
+								if (!ownsResumeReservation(thread, reservation)) {
+									throw new Error(`Run #${runId} changed while its retained session was being cloned.`);
+								}
+								seed.sessionId = clonedSession.sessionId;
+								seed.sessionDir = clonedSession.sessionDir;
+							}
+						}
+
+						const currentConfig = await loadConfig(runtime.configPath);
+						if (!ownsResumeReservation(thread, reservation)) {
+							throw new Error(`Run #${runId} changed while resume configuration was loading.`);
+						}
+						runtime.backgroundQueue.setConcurrency(currentConfig.maxConcurrency);
+						const currentAgents = discoverAgents(currentCtx.cwd, {
+							scope: currentConfig.agentScope,
+							enabledNames: currentConfig.enabledAgents,
+							projectTrusted: currentCtx.isProjectTrusted?.() === true,
+						}).agents;
+						const nextTask = requestedObjective ?? thread.task;
+						const pending = await startBackground(
+							thread.agentName,
+							nextTask,
+							thread.cwd,
+							thread.vision,
+							thread.isolation,
+							thread,
+							objective !== undefined,
+							{
+								ctx: currentCtx,
+								config: currentConfig,
+								agents: currentAgents,
+								sessionRef: currentModelRef(currentCtx),
+							},
+							seed,
+							reservation,
+						);
+						if (pending.exitCode !== -1) {
+							if (clonedSession) {
+								await cleanupTrackedSessionDir(
+									clonedSession.sessionDir,
+									`Could not discard failed resume session clone for run #${runId}`,
+								);
+							}
+							await discardUnusedWorktree(continuationWorktree);
+							if (ownsResumeReservation(thread, reservation)) thread.state = previousState;
+							return pending;
+						}
+
+						// The cloned branch replaces the removed-worktree session for this
+						// logical id. Keep an undeletable old dir in runtime cleanup if needed.
+						if (clonedSession && previousSessionDir && previousSessionDir !== clonedSession.sessionDir) {
+							try {
+								await rm(previousSessionDir, { recursive: true, force: true });
+								runtime.sessionDirs.delete(previousSessionDir);
+							} catch {
+								/* shutdown retries cleanup of the old retained branch */
+							}
+						}
+						return pending;
+					} catch (error) {
+						if (clonedSession) {
+							await cleanupTrackedSessionDir(
+								clonedSession.sessionDir,
+								`Could not discard interrupted resume session clone for run #${runId}`,
+							);
+						}
+						await discardUnusedWorktree(continuationWorktree);
+						if (ownsResumeReservation(thread, reservation)) {
+							thread.state = previousState;
+							thread.sessionId = previousSessionId;
+							thread.sessionDir = previousSessionDir;
+							thread.executionCwd = previousExecutionCwd;
+						}
+						return failedStartResult(
+							thread.agentName,
+							requestedObjective ?? thread.task,
+							`Could not resume run #${runId}: ${error instanceof Error ? error.message : String(error)}`,
+						);
+					} finally {
+						finishPreflight();
+						if (
+							thread.lifecycleOperation === "resume" &&
+							thread.lifecycleVersion === reservation.version
+						) {
+							thread.lifecycleOperation = undefined;
+						}
+					}
+				};
+
+				thread.fork = async (objective?: string, forkCtx?: ExtensionContext): Promise<SingleResult> => {
+					const forkObjective = objective?.trim();
+					if (!runtime.sessionActive || runtime.threads.get(runId) !== thread) {
+						return failedStartResult(thread.agentName, thread.task, `Run #${runId} belongs to a parent session that has shut down.`);
+					}
+					if (objective !== undefined && !forkObjective) {
+						return failedStartResult(thread.agentName, thread.task, "fork objective must be non-blank when provided.");
+					}
+					if (thread.retired || thread.state === "stopped") {
+						return failedStartResult(thread.agentName, thread.task, `Run #${runId} was retired by subagent_stop and cannot be forked.`);
+					}
+					if (thread.lifecycleOperation) {
+						return failedStartResult(thread.agentName, thread.task, `Run #${runId} is already ${thread.lifecycleOperation === "resume" ? "resuming" : "being forked"}.`);
+					}
+					if (thread.state === "queued" && !thread.sessionId) {
+						return failedStartResult(thread.agentName, thread.task, `Run #${runId} is queued and has no retained session to fork.`);
+					}
+					if (["queued", "running", "steering", "interrupting"].includes(thread.state)) {
+						return failedStartResult(thread.agentName, thread.task, `Run #${runId} is active; park it first with subagent_control { action: "park", id: ${runId} }, then fork the stable session.`);
+					}
+					if (!["parked", "completed", "failed"].includes(thread.state)) {
+						return failedStartResult(thread.agentName, thread.task, `Run #${runId} is ${thread.state} and has no forkable retained checkpoint.`);
+					}
+					if (!thread.sessionId || !thread.sessionDir) {
+						return failedStartResult(thread.agentName, thread.task, `Run #${runId} has no retained session to fork (it may have been parked before starting).`);
+					}
+					if (thread.isolation === "worktree") {
+						const worktreeState = thread.worktree?.state;
+						const seedIntegrated =
+							worktreeState === "integrated" ||
+							worktreeState === "no_changes" ||
+							thread.lastResult?.integrationApplied === true;
+						if (!seedIntegrated) {
+							return failedStartResult(
+								thread.agentName,
+								thread.task,
+								`Run #${runId}'s isolated checkpoint has not been integrated. Resume and settle it before forking so its seed is applied exactly once.`,
+							);
+						}
+					}
+
+					// Same lifecycle CAS as resume: a concurrent resume/fork cannot consume
+					// or clone this session while the branch copy is in progress.
+					const forkVersion = ++thread.lifecycleVersion;
+					const forkGeneration = thread.generation;
+					const forkSessionId = thread.sessionId;
+					const forkSessionDir = thread.sessionDir;
+					const ownsFork = (): boolean =>
+						runtime.sessionActive &&
+						runtime.threads.get(runId) === thread &&
+						!thread.retired &&
+						thread.lifecycleOperation === "fork" &&
+						thread.lifecycleVersion === forkVersion &&
+						thread.generation === forkGeneration &&
+						thread.sessionId === forkSessionId &&
+						thread.sessionDir === forkSessionDir;
+					thread.lifecycleOperation = "fork";
+					const finishPreflight = beginPreflight();
+					let childWorktree: WorktreeIsolation | undefined;
+					let forkedSession: Awaited<ReturnType<typeof forkRetainedSession>> | undefined;
+					try {
+						await thread.generationCompletion;
+						if (!ownsFork()) {
+							return failedStartResult(thread.agentName, thread.task, `Run #${runId} changed while fork was preparing; no child was started.`);
+						}
+						const currentCtx = forkCtx ?? runCtx;
+						if (thread.isolation === "worktree") {
+							if (!thread.worktree) throw new Error(`Run #${runId} has no isolated worktree checkpoint.`);
+							const seedAlreadyIntegrated =
+								thread.worktree.state === "integrated" ||
+								thread.worktree.state === "no_changes" ||
+								thread.lastResult?.integrationApplied === true;
+							childWorktree = await createContinuationWorktree(thread.worktree, seedAlreadyIntegrated);
+							if (!ownsFork()) throw new Error(`Run #${runId} changed while its fork worktree was being created.`);
+						}
+						forkedSession = await forkRetainedSession({
+							cwd: thread.executionCwd,
+							targetCwd: childWorktree?.cwd ?? thread.cwd,
+							sessionDir: thread.sessionDir,
+							sessionId: thread.sessionId,
+						});
+						runtime.sessionDirs.add(forkedSession.sessionDir);
+						if (!ownsFork()) throw new Error(`Run #${runId} changed while its retained session was being forked.`);
+						const currentConfig = await loadConfig(runtime.configPath);
+						if (!ownsFork()) throw new Error(`Run #${runId} changed while fork configuration was loading.`);
+						runtime.backgroundQueue.setConcurrency(currentConfig.maxConcurrency);
+						const currentAgents = discoverAgents(currentCtx.cwd, {
+							scope: currentConfig.agentScope,
+							enabledNames: currentConfig.enabledAgents,
+							projectTrusted: currentCtx.isProjectTrusted?.() === true,
+						}).agents;
+						if (!ownsFork()) throw new Error(`Run #${runId} changed while fork was preparing; no child was started.`);
+						const childTask = forkObjective ?? thread.task;
+						const child = await startBackground(
+							thread.agentName,
+							childTask,
+							thread.cwd,
+							thread.vision,
+							thread.isolation,
+							undefined,
+							false,
+							{
+								ctx: currentCtx,
+								config: currentConfig,
+								agents: currentAgents,
+								sessionRef: currentModelRef(currentCtx),
+							},
+							{
+								sessionId: forkedSession.sessionId,
+								sessionDir: forkedSession.sessionDir,
+								prompt: forkObjective ?? FORK_CONTINUATION_PROMPT,
+								worktree: childWorktree,
+								forkedFromRunId: runId,
+								forkObjective,
+								modelPool: [...thread.modelPool],
+								thinkingLevel: thread.thinkingLevel,
+							},
+						);
+						if (child.exitCode !== -1 || child.runId === undefined) {
+							await cleanupTrackedSessionDir(
+								forkedSession.sessionDir,
+								`Could not discard failed fork session clone for run #${runId}`,
+							);
+							await discardUnusedWorktree(childWorktree);
+							return child;
+						}
+
+						// Once the independent child is enqueued it remains valid even if the
+						// source is retired; just skip source-side relationship mutation.
+						if (!ownsFork()) return child;
+						const childRunId = child.runId;
+						if (!thread.forkChildRunIds.includes(childRunId)) thread.forkChildRunIds.push(childRunId);
+						const childThread = runtime.threads.get(childRunId);
+						if (childThread) childThread.forkedFromRunId = runId;
+						monitor.setForkRelation(runId, childRunId);
+						trajectoryStore.get(runId).trajectory.append({
+							kind: "fork",
+							sourceRunId: runId,
+							childRunId,
+							objective: forkObjective,
+						});
+						const sourceResult = runtime.settledRuns.get(runId) ?? thread.lastResult;
+						if (sourceResult) sourceResult.forkChildRunIds = [...thread.forkChildRunIds];
+						return child;
+					} catch (error) {
+						if (forkedSession) {
+							await cleanupTrackedSessionDir(
+								forkedSession.sessionDir,
+								`Could not discard interrupted fork session clone for run #${runId}`,
+							);
+						}
+						await discardUnusedWorktree(childWorktree);
+						return failedStartResult(
+							thread.agentName,
+							forkObjective ?? thread.task,
+							`Could not fork retained session for run #${runId}: ${error instanceof Error ? error.message : String(error)}`,
+						);
+					} finally {
+						finishPreflight();
+						if (thread.lifecycleVersion === forkVersion && thread.lifecycleOperation === "fork") {
+							thread.lifecycleOperation = undefined;
+						}
+					}
+				};
+
+				const onLive = makeLiveHandler(runId, runId, generation);
+				const queueController = runtime.backgroundQueue.enqueue(
+					async (backgroundSignal) => {
+						if (runtime.threads.get(runId)?.generation !== generation) return;
+						let result: SingleResult;
+						try {
+							result = await runSingleAgentWithModelFallback(
+								{
+									defaultCwd: executionCwd,
+									agent: pool.agent,
+									agentName,
+									task,
+									cwd: executionCwd,
+									thinkingLevel,
+									signal: backgroundSignal,
+									onLive,
+									control,
+									makeDetails: makeDetails("single", true),
+									idleTimeoutMs: runConfig.idleTimeoutSec * 1000,
+									...(priorSessionId && priorSessionDir
+										? {
+											sessionId: priorSessionId,
+											sessionDir: priorSessionDir,
+											stdinText: seed?.prompt ?? (newObjectiveOnResume
+												? task
+												: buildResumePrompt(priorTask ?? task, buildFallbackResumeReason())),
+										}
+										: {}),
+								},
+								pool.fallbackModelRefs,
+							);
+						} catch (error) {
+							const errorMessage = error instanceof Error ? error.message : String(error);
+							result = {
+								...pending,
+								task: control.getObjective(),
+								exitCode: 1,
+								stderr: errorMessage,
+								stopReason: backgroundSignal.aborted ? "aborted" : "error",
+								errorMessage,
+								dispatchFailed: true,
+							};
+						}
+
+						// A stale process/generation may finish after a park/resume race. It owns
+						// no monitor mutation, result registration, or completion delivery.
+						if (runtime.threads.get(runId)?.generation !== generation) return;
+						result.runId = runId;
+						result.isolation = isolation;
+						result.originalCwd = originalCwd;
+						result.isolationCwd = executionCwd;
+						result.forkedFromRunId = thread.forkedFromRunId;
+						result.forkChildRunIds = [...thread.forkChildRunIds];
+						thread.queueController = undefined;
+						runtime.runControllers.delete(runId);
+						thread.task = result.task;
+						thread.sessionId = result.sessionId;
+						thread.sessionDir = result.sessionDir;
+						thread.lastResult = result;
+						runtime.retainSession(result);
+						monitor.setModel(runId, result.model, result.modelFallbackFrom);
+
+						// Destructive stop owns publication once it has synchronously claimed
+						// the lifecycle. Leave the partial result/session on the thread; the
+						// stop path waits for this queue task, finalizes isolation, and emits
+						// exactly one aborted result.
+						if (thread.lifecycleOperation === "stop") return;
+
+						if (result.parked) {
+							thread.state = "parked";
+							monitor.setStatus(runId, "parked");
+							runtime.settledRuns.delete(runId);
+							return;
+						}
+
+						if (thread.retireOnSettle) runtime.retireThreadSession(thread);
+						const wantsFixLoop = shouldTriggerFixLoop(result, runConfig);
+						if (wantsFixLoop && isolation === "shared" && runtime.sessionActive) {
+							thread.state = "running";
+							finishRun(runId, "done", { silent: true, retain: true });
+							monitor.setAnnotation(runId, "auto-fix chain running");
+							startFixLoop(result, `fix-${runId}`, runId, thread.executionCwd, vision);
+							return;
+						}
+						// Claim terminal settlement synchronously before the first slow await.
+						// Park therefore either wins while RPC is still active, or is rejected
+						// once settlement owns the generation. Destructive stop may supersede
+						// this reservation; publication is revalidated after Git finalization.
+						const settlementVersion = ++thread.lifecycleVersion;
+						thread.lifecycleOperation = "settle";
+						const ownsSettlement = (): boolean =>
+							runtime.threads.get(runId) === thread &&
+							thread.generation === generation &&
+							thread.lifecycleVersion === settlementVersion &&
+							thread.lifecycleOperation === "settle" &&
+							!thread.retired;
+						try {
+							// Worktree isolation is rejected for reviewers, the only role that can
+							// trigger auto-fix. Keep that invariant explicit: an isolated result is
+							// finalized once here and can never start a chain that would integrate
+							// the same worktree early.
+							await thread.finalizeIsolation(generation, result);
+							if (!ownsSettlement()) return;
+
+							const failed = isFailedResult(result);
+							thread.state = failed ? "failed" : "completed";
+							// Stamp the terminal monitor state before projecting it. This gives every
+							// path a fixed endedAt even when the row is removed immediately.
+							monitor.setStatus(runId, failed ? "failed" : "done");
+							trajectoryState.trajectory.append({
+								kind: "settled",
+								status: failed ? "failed" : "done",
+								model: result.model,
+								isolation,
+								...(result.integrationStatus && result.integrationStatus !== "pending"
+									? { integrationStatus: result.integrationStatus }
+									: {}),
+							});
+							if (!runtime.sessionActive || !ownsSettlement()) return;
+
+							const modelLevel = failed && isModelLevelFailure(result);
+							const dispatchFailed = result.dispatchFailed === true;
+							finishRun(runId, failed ? "failed" : "done", modelLevel || dispatchFailed ? { silent: true } : undefined);
+							runtime.registerRunResult(runId, result);
+							const completion: CompletionMessageItem = {
+								agent: result.agent,
+								block: modelLevel
+									? `${formatCompletionBlock(result, runConfig.maxResultLines, runCtx.cwd)}\n\n${modelLevelTakeoverNote(result, { runId })}`
+									: formatCompletionBlock(result, runConfig.maxResultLines, runCtx.cwd),
+								triggerTurn: completionTriggersTurn(result, runConfig.notifyOnReviewPass),
+							};
+							if (modelLevel) {
+								runCtx.ui.notify(`✗ ${result.agent} dispatch failed: model unavailable or broken — task handed to the main window`, "error");
+							} else if (dispatchFailed) {
+								runCtx.ui.notify(`✗ ${result.agent} dispatch failed: ${result.errorMessage ?? "dispatch crashed"}`, "error");
+							}
+							if (failed) {
+								runtime.sendCompletionGroup([completion]);
+								runtime.completionBatcher.flush();
+							} else {
+								runtime.completionBatcher.push(completion);
+							}
+						} finally {
+							if (ownsSettlement()) thread.lifecycleOperation = undefined;
+						}
+					},
+					() => {
+						if (runtime.threads.get(runId)?.generation !== generation) return;
+						// Queued park/stop owns publication and may still be finalizing an
+						// isolated worktree. Do not expose a terminal monitor/trajectory state
+						// before that owner records the checkpoint or aborted result.
+						if (thread.lifecycleOperation === "park" || thread.lifecycleOperation === "stop") return;
+						runtime.runControllers.delete(runId);
+						thread.queueController = undefined;
+						if (thread.state === "parked") {
+							monitor.setStatus(runId, "parked");
+							return;
+						}
+						thread.state = "stopped";
+						monitor.setStatus(runId, "failed");
+						trajectoryState.trajectory.append({ kind: "settled", status: "stopped", model: monitor.findRun(runId)?.model, isolation });
+						if (!runtime.sessionActive) {
+							monitor.removeRun(runId);
+							return;
+						}
+						finishRun(runId, "failed");
+					},
+					async (error) => {
+						if (runtime.threads.get(runId)?.generation !== generation) return;
+						// Queue-level crashes use the same settlement reservation as ordinary
+						// results. A concurrent destructive stop may supersede it while slow
+						// worktree finalization is running, in which case stop publishes once.
+						if (thread.lifecycleOperation === "stop") return;
+						const settlementVersion = ++thread.lifecycleVersion;
+						thread.lifecycleOperation = "settle";
+						const ownsSettlement = (): boolean =>
+							runtime.threads.get(runId) === thread &&
+							thread.generation === generation &&
+							thread.lifecycleVersion === settlementVersion &&
+							thread.lifecycleOperation === "settle" &&
+							!thread.retired;
+						try {
+							const crashed: SingleResult = {
+								...dispatchFailedResult(pool.agent, control.getObjective(), error, thinkingLevel),
+								runId,
+								isolation,
+								originalCwd,
+								isolationCwd: executionCwd,
+								forkedFromRunId: thread.forkedFromRunId,
+							};
+							await thread.finalizeIsolation(generation, crashed);
+							if (!ownsSettlement()) return;
+							thread.state = "failed";
+							monitor.setStatus(runId, "failed");
+							trajectoryState.trajectory.append({
+								kind: "settled",
+								status: "failed",
+								model: crashed.model,
+								isolation,
+								...(crashed.integrationStatus && crashed.integrationStatus !== "pending"
+									? { integrationStatus: crashed.integrationStatus }
+									: {}),
+							});
+							finishRun(runId, "failed", { silent: true });
+							runtime.registerRunResult(runId, crashed);
+							runtime.runControllers.delete(runId);
+							thread.queueController = undefined;
+							if (!runtime.sessionActive || !ownsSettlement()) return;
+							try {
+								runCtx.ui.notify(`✗ ${agent.name} dispatch failed: ${crashed.errorMessage}`, "error");
+								runtime.sendCompletionGroup([
+									{
+										agent: agent.name,
+										block: formatCompletionBlock(crashed, runConfig.maxResultLines, runCtx.cwd),
+										triggerTurn: true,
+									},
+								]);
+								runtime.completionBatcher.flush();
+							} catch {
+								/* a second delivery failure must not throw through the queue */
+							}
+						} finally {
+							if (ownsSettlement()) thread.lifecycleOperation = undefined;
+						}
+					},
+				);
+				thread.queueController = queueController;
+				thread.generationCompletion = runtime.backgroundQueue.waitForTask(queueController);
+				runtime.runControllers.set(runId, queueController);
+				return pending;
+			};
+
+			// Sub-agents intentionally detach from the foreground turn. This makes the
+			// editor available immediately; completion messages later wake the main agent.
+			if (params.tasks && params.tasks.length > 0) {
+				if (params.tasks.length > config.maxConcurrency) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Too many parallel tasks (${params.tasks.length}). Max is ${config.maxConcurrency} (configurable via /subagents-setup).`,
+							},
+						],
+						details: makeDetails("parallel", true)([]),
+					};
+				}
+
+				const results: SingleResult[] = [];
+				// Preserve caller order (and deterministic completion batching) while
+				// preparing each isolated filesystem before its queue entry can start.
+				for (const item of params.tasks) {
+					results.push(await startBackground(
+						item.agent,
+						item.task,
+						item.cwd,
+						item.vision === true,
+						defaultIsolationMode("parallel", item.agent, item.isolation as IsolationMode | undefined),
+					));
+				}
+				const startedRuns = results.filter((result) => result.exitCode === -1);
+				const started = startedRuns.length;
+				const startedRefs = startedRuns.map((result) =>
+					result.runId === undefined ? result.agent : `#${result.runId} ${result.agent}`,
+				);
+				const failureLines = results.flatMap((result, index) => {
+					if (result.exitCode === -1) return [];
+					const reason = getResultOutput(result).trim() || "unknown startup failure";
+					return [
+						`- tasks[${index}] (${params.tasks![index]!.agent}) failed to start: ${reason.replace(/\n/g, "\n  ")}`,
+					];
+				});
+				if (started === 0) {
+					// Pi marks custom-tool failures only when execute throws; returning an
+					// `isError` property is still a successful AgentToolResult.
+					throw new Error(`No background subagents were started.\n${failureLines.join("\n")}`);
+				}
+				const text = [
+					`Started ${started} background subagent${started === 1 ? "" : "s"}: ${startedRefs.join(", ")}. Results will automatically resume the main agent when ready.`,
+					...(failureLines.length > 0
+						? [`${failureLines.length} task${failureLines.length === 1 ? "" : "s"} failed before launch:`, ...failureLines]
+						: []),
+				].join("\n");
+				return {
+					content: [{ type: "text", text }],
+					details: makeDetails("parallel", true)(results),
+					terminate: true,
+				};
+			}
+
+			const result = await startBackground(
+				params.agent as string,
+				params.task as string,
+				params.cwd,
+				params.vision === true,
+				defaultIsolationMode("single", params.agent as string, params.isolation as IsolationMode | undefined),
+			);
+			if (result.exitCode !== -1) {
+				throw new Error(getResultOutput(result));
+			}
+			const runRef = result.runId === undefined ? result.agent : `#${result.runId} ${result.agent}`;
+			return {
+				content: [{ type: "text", text: `Started ${runRef} in the background. Its result will automatically resume the main agent when ready.` }],
+				details: makeDetails("single", true)([result]),
+				terminate: true,
+			};
+
+		},
+
+		renderCall(args, theme) {
+			if (args.tasks && args.tasks.length > 0) {
+				let text = `${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${args.tasks.length})`)}`;
+				for (const t of args.tasks.slice(0, 4)) {
+					const preview = formatTaskSummary(t.task, 48);
+					const isolation = defaultIsolationMode("parallel", t.agent, t.isolation) === "worktree" ? " [worktree]" : "";
+					text += `\n  ${theme.fg("accent", t.agent)}${theme.fg("dim", isolation)} ${theme.fg("dim", preview)}`;
+				}
+				if (args.tasks.length > 4) text += `\n  ${theme.fg("dim", `… +${args.tasks.length - 4} more`)}`;
+				return new Text(text, 0, 0);
+			}
+			const task: string = args.task ?? "";
+			const preview = formatTaskSummary(task, 60);
+			const isolation = args.isolation === "worktree" ? " [worktree]" : "";
+			return new Text(
+				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent ?? "?")}${theme.fg("dim", isolation)} ${theme.fg("dim", preview)}`,
+				0,
+				0,
+			);
+		},
+
+		renderResult(result, _options, theme) {
+			const details = result.details as SubagentDetails | undefined;
+			if (!details || details.results.length === 0) return new Text(theme.fg("dim", "(no output)"), 0, 0);
+
+			if (details.mode === "single") {
+				const r = details.results[0];
+				const pending = r.exitCode === -1;
+				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
+				const usage = formatUsage(r.usage);
+				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (pool fallback from ${r.modelFallbackFrom})` : ""}`;
+				const isolation = r.isolation === "worktree" ? ` · worktree ${r.integrationStatus ?? "active"}` : "";
+				const runId = r.runId === undefined ? "" : `${theme.fg("dim", `#${r.runId}`)} `;
+				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${runId}${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${isolation}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`;
+				return new Text(line, 0, 0);
+			}
+
+			// Parallel mode: header + one compact line per agent
+			const lines: string[] = [
+				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${details.results.length})`)}`,
+			];
+			for (const r of details.results) {
+				const pending = r.exitCode === -1;
+				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
+				const usage = formatUsage(r.usage);
+				const model = `${r.model ?? "?"}${r.modelFallbackFrom ? ` (pool fallback from ${r.modelFallbackFrom})` : ""}`;
+				const isolation = r.isolation === "worktree" ? ` · worktree ${r.integrationStatus ?? "active"}` : "";
+				const runId = r.runId === undefined ? "" : `${theme.fg("dim", `#${r.runId}`)} `;
+				lines.push(`  ${icon} ${runId}${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${isolation}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`);
+			}
+			return new Text(lines.join("\n"), 0, 0);
+		},
+	});
+}