@ferris1225/pi-subagents 0.27.0 → 0.29.0

package/src/models.ts

@@ -36,6 +36,19 @@ export function availableModelRefs(ctx: ModelContext): string[] {
 	return [currentRef, ...refs.filter((ref) => ref !== currentRef)];
 }
 
+/**
+ * Resolve the model for a `vision: true` dispatch. The configured vision model
+ * wins when it is usable by the current session; otherwise the task falls back
+ * to the main window's current model (the documented behavior when the vision
+ * model is unset). Returns undefined only when neither exists — callers then
+ * keep the agent's own model as the last resort.
+ */
+export function resolveVisionModelRef(ctx: ModelContext, visionModel?: string): string | undefined {
+	const configured = visionModel?.trim();
+	if (configured && availableModelRefs(ctx).includes(configured)) return configured;
+	return ctx.model ? modelRef(ctx.model) : undefined;
+}
+
 /** Replace unavailable persisted overrides with a model usable by the main session. */
 export function repairUnavailableModelOverrides(
 	ctx: ModelContext,

package/src/prompt.ts

@@ -41,9 +41,13 @@ It immediately ends the current main-agent turn so the user can keep working. Wh
 finishes, its result is sent back as a message that automatically resumes the main agent;
 if the main agent is busy, the result waits as a follow-up.
 
-NEVER run sleep, wait, or polling commands (e.g. Start-Sleep, sleep, timeout) to wait for
-a sub-agent — the turn already ended and the main agent is auto-resumed when results arrive.
-Manual waiting blocks the turn, delays result delivery, and wastes the user's time.
+NEVER run sleep, wait, or polling commands (e.g. Start-Sleep, sleep, timeout), and do NOT
+call subagent_wait to hold the turn — dispatching already ended it, and results arrive as
+messages that resume the main agent automatically (even mid-turn). Ending your turn is the
+default and the only correct way to wait; subagent_wait blocks the turn so the user cannot
+give you other work meanwhile. It is non-blocking by default: settled results return
+immediately, active runs return a "still running — end your turn" note. Pass an explicit
+timeoutMs only when you must stay in the turn (e.g. the user asked you to wait).
 
 Available agents:
 ${catalog}
@@ -58,6 +62,10 @@ ${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `
 - Treat delegated agents as leaf workers: do not ask a sub-agent to dispatch another sub-agent; child processes do not have this tool.
 - Trust but verify: a sub-agent's summary describes intent, not outcome. Check the actual changes/results before reporting work done.
 
+Vision tasks:
+- Judge whether a delegated task may require viewing images (frontend screenshots, mockups, design files, visual regression comparisons). If it might, pass \`vision: true\` in the subagent call and give the sub-agent the exact image paths — it reads them with its read tool.
+- \`vision: true\` runs the sub-agent on the vision-capable model configured in /subagents-setup; when none is configured it falls back to the main session's current model. Do not skip the flag because the agent's default model looks fast/cheap — a non-vision model cannot see the images.
+
 Review & verification:
 - Never report an unrun check as passed; report it as unavailable or as a pre-existing failure.
 ${hasReviewer ? "- For non-trivial diffs, run one fresh read-only `reviewer` sub-agent before reporting done. Fix only concrete blockers and re-review at most once.\n- Use multi-model cross-review only when explicitly requested or for genuinely high-risk changes (security, unsafe/FFI, persistence-migration, concurrency). Reviewers are read-only; only the main agent edits.\n" : ""}- Commit or push only when explicitly requested, applicable checks pass, and no accepted blockers remain.`;

package/src/runtime.ts

@@ -0,0 +1,110 @@
+/**
+ * Shared per-session runtime state for pi-subagents.
+ *
+ * The extension registers several tools (subagent, subagent_wait/status/stop) and
+ * a widget that all talk to one set of live structures: the background queue, the
+ * completion batcher, abort controllers per run, and the settled-results store.
+ * `createRuntime` builds those once per extension load and hands the same object
+ * to every registration site, so state stays in one place without globals.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { BackgroundTaskQueue } from "./background.ts";
+import {
+	completionGroupTriggersTurn,
+	createCompletionBatcher,
+	formatCompletionMessage,
+	type CompletionBatcher,
+	type CompletionMessageItem,
+} from "./completion.ts";
+import { loadConfigSync } from "./config.ts";
+import { monitor } from "./monitor.ts";
+import type { SingleResult } from "./spawn.ts";
+
+export interface SubagentRuntime {
+	configPath: string;
+	backgroundQueue: BackgroundTaskQueue;
+	/** False after session_shutdown; guards delivery and queue work. */
+	sessionActive: boolean;
+	/** Deliver a batch of completion messages to the main window, waking it only
+	 * when the batch needs a turn. */
+	sendCompletionGroup: (items: CompletionMessageItem[]) => void;
+	completionBatcher: CompletionBatcher<CompletionMessageItem>;
+	/** Abort controllers per active run, so subagent_stop can cancel a run in-turn. */
+	runControllers: Map<number, AbortController>;
+	/** Final results keyed by run id, so subagent_wait can hand the model the
+	 * actual result in-turn instead of it sleeping/polling for a wake-up message. */
+	settledRuns: Map<number, SingleResult>;
+	settledListeners: Map<number, Set<(result: SingleResult) => void>>;
+	registerRunResult: (runId: number, result: SingleResult) => void;
+	/** Flip sessionActive off and release all session-scoped resources. */
+	shutdown: () => void;
+}
+
+export function createRuntime(pi: ExtensionAPI, configPath: string): SubagentRuntime {
+	// Init-time decisions need the config synchronously; the full (migrating)
+	// async load runs per tool call.
+	const initialConfig = loadConfigSync(configPath);
+	const backgroundQueue = new BackgroundTaskQueue(initialConfig.maxConcurrency);
+
+	const runtime: SubagentRuntime = {
+		configPath,
+		backgroundQueue,
+		sessionActive: true,
+		sendCompletionGroup: (items) => {
+			if (!runtime.sessionActive || items.length === 0) return;
+			const message = {
+				customType: "subagent-result",
+				content: formatCompletionMessage(items),
+				display: true,
+			};
+			if (completionGroupTriggersTurn(items)) {
+				// steer: the result is injected after the current tool call even mid-turn,
+				// or starts a new turn when idle. followUp would sit in the queue until the
+				// whole turn ends — a main agent waiting for the result (sleep/poll) would
+				// never see it delivered, which is exactly the "returned but never woken"
+				// failure mode.
+				pi.sendMessage(message, { deliverAs: "steer", triggerTurn: true });
+			} else {
+				// No-wake delivery: nextTurn rides along with the next user turn and can
+				// never start a continuation by itself. followUp would auto-continue
+				// whenever pi is already streaming, defeating the opt-out.
+				pi.sendMessage(message, { deliverAs: "nextTurn" });
+			}
+		},
+		completionBatcher: undefined as unknown as CompletionBatcher<CompletionMessageItem>,
+		runControllers: new Map<number, AbortController>(),
+		settledRuns: new Map<number, SingleResult>(),
+		settledListeners: new Map<number, Set<(result: SingleResult) => void>>(),
+		registerRunResult: (runId, result) => {
+			runtime.settledRuns.set(runId, result);
+			const listeners = runtime.settledListeners.get(runId);
+			if (listeners) {
+				runtime.settledListeners.delete(runId);
+				for (const listener of listeners) {
+					try {
+						listener(result);
+					} catch {
+						/* listener errors must never break settling */
+					}
+				}
+			}
+		},
+		shutdown: () => {
+			runtime.sessionActive = false;
+			runtime.completionBatcher.dispose();
+			runtime.backgroundQueue.cancelAll();
+			runtime.settledRuns.clear();
+			runtime.settledListeners.clear();
+			runtime.runControllers.clear();
+			// Clear the monitor so stale runs from this session never leak into the
+			// next one (the module-level singleton survives across sessions).
+			monitor.clear();
+		},
+	};
+
+	runtime.completionBatcher = createCompletionBatcher<CompletionMessageItem>({
+		emit: runtime.sendCompletionGroup,
+	});
+	return runtime;
+}

package/src/setup.ts

@@ -103,6 +103,31 @@ async function pickAgentModel(
 	);
 }
 
+/** Vision model pick for image tasks (screenshots/mockups); the inherit option
+ * leaves it unset, so vision-flagged dispatches fall back to the main session's
+ * current model. */
+async function pickVisionModel(
+	ctx: ExtensionCommandContext,
+	currentRef: string | undefined,
+	refs: readonly string[],
+): Promise<string | typeof INHERIT | undefined> {
+	const items = [
+		{
+			value: INHERIT,
+			label: currentRef
+				? `(not set — vision tasks fall back to the main session's model; drop "${currentRef}")`
+				: "(not set — vision tasks fall back to the main session's current model)",
+		},
+		...refs.map((ref) => ({ value: ref, label: ref === currentRef ? `${ref} (current)` : ref })),
+	];
+	return promptSelectOne(
+		ctx,
+		"Vision-capable model for image tasks (screenshots, mockups, designs)?",
+		"Type to filter • ↑/↓ • PgUp/PgDn • Enter selects • Esc cancels setup",
+		items,
+	);
+}
+
 async function pickAgentModelsAndStrength(
 	ctx: ExtensionCommandContext,
 	enabledAgents: readonly string[],
@@ -337,6 +362,18 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 	const picked = await pickAgentModelsAndStrength(ctx, enabled, base.agentModels, base.agentThinkingLevels, thinkingLevel, defaults);
 	if (picked === undefined) return notifyCancelled(ctx);
 
+	let nextVisionModel: string | undefined;
+	// No models available: keep the vision model unset (vision tasks then fall
+	// back to the main session's model) instead of showing a one-option picker.
+	const refs = availableModelRefs(ctx);
+	if (refs.length === 0) {
+		ctx.ui.notify("No Pi models are currently available; vision model left unset.", "warning");
+	} else {
+		const visionModel = await pickVisionModel(ctx, base.visionModel, refs);
+		if (visionModel === undefined) return notifyCancelled(ctx);
+		if (visionModel !== INHERIT) nextVisionModel = visionModel;
+	}
+
 	const injection = await pickInjection(ctx, base.proactiveInjection);
 	if (injection === undefined) return notifyCancelled(ctx);
 
@@ -382,7 +419,9 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 		maxConcurrency,
 		maxFixRounds,
 		idleTimeoutSec,
+		announcedFeatures: base.announcedFeatures,
 	};
+	if (nextVisionModel !== undefined) next.visionModel = nextVisionModel;
 	await saveConfig(next, configPath);
 	ctx.ui.notify(`pi-subagents configured. Saved to ${configPath}`, "info");
 }
@@ -391,6 +430,7 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 	const choice = await ctx.ui.select("pi-subagents is already configured. What would you like to change?", [
 		"Enable/disable agents",
 		"Configure an agent (model + thinking)",
+		"Change vision model (image tasks)",
 		"Toggle proactive injection",
 		"Change agent scope",
 		"Change max concurrent sub-agents",
@@ -440,6 +480,16 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 		const injection = await pickInjection(ctx, config.proactiveInjection);
 		if (injection === undefined) return notifyCancelled(ctx);
 		next.proactiveInjection = injection;
+	} else if (choice.startsWith("Change vision")) {
+		const refs = availableModelRefs(ctx);
+		if (refs.length === 0) {
+			ctx.ui.notify("No Pi models are currently available; vision model left unchanged.", "warning");
+			return;
+		}
+		const visionModel = await pickVisionModel(ctx, config.visionModel, refs);
+		if (visionModel === undefined) return notifyCancelled(ctx);
+		if (visionModel === INHERIT) delete next.visionModel;
+		else next.visionModel = visionModel;
 	} else if (choice.startsWith("Change agent scope")) {
 		const scope = await pickScope(ctx, config.agentScope);
 		if (scope === undefined) return notifyCancelled(ctx);

package/src/tools.ts

@@ -0,0 +1,406 @@
+/**
+ * Lookup tools around the subagent runtime: subagent_wait (in-turn result
+ * lookup, non-blocking by default), subagent_status (overview / full result by
+ * id), and subagent_stop (cancel active runs).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { loadConfig } from "./config.ts";
+import { emptyUsage, formatCompletionBlock, formatUsage, matchRunIds } from "./format.ts";
+import {
+	formatElapsed,
+	formatUsageCompact,
+	monitor,
+	statusLabel,
+} from "./monitor.ts";
+import type { SubagentRuntime } from "./runtime.ts";
+import { isFailedResult, type SingleResult } from "./spawn.ts";
+
+/** In-turn result lookup. Dispatch already ended the turn and results arrive as
+ * wake-up messages, so the default must NOT block: a settled run returns its
+ * result immediately, a still-active run returns a "still running — end your
+ * turn" note and the model finishes (the completion then wakes it). Blocking
+ * is opt-in via an explicit timeoutMs — a long default would hold the turn
+ * hostage for nothing, since the result arrives on its own either way. */
+const SUBAGENT_WAIT_DEFAULT_TIMEOUT_MS = 0;
+
+function renderFirstLine(result: { content?: unknown }, label: string, theme: any): Text {
+	const parts = (result.content ?? []) as Array<{ type: string; text?: string }>;
+	const text = parts
+		.map((part) => (typeof part.text === "string" ? part.text : ""))
+		.join(" ")
+		.trim();
+	const firstLine = text.split("\n").find((line) => line.trim()) ?? "(no output)";
+	return new Text(`${theme.fg("toolTitle", theme.bold(label))}${theme.fg("dim", firstLine.slice(0, 60))}`, 0, 0);
+}
+
+export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime): void {
+	const SubagentWaitParams = Type.Object({
+		id: Type.Optional(
+			Type.String({
+				description: "Run id or prefix shown in the subagent widget (#id). Omit to wait for all active runs in this session.",
+			}),
+		),
+		timeoutMs: Type.Optional(
+			Type.Number({
+				description: `Block for up to this many milliseconds and report the still-running runs. Default ${SUBAGENT_WAIT_DEFAULT_TIMEOUT_MS}: no blocking — settled runs return their result immediately, active runs return a note telling the model to end its turn.`,
+			}),
+		),
+	});
+
+	pi.registerTool({
+		name: "subagent_wait",
+		label: "Subagent Wait",
+		description: [
+			"Look up background sub-agent run(s) and return their results.",
+			"PREFER NOT CALLING THIS: dispatching already ended your turn and results arrive as a message that wakes you automatically.",
+			"By default it does NOT block: a settled run returns its result immediately; a still-active run returns a 'still running — end your turn' note.",
+			"Pass an explicit timeoutMs ONLY when you must stay in the turn and need the result right now (sequential dependent steps).",
+			"NEVER sleep, poll, or wait with bash to get a sub-agent result: end the turn, or call this tool.",
+			"The same result is also delivered as a completion message that resumes the main agent, so you may see it twice (once here, once as a wake-up) — that is expected, not a duplicate.",
+		].join(" "),
+		promptSnippet: "Look up a background subagent result in-turn (id: run id from the widget; omit for all). Non-blocking by default; pass timeoutMs to block.",
+		promptGuidelines: [
+			"Do NOT call subagent_wait to hold the turn: results arrive as wake-up messages automatically. The default call is a non-blocking lookup — settled results return immediately, active runs return a note telling you to end your turn.",
+			"Pass an explicit timeoutMs only when you must keep the turn AND the next step depends on the result right now — e.g. the user asked you to wait for it.",
+			"Never use bash sleep/timeout/polling to wait for a sub-agent — it blocks the turn and delays result delivery.",
+			"If subagent_wait times out, end the turn and wait for the wake-up message, or call it again with a longer timeoutMs.",
+		],
+		parameters: SubagentWaitParams,
+
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const config = await loadConfig(runtime.configPath);
+			// A non-finite or negative timeout would produce a nonsensical note
+			// ("timed out after Infinitys") or an instant "timeout" that was never
+			// asked for; fall back to the default. Zero is honored as an immediate
+			// give-up (clamped to 1ms below).
+			const timeoutMs =
+				typeof params.timeoutMs === "number" && Number.isFinite(params.timeoutMs) && params.timeoutMs >= 0
+					? params.timeoutMs
+					: SUBAGENT_WAIT_DEFAULT_TIMEOUT_MS;
+			const isActive = (run: { status: string; retained?: boolean }): boolean =>
+				run.status === "queued" || run.status === "running" || run.retained === true;
+
+			const requested = params.id?.trim();
+			// A run that already settled resolves immediately with its result.
+			if (requested) {
+				const settledIds = matchRunIds([...runtime.settledRuns.keys()], requested);
+				if (settledIds.length > 0) {
+					return {
+						content: [
+							{ type: "text", text: settledIds.map((id) => formatCompletionBlock(runtime.settledRuns.get(id)!, config.maxResultLines, ctx.cwd)).join("\n\n") },
+						],
+						details: {},
+					};
+				}
+			}
+
+			const activeRuns = monitor.getRuns().filter(isActive);
+			const targetIds = requested ? matchRunIds(activeRuns.map((run) => run.id), requested) : activeRuns.map((run) => run.id);
+			const targets = activeRuns.filter((run) => targetIds.includes(run.id));
+			if (targets.length === 0) {
+				const activeList = activeRuns.map((run) => `#${run.id} ${run.agent}`).join(", ");
+				return {
+					content: [
+						{
+							type: "text",
+							text: requested
+								? `No active subagent run matches "${requested}".${activeList ? ` Active runs: ${activeList}.` : ""}`
+								: `No active subagent runs${activeList ? ` (active: ${activeList})` : " right now"}.`,
+						},
+					],
+					details: {},
+				};
+			}
+
+			const waitForRun = (runId: number): Promise<{ result?: SingleResult; note?: string }> => {
+				const already = runtime.settledRuns.get(runId);
+				if (already) return Promise.resolve({ result: already });
+				return new Promise((resolve) => {
+					let done = false;
+					let timer: ReturnType<typeof setTimeout> | undefined;
+					let unsub: (() => void) | undefined;
+					const cleanup = (): void => {
+						if (timer) clearTimeout(timer);
+						if (unsub) unsub();
+						signal?.removeEventListener("abort", onAbort);
+						const listeners = runtime.settledListeners.get(runId);
+						if (listeners) {
+							listeners.delete(onSettled);
+							if (listeners.size === 0) runtime.settledListeners.delete(runId);
+						}
+					};
+					const finish = (outcome: { result?: SingleResult; note?: string }): void => {
+						if (done) return;
+						done = true;
+						cleanup();
+						resolve(outcome);
+					};
+					const onSettled = (result: SingleResult): void => finish({ result });
+					const onMonitor = (): void => {
+						const current = runtime.settledRuns.get(runId);
+						if (current) {
+							finish({ result: current });
+							return;
+						}
+						if (!monitor.findRun(runId)) {
+							// Removal is followed synchronously by registerRunResult in the
+							// finishing task; re-check on the next tick so the result wins.
+							setTimeout(() => {
+								const late = runtime.settledRuns.get(runId);
+								if (late) finish({ result: late });
+								else finish({ note: `run #${runId} was removed before its result was recorded (cancelled or session ended)` });
+							}, 0);
+						}
+					};
+					const onAbort = (): void => finish({ note: "wait aborted" });
+					let listeners = runtime.settledListeners.get(runId);
+					if (!listeners) {
+						listeners = new Set();
+						runtime.settledListeners.set(runId, listeners);
+					}
+					listeners.add(onSettled);
+					unsub = monitor.subscribe(onMonitor);
+					timer = setTimeout(
+						() =>
+							finish({
+								note:
+									timeoutMs === 0
+										? `run #${runId} is still active — end your turn: the result will wake you (or call subagent_wait again with an explicit timeoutMs to block)`
+										: `wait timed out after ${Math.round(timeoutMs / 1000)}s — run #${runId} is still active; call subagent_wait again or end the turn (the result will wake you when ready)`,
+							}),
+						Math.max(1, timeoutMs),
+					);
+					if (signal?.aborted) onAbort();
+					else signal?.addEventListener("abort", onAbort, { once: true });
+				});
+			};
+
+			const outcomes = await Promise.all(targets.map((run) => waitForRun(run.id)));
+			const blocks = outcomes.map((outcome) =>
+				outcome.result ? formatCompletionBlock(outcome.result, config.maxResultLines, ctx.cwd) : (outcome.note ?? "(no outcome)"),
+			);
+			return { content: [{ type: "text", text: blocks.join("\n\n") }], details: {} };
+		},
+
+		renderCall(args, theme) {
+			const target = args.id ? `#${args.id}` : "all";
+			return new Text(`${theme.fg("toolTitle", theme.bold("subagent_wait "))}${theme.fg("accent", target)}`, 0, 0);
+		},
+
+		renderResult(result, _options, theme) {
+			return renderFirstLine(result, "subagent_wait ", theme);
+		},
+	});
+
+	// Status overview: what is running right now and what finished this session,
+	// with per-run details (id, agent, model, usage, elapsed, activity) so the
+	// main agent can decide whether to wait, stop, or re-dispatch. Learned from
+	// nicobailon/pi-subagents ({action:"status"} + status files): inspect before
+	// you act, and report run ids when handing off.
+	const SubagentStatusParams = Type.Object({
+		id: Type.Optional(
+			Type.String({
+				description: "Run id or prefix to show the full result for (must already be finished; use subagent_wait to block on an active run).",
+			}),
+		),
+	});
+
+	pi.registerTool({
+		name: "subagent_status",
+		label: "Subagent Status",
+		description: [
+			"List active background sub-agent runs (id, agent, model, usage, elapsed, current activity) and recently finished results.",
+			"Pass id to read the full result of a finished run; pass no id for the overview.",
+			"Use it to decide whether to subagent_wait, subagent_stop, or re-dispatch — never to poll: results arrive by themselves.",
+		].join(" "),
+		promptSnippet: "Inspect background subagents: active runs, finished results, full result by id.",
+		promptGuidelines: [
+			"Call subagent_status to see what is running and what already finished; the widget shows the same live state.",
+			"Never poll subagent_status in a loop to wait for a run: end the turn (you will be woken) or call subagent_wait.",
+			"A finished run's id stays available for the session; its full result is one subagent_status call away.",
+		],
+		parameters: SubagentStatusParams,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const config = await loadConfig(runtime.configPath);
+			const requested = params.id?.trim();
+
+			if (requested) {
+				const settledIds = matchRunIds([...runtime.settledRuns.keys()], requested);
+				if (settledIds.length > 0) {
+					return {
+						content: [
+							{ type: "text", text: settledIds.map((id) => formatCompletionBlock(runtime.settledRuns.get(id)!, config.maxResultLines, ctx.cwd)).join("\n\n") },
+						],
+						details: {},
+					};
+				}
+				const runs = monitor.getRuns();
+				const activeId = matchRunIds(runs.map((run) => run.id), requested)[0];
+				const active = activeId === undefined ? undefined : runs.find((run) => run.id === activeId);
+				if (active) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Run #${active.id} ${active.agent} is still active (${active.activity ?? statusLabel(active.status)}). Use subagent_wait to block for its result, or subagent_stop to cancel it.`,
+							},
+						],
+						details: {},
+					};
+				}
+				return { content: [{ type: "text", text: `No subagent run matches "${requested}".` }], details: {} };
+			}
+
+			const now = Date.now();
+			const activeRuns = monitor.getRuns().filter(
+				(run) => run.status === "queued" || run.status === "running" || run.retained,
+			);
+			const activeLines = activeRuns.map((run) => {
+				const parts = [
+					`#${run.id} ${run.agent}`,
+					run.model ?? "?",
+					formatUsageCompact(run.usage),
+					formatElapsed(run, now),
+				].filter(Boolean);
+				return `- ${parts.join(" · ")} · ${run.activity ?? statusLabel(run.status)}`;
+			});
+			const completed = [...runtime.settledRuns.entries()].slice(-5);
+			const completedLines = completed.map(([id, result]) => {
+				const usage = formatUsage(result.usage);
+				return `- #${id} ${result.agent} · ${isFailedResult(result) ? "failed" : "completed"}${usage ? ` · ${usage}` : ""}`;
+			});
+
+			const sections: string[] = [];
+			sections.push(`### Active subagent runs (${activeRuns.length})`);
+			sections.push(activeLines.length > 0 ? activeLines.join("\n") : "(none)");
+			sections.push(`### Finished this session (${runtime.settledRuns.size})`);
+			sections.push(completedLines.length > 0 ? completedLines.join("\n") : "(none)");
+			sections.push("Pass a run id to subagent_status for the full result, or subagent_wait to block for an active run.");
+			return { content: [{ type: "text", text: sections.join("\n\n") }], details: {} };
+		},
+
+		renderCall(args, theme) {
+			return new Text(
+				`${theme.fg("toolTitle", theme.bold("subagent_status "))}${theme.fg("accent", args.id ? `#${args.id}` : "overview")}`,
+				0,
+				0,
+			);
+		},
+
+		renderResult(result, _options, theme) {
+			return renderFirstLine(result, "subagent_status ", theme);
+		},
+	});
+
+	// Cancel one or more active runs: aborts the queue controller, which
+	// terminates the child and delivers an aborted result (with whatever partial
+	// output it produced) so the main agent always knows the run stopped.
+	const SubagentStopParams = Type.Object({
+		id: Type.Optional(
+			Type.String({
+				description: "Run id or prefix to stop (see the widget or subagent_status).",
+			}),
+		),
+		all: Type.Optional(Type.Boolean({ description: "Stop every active run (default false)." })),
+	});
+
+	pi.registerTool({
+		name: "subagent_stop",
+		label: "Subagent Stop",
+		description: [
+			"Cancel one or more active background sub-agent runs: the child process is terminated and an aborted result (with partial output) is delivered.",
+			"Pass id (run id or prefix) to stop one run, or all: true to stop every active run.",
+		].join(" "),
+		promptSnippet: "Stop a running background subagent (id from the widget/subagent_status; or all: true).",
+		promptGuidelines: [
+			"Stop a run when its task is obsolete, stuck, or superseded — do not leave it burning tokens.",
+			"A stopped run reports as failed with 'aborted' and its partial output, so the next step knows it did not complete.",
+		],
+		parameters: SubagentStopParams,
+
+		async execute(_toolCallId, params, _signal, _onUpdate) {
+			const targets =
+				params.all === true
+					? [...runtime.runControllers.keys()]
+					: params.id !== undefined && params.id.trim() !== ""
+						? matchRunIds([...runtime.runControllers.keys()], params.id!.trim())
+						: [];
+
+			if (targets.length === 0) {
+				const activeList = [...runtime.runControllers.keys()].map((id) => `#${id}`).join(", ");
+				return {
+					content: [
+						{
+							type: "text",
+							text:
+								params.all === true
+									? "No active subagent runs to stop."
+									: `No active subagent run matches "${params.id}".${activeList ? ` Active runs: ${activeList}.` : ""}`,
+						},
+					],
+					details: {},
+				};
+			}
+
+			const stopped: string[] = [];
+			for (const runId of targets) {
+				const run = monitor.findRun(runId);
+				if (!run) {
+					runtime.runControllers.delete(runId);
+					continue;
+				}
+				// Abort before registering the synthetic result: abort() only marks the
+				// queue entry (drain delivers the cancellation callback later), so the
+				// has() re-check right after it distinguishes an entry that never ran
+				// from one whose task already started under a stale "queued" status —
+				// a started task owns its own (real, partial-output) result.
+				const controller = runtime.runControllers.get(runId);
+				controller?.abort();
+				// A queued run never reaches the child-spawn code path, so its abort
+				// goes through the queue's cancelled callback with no result object;
+				// register a synthetic aborted result so subagent_wait resolves.
+				if (run.status === "queued" && runtime.runControllers.has(runId)) {
+					runtime.registerRunResult(runId, {
+						agent: run.agent,
+						agentSource: "builtin",
+						task: run.task,
+						exitCode: 1,
+						messages: [],
+						stderr: "Stopped by subagent_stop before the run started.",
+						usage: emptyUsage(),
+						model: run.model,
+						thinking: run.thinking,
+						stopReason: "aborted",
+						errorMessage: "Stopped by subagent_stop before the run started.",
+					});
+				}
+				stopped.push(`#${runId} ${run.agent}${run.status === "queued" ? " (queued)" : ""}`);
+			}
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Stopped ${stopped.length} run${stopped.length === 1 ? "" : "s"}: ${stopped.join(", ")}. An aborted result (with partial output) is delivered.`,
+					},
+				],
+				details: {},
+			};
+		},
+
+		renderCall(args, theme) {
+			return new Text(
+				`${theme.fg("toolTitle", theme.bold("subagent_stop "))}${theme.fg("accent", args.all === true ? "all" : args.id ? `#${args.id}` : "?")}`,
+				0,
+				0,
+			);
+		},
+
+		renderResult(result, _options, theme) {
+			return renderFirstLine(result, "subagent_stop ", theme);
+		},
+	});
+}