pi-subagents 0.34.0 → 0.35.0

package/src/extension/chain-validation.ts

@@ -0,0 +1,165 @@
+/**
+ * Friendly chain parameter validation.
+ *
+ * The runtime (pi-ai) validates tool arguments against the TypeBox schema before
+ * the tool's `execute` runs. When a chain step has an extra property, the model
+ * receives a raw TypeBox message such as `chain.1: must not have additional
+ * properties` — which does not name the offending property, list the allowed
+ * ones, or show the expected shape. Agents then iteratively guess the format and
+ * waste several turns before getting it right.
+ *
+ * `validateChainInput` runs from the tool's `prepareArguments` shim (and the RPC
+ * bridge) *before* schema validation. It throws a rich, actionable error for the
+ * common chain-shape failures, so the model sees which property is disallowed,
+ * what is allowed, and a valid example — instead of a raw TypeBox diagnostic.
+ *
+ * Allowed property names and additional-property strictness are derived directly
+ * from the schema objects in `schemas.ts` so this stays aligned with TypeBox.
+ */
+
+import {
+	ChainItem,
+	ParallelTaskSchema,
+	DynamicParallelTemplateSchema,
+	DynamicExpandSchema,
+	DynamicCollectSchema,
+} from "./schemas.ts";
+
+type ObjectSchema = {
+	properties?: Record<string, unknown>;
+	additionalProperties?: unknown;
+};
+
+function allowedKeysOf(schema: ObjectSchema | undefined): string[] {
+	return schema?.properties ? Object.keys(schema.properties) : [];
+}
+
+const ExpandFromSchema = (DynamicExpandSchema.properties?.from ?? {}) as ObjectSchema;
+
+export const CHAIN_STEP_KEYS = allowedKeysOf(ChainItem);
+export const PARALLEL_TASK_KEYS = allowedKeysOf(ParallelTaskSchema);
+export const DYNAMIC_TEMPLATE_KEYS = allowedKeysOf(DynamicParallelTemplateSchema);
+export const EXPAND_KEYS = allowedKeysOf(DynamicExpandSchema);
+export const EXPAND_FROM_KEYS = allowedKeysOf(ExpandFromSchema);
+export const COLLECT_KEYS = allowedKeysOf(DynamicCollectSchema);
+
+const CHAIN_STEP_EXAMPLE = '{"agent": "worker", "task": "do X"}';
+const PARALLEL_TASK_EXAMPLE = '{"agent": "worker", "task": "do X"}';
+const DYNAMIC_TEMPLATE_EXAMPLE = '{"agent": "worker", "task": "Review {item.path}"}';
+const EXPAND_EXAMPLE = '{"from": {"output": "targets", "path": "/items"}, "maxItems": 4}';
+const EXPAND_FROM_EXAMPLE = '{"output": "targets", "path": "/items"}';
+const COLLECT_EXAMPLE = '{"as": "reviews"}';
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function disallowedKeys(value: Record<string, unknown>, allowed: readonly string[]): string[] {
+	return Object.keys(value).filter((key) => !allowed.includes(key));
+}
+
+function typeName(value: unknown): string {
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+
+function quoteList(keys: string[]): string {
+	return keys.map((key) => `"${key}"`).join(", ");
+}
+
+function disallowedMessage(
+	path: string,
+	keys: string[],
+	allowed: readonly string[],
+	example?: string,
+): string {
+	const subject = keys.length === 1
+		? `property "${keys[0]}" is not allowed`
+		: `properties ${quoteList(keys)} are not allowed`;
+	const examplePart = example ? `\n\nExample: ${example}` : "";
+	return `subagent ${path}: ${subject}.\nAllowed properties: ${allowed.join(", ")}.${examplePart}`;
+}
+
+function expectObject(value: unknown, path: string, allowed: readonly string[], example?: string): asserts value is Record<string, unknown> {
+	if (!isPlainObject(value)) {
+		const examplePart = example ? `\n\nExample: ${example}` : "";
+		throw new Error(
+			`subagent ${path}: expected an object, received ${typeName(value)}.\nAllowed properties: ${allowed.join(", ")}.${examplePart}`,
+		);
+	}
+}
+
+function checkNoExtraKeys(
+	value: Record<string, unknown>,
+	path: string,
+	schema: ObjectSchema,
+	allowed: readonly string[],
+	example?: string,
+): void {
+	if (schema.additionalProperties !== false) return;
+	const extra = disallowedKeys(value, allowed);
+	if (extra.length > 0) {
+		throw new Error(disallowedMessage(path, extra, allowed, example));
+	}
+}
+
+/**
+ * Validates the `chain` array on a raw subagent tool-call argument object and
+ * throws a friendly, actionable error when a chain step (or a nested
+ * `parallel`/`expand`/`collect` object) has a disallowed property or wrong shape.
+ *
+ * No-op when `chain` is absent or not an array, so management/control/single/
+ * parallel calls are unaffected.
+ */
+export function validateChainInput(args: unknown): void {
+	if (!isPlainObject(args)) return;
+	const chain = (args as Record<string, unknown>).chain;
+	if (!Array.isArray(chain)) return;
+
+	chain.forEach((step, index) => {
+		const stepPath = `chain step validation failed at chain[${index}]`;
+		expectObject(step, stepPath, CHAIN_STEP_KEYS, CHAIN_STEP_EXAMPLE);
+		checkNoExtraKeys(step, stepPath, ChainItem, CHAIN_STEP_KEYS, CHAIN_STEP_EXAMPLE);
+
+		if (step.expand !== undefined) {
+			const expandPath = `${stepPath}.expand`;
+			expectObject(step.expand, expandPath, EXPAND_KEYS, EXPAND_EXAMPLE);
+			checkNoExtraKeys(step.expand, expandPath, DynamicExpandSchema, EXPAND_KEYS, EXPAND_EXAMPLE);
+
+			const from = (step.expand as Record<string, unknown>).from;
+			if (from !== undefined) {
+				const fromPath = `${expandPath}.from`;
+				expectObject(from, fromPath, EXPAND_FROM_KEYS, EXPAND_FROM_EXAMPLE);
+				checkNoExtraKeys(from, fromPath, ExpandFromSchema, EXPAND_FROM_KEYS, EXPAND_FROM_EXAMPLE);
+			}
+		}
+
+		if (step.collect !== undefined) {
+			const collectPath = `${stepPath}.collect`;
+			expectObject(step.collect, collectPath, COLLECT_KEYS, COLLECT_EXAMPLE);
+			checkNoExtraKeys(step.collect, collectPath, DynamicCollectSchema, COLLECT_KEYS, COLLECT_EXAMPLE);
+		}
+
+		const parallel = step.parallel;
+		if (parallel === undefined) return;
+
+		if (Array.isArray(parallel)) {
+			parallel.forEach((task, pIndex) => {
+				const taskPath = `${stepPath}.parallel[${pIndex}]`;
+				expectObject(task, taskPath, PARALLEL_TASK_KEYS, PARALLEL_TASK_EXAMPLE);
+				checkNoExtraKeys(task, taskPath, ParallelTaskSchema, PARALLEL_TASK_KEYS, PARALLEL_TASK_EXAMPLE);
+			});
+			return;
+		}
+
+		if (isPlainObject(parallel)) {
+			const templatePath = `${stepPath}.parallel (dynamic fanout template)`;
+			checkNoExtraKeys(parallel, templatePath, DynamicParallelTemplateSchema, DYNAMIC_TEMPLATE_KEYS, DYNAMIC_TEMPLATE_EXAMPLE);
+			return;
+		}
+
+		throw new Error(
+			`subagent ${stepPath}.parallel: expected an array of task objects or a dynamic fanout template object, received ${typeName(parallel)}.\n\nExample static: [${PARALLEL_TASK_EXAMPLE}]\nExample dynamic: ${DYNAMIC_TEMPLATE_EXAMPLE}`,
+		);
+	});
+}

package/src/extension/doctor.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { discoverAgentsAll, type AgentSource } from "../agents/agents.ts";
 import { isAsyncAvailable } from "../runs/background/async-execution.ts";
+import { formatSpawnBudgetSummary, getSpawnBudgetSnapshot } from "../runs/shared/spawn-budget.ts";
 import { diagnoseIntercomBridge, type IntercomBridgeDiagnostic } from "../intercom/intercom-bridge.ts";
 import { discoverAvailableSkills, type SkillSource } from "../agents/skills.ts";
 import {
@@ -162,6 +163,17 @@ function formatIntercomDiagnostic(diagnostic: IntercomBridgeDiagnostic, context:
 	return lines;
 }
 
+function formatSpawnBudgetSection(input: DoctorReportInput): string[] {
+	const snapshot = getSpawnBudgetSnapshot(input.state, input.config, input.currentSessionId ?? input.state.currentSessionId);
+	return [
+		`- usage: ${formatSpawnBudgetSummary(snapshot)}`,
+		`- recent grants: ${snapshot.grantHistory.length === 0
+			? "none"
+			: snapshot.grantHistory.map((grant) => `+${grant.amount} at ${new Date(grant.grantedAt).toISOString()} (${grant.previousLimit} → ${grant.limit})`).join("; ")}`,
+		"- reset boundary: a new parent session resets usage and grants; compaction does not",
+	];
+}
+
 function formatPermissionSystemSection(): string[] {
 	const lines: string[] = [];
 	const parentSession = process.env["PI_SUBAGENT_PARENT_SESSION"] ?? "";
@@ -199,6 +211,9 @@ export function buildDoctorReport(input: DoctorReportInput): string {
 		"Discovery",
 		...formatDiscovery(input, deps),
 		"",
+		"Spawn budget",
+		...formatSpawnBudgetSection(input),
+		"",
 		"Permission system",
 		...formatPermissionSystemSection(),
 		"",

package/src/extension/fanout-child.ts

@@ -5,6 +5,7 @@ import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-age
 import { discoverAgents } from "../agents/agents.ts";
 import { getArtifactsDir } from "../shared/artifacts.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
+import { resolveWaitToolConfig } from "../runs/background/wait-config.ts";
 import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
 import { readNestedControlRequests, resolveNestedRouteFromEnv, writeNestedControlResult } from "../runs/shared/nested-events.ts";
 import { deliverSubagentIntercomMessageEvent } from "../intercom/result-intercom.ts";
@@ -146,6 +147,7 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 		state,
 		config,
 		asyncByDefault: config.asyncByDefault === true,
+		waitToolEnabled: resolveWaitToolConfig(config.waitTool).enabled,
 		tempArtifactsDir: getArtifactsDir(null),
 		getSubagentSessionRoot,
 		expandTilde,
@@ -159,7 +161,7 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 		description: [
 			"Delegate to subagents from child-safe fanout mode.",
 			"Allowed management/control actions: list, get, status, interrupt, resume, steer, append-step, doctor.",
-			"Agent config mutation actions (create, update, delete, eject, disable, enable, reset) are blocked in this mode.",
+			"Mutating management actions (create, update, delete, eject, disable, enable, reset, grant-spawn-budget) are blocked in this mode.",
 		].join("\n"),
 		parameters: SubagentParams,
 		execute(id, params, signal, onUpdate, ctx) {

package/src/extension/index.ts

@@ -23,21 +23,26 @@ import { discoverAgents } from "../agents/agents.ts";
 import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
 import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import { cleanupOldChainDirs } from "../shared/settings.ts";
-import { clearLegacyResultAnimationTimer, renderWidget, renderSubagentResult } from "../tui/render.ts";
-import { SubagentParams, WaitParams } from "./schemas.ts";
+import { clearLegacyResultAnimationTimer, renderSubagentResult } from "../tui/render.ts";
+import { SubagentParams } from "./schemas.ts";
+import { validateChainInput } from "./chain-validation.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
 import { createResultWatcher } from "../runs/background/result-watcher.ts";
 import { createScheduledRunManager } from "../runs/background/scheduled-runs.ts";
 import { registerSlashCommands } from "../slash/slash-commands.ts";
 import { registerPromptTemplateDelegationBridge } from "../slash/prompt-template-bridge.ts";
+import { registerMainWatchdog } from "../watchdog/register-main.ts";
 import { registerSlashSubagentBridge } from "../slash/slash-bridge.ts";
 import { createNativeSupervisorChannel } from "../intercom/native-supervisor-channel.ts";
 import { registerSubagentRpcBridge } from "./rpc.ts";
 import { clearSlashSnapshots, getSlashRenderableSnapshot, resolveSlashMessageDetails, restoreSlashFinalSnapshots, type SlashMessageDetails } from "../slash/slash-live-state.ts";
 import { inspectSubagentStatus } from "../runs/background/run-status.ts";
-import { resolveWaitToolConfig, waitForSubagents } from "../runs/background/wait.ts";
-import registerSubagentNotify, { type SubagentNotifyDetails } from "../runs/background/notify.ts";
+import { resolveWaitToolConfig } from "../runs/background/subagent-wait.ts";
+import { registerWaitTool } from "../runs/background/wait-tool.ts";
+import { drainOutstandingWork } from "../runs/background/auto-drain.ts";
+import registerSubagentNotify, { parseSubagentNotifyContent, type SubagentNotifyDetails } from "../runs/background/notify.ts";
+import { formatSteeringNotice, handleSubagentSteeringNotice, SUBAGENT_STEERING_MESSAGE_TYPE, type SubagentSteeringMessageDetails } from "./steering-notices.ts";
 import { SUBAGENT_CHILD_ENV, SUBAGENT_PARENT_SESSION_ENV } from "../runs/shared/pi-args.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
 import { loadConfig } from "./config.ts";
@@ -53,7 +58,9 @@ import {
 	SUBAGENT_ASYNC_COMPLETE_EVENT,
 	SUBAGENT_ASYNC_STARTED_EVENT,
 	SUBAGENT_CONTROL_EVENT,
+	SUBAGENT_STEERING_NOTICE_EVENT,
 	WIDGET_KEY,
+	resolveMaxSubagentSpawnsPerSession,
 } from "../shared/types.ts";
 import {
 	clearPendingForegroundControlNotices,
@@ -113,30 +120,6 @@ function isSlashResultRunning(result: { details?: Details }): boolean {
 		|| false;
 }
 
-// Drives the inline running-indicator braille animation for foreground subagent
-// results. Foreground runs receive progress only on child events, so the glyph
-// (derived from progress fields) would freeze between events. While a result is
-// running we tick a frame counter + invalidate() every 80ms so renderSubagentResult
-// can blend the frame into runningGlyph and produce a smooth spinner.
-function subagentResultIsRunning(result: { details?: Details }): boolean {
-	return result.details?.progress?.some((entry) => entry.status === "running")
-		|| result.details?.results.some((entry) => entry.progress?.status === "running")
-		|| false;
-}
-
-function ensureSubagentResultAnimation(context: { state: Record<string, unknown>; invalidate?: () => void }): void {
-	const state = context.state as { subagentResultAnimationTimer?: ReturnType<typeof setInterval>; frame?: number };
-	if (state.subagentResultAnimationTimer) return;
-	if (typeof context.invalidate !== "function") return;
-	if (state.frame === undefined) state.frame = 0;
-	state.subagentResultAnimationTimer = setInterval(() => {
-		state.frame = ((state.frame ?? 0) + 1) % 10;
-		try {
-			context.invalidate();
-		} catch {}
-	}, 80);
-}
-
 function isSlashResultError(result: { details?: Details }): boolean {
 	return result.details?.results.some((entry) => entry.exitCode !== 0 && entry.progress?.status !== "running") || false;
 }
@@ -177,38 +160,6 @@ function createSlashResultComponent(
 	return container;
 }
 
-function parseSubagentNotifyContent(content: string): SubagentNotifyDetails | undefined {
-	const lines = content.split("\n");
-	const header = lines[0] ?? "";
-	const match = header.match(/^Background task (completed|failed|paused): \*\*(.+?)\*\*(?:\s+(\([^)]*\)))?$/);
-	if (!match) return undefined;
-	const body = lines.slice(2);
-	let sessionIndex = -1;
-	for (let i = body.length - 1; i >= 1; i--) {
-		if (body[i - 1]?.trim() === "" && /^(Session|Session file|Session share error):\s+/.test(body[i]!)) {
-			sessionIndex = i;
-			break;
-		}
-	}
-	const sessionLine = sessionIndex >= 0 ? body[sessionIndex] : undefined;
-	const resultLines = sessionIndex >= 0 ? body.slice(0, sessionIndex) : body;
-	const resultPreview = resultLines.join("\n").trim() || "(no output)";
-	let sessionLabel: string | undefined;
-	let sessionValue: string | undefined;
-	if (sessionLine) {
-		const separator = sessionLine.indexOf(":");
-		sessionLabel = sessionLine.slice(0, separator).toLowerCase();
-		sessionValue = sessionLine.slice(separator + 1).trim();
-	}
-	return {
-		agent: match[2]!,
-		status: match[1] as SubagentNotifyDetails["status"],
-		...(match[3] ? { taskInfo: match[3] } : {}),
-		resultPreview,
-		...(sessionLabel && sessionValue ? { sessionLabel, sessionValue } : {}),
-	};
-}
-
 class SubagentControlNoticeComponent implements Component {
 	constructor(
 		private readonly details: SubagentControlMessageDetails,
@@ -266,8 +217,15 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		baseCwd: "",
 		currentSessionId: null,
 		subagentInProgress: false,
-		subagentSpawns: { sessionId: null, count: 0 },
+		subagentSpawns: {
+			sessionId: null,
+			count: 0,
+			configuredLimit: resolveMaxSubagentSpawnsPerSession(config.maxSubagentSpawnsPerSession) ?? null,
+			granted: 0,
+			grantHistory: [],
+		},
 		asyncJobs: new Map(),
+		fleetJobs: new Map(),
 		foregroundRuns: new Map(),
 		foregroundControls: new Map(),
 		lastForegroundControlId: null,
@@ -285,6 +243,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	};
 
 	const supervisorChannel = createNativeSupervisorChannel(pi, state);
+	const mainWatchdog = registerMainWatchdog(pi);
+	let disposeSubagentNotify = () => {};
 	const { startResultWatcher, primeExistingResults, stopResultWatcher } = createResultWatcher(
 		pi,
 		state,
@@ -295,6 +255,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	primeExistingResults();
 
 	const runtimeCleanup = () => {
+		disposeSubagentNotify();
+		mainWatchdog.dispose();
 		stopResultWatcher();
 		scheduledRunManager.stop();
 		supervisorChannel.dispose();
@@ -306,7 +268,9 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	};
 	globalStore[runtimeCleanupStoreKey] = runtimeCleanup;
 
-	const { ensurePoller, handleStarted, handleComplete, resetJobs, restoreActiveJobs } = createAsyncJobTracker(pi, state, ASYNC_DIR);
+	const { ensurePoller, refreshWidget, handleStarted, handleComplete, resetJobs, restoreActiveJobs } = createAsyncJobTracker(pi, state, ASYNC_DIR, {
+		widgetEnabled: config.asyncWidget !== false,
+	});
 	let executorExecute: ((id: string, params: SubagentParamsLike, signal: AbortSignal, onUpdate: ((r: AgentToolResult<Details>) => void) | undefined, ctx: ExtensionContext) => Promise<AgentToolResult<Details>>) | undefined;
 	const scheduledRunManager = createScheduledRunManager({
 		config,
@@ -326,7 +290,9 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		state,
 		config,
 		asyncByDefault,
+		waitToolEnabled: waitToolConfig.enabled,
 		handleScheduledRunAction: (params, ctx) => scheduledRunManager.handleToolCall(params, ctx),
+		watchdog: mainWatchdog,
 		tempArtifactsDir,
 		getSubagentSessionRoot,
 		expandTilde,
@@ -381,6 +347,12 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		return new Text(text, 0, 0);
 	});
 
+	pi.registerMessageRenderer<SubagentSteeringMessageDetails>(SUBAGENT_STEERING_MESSAGE_TYPE, (message, _options, theme) => {
+		const details = message.details as SubagentSteeringMessageDetails | undefined;
+		if (!details) return undefined;
+		return new Text(theme.fg(details.state === "recovered" ? "warning" : "error", formatSteeringNotice(details)), 0, 0);
+	});
+
 	pi.registerMessageRenderer<SubagentControlMessageDetails>(SUBAGENT_CONTROL_MESSAGE_TYPE, (message, _options, theme) => {
 		const details = message.details as SubagentControlMessageDetails | undefined;
 		if (!details?.event) return undefined;
@@ -403,39 +375,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const promptTemplateBridge = registerPromptTemplateDelegationBridge({
 		events: pi.events,
 		getContext: () => state.lastUiContext,
-		execute: async (requestId, request, signal, ctx, onUpdate) => {
-			if (request.tasks && request.tasks.length > 0) {
-				return executeSubagentCollapsed(
-					requestId,
-					{
-						tasks: request.tasks,
-						context: request.context,
-						cwd: request.cwd,
-						worktree: request.worktree,
-						async: false,
-						clarify: false,
-					},
-					signal,
-					onUpdate,
-					ctx,
-				);
-			}
-			return executeSubagentCollapsed(
-				requestId,
-				{
-					agent: request.agent,
-					task: request.task,
-					context: request.context,
-					cwd: request.cwd,
-					model: request.model,
-					async: false,
-					clarify: false,
-				},
-				signal,
-				onUpdate,
-				ctx,
-			);
-		},
+		execute: (requestId, params, signal, ctx, onUpdate) =>
+			executeSubagentCollapsed(requestId, params, signal, onUpdate, ctx),
 	});
 
 	const rpcBridge = registerSubagentRpcBridge({
@@ -458,6 +399,14 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		description: buildSubagentToolDescription(config),
 		parameters: SubagentParams,
 
+		prepareArguments(args) {
+			// Run friendly chain validation before pi-ai's raw TypeBox schema check
+			// so the model sees which property is disallowed, what is allowed, and a
+			// valid example instead of `chain.N: must not have additional properties`.
+			validateChainInput(args);
+			return args as never;
+		},
+
 		execute(id, params, signal, onUpdate, ctx) {
 			return executeSubagentCollapsed(id, params, signal, onUpdate, ctx);
 		},
@@ -493,38 +442,20 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		},
 
 		renderResult(result, options, theme, context) {
-			if (subagentResultIsRunning(result)) {
-				ensureSubagentResultAnimation(context);
-			} else {
-				clearLegacyResultAnimationTimer(context);
-			}
-			const frame = (context.state as { frame?: number } | undefined)?.frame ?? 0;
-			return renderSubagentResult(result, options, theme, frame);
+			clearLegacyResultAnimationTimer(context);
+			return renderSubagentResult(result, options, theme);
 		},
 
 	};
 
 	pi.registerTool(tool);
 
-	const waitTool: ToolDefinition<typeof WaitParams, Details> = {
-		name: "wait",
-		label: "Wait",
-		description: `Block until background (async) subagent runs started in this session finish, then return.
-
-Use this after launching async subagents when you have no independent work left and must not end your turn — for example inside a skill that has to run to completion, or any non-interactive run (\`pi -p ...\`) where the whole task is a single turn and ending it would abandon the still-running children.
-
-• { } — return as soon as the FIRST active run finishes (default). Ideal for a rolling fleet: launch N, wait, spawn a replacement for the one that finished, wait again — keeping N in flight.
-• { all: true } — block until EVERY active run in this session is finished.
-• { id: "..." } — wait for one specific run (id or prefix) to finish.
-• { timeoutMs: 600000 } — stop waiting after N ms (the runs keep going regardless; default 30 min)
+	registerWaitTool(pi, state, waitToolConfig.enabled);
 
-wait also returns when a run needs attention (a child that went idle or blocked for a decision), not only on completion — so a stuck child never stalls the loop; the summary names the run(s) to inspect/nudge/resume/interrupt. It wakes the instant a completion or control event arrives (subscribed to Pi's event bus, with a poll fallback that reconciles crashed runners), keeps the turn alive for normal notification delivery, and resolves early if the turn is aborted.${waitToolConfig.enabled ? "" : "\n\nConfigured behavior: wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED and returns immediately without blocking."}`,
-		parameters: WaitParams,
-		execute(_id, params, signal, _onUpdate, _ctx) {
-			return waitForSubagents(params, signal, { state, events: pi.events, enabled: waitToolConfig.enabled });
-		},
-	};
-	pi.registerTool(waitTool);
+	pi.on("agent_end", async (_event, ctx) => {
+		if (ctx.hasUI) return;
+		await drainOutstandingWork({ state, events: pi.events });
+	});
 
 	registerSlashCommands(pi, state);
 
@@ -541,7 +472,7 @@ wait also returns when a run needs attention (a child that went idle or blocked
 			}
 		}
 	}
-	registerSubagentNotify(pi, state, { batchConfig: config.completionBatch });
+	disposeSubagentNotify = registerSubagentNotify(pi, state, { batchConfig: config.completionBatch });
 
 	const existingVisibleControlNotices = globalStore[controlNoticeSeenStoreKey];
 	const visibleControlNotices = existingVisibleControlNotices instanceof Set ? existingVisibleControlNotices as Set<string> : new Set<string>();
@@ -554,10 +485,14 @@ wait also returns when a run needs attention (a child that went idle or blocked
 			details: payload as SubagentControlMessageDetails,
 		});
 	};
+	const steeringNoticeHandler = (payload: unknown) => {
+		handleSubagentSteeringNotice({ pi, state, details: payload as SubagentSteeringMessageDetails });
+	};
 	const eventUnsubscribes = [
 		pi.events.on(SUBAGENT_ASYNC_STARTED_EVENT, handleStarted),
 		pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, handleComplete),
 		pi.events.on(SUBAGENT_CONTROL_EVENT, controlEventHandler),
+		pi.events.on(SUBAGENT_STEERING_NOTICE_EVENT, steeringNoticeHandler),
 		rpcBridge.dispose,
 	];
 	globalStore[eventUnsubscribeStoreKey] = eventUnsubscribes;
@@ -567,8 +502,7 @@ wait also returns when a run needs attention (a child that went idle or blocked
 		if (!ctx.hasUI) return;
 		state.lastUiContext = ctx;
 		if (state.asyncJobs.size > 0) {
-			renderWidget(ctx, Array.from(state.asyncJobs.values()));
-			ctx.ui.requestRender?.();
+			refreshWidget(ctx);
 			ensurePoller();
 		}
 	});
@@ -587,7 +521,13 @@ wait also returns when a run needs attention (a child that went idle or blocked
 	const resetSessionState = (ctx: ExtensionContext) => {
 		state.baseCwd = ctx.cwd;
 		state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
-		state.subagentSpawns = { sessionId: state.currentSessionId, count: 0 };
+		state.subagentSpawns = {
+			sessionId: state.currentSessionId,
+			count: 0,
+			configuredLimit: resolveMaxSubagentSpawnsPerSession(config.maxSubagentSpawnsPerSession) ?? null,
+			granted: 0,
+			grantHistory: [],
+		};
 		// Set PI_SUBAGENT_PARENT_SESSION for permission-system forwarding.
 		// Only set in the root session (the interactive UI session), not in
 		// child subagent processes — children inherit the parent's value
@@ -616,6 +556,7 @@ wait also returns when a run needs attention (a child that went idle or blocked
 	});
 
 	pi.on("session_shutdown", () => {
+		disposeSubagentNotify();
 		delete process.env[SUBAGENT_PARENT_SESSION_ENV];
 		for (const unsubscribe of eventUnsubscribes) {
 			try {

package/src/extension/rpc.ts

@@ -3,12 +3,13 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Compile } from "typebox/compile";
 import { resolveAsyncRunLocation } from "../runs/background/async-resume.ts";
-import { deliverTimeoutRequest } from "../runs/background/control-channel.ts";
+import { deliverStopRequest } from "../runs/background/control-channel.ts";
 import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.ts";
 import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { type Details, ASYNC_DIR, RESULTS_DIR } from "../shared/types.ts";
 import { readStatus } from "../shared/utils.ts";
 import { SubagentParams } from "./schemas.ts";
+import { validateChainInput } from "./chain-validation.ts";
 
 export const SUBAGENT_RPC_PROTOCOL_VERSION = 1;
 export const SUBAGENT_RPC_REQUEST_EVENT = "subagents:rpc:v1:request";
@@ -111,6 +112,13 @@ function assertRecordParams(params: unknown, method: SubagentRpcMethod): Record<
 }
 
 function assertSubagentParams(params: SubagentParamsLike, label: string): void {
+	// Friendly chain validation first: name the disallowed property, list allowed
+	// ones, and show a valid example instead of raw TypeBox diagnostics.
+	try {
+		validateChainInput(params);
+	} catch (error) {
+		throw new SubagentRpcError("invalid_params", `${label}: ${error instanceof Error ? error.message : String(error)}`);
+	}
 	if (subagentParamsValidator.Check(params)) return;
 	const messages = [...subagentParamsValidator.Errors(params)]
 		.slice(0, 4)
@@ -247,7 +255,7 @@ function stopAsyncRun(
 	}
 
 	try {
-		deliverTimeoutRequest({
+		deliverStopRequest({
 			asyncDir: location.asyncDir,
 			pid: status.pid,
 			kill: options.kill,