@narumitw/pi-subagents 0.20.0 → 0.25.0

package/README.md

@@ -81,9 +81,11 @@ Count-selection guidance:
 - A single `subagent` call is blocking. Use one only when context isolation, high-volume output
   isolation, or independent review is worth waiting for; otherwise the main agent should do the work.
 - Do not delegate ordinary critical-path work merely to wait for it. Use detached `subagent_spawn`
-  only when parallel work, bounded context/output, independent review, a distinct model/tool profile,
-  or workspace isolation provides concrete value. Continue useful non-overlapping work when available;
-  otherwise call `subagent_wait` and synthesize the result before finishing.
+  only for a concrete bounded subtask that can run independently alongside useful main-agent work
+  and when parallel work, bounded context/output, independent review, a distinct model/tool profile,
+  or workspace isolation provides concrete value. After spawning, do useful non-overlapping work
+  immediately. Call `subagent_wait` sparingly, only when the immediate next critical-path step needs
+  the result and is blocked until it arrives; do not wait repeatedly by reflex.
 - Prefer **2–4 parallel read-only subagents** when a broad task naturally splits into independent
   branches that can each return a concise summary.
 - Exceed 4 tasks only when the branches are clearly distinct and worth the extra cost, while staying
@@ -202,9 +204,9 @@ Run a chain where each step receives the previous output:
 
 Stateful lifecycle tools are available by default. `subagent_spawn` is detached: it schedules work, returns immediately with an opaque `agentId`, and later injects one bounded `pi-subagent-completion` message per settled turn. The message uses `deliverAs: "steer"` with `triggerTurn: false`, so an active root turn can consume it naturally.
 
-Detached work has a root-coordination invariant: the main agent should continue useful non-overlapping work when available, or call `subagent_wait` when coordination is the only useful next action. If it yields while current delegated work is still live or awaiting synthesis, the extension schedules one idle-gated recovery continuation for that orchestration revision. A completion, close, interruption, new root turn, session replacement, or shutdown revises or clears that ephemeral state. Recovery is bounded and does not internally wait forever or persist across sessions.
+Detached work follows a critical-path policy: spawn only a concrete bounded subtask that can run independently alongside useful main-agent work, then do that non-overlapping work immediately. Use `subagent_wait` sparingly and only when the immediate next critical-path step requires the result and is blocked until it arrives. The extension does not start an autonomous recovery turn merely because delegated work remains live or completes. If the root turn has already ended, completion stays queued for the next turn instead of waking the root.
 
-A single detached agent is justified only by a concrete isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation. Simple work that the main agent can perform directly should not be delegated.
+A single detached agent additionally needs a concrete isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation. Simple work that the main agent can perform directly should not be delegated.
 
 When `subagent_wait` starts while a turn is running, that wait consumes the turn's completion: the terminal output is returned by the tool and is not also injected as a duplicate asynchronous completion. Multiple active waiters may all receive the terminal result. A timed-out or aborted wait does not consume it, so later settlement still delivers the normal asynchronous completion. If a turn has already settled and queued its completion before a wait starts, the queued message cannot be retracted safely.
 
@@ -237,7 +239,7 @@ Set `"enabled": false` to remove all stateful lifecycle tools. Otherwise, the ex
 | `subagent_send` | Send follow-up work to a reusable agent; shared-workspace write conflicts are guarded unless explicitly overridden. |
 | `subagent_message` | Queue a bounded mailbox message without starting a turn; sender IDs must be `root` or an agent in the same tree. |
 | `subagent_messages` | Read and optionally acknowledge unread mailbox messages. |
-| `subagent_wait` | Wait when coordination is the useful next action; timeout does not terminate the agent, and parent abort/user steering cancels only the wait. Already-terminal agents return immediately. |
+| `subagent_wait` | Wait sparingly when the immediate next critical-path step is blocked on a result; timeout does not terminate the agent, and parent abort/user steering cancels only the wait. Already-terminal agents return immediately. |
 | `subagent_list` | List retained agents and lifecycle states. |
 | `subagent_interrupt` | Abort the current turn while retaining its identity and history. |
 | `subagent_close` | Abort if necessary, close the agent, and remove it from retained persistence. |
@@ -292,10 +294,12 @@ Built-in agents are available without setup and can be overridden by user or pro
 | --- | --- | --- |
 | `scout` | Read-only codebase reconnaissance. | `read`, `grep`, `find`, `ls`, `bash` |
 | `planner` | Grounded implementation plans. | `read`, `grep`, `find`, `ls` |
-| `reviewer` | Independent review and verification. | `read`, `grep`, `find`, `ls`, `bash` |
+| `reviewer` | Independent review of code and existing verification evidence. | `read`, `grep`, `find`, `ls`, `bash` |
 | `worker` | General-purpose implementation. | Pi default tools |
 | `general`, `general-purpose` | Aliases for `worker`. | Pi default tools |
 
+The built-in `reviewer` does not run tests, builds, benchmarks, or formatters. It recommends additional verification commands for the main agent to run instead. Custom agents can override this behavior.
+
 Built-in agents inherit the active/default Pi model instead of forcing a provider-specific model alias, which keeps subprocesses usable across different Pi setups.
 
 ## ⚙️ Configure agent tools

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.20.0",
+	"version": "0.25.0",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",

package/src/agents.ts

@@ -93,14 +93,15 @@ const BUILT_IN_AGENTS: AgentConfig[] = [
 	},
 	{
 		name: "reviewer",
-		description: "Independent code review and verification agent for completed changes.",
+		description: "Independent code review agent that inspects existing verification evidence.",
 		tools: ["read", "grep", "find", "ls", "bash"],
 		source: "built-in",
 		filePath: "built-in:reviewer",
 		systemPrompt: [
-			"You are a reviewer subagent. Review changes adversarially and verify claims.",
-			"Do not edit files. Run safe inspection or test commands when useful.",
-			"Report PASS, FAIL, or PARTIAL with evidence, commands run, and specific follow-ups.",
+			"You are a reviewer subagent. Review changes adversarially and assess claims against the code and existing evidence.",
+			"Do not edit files or run tests, builds, benchmarks, formatters, or other long-running verification commands.",
+			"Inspect code, diffs, test definitions, and existing verification evidence. Recommend any additional commands for the main agent to run.",
+			"Report PASS, FAIL, or PARTIAL with evidence, commands inspected, and specific follow-ups.",
 		].join("\n"),
 	},
 	{

package/src/stateful.ts

@@ -7,17 +7,8 @@ import { discoverAgents, type AgentScope, isThinkingLevel } from "./agents.js";
 import { buildContextSnapshot, type ContextMode, redactPrivateText } from "./context.js";
 import { assertSubagentDepthAllowed } from "./execution.js";
 import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
-import {
-	ORCHESTRATION_MARKER_PREFIX,
-	RootOrchestrationState,
-	type OrchestrationRecoveryTicket,
-} from "./orchestration.js";
 import { AgentPersistence } from "./persistence.js";
-import {
-	AgentRegistry,
-	type AgentTurnCompletion,
-	type ManagedAgent,
-} from "./registry.js";
+import { AgentRegistry, type AgentTurnCompletion, type ManagedAgent } from "./registry.js";
 import { readSubagentSettings } from "./settings.js";
 import { SubprocessTransport } from "./subprocess-transport.js";
 import {
@@ -58,8 +49,6 @@ export function registerStatefulSubagents(
 	const isolatedAgents = new Map<string, string>();
 	const seenMessageIds = new Set<string>();
 	const parentRuntime: ParentRuntimeSnapshot = { model: undefined, thinkingLevel: "off" };
-	const orchestration = new RootOrchestrationState();
-	const cancelledRecoveryNonces = new Set<string>();
 	const completionWaiters = new Map<string, number>();
 
 	const requireRegistry = () => {
@@ -69,11 +58,12 @@ export function registerStatefulSubagents(
 
 	pi.on("session_start", async (_event, ctx) => {
 		const generation = ++runtimeGeneration;
-		rememberCancelledRecovery(orchestration.supersedePending(), cancelledRecoveryNonces);
-		orchestration.reset();
 		parentRuntime.model = ctx.model;
 		parentRuntime.thinkingLevel = normalizeRuntimeThinkingLevel(pi.getThinkingLevel());
-		const owner = ctx.sessionManager.getSessionId?.() ?? ctx.sessionManager.getSessionFile?.() ?? `ephemeral:${ctx.cwd}`;
+		const owner =
+			ctx.sessionManager.getSessionId?.() ??
+			ctx.sessionManager.getSessionFile?.() ??
+			`ephemeral:${ctx.cwd}`;
 		const sessionPersistence = new AgentPersistence(owner, {
 			retentionDays: settings.retentionDays,
 			maxStoredAgents: settings.maxStoredAgents,
@@ -112,7 +102,6 @@ export function registerStatefulSubagents(
 			},
 			onTurnComplete: (completion) => {
 				if (generation !== runtimeGeneration) return;
-				orchestration.complete(completion.agent.id);
 				if (!completionWaiters.has(completion.agent.id)) {
 					sendDetachedCompletion(pi, completion);
 				}
@@ -122,8 +111,7 @@ export function registerStatefulSubagents(
 			.load()
 			.filter(
 				(agent) =>
-					(agent.agentScope !== "project" && agent.agentScope !== "both") ||
-					ctx.isProjectTrusted(),
+					(agent.agentScope !== "project" && agent.agentScope !== "both") || ctx.isProjectTrusted(),
 			);
 		for (const agent of restored) {
 			for (const message of agent.mailbox) seenMessageIds.add(message.id);
@@ -140,38 +128,6 @@ export function registerStatefulSubagents(
 		sweepTimer.unref();
 	});
 
-	pi.on("input", (event) => {
-		if (event.source === "extension") {
-			const nonce = extractOrchestrationNonce(event.text);
-			if (nonce && cancelledRecoveryNonces.delete(nonce)) return { action: "handled" as const };
-			return;
-		}
-		rememberCancelledRecovery(orchestration.supersedePending(), cancelledRecoveryNonces);
-	});
-
-	pi.on("before_agent_start", () => {
-		orchestration.beginTurn();
-	});
-
-	pi.on("before_provider_request", () => {
-		orchestration.observeAvailable();
-	});
-
-	pi.on("agent_end", (_event, ctx) => {
-		const ticket = orchestration.endTurn();
-		if (ticket && !hasPendingRootMessages(ctx)) queueOrchestrationFollowUp(pi, ctx, ticket);
-	});
-
-	const settledEvents = pi as unknown as {
-		on(
-			event: "agent_settled",
-			handler: (event: unknown, ctx: ExtensionContext) => void,
-		): void;
-	};
-	settledEvents.on("agent_settled", (_event, ctx) => {
-		dispatchOrchestrationRecovery(pi, ctx, orchestration);
-	});
-
 	pi.on("model_select", (event) => {
 		parentRuntime.model = event.model;
 	});
@@ -182,8 +138,6 @@ export function registerStatefulSubagents(
 
 	pi.on("session_shutdown", async (_event, ctx) => {
 		runtimeGeneration++;
-		rememberCancelledRecovery(orchestration.supersedePending(), cancelledRecoveryNonces);
-		orchestration.reset();
 		if (sweepTimer) clearInterval(sweepTimer);
 		sweepTimer = undefined;
 		for (const agentId of isolatedAgents.keys()) {
@@ -203,25 +157,23 @@ export function registerStatefulSubagents(
 		persistence = undefined;
 		if (cleanupError && ctx.hasUI) {
 			const reason = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
-			ctx.ui.notify(
-				`Some isolated subagent workspaces could not be removed: ${reason}`,
-				"warning",
-			);
+			ctx.ui.notify(`Some isolated subagent workspaces could not be removed: ${reason}`, "warning");
 		}
 	});
 
 	pi.registerTool({
 		name: "subagent_spawn",
 		label: "Spawn Subagent",
-		description: "Start an addressable background subagent, return immediately with an agentId, and receive its completion asynchronously.",
+		description:
+			"Start an addressable background subagent, return immediately with an agentId, and receive its completion asynchronously.",
 		promptSnippet: "Start a reusable detached subagent; completion is delivered asynchronously",
 		promptGuidelines: [
-			"Do not delegate simple or critical-path work that the main agent can perform directly.",
-			"A single detached subagent is appropriate only for a concrete isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation.",
-			"Use one blocking subagent parallel call for multiple independent one-shot tasks; do not use repeated detached spawns when no reuse or overlap is needed.",
-			"After spawning, continue useful non-overlapping local work when available; otherwise call subagent_wait rather than yielding while delegated work remains unresolved.",
-			"Consume available completion messages and synthesize their results before finishing; interrupt or close agents that are no longer needed.",
-			"Detached completion is delivered automatically. Do not poll, wait forever, or spawn additional agents without a distinct need.",
+			"Do not use subagent_spawn for simple or critical-path work that the main agent can perform directly.",
+			"Use a single subagent_spawn only for a concrete bounded subtask that can run independently alongside useful main-agent work and has an isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation.",
+			"Use one blocking subagent parallel call for multiple independent one-shot tasks; do not use repeated subagent_spawn calls when no reuse or overlap is needed.",
+			"After subagent_spawn returns, do useful non-overlapping local work immediately. Call subagent_wait sparingly, only when the immediate next critical-path step requires the result and is blocked until it arrives; do not wait repeatedly by reflex.",
+			"Consume and synthesize available subagent_spawn completion messages; interrupt or close agents that are no longer needed.",
+			"subagent_spawn completion is delivered automatically. Do not poll, wait forever, or spawn additional agents without a distinct need.",
 		],
 		parameters: Type.Object({
 			agent: Type.String({ minLength: 1 }),
@@ -247,13 +199,7 @@ export function registerStatefulSubagents(
 			const scope = (params.agentScope ?? "user") as AgentScope;
 			assertSubagentDepthAllowed();
 			const cwd = params.cwd ?? ctx.cwd;
-			await confirmProjectAgent(
-				params.agent,
-				scope,
-				params.confirmProjectAgents ?? true,
-				ctx,
-				cwd,
-			);
+			await confirmProjectAgent(params.agent, scope, params.confirmProjectAgents ?? true, ctx, cwd);
 			const resolvedAgent = discoverAgents(cwd, scope, readSubagentSettings()).agents.find(
 				(agent) => agent.name === params.agent,
 			);
@@ -269,12 +215,7 @@ export function registerStatefulSubagents(
 			);
 			const requestedCwd = cwd;
 			if ((params.workspaceMode ?? "shared") === "shared" && !params.allowConcurrentWrites) {
-				assertNoSharedWriteConflict(
-					requireRegistry(),
-					params.agent,
-					requestedCwd,
-					scope,
-				);
+				assertNoSharedWriteConflict(requireRegistry(), params.agent, requestedCwd, scope);
 			}
 			const workspaceOwner = `pending-${randomUUID()}`;
 			const workspace =
@@ -298,10 +239,9 @@ export function registerStatefulSubagents(
 				throw error;
 			}
 			if (workspace) isolatedAgents.set(agent.id, workspaceOwner);
-			trackSpawnedAgent(orchestration, agent);
 			return result(
 				agent,
-				`Spawned ${agent.agent} as ${agent.id}. Continue coordinating this agent; do useful non-overlapping work or call subagent_wait, then synthesize its result before finishing.`,
+				`Spawned ${agent.agent} as ${agent.id}. Do useful non-overlapping work immediately. Completion will arrive asynchronously; call subagent_wait only if the immediate next critical-path step is blocked on this result.`,
 			);
 		},
 	});
@@ -334,7 +274,6 @@ export function registerStatefulSubagents(
 				isolatedAgents.has(existing.id),
 			);
 			const agent = await requireRegistry().followUp(params.agentId, params.task);
-			trackSpawnedAgent(orchestration, agent);
 			return result(agent, `Started follow-up for ${agent.id}.`);
 		},
 	});
@@ -384,9 +323,7 @@ export function registerStatefulSubagents(
 			}));
 			const text = summaries.length
 				? summaries
-						.map(
-							(message) => `${message.id} from ${message.senderId}: ${message.content}`,
-						)
+						.map((message) => `${message.id} from ${message.senderId}: ${message.content}`)
 						.join("\n")
 				: "No unread messages.";
 			return {
@@ -399,7 +336,8 @@ export function registerStatefulSubagents(
 	pi.registerTool({
 		name: "subagent_wait",
 		label: "Wait for Subagent",
-		description: "Wait for a stateful subagent turn without terminating it when the wait times out.",
+		description:
+			"Wait for a stateful subagent turn without terminating it when the wait times out. Use sparingly, only when the immediate next critical-path step is blocked on this result.",
 		parameters: Type.Object({
 			agentId: Type.String(),
 			timeoutMs: Type.Optional(Type.Number({ minimum: 1, maximum: 3_600_000, default: 30_000 })),
@@ -412,7 +350,6 @@ export function registerStatefulSubagents(
 			}
 			try {
 				const waited = await requireRegistry().wait(params.agentId, params.timeoutMs, signal);
-				if (!waited.timedOut) orchestration.observe(waited.agent.id);
 				return result(
 					waited.agent,
 					waited.timedOut
@@ -436,9 +373,7 @@ export function registerStatefulSubagents(
 				content: [
 					{
 						type: "text",
-						text: agents.length
-							? agents.map(formatLine).join("\n")
-							: "No stateful subagents.",
+						text: agents.length ? agents.map(formatLine).join("\n") : "No stateful subagents.",
 					},
 				],
 				details: { agents: agents.map(summarizeAgent) },
@@ -481,7 +416,6 @@ export function registerStatefulSubagents(
 		async execute(_id, params) {
 			const existing = requireRegistry().get(params.agentId);
 			if (existing?.state === "closed" && !params.subtree) {
-				orchestration.resolve(existing.id);
 				const pendingOwner = isolatedAgents.get(existing.id);
 				if (pendingOwner) await workspaceManager.cleanup(pendingOwner);
 				isolatedAgents.delete(existing.id);
@@ -494,7 +428,6 @@ export function registerStatefulSubagents(
 				} finally {
 					await cleanupClosedWorkspaces(requireRegistry(), isolatedAgents, workspaceManager);
 				}
-				for (const closed of agents) orchestration.resolve(closed.id);
 				return {
 					content: [{ type: "text", text: `Closed ${agents.length} agent(s).` }],
 					details: {
@@ -509,7 +442,6 @@ export function registerStatefulSubagents(
 			} finally {
 				await cleanupClosedWorkspaces(requireRegistry(), isolatedAgents, workspaceManager);
 			}
-			orchestration.resolve(agent.id);
 			return result(agent, `Closed ${agent.id}.`);
 		},
 	});
@@ -530,7 +462,6 @@ export function registerStatefulSubagents(
 					isolatedAgents.clear();
 				}
 				seenMessageIds.clear();
-				orchestration.reset();
 				await persistence?.delete();
 				ctx.ui.notify("Cleared stateful subagents.", "info");
 				return;
@@ -577,12 +508,7 @@ export function assertFollowUpWriteAllowed(
 	isolatedWorkspace: boolean,
 ): void {
 	if (allowConcurrentWrites || isolatedWorkspace) return;
-	assertNoSharedWriteConflict(
-		registry,
-		agent.agent,
-		agent.cwd,
-		agent.agentScope ?? "user",
-	);
+	assertNoSharedWriteConflict(registry, agent.agent, agent.cwd, agent.agentScope ?? "user");
 }
 
 export function isWriteCapable(tools: string[] | undefined): boolean {
@@ -614,7 +540,10 @@ async function confirmProjectAgent(
 		throw new Error("Project-local subagent definitions require a trusted project");
 	}
 	if (confirm && ctx.hasUI) {
-		const approved = await ctx.ui.confirm("Run project-local agent?", `Agent: ${name}\nSource: ${agent.filePath}`);
+		const approved = await ctx.ui.confirm(
+			"Run project-local agent?",
+			`Agent: ${name}\nSource: ${agent.filePath}`,
+		);
 		if (!approved) throw new Error("Project-local subagent was not approved");
 	}
 }
@@ -623,9 +552,7 @@ function isSameCwd(left: string, right: string): boolean {
 	return path.resolve(left) === path.resolve(right);
 }
 
-function normalizeContextMode(
-	value: "none" | "all" | "summary" | number | undefined,
-): ContextMode {
+function normalizeContextMode(value: "none" | "all" | "summary" | number | undefined): ContextMode {
 	if (value === undefined) return "none";
 	if (value === "none" || value === "all" || value === "summary") return value;
 	return Math.max(1, Math.floor(value));
@@ -680,85 +607,7 @@ function summarizeAgent(agent: ManagedAgent) {
 	};
 }
 
-function trackSpawnedAgent(
-	orchestration: RootOrchestrationState,
-	agent: ManagedAgent,
-): void {
-	orchestration.spawn(agent.id);
-	if (agent.state === "closed") orchestration.resolve(agent.id);
-	else if (agent.state !== "starting" && agent.state !== "running") {
-		orchestration.complete(agent.id);
-	}
-}
-
-function rememberCancelledRecovery(
-	ticket: OrchestrationRecoveryTicket | undefined,
-	cancelledNonces: Set<string>,
-): void {
-	if (!ticket) return;
-	cancelledNonces.add(ticket.nonce);
-	if (cancelledNonces.size <= 64) return;
-	const oldest = cancelledNonces.values().next().value;
-	if (oldest) cancelledNonces.delete(oldest);
-}
-
-function extractOrchestrationNonce(text: string): string | undefined {
-	const marker = `<!-- ${ORCHESTRATION_MARKER_PREFIX}`;
-	const start = text.lastIndexOf(marker);
-	if (start < 0) return undefined;
-	const valueStart = start + marker.length;
-	const end = text.indexOf(" -->", valueStart);
-	return end < 0 ? undefined : text.slice(valueStart, end);
-}
-
-function queueOrchestrationFollowUp(
-	pi: ExtensionAPI,
-	ctx: ExtensionContext,
-	ticket: OrchestrationRecoveryTicket,
-): void {
-	try {
-		pi.sendUserMessage(ticket.prompt, { deliverAs: "followUp" });
-	} catch (error) {
-		if (ctx.hasUI) {
-			const reason = error instanceof Error ? error.message : String(error);
-			ctx.ui.notify(`Subagent coordination follow-up failed: ${reason}`, "warning");
-		}
-	}
-}
-
-function dispatchOrchestrationRecovery(
-	pi: ExtensionAPI,
-	ctx: ExtensionContext,
-	orchestration: RootOrchestrationState,
-): boolean {
-	const ticket = orchestration.pendingTicket();
-	if (!ticket || !orchestration.isCurrent(ticket)) return false;
-	if (hasPendingRootMessages(ctx)) return false;
-	try {
-		pi.sendUserMessage(ticket.prompt);
-		orchestration.markDelivered(ticket);
-		return true;
-	} catch (error) {
-		if (ctx.hasUI) {
-			const reason = error instanceof Error ? error.message : String(error);
-			ctx.ui.notify(`Subagent coordination prompt failed: ${reason}`, "warning");
-		}
-		return false;
-	}
-}
-
-function hasPendingRootMessages(ctx: ExtensionContext): boolean {
-	try {
-		return ctx.hasPendingMessages();
-	} catch {
-		return true;
-	}
-}
-
-function sendDetachedCompletion(
-	pi: ExtensionAPI,
-	completion: AgentTurnCompletion,
-): void {
+function sendDetachedCompletion(pi: ExtensionAPI, completion: AgentTurnCompletion): void {
 	const content = buildDetachedCompletionMessage(completion);
 	pi.sendMessage(
 		{
@@ -798,8 +647,8 @@ export function buildDetachedCompletionMessage(completion: AgentTurnCompletion):
 }
 
 function sanitizeCompletionLine(value: string, maxBytes: number): string {
-	return truncateUtf8(redactPrivateText(value), maxBytes).text
-		.replace(/[\u0000-\u001f\u007f]+/g, " ")
+	return truncateUtf8(redactPrivateText(value), maxBytes)
+		.text.replace(/[\u0000-\u001f\u007f]+/g, " ")
 		.replace(/\s+/g, " ")
 		.trim();
 }

package/src/subagents.ts

@@ -39,9 +39,9 @@ export default function (pi: ExtensionAPI) {
 			"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work needed for the main agent's next action.",
 			"A single blocking subagent call should be used only when independent context, high-volume output isolation, or an external review is worth waiting for; otherwise do the task in the main agent.",
 			"For one-shot parallel work, use a single subagent call with tasks instead of repeated subagent_spawn calls, even when the user explicitly requests multiple agents.",
-			"When subagent_spawn is available, use it only when detached delegation has a concrete parallel, isolation, or specialization benefit; otherwise keep the work in the main agent.",
-			"After detached spawn, continue useful non-overlapping work when available, or call subagent_wait when coordination is the only useful next action; do not yield permanently while delegated work remains unresolved.",
-			"Consume detached completion messages and synthesize their results before finishing; interrupt or close agents that are no longer needed.",
+			"When subagent_spawn is available, use it only for a concrete bounded subtask that can run independently alongside useful main-agent work and has a parallel, isolation, or specialization benefit; otherwise keep the work in the main agent.",
+			"After subagent_spawn returns, do useful non-overlapping work immediately. Call subagent_wait sparingly, only when the immediate next critical-path step requires the result and is blocked until it arrives; do not wait repeatedly by reflex.",
+			"Consume and synthesize available subagent_spawn completion messages; interrupt or close agents that are no longer needed.",
 			"Use subagent parallel mode with 2-4 parallel read-only subagents when work has broad independent branches; prefer scout or reviewer for fan-out and add an aggregator when synthesis helps.",
 			"Use more than 4 subagent tasks only when clearly justified by distinct independent branches, and stay within the existing hard max 8 parallel tasks.",
 			"Do not use subagent parallel mode for write-heavy implementation touching the same files or shared state; serialize those changes in the main agent or one worker.",
@@ -65,7 +65,8 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("tool_result", (event) => {
 		if (event.toolName !== "subagent") return;
-		if ((event.details as (SubagentDetails & { isError?: boolean }) | undefined)?.isError) return { isError: true };
+		if ((event.details as (SubagentDetails & { isError?: boolean }) | undefined)?.isError)
+			return { isError: true };
 	});
 
 	pi.on("session_start", (_event, ctx) => {

package/src/orchestration.ts

@@ -1,164 +0,0 @@
-import { randomUUID } from "node:crypto";
-
-export type OrchestrationRecoveryTicket = {
-	generation: number;
-	revision: number;
-	nonce: string;
-	prompt: string;
-};
-
-type DelegatedAgent = {
-	live: boolean;
-	resultAvailable: boolean;
-	observedInTurn: boolean;
-};
-
-export const ORCHESTRATION_MARKER_PREFIX = "pi-subagent-orchestration:";
-
-const RECOVERY_PROMPT = [
-	"Delegated subagents still need root coordination.",
-	"Do not yield permanently while current delegated work is unresolved.",
-	"Continue useful non-overlapping local work, or call subagent_wait when no useful local continuation remains.",
-	"Consume available subagent results and synthesize them before finishing.",
-	"Interrupt or close agents that are no longer needed; do not wait forever or spawn more agents unnecessarily.",
-].join(" ");
-
-/** Ephemeral root-turn coordination state. Never persisted across sessions. */
-export class RootOrchestrationState {
-	private generation = 0;
-	private revision = 0;
-	private turnOpen = false;
-	private agents = new Map<string, DelegatedAgent>();
-	private pending: OrchestrationRecoveryTicket | undefined;
-	private deliveredRevision: number | undefined;
-
-	reset(): void {
-		this.generation += 1;
-		this.revision = 0;
-		this.turnOpen = false;
-		this.agents.clear();
-		this.pending = undefined;
-		this.deliveredRevision = undefined;
-	}
-
-	beginTurn(): void {
-		this.turnOpen = true;
-		if (this.pending) this.deliveredRevision = this.pending.revision;
-		this.observeAvailable();
-		// New root work supersedes an intent that has not been delivered yet. The
-		// turn gets a chance to coordinate before agent_end evaluates it again.
-		this.pending = undefined;
-	}
-
-	spawn(agentId: string): void {
-		this.agents.set(agentId, {
-			live: true,
-			resultAvailable: false,
-			observedInTurn: false,
-		});
-		this.bumpRevision();
-	}
-
-	complete(agentId: string): void {
-		const existing = this.agents.get(agentId);
-		if (!existing) return;
-		this.agents.set(agentId, {
-			live: false,
-			resultAvailable: true,
-			observedInTurn: false,
-		});
-		this.bumpRevision();
-		if (!this.turnOpen) this.ensureRecovery();
-	}
-
-	resolve(agentId: string): void {
-		if (!this.agents.delete(agentId)) return;
-		this.bumpRevision();
-	}
-
-	observe(agentId: string): void {
-		const agent = this.agents.get(agentId);
-		if (agent && !agent.live && agent.resultAvailable) agent.observedInTurn = true;
-	}
-
-	observeAvailable(): void {
-		for (const agent of this.agents.values()) {
-			if (!agent.live && agent.resultAvailable) agent.observedInTurn = true;
-		}
-	}
-
-	endTurn(): OrchestrationRecoveryTicket | undefined {
-		if (this.turnOpen) {
-			for (const [id, agent] of this.agents) {
-				if (!agent.live && agent.resultAvailable && agent.observedInTurn) {
-					this.agents.delete(id);
-				}
-			}
-			this.turnOpen = false;
-		}
-		return this.ensureRecovery();
-	}
-
-	pendingTicket(): OrchestrationRecoveryTicket | undefined {
-		return this.pending;
-	}
-
-	isCurrent(ticket: OrchestrationRecoveryTicket): boolean {
-		return (
-			ticket.generation === this.generation &&
-			ticket.revision === this.revision &&
-			ticket.nonce === this.pending?.nonce &&
-			this.hasUnresolved()
-		);
-	}
-
-	markDelivered(ticket: OrchestrationRecoveryTicket): void {
-		if (!this.isCurrent(ticket)) return;
-		this.pending = undefined;
-		this.deliveredRevision = ticket.revision;
-	}
-
-	supersedePending(): OrchestrationRecoveryTicket | undefined {
-		const ticket = this.pending;
-		if (!ticket) return undefined;
-		this.pending = undefined;
-		this.deliveredRevision = ticket.revision;
-		return ticket;
-	}
-
-	hasUnresolved(): boolean {
-		return this.agents.size > 0;
-	}
-
-	liveAgentIds(): string[] {
-		return [...this.agents]
-			.filter(([, agent]) => agent.live)
-			.map(([id]) => id)
-			.sort();
-	}
-
-	private ensureRecovery(): OrchestrationRecoveryTicket | undefined {
-		if (!this.hasUnresolved()) {
-			this.pending = undefined;
-			return undefined;
-		}
-		if (this.deliveredRevision === this.revision) return undefined;
-		if (this.pending?.revision === this.revision && this.pending.generation === this.generation) {
-			return this.pending;
-		}
-		const nonce = randomUUID();
-		this.pending = {
-			generation: this.generation,
-			revision: this.revision,
-			nonce,
-			prompt: `${RECOVERY_PROMPT}\n<!-- ${ORCHESTRATION_MARKER_PREFIX}${nonce} -->`,
-		};
-		return this.pending;
-	}
-
-	private bumpRevision(): void {
-		this.revision += 1;
-		this.pending = undefined;
-		this.deliveredRevision = undefined;
-	}
-}