@narumitw/pi-subagents 0.54.0 → 1.0.0

package/README.md

@@ -299,8 +299,8 @@ No benchmark result in this release changes the default delegation policy or mak
 | --- | --- | --- |
 | `list_agents` | Optional `agentScope` (default `user`) and `limit` (default 32, maximum 100) | Bounded agent metadata and omission counts |
 | `get_agent` | Required `agent`; optional `agentScope` | One resolved definition, safe source path, configured tools, and consultation-effective tools; never the system prompt |
-| `list_runs` | Optional `includeClosed` and `limit` (default 50, maximum 100) | Metadata-only retained-run summaries and unread counts |
-| `get_run` | Required `agentId` | Safe `cwd`, current-task/error summaries, thinking level, context footprint, protocol, effective transport, bounded timing/usage telemetry, structured result when valid, policy, history count, and unread count |
+| `list_runs` | Optional `includeClosed` and `limit` (default 50, maximum 100) | Metadata-only retained-run summaries, turn generation, pending-completion count, and unread counts |
+| `get_run` | Required `agentId` | Safe `cwd`, current run and turn generation, current-task/error summaries, thinking level, context footprint, protocol, effective transport, bounded timing/usage telemetry, structured result when valid, policy, history count, pending-completion count, and unread count |
 | `list_workflows` | Optional `limit` (default 50, maximum 100) | Metadata-only persisted blocking-workflow summaries for the current session |
 | `get_workflow` | Required `workflowId` | Bounded task states, generations, dependencies, plan identities, artifact metadata, verification state, and outcome reasons without artifact contents |
 | `list_models` | Optional `limit` (default 50, maximum 100) | Session-scoped models, or the already-loaded available snapshot |
@@ -310,7 +310,7 @@ No benchmark result in this release changes the default delegation policy or mak
 
 The schema rejects fields that do not belong to the selected action. Explicit `project` or `both` scope fails before project-agent discovery unless Pi already trusts the project. Run inspection never returns history output, stored context, or mailbox content; unread counts come from a metadata-only snapshot and do not acknowledge messages. Workflow inspection reads validated, redacted snapshots without quarantining or rewriting invalid files. Paths beneath the Pi agent directory use `~`, project paths are workspace-relative, model objects are projected through an allow-list, and model-facing text is bounded to 50 KiB or 2,000 lines.
 
-Compatibility: `subagent_manage({ "action": "list" })` remains supported with its existing behavior. Prefer `subagent_inspect` when a whole tool must be safe to activate on a read-only surface.
+`subagent_manage` no longer accepts its former compatibility `list` action. Use `subagent_inspect({ "action": "list_runs", "includeClosed": true })` for metadata-only discovery and `get_run` for detail.
 
 ## 📖 Read-only consultation
 
@@ -599,9 +599,9 @@ Legacy v1 and v2 records without acceptance fields retain their prior completed
 
 ## 🔁 Stateful agents
 
-Stateful lifecycle tools are available by default. `subagent_spawn` is detached: it schedules work, returns immediately with an opaque `agentId`, and later injects a bounded `pi-subagent-completion` custom message. Completions that settle in the same dispatch window are batched, and the broker allows at most one in-flight root wake until that parent turn starts.
+Stateful lifecycle tools are available by default. `subagent_spawn` is detached: it schedules work, returns immediately with an opaque `agentId`, and later injects a bounded `pi-subagent-completion` custom message. Every turn receives an executor-owned `runId`, monotonically increasing agent-local generation, and unique `completionId`. The terminal completion is persisted before delivery, simultaneous completions are batched, and the broker allows at most one in-flight root wake until that parent turn starts.
 
-Detached work follows a non-polling policy. With default `next-turn` delivery, prefer one bounded `subagent_spawn` for related asynchronous research or review only when the current response does not depend on its result. If it does, use blocking `subagent` when registered; in **Async only**, complete required work directly, opt into `auto-resume` when a later synthesis turn is appropriate, or switch workflows. With opt-in `auto-resume`, detached broad work may be final-answer-dependent because completion requests a synthesis turn after the root settles. In either mode, do useful non-overlapping main-agent work immediately, do not poll `subagent_manage` with `action: "list"` or `subagent_mailbox` with `action: "read"`, and do not duplicate delegated work. Add another detached agent only for truly independent work with safe workspace concurrency. Detached lifecycle work intentionally has no `subagent_wait` tool.
+Detached work follows a non-polling policy. With default `next-turn` delivery, prefer one bounded `subagent_spawn` for related asynchronous research or review only when the current response does not depend on its result. If it does, use blocking `subagent` when registered; in **Async only**, complete required work directly, opt into `auto-resume` when a later synthesis turn is appropriate, or switch workflows. With opt-in `auto-resume`, detached broad work may be final-answer-dependent because completion requests a synthesis turn after the root settles. In either mode, do useful non-overlapping main-agent work immediately, do not poll `subagent_inspect` or `subagent_mailbox` with `action: "read"`, and do not duplicate delegated work. Add another detached agent only for truly independent work with safe workspace concurrency. Detached lifecycle work intentionally has no `subagent_wait` tool.
 
 A 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.
 
@@ -610,7 +610,7 @@ A detached agent additionally needs a concrete isolation or specialization benef
 - `"next-turn"` (default) preserves the previous behavior: use `deliverAs: "steer"` with `triggerTurn: false`. An active root can consume completion naturally; an idle root is not awakened.
 - `"auto-resume"` holds completion while the root is active, then requests one synthesis turn after the parent settles when no user or extension messages are already pending. Simultaneous completions share that turn, active work is not interrupted, and pending input suppresses the autonomous wake.
 
-Auto-resume is best-effort because Pi's custom-message API is fire-and-forget. Session-generation checks, shutdown cleanup, batching, and the in-flight wake guard prevent stale or duplicate scheduling pressure, but they do not make completion delivery durable across process exit.
+The bounded persisted completion outbox provides ordered at-least-once delivery across process restart without replaying the child turn. When state must be reduced to its storage bound, persistence drops roots without pending completions first and trims old history rather than discarding an outbox-owned root. A completion is acknowledged only after parent context assembly observes its exact `completionId`; an injection that returns synchronously but never reaches context remains pending for retry. If the process exits after context assembly but before acknowledgement is persisted, the same ID can be delivered again and consumers must deduplicate it. Auto-resume wake admission remains best-effort because Pi's custom-message API is fire-and-forget, but an unacknowledged terminal completion itself remains available for redelivery on the next start of the owning session. Transient terminal-persistence failures retry with bounded exponential backoff and keep the run pending; shutdown cancels retry waits and reports a final persistence failure instead of silently resolving unsaved work.
 
 The default `subprocess` transport preserves compatibility: each turn starts a fresh isolated `pi --mode json -p --no-session` child and receives sanitized, bounded history.
 Set `transport` to `in-process` to retain one public Pi SDK `AgentSession` per stateful `agentId`, avoiding repeated process startup while preserving native child history in memory.
@@ -687,7 +687,7 @@ This avoids lifecycle-driven tool-schema churn and preserves a stable provider p
 | --- | --- |
 | `subagent_spawn` | Start detached work with optional task-selected thinking and retained timeout, exact-retry `idempotencyKey`, and `text`, `structured-v1`, or `structured-v2` result format; return an opaque `agentId` immediately and deliver completion asynchronously. |
 | `subagent_send` | Send follow-up work with an optional one-turn timeout override and trigger a new turn on a reusable agent; semantic skew requires explicit `revalidate: true`, and shared-workspace write conflicts are guarded unless explicitly overridden. |
-| `subagent_manage` | Use `action: "list"` to inspect agents, `"interrupt"` to retain an agent after aborting active work, or `"close"` to release it; interrupt/close accept optional `subtree`. |
+| `subagent_manage` | Use `"interrupt"` to retain an agent after aborting active work or `"close"` to release it; both actions accept optional `subtree`. Use `subagent_inspect` for all list and detail operations. |
 | `subagent_mailbox` | Use `action: "send"` for queue-only messages that do not start a turn, or `"read"` to read and optionally acknowledge unread messages. |
 
 The action schemas are flat for provider compatibility and reject parameters that belong to another action. For example:
@@ -721,13 +721,14 @@ The five replaced names are intentionally not registered as aliases. Update expl
 
 | Previous call | Fixed-surface call |
 | --- | --- |
-| `subagent_list({ includeClosed })` | `subagent_manage({ action: "list", includeClosed })` |
+| `subagent_list({ includeClosed })` | `subagent_inspect({ action: "list_runs", includeClosed })` |
+| `subagent_manage({ action: "list", includeClosed })` | `subagent_inspect({ action: "list_runs", includeClosed })` |
 | `subagent_interrupt({ agentId, subtree })` | `subagent_manage({ action: "interrupt", agentId, subtree })` |
 | `subagent_close({ agentId, subtree })` | `subagent_manage({ action: "close", agentId, subtree })` |
 | `subagent_message({ agentId, message, ... })` | `subagent_mailbox({ action: "send", agentId, message, ... })` |
 | `subagent_messages({ agentId, acknowledge, limit })` | `subagent_mailbox({ action: "read", agentId, acknowledge, limit })` |
 
-Persisted agent and mailbox records require no migration. If an explicit prompt in a resumed conversation keeps requesting an old name, update it with the mapping above or start a fresh conversation. To roll back after an upgrade, pin the package version used before the upgrade; for this migration, use `pi install npm:@narumitw/pi-subagents@0.26.0`. The previous release can read the same state directory.
+Persisted agent and mailbox records require no manual migration; older records load with an empty completion outbox and generation zero. If an explicit prompt in a resumed conversation keeps requesting an old name, update it with the mapping above or start a fresh conversation. To roll back after an upgrade, pin the package version used before the upgrade; for this migration, use `pi install npm:@narumitw/pi-subagents@0.26.0`. The previous release can read the same state directory.
 
 A spawn can request a thinking level explicitly:
 

package/package.json

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

package/src/completion-delivery.ts

@@ -12,6 +12,9 @@ const COMPLETION_BATCH_DELAY_MS = 10;
 
 interface CompletionMetadata {
 	protocol: typeof PI_SUBAGENTS_RPC_PROTOCOL;
+	completionId: string;
+	runId: string;
+	generation: number;
 	agentId: string;
 	agent: string;
 	state: string;
@@ -38,13 +41,15 @@ type CompletionPi = Pick<ExtensionAPI, "sendMessage">;
 
 export interface CompletionDeliveryBrokerOptions {
 	onDeliveryError?: (error: unknown) => void;
-	onDelivered?: (completions: readonly AgentTurnCompletion[], deliveredAt: number) => void;
+	onAcknowledged?: (completions: readonly AgentTurnCompletion[], acknowledgedAt: number) => void;
 	now?: () => number;
 }
 
 /** Owns bounded completion batching and at most one idle-root wake for one parent session. */
 export class CompletionDeliveryBroker {
 	private pending: AgentTurnCompletion[] = [];
+	private readonly knownCompletionIds = new Set<string>();
+	private awaitingParentAck: AgentTurnCompletion[] = [];
 	private flushTimer?: NodeJS.Timeout;
 	private wakeInFlight = false;
 	private closed = false;
@@ -57,7 +62,8 @@ export class CompletionDeliveryBroker {
 	) {}
 
 	enqueue(completion: AgentTurnCompletion): void {
-		if (this.closed) return;
+		if (this.closed || this.knownCompletionIds.has(completion.completionId)) return;
+		this.knownCompletionIds.add(completion.completionId);
 		this.pending.push(completion);
 		this.scheduleFlush();
 	}
@@ -72,6 +78,14 @@ export class CompletionDeliveryBroker {
 		this.scheduleFlush();
 	}
 
+	onParentContext(messages: readonly unknown[]): void {
+		this.acknowledgeVisible(completionIdsFromContext(messages));
+		if (this.awaitingParentAck.length > 0) {
+			this.pending = [...this.awaitingParentAck.splice(0), ...this.pending];
+		}
+		this.scheduleFlush();
+	}
+
 	onParentSettled(): void {
 		this.wakeInFlight = false;
 		this.scheduleFlush();
@@ -88,18 +102,21 @@ export class CompletionDeliveryBroker {
 		let canWake = this.shouldWakeRoot();
 		for (let index = 0; index < batches.length; index++) {
 			const triggerTurn = canWake && index === batches.length - 1;
-			const message = buildCompletionMessage(batches[index]);
+			const batch = batches[index];
+			const message = buildCompletionMessage(batch);
 			if (triggerTurn) this.wakeInFlight = true;
+			this.awaitingParentAck.push(...batch);
 			try {
 				this.pi.sendMessage(message, { deliverAs: "steer", triggerTurn });
-				this.notifyDelivered(batches[index]);
 			} catch (primaryError) {
+				this.removeAwaiting(batch);
 				if (triggerTurn) this.wakeInFlight = false;
 				canWake = false;
+				this.awaitingParentAck.push(...batch);
 				try {
 					this.pi.sendMessage(message, { deliverAs: "nextTurn", triggerTurn: false });
-					this.notifyDelivered(batches[index]);
 				} catch (fallbackError) {
+					this.removeAwaiting(batch);
 					this.pending = [...batches.slice(index).flat(), ...this.pending];
 					try {
 						this.options.onDeliveryError?.(
@@ -122,6 +139,8 @@ export class CompletionDeliveryBroker {
 		if (this.flushTimer) clearTimeout(this.flushTimer);
 		this.flushTimer = undefined;
 		this.pending = [];
+		this.awaitingParentAck = [];
+		this.knownCompletionIds.clear();
 	}
 
 	private scheduleFlush(): void {
@@ -132,14 +151,34 @@ export class CompletionDeliveryBroker {
 		}, COMPLETION_BATCH_DELAY_MS);
 	}
 
-	private notifyDelivered(completions: readonly AgentTurnCompletion[]): void {
+	private acknowledgeVisible(visibleIds: ReadonlySet<string>): void {
+		if (visibleIds.size === 0) return;
+		const completions = [...this.awaitingParentAck, ...this.pending].filter((completion) =>
+			visibleIds.has(completion.completionId),
+		);
+		if (completions.length === 0) return;
+		const acknowledgedIds = new Set(completions.map((completion) => completion.completionId));
+		this.awaitingParentAck = this.awaitingParentAck.filter(
+			(completion) => !acknowledgedIds.has(completion.completionId),
+		);
+		this.pending = this.pending.filter(
+			(completion) => !acknowledgedIds.has(completion.completionId),
+		);
+		for (const completion of completions) this.knownCompletionIds.delete(completion.completionId);
 		try {
-			this.options.onDelivered?.(completions, (this.options.now ?? Date.now)());
+			this.options.onAcknowledged?.(completions, (this.options.now ?? Date.now)());
 		} catch {
-			// Delivery already succeeded, so observer failures cannot requeue it.
+			// Context assembly already observed the message, so observer failures cannot retract it.
 		}
 	}
 
+	private removeAwaiting(completions: readonly AgentTurnCompletion[]): void {
+		const removed = new Set(completions.map((completion) => completion.completionId));
+		this.awaitingParentAck = this.awaitingParentAck.filter(
+			(completion) => !removed.has(completion.completionId),
+		);
+	}
+
 	private isRootIdle(): boolean {
 		try {
 			return this.ctx.isIdle();
@@ -158,6 +197,33 @@ export class CompletionDeliveryBroker {
 	}
 }
 
+function completionIdsFromContext(messages: readonly unknown[]): Set<string> {
+	const ids = new Set<string>();
+	for (const message of messages) {
+		if (!message || typeof message !== "object" || Array.isArray(message)) continue;
+		const record = message as Record<string, unknown>;
+		if (record.role !== "custom" || record.customType !== "pi-subagent-completion") continue;
+		const details = record.details;
+		if (!details || typeof details !== "object" || Array.isArray(details)) continue;
+		const metadata = details as Record<string, unknown>;
+		if (
+			metadata.protocol === PI_SUBAGENTS_RPC_PROTOCOL &&
+			typeof metadata.completionId === "string"
+		) {
+			ids.add(metadata.completionId);
+		}
+		if (!Array.isArray(metadata.completions)) continue;
+		for (const completion of metadata.completions) {
+			if (!completion || typeof completion !== "object" || Array.isArray(completion)) continue;
+			const item = completion as Record<string, unknown>;
+			if (item.protocol === PI_SUBAGENTS_RPC_PROTOCOL && typeof item.completionId === "string") {
+				ids.add(item.completionId);
+			}
+		}
+	}
+	return ids;
+}
+
 function chunkCompletions(completions: AgentTurnCompletion[]): AgentTurnCompletion[][] {
 	const batches: AgentTurnCompletion[][] = [];
 	for (let index = 0; index < completions.length; index += MAX_COMPLETIONS_PER_MESSAGE) {
@@ -203,6 +269,9 @@ function buildCompletionMessage(completions: AgentTurnCompletion[]): CompletionM
 function completionMetadata(completion: AgentTurnCompletion): CompletionMetadata {
 	return {
 		protocol: PI_SUBAGENTS_RPC_PROTOCOL,
+		completionId: completion.completionId,
+		runId: completion.runId,
+		generation: completion.generation,
 		agentId: completion.agent.id,
 		agent: completion.agent.agent,
 		state: completion.agent.state,
@@ -233,6 +302,9 @@ export function buildDetachedCompletionMessage(completion: AgentTurnCompletion):
 		[
 			"Message Type: SUBAGENT_COMPLETION",
 			`Protocol: ${PI_SUBAGENTS_RPC_PROTOCOL}`,
+			`Completion ID: ${completion.completionId}`,
+			`Run ID: ${completion.runId}`,
+			`Generation: ${completion.generation}`,
 			`Agent ID: ${completion.agent.id}`,
 			`Agent: ${agentName}`,
 			`Task: ${task}`,

package/src/inspect.ts

@@ -404,6 +404,8 @@ function projectRunSummary(run: AgentRunInspectionSummary): Record<string, unkno
 		updatedAt: run.updatedAt,
 		historyCount: run.historyCount,
 		unreadMessages: run.unreadMessages,
+		turnGeneration: run.turnGeneration,
+		pendingCompletionCount: run.pendingCompletionCount,
 	};
 }
 
@@ -474,6 +476,8 @@ function projectRun(run: AgentRunInspectionDetail, ctx: ExtensionContext): Recor
 			: undefined,
 		semanticCompatibility: run.semanticCompatibility,
 		telemetry: run.telemetry,
+		currentRunId: run.currentRunId,
+		currentTurnGeneration: run.currentTurnGeneration,
 		currentTask: run.currentTask ? boundedPrivateText(run.currentTask, 2 * 1024) : undefined,
 		error: run.error ? boundedPrivateText(run.error, 2 * 1024) : undefined,
 		target: run.target

package/src/persistence.ts

@@ -16,12 +16,13 @@ import { resolveStatefulLimits } from "./stateful-limits.js";
 import { copyTurnTerminationReport, type TurnTerminationReport } from "./timeout-checkpoint.js";
 import { MAX_SUBAGENT_TOOL_CALLS, MAX_SUBAGENT_TURNS } from "./turn-budget.js";
 
-const STATE_VERSION = 2;
+const STATE_VERSION = 3;
+const MAX_STORED_COMPLETIONS_PER_AGENT = 20;
 const DEFAULT_STATEFUL_LIMITS = resolveStatefulLimits();
-const MAX_STATE_BYTES = 1024 * 1024;
+const MAX_STATE_BYTES = 5 * 1024 * 1024;
 
 interface StoredState {
-	version: 2;
+	version: 3;
 	updatedAt: number;
 	agents: ManagedAgent[];
 }
@@ -86,8 +87,19 @@ export class AgentPersistence {
 		const state: StoredState = { version: STATE_VERSION, updatedAt: Date.now(), agents: records };
 		let content = `${JSON.stringify(state, null, "\t")}\n`;
 		while (Buffer.byteLength(content, "utf8") > MAX_STATE_BYTES && state.agents.length > 0) {
-			const oldestRootId = state.agents[0].rootId;
-			state.agents = state.agents.filter((agent) => agent.rootId !== oldestRootId);
+			const rootsWithPendingCompletions = new Set(
+				state.agents
+					.filter((agent) => (agent.pendingCompletions?.length ?? 0) > 0)
+					.map((agent) => agent.rootId),
+			);
+			const droppableRoot = state.agents.find(
+				(agent) => !rootsWithPendingCompletions.has(agent.rootId),
+			)?.rootId;
+			if (droppableRoot) {
+				state.agents = state.agents.filter((agent) => agent.rootId !== droppableRoot);
+			} else if (!trimOldestHistory(state.agents) && !clearOldestContext(state.agents)) {
+				throw new Error("Subagent state exceeds its durable completion storage limit");
+			}
 			content = `${JSON.stringify(state, null, "\t")}\n`;
 		}
 		await fs.promises.mkdir(path.dirname(this.filePath), { recursive: true });
@@ -113,6 +125,27 @@ export class AgentPersistence {
 	}
 }
 
+function trimOldestHistory(agents: ManagedAgent[]): boolean {
+	const candidate = agents
+		.filter((agent) => agent.history.length > 0)
+		.sort(
+			(left, right) =>
+				(left.history[0]?.completedAt ?? Number.POSITIVE_INFINITY) -
+				(right.history[0]?.completedAt ?? Number.POSITIVE_INFINITY),
+		)[0];
+	if (!candidate) return false;
+	candidate.history.shift();
+	return true;
+}
+
+function clearOldestContext(agents: ManagedAgent[]): boolean {
+	const candidate = agents.find((agent) => agent.context !== undefined);
+	if (!candidate) return false;
+	candidate.context = undefined;
+	candidate.contextTruncated = true;
+	return true;
+}
+
 function sanitizeAgent(agent: ManagedAgent): ManagedAgent {
 	return {
 		...agent,
@@ -126,6 +159,17 @@ function sanitizeAgent(agent: ManagedAgent): ManagedAgent {
 		})),
 		state: agent.state === "running" || agent.state === "starting" ? "interrupted" : agent.state,
 		currentTask: undefined,
+		currentRunId: undefined,
+		currentTurnGeneration: undefined,
+		turnGeneration: agent.turnGeneration ?? 0,
+		pendingCompletions: (agent.pendingCompletions ?? [])
+			.slice(-MAX_STORED_COMPLETIONS_PER_AGENT)
+			.map((completion) => ({
+				...completion,
+				task: redactPrivateText(completion.task),
+				output: redactPrivateText(completion.output),
+				error: completion.error ? redactPrivateText(completion.error) : undefined,
+			})),
 		currentTimeoutMs: undefined,
 		currentIdleTimeoutMs: undefined,
 		currentMaxTurns: undefined,
@@ -184,7 +228,10 @@ function sanitizeTermination(report: TurnTerminationReport): TurnTerminationRepo
 function isStoredState(value: unknown): value is StoredState {
 	if (!value || typeof value !== "object") return false;
 	const state = value as { version?: unknown; agents?: unknown };
-	if ((state.version !== 1 && state.version !== STATE_VERSION) || !Array.isArray(state.agents)) {
+	if (
+		(state.version !== 1 && state.version !== 2 && state.version !== STATE_VERSION) ||
+		!Array.isArray(state.agents)
+	) {
 		return false;
 	}
 	return state.agents.every((agent) => {
@@ -208,6 +255,9 @@ function isStoredState(value: unknown): value is StoredState {
 			(record.termination === undefined || isTerminationReport(record.termination)) &&
 			(record.contextTurns === undefined || isNonNegativeInteger(record.contextTurns)) &&
 			(record.contextBytes === undefined || isNonNegativeInteger(record.contextBytes)) &&
+			(record.turnGeneration === undefined || isNonNegativeInteger(record.turnGeneration)) &&
+			(record.pendingCompletions === undefined ||
+				isCompletionOutbox(record.pendingCompletions, record.turnGeneration ?? 0)) &&
 			(record.spawnIdempotencyKey === undefined ||
 				(typeof record.spawnIdempotencyKey === "string" &&
 					record.spawnIdempotencyKey.length > 0 &&
@@ -356,10 +406,59 @@ function isTargetPolicyAudit(value: unknown): boolean {
 	);
 }
 
+function isCompletionOutbox(value: unknown, turnGeneration: number): boolean {
+	if (!Array.isArray(value) || value.length > MAX_STORED_COMPLETIONS_PER_AGENT) return false;
+	const ids = new Set<string>();
+	let previousGeneration = 0;
+	let previousCreatedAt = Number.NEGATIVE_INFINITY;
+	for (const completion of value) {
+		if (!isPersistedCompletion(completion, turnGeneration)) return false;
+		if (ids.has(completion.completionId)) return false;
+		if (completion.generation <= previousGeneration || completion.createdAt <= previousCreatedAt) {
+			return false;
+		}
+		ids.add(completion.completionId);
+		previousGeneration = completion.generation;
+		previousCreatedAt = completion.createdAt;
+	}
+	return true;
+}
+
+function isPersistedCompletion(
+	value: unknown,
+	turnGeneration: number,
+): value is import("./registry.js").PersistedAgentCompletion {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const completion = value as Record<string, unknown>;
+	return (
+		typeof completion.completionId === "string" &&
+		completion.completionId.length > 0 &&
+		completion.completionId.length <= 256 &&
+		typeof completion.runId === "string" &&
+		completion.runId.length > 0 &&
+		completion.runId.length <= 256 &&
+		typeof completion.generation === "number" &&
+		Number.isSafeInteger(completion.generation) &&
+		completion.generation >= 1 &&
+		completion.generation <= turnGeneration &&
+		typeof completion.task === "string" &&
+		typeof completion.output === "string" &&
+		(completion.error === undefined || typeof completion.error === "string") &&
+		typeof completion.createdAt === "number" &&
+		Number.isFinite(completion.createdAt)
+	);
+}
+
 function isAgentTurn(value: unknown): boolean {
 	if (!value || typeof value !== "object") return false;
 	const turn = value as Record<string, unknown>;
 	return (
+		(turn.runId === undefined ||
+			(typeof turn.runId === "string" && turn.runId.length > 0 && turn.runId.length <= 256)) &&
+		(turn.generation === undefined ||
+			(typeof turn.generation === "number" &&
+				Number.isSafeInteger(turn.generation) &&
+				turn.generation >= 1)) &&
 		typeof turn.task === "string" &&
 		typeof turn.output === "string" &&
 		typeof turn.startedAt === "number" &&

package/src/registry-types.ts

@@ -23,6 +23,8 @@ export type AgentLifecycleState =
 	| "closed";
 
 export interface AgentTurn {
+	runId?: string;
+	generation?: number;
 	task: string;
 	output: string;
 	startedAt: number;
@@ -32,6 +34,16 @@ export interface AgentTurn {
 	termination?: TurnTerminationReport;
 }
 
+export interface PersistedAgentCompletion {
+	completionId: string;
+	runId: string;
+	generation: number;
+	task: string;
+	output: string;
+	error?: string;
+	createdAt: number;
+}
+
 export interface AgentMailboxMessage {
 	id: string;
 	senderId: string;
@@ -64,6 +76,10 @@ export interface ManagedAgent {
 	maxToolCalls?: number;
 	currentMaxToolCalls?: number;
 	currentTask?: string;
+	turnGeneration?: number;
+	currentRunId?: string;
+	currentTurnGeneration?: number;
+	pendingCompletions?: PersistedAgentCompletion[];
 	history: AgentTurn[];
 	error?: string;
 	context?: string;
@@ -98,6 +114,8 @@ export interface AgentRunInspectionSummary {
 	updatedAt: number;
 	historyCount: number;
 	unreadMessages: number;
+	turnGeneration: number;
+	pendingCompletionCount: number;
 }
 
 export interface AgentRunInspectionDetail extends AgentRunInspectionSummary {
@@ -112,6 +130,8 @@ export interface AgentRunInspectionDetail extends AgentRunInspectionSummary {
 	maxToolCalls?: number;
 	currentMaxToolCalls?: number;
 	currentTask?: string;
+	currentRunId?: string;
+	currentTurnGeneration?: number;
 	error?: string;
 	workspaceMode?: "worktree";
 	contextTurns?: number;
@@ -151,11 +171,8 @@ export interface TurnOutcome {
 	telemetry?: TransportTelemetry;
 }
 
-export interface AgentTurnCompletion {
+export interface AgentTurnCompletion extends PersistedAgentCompletion {
 	agent: ManagedAgent;
-	task: string;
-	output: string;
-	error?: string;
 }
 
 export interface AgentRegistryOptions {

package/src/registry.ts

@@ -21,6 +21,7 @@ import {
 	DEFAULT_MAX_CONTEXT_BYTES,
 	DEFAULT_MAX_OUTPUT_BYTES,
 	MAX_SUBAGENT_TIMEOUT_MS,
+	MAX_TOOL_MESSAGE_BYTES,
 	truncateUtf8,
 } from "./limits.js";
 import { classifyStructuredOutcome } from "./outcome.js";
@@ -47,6 +48,9 @@ import type { TransportTelemetry } from "./transport-types.js";
 import { type TurnLimits, validateTurnLimits } from "./turn-budget.js";
 
 const DEFAULT_STATEFUL_LIMITS = resolveStatefulLimits();
+const MAX_PENDING_COMPLETIONS_PER_AGENT = 20;
+const INITIAL_PERSISTENCE_RETRY_DELAY_MS = 25;
+const MAX_PERSISTENCE_RETRY_DELAY_MS = 1_000;
 
 export type * from "./registry-types.js";
 
@@ -73,6 +77,8 @@ function validateTurnTimeout(value: number): number {
 
 function clearCurrentTurn(agent: ManagedAgent): void {
 	agent.currentTask = undefined;
+	agent.currentRunId = undefined;
+	agent.currentTurnGeneration = undefined;
 	agent.currentTimeoutMs = undefined;
 	agent.currentIdleTimeoutMs = undefined;
 	agent.currentMaxTurns = undefined;
@@ -86,6 +92,21 @@ function waitAbortError(): Error {
 	return error;
 }
 
+function waitForPersistenceRetry(milliseconds: number, signal: AbortSignal): Promise<void> {
+	if (signal.aborted) return Promise.reject(signal.reason);
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal.reason);
+		};
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, milliseconds);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
 export class AgentRegistry {
 	private readonly agents = new Map<string, ManagedAgent>();
 	private readonly controllers = new Map<string, AbortController>();
@@ -96,6 +117,7 @@ export class AgentRegistry {
 		resolve: (agent: ManagedAgent) => void;
 	}> = [];
 	private changeQueue: Promise<void> = Promise.resolve();
+	private readonly shutdownController = new AbortController();
 	private readonly maxAgents: number;
 	private readonly maxActiveTurns: number;
 	private readonly maxHistoryTurns: number;
@@ -108,6 +130,7 @@ export class AgentRegistry {
 	private readonly idleTtlMs: number;
 	private readonly transport: SubagentTransport;
 	private readonly now: () => number;
+	private lastCompletionAt = 0;
 
 	constructor(
 		transport: SubagentTransport | AgentTurnRunner,
@@ -176,6 +199,9 @@ export class AgentRegistry {
 			}
 			const depth = seen.size - 1;
 			if (cyclic || depth > this.maxDepth) continue;
+			for (const completion of record.pendingCompletions ?? []) {
+				this.lastCompletionAt = Math.max(this.lastCompletionAt, completion.createdAt);
+			}
 			this.agents.set(record.id, {
 				...record,
 				state:
@@ -183,6 +209,12 @@ export class AgentRegistry {
 				rootId,
 				depth,
 				currentTask: undefined,
+				turnGeneration: record.turnGeneration ?? 0,
+				currentRunId: undefined,
+				currentTurnGeneration: undefined,
+				pendingCompletions: (record.pendingCompletions ?? []).map((completion) => ({
+					...completion,
+				})),
 				currentTimeoutMs: undefined,
 				currentIdleTimeoutMs: undefined,
 				currentMaxTurns: undefined,
@@ -286,6 +318,8 @@ export class AgentRegistry {
 			maxToolCalls: input.maxToolCalls,
 			currentMaxToolCalls: input.maxToolCalls,
 			currentTask: task,
+			turnGeneration: 0,
+			pendingCompletions: [],
 			history: [],
 			mailbox: [],
 			context: input.context,
@@ -486,19 +520,30 @@ export class AgentRegistry {
 			const index = this.queue.findIndex((entry) => entry.agent.id === id);
 			if (index >= 0) {
 				const [entry] = this.queue.splice(index, 1);
+				const persistedCompletion = {
+					completionId: `completion:${agent.id}:${randomUUID()}`,
+					runId: agent.currentRunId ?? `run:${agent.id}:${randomUUID()}`,
+					generation: agent.currentTurnGeneration ?? agent.turnGeneration ?? 1,
+					task: truncateUtf8(entry.task, 256).text,
+					output: "",
+					error: "Interrupted before execution",
+					createdAt: this.completionCreatedAt(),
+				};
 				agent.state = "interrupted";
+				agent.pendingCompletions = [...(agent.pendingCompletions ?? []), persistedCompletion];
 				clearCurrentTurn(agent);
 				agent.updatedAt = this.now();
+				const persisted = await this.persistTerminalState().then(
+					() => true,
+					() => false,
+				);
 				const completion: AgentTurnCompletion = {
+					...persistedCompletion,
 					agent: this.copy(agent),
-					task: entry.task,
-					output: "",
-					error: "Interrupted before execution",
 				};
 				entry.resolve(agent);
 				this.running.delete(id);
-				await this.notifyTurnComplete(completion);
-				await this.changed();
+				if (persisted) await this.notifyTurnComplete(completion);
 				return this.copy(agent);
 			}
 		}
@@ -584,6 +629,7 @@ export class AgentRegistry {
 	}
 
 	async shutdown(): Promise<void> {
+		this.shutdownController.abort(new Error("Subagent registry is shutting down"));
 		for (const entry of this.queue.splice(0)) {
 			if (entry.agent.capabilityGrant?.state === "active") {
 				entry.agent.capabilityGrant = revokeCapabilityGrant(
@@ -629,7 +675,7 @@ export class AgentRegistry {
 		} catch (error) {
 			shutdownError = error;
 		}
-		await this.changed();
+		await this.changed(true);
 		if (shutdownError) throw shutdownError;
 	}
 
@@ -666,6 +712,8 @@ export class AgentRegistry {
 			maxToolCalls: agent.maxToolCalls,
 			currentMaxToolCalls: agent.currentMaxToolCalls,
 			currentTask: agent.currentTask,
+			currentRunId: agent.currentRunId,
+			currentTurnGeneration: agent.currentTurnGeneration,
 			error: agent.error,
 			workspaceMode: agent.workspaceMode,
 			contextTurns: agent.contextTurns,
@@ -712,14 +760,60 @@ export class AgentRegistry {
 		return agent ? this.copy(agent) : undefined;
 	}
 
-	markCompletionDelivered(id: string, deliveredAt: number): void {
-		const agent = this.agents.get(id);
-		if (!agent?.telemetry) return;
-		agent.telemetry = {
-			...agent.telemetry,
-			updatedAt: deliveredAt,
-			timing: { ...agent.telemetry.timing, completionDeliveredAt: deliveredAt },
-		};
+	listPendingCompletions(): AgentTurnCompletion[] {
+		return [...this.agents.values()]
+			.flatMap((agent) =>
+				(agent.pendingCompletions ?? []).map((completion) => ({
+					...completion,
+					agent: this.copy(agent),
+				})),
+			)
+			.sort(
+				(left, right) =>
+					left.createdAt - right.createdAt ||
+					left.generation - right.generation ||
+					left.completionId.localeCompare(right.completionId),
+			);
+	}
+
+	async markCompletionDelivered(completionId: string, deliveredAt: number): Promise<void> {
+		const agent = [...this.agents.values()].find((candidate) =>
+			candidate.pendingCompletions?.some((completion) => completion.completionId === completionId),
+		);
+		if (!agent) return;
+		const acknowledged = (agent.pendingCompletions ?? []).find(
+			(completion) => completion.completionId === completionId,
+		);
+		if (!acknowledged) return;
+		agent.pendingCompletions = (agent.pendingCompletions ?? []).filter(
+			(completion) => completion.completionId !== completionId,
+		);
+		if (agent.telemetry) {
+			agent.telemetry = {
+				...agent.telemetry,
+				updatedAt: deliveredAt,
+				timing: { ...agent.telemetry.timing, completionDeliveredAt: deliveredAt },
+			};
+		}
+		agent.updatedAt = Math.max(agent.updatedAt, deliveredAt);
+		try {
+			await this.changed(true);
+		} catch (error) {
+			if (
+				!agent.pendingCompletions?.some(
+					(completion) => completion.completionId === acknowledged.completionId,
+				)
+			) {
+				agent.pendingCompletions = [...(agent.pendingCompletions ?? []), acknowledged].sort(
+					(left, right) => left.createdAt - right.createdAt || left.generation - right.generation,
+				);
+			}
+			if (agent.telemetry?.timing.completionDeliveredAt === deliveredAt) {
+				const { completionDeliveredAt: _discarded, ...timing } = agent.telemetry.timing;
+				agent.telemetry = { ...agent.telemetry, timing };
+			}
+			throw error;
+		}
 	}
 
 	async sweepExpired(): Promise<number> {
@@ -740,6 +834,14 @@ export class AgentRegistry {
 		task: string,
 		limits: TurnLimits & { timeoutMs?: number } = {},
 	): void {
+		if ((agent.pendingCompletions?.length ?? 0) >= MAX_PENDING_COMPLETIONS_PER_AGENT) {
+			throw new Error(
+				`Agent ${agent.id} has ${MAX_PENDING_COMPLETIONS_PER_AGENT} undelivered completions; wait for delivery before another turn`,
+			);
+		}
+		agent.turnGeneration = (agent.turnGeneration ?? 0) + 1;
+		agent.currentTurnGeneration = agent.turnGeneration;
+		agent.currentRunId = `run:${agent.id}:${randomUUID()}`;
 		agent.state = "starting";
 		agent.error = undefined;
 		agent.currentTask = task;
@@ -790,17 +892,30 @@ export class AgentRegistry {
 			agent.state = "failed";
 			agent.error = "Capability grant expired or no longer matches the accepted plan";
 			agent.outcome = classifyStructuredOutcome("failed", "capability-grant-invalid");
-			agent.currentTask = undefined;
-			agent.currentTimeoutMs = undefined;
-			agent.updatedAt = this.now();
-			resolveQueued(agent);
-			this.running.delete(agent.id);
-			void this.notifyTurnComplete({
-				agent: this.copy(agent),
-				task,
+			const persistedCompletion = {
+				completionId: `completion:${agent.id}:${randomUUID()}`,
+				runId: agent.currentRunId ?? `run:${agent.id}:${randomUUID()}`,
+				generation: agent.currentTurnGeneration ?? agent.turnGeneration ?? 1,
+				task: truncateUtf8(task, 256).text,
 				output: "",
-				error: agent.error,
-			}).then(() => this.changed());
+				error: truncateUtf8(agent.error, 512).text,
+				createdAt: this.completionCreatedAt(),
+			};
+			agent.pendingCompletions = [...(agent.pendingCompletions ?? []), persistedCompletion];
+			clearCurrentTurn(agent);
+			agent.updatedAt = this.now();
+			void this.persistTerminalState()
+				.then(() =>
+					this.notifyTurnComplete({
+						...persistedCompletion,
+						agent: this.copy(agent),
+					}),
+				)
+				.catch(() => undefined)
+				.finally(() => {
+					resolveQueued(agent);
+					this.running.delete(agent.id);
+				});
 			return;
 		}
 		const controller = new AbortController();
@@ -808,6 +923,8 @@ export class AgentRegistry {
 		agent.state = "running";
 		agent.updatedAt = this.now();
 		const startedAt = this.now();
+		const runId = agent.currentRunId ?? `run:${agent.id}:${randomUUID()}`;
+		const turnGeneration = agent.currentTurnGeneration ?? agent.turnGeneration ?? 1;
 		const completionKey = `completion:${agent.id}:${randomUUID()}`;
 		const acceptedPlanId = agent.executionPlan?.id;
 		let completionContent = "";
@@ -830,6 +947,8 @@ export class AgentRegistry {
 					? truncateUtf8(outcome.error, this.maxTurnOutputBytes).text
 					: undefined;
 				agent.history.push({
+					runId,
+					generation: turnGeneration,
 					task,
 					output,
 					startedAt,
@@ -925,6 +1044,8 @@ export class AgentRegistry {
 					this.maxTurnOutputBytes,
 				).text;
 				agent.history.push({
+					runId,
+					generation: turnGeneration,
 					task,
 					output: "",
 					startedAt,
@@ -947,12 +1068,16 @@ export class AgentRegistry {
 				return agent;
 			})
 			.finally(async () => {
-				const turnCompletion: AgentTurnCompletion = {
-					agent: this.copy(agent),
-					task,
-					output: completionOutput,
-					error: completionError,
+				const persistedCompletion = {
+					completionId: completionKey,
+					runId,
+					generation: turnGeneration,
+					task: truncateUtf8(task, 256).text,
+					output: truncateUtf8(completionOutput, MAX_TOOL_MESSAGE_BYTES).text,
+					error: completionError ? truncateUtf8(completionError, 512).text : undefined,
+					createdAt: this.completionCreatedAt(),
 				};
+				agent.pendingCompletions = [...(agent.pendingCompletions ?? []), persistedCompletion];
 				if (agent.parentId) {
 					const parent = this.agents.get(agent.parentId);
 					if (parent && parent.state !== "closed") {
@@ -961,12 +1086,19 @@ export class AgentRegistry {
 				}
 				clearCurrentTurn(agent);
 				agent.updatedAt = this.now();
+				const persisted = await this.persistTerminalState().then(
+					() => true,
+					() => false,
+				);
 				this.controllers.delete(agent.id);
+				const turnCompletion: AgentTurnCompletion = {
+					...persistedCompletion,
+					agent: this.copy(agent),
+				};
 				this.running.delete(agent.id);
 				resolveQueued(agent);
 				this.pumpQueue();
-				await this.notifyTurnComplete(turnCompletion);
-				await this.changed();
+				if (persisted) await this.notifyTurnComplete(turnCompletion);
 			});
 	}
 
@@ -1032,11 +1164,22 @@ export class AgentRegistry {
 		return [...this.agents.values()].filter((agent) => agent.state !== "closed").length;
 	}
 
+	private completionCreatedAt(): number {
+		this.lastCompletionAt = Math.max(this.now(), this.lastCompletionAt + 1);
+		return this.lastCompletionAt;
+	}
+
 	private evictExpired(): ManagedAgent[] {
 		const cutoff = this.now() - this.idleTtlMs;
 		const protectedIds = new Set<string>();
 		for (const agent of this.agents.values()) {
-			if (agent.state !== "running" && agent.state !== "starting") continue;
+			if (
+				agent.state !== "running" &&
+				agent.state !== "starting" &&
+				(agent.pendingCompletions?.length ?? 0) === 0
+			) {
+				continue;
+			}
 			let current: ManagedAgent | undefined = agent;
 			while (current) {
 				protectedIds.add(current.id);
@@ -1081,6 +1224,25 @@ export class AgentRegistry {
 		for (const agent of closed.slice(this.maxAgents)) this.agents.delete(agent.id);
 	}
 
+	private async persistTerminalState(): Promise<void> {
+		let failures = 0;
+		for (;;) {
+			try {
+				await this.changed(true);
+				return;
+			} catch (error) {
+				if (this.shutdownController.signal.aborted) throw error;
+				failures++;
+				if (failures === 1) continue;
+				const delay = Math.min(
+					INITIAL_PERSISTENCE_RETRY_DELAY_MS * 2 ** (failures - 2),
+					MAX_PERSISTENCE_RETRY_DELAY_MS,
+				);
+				await waitForPersistenceRetry(delay, this.shutdownController.signal);
+			}
+		}
+	}
+
 	private async notifyTurnComplete(completion: AgentTurnCompletion): Promise<void> {
 		try {
 			await this.options.onTurnComplete?.(completion);
@@ -1089,16 +1251,17 @@ export class AgentRegistry {
 		}
 	}
 
-	private changed(): Promise<void> {
+	private changed(propagateError = false): Promise<void> {
 		const snapshot = this.list(true);
 		const next = this.changeQueue.then(async () => {
 			try {
 				await this.options.onChange?.(snapshot);
-			} catch {
-				// Persistence is best-effort; lifecycle operations must remain usable if storage fails.
+			} catch (error) {
+				if (propagateError) throw error;
+				// Non-terminal persistence remains best-effort so lifecycle controls stay usable.
 			}
 		});
-		this.changeQueue = next;
+		this.changeQueue = next.catch(() => undefined);
 		return next;
 	}
 
@@ -1115,6 +1278,8 @@ export class AgentRegistry {
 			updatedAt: agent.updatedAt,
 			historyCount: agent.history.length,
 			unreadMessages,
+			turnGeneration: agent.turnGeneration ?? 0,
+			pendingCompletionCount: agent.pendingCompletions?.length ?? 0,
 		};
 	}
 
@@ -1126,6 +1291,9 @@ export class AgentRegistry {
 			currentMailboxMessageIds: agent.currentMailboxMessageIds
 				? [...agent.currentMailboxMessageIds]
 				: undefined,
+			pendingCompletions: (agent.pendingCompletions ?? []).map((completion) => ({
+				...completion,
+			})),
 			history: agent.history.map((turn) => ({ ...turn })),
 			mailbox: agent.mailbox.map((message) => ({ ...message })),
 			contract: agent.contract ? structuredClone(agent.contract) : undefined,

package/src/stateful-guidance.ts

@@ -31,6 +31,6 @@ export function createSpawnPromptGuidelines(
 		"Add another subagent_spawn only for truly independent work with safe workspace concurrency.",
 		noLocalWorkGuidance,
 		'Consume and synthesize available subagent_spawn completion messages; use subagent_manage with action "interrupt" or "close" for agents that are no longer needed.',
-		'Completion from subagent_spawn is delivered automatically. Do not poll with subagent_manage action "list" or subagent_mailbox action "read", repeatedly check progress, or duplicate the delegated work.',
+		'Completion from subagent_spawn is delivered automatically. Do not poll with subagent_inspect or subagent_mailbox action "read", repeatedly check progress, or duplicate the delegated work.',
 	];
 }

package/src/stateful-render.ts

@@ -75,7 +75,6 @@ function renderStatefulCall(tool: StatefulRenderTool, args: Record<string, unkno
 		const metadata: string[] = [];
 		if (typeof args.agentId === "string") metadata.push(`id:${safeLine(args.agentId, "", 256)}`);
 		if (args.subtree === true) metadata.push("subtree");
-		if (args.includeClosed === true) metadata.push("include closed");
 		return new Text(toolHeader(theme, "subagent_manage", args.action, metadata), 0, 0);
 	}
 	const metadata = [`id:${safeLine(args.agentId, "...", 256)}`];

package/src/stateful-tool-params.ts

@@ -1,25 +1,18 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 
-const MANAGE_ACTIONS = ["list", "interrupt", "close"] as const;
+const MANAGE_ACTIONS = ["interrupt", "close"] as const;
 const MAILBOX_ACTIONS = ["send", "read"] as const;
 const MAX_MAILBOX_MESSAGE_LENGTH = 16 * 1024;
 
 export const ManageParamsSchema = Type.Object(
 	{
 		action: StringEnum(MANAGE_ACTIONS, {
-			description:
-				"Use list to inspect agents, interrupt to stop active work, or close to release agents.",
+			description: "Interrupt active work or close an agent and release its resources.",
 		}),
 		agentId: Type.Optional(
 			Type.String({ minLength: 1, description: "Required for interrupt and close." }),
 		),
-		includeClosed: Type.Optional(
-			Type.Boolean({
-				default: false,
-				description: "List closed records as well as retained agents.",
-			}),
-		),
 		subtree: Type.Optional(
 			Type.Boolean({
 				default: false,
@@ -57,9 +50,11 @@ export const MailboxParamsSchema = Type.Object(
 	{ additionalProperties: false },
 );
 
-export type ValidatedManageParams =
-	| { action: "list"; includeClosed?: boolean }
-	| { action: "interrupt" | "close"; agentId: string; subtree?: boolean };
+export type ValidatedManageParams = {
+	action: "interrupt" | "close";
+	agentId: string;
+	subtree?: boolean;
+};
 
 export type ValidatedMailboxParams =
 	| {
@@ -73,21 +68,19 @@ export type ValidatedMailboxParams =
 
 export function validateManageParams(params: unknown): ValidatedManageParams {
 	const values = parameterRecord(params, "subagent_manage");
-	assertKnownKeys("subagent_manage", values, ["action", "agentId", "includeClosed", "subtree"]);
+	assertKnownKeys("subagent_manage", values, ["action", "agentId", "subtree"]);
 	const action = values.action;
+	if (action === "list") {
+		throw new Error(
+			'subagent_manage no longer supports "list"; use subagent_inspect action "list_runs"',
+		);
+	}
 	if (
 		typeof action !== "string" ||
 		!MANAGE_ACTIONS.includes(action as (typeof MANAGE_ACTIONS)[number])
 	) {
 		throw new Error(`subagent_manage action must be one of: ${MANAGE_ACTIONS.join(", ")}`);
 	}
-	if (action === "list") {
-		assertOptionalBoolean("subagent_manage", action, values, "includeClosed");
-		return {
-			action,
-			...(values.includeClosed === undefined ? {} : { includeClosed: values.includeClosed }),
-		} as ValidatedManageParams;
-	}
 	assertRequiredString("subagent_manage", action, values, "agentId");
 	assertOptionalBoolean("subagent_manage", action, values, "subtree");
 	return {

package/src/stateful.ts

@@ -52,7 +52,7 @@ import {
 	hashSpawnRequest,
 	MAX_SPAWN_IDEMPOTENCY_KEY_LENGTH,
 } from "./spawn-idempotency.js";
-import { formatStatefulAgentLine, summarizeStatefulAgent } from "./stateful-agent-view.js";
+import { summarizeStatefulAgent } from "./stateful-agent-view.js";
 import { resolveCompletionDelivery, resolveStatefulTransportKind } from "./stateful-config.js";
 import { createSpawnPromptGuidelines } from "./stateful-guidance.js";
 import {
@@ -300,10 +300,16 @@ export function registerStatefulSubagents(
 					const reason = error instanceof Error ? error.message : String(error);
 					ctx.ui.notify(`Subagent completion delivery failed: ${reason}`, "warning");
 				},
-				onDelivered: (completions, deliveredAt) => {
+				onAcknowledged: (completions, deliveredAt) => {
 					if (generation !== runtimeGeneration) return;
 					for (const completion of completions) {
-						nextRegistry.markCompletionDelivered(completion.agent.id, deliveredAt);
+						void nextRegistry
+							.markCompletionDelivered(completion.completionId, deliveredAt)
+							.catch((error: unknown) => {
+								if (!ctx.hasUI || generation !== runtimeGeneration) return;
+								const reason = error instanceof Error ? error.message : String(error);
+								ctx.ui.notify(`Subagent completion acknowledgement failed: ${reason}`, "warning");
+							});
 					}
 				},
 			});
@@ -378,6 +384,9 @@ export function registerStatefulSubagents(
 			registry = nextRegistry;
 			persistence = sessionPersistence;
 			completionBroker = sessionBroker;
+			for (const completion of nextRegistry.listPendingCompletions()) {
+				sessionBroker.enqueue(completion);
+			}
 			runtimeLimits = nextLimits;
 			refreshSpawnToolRegistration?.();
 			const sweepEveryMs = Math.max(
@@ -402,6 +411,10 @@ export function registerStatefulSubagents(
 		completionBroker?.onParentTurnStart();
 	});
 
+	pi.on("context", (event) => {
+		completionBroker?.onParentContext(event.messages);
+	});
+
 	pi.on("agent_settled", () => {
 		completionBroker?.onParentSettled();
 	});
@@ -835,8 +848,8 @@ export function registerStatefulSubagents(
 		name: "subagent_manage",
 		label: "Manage Subagents",
 		description:
-			"List retained subagents through the compatibility route, interrupt active work while keeping an agent reusable, or close agents and release their resources. Prefer subagent_inspect when the whole activated capability must be read-only.",
-		promptSnippet: "List or control retained detached subagents",
+			"Interrupt active work while keeping an agent reusable, or close agents and release their resources. Use subagent_inspect for every read-only list, detail, status, and diagnostic operation.",
+		promptSnippet: "Interrupt or close retained detached subagents",
 		parameters: ManageParamsSchema,
 		...createStatefulToolRenderer("manage"),
 		async execute(_id, params, signal): Promise<StatefulActionToolResult> {
@@ -848,20 +861,6 @@ export function registerStatefulSubagents(
 				return value;
 			};
 			const operation = validateManageParams(params);
-			if (operation.action === "list") {
-				const agents = ownedRegistry.list(operation.includeClosed);
-				return {
-					content: [
-						{
-							type: "text",
-							text: agents.length
-								? agents.map(formatStatefulAgentLine).join("\n")
-								: "No stateful subagents.",
-						},
-					],
-					details: { agents: agents.map(summarizeStatefulAgent) },
-				};
-			}
 			const agentId = operation.agentId;
 			if (operation.action === "interrupt") {
 				if (operation.subtree) {