@ferris1225/pi-subagents 4.2.7 → 4.2.12

package/src/dispatch.ts

@@ -6,7 +6,7 @@
  * completion ownership live in thread-lifecycle.ts.
  */
 
-import { StringEnum } from "@earendil-works/pi-ai";
+import { StringEnum, type Usage } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { join, resolve } from "node:path";
@@ -19,6 +19,8 @@ import {
 	formatToolActivity,
 	monitor,
 	statusIcon,
+	statusLabel,
+	sumUsage,
 	type RunView,
 	type RunWaitReason,
 } from "./monitor.ts";
@@ -32,6 +34,7 @@ import {
 	type SingleResult,
 	type SubagentDetails,
 	type SubagentLiveEvent,
+	type UsageStats,
 } from "./spawn.ts";
 import {
 	createBackgroundDispatcher,
@@ -116,6 +119,31 @@ export function defaultIsolationMode(
 	return mode === "parallel" && writeCapable ? "worktree" : "shared";
 }
 
+/** Map the child's own usage tally onto pi's tool-result `Usage`, so sub-agent
+ * token spend lands in the parent's footer, /session, and RPC session totals
+ * instead of being invisible. Only the total cost is known here: a child
+ * reports one cost number, not a per-bucket split. */
+function toToolUsage(stats: UsageStats): Usage {
+	return {
+		input: stats.input,
+		output: stats.output,
+		cacheRead: stats.cacheRead,
+		cacheWrite: stats.cacheWrite,
+		totalTokens: stats.input + stats.output + stats.cacheRead + stats.cacheWrite,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: stats.cost },
+	};
+}
+
+/** Usage of the runs awaited in-turn. Omitted entirely in the background path:
+ * those children have not finished when the tool returns, so any number there
+ * would be a fabrication. */
+function toolUsage(runtime: SubagentRuntime, runIds: number[]): { usage?: Usage } {
+	const parts = runIds
+		.map((id) => runtime.settledRuns.get(id)?.usage)
+		.filter((usage): usage is UsageStats => usage !== undefined);
+	return parts.length > 0 ? { usage: toToolUsage(sumUsage(parts)) } : {};
+}
+
 /** In-turn wait behind dispatch `wait: true` — the escape hatch for one-shot
  * `pi -p` parents that exit at end of turn: hold the call until every run it
  * started settles, then hand back their result blocks. Interactive sessions
@@ -130,6 +158,7 @@ export async function awaitRunResults(
 	signal: AbortSignal | undefined,
 	maxResultLines: number,
 	fallbackCwd: string,
+	onProgress?: (text: string) => void,
 ): Promise<string> {
 	const waitForRun = (runId: number): Promise<{ result?: SingleResult; note?: string }> => {
 		const already = runtime.settledRuns.get(runId);
@@ -189,12 +218,38 @@ export async function awaitRunResults(
 			else signal?.addEventListener("abort", onAbort, { once: true });
 		});
 	};
-	const outcomes = await Promise.all(runIds.map(waitForRun));
-	return outcomes.map((outcome) =>
-		outcome.result
-			? formatCompletionBlock(outcome.result, maxResultLines, { resultRoot: projectResultsRoot(runtime.configPath, outcome.result.projectCwd ?? fallbackCwd) })
-			: (outcome.note ?? "(no outcome)"),
-	).join("\n\n");
+	// One shared subscription drives the progress line: each waiter already
+	// subscribes for its own settlement, and the tool card wants a single
+	// rolled-up line rather than one per run.
+	let lastProgress: string | undefined;
+	const emitProgress = onProgress
+		? (): void => {
+			const parts = runIds.map((id) => {
+				const settled = runtime.settledRuns.get(id);
+				if (settled) return `#${id} ${isFailedResult(settled) ? "failed" : "done"}`;
+				const live = monitor.findRun(id);
+				return live ? `#${id} ${statusLabel(live.status)}` : `#${id} …`;
+			});
+			const text = `Waiting in-turn on ${runIds.length} run${runIds.length === 1 ? "" : "s"} · ${parts.join(", ")}`;
+			// The monitor notifies on every usage and activity change; this line
+			// names only statuses, so most notifications leave it identical.
+			if (text === lastProgress) return;
+			lastProgress = text;
+			onProgress(text);
+		}
+		: undefined;
+	const progressUnsub = emitProgress ? monitor.subscribe(emitProgress) : undefined;
+	emitProgress?.();
+	try {
+		const outcomes = await Promise.all(runIds.map(waitForRun));
+		return outcomes.map((outcome) =>
+			outcome.result
+				? formatCompletionBlock(outcome.result, maxResultLines, { resultRoot: projectResultsRoot(runtime.configPath, outcome.result.projectCwd ?? fallbackCwd) })
+				: (outcome.note ?? "(no outcome)"),
+		).join("\n\n");
+	} finally {
+		progressUnsub?.();
+	}
 }
 
 export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime): void {
@@ -203,16 +258,22 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 	// refreshes the fallback context, config, and agent catalog it resolves.
 	const environmentRef: { current: DispatchEnvironment | undefined } = { current: undefined };
 
-	// Finished runs leave the active monitor immediately. Their final findings
-	// are sent as a custom message that starts a follow-up turn.
+	// Terminal rows stay in the monitor until the next beginTurn so the footer
+	// can count them beside siblings that are still live. The widget ignores
+	// them. A second finishRun for the same endedAt is a no-op; a resume
+	// clears endedAt, so the next settlement notifies again.
+	const publishedEndedAt = new Map<number, number>();
 	const finishRun = (
 		runId: number,
 		status: "done" | "failed",
 		opts?: { silent?: boolean },
 	): void => {
+		const run = monitor.findRun(runId);
+		if (!run) return;
 		monitor.setStatus(runId, status); // stamps endedAt for the elapsed time
-		const run = monitor.removeRun(runId);
-		if (!run) return; // already finished — stay idempotent
+		const endedAt = monitor.findRun(runId)?.endedAt;
+		if (endedAt !== undefined && publishedEndedAt.get(runId) === endedAt) return;
+		if (endedAt !== undefined) publishedEndedAt.set(runId, endedAt);
 		if (opts?.silent || !runtime.sessionActive) return;
 		const icon = status === "done" ? "✓" : "✗";
 		environmentRef.current?.ctx.ui.notify(`${icon} #${run.id} ${monitor.summarize(run)}`, status === "done" ? "info" : "error");
@@ -332,7 +393,13 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			"Dispatch isolated background agents for recon, implementation, cleanup, docs sync, or result merging; never blocks your turn, and completions wake you automatically.",
 		parameters: SubagentParams,
 
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			// `wait: true` holds this call for minutes and would otherwise show a
+			// blank card; the background path returns at once and has nothing to
+			// stream. Frames carry the final details shape because renderResult
+			// falls back to "(no output)" without it.
+			const makeProgress = (details: SubagentDetails): ((text: string) => void) | undefined =>
+				onUpdate ? (text: string): void => onUpdate({ content: [{ type: "text", text }], details }) : undefined;
 			// Run ids are allocated below; restore raises the allocator above every
 			// id a durable record still owns, so a dispatch racing it could hand a
 			// fresh run the id of a parked thread and overwrite its record.
@@ -438,7 +505,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					const startedIds = startedRuns
 						.map((result) => result.runId)
 						.filter((id): id is number => id !== undefined);
-					const blocks = await awaitRunResults(runtime, startedIds, signal, config.maxResultLines, ctx.cwd);
+					const blocks = await awaitRunResults(runtime, startedIds, signal, config.maxResultLines, ctx.cwd, makeProgress(makeDetails("parallel", true)(results)));
 					const text = [
 						`Started ${started} subagent${started === 1 ? "" : "s"} (${startedRefs.join(", ")}) and waited in-turn.`,
 						...(failureLines.length > 0
@@ -450,6 +517,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					return {
 						content: [{ type: "text", text }],
 						details: makeDetails("parallel", true)(results),
+						...toolUsage(runtime, startedIds),
 					};
 				}
 				const text = [
@@ -483,10 +551,11 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			}
 			const runRef = result.runId === undefined ? result.agent : `#${result.runId} ${result.agent}`;
 			if (params.wait && result.runId !== undefined) {
-				const blocks = await awaitRunResults(runtime, [result.runId], signal, config.maxResultLines, ctx.cwd);
+				const blocks = await awaitRunResults(runtime, [result.runId], signal, config.maxResultLines, ctx.cwd, makeProgress(makeDetails("single", true)([result])));
 				return {
 					content: [{ type: "text", text: `Started ${runRef} and waited in-turn.\n\n${blocks}` }],
 					details: makeDetails("single", true)([result]),
+					...toolUsage(runtime, [result.runId]),
 				};
 			}
 			return {

package/src/format.ts

@@ -1,165 +1,183 @@
-/**
- * Pure formatting/result helpers shared by the subagent tool and completion
- * delivery: usage rendering, completion blocks, synthetic result constructors,
- * and run-id matching.
- */
-
-import type { AgentConfig } from "./agents.ts";
-import { formatTaskSummary } from "./monitor.ts";
-import { emptyUsage } from "./rpc-run.ts";
-import {
-	getResultOutput,
-	isFailedResult,
-	truncateResultOutput,
-	writeResultArtifact,
-	type SingleResult,
-	type UsageStats,
-} from "./spawn.ts";
-
-export function queuedResult(agent: AgentConfig, task: string, thinking?: string): SingleResult {
-	return {
-		agent: agent.name,
-		task,
-		exitCode: -1,
-		messages: [],
-		stderr: "",
-		usage: emptyUsage(),
-		model: agent.model,
-		...(thinking ? { thinking } : {}),
-	};
-}
-
-export function failedStartResult(agentName: string, task: string, errorMessage: string): SingleResult {
-	return {
-		agent: agentName,
-		task,
-		exitCode: 1,
-		messages: [],
-		stderr: errorMessage,
-		usage: emptyUsage(),
-		errorMessage,
-		dispatchFailed: true,
-	};
-}
-
-/** Failed result for a background task that crashed with an exception (spawn
- * infra, delivery API, ...) instead of returning a normal result. */
-export function dispatchFailedResult(agent: AgentConfig, task: string, error: unknown, thinking?: string): SingleResult {
-	const errorMessage = error instanceof Error ? error.message : String(error);
-	return {
-		...queuedResult(agent, task, thinking),
-		exitCode: 1,
-		stderr: errorMessage,
-		stopReason: "error",
-		errorMessage,
-		dispatchFailed: true,
-	};
-}
-
-function formatTokens(count: number): string {
-	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
-	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
-	return String(count);
-}
-
-export function formatUsage(usage: UsageStats): string {
-	const parts: string[] = [];
-	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
-	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
-	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
-	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
-	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
-	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
-	return parts.join(" ");
-}
-
-export interface CompletionFormatOptions {
-	/** Project-scoped directory the full result is written to when the output
-	 * is truncated: <projectRoot>/results. */
-	resultRoot?: string;
-}
-
-export function formatCompletionBlock(
-	result: SingleResult,
-	maxResultLines: number,
-	options: CompletionFormatOptions = {},
-): string {
-	const failed = isFailedResult(result);
-	const failedTools = result.failedTools ?? [];
-	const status = failed ? "failed" : "completed";
-	const usage = formatUsage(result.usage);
-	const output = getResultOutput(result);
-	const { text, truncated } = truncateResultOutput(output, maxResultLines);const fallbackNote = result.modelFallbackFrom
-		? ` (selected model ${result.modelFallbackFrom} failed → main ${result.model ?? "dynamic default"})`
-		: "";
-	const startupRetryNote = result.startupRetries
-		? ` (recovered after ${result.startupRetries} startup retr${result.startupRetries === 1 ? "y" : "ies"} — concurrent pi startup race)`
-		: "";
-	const runNote = result.runId !== undefined ? ` · run #${result.runId}` : "";
-	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}${startupRetryNote}${runNote}`, "", `Task: ${formatTaskSummary(result.task, 80, false)}`, ""];
-	if (result.isolation === "worktree") {
-		const isolation =
-			result.integrationStatus === "integrated"
-				? "worktree · changes integrated into the original working tree"
-				: result.integrationStatus === "no_changes"
-					? "worktree · no changes; temporary worktree removed"
-					: result.integrationStatus === "retained"
-						? result.integrationApplied
-							? "worktree · changes applied, but cleanup failed; recovery artifacts retained"
-							: "worktree · integration failed; recovery artifacts retained"
-						: "worktree · isolated";
-		lines.push(`Isolation: ${isolation}`);
-		if (result.integrationWorktreePath) lines.push(`Retained worktree: ${result.integrationWorktreePath}`);
-		if (result.integrationPatchPath) lines.push(`Retained patch: ${result.integrationPatchPath}`);
-		if (result.integrationError) lines.push(`Integration error: ${result.integrationError}`);
-		lines.push("");
-	}
-	lines.push(text);
-	// Failed-tool diagnostics ride along only when the run itself failed: they
-	// explain the failure, while on a successful run a transient failed call
-	// (no-match grep, rejected edit) is noise the agent already worked around.
-	if (failed && failedTools.length > 0) {
-		lines.push(
-			"",
-			`⚠ ${failedTools.length} failed tool call${failedTools.length === 1 ? "" : "s"}:`,
-			...failedTools.map((tool) => `- ${tool.toolName}: ${tool.error.trim() || "(no output)"}`),
-		);
-	}
-	if (truncated) {
-		// The full text lives on disk so the main agent can read it on demand.
-		const artifact = options.resultRoot
-			? writeResultArtifact(output, result.agent, options.resultRoot)
-			: "(result root unavailable)";
-		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${artifact})`);
-	}
-	return lines.join("\n");
-}
-
-/** Instruction appended to a model-level failure: the sub-agent's provider never
- * produced usable output (or the run stalled), so the task is handed back to the
- * main window instead of being left as a dead failure. When the run preserved a
- * session with earlier work (and the run id is known), steer the main agent to
- * RESUME it in-context once a model is available, instead of re-dispatching
- * fresh (which would re-scan everything). */
-export function modelLevelTakeoverNote(result: SingleResult, opts?: { runId?: number }): string {
-	const retry = result.modelFallbackFrom ? ", and the current main model also failed" : "";
-	const detail = result.errorMessage?.trim();
-	const cause = detail
-		? `its model/provider call failed (${detail})`
-		: "its model was unavailable or failed (or the run stalled)";
-	const sessionPreserved = Boolean(result.sessionDir && result.sessionId) && opts?.runId !== undefined;
-	const recovery = sessionPreserved
-		? ` The sub-agent's earlier work in this run is preserved. Once a model is available again, call subagent_control with { action: "resume", id: ${opts!.runId} } to CONTINUE it in-context (it keeps the same run id and does not re-scan), or execute the task in the main window with your own tools.`
-		: ` Please execute this task in the main window with your own tools; do not re-dispatch it as a sub-agent.`;
-	return `The sub-agent could not complete this task: ${cause}${retry}.${recovery}`;
-}
-
-/** Resolve a run-id request to actual ids: an exact numeric match always wins
- * (so "1" never fans out to 10, 11, …); only when no exact match exists does a
- * prefix match run, as a convenience for partial ids. Keeps single-digit lookups
- * from returning — or, for subagent_stop, acting on — a whole prefix family. */
-export function matchRunIds(ids: number[], requested: string): number[] {
-	const exact = ids.filter((id) => String(id) === requested);
-	if (exact.length > 0) return exact;
-	return ids.filter((id) => String(id).startsWith(requested));
-}
+/**
+ * Pure formatting/result helpers shared by the subagent tool and completion
+ * delivery: usage rendering, completion blocks, synthetic result constructors,
+ * and run-id matching.
+ */
+
+import type { AgentConfig } from "./agents.ts";
+import { runLabel, shrinkRunLabel } from "./monitor.ts";
+import { emptyUsage } from "./rpc-run.ts";
+import {
+	RESULT_LINE_MAX,
+	getResultOutput,
+	isFailedResult,
+	truncateResultOutput,
+	writeResultArtifact,
+	type SingleResult,
+	type UsageStats,
+} from "./spawn.ts";
+
+export function queuedResult(agent: AgentConfig, task: string, thinking?: string): SingleResult {
+	return {
+		agent: agent.name,
+		task,
+		exitCode: -1,
+		messages: [],
+		stderr: "",
+		usage: emptyUsage(),
+		model: agent.model,
+		...(thinking ? { thinking } : {}),
+	};
+}
+
+export function failedStartResult(agentName: string, task: string, errorMessage: string): SingleResult {
+	return {
+		agent: agentName,
+		task,
+		exitCode: 1,
+		messages: [],
+		stderr: errorMessage,
+		usage: emptyUsage(),
+		errorMessage,
+		dispatchFailed: true,
+	};
+}
+
+/** Failed result for a background task that crashed with an exception (spawn
+ * infra, delivery API, ...) instead of returning a normal result. */
+export function dispatchFailedResult(agent: AgentConfig, task: string, error: unknown, thinking?: string): SingleResult {
+	const errorMessage = error instanceof Error ? error.message : String(error);
+	return {
+		...queuedResult(agent, task, thinking),
+		exitCode: 1,
+		stderr: errorMessage,
+		stopReason: "error",
+		errorMessage,
+		dispatchFailed: true,
+	};
+}
+
+function formatTokens(count: number): string {
+	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
+	return String(count);
+}
+
+export function formatUsage(usage: UsageStats): string {
+	const parts: string[] = [];
+	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+	if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+	return parts.join(" ");
+}
+
+export interface CompletionFormatOptions {
+	/** Project-scoped directory the full result is written to when the output
+	 * is truncated: <projectRoot>/results. */
+	resultRoot?: string;
+}
+
+/** Display width of the task-derived label folded into the completion heading:
+ * tight enough to stay a hint rather than a second copy of the task. */
+const COMPLETION_LABEL_MAX = 24;
+
+export function formatCompletionBlock(
+	result: SingleResult,
+	maxResultLines: number,
+	options: CompletionFormatOptions = {},
+): string {
+	const failed = isFailedResult(result);
+	const failedTools = result.failedTools ?? [];
+	const status = failed ? "failed" : "completed";
+	const usage = formatUsage(result.usage);
+	const output = getResultOutput(result);
+	const { text, truncated, shownLines, totalLines, widthClipped } = truncateResultOutput(output, maxResultLines);
+	const fallbackNote = result.modelFallbackFrom
+		? ` (selected model ${result.modelFallbackFrom} failed → main ${result.model ?? "dynamic default"})`
+		: "";
+	const startupRetryNote = result.startupRetries
+		? ` (recovered after ${result.startupRetries} startup retr${result.startupRetries === 1 ? "y" : "ies"} — concurrent pi startup race)`
+		: "";
+	const runNote = result.runId !== undefined ? ` · run #${result.runId}` : "";
+	// A short task-derived label, not the task itself: the parent authored the
+	// task and still has it in context, but a wide fan-out of same-agent runs
+	// needs more than a run id to tell completions apart.
+	const label = shrinkRunLabel(runLabel(result.task), COMPLETION_LABEL_MAX);
+	const lines = [
+		`### [${result.agent}${label ? `·${label}` : ""}] ${status}${usage ? ` (${usage})` : ""}${fallbackNote}${startupRetryNote}${runNote}`,
+		"",
+	];
+	if (result.isolation === "worktree") {
+		const isolation =
+			result.integrationStatus === "integrated"
+				? "worktree · changes integrated into the original working tree"
+				: result.integrationStatus === "no_changes"
+					? "worktree · no changes; temporary worktree removed"
+					: result.integrationStatus === "retained"
+						? result.integrationApplied
+							? "worktree · changes applied, but cleanup failed; recovery artifacts retained"
+							: "worktree · integration failed; recovery artifacts retained"
+						: "worktree · isolated";
+		lines.push(`Isolation: ${isolation}`);
+		if (result.integrationWorktreePath) lines.push(`Retained worktree: ${result.integrationWorktreePath}`);
+		if (result.integrationPatchPath) lines.push(`Retained patch: ${result.integrationPatchPath}`);
+		if (result.integrationError) lines.push(`Integration error: ${result.integrationError}`);
+		lines.push("");
+	}
+	lines.push(text);
+	// Failed-tool diagnostics ride along only when the run itself failed: they
+	// explain the failure, while on a successful run a transient failed call
+	// (no-match grep, rejected edit) is noise the agent already worked around.
+	if (failed && failedTools.length > 0) {
+		lines.push(
+			"",
+			`⚠ ${failedTools.length} failed tool call${failedTools.length === 1 ? "" : "s"}:`,
+			...failedTools.map((tool) => `- ${tool.toolName}: ${tool.error.trim() || "(no output)"}`),
+		);
+	}
+	if (truncated) {
+		// The full text lives on disk so the main agent can read it on demand.
+		const artifact = options.resultRoot
+			? writeResultArtifact(output, result.agent, options.resultRoot)
+			: "(result root unavailable)";
+		// State the real loss and condition the read: handing the parent both a
+		// summary and a full-text entrance invites the same content twice.
+		const lineLoss = shownLines < totalLines ? `${shownLines} of ${totalLines} lines shown` : `${shownLines} line${shownLines === 1 ? "" : "s"} shown`;
+		const widthLoss = widthClipped ? `clipped to ${RESULT_LINE_MAX} characters` : undefined;
+		const loss = widthLoss ? `${lineLoss}, ${widthLoss}` : lineLoss;
+		lines.push("", `(${loss}; full result ${artifact} — read only if these are insufficient)`);
+	}
+	return lines.join("\n");
+}
+
+/** Instruction appended to a model-level failure: the sub-agent's provider never
+ * produced usable output (or the run stalled), so the task is handed back to the
+ * main window instead of being left as a dead failure. When the run preserved a
+ * session with earlier work (and the run id is known), steer the main agent to
+ * RESUME it in-context once a model is available, instead of re-dispatching
+ * fresh (which would re-scan everything). */
+export function modelLevelTakeoverNote(result: SingleResult, opts?: { runId?: number }): string {
+	const retry = result.modelFallbackFrom ? ", and the current main model also failed" : "";
+	const detail = result.errorMessage?.trim();
+	const cause = detail
+		? `its model/provider call failed (${detail})`
+		: "its model was unavailable or failed (or the run stalled)";
+	const sessionPreserved = Boolean(result.sessionDir && result.sessionId) && opts?.runId !== undefined;
+	const recovery = sessionPreserved
+		? ` The sub-agent's earlier work in this run is preserved. Once a model is available again, call subagent_control with { action: "resume", id: ${opts!.runId} } to CONTINUE it in-context (it keeps the same run id and does not re-scan), or execute the task in the main window with your own tools.`
+		: ` Please execute this task in the main window with your own tools; do not re-dispatch it as a sub-agent.`;
+	return `The sub-agent could not complete this task: ${cause}${retry}.${recovery}`;
+}
+
+/** Resolve a run-id request to actual ids: an exact numeric match always wins
+ * (so "1" never fans out to 10, 11, …); only when no exact match exists does a
+ * prefix match run, as a convenience for partial ids. Keeps single-digit lookups
+ * from returning — or, for subagent_stop, acting on — a whole prefix family. */
+export function matchRunIds(ids: number[], requested: string): number[] {
+	const exact = ids.filter((id) => String(id) === requested);
+	if (exact.length > 0) return exact;
+	return ids.filter((id) => String(id).startsWith(requested));
+}