@narumitw/pi-subagents 2.0.5 → 2.1.0

package/src/stateful-limits.ts

@@ -29,36 +29,36 @@ export interface StatefulLimitDefinition {
 export const STATEFUL_LIMIT_DEFINITIONS: readonly StatefulLimitDefinition[] = [
 	{
 		field: "maxAgents",
-		label: "Retained agents",
-		description: "Running, queued, and reusable idle detached agents",
+		label: "Subagents saved for follow-up",
+		description: "Working, queued, and reusable background subagents kept in one session",
 		defaultValue: 16,
 		minimum: 1,
 	},
 	{
 		field: "maxActiveTurns",
-		label: "Active turns",
-		description: "Detached agent turns that may run at the same time",
+		label: "Subagents working at once",
+		description: "Background subagent turns that may run at the same time",
 		defaultValue: 4,
 		minimum: 1,
 	},
 	{
 		field: "maxChildrenPerAgent",
-		label: "Children per agent",
-		description: "Direct child agents retained beneath one parent",
+		label: "Direct children per subagent",
+		description: "Subagents that one parent subagent may keep for follow-up",
 		defaultValue: 8,
 		minimum: 1,
 	},
 	{
 		field: "maxDepth",
-		label: "Agent tree depth",
-		description: "Nested child levels below a root agent",
+		label: "Nested subagent levels",
+		description: "Child levels allowed below a top-level subagent",
 		defaultValue: 3,
 		minimum: 0,
 	},
 	{
 		field: "maxStoredAgents",
-		label: "Stored agents",
-		description: "Detached agent records kept per session on disk",
+		label: "Stored subagent records",
+		description: "Background subagent records kept on disk for each session",
 		defaultValue: 50,
 		minimum: 1,
 	},

package/src/stateful-registration.ts

@@ -17,6 +17,11 @@ import {
 	THINKING_LEVELS,
 } from "./agents/types.js";
 import type { CompletionDeliveryBroker } from "./completion-delivery.js";
+import {
+	CompletionRequirementModeSchema,
+	completionRequirementsFromBranch,
+	reconcileRequiredCompletionContext,
+} from "./completion-requirement.js";
 import type { ContextMode } from "./context.js";
 import type { CreateStatefulTransportOptions } from "./create-stateful-transport.js";
 import { DelegationContractSchema } from "./delegation-contract.js";
@@ -55,7 +60,9 @@ import {
 	validateManageParams,
 } from "./stateful-tool-params.js";
 import { MAX_TASK_NAME_LENGTH } from "./task-path.js";
+import { grammarSafeToolObject } from "./tool-schema-compatibility.js";
 import { MAX_SUBAGENT_TOOL_CALLS, MAX_SUBAGENT_TURNS } from "./turn-budget.js";
+import type { UsageRecordingController } from "./usage-recording.js";
 import type { WorkspaceManager } from "./workspace.js";
 
 type CwdPolicyModule = typeof import("./cwd-policy.js");
@@ -196,6 +203,21 @@ const StatefulTimeoutSchema = Type.Integer({
 	description:
 		"Work deadline in milliseconds selected for the task difficulty. On expiry, Pi aborts the work and makes one separately bounded summary attempt. Retained as the agent default.",
 });
+const DEFAULT_SUBAGENT_AWAIT_TIMEOUT_MS = 30_000;
+const SubagentAwaitParams = Type.Object({
+	agentId: Type.String({
+		minLength: 1,
+		description: "Retained agent ID or canonical task path.",
+	}),
+	timeoutMs: Type.Optional(
+		Type.Integer({
+			minimum: 1,
+			maximum: MAX_SUBAGENT_TIMEOUT_MS,
+			description:
+				"Maximum time to wait in milliseconds. A wait timeout stops only this tool call and does not interrupt or close the subagent. Defaults to 30000.",
+		}),
+	),
+});
 const StatefulTurnLimitFields = {
 	idleTimeoutMs: Type.Optional(
 		Type.Integer({
@@ -209,14 +231,16 @@ const StatefulTurnLimitFields = {
 		Type.Integer({
 			minimum: 1,
 			maximum: MAX_SUBAGENT_TURNS,
-			description: "Maximum unfinished assistant turns; retained as the agent default.",
+			description:
+				"Maximum unfinished assistant turns; retained as the agent default. Omit rather than guessing a tight bound.",
 		}),
 	),
 	maxToolCalls: Type.Optional(
 		Type.Integer({
 			minimum: 1,
 			maximum: MAX_SUBAGENT_TOOL_CALLS,
-			description: "Maximum tool calls; retained as the agent default.",
+			description:
+				"Maximum tool calls; retained as the agent default. Omit rather than guessing a tight bound.",
 		}),
 	),
 };
@@ -227,6 +251,7 @@ export interface StatefulSubagentDependencies {
 	settings?: SubagentRuntimeSettings;
 	getSettings?: () => SubagentSettings | undefined;
 	loadTransport?: CreateStatefulTransportOptions["loadTransport"];
+	usageRecording?: UsageRecordingController;
 }
 
 export interface StatefulSubagentRuntimeStatus {
@@ -362,7 +387,7 @@ export function registerStatefulSubagents(
 		if (!registry) throw new Error("Stateful subagents are not initialized for this session");
 		return registry;
 	};
-	pi.on("session_start", async (_event, ctx) => {
+	pi.on("session_start", async (event, ctx) => {
 		const generation = ++runtimeGeneration;
 		completionBroker?.close();
 		completionBroker = undefined;
@@ -415,9 +440,16 @@ export function registerStatefulSubagents(
 						const reason = error instanceof Error ? error.message : String(error);
 						ctx.ui.notify(`Subagent completion delivery failed: ${reason}`, "warning");
 					},
+					onDeliveryAttempt: (completions, input) => {
+						if (generation !== runtimeGeneration) return;
+						for (const completion of completions) {
+							dependencies.usageRecording?.recordCompletionDeliveryAttempt(completion, input);
+						}
+					},
 					onAcknowledged: (completions, deliveredAt) => {
 						if (generation !== runtimeGeneration) return;
 						for (const completion of completions) {
+							dependencies.usageRecording?.recordCompletionVisible(completion);
 							void nextRegistry
 								.markCompletionDelivered(completion.completionId, deliveredAt)
 								.catch((error: unknown) => {
@@ -479,6 +511,7 @@ export function registerStatefulSubagents(
 					if (generation !== runtimeGeneration) return;
 					await sessionPersistence.save(agents);
 					if (generation !== runtimeGeneration) return;
+					dependencies.usageRecording?.observeAgents(agents);
 					for (const agent of agents) {
 						for (const message of agent.mailbox) {
 							if (seenMessageIds.has(message.id)) continue;
@@ -506,9 +539,9 @@ export function registerStatefulSubagents(
 					}
 				},
 				onTurnComplete: (completion) => {
-					if (generation === runtimeGeneration && completion.recipientId === "root") {
-						sessionBroker.enqueue(completion);
-					}
+					if (generation !== runtimeGeneration) return;
+					dependencies.usageRecording?.recordChildCompletion(completion);
+					if (completion.recipientId === "root") sessionBroker.enqueue(completion);
 				},
 			});
 			const persisted = sessionPersistence.load();
@@ -550,6 +583,26 @@ export function registerStatefulSubagents(
 				for (const message of agent.mailbox) seenMessageIds.add(message.id);
 			}
 			nextRegistry.restore(restored);
+			const branchRequirements = completionRequirementsFromBranch(ctx.sessionManager.getBranch());
+			const branchOwnsRequirementState =
+				branchRequirements.observedState || event.reason === "fork" || event.reason === "new";
+			nextRegistry.reconcileCompletionRequirements(
+				branchRequirements.records,
+				branchOwnsRequirementState,
+			);
+			if (branchOwnsRequirementState) {
+				try {
+					await sessionPersistence.save(nextRegistry.list(true));
+				} catch (error) {
+					if (generation === runtimeGeneration && ctx.hasUI) {
+						const reason = error instanceof Error ? error.message : String(error);
+						ctx.ui.notify(
+							`Subagent requirement reconciliation could not be persisted yet: ${reason}`,
+							"warning",
+						);
+					}
+				}
+			}
 			if (generation !== runtimeGeneration) {
 				sessionBroker.close();
 				await sessionPeerBroker.close();
@@ -589,6 +642,9 @@ export function registerStatefulSubagents(
 
 	pi.on("context", (event) => {
 		completionBroker?.onParentContext(event.messages);
+		const agents = registry?.list() ?? [];
+		const messages = reconcileRequiredCompletionContext(event.messages, agents);
+		if (messages !== event.messages) return { messages };
 	});
 
 	pi.on("agent_settled", () => {
@@ -639,7 +695,7 @@ export function registerStatefulSubagents(
 		description: appendAgentCatalog(baseSpawnDescription(), agentCatalog),
 		promptSnippet: "Start a reusable detached subagent; completion is delivered asynchronously",
 		promptGuidelines: createSpawnPromptGuidelines(completionDelivery, blockingEnabled),
-		parameters: Type.Object({
+		parameters: grammarSafeToolObject({
 			agent: Type.String({ minLength: 1 }),
 			taskName: Type.Optional(
 				Type.String({
@@ -689,6 +745,7 @@ export function registerStatefulSubagents(
 						"Use text (default), structured-v1, or the evidence-preserving structured-v2 completion contract.",
 				}),
 			),
+			completionRequirement: Type.Optional(CompletionRequirementModeSchema),
 		}),
 		...createStatefulToolRenderer("spawn"),
 		async execute(_id, params, signal, _update, ctx) {
@@ -780,6 +837,7 @@ export function registerStatefulSubagents(
 				allowConcurrentWrites: params.allowConcurrentWrites ?? false,
 				contract,
 				resultFormat,
+				completionRequirement: params.completionRequirement ?? "background",
 			});
 			if (!capturedRegistry) {
 				throw new Error("Stateful subagents are not initialized for this session");
@@ -873,6 +931,7 @@ export function registerStatefulSubagents(
 						spawnRequestHash: params.idempotencyKey ? requestHash : undefined,
 						contract,
 						resultFormat: resultFormat === "text" ? undefined : resultFormat,
+						completionRequirement: params.completionRequirement ?? "background",
 						executionPlan,
 						capabilityGrant,
 						semanticSnapshot,
@@ -892,11 +951,15 @@ export function registerStatefulSubagents(
 				resolvePending?.(agent);
 				const deliveryNote =
 					completionDelivery === "auto-resume"
-						? "Auto-resume will request synthesis after completion."
+						? "Auto-resume steers completions into active parent work or requests synthesis when idle. Treat this response as progress, not final synthesis, until every final-answer-required completion message is visible. If local work is exhausted while required children remain active, emit at most one brief progress sentence and end the turn; do not repeat waiting updates or use the requested final format, verdict, or conclusion. Do not redo a running child's assigned work."
 						: "The current response must not depend on the result because next-turn delivery will not wake an idle root.";
+				const requirementNote =
+					params.completionRequirement === "required"
+						? "This exact run is runtime-tracked as required until its completion becomes visible or reaches an explicit terminal state. Current Pi versions still cannot prevent already-streamed premature output."
+						: "This run is background work and does not block the parent final answer.";
 				return result(
 					agent,
-					`Spawned ${agent.agent} as ${agent.taskPath ?? agent.id} (${agent.id}). Continue the identified non-overlapping local work immediately; do not merely announce the spawn or end while useful local work remains. Only an explicit user-requested specialist model, tool-profile, or isolation exception may lack concurrent local work. ${deliveryNote} Do not poll for progress.`,
+					`Spawned ${agent.agent} as ${agent.taskPath ?? agent.id} (${agent.id}). ${requirementNote} Continue the identified non-overlapping local work immediately; do not merely announce the spawn or end while useful local work remains. Only an explicit user-requested specialist model, tool-profile, or isolation exception may lack concurrent local work. ${deliveryNote} Do not poll for progress.`,
 				);
 			} catch (error) {
 				rejectPending?.(error);
@@ -937,6 +1000,7 @@ export function registerStatefulSubagents(
 				}),
 			),
 			...StatefulTurnLimitFields,
+			completionRequirement: Type.Optional(CompletionRequirementModeSchema),
 			revalidate: Type.Optional(
 				Type.Boolean({
 					description:
@@ -1055,12 +1119,37 @@ export function registerStatefulSubagents(
 				idleTimeoutMs: params.idleTimeoutMs,
 				maxTurns: params.maxTurns,
 				maxToolCalls: params.maxToolCalls,
+				completionRequirement: params.completionRequirement ?? "background",
 			});
 			assertCurrentSpawn(signal, generation, runtimeGeneration);
 			return result(agent, `Started follow-up for ${agent.id}.`);
 		},
 	});
 
+	if (blockingEnabled) {
+		pi.registerTool({
+			name: "subagent_await",
+			label: "Await Subagent",
+			description:
+				"Wait for one retained subagent's current turn to settle and return its latest bounded output. This blocks Pi from processing queued steering until the wait finishes. A wait timeout or caller cancellation stops only the wait and never interrupts or closes the subagent; use subagent_manage for lifecycle changes. Automatic completion delivery remains active and may later repeat the same at-least-once completion.",
+			promptSnippet:
+				"Intentionally block until one retained subagent settles or the wait times out",
+			promptGuidelines: [
+				"Use subagent_await only when the retained result is required before the next action, useful overlapping main-agent work is complete, and blocking Pi is intentional.",
+				"Do not repeatedly call subagent_await after a timeout; the subagent keeps running and completion delivery remains active. Use subagent_manage only when the user wants to interrupt or close it.",
+			],
+			parameters: SubagentAwaitParams,
+			...createStatefulToolRenderer("await"),
+			async execute(_id, params, signal): Promise<StatefulActionToolResult> {
+				const generation = runtimeGeneration;
+				const timeoutMs = params.timeoutMs ?? DEFAULT_SUBAGENT_AWAIT_TIMEOUT_MS;
+				const waited = await requireRegistry().wait(params.agentId, timeoutMs, signal);
+				assertCurrentSpawn(signal, generation, runtimeGeneration);
+				return awaitResult(waited.agent, waited.timedOut, timeoutMs);
+			},
+		});
+	}
+
 	pi.registerTool({
 		name: "subagent_manage",
 		label: "Manage Subagents",
@@ -1225,6 +1314,34 @@ function result(agent: ManagedAgent, text: string) {
 	};
 }
 
+function awaitResult(agent: ManagedAgent, timedOut: boolean, timeoutMs: number) {
+	const latestTurn = agent.history.at(-1);
+	const output = timedOut
+		? ""
+		: truncateUtf8(latestTurn?.output ?? "", DEFAULT_MAX_CONTEXT_BYTES).text;
+	const error = timedOut ? "" : truncateUtf8(agent.error ?? "", MAX_TOOL_MESSAGE_BYTES).text;
+	const text = timedOut
+		? `Stopped waiting for ${agent.taskPath ?? agent.id} after ${timeoutMs}ms; it remains ${agent.state}. The wait did not interrupt or close the subagent.`
+		: [`Subagent ${agent.taskPath ?? agent.id} settled as ${agent.state}.`, output || error]
+				.filter(Boolean)
+				.join("\n\n");
+	return {
+		content: [
+			{
+				type: "text" as const,
+				text: truncateUtf8(text, DEFAULT_MAX_CONTEXT_BYTES).text,
+			},
+		],
+		details: {
+			agent: summarizeStatefulAgent(agent),
+			timedOut,
+			timeoutMs,
+			...(output ? { output } : {}),
+			...(error ? { error } : {}),
+		},
+	};
+}
+
 function normalizeRuntimeThinkingLevel(value: string): ParentRuntimeSnapshot["thinkingLevel"] {
 	return isThinkingLevel(value) ? value : "off";
 }

package/src/stateful-render.ts

@@ -17,7 +17,7 @@ import {
 	toolHeader,
 } from "./render-common.js";
 
-export type StatefulRenderTool = "spawn" | "send" | "manage" | "mailbox";
+export type StatefulRenderTool = "spawn" | "send" | "await" | "manage" | "mailbox";
 
 export function createStatefulToolRenderer(tool: StatefulRenderTool) {
 	return {
@@ -71,6 +71,11 @@ function renderStatefulCall(tool: StatefulRenderTool, args: Record<string, unkno
 			0,
 		);
 	}
+	if (tool === "await") {
+		const metadata = ["blocking"];
+		if (typeof args.timeoutMs === "number") metadata.push(`timeout:${args.timeoutMs}ms`);
+		return new Text(toolHeader(theme, "subagent_await", args.agentId, metadata), 0, 0);
+	}
 	if (tool === "manage") {
 		const metadata: string[] = [];
 		if (typeof args.agentId === "string") metadata.push(`id:${safeLine(args.agentId, "", 256)}`);
@@ -98,9 +103,12 @@ function renderStatefulResult(
 	const details = recordValue(result.details);
 	const args = recordValue(context.args) ?? {};
 	if (!details) return renderFallbackResult(result, options, theme, context.isError);
-	if (tool === "spawn" || tool === "send") {
+	if (tool === "spawn" || tool === "send" || tool === "await") {
 		const agent = recordValue(details.agent);
 		if (!agent) return renderFallbackResult(result, options, theme, context.isError);
+		if (tool === "await" && details.timedOut === true) {
+			return new Text(renderAwaitTimeout(agent, result, options.expanded, theme), 0, 0);
+		}
 		return new Text(renderAgentResult(agent, result, options.expanded, theme), 0, 0);
 	}
 	if (tool === "manage") {
@@ -173,6 +181,22 @@ function renderAgentResult(
 	return lines.join("\n");
 }
 
+function renderAwaitTimeout(
+	agent: Record<string, unknown>,
+	result: AgentToolResult<unknown>,
+	expanded: boolean,
+	theme: Theme,
+): string {
+	const lines = [
+		`${statusBadge(theme, "running")} · ${theme.fg("accent", safeLine(agent.id, "agent", 256))} · ${theme.fg("warning", "wait timed out")} · ${theme.fg("muted", safeLine(agent.state, "unknown", 128))}`,
+	];
+	if (expanded) {
+		const content = safeBlock(textResult(result), "", 8 * 1024).trim();
+		if (content) lines.push(theme.fg("toolOutput", content));
+	} else lines.push(expansionHint());
+	return lines.join("\n");
+}
+
 function renderManageResult(
 	args: Record<string, unknown>,
 	details: Record<string, unknown>,
@@ -276,6 +300,7 @@ function lifecycleStatus(state: string): RenderStatus {
 			return "running";
 		case "idle":
 			return "idle";
+		case "partial":
 		case "blocked":
 		case "needs-input":
 		case "abstained":

package/src/subagent-details.ts

@@ -0,0 +1,43 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { SchedulingDecision } from "./adaptive-scheduler.js";
+import type { AgentScope } from "./agents/types.js";
+import type { OrchestrationMetrics } from "./orchestration-metrics.js";
+import type { PanelSynthesis } from "./panel-contract.js";
+import type { PanelEvidenceArtifact } from "./panel-evidence.js";
+import type { PanelFailure } from "./panel-failure.js";
+import type { PanelPhaseBudgets, PanelPreset } from "./panel-planning.js";
+import type { SingleResult } from "./runner-types.js";
+import type { WorkItemLedgerSnapshot } from "./work-item-ledger.js";
+
+export interface PanelDetails {
+	id: string;
+	preset: PanelPreset;
+	sharedTaskPreview: string;
+	state: "running" | "completed" | "degraded" | "insufficient-panel" | "failed" | "cancelled";
+	reviewerIds: string[];
+	validReviewCount: number;
+	failedReviewCount: number;
+	blockingObjectionCount: number;
+	dissentCount: number;
+	budgets: PanelPhaseBudgets;
+	evidence: PanelEvidenceArtifact[];
+	failures: PanelFailure[];
+	synthesis?: PanelSynthesis;
+	synthesizerResult?: SingleResult;
+	cleanupComplete: boolean;
+}
+
+export interface SubagentDetails {
+	mode: "single" | "parallel" | "chain" | "workflow" | "panel";
+	agentScope: AgentScope;
+	projectAgentsDir: string | null;
+	results: SingleResult[];
+	aggregator?: SingleResult;
+	workflow?: WorkItemLedgerSnapshot;
+	schedulerDecisions?: SchedulingDecision[];
+	metrics?: OrchestrationMetrics;
+	panel?: PanelDetails;
+	isError?: boolean;
+}
+
+export type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;

package/src/subagents-extension.ts

@@ -39,7 +39,6 @@ import {
 import { MAX_BLOCKING_PARALLEL_CONCURRENCY } from "./limits.js";
 import { SubagentParams } from "./params.js";
 import { renderSubagentCall, renderSubagentResult } from "./render.js";
-import type { SubagentDetails } from "./runner.js";
 import {
 	consumeSubagentSettingsNotice,
 	DEFAULT_CONSULT_RESOURCE_POLICY,
@@ -50,7 +49,14 @@ import {
 	resolveBlockingMaxParallelTasks,
 } from "./settings-reader.js";
 import { registerStatefulSubagents } from "./stateful-registration.js";
+import type { SubagentDetails } from "./subagent-details.js";
 import type { SubagentTransport } from "./transport.js";
+import {
+	registerUsageRecording,
+	type UsageRecordingDependencies,
+	type UsageSurfaceArm,
+} from "./usage-recording.js";
+import { resolveUsageRecordingEnabled } from "./usage-recording-config.js";
 
 type BlockingExecutionModule = Pick<typeof import("./execution.js"), "executeSubagent">;
 
@@ -60,6 +66,7 @@ export interface SubagentsDependencies {
 	config?: ConfigRegistrationDependencies;
 	consult?: ConsultRegistrationDependencies;
 	inspect?: InspectRegistrationDependencies;
+	usageRecording?: Partial<UsageRecordingDependencies>;
 }
 
 export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies = {}) {
@@ -68,6 +75,7 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 		dependencies.loadBlockingExecution ?? (() => import("./execution.js")),
 	);
 	const configOwner = registerSubagentConfigLifecycle(pi);
+	const usageRecording = registerUsageRecording(pi, dependencies.usageRecording);
 	const settings = readSubagentSettings();
 	let currentSettings: SubagentSettings | undefined = settings;
 	let currentCatalog = "";
@@ -78,7 +86,7 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 	let refreshStatefulCatalog: (catalog: string) => void = () => undefined;
 	let refreshConsultCatalog: (catalog: string) => void = () => undefined;
 
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", async (event, ctx) => {
 		// Preserve a one-shot migration notice from extension load while refreshing
 		// validation against settings that may have changed before this session.
 		const loadNotice = consumeSubagentSettingsNotice();
@@ -96,6 +104,14 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 		refreshBlockingCatalog(currentCatalog);
 		refreshStatefulCatalog(currentCatalog);
 		refreshConsultCatalog(currentCatalog);
+		await usageRecording.startSession({
+			enabled: resolveUsageRecordingEnabled(currentSettings?.usageRecording),
+			surfaceArm: usageSurfaceArm(blockingEnabled, statefulRuntime.getRuntimeStatus().enabled),
+			reason: event.reason,
+			onWarning: (message) => {
+				if (ctx.hasUI) ctx.ui.notify(message, "warning");
+			},
+		});
 	});
 
 	const statefulRuntime = registerStatefulSubagents(pi, {
@@ -103,6 +119,7 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 		settings: settings?.stateful,
 		getSettings: () => currentSettings,
 		loadTransport: dependencies.loadStatefulTransport,
+		usageRecording,
 	});
 	refreshStatefulCatalog = statefulRuntime.setAgentCatalog;
 	const getBlockingEnabled = () => blockingEnabled;
@@ -122,6 +139,7 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 			getConsultResourcePolicy,
 			getConsultationCwdPolicy,
 			getDelegationCwdPolicy,
+			getUsageRecordingStatus: () => usageRecording.getStatus(),
 		},
 		dependencies.inspect,
 	);
@@ -141,6 +159,15 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 			getConsultResourcePolicy,
 			getConsultationCwdPolicy,
 			getDelegationCwdPolicy,
+			getUsageRecordingEnabled: () => usageRecording.getStatus().enabled,
+			getUsageRecordingStatus: () => usageRecording.getStatus(),
+			setUsageRecordingEnabled: async (value: boolean) => {
+				await usageRecording.setEnabled(value);
+				currentSettings = {
+					...(currentSettings ?? {}),
+					usageRecording: { ...(currentSettings?.usageRecording ?? {}), enabled: value },
+				};
+			},
 			setMaxParallelTasks(value: number) {
 				const previousSettings = currentSettings;
 				currentSettings = {
@@ -188,6 +215,14 @@ export default function (pi: ExtensionAPI, dependencies: SubagentsDependencies =
 		configOwner,
 		dependencies.config,
 	);
+	pi.on("session_shutdown", (event) => usageRecording.shutdown(event.reason));
+}
+
+function usageSurfaceArm(blockingEnabled: boolean, statefulEnabled: boolean): UsageSurfaceArm {
+	if (blockingEnabled && statefulEnabled) return "all";
+	if (statefulEnabled) return "async-only";
+	if (blockingEnabled) return "blocking-only";
+	return "disabled";
 }
 
 function registerBlockingSubagent(
@@ -196,6 +231,7 @@ function registerBlockingSubagent(
 	loadExecution: () => Promise<BlockingExecutionModule>,
 ): (catalog: string) => void {
 	let catalog = "";
+	let deprecationWarningShown = false;
 	const activeControllers = new Set<AbortController>();
 	const activeWork = new Set<Promise<unknown>>();
 	const cancelAndWaitForWork = async (reason: string) => {
@@ -204,10 +240,20 @@ function registerBlockingSubagent(
 		}
 		await Promise.allSettled([...activeWork]);
 	};
-	pi.on("session_start", () => cancelAndWaitForWork("Blocking subagent session replaced"));
+	pi.on("session_start", () => {
+		deprecationWarningShown = false;
+		return cancelAndWaitForWork("Blocking subagent session replaced");
+	});
 	pi.on("session_shutdown", () => cancelAndWaitForWork("Blocking subagent session shut down"));
+	const statefulEnabled = () => getSettings()?.stateful?.enabled !== false;
+	const deprecationAlternatives = () =>
+		statefulEnabled()
+			? "Prefer the main agent for tightly coupled work, subagent_spawn for detached work, subagent_await for an intentional retained-agent join, or subagent_consult for bounded synchronous read-only evidence."
+			: "Prefer the main agent for tightly coupled work or subagent_consult for bounded synchronous read-only evidence; enable the background workflow before using detached alternatives.";
 	const baseDescription = () =>
 		[
+			"Deprecated compatibility tool: do not choose subagent for new work.",
+			deprecationAlternatives(),
 			"Run specialized subagents as a blocking operation with isolated contexts.",
 			"The call blocks the main agent until every worker and optional aggregator finishes, so queued steering waits.",
 			"Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder), workflow (named dependency tasks with optional capability routing), or panel (independent reviewers plus evidence-preserving synthesis).",
@@ -218,14 +264,17 @@ function registerBlockingSubagent(
 			`Working-directory target policy: ${getSettings()?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY}. This controls launch targets and protected project resources, not filesystem access or sandboxing.`,
 		].join(" ");
 	const promptGuidelines = () => [
-		"Use subagent only when delegation fits; the main agent should decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
+		statefulEnabled()
+			? "The subagent tool is deprecated for new work; prefer the main agent, subagent_spawn with supported completion delivery, subagent_await for an intentional retained-agent join, or subagent_consult for bounded synchronous read-only evidence."
+			: "The subagent tool is deprecated for new work; prefer the main agent or subagent_consult for bounded synchronous read-only evidence, and enable the background workflow before using detached alternatives.",
+		"Use deprecated subagent only for an existing caller or an explicit user request whose blocking chain, fan-in, panel, or workflow semantics do not yet have a detached replacement.",
+		"When compatibility requires subagent, decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
 		"The main agent retains overall planning, immediate critical-path work, integration, final verification, and the final answer.",
 		"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work the main agent can perform directly.",
 		"One ordinary implementation worker should not replace work the main agent can perform directly; use a blocking single only when intentional synchronous isolation or a user-requested specialist justifies waiting.",
 		"Keep ordinary planning in the main agent, or use explicit workflow mode when a genuine dependency graph requires caller-authored orchestration.",
 		"Keep ordinary review in the main agent with a review skill and deterministic checks; reserve panel mode or custom verifier agents for consequential independent verification.",
-		"Use the blocking subagent tool only when delegated outputs are required before the main agent's next action and waiting is intentional; the main agent cannot process queued steering until the call returns.",
-		"Use a blocking subagent single, parallel, chain, workflow, panel, or fan-in call only when synchronous context or output isolation is worth making the main agent unavailable while it runs.",
+		"A compatibility subagent call blocks the main agent from processing queued steering until it returns; use it only when the explicit legacy workflow justifies making Pi unavailable.",
 		`If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the configured max ${resolveBlockingMaxParallelTasks(getSettings())}, and avoid write-heavy implementation touching the same files or shared state.`,
 		"For parallel subagent calls, omit the aggregator key entirely unless a fan-in step is required; do not send null, empty strings, or an empty object for unused optional fields.",
 		"Use workflow mode for explicit dependencies or capability routing; declare read/write or ownership scopes, require structured-v2 artifacts when downstream tasks consume them, and use retry or hedging only with the required side-effect contract.",
@@ -236,10 +285,10 @@ function registerBlockingSubagent(
 	];
 	const definition: ToolDefinition<typeof SubagentParams, SubagentDetails> = {
 		name: "subagent",
-		label: "Blocking Subagent",
+		label: "Blocking Subagent · Deprecated",
 		description: appendAgentCatalog(baseDescription(), catalog),
 		promptSnippet:
-			"Run blocking isolated subagents only when their outputs are required before the main agent can continue.",
+			"Deprecated blocking subagent compatibility tool; prefer detached or read-only alternatives.",
 		promptGuidelines: promptGuidelines(),
 		parameters: SubagentParams,
 
@@ -251,6 +300,15 @@ function registerBlockingSubagent(
 				: lifecycleController.signal;
 			const work = (async () => {
 				throwIfAborted(effectiveSignal, "Blocking subagent execution was cancelled");
+				if (!deprecationWarningShown && ctx.hasUI) {
+					deprecationWarningShown = true;
+					ctx.ui.notify(
+						statefulEnabled()
+							? "subagent is deprecated for new work. Prefer the main agent, subagent_spawn with completion delivery, subagent_await for an intentional join, or subagent_consult for synchronous read-only evidence."
+							: "subagent is deprecated for new work. Prefer the main agent or subagent_consult; enable the background workflow before using detached alternatives.",
+						"warning",
+					);
+				}
 				let executionModule: BlockingExecutionModule;
 				try {
 					executionModule = await loadExecution();

package/src/subagents.ts

@@ -11,6 +11,7 @@ export {
 	inspectDelegationWorkflowSettings,
 	inspectStatefulLimitSettings,
 	inspectSubagentSettings,
+	inspectUsageRecordingSettings,
 	normalizeAgentSettings,
 	normalizeSubagentSettings,
 	readSubagentSettings,
@@ -27,6 +28,7 @@ export {
 	updateCwdPolicySetting,
 	updateDelegationWorkflowSetting,
 	updateStatefulLimitSetting,
+	updateUsageRecordingSetting,
 } from "./settings.js";
 export { default, type SubagentsDependencies } from "./subagents-extension.js";
 export { formatTokens, formatUsageStats } from "./usage-format.js";

package/src/subprocess-transport.ts

@@ -8,9 +8,10 @@ import {
 } from "./peer-transport.js";
 import { resolvePiPromptResources } from "./prompt-resources.js";
 import type { ManagedAgent, TurnOutcome } from "./registry.js";
-import { getResultFinalOutput, runSingleAgent, type SubagentDetails } from "./runner.js";
+import { getResultFinalOutput, runSingleAgent } from "./runner.js";
 import { readSubagentSettings, resolveSubagentThinkingLevel } from "./settings.js";
 import { buildStatefulTurnPrompt, resolveStatefulTurnTimeout } from "./stateful-prompt.js";
+import type { SubagentDetails } from "./subagent-details.js";
 import type { SubagentTransport } from "./transport.js";
 import type { TransportProgressCallback, TransportTelemetry } from "./transport-types.js";
 

package/src/supervision.ts

@@ -1,4 +1,5 @@
-import { isResultError, type SingleResult } from "./runner.js";
+import { isResultError } from "./runner-outcome.js";
+import type { SingleResult } from "./runner-types.js";
 
 const HEDGE_LOSER_GRACE_MS = 5_000;