@ferris1225/pi-subagents 4.1.1 → 4.1.3

package/src/prompt.ts

@@ -11,22 +11,42 @@ function bullets(lines: readonly string[]): string {
 	return lines.map((line) => `- ${line}`).join("\n");
 }
 
-export function buildDelegationDirective(agents: AgentConfig[]): string {
+export function buildDelegationDirective(
+	agents: AgentConfig[],
+	options: { maxFixRounds?: number } = {},
+): string {
 	if (agents.length === 0) return "";
 
 	const catalog = agents.map(formatCatalogEntry).join("\n");
 	const hasExplorer = agents.some((agent) => agent.name === "explorer");
 	const hasWorker = agents.some((agent) => agent.name === "worker");
 	const hasCleaner = agents.some((agent) => agent.name === "cleaner");
+	const hasDocumenter = agents.some((agent) => agent.name === "documenter");
 	const hasReviewer = agents.some((agent) => agent.name === "reviewer");
 	const hasMultiple = agents.length > 1;
-	const worktreeTargets = hasWorker && hasCleaner
-		? "worker, cleaner, or another"
-		: hasWorker
-			? "worker or another"
-			: hasCleaner
-				? "cleaner or another"
-				: "a";
+	const autoFixEnabled = hasWorker && (options.maxFixRounds ?? 1) > 0;
+	const codeWriterNames = [
+		...(hasWorker ? ["worker"] : []),
+		...(hasCleaner ? ["cleaner"] : []),
+	];
+	const reviewedWriterNames = [
+		...codeWriterNames,
+		...(hasDocumenter ? ["documenter"] : []),
+	];
+	const automaticWriterRoute = [
+		...(hasDocumenter ? ["documenter"] : []),
+		...(hasReviewer ? ["reviewer"] : []),
+	].join(" → ");
+	const namedWorktreeTargets = [
+		...(hasWorker ? ["worker"] : []),
+		...(hasCleaner ? ["cleaner"] : []),
+		...(hasDocumenter ? ["documenter"] : []),
+	];
+	const worktreeTargets = namedWorktreeTargets.length === 0
+		? "a"
+		: namedWorktreeTargets.length === 1
+			? `${namedWorktreeTargets[0]} or another`
+			: `${namedWorktreeTargets.slice(0, -1).join(", ")}, ${namedWorktreeTargets.at(-1)}, or another`;
 
 	const dispatchRules = [
 		"Handle simple work inline with direct tools: one-line lookups, known-target reads/edits, and quick questions do not justify a child process.",
@@ -40,12 +60,17 @@ export function buildDelegationDirective(agents: AgentConfig[]): string {
 			: []),
 		...(hasCleaner
 			? [
-				`Use \`cleaner\` only when the user explicitly authorizes cleanup/removal/simplification edits, including a requested maintenance pass. It gathers evidence, then applies every safe proven in-scope cut; zero edits is valid. Generic or read-only audit, inspect, report, review, code-health, plan, proposed-solution, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
+				`Use \`cleaner\` only for user-authorized cleanup, removal, simplification, duplicate-code consolidation, or maintenance. Once dispatched, it applies every safe proven in-scope cut without item-by-item approval; zero edits is valid only if none is proved. Generic or read-only audit, review, code-health, plan, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
+			]
+			: []),
+		...(hasDocumenter
+			? [
+				`Use \`documenter\` directly for explicit whole-codebase maintenance or standalone documentation work.${codeWriterNames.length > 0 ? ` Successful ${codeWriterNames.join("/")} runs already auto-sync the actual diff; never dispatch a duplicate.` : ""} Zero edits is valid and broad mode is never inferred. It changes docs/comments only and never runtime behavior, versions, release state, or ${hasReviewer ? "the final reviewer gate" : "direct final verification"}.`,
 			]
 			: []),
 		...(hasReviewer
 			? [
-				`Use \`reviewer\` for generic/read-only assessments and as the fresh independent pre-commit gate for non-trivial diffs${hasCleaner ? ", including cleaner edits" : ""}. Advisory findings do not authorize follow-up edits; only gate verdicts can enter auto-fix.`,
+				`Use \`reviewer\` for read-only assessments or an explicit gate.${reviewedWriterNames.length > 0 ? ` Successful ${reviewedWriterNames.join("/")} runs already get a fresh read-only reviewer gate.` : ""} Advisory output has no VERDICT: it stays read-only and does not authorize follow-up edits.`,
 			]
 			: []),
 		"Brief every child with the complete goal, exact paths, constraints, and expected output. It has no memory of this conversation.",
@@ -55,7 +80,7 @@ export function buildDelegationDirective(agents: AgentConfig[]): string {
 				"Dispatch independent work in one `tasks` array and let the resumed main agent start dependent work only after prerequisites finish.",
 			]
 			: []),
-		`Filesystem isolation: single tasks default to shared${hasWorker ? "; parallel worker tasks default to detached Git worktrees" : ""}${hasCleaner ? "; cleaner defaults to shared" : ""}. Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a Git repository with committed HEAD. Read-only agents reject it, and setup/integration failure never falls back silently to shared.`,
+		`Filesystem isolation: single tasks default to shared${hasWorker ? "; parallel worker tasks default to detached Git worktrees" : ""}${hasCleaner ? "; cleaner defaults to shared" : ""}${hasDocumenter ? "; documenter defaults to shared" : ""}. Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a Git repository with committed HEAD. Read-only agents reject it, and setup/integration failure never falls back silently to shared.`,
 		"A configured child model/provider failure automatically continues the same retained session on the current main model; do not redispatch. Ordinary tool/task failures stay on the selected model.",
 		"Trust but verify: inspect actual changes/results before reporting completion.",
 	];
@@ -69,9 +94,19 @@ export function buildDelegationDirective(agents: AgentConfig[]): string {
 
 	const verificationRules = [
 		"Never report an unrun check as passed; identify unavailable checks and pre-existing failures honestly.",
+		...(automaticWriterRoute && reviewedWriterNames.length > 0
+			? [
+				`Successful top-level write roles automatically continue through enabled downstream roles (${automaticWriterRoute}) to one final delivery; never duplicate stages.`,
+			]
+			: []),
 		...(hasReviewer
 			? [
-				"Send every non-trivial diff through one fresh read-only `reviewer` gate before reporting done. Resolve every finding; do not bypass the configured auto-fix/re-review cap.",
+				...(hasDocumenter
+					? [
+						`A direct REVIEW_PASS is preliminary: runtime runs documenter on the pending diff, then a fresh reviewer. A direct REVIEW_FAIL ${autoFixEnabled ? "keeps auto-fix; maxFixRounds limits worker fixes only, not initial docs/review." : "cannot start fixes while worker/fix rounds are disabled."}`,
+					]
+					: []),
+				"Resolve every gate finding; do not bypass the configured auto-fix/re-review cap. A reviewer report without a standalone VERDICT is advisory and cannot trigger writes.",
 				"Use multi-model cross-review only when explicitly requested or for genuinely high-risk security, unsafe/FFI, persistence-migration, or concurrency changes.",
 			]
 			: []),

package/src/recovery.ts

@@ -1,145 +1,145 @@
-/** Durable handoff for worktree integration/cleanup failures across sessions. */
-
-import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { stripVTControlCharacters } from "node:util";
-import type { WorktreeFinalization } from "./worktree.ts";
-
-export const RECOVERY_MANIFEST_FILE_NAME = "pi-subagents-recovery.json";
-const RECOVERY_MANIFEST_VERSION = 1;
-
-export interface RecoveryRecord {
-	runId: number;
-	createdAt: number;
-	integrated: boolean;
-	worktreePath?: string;
-	patchPath?: string;
-	error?: string;
-}
-
-interface RecoveryManifest {
-	version: number;
-	records: RecoveryRecord[];
-}
-
-export function getRecoveryManifestPath(configPath: string): string {
-	return join(dirname(configPath), RECOVERY_MANIFEST_FILE_NAME);
-}
-
-function normalizeRecord(value: unknown): RecoveryRecord | undefined {
-	if (!value || typeof value !== "object") return undefined;
-	const raw = value as Record<string, unknown>;
-	if (typeof raw.runId !== "number" || !Number.isInteger(raw.runId) || raw.runId < 1) return undefined;
-	if (typeof raw.createdAt !== "number" || !Number.isFinite(raw.createdAt)) return undefined;
-	return {
-		runId: raw.runId,
-		createdAt: raw.createdAt,
-		integrated: raw.integrated === true,
-		...(typeof raw.worktreePath === "string" && raw.worktreePath ? { worktreePath: raw.worktreePath } : {}),
-		...(typeof raw.patchPath === "string" && raw.patchPath ? { patchPath: raw.patchPath } : {}),
-		...(typeof raw.error === "string" && raw.error ? { error: raw.error } : {}),
-	};
-}
-
-export async function readRecoveryRecords(configPath: string): Promise<RecoveryRecord[]> {
-	try {
-		const parsed = JSON.parse(await readFile(getRecoveryManifestPath(configPath), "utf8")) as {
-			records?: unknown;
-		};
-		if (!Array.isArray(parsed.records)) return [];
-		return parsed.records.flatMap((record) => {
-			const normalized = normalizeRecord(record);
-			return normalized ? [normalized] : [];
-		});
-	} catch {
-		return [];
-	}
-}
-
-function recoveryKey(record: RecoveryRecord): string {
-	return `${record.runId}\0${record.worktreePath ?? ""}\0${record.patchPath ?? ""}\0${record.error ?? ""}`;
-}
-
-async function writeManifest(path: string, records: readonly RecoveryRecord[]): Promise<void> {
-	if (records.length === 0) {
-		await rm(path, { force: true });
-		return;
-	}
-	await mkdir(dirname(path), { recursive: true });
-	const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-	try {
-		const manifest: RecoveryManifest = {
-			version: RECOVERY_MANIFEST_VERSION,
-			records: [...records],
-		};
-		await writeFile(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
-		await rename(temporaryPath, path);
-	} finally {
-		await rm(temporaryPath, { force: true }).catch(() => undefined);
-	}
-}
-
-/** Merge retained artifacts into the durable manifest. */
-export async function persistRecoveryRecords(
-	configPath: string,
-	records: readonly RecoveryRecord[],
-): Promise<void> {
-	if (records.length === 0) return;
-	const path = getRecoveryManifestPath(configPath);
-	await withFileMutationQueue(path, async () => {
-		const merged = new Map<string, RecoveryRecord>();
-		for (const record of await readRecoveryRecords(configPath)) merged.set(recoveryKey(record), record);
-		for (const record of records) merged.set(recoveryKey(record), record);
-		await writeManifest(path, [...merged.values()]);
-	});
-}
-
-export function recoveryRecordFromFinalization(
-	runId: number,
-	finalization: WorktreeFinalization,
-	now = Date.now(),
-): RecoveryRecord {
-	return {
-		runId,
-		createdAt: now,
-		integrated: finalization.integrated,
-		...(finalization.worktreePath ? { worktreePath: finalization.worktreePath } : {}),
-		...(finalization.patchPath ? { patchPath: finalization.patchPath } : {}),
-		...(finalization.error ? { error: finalization.error } : {}),
-	};
-}
-
-/** Show retained recovery paths on every later session start until the user
- * removes the artifacts. Stale records are pruned automatically. */
-export async function announceRecoveryRecords(
-	configPath: string,
-	ctx: {
-		hasUI?: boolean;
-		ui: { notify(message: string, kind: "info" | "warning" | "error"): void };
-	},
-): Promise<void> {
-	if (ctx.hasUI === false) return;
-	const records = await readRecoveryRecords(configPath);
-	if (records.length === 0) return;
-	const live = records.filter((record) =>
-		(record.worktreePath ? existsSync(record.worktreePath) : false) ||
-		(record.patchPath ? existsSync(record.patchPath) : false),
-	);
-	if (live.length !== records.length) {
-		const path = getRecoveryManifestPath(configPath);
-		await withFileMutationQueue(path, () => writeManifest(path, live)).catch(() => undefined);
-	}
-	for (const record of live) {
-		const paths = [
-			record.worktreePath ? `worktree ${stripVTControlCharacters(record.worktreePath)}` : undefined,
-			record.patchPath ? `patch ${stripVTControlCharacters(record.patchPath)}` : undefined,
-		].filter(Boolean).join(" · ");
-		const reason = record.error ? ` · ${stripVTControlCharacters(record.error)}` : "";
-		ctx.ui.notify(
-			`pi-subagents recovery for run #${record.runId}: ${record.integrated ? "changes were applied but cleanup failed" : "integration failed"}${paths ? ` · retained ${paths}` : ""}${reason}`,
-			"error",
-		);
-	}
-}
+/** Durable handoff for worktree integration/cleanup failures across sessions. */
+
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import type { WorktreeFinalization } from "./worktree.ts";
+
+export const RECOVERY_MANIFEST_FILE_NAME = "pi-subagents-recovery.json";
+const RECOVERY_MANIFEST_VERSION = 1;
+
+export interface RecoveryRecord {
+	runId: number;
+	createdAt: number;
+	integrated: boolean;
+	worktreePath?: string;
+	patchPath?: string;
+	error?: string;
+}
+
+interface RecoveryManifest {
+	version: number;
+	records: RecoveryRecord[];
+}
+
+export function getRecoveryManifestPath(configPath: string): string {
+	return join(dirname(configPath), RECOVERY_MANIFEST_FILE_NAME);
+}
+
+function normalizeRecord(value: unknown): RecoveryRecord | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const raw = value as Record<string, unknown>;
+	if (typeof raw.runId !== "number" || !Number.isInteger(raw.runId) || raw.runId < 1) return undefined;
+	if (typeof raw.createdAt !== "number" || !Number.isFinite(raw.createdAt)) return undefined;
+	return {
+		runId: raw.runId,
+		createdAt: raw.createdAt,
+		integrated: raw.integrated === true,
+		...(typeof raw.worktreePath === "string" && raw.worktreePath ? { worktreePath: raw.worktreePath } : {}),
+		...(typeof raw.patchPath === "string" && raw.patchPath ? { patchPath: raw.patchPath } : {}),
+		...(typeof raw.error === "string" && raw.error ? { error: raw.error } : {}),
+	};
+}
+
+export async function readRecoveryRecords(configPath: string): Promise<RecoveryRecord[]> {
+	try {
+		const parsed = JSON.parse(await readFile(getRecoveryManifestPath(configPath), "utf8")) as {
+			records?: unknown;
+		};
+		if (!Array.isArray(parsed.records)) return [];
+		return parsed.records.flatMap((record) => {
+			const normalized = normalizeRecord(record);
+			return normalized ? [normalized] : [];
+		});
+	} catch {
+		return [];
+	}
+}
+
+function recoveryKey(record: RecoveryRecord): string {
+	return `${record.runId}\0${record.worktreePath ?? ""}\0${record.patchPath ?? ""}\0${record.error ?? ""}`;
+}
+
+async function writeManifest(path: string, records: readonly RecoveryRecord[]): Promise<void> {
+	if (records.length === 0) {
+		await rm(path, { force: true });
+		return;
+	}
+	await mkdir(dirname(path), { recursive: true });
+	const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+	try {
+		const manifest: RecoveryManifest = {
+			version: RECOVERY_MANIFEST_VERSION,
+			records: [...records],
+		};
+		await writeFile(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+		await rename(temporaryPath, path);
+	} finally {
+		await rm(temporaryPath, { force: true }).catch(() => undefined);
+	}
+}
+
+/** Merge retained artifacts into the durable manifest. */
+export async function persistRecoveryRecords(
+	configPath: string,
+	records: readonly RecoveryRecord[],
+): Promise<void> {
+	if (records.length === 0) return;
+	const path = getRecoveryManifestPath(configPath);
+	await withFileMutationQueue(path, async () => {
+		const merged = new Map<string, RecoveryRecord>();
+		for (const record of await readRecoveryRecords(configPath)) merged.set(recoveryKey(record), record);
+		for (const record of records) merged.set(recoveryKey(record), record);
+		await writeManifest(path, [...merged.values()]);
+	});
+}
+
+export function recoveryRecordFromFinalization(
+	runId: number,
+	finalization: WorktreeFinalization,
+	now = Date.now(),
+): RecoveryRecord {
+	return {
+		runId,
+		createdAt: now,
+		integrated: finalization.integrated,
+		...(finalization.worktreePath ? { worktreePath: finalization.worktreePath } : {}),
+		...(finalization.patchPath ? { patchPath: finalization.patchPath } : {}),
+		...(finalization.error ? { error: finalization.error } : {}),
+	};
+}
+
+/** Show retained recovery paths on every later session start until the user
+ * removes the artifacts. Stale records are pruned automatically. */
+export async function announceRecoveryRecords(
+	configPath: string,
+	ctx: {
+		hasUI?: boolean;
+		ui: { notify(message: string, kind: "info" | "warning" | "error"): void };
+	},
+): Promise<void> {
+	if (ctx.hasUI === false) return;
+	const records = await readRecoveryRecords(configPath);
+	if (records.length === 0) return;
+	const live = records.filter((record) =>
+		(record.worktreePath ? existsSync(record.worktreePath) : false) ||
+		(record.patchPath ? existsSync(record.patchPath) : false),
+	);
+	if (live.length !== records.length) {
+		const path = getRecoveryManifestPath(configPath);
+		await withFileMutationQueue(path, () => writeManifest(path, live)).catch(() => undefined);
+	}
+	for (const record of live) {
+		const paths = [
+			record.worktreePath ? `worktree ${stripVTControlCharacters(record.worktreePath)}` : undefined,
+			record.patchPath ? `patch ${stripVTControlCharacters(record.patchPath)}` : undefined,
+		].filter(Boolean).join(" · ");
+		const reason = record.error ? ` · ${stripVTControlCharacters(record.error)}` : "";
+		ctx.ui.notify(
+			`pi-subagents recovery for run #${record.runId}: ${record.integrated ? "changes were applied but cleanup failed" : "integration failed"}${paths ? ` · retained ${paths}` : ""}${reason}`,
+			"error",
+		);
+	}
+}

package/src/rpc-run.ts

@@ -14,7 +14,7 @@ import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import type { Message } from "@earendil-works/pi-ai";
-import type { AgentConfig } from "./agents.ts";
+import { SUBAGENT_TOOL_NAMES, type AgentConfig } from "./agents.ts";
 import type { ThinkingLevel } from "./config.ts";
 import type { IsolationMode, WorktreeFinalizationStatus } from "./worktree.ts";
 
@@ -66,10 +66,13 @@ export interface RpcSingleResult {
 	 * model execution. This remains main-model handoff eligible even when an
 	 * earlier, aborted objective left assistant text in the session. */
 	rpcPromptRejected?: boolean;
-	/** Handshake or initial prompt ACK never came back. This is a startup/
-	 * transport miss, not a model/provider failure. */
+	/** Startup handshake failed before the initial prompt was dispatched. This
+	 * transport miss is safe to retry and is not a model/provider failure. */
 	rpcStartupFailed?: boolean;
-	/** The child accepted a prompt; startup retries must never duplicate it. */
+	/** The parent dispatched the initial prompt command. Until its response is
+	 * observed, Pi may already be running it, so startup retries must not replay it. */
+	rpcPromptDispatched?: boolean;
+	/** The child confirmed prompt acceptance (or emitted agent activity). */
 	rpcPromptAccepted?: boolean;
 	/** Pi emitted agent/turn/model/tool activity for this attempt. */
 	rpcActivity?: boolean;
@@ -415,6 +418,13 @@ interface RpcResponse {
 	data?: unknown;
 }
 
+class RpcCommandRejectedError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "RpcCommandRejectedError";
+	}
+}
+
 interface PendingRequest {
 	resolve: (response: RpcResponse) => void;
 	reject: (error: Error) => void;
@@ -459,7 +469,7 @@ export interface RunRpcAttemptOptions {
 /** Run one persistent RPC child until a stable `agent_settled` or control action. */
 export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise<RpcSingleResult> {
 	const { agent, agentName, task, thinkingLevel, idleTimeoutMs, signal, onLive, control } = options;
-	const args: string[] = ["--mode", "rpc", "--exclude-tools", "subagent,subagent_control"];
+	const args: string[] = ["--mode", "rpc", "--exclude-tools", SUBAGENT_TOOL_NAMES.join(",")];
 	if (options.sessionDir && options.sessionId) {
 		args.push("--session-dir", options.sessionDir);
 		args.push(sessionExists(options.sessionDir, options.sessionId) ? "--session" : "--session-id", options.sessionId);
@@ -468,7 +478,10 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 	}
 	if (agent.model) args.push("--model", agent.model);
 	args.push("--thinking", thinkingLevel);
-	if (agent.tools && agent.tools.length > 0) args.push("--tools", agent.tools.join(","));
+	if (agent.tools) {
+		if (agent.tools.length > 0) args.push("--tools", agent.tools.join(","));
+		else args.push("--no-tools");
+	}
 
 	let tmpPromptDir: string | null = null;
 	let tmpPromptPath: string | null = null;
@@ -642,7 +655,9 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				},
 			);
 		}).then((response) => {
-			if (!response.success) throw new Error(response.error || `RPC ${response.command} failed.`);
+			if (!response.success) {
+				throw new RpcCommandRejectedError(response.error || `RPC ${response.command} failed.`);
+			}
 			return response;
 		});
 	};
@@ -734,7 +749,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				result.exitCode = 1;
 				result.stopReason = "error";
 				result.errorMessage = `Replacement prompt was rejected: ${promptError.message}`;
-				if (!isRpcCommandTimeoutError(promptError.message)) result.rpcPromptRejected = true;
+				if (promptError instanceof RpcCommandRejectedError) result.rpcPromptRejected = true;
 				finish();
 				terminate();
 				if (!closed) await processClosed.promise;
@@ -1076,7 +1091,7 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				result.stopReason = "error";
 				result.errorMessage = error.message;
 				if (startup) result.rpcStartupFailed = true;
-				else result.rpcPromptRejected = true;
+				else if (error instanceof RpcCommandRejectedError) result.rpcPromptRejected = true;
 				finish();
 				terminate();
 			};
@@ -1091,11 +1106,15 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 				}
 			}
 			if (!finished && !initialPromptResolved && !control?.isParkRequested() && !control?.isStopRequested()) {
+				// Pi starts the agent immediately after prompt preflight, before its
+				// success response necessarily reaches stdout. From this point on, a
+				// missing ACK is ambiguous and must never be recovered by replay.
+				result.rpcPromptDispatched = true;
 				void send({ type: "prompt", message: asPlainTextRpcPrompt(options.prompt) }).then(
 					() => resolveInitialPrompt(true),
 					(error) => {
 						const promptError = error instanceof Error ? error : new Error(String(error));
-						failBeforePrompt(promptError, isRpcCommandTimeoutError(promptError.message));
+						failBeforePrompt(promptError, false);
 					},
 				);
 			}

package/src/runtime.ts

@@ -58,15 +58,17 @@ export interface SubagentThread {
 	state: ThreadState;
 	control: RpcRunControl;
 	queueController?: AbortController;
-	/** Resolves only after the current generation's queue work has fully
-	 * quiesced and released its concurrency slot. Auto-fix orchestration is part
-	 * of the parent generation and replaces/extends this promise. */
+	/** Resolves only after the current generation's top-level child, downstream
+	 * managed workflow, and queue work have fully quiesced and released their
+	 * concurrency slot. */
 	generationCompletion: Promise<void>;
 	/** Synchronous CAS used by lifecycle controls across their async preflight. */
 	lifecycleVersion: number;
 	lifecycleOperation?: ThreadLifecycleOperation;
 	sessionId?: string;
 	sessionDir?: string;
+	/** Active execution time accumulated across retained resume generations. */
+	elapsedMs: number;
 	/** Most recent generation result, retained for parked destructive-stop output. */
 	lastResult?: SingleResult;
 	/** A destructive stop retires context even if the active child settles later. */
@@ -81,7 +83,8 @@ export interface SubagentThread {
 	fork: (objective?: string, ctx?: ExtensionContext) => Promise<SingleResult>;
 	forkedFromRunId?: number;
 	forkChildRunIds: number[];
-	/** Dispatch-owned, generation-guarded worktree settlement hook. */
+	/** Dispatch-owned, generation-guarded worktree settlement hook. Its apply
+	 * runs under the canonical original-repository lane. */
 	finalizeIsolation: (generation: number, result?: SingleResult) => Promise<WorktreeFinalization | undefined>;
 	/** Best-effort shutdown notification for retained integration artifacts. */
 	notifyIsolationFailure?: (finalization: WorktreeFinalization) => void;
@@ -91,6 +94,8 @@ export interface SubagentThread {
 export interface SubagentRuntime {
 	configPath: string;
 	backgroundQueue: BackgroundTaskQueue;
+	/** Live parent tool names from ExtensionAPI, read again for each child launch. */
+	getActiveTools: () => string[];
 	/** False after session_shutdown; guards delivery and queue work. */
 	sessionActive: boolean;
 	/** Deliver a batch of completion messages to the main window, waking it only
@@ -110,7 +115,7 @@ export interface SubagentRuntime {
 	 * next generation. Shutdown invalidates these claims and waits for cleanup. */
 	preflightOperations: Set<Promise<void>>;
 	/** Every session directory retained for this parent session, including
-	 * auto-fix internals that are not directly controllable. */
+	 * managed-workflow internals that are not directly controllable. */
 	sessionDirs: Set<string>;
 	retainSession: (result: Pick<SingleResult, "sessionDir">) => void;
 	retireThreadSession: (thread: SubagentThread) => void;
@@ -127,6 +132,7 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 	const runtime: SubagentRuntime = {
 		configPath,
 		backgroundQueue,
+		getActiveTools: () => pi.getActiveTools(),
 		sessionActive: true,
 		sendCompletionGroup: (items) => {
 			if (!runtime.sessionActive || items.length === 0) return;
@@ -134,8 +140,8 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 			// Computing this at delivery (emit) time — not when the item was
 			// pushed — reflects the current monitor state, since finishing runs
 			// are removed from the monitor before their completion is pushed.
-			// Auto-fix parents are flipped back to "running" while their chain
-			// owns the logical run, so they are included without a special case.
+			// Managed-workflow parents remain "running" through documenter,
+			// reviewer, and any fix rounds, so they are included without a special case.
 			const active = monitor
 				.getRuns()
 				.filter((run) => isRunActiveStatus(run.status))