@narumitw/pi-subagents 0.25.0 → 0.26.0

package/src/stateful.ts

@@ -1,21 +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 { 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([
@@ -27,29 +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 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");
@@ -58,6 +160,8 @@ export function registerStatefulSubagents(
 
 	pi.on("session_start", async (_event, ctx) => {
 		const generation = ++runtimeGeneration;
+		completionBroker?.close();
+		completionBroker = undefined;
 		parentRuntime.model = ctx.model;
 		parentRuntime.thinkingLevel = normalizeRuntimeThinkingLevel(pi.getThinkingLevel());
 		const owner =
@@ -69,14 +173,21 @@ export function registerStatefulSubagents(
 			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,
@@ -102,9 +213,7 @@ export function registerStatefulSubagents(
 			},
 			onTurnComplete: (completion) => {
 				if (generation !== runtimeGeneration) return;
-				if (!completionWaiters.has(completion.agent.id)) {
-					sendDetachedCompletion(pi, completion);
-				}
+				completionBroker?.enqueue(completion);
 			},
 		});
 		const restored = sessionPersistence
@@ -128,6 +237,14 @@ export function registerStatefulSubagents(
 		sweepTimer.unref();
 	});
 
+	pi.on("agent_start", () => {
+		completionBroker?.onParentTurnStart();
+	});
+
+	pi.on("agent_settled", () => {
+		completionBroker?.onParentSettled();
+	});
+
 	pi.on("model_select", (event) => {
 		parentRuntime.model = event.model;
 	});
@@ -138,6 +255,8 @@ export function registerStatefulSubagents(
 
 	pi.on("session_shutdown", async (_event, ctx) => {
 		runtimeGeneration++;
+		completionBroker?.close();
+		completionBroker = undefined;
 		if (sweepTimer) clearInterval(sweepTimer);
 		sweepTimer = undefined;
 		for (const agentId of isolatedAgents.keys()) {
@@ -145,39 +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");
 		}
 	});
 
-	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.",
+			"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 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.",
-		],
+		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 })),
@@ -229,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,
@@ -239,12 +355,21 @@ export function registerStatefulSubagents(
 				throw error;
 			}
 			if (workspace) isolatedAgents.set(agent.id, workspaceOwner);
+			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}. 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.`,
+				`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",
@@ -333,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. 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 })),
-		}),
-		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);
-				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",
@@ -392,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),
 					},
 				};
@@ -428,10 +526,12 @@ export function registerStatefulSubagents(
 				} finally {
 					await cleanupClosedWorkspaces(requireRegistry(), isolatedAgents, workspaceManager);
 				}
+				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),
 					},
 				};
@@ -447,32 +547,39 @@ export function registerStatefulSubagents(
 	});
 
 	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();
-				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(
@@ -495,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.",
 			);
 		}
 	}
@@ -516,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,
@@ -566,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) {
@@ -597,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,
@@ -607,21 +726,188 @@ function summarizeAgent(agent: ManagedAgent) {
 	};
 }
 
-function sendDetachedCompletion(pi: ExtensionAPI, completion: AgentTurnCompletion): void {
-	const content = buildDetachedCompletionMessage(completion);
-	pi.sendMessage(
-		{
+interface CompletionMetadata {
+	agentId: string;
+	agent: string;
+	state: string;
+}
+
+interface CompletionMessage {
+	customType: "pi-subagent-completion";
+	content: string;
+	display: true;
+	details:
+		| CompletionMetadata
+		| {
+				completionCount: number;
+				completions: CompletionMetadata[];
+		  };
+}
+
+type CompletionContext = Pick<ExtensionContext, "hasPendingMessages" | "isIdle">;
+type CompletionPi = Pick<ExtensionAPI, "sendMessage">;
+
+export interface CompletionDeliveryBrokerOptions {
+	onDeliveryError?: (error: unknown) => void;
+}
+
+/**
+ * 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;
+				}
+			}
+		}
+	}
+
+	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;
+		}
+	}
+}
+
+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 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 {
@@ -647,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(
@@ -678,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";
 }