@narumitw/pi-subagents 0.20.0 → 0.26.0

package/src/stateful.ts

@@ -1,30 +1,31 @@
 import { randomUUID } from "node:crypto";
 import * as path from "node:path";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
+import {
+	defineTool,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { discoverAgents, type AgentScope, isThinkingLevel } from "./agents.js";
+import {
+	type AgentScope,
+	type CompletionDelivery,
+	discoverAgents,
+	isThinkingLevel,
+	THINKING_LEVELS,
+} 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 { readSubagentSettings } from "./settings.js";
-import { SubprocessTransport } from "./subprocess-transport.js";
 import {
 	type ChildSessionFactory,
 	InProcessTransport,
 	type ParentRuntimeSnapshot,
 } from "./in-process-transport.js";
+import { DEFAULT_MAX_CONTEXT_BYTES, truncateUtf8 } from "./limits.js";
+import { AgentPersistence } from "./persistence.js";
+import { AgentRegistry, type AgentTurnCompletion, type ManagedAgent } from "./registry.js";
+import { readSubagentSettings } from "./settings.js";
+import { SubprocessTransport } from "./subprocess-transport.js";
 import { WorkspaceManager } from "./workspace.js";
 
 const ContextModeSchema = Type.Union([
@@ -36,31 +37,121 @@ const ScopeSchema = StringEnum(["user", "project", "both"] as const, {
 		'Per-invocation custom agent scope for this spawn. Default: "user". Use "project" for project-local agents or "both" for user and project agents; the selected scope is retained for follow-ups.',
 	default: "user",
 });
+const StatefulThinkingLevelSchema = StringEnum(THINKING_LEVELS, {
+	description:
+		"Optional requested Pi thinking level selected for this task difficulty; retained for every turn of the spawned agent.",
+});
 const MAX_TOOL_MESSAGE_BYTES = 2 * 1024;
 const MAX_COMPLETION_ERROR_BYTES = 512;
+const MAX_COMPLETIONS_PER_MESSAGE = 16;
+const COMPLETION_BATCH_DELAY_MS = 10;
+
+function createSpawnPromptGuidelines(completionDelivery: CompletionDelivery): string[] {
+	const deliveryGuidance =
+		completionDelivery === "auto-resume"
+			? "With subagent_spawn completion delivery set to auto-resume, prefer one subagent_spawn for broad asynchronous research or review that covers related branches even when the final answer depends on its result; do not choose blocking parallel fan-out merely to keep delegation in the same turn."
+			: "With subagent_spawn completion delivery set to next-turn (the default), prefer one subagent_spawn for broad asynchronous research or review only when the current response does not depend on its result; use the blocking subagent when the final answer depends on the detached result.";
+	const noLocalWorkGuidance =
+		completionDelivery === "auto-resume"
+			? "After subagent_spawn returns, do useful non-overlapping local work immediately. If none remains, briefly tell the user what subagent_spawn launched and end the response; auto-resume will request a synthesis turn after completion."
+			: "After subagent_spawn returns, do useful non-overlapping local work immediately. If none remains, briefly tell the user what subagent_spawn launched and end the response only when the current response does not depend on its result; next-turn delivery will not wake an idle root.";
+	return [
+		"Do not use subagent_spawn for simple or critical-path work that the main agent can perform directly.",
+		"Set subagent_spawn thinkingLevel to the lowest sufficient thinking level for the delegated task: use off or minimal for extraction, formatting, or mechanical work; low for straightforward bounded work; medium for ordinary multi-step research or implementation; high for complex debugging, design, review, or cross-file analysis; xhigh for highly ambiguous, cross-system, or high-risk analysis; and max only for the hardest tasks when quality clearly outweighs latency and cost. Omit subagent_spawn thinkingLevel only to preserve the agent or child default.",
+		deliveryGuidance,
+		"Use a single subagent_spawn only for a concrete bounded subtask that can run independently and has an isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation.",
+		"Use the blocking subagent instead of subagent_spawn when synchronous output is required before the main agent can continue and waiting is intentional; queued steering cannot be processed until that blocking call returns.",
+		"When subagent_spawn fits the completion-delivery policy, do not choose a blocking parallel subagent merely to keep delegation in the same turn.",
+		"Add another subagent_spawn only for truly independent work with safe workspace concurrency.",
+		noLocalWorkGuidance,
+		"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 with subagent_list or subagent_messages, repeatedly check progress, or duplicate the delegated work.",
+	];
+}
 
 export interface StatefulSubagentDependencies {
 	createInProcessSession?: ChildSessionFactory;
+	workspaceManager?: WorkspaceManager;
+}
+
+export interface StatefulSubagentRuntimeStatus {
+	enabled: boolean;
+	initialized: boolean;
+	transport: "subprocess" | "in-process";
+	completionDelivery: CompletionDelivery;
+	activeAgents: number;
+	retainedAgents: number;
+}
+
+export interface StatefulSubagentController {
+	getCompletionDelivery(): CompletionDelivery;
+	setCompletionDelivery(value: CompletionDelivery): void;
+	getRuntimeStatus(): StatefulSubagentRuntimeStatus;
+	listAgents(includeClosed?: boolean): ManagedAgent[];
+	clearAgents(): Promise<number>;
 }
 
 export function registerStatefulSubagents(
 	pi: ExtensionAPI,
 	dependencies: StatefulSubagentDependencies = {},
-): void {
+): StatefulSubagentController {
 	const settings = readSubagentSettings()?.stateful ?? {};
-	if (settings.enabled === false) return;
-
+	const enabled = settings.enabled !== false;
+	const transportKind = resolveStatefulTransportKind(settings.transport);
+	let completionDelivery = resolveCompletionDelivery(settings.completionDelivery);
+	let completionBroker: CompletionDeliveryBroker | undefined;
+	let refreshSpawnToolRegistration: (() => void) | undefined;
 	let registry: AgentRegistry | undefined;
 	let persistence: AgentPersistence | undefined;
 	let sweepTimer: NodeJS.Timeout | undefined;
 	let runtimeGeneration = 0;
-	const workspaceManager = new WorkspaceManager();
+	const workspaceManager = dependencies.workspaceManager ?? new WorkspaceManager();
 	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 clearAgents = async (): Promise<number> => {
+		const currentRegistry = registry;
+		if (!currentRegistry) return 0;
+		const count = currentRegistry.list().length;
+		try {
+			await currentRegistry.closeAll();
+		} finally {
+			await workspaceManager.cleanupAll();
+			isolatedAgents.clear();
+		}
+		seenMessageIds.clear();
+		await persistence?.delete();
+		return count;
+	};
+	const controller: StatefulSubagentController = {
+		getCompletionDelivery() {
+			return completionDelivery;
+		},
+		setCompletionDelivery(value) {
+			completionDelivery = value;
+			completionBroker?.setDelivery(value);
+			refreshSpawnToolRegistration?.();
+		},
+		getRuntimeStatus() {
+			const agents = registry?.list(true) ?? [];
+			return {
+				enabled,
+				initialized: registry !== undefined,
+				transport: transportKind,
+				completionDelivery,
+				activeAgents: agents.filter(
+					(agent) => agent.state === "starting" || agent.state === "running",
+				).length,
+				retainedAgents: agents.filter((agent) => agent.state !== "closed").length,
+			};
+		},
+		listAgents(includeClosed = false) {
+			return registry?.list(includeClosed) ?? [];
+		},
+		clearAgents,
+	};
+	if (!enabled) return controller;
 
 	const requireRegistry = () => {
 		if (!registry) throw new Error("Stateful subagents are not initialized for this session");
@@ -69,24 +160,34 @@ export function registerStatefulSubagents(
 
 	pi.on("session_start", async (_event, ctx) => {
 		const generation = ++runtimeGeneration;
-		rememberCancelledRecovery(orchestration.supersedePending(), cancelledRecoveryNonces);
-		orchestration.reset();
+		completionBroker?.close();
+		completionBroker = undefined;
 		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,
 		});
 		persistence = sessionPersistence;
+		completionBroker = new CompletionDeliveryBroker(pi, ctx, completionDelivery, {
+			onDeliveryError: (error) => {
+				if (!ctx.hasUI) return;
+				const reason = error instanceof Error ? error.message : String(error);
+				ctx.ui.notify(`Subagent completion delivery failed: ${reason}`, "warning");
+			},
+		});
 		const transport =
-			resolveStatefulTransportKind(settings.transport) === "in-process"
+			transportKind === "in-process"
 				? new InProcessTransport({
 						modelRegistry: ctx.modelRegistry,
 						getParentRuntime: () => ({ ...parentRuntime }),
 						createSession: dependencies.createInProcessSession,
 					})
-				: new SubprocessTransport(ctx);
+				: new SubprocessTransport();
 		registry = new AgentRegistry(transport, {
 			maxAgents: settings.maxAgents,
 			maxActiveTurns: settings.maxActiveTurns,
@@ -112,18 +213,14 @@ export function registerStatefulSubagents(
 			},
 			onTurnComplete: (completion) => {
 				if (generation !== runtimeGeneration) return;
-				orchestration.complete(completion.agent.id);
-				if (!completionWaiters.has(completion.agent.id)) {
-					sendDetachedCompletion(pi, completion);
-				}
+				completionBroker?.enqueue(completion);
 			},
 		});
 		const restored = sessionPersistence
 			.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,36 +237,12 @@ 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_start", () => {
+		completionBroker?.onParentTurnStart();
 	});
 
-	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("agent_settled", () => {
+		completionBroker?.onParentSettled();
 	});
 
 	pi.on("model_select", (event) => {
@@ -182,8 +255,8 @@ export function registerStatefulSubagents(
 
 	pi.on("session_shutdown", async (_event, ctx) => {
 		runtimeGeneration++;
-		rememberCancelledRecovery(orchestration.supersedePending(), cancelledRecoveryNonces);
-		orchestration.reset();
+		completionBroker?.close();
+		completionBroker = undefined;
 		if (sweepTimer) clearInterval(sweepTimer);
 		sweepTimer = undefined;
 		for (const agentId of isolatedAgents.keys()) {
@@ -191,41 +264,35 @@ export function registerStatefulSubagents(
 		}
 		isolatedAgents.clear();
 		seenMessageIds.clear();
-		completionWaiters.clear();
 		let cleanupError: unknown;
 		try {
 			await workspaceManager.cleanupAll();
 		} catch (error) {
 			cleanupError = error;
 		}
-		await registry?.shutdown();
-		registry = undefined;
-		persistence = undefined;
+		try {
+			await registry?.shutdown();
+		} finally {
+			registry = undefined;
+			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({
+	const spawnTool = defineTool({
 		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 with an optional thinking level chosen for the task difficulty, 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.",
-		],
+		promptGuidelines: createSpawnPromptGuidelines(completionDelivery),
 		parameters: Type.Object({
 			agent: Type.String({ minLength: 1 }),
 			task: Type.String({ minLength: 1, maxLength: DEFAULT_MAX_CONTEXT_BYTES }),
+			thinkingLevel: Type.Optional(StatefulThinkingLevelSchema),
 			cwd: Type.Optional(Type.String()),
 			agentScope: Type.Optional(ScopeSchema),
 			confirmProjectAgents: Type.Optional(Type.Boolean({ default: true })),
@@ -247,13 +314,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 +330,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 =
@@ -288,6 +344,7 @@ export function registerStatefulSubagents(
 					task: params.task,
 					cwd: workspace?.path ?? requestedCwd,
 					agentScope: scope,
+					thinkingLevel: params.thinkingLevel,
 					parentId: params.parentId,
 					context: snapshot.text || undefined,
 					contextSourceIds: snapshot.sourceIds,
@@ -298,13 +355,21 @@ export function registerStatefulSubagents(
 				throw error;
 			}
 			if (workspace) isolatedAgents.set(agent.id, workspaceOwner);
-			trackSpawnedAgent(orchestration, agent);
+			const deliveryNote =
+				completionDelivery === "auto-resume"
+					? "If no useful local work remains, briefly tell the user what was launched and end the response; auto-resume will request synthesis after completion."
+					: "End the response without the result only when the current response does not depend on it; next-turn delivery will not wake an idle root.";
 			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. ${deliveryNote} Do not poll for progress.`,
 			);
 		},
 	});
+	refreshSpawnToolRegistration = () => {
+		spawnTool.promptGuidelines = createSpawnPromptGuidelines(completionDelivery);
+		pi.registerTool(spawnTool);
+	};
+	refreshSpawnToolRegistration();
 
 	pi.registerTool({
 		name: "subagent_send",
@@ -334,7 +399,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 +448,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 {
@@ -396,35 +458,6 @@ 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.",
-		parameters: Type.Object({
-			agentId: Type.String(),
-			timeoutMs: Type.Optional(Type.Number({ minimum: 1, maximum: 3_600_000, default: 30_000 })),
-		}),
-		async execute(_id, params, signal) {
-			const existing = requireRegistry().get(params.agentId);
-			const registered = existing?.state === "starting" || existing?.state === "running";
-			if (registered) {
-				completionWaiters.set(params.agentId, (completionWaiters.get(params.agentId) ?? 0) + 1);
-			}
-			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
-						? `Wait timed out; ${waited.agent.id} is ${waited.agent.state}.`
-						: formatFinal(waited.agent),
-				);
-			} finally {
-				if (registered) decrementWaiter(completionWaiters, params.agentId);
-			}
-		},
-	});
-
 	pi.registerTool({
 		name: "subagent_list",
 		label: "List Subagents",
@@ -436,9 +469,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) },
@@ -457,10 +488,12 @@ export function registerStatefulSubagents(
 		async execute(_id, params) {
 			if (params.subtree) {
 				const agents = await requireRegistry().interruptTree(params.agentId);
+				const root = requireRegistry().get(params.agentId);
+				if (!root) throw new Error(`Unknown subagent: ${params.agentId}`);
 				return {
 					content: [{ type: "text", text: `Interrupted ${agents.length} active agent(s).` }],
 					details: {
-						agent: summarizeAgent(requireRegistry().get(params.agentId)!),
+						agent: summarizeAgent(root),
 						agents: agents.map(summarizeAgent),
 					},
 				};
@@ -481,7 +514,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,11 +526,12 @@ export function registerStatefulSubagents(
 				} finally {
 					await cleanupClosedWorkspaces(requireRegistry(), isolatedAgents, workspaceManager);
 				}
-				for (const closed of agents) orchestration.resolve(closed.id);
+				const root = requireRegistry().get(params.agentId);
+				if (!root) throw new Error(`Unknown subagent: ${params.agentId}`);
 				return {
 					content: [{ type: "text", text: `Closed ${agents.length} agent(s).` }],
 					details: {
-						agent: summarizeAgent(requireRegistry().get(params.agentId)!),
+						agent: summarizeAgent(root),
 						agents: agents.map(summarizeAgent),
 					},
 				};
@@ -509,39 +542,44 @@ export function registerStatefulSubagents(
 			} finally {
 				await cleanupClosedWorkspaces(requireRegistry(), isolatedAgents, workspaceManager);
 			}
-			orchestration.resolve(agent.id);
 			return result(agent, `Closed ${agent.id}.`);
 		},
 	});
 
 	pi.registerCommand("subagents:agents", {
-		description: "Inspect or clear stateful subagents",
+		description: "Inspect or clear current-session subagents",
 		getArgumentCompletions(prefix: string) {
 			return ["list", "clear"]
 				.filter((value) => value.startsWith(prefix))
 				.map((value) => ({ value, label: value }));
 		},
 		async handler(args, ctx) {
-			if (args.trim() === "clear") {
-				try {
-					await requireRegistry().closeAll();
-				} finally {
-					await workspaceManager.cleanupAll();
-					isolatedAgents.clear();
-				}
-				seenMessageIds.clear();
-				orchestration.reset();
-				await persistence?.delete();
-				ctx.ui.notify("Cleared stateful subagents.", "info");
+			const subcommand = args.trim().toLowerCase() || "list";
+			if (subcommand === "clear") {
+				const count = await controller.clearAgents();
+				ctx.ui.notify(
+					count > 0
+						? `Cleared ${count} current-session subagent${count === 1 ? "" : "s"}.`
+						: statefulEmptyMessage(controller.getRuntimeStatus()),
+					"info",
+				);
 				return;
 			}
-			const agents = requireRegistry().list(true);
+			if (subcommand !== "list") {
+				ctx.ui.notify(`Unknown /subagents:agents subcommand: ${subcommand}`, "warning");
+				return;
+			}
+			const agents = controller.listAgents(true);
 			ctx.ui.notify(
-				agents.length ? agents.map(formatLine).join("\n") : "No stateful subagents.",
+				agents.length
+					? agents.map(formatLine).join("\n")
+					: statefulEmptyMessage(controller.getRuntimeStatus()),
 				"info",
 			);
 		},
 	});
+
+	return controller;
 }
 
 export function assertNoSharedWriteConflict(
@@ -564,7 +602,7 @@ export function assertNoSharedWriteConflict(
 		if (isWriteCapable(activeConfig?.tools)) {
 			throw new Error(
 				`Write-capable subagent ${active.id} is already active in shared workspace ${cwd}. ` +
-					"For independent one-shot work, use subagent parallel mode. Otherwise wait or close the active agent; set allowConcurrentWrites only when overlapping writes are knowingly safe, or use workspaceMode worktree when repository isolation is needed.",
+					"Prefer one subagent_spawn covering combined asynchronous work. Use the blocking subagent parallel mode only when concurrent synchronous outputs justify making the main agent unavailable. Otherwise let the active agent finish or close it; set allowConcurrentWrites only when overlapping writes are knowingly safe, or use workspaceMode worktree when repository isolation is needed.",
 			);
 		}
 	}
@@ -577,12 +615,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 {
@@ -590,12 +623,6 @@ export function isWriteCapable(tools: string[] | undefined): boolean {
 	return tools.some((tool) => ["bash", "write", "edit"].includes(tool));
 }
 
-function decrementWaiter(waiters: Map<string, number>, agentId: string): void {
-	const count = waiters.get(agentId);
-	if (count === undefined || count <= 1) waiters.delete(agentId);
-	else waiters.set(agentId, count - 1);
-}
-
 async function confirmProjectAgent(
 	name: string,
 	scope: AgentScope,
@@ -614,7 +641,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 +653,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));
@@ -639,23 +667,40 @@ export function resolveSpawnContextMode(
 	return normalizeContextMode(value);
 }
 
-function formatLine(agent: ManagedAgent): string {
+function statefulEmptyMessage(status: StatefulSubagentRuntimeStatus): string {
+	if (!status.enabled) return "Stateful subagents are disabled in user settings.";
+	if (!status.initialized) return "Stateful subagents are not initialized for this session.";
+	return "No current-session subagents.";
+}
+
+export function formatStatefulAgentLine(agent: ManagedAgent): string {
 	const elapsedSeconds = Math.max(0, Math.floor((Date.now() - agent.updatedAt) / 1000));
 	const actions =
 		agent.state === "running" || agent.state === "starting"
-			? "wait, interrupt, close"
+			? "interrupt, close"
 			: agent.state === "closed"
 				? "inspect"
 				: "send, close";
-	const task = agent.currentTask ? ` — ${agent.currentTask.slice(0, 80)}` : "";
+	const task = agent.currentTask ? ` — ${sanitizeStatusLine(agent.currentTask, 80)}` : "";
 	const unread = agent.mailbox.filter((message) => !message.readAt).length;
 	const indent = "  ".repeat(agent.depth);
-	return `${indent}${agent.id} ${agent.agent} ${agent.state} ${elapsedSeconds}s unread:${unread} [${actions}]${task}`;
+	const thinking = agent.thinkingLevel ? ` thinking:${agent.thinkingLevel}` : "";
+	return `${indent}${sanitizeStatusLine(agent.id, 128)} ${sanitizeStatusLine(agent.agent, 128)} ${agent.state} ${elapsedSeconds}s${thinking} unread:${unread} [${actions}]${task}`;
 }
 
-function formatFinal(agent: ManagedAgent): string {
-	const last = agent.history.at(-1);
-	return last?.output || agent.error || `${agent.id} is ${agent.state}.`;
+function sanitizeStatusLine(value: string, maxLength: number): string {
+	return (
+		value
+			.slice(0, maxLength)
+			// biome-ignore lint/suspicious/noControlCharactersInRegex: Escape untrusted terminal controls.
+			.replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ")
+			.replace(/\s+/gu, " ")
+			.trim()
+	);
+}
+
+function formatLine(agent: ManagedAgent): string {
+	return formatStatefulAgentLine(agent);
 }
 
 function summarizeAgent(agent: ManagedAgent) {
@@ -670,6 +715,7 @@ function summarizeAgent(agent: ManagedAgent) {
 		createdAt: agent.createdAt,
 		updatedAt: agent.updatedAt,
 		cwd: agent.cwd,
+		thinkingLevel: agent.thinkingLevel,
 		currentTask: agent.currentTask
 			? truncateUtf8(agent.currentTask, MAX_TOOL_MESSAGE_BYTES).text
 			: undefined,
@@ -680,99 +726,188 @@ 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);
-	}
+interface CompletionMetadata {
+	agentId: string;
+	agent: string;
+	state: string;
 }
 
-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);
+interface CompletionMessage {
+	customType: "pi-subagent-completion";
+	content: string;
+	display: true;
+	details:
+		| CompletionMetadata
+		| {
+				completionCount: number;
+				completions: CompletionMetadata[];
+		  };
 }
 
-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);
+type CompletionContext = Pick<ExtensionContext, "hasPendingMessages" | "isIdle">;
+type CompletionPi = Pick<ExtensionAPI, "sendMessage">;
+
+export interface CompletionDeliveryBrokerOptions {
+	onDeliveryError?: (error: unknown) => void;
 }
 
-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");
+/**
+ * Coalesces detached completions so one bounded notification batch starts at
+ * most one root synthesis turn. The broker belongs to one parent session and
+ * must be closed when that session is replaced or shut down.
+ */
+export class CompletionDeliveryBroker {
+	private pending: AgentTurnCompletion[] = [];
+	private flushTimer?: NodeJS.Timeout;
+	private wakeInFlight = false;
+	private closed = false;
+
+	constructor(
+		private readonly pi: CompletionPi,
+		private readonly ctx: CompletionContext,
+		private delivery: CompletionDelivery,
+		private readonly options: CompletionDeliveryBrokerOptions = {},
+	) {}
+
+	enqueue(completion: AgentTurnCompletion): void {
+		if (this.closed) return;
+		this.pending.push(completion);
+		this.scheduleFlush();
+	}
+
+	setDelivery(value: CompletionDelivery): void {
+		this.delivery = value;
+		this.scheduleFlush();
+	}
+
+	onParentTurnStart(): void {
+		this.wakeInFlight = false;
+		this.scheduleFlush();
+	}
+
+	onParentSettled(): void {
+		this.wakeInFlight = false;
+		this.scheduleFlush();
+	}
+
+	flush(): void {
+		if (this.closed || this.pending.length === 0) return;
+		if (this.flushTimer) clearTimeout(this.flushTimer);
+		this.flushTimer = undefined;
+		if (this.delivery === "auto-resume" && !this.isRootIdle()) return;
+
+		const completions = this.pending.splice(0);
+		const batches = chunkCompletions(completions);
+		let canWake = this.shouldWakeRoot();
+		for (let index = 0; index < batches.length; index++) {
+			const triggerTurn = canWake && index === batches.length - 1;
+			const message = buildCompletionMessage(batches[index]);
+			if (triggerTurn) this.wakeInFlight = true;
+			try {
+				this.pi.sendMessage(message, { deliverAs: "steer", triggerTurn });
+			} catch (primaryError) {
+				if (triggerTurn) this.wakeInFlight = false;
+				canWake = false;
+				try {
+					this.pi.sendMessage(message, { deliverAs: "nextTurn", triggerTurn: false });
+				} catch (fallbackError) {
+					this.pending = [...batches.slice(index).flat(), ...this.pending];
+					try {
+						this.options.onDeliveryError?.(
+							new AggregateError(
+								[primaryError, fallbackError],
+								"Detached subagent completion delivery failed",
+							),
+						);
+					} catch {
+						// Delivery retention must survive a failing observer.
+					}
+					return;
+				}
+			}
 		}
 	}
-}
 
-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");
+	close(): void {
+		this.closed = true;
+		if (this.flushTimer) clearTimeout(this.flushTimer);
+		this.flushTimer = undefined;
+		this.pending = [];
+	}
+
+	private scheduleFlush(): void {
+		if (this.closed || this.pending.length === 0 || this.flushTimer) return;
+		this.flushTimer = setTimeout(() => {
+			this.flushTimer = undefined;
+			this.flush();
+		}, COMPLETION_BATCH_DELAY_MS);
+	}
+
+	private isRootIdle(): boolean {
+		try {
+			return this.ctx.isIdle();
+		} catch {
+			return false;
+		}
+	}
+
+	private shouldWakeRoot(): boolean {
+		if (this.delivery !== "auto-resume" || this.wakeInFlight) return false;
+		try {
+			return !this.ctx.hasPendingMessages();
+		} catch {
+			return false;
 		}
-		return false;
 	}
 }
 
-function hasPendingRootMessages(ctx: ExtensionContext): boolean {
-	try {
-		return ctx.hasPendingMessages();
-	} catch {
-		return true;
+function chunkCompletions(completions: AgentTurnCompletion[]): AgentTurnCompletion[][] {
+	const batches: AgentTurnCompletion[][] = [];
+	for (let index = 0; index < completions.length; index += MAX_COMPLETIONS_PER_MESSAGE) {
+		batches.push(completions.slice(index, index + MAX_COMPLETIONS_PER_MESSAGE));
 	}
+	return batches;
 }
 
-function sendDetachedCompletion(
-	pi: ExtensionAPI,
-	completion: AgentTurnCompletion,
-): void {
-	const content = buildDetachedCompletionMessage(completion);
-	pi.sendMessage(
-		{
+function buildCompletionMessage(completions: AgentTurnCompletion[]): CompletionMessage {
+	if (completions.length === 1) {
+		const completion = completions[0];
+		return {
 			customType: "pi-subagent-completion",
-			content,
+			content: buildDetachedCompletionMessage(completion),
 			display: true,
-			details: {
-				agentId: completion.agent.id,
-				agent: completion.agent.agent,
-				state: completion.agent.state,
-			},
+			details: completionMetadata(completion),
+		};
+	}
+	const content = truncateUtf8(
+		[
+			"Message Type: SUBAGENT_COMPLETION_BATCH",
+			`Completion Count: ${completions.length}`,
+			...completions.flatMap((completion, index) => [
+				"",
+				`--- Completion ${index + 1} of ${completions.length} ---`,
+				buildDetachedCompletionMessage(completion),
+			]),
+		].join("\n"),
+		DEFAULT_MAX_CONTEXT_BYTES,
+	).text;
+	return {
+		customType: "pi-subagent-completion",
+		content,
+		display: true,
+		details: {
+			completionCount: completions.length,
+			completions: completions.map(completionMetadata),
 		},
-		{ deliverAs: "steer", triggerTurn: false },
-	);
+	};
+}
+
+function completionMetadata(completion: AgentTurnCompletion): CompletionMetadata {
+	return {
+		agentId: completion.agent.id,
+		agent: completion.agent.agent,
+		state: completion.agent.state,
+	};
 }
 
 export function buildDetachedCompletionMessage(completion: AgentTurnCompletion): string {
@@ -798,10 +933,13 @@ export function buildDetachedCompletionMessage(completion: AgentTurnCompletion):
 }
 
 function sanitizeCompletionLine(value: string, maxBytes: number): string {
-	return truncateUtf8(redactPrivateText(value), maxBytes).text
-		.replace(/[\u0000-\u001f\u007f]+/g, " ")
-		.replace(/\s+/g, " ")
-		.trim();
+	return (
+		truncateUtf8(redactPrivateText(value), maxBytes)
+			// biome-ignore lint/suspicious/noControlCharactersInRegex: Strip untrusted terminal controls.
+			.text.replace(/[\u0000-\u001f\u007f]+/g, " ")
+			.replace(/\s+/g, " ")
+			.trim()
+	);
 }
 
 async function cleanupClosedWorkspaces(
@@ -829,6 +967,12 @@ export function resolveStatefulTransportKind(
 	return value ?? "subprocess";
 }
 
+export function resolveCompletionDelivery(
+	value: CompletionDelivery | undefined,
+): CompletionDelivery {
+	return value ?? "next-turn";
+}
+
 function normalizeRuntimeThinkingLevel(value: string): ParentRuntimeSnapshot["thinkingLevel"] {
 	return isThinkingLevel(value) ? value : "off";
 }