@ferris1225/pi-subagents 4.1.13 → 4.1.15

package/src/dispatch.ts

@@ -1,11 +1,9 @@
 /**
  * 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 worker/cleaner → reviewer workflows with a
- * conditional documenter, bounded worker/reviewer fix rounds, and internal
- * step launching. Stable
- * thread generations, final integration, and completion ownership live in
- * thread-lifecycle.ts.
+ * per-run status tracking, the managed worker/cleaner → reviewer gate, and
+ * internal step launching. Stable thread generations, final integration, and
+ * completion ownership live in thread-lifecycle.ts.
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -18,9 +16,10 @@ import { getStateRoot } from "./durable.ts";
 import { loadConfig } from "./config.ts";
 import { formatUsage, queuedResult } from "./format.ts";
 import {
-	buildFinalDocumenterBrief,
 	buildFinalReviewBrief,
-	documentationDisposition,
+	buildReReviewBrief,
+	buildReviewerFixBrief,
+	MAX_REVIEW_FIX_ROUNDS,
 	type ChainStep,
 	type ManagedWorkflowOutcome,
 } from "./workflow.ts";
@@ -65,11 +64,6 @@ const IsolationSchema = Type.Optional(
 	StringEnum(["shared", "worktree"] as const, { description: ISOLATION_DESCRIPTION }),
 );
 
-const ADVISORY_DESCRIPTION =
-	"Report-only reviewer dispatch: findings return to you for the decision; a verdict (if emitted anyway) never starts the auto-fix chain. Use when re-verifying work you already fixed yourself.";
-
-const AdvisorySchema = Type.Optional(Type.Boolean({ description: ADVISORY_DESCRIPTION }));
-
 const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({
@@ -78,7 +72,6 @@ const TaskItem = Type.Object({
 	}),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 	isolation: IsolationSchema,
-	advisory: AdvisorySchema,
 });
 
 const SubagentParams = Type.Object({
@@ -89,7 +82,6 @@ const SubagentParams = Type.Object({
 	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,
-	advisory: AdvisorySchema,
 });
 
 export function defaultIsolationMode(mode: "single" | "parallel", agentName: string, requested?: IsolationMode): IsolationMode {
@@ -97,14 +89,26 @@ export function defaultIsolationMode(mode: "single" | "parallel", agentName: str
 	return mode === "parallel" && agentName === "worker" ? "worktree" : "shared";
 }
 
-function workflowStageStatus(result: SingleResult): WorkflowStageStatus {
+function workflowStageStatus(result: SingleResult, relation?: string): WorkflowStageStatus {
 	if (isFailedResult(result)) return "failed";
+	if (relation === "review fix") return "done";
 	if (result.agent !== "reviewer") return "done";
 	const verdict = reviewVerdict(getResultOutput(result));
 	if (verdict === "fail") return "changes";
 	return verdict === "pass" ? "done" : "failed";
 }
 
+/** The runtime-granted write continuation of a failed gate: same reviewer
+ * role, model, and retained session, but the read-only boundary is lifted for
+ * this one stage so it applies its own fix instructions. */
+function withReviewerFixStageAgent(agent: AgentConfig): AgentConfig {
+	return {
+		...agent,
+		tools: undefined,
+		systemPrompt: `${agent.systemPrompt.trimEnd()}\n\nRuntime workflow context: FIX STAGE — your gate just returned REVIEW_FAIL. Your read-only boundary is lifted for this stage only: apply your own fix instructions exactly as you specified them, run the narrowest decisive checks, and report what changed. Never edit during a review and never emit a verdict in a fix stage.`,
+	};
+}
+
 export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime): void {
 	// Latest dispatch environment. The dispatcher is created once per process so
 	// restored threads can resume before any dispatch has run; each execute
@@ -185,23 +189,30 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 
 	/** 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. */
+	 * but never enters top-level lifecycle policy or completion delivery.
+	 * `stage` continues a retained session (the reviewer fix stage) and/or
+	 * replaces the resolved agent (lifting the reviewer read-only boundary). */
 	const launchInWorkflow = async (
 		request: ManagedWorkflowRequest,
 		agentName: string,
 		task: string,
 		meta: RunChainMeta,
+		stage: {
+			agentOverride?: AgentConfig;
+			session?: { sessionId: string; sessionDir: string };
+		} = {},
 	): Promise<{ runId: number; result: SingleResult }> => {
 		const discoveredAgent = request.agents.find((candidate) => candidate.name === agentName);
 		if (!discoveredAgent) {
 			throw new Error(`Managed workflow requires enabled agent "${agentName}", but discovery did not provide it.`);
 		}
+		const boundaryAgent = stage.agentOverride ?? discoveredAgent;
 		const resolveLiveAgentTools = (candidate: AgentConfig): AgentConfig =>
-			resolveAgentTools({ ...candidate, tools: discoveredAgent.tools }, runtime.getActiveTools());
-		const agent = resolveLiveAgentTools(discoveredAgent);
-		// Workflow policy (fix-round caps, agents) stays fixed for the chain,
-		// but model/thinking routes are re-read per stage so config edits
-		// apply to stages that have not launched yet.
+			resolveAgentTools({ ...candidate, tools: boundaryAgent.tools }, runtime.getActiveTools());
+		const agent = resolveLiveAgentTools(boundaryAgent);
+		// Workflow policy (agents) stays fixed for the chain, but model/thinking
+		// routes are re-read per stage so config edits apply to stages that have
+		// not launched yet.
 		const stageConfig = await loadConfig(runtime.configPath).catch(() => request.config);
 		const resolvedRoute = resolveDispatchModelRoute(agent, stageConfig, request.ctx);
 		const route = request.isolation === "worktree"
@@ -230,6 +241,9 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					makeDetails: makeDetails("single", true),
 					idleTimeoutMs: stageConfig.idleTimeoutSec * 1000,
 					sessionRoot: getStateRoot(runtime.configPath),
+					...(stage.session
+						? { sessionId: stage.session.sessionId, sessionDir: stage.session.sessionDir, stdinText: task }
+						: {}),
 				},
 				route.mainFallbackRef,
 			);
@@ -303,62 +317,37 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			status: workflowStageStatus(initialStepResult),
 		}];
 		let reviewStage: WorkflowStage | undefined;
-		if (request.plan.kind === "post-writer" && enabled("reviewer")) {
+		if (enabled("reviewer")) {
 			reviewStage = { agent: "reviewer", relation: "review", status: "pending" };
 			workflowStages.push(reviewStage);
 		}
-		let documentationStage: WorkflowStage | undefined;
-		if (enabled("documenter")) {
-			documentationStage = { agent: "documenter", relation: "docs", status: "pending" };
-			workflowStages.push(documentationStage);
-		}
 		const publishWorkflowStages = (): void => {
 			monitor.setWorkflowStages(request.parentRunId, workflowStages);
 		};
-		const insertBeforeDocumentation = (stage: WorkflowStage): void => {
-			const documentationIndex = documentationStage
-				? workflowStages.indexOf(documentationStage)
-				: -1;
-			if (documentationIndex === -1) workflowStages.push(stage);
-			else workflowStages.splice(documentationIndex, 0, stage);
-		};
-		const removeDocumentationStage = (): void => {
-			if (!documentationStage) return;
-			const index = workflowStages.indexOf(documentationStage);
-			if (index !== -1) workflowStages.splice(index, 1);
-			documentationStage = undefined;
-			publishWorkflowStages();
-		};
 		publishWorkflowStages();
 
 		const launchStep = async (
 			agentName: string,
 			task: string,
 			relation: string,
-			projection: {
-				stage?: WorkflowStage;
-				timelineRelation?: string;
-				childRelation?: string;
+			stage: WorkflowStage,
+			stageOptions: {
+				agentOverride?: AgentConfig;
+				session?: { sessionId: string; sessionDir: string };
 			} = {},
 		): Promise<SingleResult> => {
 			if (!enabled(agentName)) {
 				throw new Error(`Managed workflow cannot launch disabled or missing agent "${agentName}".`);
 			}
-			const stage: WorkflowStage = projection.stage ?? {
-				agent: agentName,
-				relation: projection.timelineRelation ?? relation,
-				status: "pending",
-			};
-			if (!projection.stage) insertBeforeDocumentation(stage);
 			stage.status = "active";
 			publishWorkflowStages();
 			try {
 				const step = await launchInWorkflow(request, agentName, task, {
 					groupId: request.groupId,
-					relationLabel: projection.childRelation ?? relation,
+					relationLabel: relation,
 					parentRunId: request.parentRunId,
-				});
-				stage.status = workflowStageStatus(step.result);
+				}, stageOptions);
+				stage.status = workflowStageStatus(step.result, relation);
 				publishWorkflowStages();
 				request.rememberLatest(step.result);
 				steps.push({ ...step, relation });
@@ -370,68 +359,52 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			}
 		};
 
-		/** Run the low-cost final documentation sync only when the terminal REVIEW_PASS
-		 * reports drift or omits the marker. A failed process, missing verdict, or
-		 * REVIEW_FAIL never writes docs. With no reviewer, retain the conservative
-		 * writer → documenter fallback. */
-		const runFinalDocumentation = async (
-			lastWriterResult: SingleResult | undefined,
-			finalReviewResult: SingleResult | undefined,
-		): Promise<void> => {
-			if (!canContinue() || !enabled("documenter")) return;
-			if (lastWriterResult?.agent === "documenter") {
-				removeDocumentationStage();
-				return;
-			}
-			if (finalReviewResult) {
-				if (isFailedResult(finalReviewResult)) {
-					removeDocumentationStage();
-					return;
-				}
-				const reviewOutput = getResultOutput(finalReviewResult);
-				if (
-					reviewVerdict(reviewOutput) !== "pass" ||
-					documentationDisposition(reviewOutput) === "clean"
-				) {
-					removeDocumentationStage();
-					return;
-				}
-			}
-			documentationStage ??= { agent: "documenter", relation: "docs", status: "pending" };
-			if (!workflowStages.includes(documentationStage)) workflowStages.push(documentationStage);
-			await launchStep(
-				"documenter",
-				buildFinalDocumenterBrief(lastWriterResult, finalReviewResult),
-				"final documentation sync",
-				{ stage: documentationStage },
-			);
-		};
-
 		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 === "review-pass-sync") {
-				// The direct passing review already gated the pending code. Its
-				// disposition requested (or conservatively defaulted to) one docs sync.
-				await runFinalDocumentation(undefined, initialStepResult);
-			} else if (enabled("reviewer")) {
-				// A failing gate is not a workflow continuation: the REVIEW_FAIL
-				// report and its fix instructions are delivered to the main agent,
-				// which owns the fix decision.
-				const gateReview = await launchStep(
+			if (!canContinue()) return { steps };
+			if (reviewStage) {
+				const discoveredReviewer = request.agents.find((candidate) => candidate.name === "reviewer")!;
+				let gateReview = await launchStep(
 					"reviewer",
-					buildFinalReviewBrief(initialStepResult, { documenterPending: enabled("documenter") }),
+					buildFinalReviewBrief(initialStepResult),
 					"final review",
-					{ stage: reviewStage },
+					reviewStage,
 				);
-				await runFinalDocumentation(initialStepResult, gateReview);
-			} else {
-				// No gate configured: the documenter is the only downstream stage.
-				await runFinalDocumentation(initialStepResult, undefined);
+				// The failing gate owns its fixes until it passes: the same retained
+				// reviewer session applies its own fix instructions with write access,
+				// then a fresh gate re-scans the complete diff. Nobody outside the
+				// loop has to guess what satisfies the gate; the cap only stops
+				// pathological burn and hands the still-failing gate to the main agent.
+				for (let round = 1; round <= MAX_REVIEW_FIX_ROUNDS; round++) {
+					const gateSession = gateReview.sessionId && gateReview.sessionDir
+						? { sessionId: gateReview.sessionId, sessionDir: gateReview.sessionDir }
+						: undefined;
+					if (reviewVerdict(getResultOutput(gateReview)) !== "fail" || !gateSession || !canContinue()) break;
+					const fixStage: WorkflowStage = { agent: "reviewer", relation: "fix", status: "pending" };
+					workflowStages.push(fixStage);
+					publishWorkflowStages();
+					const fixResult = await launchStep(
+						"reviewer",
+						buildReviewerFixBrief(getResultOutput(gateReview)),
+						"review fix",
+						fixStage,
+						{ agentOverride: withReviewerFixStageAgent(discoveredReviewer), session: gateSession },
+					);
+					if (isFailedResult(fixResult) || !canContinue()) break;
+					const reReviewStage: WorkflowStage = { agent: "reviewer", relation: "review", status: "pending" };
+					workflowStages.push(reReviewStage);
+					publishWorkflowStages();
+					gateReview = await launchStep(
+						"reviewer",
+						buildReReviewBrief(fixResult, round),
+						round === 1 ? "re-review" : `re-review ${round}`,
+						reReviewStage,
+					);
+				}
 			}
-			return { kind: request.plan.kind, steps };
+			return { steps };
 		} finally {
 			removeWorkflowGroup(request.groupId);
 		}
@@ -456,15 +429,13 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		name: "subagent",
 		label: "Subagent",
 		description: [
-			"Dispatch enabled specialized agents as isolated leaf Pi child processes, singly or in parallel; fan-out breadth is yours — extra tasks queue for the next free process slot.",
-			"Built-ins: explorer for broad read-only reconnaissance (a retrieval index, never a gate); worker for implementation; cleaner as a separate explicitly authorized cleanup/removal/simplification/deduplication entry; documenter for explicit docs/comments work or conditional final diff sync; reviewer for generic read-only assessments and independent code gates.",
-			"Work starts in the background. Successful worker/cleaner runs keep one enabled reviewer gate; a REVIEW_FAIL is delivered to you with fix instructions — resolve the findings yourself (fix inline or dispatch a briefed worker) without waiting for the user; only a genuinely destructive or scope-changing fix is worth asking about. Documenter runs afterward only when REVIEW_PASS reports DOCUMENTATION: NEEDED or omits the marker, with a reviewer-disabled fallback. A top-level documenter delivers directly. Results resume the main agent and are already shown, so do not poll, duplicate downstream roles, or restate them.",
-			"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 resume a parked or settled thread's retained context by stable run id; use subagent_stop for destructive cancellation.",
+			"Dispatch enabled agents as isolated leaf Pi child processes, singly or in parallel. Dispatching never blocks your turn — runs proceed in the background and each completion resumes you automatically; never poll or restate delivered results.",
+			"Put every genuinely independent unit in one `tasks` array (no per-call cap; extras queue for a free process slot). Single tasks share the checkout; parallel workers default to detached Git worktrees — write-capable agents only, and setup failure never silently falls back to shared.",
+			"Successful worker/cleaner runs get one automatic reviewer gate; a failing gate is fixed by the reviewer itself in a write-enabled continuation of the same session and re-reviewed until it passes. A REVIEW_FAIL from a gate you dispatched directly returns its findings to you — fix them inline or via a briefed worker without waiting for the user.",
+			"A configured child-model failure continues the retained session on the current main model. Resume a parked or settled thread with subagent_control by run id; use subagent_stop for destructive cancellation.",
 		].join(" "),
 		promptSnippet:
-			"Dispatch isolated background agents for broad recon, self-contained implementation, authorized cleanup, explicit docs, or independent review; keep trivial work on direct tools. Worker/cleaner gates and only needed/conservative docs sync run automatically, REVIEW_FAIL findings return to you, results resume automatically, and each workflow delivers once.",
+			"Dispatch isolated background agents for recon, implementation, cleanup, docs, or review; never blocks your turn, and REVIEW_FAIL findings return to you to fix.",
 		parameters: SubagentParams,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -523,10 +494,11 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				};
 			}
 
-			// Sub-agents intentionally detach from the foreground turn. This makes the
-			// editor available immediately; completion messages later wake the main agent.
-			// Fan-out breadth is the model's call; the background queue paces how many
-			// child processes actually run at once, so no per-call task cap is enforced.
+			// Sub-agents run detached from the foreground turn: the editor stays
+			// available and completion messages later wake the main agent. The turn is
+			// NOT terminated here — the model can keep dispatching independent units
+			// or do its own work, and the background queue paces how many child
+			// processes actually run at once, so no per-call task cap is enforced.
 			if (params.tasks && params.tasks.length > 0) {
 				const results: SingleResult[] = [];
 				// Preserve caller order (and deterministic completion batching) while
@@ -537,7 +509,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						item.task,
 						item.cwd,
 						defaultIsolationMode("parallel", item.agent, item.isolation as IsolationMode | undefined),
-						{ advisoryReview: item.advisory === true },
 					));
 				}
 				const startedRuns = results.filter((result) => result.exitCode === -1);
@@ -558,7 +529,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					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.`,
+					`Started ${started} background subagent${started === 1 ? "" : "s"}: ${startedRefs.join(", ")}. They run in the background and never block you — dispatch more independent units now or keep working; each result resumes you automatically when you are idle.`,
 					...(failureLines.length > 0
 						? [`${failureLines.length} task${failureLines.length === 1 ? "" : "s"} failed before launch:`, ...failureLines]
 						: []),
@@ -566,7 +537,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				return {
 					content: [{ type: "text", text }],
 					details: makeDetails("parallel", true)(results),
-					terminate: true,
 				};
 			}
 
@@ -575,16 +545,14 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				params.task as string,
 				params.cwd,
 				defaultIsolationMode("single", params.agent as string, params.isolation as IsolationMode | undefined),
-				{ advisoryReview: params.advisory === true },
 			);
 			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.` }],
+				content: [{ type: "text", text: `Started ${runRef} in the background. It never blocks you — dispatch more independent units now or keep working; its result resumes you automatically when you are idle.` }],
 				details: makeDetails("single", true)([result]),
-				terminate: true,
 			};
 
 		},

package/src/durable.ts

@@ -1,13 +1,15 @@
 /**
- * Durable thread state: a manifest next to the config that lets parked and
- * settled sub-agent threads survive pi reloads and restarts, plus the durable
+ * Durable thread state: a manifest next to the config that lets interrupted
+ * (parked) sub-agent threads survive pi reloads and restarts, plus the durable
  * state root that keeps their retained sessions and isolated worktrees out of
  * the OS temp directory.
  *
- * Records are small path/state snapshots, never full transcripts; the retained
- * Pi session files and worktrees they point at remain the actual context.
- * Writes are atomic (tmp+rename) and serialized through the same
- * withFileMutationQueue as the recovery manifest.
+ * Only parked threads are ever recorded: a thread that settles normally drops
+ * its record, so the manifest file exists exactly while unfinished work needs
+ * it and disappears on its own. Records are small path/state snapshots, never
+ * full transcripts; the retained Pi session files and worktrees they point at
+ * remain the actual context. Writes are atomic (tmp+rename) and serialized
+ * through the same withFileMutationQueue as the recovery manifest.
  */
 
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
@@ -29,9 +31,9 @@ export const THREADS_MANIFEST_FILE_NAME = "pi-subagents-threads.json";
 const THREADS_MANIFEST_VERSION = 1;
 export const STATE_DIR_NAME = "pi-subagents-state";
 
-/** Fixed retention: settled results stop being resumable after a week,
- * parked work (which may hold unintegrated changes) after a month. */
-export const SETTLED_RECORD_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
+/** Fixed retention: parked work (which may hold unintegrated changes) stops
+ * being resumable after a month. Older manifests may still carry settled
+ * records from previous versions; restore discards them on sight. */
 export const PARKED_RECORD_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
 
 /** Result excerpts are for status display after restore, not full transcripts. */
@@ -297,7 +299,7 @@ async function discardRecordArtifacts(record: ThreadRecord): Promise<void> {
 }
 
 /** Drop records past their retention age along with their artifacts. Runs at
- * extension load; the fixed ages honor the no-config-knobs policy. */
+ * extension load; the fixed age honors the no-config-knobs policy. */
 export async function pruneThreadRecords(
 	configPath: string,
 	now = Date.now(),
@@ -309,8 +311,7 @@ export async function pruneThreadRecords(
 		let changed = false;
 		const kept: ThreadRecord[] = [];
 		for (const record of records) {
-			const maxAge = record.state === "parked" ? PARKED_RECORD_MAX_AGE_MS : SETTLED_RECORD_MAX_AGE_MS;
-			if (now - record.updatedAt <= maxAge) {
+			if (now - record.updatedAt <= PARKED_RECORD_MAX_AGE_MS) {
 				kept.push(record);
 				continue;
 			}

package/src/format.ts

@@ -156,6 +156,14 @@ export function modelLevelTakeoverNote(result: SingleResult, opts?: { runId?: nu
 	return `The sub-agent could not complete this task: ${cause}${retry}.${recovery}`;
 }
 
+/** Instruction appended whenever a failing gate verdict is delivered: the
+ * findings return to the main agent, which owns the fix decision — the runtime
+ * never auto-fixes. Stating it at this exact decision point keeps the main
+ * agent from relaying the findings to the user and stopping. */
+export function reviewFailFollowUpNote(): string {
+	return "This gate failed and the findings are yours to resolve now: fix them inline or dispatch a worker briefed with these fix instructions, then re-verify the change. Ask the user only before a genuinely destructive or scope-changing fix; do not deliver while a finding stands.";
+}
+
 /** Resolve a run-id request to actual ids: an exact numeric match always wins
  * (so "1" never fans out to 10, 11, …); only when no exact match exists does a
  * prefix match run, as a convenience for partial ids. Keeps single-digit lookups

package/src/prompt.ts

@@ -40,53 +40,40 @@ export function buildDelegationDirective(
 			: `${namedWorktreeTargets.slice(0, -1).join(", ")}, ${namedWorktreeTargets.at(-1)}, or another`;
 
 	const dispatchRules = [
-		"Route substantive work to sub-agents so your context stays lean for orchestration; inline only trivial work — a one-shot lookup, a single focused read/edit, or an answer already in context.",
+		`Delegate aggressively: child contexts are cheap, yours is scarce. Inline only trivial work — a one-shot lookup, a single focused edit, an answer already in context${hasWorker ? "; default every non-trivial implementation, fix, refactor, or test task to `worker`" : ""}.`,
 		...(hasExplorer
 			? [
-				"Use `explorer` for any broad or multi-file search; it is a retrieval index, never a gate — its findings are leads, not proof. Before acting on them yourself — editing inline, deleting, or deciding something load-bearing — re-read the files involved; a child you brief re-verifies them in its own context.",
+				"`explorer`: broad or multi-file search. Its findings are leads, never proof — re-read load-bearing files before acting yourself (a child you brief re-verifies). Split a broad question into several parallel explorers with disjoint scopes.",
 			]
 			: []),
-		...(hasWorker
-			? ["Use `worker` for a self-contained implementation, fix, refactor, or test whose separate context pays for itself."]
-			: []),
 		...(hasCleaner
-			? [
-				`Use \`cleaner\` only for user-authorized cleanup or deduplication; it applies every safe proven cut without item-by-item approval, and never runs as a pre-commit gate or by PR count.`,
-			]
+			? ["`cleaner`: only user-authorized cleanup or dedup; it applies every safe proven cut without per-item approval and is never a gate."]
 			: []),
 		...(hasDocumenter
-			? [
-				`Use \`documenter\` directly only for explicit standalone documentation work; a top-level documenter delivers without a gate.${codeWriterNames.length > 0 ? ` The runtime runs the final docs sync after REVIEW_PASS with DOCUMENTATION: NEEDED or a missing marker, or as the reviewer-disabled fallback; writers sync docs they directly affect — never dispatch a duplicate.` : ""}`,
-			]
+			? ["`documenter`: standalone docs/comment work, or syncing real drift a change left — writers already sync what they directly affect."]
 			: []),
 		...(hasReviewer
 			? [
-				`Use \`reviewer\` for read-only assessments or gates.${codeWriterNames.length > 0 ? ` Successful ${codeWriterNames.join("/")} runs already get one fresh gate and then deliver once.` : ""} Advisory output has no VERDICT and cannot authorize edits; dispatch your own re-verification with \`advisory: true\`.`,
+				`\`reviewer\`: read-only assessments and gates${codeWriterNames.length > 0 ? `; successful ${codeWriterNames.join("/")} runs get one fresh gate, and failing gates are fixed by the reviewer itself and re-reviewed until they pass` : ""}. Advisory output has no VERDICT and cannot authorize edits.`,
 			]
 			: []),
-		"You own the fan-out breadth: every genuinely independent unit goes in one `tasks` array — there is no per-call cap, and extra tasks queue for the next free process slot. One child owns one coherent deliverable and its files; no two children share a file or re-answer the same question; dependent work starts only after its prerequisite delivers.",
-		"Brief each child with the complete goal, exact paths, constraints, and expected output; it has no conversation memory and cannot delegate. Continue a parked/settled thread with `subagent_control resume`.",
-		`Single tasks share the checkout${hasWorker ? "; parallel workers default to detached Git worktrees" : ""}. Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a Git repo with committed HEAD; setup failure never silently falls back 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.",
+		`Parallelize by default: map the todo list onto ONE \`tasks\` dispatch. One child owns one deliverable and its files; only genuinely dependent work waits for its prerequisite.`,
+		"Brief each child completely — goal, exact paths, constraints, expected output; it has no conversation memory and cannot delegate. Resume parked threads with `subagent_control resume`.",
+		`Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a repo with committed HEAD.`,
 	];
 
 	const handoffRules = [
-		"Dispatch ends this turn; each completion resumes the main agent automatically — never sleep, poll, or call `subagent_wait` to hold the turn.",
+		"Dispatch never blocks or ends your turn — keep working; each completion resumes you automatically. Never sleep, poll, or `subagent_wait` to hold the turn.",
 		"Results are already shown; add only your conclusion or next action, never a restatement.",
-		"Before declaring the overall task done, use `subagent_status` to confirm that no runs remain active.",
+		"Before declaring the overall task done, `subagent_status` must show no active runs.",
 	];
 
 	const verificationRules = [
-		"Never report an unrun check as passed; surface unavailable checks and pre-existing failures honestly, and inspect actual changes before reporting completion.",
+		"Never report an unrun check as passed; surface unavailable checks and pre-existing failures, and inspect actual changes before reporting completion.",
 		...(hasReviewer
 			? [
-				...(hasDocumenter
-					? [
-						"A direct REVIEW_PASS with DOCUMENTATION: CLEAN delivers immediately; NEEDED or a missing marker runs one documentation sync.",
-					]
-					: []),
-				"A REVIEW_FAIL — direct or from a managed gate — returns the findings to you: resolve them yourself, inline or via a worker you brief, without waiting for the user; the runtime never auto-fixes. Ask only for genuinely destructive or scope-changing fixes. Advisory reports 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.",
+				"A REVIEW_FAIL from a gate you dispatched directly returns its findings to you: fix them inline or via a briefed worker without waiting for the user (ask only for genuinely destructive or scope-changing fixes), then re-verify.",
+				"Multi-model cross-review only when explicitly requested or for high-risk security, unsafe/FFI, persistence-migration, or concurrency changes.",
 			]
 			: []),
 		"Commit or push only when explicitly requested, applicable checks pass, and no review finding remains unresolved.",
@@ -95,7 +82,7 @@ export function buildDelegationDirective(
 	return `
 ## Sub-agent delegation (pi-subagents)
 
-The \`subagent\` tool runs isolated leaf Pi child processes and context windows; each completion automatically resumes the main agent.
+\`subagent\` runs isolated leaf Pi child processes in the background; each completion resumes you.
 
 Agents:
 ${catalog}

package/src/runtime.ts

@@ -20,7 +20,7 @@ import {
 	type CompletionMessageItem,
 } from "./completion.ts";
 import { type ThinkingLevel } from "./config.ts";
-import { threadRecordFromThread, upsertThreadRecord, type ThreadRecord } from "./durable.ts";
+import { removeThreadRecord, threadRecordFromThread, upsertThreadRecord, type ThreadRecord } from "./durable.ts";
 import { isRunActiveStatus, monitor } from "./monitor.ts";
 import type { RpcRunControl } from "./rpc-run.ts";
 import type { StartBackgroundInternal } from "./thread-lifecycle.ts";
@@ -50,8 +50,6 @@ export interface SubagentThread {
 	executionCwd: string;
 	thinkingLevel?: ThinkingLevel;
 	isolation: IsolationMode;
-	/** Report-only reviewer dispatch: verdicts never chain into a managed workflow. */
-	advisoryReview: boolean;
 	worktree?: WorktreeIsolation;
 	state: ThreadState;
 	control: RpcRunControl;
@@ -242,10 +240,14 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 				Promise.allSettled(preflights),
 				runtime.backgroundQueue.waitForIdle(),
 			]);
-			// Persist one record per non-retired thread, then keep exactly the
-			// artifacts those records reference. A thread whose settlement finished
-			// during the wait above already wrote its own terminal record; the
-			// lastResult-derived state below matches it.
+			// Only interrupted (parked) threads stay resumable across reloads:
+			// each keeps its durable record and retained artifacts. Settled
+			// threads drop their record — the manifest exists only while
+			// unfinished work needs it — and their sessions are deleted now. A
+			// thread whose settlement finished during the wait above already
+			// wrote (or removed) its own record; the lastResult-derived state
+			// below matches it.
+			const settledIds: number[] = [];
 			const records: ThreadRecord[] = [];
 			for (const thread of runtime.threads.values()) {
 				if (thread.retired) continue;
@@ -258,11 +260,13 @@ export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRun
 				} else {
 					state = "parked";
 				}
-				records.push(threadRecordFromThread(thread, state));
+				if (state === "parked") records.push(threadRecordFromThread(thread, state));
+				else settledIds.push(thread.id);
 			}
-			await Promise.all(
-				records.map((record) => upsertThreadRecord(runtime.configPath, record).catch(() => undefined)),
-			);
+			await Promise.all([
+				...records.map((record) => upsertThreadRecord(runtime.configPath, record).catch(() => undefined)),
+				...settledIds.map((runId) => removeThreadRecord(runtime.configPath, runId).catch(() => undefined)),
+			]);
 			// Retained-failure recovery records are persisted by the finalization
 			// itself; shutdown only drops sessions no record claims anymore.
 			const referenced = new Set(

package/src/setup.ts

@@ -307,9 +307,9 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 					next.agentThinkingLevels.cleaner = config.agentThinkingLevels.reviewer;
 				}
 			}
-			// Documenter intentionally follows the faster explorer route. Fresh
-			// installs leave it unselected; enabling it later inherits any explorer
-			// overrides instead of silently choosing a stronger model.
+			// Documenter intentionally follows the faster explorer route. When it
+			// is re-enabled after being explicitly disabled, it inherits any
+			// explorer overrides instead of silently choosing a stronger model.
 			if (!config.enabledAgents.includes("documenter") && enabled.includes("documenter")) {
 				if (!next.agentModels.documenter && config.agentModels.explorer) {
 					next.agentModels.documenter = config.agentModels.explorer;