@ferris1225/pi-subagents 4.1.1 → 4.1.2

package/src/dispatch.ts

@@ -1,704 +1,637 @@
-/**
- * The `subagent` tool: dispatches explorer/worker/cleaner/reviewer agents as isolated pi
- * child processes, single or parallel. Owns the public dispatch contract,
- * per-run status tracking, the auto-fix chain (REVIEW_FAIL → worker → re-review),
- * and completion delivery. Stable thread generations live in thread-lifecycle.ts.
- */
-
-import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
-import { realpath } from "node:fs/promises";
-import { resolve } from "node:path";
-import { Type } from "typebox";
-import { discoverAgents } from "./agents.ts";
-import { loadConfig } from "./config.ts";
-import {
-	failedStartResult,
-	formatCompletionBlock,
-	formatUsage,
-	modelLevelTakeoverNote,
-	queuedResult,
-} from "./format.ts";
-import {
-	buildFixTaskBrief,
-	buildReReviewBrief,
-	formatChainSummary,
-	type ChainStep,
-} from "./fixloop.ts";
-import {
-	formatTaskSummary,
-	formatToolActivity,
-	monitor,
-	statusIcon,
-	sumUsage,
-	type RunChainMeta,
-} from "./monitor.ts";
-import type { SubagentRuntime } from "./runtime.ts";
-import {
-	getResultOutput,
-	isFailedResult,
-	isModelLevelFailure,
-	reviewVerdict,
-	runSingleAgentWithMainFallback,
-	type SingleResult,
-	type SubagentDetails,
-	type SubagentLiveEvent,
-} from "./spawn.ts";
-import {
-	createBackgroundDispatcher,
-	resolveDispatchModelRoute,
-} from "./thread-lifecycle.ts";
-import { resolveWorktreeTarget, type IsolationMode } from "./worktree.ts";
-
-export { FORK_CONTINUATION_PROMPT, isWorktreeCapableAgent } from "./thread-lifecycle.ts";
-
-const NON_BLANK_TASK_OPTIONS = { minLength: 1, pattern: "\\S" } as const;
-
-const ISOLATION_DESCRIPTION =
-	"Filesystem isolation: shared uses the caller's working tree; worktree creates a detached temporary Git worktree (write-capable agents, including worker and cleaner, 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" })),
-	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)" })),
-	isolation: IsolationSchema,
-});
-
-export function defaultIsolationMode(mode: "single" | "parallel", agentName: string, requested?: IsolationMode): IsolationMode {
-	if (requested) return requested;
-	return mode === "parallel" && agentName === "worker" ? "worktree" : "shared";
-}
-
-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);
-		}
-	};
-}
-
-export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime): void {
-	pi.registerTool({
-		name: "subagent",
-		label: "Subagent",
-		description: [
-			"Dispatch enabled specialized agents as isolated leaf Pi child processes, singly or in parallel.",
-			"Built-ins: explorer for broad read-only reconnaissance; worker for implementation; cleaner only for explicitly authorized cleanup/removal/simplification edits; reviewer for generic read-only assessments and pre-commit gates.",
-			"Work starts in the background; completion automatically resumes the main agent and is already shown to the user, so do not poll or restate it. Give each child a self-contained brief because it has no conversation memory.",
-			"Single tasks default to shared; parallel workers default to detached Git worktrees. Only write-capable agents can use worktree isolation, and failures never fall back silently to shared.",
-			"A selected-model or provider failure continues the retained session on the current main model; ordinary tool/task failures do not.",
-			"Use subagent_control to steer, retarget, park, resume, or fork by stable run id.",
-		].join(" "),
-		promptSnippet:
-			"Dispatch isolated background agents: explorer (recon), worker (implementation), cleaner (authorized cleanup), reviewer (read-only assessment/gate); results resume automatically. Use direct tools for trivial work.",
-		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 },
-			): void => {
-				monitor.setStatus(runId, status); // stamps endedAt for the elapsed time
-				const run = monitor.removeRun(runId);
-				if (!run) return; // already finished — stay idempotent
-				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 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, 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);
-							monitor.setThinking(runId, e.thinking);
-							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,
-				projectTrusted: ctx.isProjectTrusted?.() === true,
-			});
-			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,
-			): Promise<{ runId?: number; result: SingleResult }> => {
-				const agent = agents.find((candidate) => candidate.name === agentName);
-				if (!agent) return { result: failedStartResult(agentName, task, `Unknown agent: "${agentName}".`) };
-				const route = resolveDispatchModelRoute(agent, config, ctx);
-				const thinkingLevel = route.thinkingLevel;
-				const runId = monitor.addRun(agent.name, task, route.agent.model, thinkingLevel, meta);
-				const onLive = makeLiveHandler(runId);
-				try {
-					const result = await runSingleAgentWithMainFallback(
-						{
-							defaultCwd: executionCwd,
-							cwd: executionCwd,
-							agent: route.agent,
-							agentName,
-							task,
-							thinkingLevel,
-							thinkingLevelForModel: route.thinkingLevelForModel,
-							signal,
-							onLive,
-							makeDetails: makeDetails("single", true),
-							idleTimeoutMs: config.idleTimeoutSec * 1000,
-						},
-						route.mainFallbackRef,
-					);
-					result.runId = runId;
-					result.projectCwd = executionCwd;
-					result.isolation = "shared";
-					runtime.retainSession(result);
-					monitor.setModel(runId, result.model, result.modelFallbackFrom);
-					monitor.setThinking(runId, result.thinking);
-					// The parent row represents the chain. Internal rounds leave live
-					// status as soon as they settle; their reports remain addressable by id.
-					finishRun(runId, isFailedResult(result) ? "failed" : "done", { silent: true });
-					runtime.registerRunResult(runId, result);
-					return { runId, result };
-				} catch (error) {
-					finishRun(runId, "failed", { silent: true });
-					const errorMessage = error instanceof Error ? error.message : String(error);
-					const crashed: SingleResult = {
-						...queuedResult(route.agent, task, thinkingLevel),
-						runId,
-						projectCwd: executionCwd,
-						isolation: "shared",
-						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 any in-flight monitor row belonging to an auto-fix chain; the
-			 * 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,
-			): 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) => {
-						if (!ownsParent()) return;
-						// The parent id belongs to the stable logical thread and will point at
-						// the chain outcome. Archive the triggering review under its own id so
-						// every id advertised by the chain summary resolves to that exact step.
-						const initialStepRunId = monitor.reserveRunId();
-						const initialStepResult: SingleResult = {
-							...initialReviewerResult,
-							runId: initialStepRunId,
-						};
-						runtime.registerRunResult(initialStepRunId, initialStepResult);
-						const chain: ChainStep[] = [
-							{ runId: initialStepRunId, result: initialStepResult, relation: "initial review" },
-						];
-						let lastReviewer = initialStepResult;
-						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}`,
-								parentRunId,
-							});
-							// 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, workerStep.result);
-							const reviewStep = await launchInLoop("reviewer", reReviewBrief, executionCwd, signal, {
-								groupId: parentGroupId,
-								relationLabel: `re-review round ${round}`,
-								parentRunId,
-							});
-							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 checkpoint and suppresses an aborted chain delivery.
-						if (controlledParent.state === "parked") {
-							clearOwnedController();
-							removeChainGroup(parentGroupId);
-							monitor.setStatus(parentRunId, "parked");
-							return;
-						}
-						// The chain is done (success, exhaustion, or abort): drop its monitor
-						// rows, then deliver one condensed
-						// summary. Register the parent's final state (the last chain result)
-						// before removal so subagent_wait can resolve it. Clone instead of
-						// mutating: the internal step remains addressable under its own run id.
-						const last = chain[chain.length - 1];
-						const parentResult: SingleResult = {
-							...last.result,
-							runId: parentRunId,
-						};
-						runtime.registerRunResult(parentRunId, parentResult);
-						removeChainGroup(parentGroupId);
-						monitor.removeRun(parentRunId);
-						runtime.retainSession(parentResult);
-						const parentThread = parentThreadAtStart;
-						parentThread.lastResult = parentResult;
-						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";
-						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,
-								usage: sumUsage(chain.map((step) => step.result.usage)),
-							},
-						]);
-						runtime.completionBatcher.flush();
-						clearOwnedController();
-					}),
-					() => {
-						if (!ownsParent()) return;
-						const controlledParent = parentThreadAtStart;
-						clearOwnedController();
-						removeChainGroup(parentGroupId);
-						if (controlledParent.state === "parked") {
-							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,
-									usage: initialReviewerResult.usage,
-								},
-							]);
-							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);
-			};
-
-			const startBackground = createBackgroundDispatcher({
-				runtime,
-				ctx,
-				config,
-				agents,
-				finishRun,
-				makeLiveHandler,
-				makeDetails,
-				startFixLoop,
-			});
-
-			// 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,
-						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,
-				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 ? ` (main after ${r.modelFallbackFrom} failed)` : ""}`;
-				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 ? ` (main after ${r.modelFallbackFrom} failed)` : ""}`;
-				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);
-		},
-	});
-}
+/**
+ * The `subagent` tool: dispatches explorer/worker/cleaner/documenter/reviewer agents as isolated pi
+ * child processes, single or parallel. Owns the public dispatch contract,
+ * per-run status tracking, managed writer → documenter → reviewer workflows,
+ * reviewer auto-fix rounds, and internal step launching. Stable thread
+ * generations, final integration, and completion ownership live in
+ * thread-lifecycle.ts.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Type } from "typebox";
+import { discoverAgents } from "./agents.ts";
+import { loadConfig } from "./config.ts";
+import { formatUsage, queuedResult } from "./format.ts";
+import {
+	buildDocumenterTaskBrief,
+	buildFinalReviewBrief,
+	buildFixTaskBrief,
+	buildPostWriterDocumenterBrief,
+	buildReReviewBrief,
+	buildReviewPassDocumenterBrief,
+	type ChainStep,
+	type ManagedWorkflowOutcome,
+} from "./fixloop.ts";
+import {
+	formatTaskSummary,
+	formatToolActivity,
+	monitor,
+	statusIcon,
+	type RunChainMeta,
+} from "./monitor.ts";
+import type { SubagentRuntime } from "./runtime.ts";
+import {
+	getResultOutput,
+	isFailedResult,
+	reviewVerdict,
+	runSingleAgentWithMainFallback,
+	type SingleResult,
+	type SubagentDetails,
+	type SubagentLiveEvent,
+} from "./spawn.ts";
+import {
+	createBackgroundDispatcher,
+	resolveDispatchModelRoute,
+	withWorktreeSystemPrompt,
+	type ManagedWorkflowRequest,
+} from "./thread-lifecycle.ts";
+import { resolveRepositoryRoot, type IsolationMode } from "./worktree.ts";
+
+export { FORK_CONTINUATION_PROMPT, isWorktreeCapableAgent } from "./thread-lifecycle.ts";
+
+const NON_BLANK_TASK_OPTIONS = { minLength: 1, pattern: "\\S" } as const;
+
+const ISOLATION_DESCRIPTION =
+	"Filesystem isolation: shared uses the caller's working tree; worktree creates a detached temporary Git worktree (write-capable agents, including worker, cleaner, and documenter, 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" })),
+	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)" })),
+	isolation: IsolationSchema,
+});
+
+export function defaultIsolationMode(mode: "single" | "parallel", agentName: string, requested?: IsolationMode): IsolationMode {
+	if (requested) return requested;
+	return mode === "parallel" && agentName === "worker" ? "worktree" : "shared";
+}
+
+const managedRepositoryRootTails = new Map<string, Promise<void>>();
+
+async function canonicalManagedRepositoryRoot(cwd: string): Promise<string> {
+	try {
+		// Repository identity does not depend on HEAD: empty repositories must
+		// serialize root and nested cwd requests under the same lane too.
+		return await resolveRepositoryRoot(cwd);
+	} catch {
+		try {
+			return await realpath(resolve(cwd));
+		} catch {
+			return resolve(cwd);
+		}
+	}
+}
+
+/** Run one operation under the canonical original-repository lane.
+ *
+ * Shared managed generations use the abortable overload for their complete
+ * writer/reviewer workflow. Isolated generations use the non-abortable overload
+ * only for their final worktree apply, so model work remains parallel while the
+ * original checkout mutation cannot race a shared writer or reviewer snapshot.
+ */
+async function runInManagedRepositoryLane<T>(
+	cwd: string,
+	task: () => Promise<T>,
+): Promise<T>;
+async function runInManagedRepositoryLane<T>(
+	cwd: string,
+	task: () => Promise<T>,
+	signal: AbortSignal,
+): Promise<T | undefined>;
+async function runInManagedRepositoryLane<T>(
+	cwd: string,
+	task: () => Promise<T>,
+	signal?: AbortSignal,
+): Promise<T | undefined> {
+	if (signal?.aborted) return undefined;
+	const root = await canonicalManagedRepositoryRoot(cwd);
+	const key = process.platform === "win32" ? root.toLowerCase() : root;
+	const previous = managedRepositoryRootTails.get(key) ?? Promise.resolve();
+	let release!: () => void;
+	const gate = new Promise<void>((resolveGate) => {
+		release = resolveGate;
+	});
+	const tail = previous.catch(() => undefined).then(() => gate);
+	managedRepositoryRootTails.set(key, tail);
+	let onAbort: (() => void) | undefined;
+	try {
+		if (signal) {
+			await Promise.race([
+				previous.catch(() => undefined),
+				new Promise<void>((resolveAborted) => {
+					if (signal.aborted) resolveAborted();
+					else {
+						onAbort = resolveAborted;
+						signal.addEventListener("abort", onAbort, { once: true });
+					}
+				}),
+			]);
+		} else {
+			await previous.catch(() => undefined);
+		}
+		if (signal?.aborted) return undefined;
+		return await task();
+	} finally {
+		if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+		release();
+		// An aborted waiter may finish before the prior owner. Keep its chained
+		// tail installed until that owner also settles, otherwise a newcomer could
+		// observe an empty map and race the still-running workflow.
+		void tail.then(() => {
+			if (managedRepositoryRootTails.get(key) === tail) managedRepositoryRootTails.delete(key);
+		});
+	}
+}
+
+export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime): void {
+	pi.registerTool({
+		name: "subagent",
+		label: "Subagent",
+		description: [
+			"Dispatch enabled specialized agents as isolated leaf Pi child processes, singly or in parallel.",
+			"Built-ins: explorer for broad read-only reconnaissance; worker for implementation; cleaner for explicitly authorized cleanup, removal, simplification, and duplicate-code consolidation; documenter for pre-commit diff sync or explicitly requested whole-codebase comment/README/docs maintenance; reviewer for generic read-only assessments and final gates.",
+			"Work starts in the background; successful top-level writers automatically continue through enabled documenter/reviewer stages and return one final completion. Results resume the main agent and are already shown to the user, so do not poll, duplicate downstream roles, or restate them. Give each child a self-contained brief because it has no conversation memory.",
+			"Single tasks default to shared; parallel workers default to detached Git worktrees. Only write-capable agents can use worktree isolation, and failures never fall back silently to shared.",
+			"A selected-model or provider failure continues the retained session on the current main model; ordinary tool/task failures do not.",
+			"Use subagent_control to steer/retarget an active top-level child, park/stop a managed downstream stage, or resume/fork retained context by stable run id.",
+		].join(" "),
+		promptSnippet:
+			"Dispatch isolated background agents: explorer (recon), worker (implementation), cleaner (authorized cleanup/deduplication), documenter (docs sync), reviewer (read-only assessment/gate); enabled post-writer stages run automatically, results resume automatically, and the workflow delivers once. Use direct tools for trivial work.",
+		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 },
+			): void => {
+				monitor.setStatus(runId, status); // stamps endedAt for the elapsed time
+				const run = monitor.removeRun(runId);
+				if (!run) return; // already finished — stay idempotent
+				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 monitor state; finishing (removeRun + notify) is owned
+			// by the queue task / launchInWorkflow. 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, 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 / launchInWorkflow 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);
+							monitor.setThinking(runId, e.thinking);
+							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,
+				projectTrusted: ctx.isProjectTrusted?.() === true,
+			});
+			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")([]),
+				};
+			}
+
+			/** Launch one workflow-internal child in a fresh model context. It sees the
+			 * parent's exact repository/worktree state and is registered by its own id,
+			 * but never enters top-level lifecycle policy or completion delivery. */
+			const launchInWorkflow = async (
+				request: ManagedWorkflowRequest,
+				agentName: string,
+				task: string,
+				meta: RunChainMeta,
+			): Promise<{ runId: number; result: SingleResult }> => {
+				const agent = request.agents.find((candidate) => candidate.name === agentName);
+				if (!agent) {
+					throw new Error(`Managed workflow requires enabled agent "${agentName}", but discovery did not provide it.`);
+				}
+				const resolvedRoute = resolveDispatchModelRoute(agent, request.config, request.ctx);
+				const route = request.isolation === "worktree"
+					? { ...resolvedRoute, agent: withWorktreeSystemPrompt(resolvedRoute.agent) }
+					: resolvedRoute;
+				const thinkingLevel = route.thinkingLevel;
+				const runId = monitor.addRun(agent.name, task, route.agent.model, thinkingLevel, {
+					...meta,
+					isolation: request.isolation,
+				});
+				const onLive = makeLiveHandler(runId);
+				try {
+					const result = await runSingleAgentWithMainFallback(
+						{
+							defaultCwd: request.executionCwd,
+							cwd: request.executionCwd,
+							agent: route.agent,
+							agentName,
+							task,
+							thinkingLevel,
+							thinkingLevelForModel: route.thinkingLevelForModel,
+							signal: request.signal,
+							onLive,
+							makeDetails: makeDetails("single", true),
+							idleTimeoutMs: request.config.idleTimeoutSec * 1000,
+						},
+						route.mainFallbackRef,
+					);
+					result.runId = runId;
+					result.projectCwd = request.projectCwd;
+					result.isolation = request.isolation;
+					runtime.retainSession(result);
+					monitor.setModel(runId, result.model, result.modelFallbackFrom);
+					monitor.setThinking(runId, result.thinking);
+					finishRun(runId, isFailedResult(result) ? "failed" : "done", { silent: true });
+					runtime.registerRunResult(runId, result);
+					return { runId, result };
+				} catch (error) {
+					finishRun(runId, "failed", { silent: true });
+					const errorMessage = error instanceof Error ? error.message : String(error);
+					const crashed: SingleResult = {
+						...queuedResult(route.agent, task, thinkingLevel),
+						runId,
+						projectCwd: request.projectCwd,
+						isolation: request.isolation,
+						exitCode: 1,
+						stderr: errorMessage,
+						stopReason: request.signal.aborted ? "aborted" : "error",
+						errorMessage,
+						dispatchFailed: true,
+					};
+					runtime.registerRunResult(runId, crashed);
+					return { runId, result: crashed };
+				}
+			};
+
+			/** Drop any in-flight internal row. Normal internal settlement already
+			 * removes rows; this is a cancellation/crash guard. */
+			const removeWorkflowGroup = (groupId: string): void => {
+				for (const run of [...monitor.getRuns()]) {
+					if (run.groupId === groupId) monitor.removeRun(run.id);
+				}
+			};
+
+			/** Run every downstream role inline under the parent generation's queue
+			 * controller. That gives park/stop/shutdown one lifecycle owner and keeps
+			 * isolated worktrees unintegrated until the final reviewer settles. */
+			const runManagedWorkflow = async (
+				request: ManagedWorkflowRequest,
+			): Promise<ManagedWorkflowOutcome> => {
+				const initialStepRunId = monitor.reserveRunId();
+				const initialStepResult: SingleResult = {
+					...request.initialResult,
+					runId: initialStepRunId,
+				};
+				runtime.registerRunResult(initialStepRunId, initialStepResult);
+				const steps: ChainStep[] = [{
+					runId: initialStepRunId,
+					result: initialStepResult,
+					relation: request.plan.initialRelation,
+				}];
+				const enabled = (name: string): boolean =>
+					request.agents.some((candidate) => candidate.name === name);
+				const canContinue = (): boolean => runtime.sessionActive && !request.signal.aborted;
+				const launchStep = async (
+					agentName: string,
+					task: string,
+					relation: string,
+				): Promise<SingleResult> => {
+					if (!enabled(agentName)) {
+						throw new Error(`Managed workflow cannot launch disabled or missing agent "${agentName}".`);
+					}
+					const step = await launchInWorkflow(request, agentName, task, {
+						groupId: request.groupId,
+						relationLabel: relation,
+						parentRunId: request.parentRunId,
+					});
+					request.rememberLatest(step.result);
+					steps.push({ ...step, relation });
+					return step.result;
+				};
+
+				const runFixRounds = async (triggeringReviewer: SingleResult): Promise<void> => {
+					let lastReviewer = triggeringReviewer;
+					for (let round = 1; round <= request.config.maxFixRounds; round++) {
+						if (!canContinue()) break;
+						const workerResult = await launchStep(
+							"worker",
+							buildFixTaskBrief(lastReviewer, round, request.config.maxFixRounds),
+							`fix round ${round}`,
+						);
+						if (!canContinue() || isFailedResult(workerResult)) break;
+
+						let documenterResult: SingleResult | undefined;
+						if (enabled("documenter")) {
+							documenterResult = await launchStep(
+								"documenter",
+								buildDocumenterTaskBrief(workerResult, round, lastReviewer),
+								`docs round ${round}`,
+							);
+							if (!canContinue() || isFailedResult(documenterResult)) break;
+						}
+
+						const reviewResult = await launchStep(
+							"reviewer",
+							buildReReviewBrief(lastReviewer, round, workerResult, documenterResult),
+							`re-review round ${round}`,
+						);
+						if (!canContinue() || isFailedResult(reviewResult)) break;
+						const verdict = reviewVerdict(getResultOutput(reviewResult));
+						// REVIEW_PASS settles. No verdict is advisory/malformed and must never
+						// trigger another writer. Only an explicit REVIEW_FAIL consumes a fix.
+						if (verdict !== "fail") break;
+						lastReviewer = reviewResult;
+					}
+				};
+
+				try {
+					// Park/stop/shutdown may win after the top-level child settles but
+					// before this continuation starts. Preserve that stable checkpoint and
+					// never create an already-aborted downstream child.
+					if (!canContinue()) return { kind: request.plan.kind, steps };
+					if (request.plan.kind === "auto-fix") {
+						await runFixRounds(initialStepResult);
+					} else {
+						let documenterResult: SingleResult | undefined;
+						if (request.plan.kind === "review-pass-sync") {
+							documenterResult = await launchStep(
+								"documenter",
+								buildReviewPassDocumenterBrief(initialStepResult),
+								"documentation sync",
+							);
+						} else if (initialStepResult.agent !== "documenter" && enabled("documenter")) {
+							documenterResult = await launchStep(
+								"documenter",
+								buildPostWriterDocumenterBrief(initialStepResult),
+								"documentation sync",
+							);
+						}
+
+						if (
+							canContinue() &&
+							(!documenterResult || !isFailedResult(documenterResult)) &&
+							enabled("reviewer")
+						) {
+							const reviewResult = await launchStep(
+								"reviewer",
+								buildFinalReviewBrief(initialStepResult, documenterResult),
+								"final review",
+							);
+							if (
+								canContinue() &&
+								!isFailedResult(reviewResult) &&
+								reviewVerdict(getResultOutput(reviewResult)) === "fail" &&
+								enabled("worker") &&
+								request.config.maxFixRounds > 0
+							) {
+								await runFixRounds(reviewResult);
+							}
+						}
+					}
+					return { kind: request.plan.kind, steps };
+				} finally {
+					removeWorkflowGroup(request.groupId);
+				}
+			};
+
+			const startBackground = createBackgroundDispatcher({
+				runtime,
+				ctx,
+				config,
+				agents,
+				finishRun,
+				makeLiveHandler,
+				makeDetails,
+				runManagedWorkflow,
+				runInManagedRepositoryLane,
+			});
+
+			// 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,
+						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,
+				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 ? ` (main after ${r.modelFallbackFrom} failed)` : ""}`;
+				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 ? ` (main after ${r.modelFallbackFrom} failed)` : ""}`;
+				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);
+		},
+	});
+}