pi-subagents 0.57.0 → 0.59.0

package/src/slash/slash-commands.ts

@@ -22,6 +22,10 @@ import { listAsyncRuns, formatAsyncRunProgressLabel, type AsyncRunSummary } from
 import { encodeInspectReply, handleInspectRpcArgs, INSPECT_WIDGET_KEY } from "../runs/background/inspect-rpc.ts";
 import { listScheduledRunSummaries } from "../runs/background/scheduled-runs.ts";
 import { SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
+import { resolveAsyncStatusChild } from "../runs/shared/child-identity.ts";
+import { readStatus } from "../shared/utils.ts";
+import { getArtifactPaths, getArtifactsDir } from "../shared/artifacts.ts";
+import { readWorkflowReceipt } from "../workflows/workflow-receipt.ts";
 import { FLEET_OPEN_SHORTCUT } from "../shared/shortcuts.ts";
 import type { SlashSubagentResponse, SlashSubagentUpdate } from "./slash-bridge.ts";
 import { registerPromptWorkflowCommands } from "./prompt-workflows.ts";
@@ -46,7 +50,6 @@ import {
 	DIRS,
 	type Details,
 	type FleetKeybindingsConfig,
-	type JsonSchemaObject,
 	type SingleResult,
 	type SubagentState,
 	type Usage,
@@ -346,25 +349,60 @@ function usageHasValue(usage: Usage): boolean {
 	return usage.input !== 0 || usage.output !== 0 || usage.cacheRead !== 0 || usage.cacheWrite !== 0 || usage.cost !== 0 || usage.turns !== 0;
 }
 
+function nonNegativeNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function usageFromValue(value: unknown, turnsOverride?: number): Usage | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	const costValue = typeof record.cost === "object" && record.cost !== null && !Array.isArray(record.cost)
+		? (record.cost as Record<string, unknown>).total
+		: record.cost;
+	const turnsValue = turnsOverride ?? record.turns;
+	const usage = {
+		input: nonNegativeNumber(record.input) ?? 0,
+		output: nonNegativeNumber(record.output) ?? 0,
+		cacheRead: nonNegativeNumber(record.cacheRead) ?? 0,
+		cacheWrite: nonNegativeNumber(record.cacheWrite) ?? 0,
+		cost: nonNegativeNumber(costValue) ?? 0,
+		turns: nonNegativeNumber(turnsValue) ?? 0,
+	};
+	return Number.isSafeInteger(usage.turns) ? usage : undefined;
+}
+
 function assistantUsageFromMessage(message: unknown): Usage | undefined {
 	if (!message || typeof message !== "object") return undefined;
 	const msg = message as { role?: unknown; usage?: unknown };
-	if (msg.role !== "assistant" || !msg.usage || typeof msg.usage !== "object") return undefined;
-	const usage = msg.usage as {
-		input?: unknown;
-		output?: unknown;
-		cacheRead?: unknown;
-		cacheWrite?: unknown;
-		cost?: { total?: unknown };
-	};
-	return {
-		input: typeof usage.input === "number" ? usage.input : 0,
-		output: typeof usage.output === "number" ? usage.output : 0,
-		cacheRead: typeof usage.cacheRead === "number" ? usage.cacheRead : 0,
-		cacheWrite: typeof usage.cacheWrite === "number" ? usage.cacheWrite : 0,
-		cost: typeof usage.cost?.total === "number" ? usage.cost.total : 0,
-		turns: 1,
-	};
+	return msg.role === "assistant" ? usageFromValue(msg.usage, 1) : undefined;
+}
+
+function compactionUsageFromEntry(entry: unknown): Usage | undefined {
+	if (!entry || typeof entry !== "object") return undefined;
+	const record = entry as { type?: unknown; usage?: unknown };
+	return record.type === "compaction" ? usageFromValue(record.usage, 0) : undefined;
+}
+
+const MAX_USAGE_METADATA_BYTES = 2 * 1024 * 1024;
+
+function readUsageMetadata(metadataPath: string): Record<string, unknown> | undefined {
+	let fd: number | undefined;
+	try {
+		fd = fs.openSync(metadataPath, "r");
+		const stat = fs.fstatSync(fd);
+		if (!stat.isFile() || stat.size > MAX_USAGE_METADATA_BYTES) return undefined;
+		const buffer = Buffer.allocUnsafe(stat.size);
+		let offset = 0;
+		while (offset < buffer.length) {
+			const bytesRead = fs.readSync(fd, buffer, offset, buffer.length - offset, null);
+			if (bytesRead <= 0) return undefined;
+			offset += bytesRead;
+		}
+		const value: unknown = JSON.parse(buffer.toString("utf-8"));
+		return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+	} finally {
+		if (fd !== undefined) fs.closeSync(fd);
+	}
 }
 
 function isSubagentDetails(value: unknown): value is Details {
@@ -382,10 +420,32 @@ function detailsFromSessionEntry(entry: unknown): Details | undefined {
 	}
 	if (record.type !== "message" || !record.message || typeof record.message !== "object") return undefined;
 	const message = record.message as { role?: unknown; toolName?: unknown; details?: unknown };
-	if (message.role !== "toolResult" || message.toolName !== "subagent") return undefined;
+	if (message.role !== "toolResult" || (message.toolName !== "subagent" && message.toolName !== "subagent_wait")) return undefined;
 	return isSubagentDetails(message.details) ? message.details : undefined;
 }
 
+function metadataUsage(
+	artifactsDirs: string[],
+	input: { runId: string; agent: string },
+): Usage | undefined {
+	if (!/^[A-Za-z0-9._-]+$/.test(input.runId)) return undefined;
+	for (const artifactsDir of artifactsDirs) {
+		for (const index of [0, undefined] as const) {
+			const metadataPath = getArtifactPaths(artifactsDir, input.runId, input.agent, index).metadataPath;
+			try {
+				const metadata = readUsageMetadata(metadataPath);
+				if (!metadata) continue;
+				if (metadata.runId !== input.runId || metadata.agent !== input.agent) continue;
+				const usage = usageFromValue(metadata.usage);
+				if (usage && usageHasValue(usage)) return usage;
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Failed to read subagent usage metadata '${metadataPath}':`, error);
+			}
+		}
+	}
+	return undefined;
+}
+
 function formatCostUsage(label: string, usage: Usage): string {
 	const extras = [
 		usage.cacheRead ? `cache read ${formatTokens(usage.cacheRead)}` : "",
@@ -395,28 +455,94 @@ function formatCostUsage(label: string, usage: Usage): string {
 	return `${label}: ↑${formatTokens(usage.input)} ↓${formatTokens(usage.output)} $${usage.cost.toFixed(4)}${extras.length ? ` (${extras.join(", ")})` : ""}`;
 }
 
-function buildSubagentCostReport(ctx: ExtensionContext): string {
+function buildSubagentCostReport(ctx: ExtensionContext, state: SubagentState): string {
 	const parent = emptyUsage();
 	const childTotal = emptyUsage();
 	const total = emptyUsage();
 	const children: Array<{ label: string; usage: Usage; sessionFile?: string }> = [];
+	const seenChildren = new Set<string>();
+	const workflowRunIds = new Set<string>();
+	let unresolvedAsyncChildren = 0;
+
+	const addChild = (input: { agent?: string; runId?: string; usage?: Usage; sessionFile?: string }): boolean => {
+		if (!input.usage || !usageHasValue(input.usage)) return false;
+		const identity = input.runId ? `run:${input.runId}` : input.sessionFile ? `session:${input.sessionFile}` : undefined;
+		if (identity && seenChildren.has(identity)) return true;
+		if (identity) seenChildren.add(identity);
+		const usage = { ...input.usage };
+		children.push({
+			label: `Child ${children.length + 1} (${input.agent ?? "unknown"})`,
+			usage,
+			...(input.sessionFile ? { sessionFile: input.sessionFile } : {}),
+		});
+		addUsage(childTotal, usage);
+		return true;
+	};
+
 	for (const entry of ctx.sessionManager.getBranch()) {
 		const message = entry.type === "message" ? (entry as { message?: unknown }).message : undefined;
-		const parentUsage = assistantUsageFromMessage(message);
+		const parentUsage = assistantUsageFromMessage(message) ?? compactionUsageFromEntry(entry);
 		if (parentUsage) addUsage(parent, parentUsage);
 		const details = detailsFromSessionEntry(entry);
 		if (!details) continue;
+		if (details.mode === "workflow" && details.runId) workflowRunIds.add(details.runId);
 		for (const result of details.results) {
-			if (!usageHasValue(result.usage)) continue;
-			const usage = { ...result.usage };
-			children.push({
-				label: `Child ${children.length + 1} (${result.agent})`,
-				usage,
-				...(result.sessionFile ? { sessionFile: result.sessionFile } : {}),
-			});
-			addUsage(childTotal, usage);
+			const resultRunId = (result as SingleResult & { runId?: unknown }).runId;
+			addChild({ agent: result.agent, runId: typeof resultRunId === "string" ? resultRunId : undefined, usage: usageFromValue(result.usage), sessionFile: result.sessionFile });
+		}
+		for (const completion of details.completions ?? []) {
+			if (completion.mode === "workflow") workflowRunIds.add(completion.runId);
+			for (const result of completion.results ?? []) {
+				addChild({ agent: result.agent, runId: result.runId, usage: usageFromValue(result.usage), sessionFile: result.sessionFile });
+			}
 		}
 	}
+
+	let sessionFile: string | null = null;
+	try {
+		sessionFile = ctx.sessionManager.getSessionFile() ?? null;
+	} catch { /* an unpersisted session can still report direct child usage */ }
+	const artifactsDirs = new Set<string>();
+	const addArtifactsDir = (cwd: string | undefined): void => {
+		try {
+			artifactsDirs.add(getArtifactsDir(sessionFile, cwd, state.artifactDirPreference));
+		} catch { /* invalid or unavailable project roots are ignored */ }
+	};
+	addArtifactsDir(ctx.cwd);
+	addArtifactsDir(state.baseCwd);
+
+	for (const workflowRunId of workflowRunIds) {
+		try {
+			const status = readStatus(path.join(DIRS.async, workflowRunId));
+			addArtifactsDir(status?.cwd);
+			const receipt = readWorkflowReceipt(DIRS.async, workflowRunId);
+			const summaryChildren = new Map((receipt.workflowChildren?.children ?? []).map((child) => [child.childId, child]));
+			const refsByRunId = new Map<string, { runId: string; agent: string }>();
+			const addRef = (runId: string | undefined, agent: string | undefined): void => {
+				if (!runId || !agent || refsByRunId.has(runId)) return;
+				refsByRunId.set(runId, { runId, agent });
+			};
+			for (const [key, entry] of Object.entries(receipt.entries)) {
+				const summaryChild = summaryChildren.get(key);
+				const runIds = entry.continuation?.runIds?.length
+					? entry.continuation.runIds
+					: entry.latestRunId ? [entry.latestRunId] : summaryChild?.runId ? [summaryChild.runId] : [];
+				for (const runId of runIds) addRef(runId, entry.agent ?? summaryChild?.agent);
+			}
+			for (const child of receipt.workflowChildren?.children ?? []) {
+				if (!Object.hasOwn(receipt.entries, child.childId)) addRef(child.runId, child.agent);
+			}
+			const refs = [...refsByRunId.values()];
+			for (const ref of refs) {
+				if (seenChildren.has(`run:${ref.runId}`)) continue;
+				const usage = metadataUsage([...artifactsDirs], ref);
+				if (!usage || !addChild({ ...ref, usage })) unresolvedAsyncChildren += 1;
+			}
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Failed to resolve async subagent usage for '${workflowRunId}':`, error);
+		}
+	}
+
 	addUsage(total, parent);
 	addUsage(total, childTotal);
 	const lines = [
@@ -432,6 +558,7 @@ function buildSubagentCostReport(ctx: ExtensionContext): string {
 			if (child.sessionFile) lines.push(`  Session: ${child.sessionFile}`);
 		}
 	}
+	if (unresolvedAsyncChildren > 0) lines.push(`Async child usage unavailable: ${unresolvedAsyncChildren}.`);
 	lines.push("────────────────────────────", formatCostUsage("Children", childTotal), formatCostUsage("Total", total));
 	return lines.join("\n");
 }
@@ -447,50 +574,76 @@ function getProfileWorkerModel(profile: { subagents?: { agentOverrides?: Record<
 	return typeof model === "string" && model.trim() ? model.trim() : undefined;
 }
 
+function isStaleExtensionContextError(error: unknown): boolean {
+	return error instanceof Error
+		&& (error.message.includes("This extension ctx is stale")
+			|| error.message.includes("Extension context no longer active"));
+}
+
+function slashHasUI(ctx: ExtensionContext): boolean | undefined {
+	try {
+		return ctx.hasUI;
+	} catch (error) {
+		if (isStaleExtensionContextError(error)) return undefined;
+		throw error;
+	}
+}
+
 
 async function requestSlashRun(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
 	requestId: string,
 	params: SubagentParamsLike,
+	signal?: AbortSignal,
 ): Promise<SlashSubagentResponse> {
 	return new Promise((resolve, reject) => {
 		let done = false;
 		let started = false;
-
-		const startTimeoutMs = 15_000;
-		const startTimeout = setTimeout(() => {
-			finish(() => reject(new Error(
-				"Slash subagent bridge did not start within 15s. Ensure the extension is loaded correctly.",
-			)));
-		}, startTimeoutMs);
+		let startTimeout: ReturnType<typeof setTimeout> | undefined;
 
 		const onStarted = (data: unknown) => {
-			if (done || !data || typeof data !== "object") return;
+			if (done || signal?.aborted || !data || typeof data !== "object") return;
 			if ((data as { requestId?: unknown }).requestId !== requestId) return;
 			started = true;
-			clearTimeout(startTimeout);
-			if (ctx.hasUI) ctx.ui.setStatus("subagent-slash", "running...");
+			if (startTimeout) clearTimeout(startTimeout);
+			try {
+				if (ctx.hasUI) ctx.ui.setStatus("subagent-slash", "running...");
+			} catch (error) {
+				if (isStaleExtensionContextError(error)) {
+					finish(() => reject(error));
+					return;
+				}
+				throw error;
+			}
 		};
 
 		const onResponse = (data: unknown) => {
-			if (done || !data || typeof data !== "object") return;
+			if (done || signal?.aborted || !data || typeof data !== "object") return;
 			const response = data as Partial<SlashSubagentResponse>;
 			if (response.requestId !== requestId) return;
-			clearTimeout(startTimeout);
+			if (startTimeout) clearTimeout(startTimeout);
 			finish(() => resolve(response as SlashSubagentResponse));
 		};
 
 		const onUpdate = (data: unknown) => {
-			if (done || !data || typeof data !== "object") return;
+			if (done || signal?.aborted || !data || typeof data !== "object") return;
 			const update = data as SlashSubagentUpdate;
 			if (update.requestId !== requestId) return;
 			applySlashUpdate(requestId, update);
-			if (!ctx.hasUI) return;
-			const tool = update.currentTool ? ` ${update.currentTool}` : "";
-			const count = update.toolCount ?? 0;
-			const liveDetailKey = keyText("app.tools.expand");
-			ctx.ui.setStatus("subagent-slash", `${count} tools${tool} | ${liveDetailKey} live detail`);
+			try {
+				if (!ctx.hasUI) return;
+				const tool = update.currentTool ? ` ${update.currentTool}` : "";
+				const count = update.toolCount ?? 0;
+				const liveDetailKey = keyText("app.tools.expand");
+				ctx.ui.setStatus("subagent-slash", `${count} tools${tool} | ${liveDetailKey} live detail`);
+			} catch (error) {
+				if (isStaleExtensionContextError(error)) {
+					finish(() => reject(error));
+					return;
+				}
+				throw error;
+			}
 		};
 
 		const onTerminalInput = ctx.hasUI
@@ -506,18 +659,43 @@ async function requestSlashRun(
 		const unsubResponse = pi.events.on(SLASH_SUBAGENT_RESPONSE_EVENT, onResponse);
 		const unsubUpdate = pi.events.on(SLASH_SUBAGENT_UPDATE_EVENT, onUpdate);
 
+		let onAbort: () => void;
 		const finish = (next: () => void) => {
 			if (done) return;
 			done = true;
-			clearTimeout(startTimeout);
+			if (startTimeout) clearTimeout(startTimeout);
 			unsubStarted();
 			unsubResponse();
 			unsubUpdate();
-			onTerminalInput?.();
+			try {
+				onTerminalInput?.();
+			} catch (error) {
+				if (!isStaleExtensionContextError(error)) throw error;
+			}
+			signal?.removeEventListener("abort", onAbort);
 			next();
 		};
+		onAbort = () => finish(() => reject(new Error("Slash subagent request canceled during session replacement or reload.")));
+		startTimeout = setTimeout(() => {
+			finish(() => reject(new Error(
+				"Slash subagent bridge did not start within 15s. Ensure the extension is loaded correctly.",
+			)));
+		}, 15_000);
 
-		pi.events.emit(SLASH_SUBAGENT_REQUEST_EVENT, { requestId, params, ctx });
+		if (signal?.aborted) {
+			onAbort();
+			return;
+		}
+		signal?.addEventListener("abort", onAbort, { once: true });
+		try {
+			pi.events.emit(SLASH_SUBAGENT_REQUEST_EVENT, { requestId, params, ctx });
+		} catch (error) {
+			if (isStaleExtensionContextError(error)) {
+				finish(() => reject(error));
+				return;
+			}
+			throw error;
+		}
 
 		// Bridge emits STARTED synchronously during REQUEST emit.
 		// If not started, no bridge received the request.
@@ -583,64 +761,76 @@ async function runSlashSubagent(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
 	params: SubagentParamsLike,
+	signal?: AbortSignal,
 ): Promise<void> {
-	if (ctx.hasUI) ctx.ui.setToolsExpanded(false);
+	if (signal?.aborted) return;
+	const initialHasUI = slashHasUI(ctx);
+	if (initialHasUI === undefined) return;
+	try {
+		if (initialHasUI) ctx.ui.setToolsExpanded(false);
+	} catch (error) {
+		if (isStaleExtensionContextError(error)) return;
+		throw error;
+	}
 	const requestId = randomUUID();
 	const initialDetails = buildSlashInitialResult(requestId, params);
 	const initialText = extractSlashMessageText(initialDetails.result.content) || "Running subagent...";
-	pi.sendMessage({
-		customType: SLASH_RESULT_TYPE,
-		content: initialText,
-		display: true,
-		details: initialDetails,
-	});
+	try {
+		pi.sendMessage({
+			customType: SLASH_RESULT_TYPE,
+			content: initialText,
+			display: true,
+			details: initialDetails,
+		});
+	} catch (error) {
+		if (isStaleExtensionContextError(error)) return;
+		throw error;
+	}
 	persistSlashSessionSnapshot(ctx);
 
 	try {
-		const response = await requestSlashRun(pi, ctx, requestId, params);
+		const response = await requestSlashRun(pi, ctx, requestId, params, signal);
+		if (signal?.aborted) return;
+		const hasUI = slashHasUI(ctx);
+		if (hasUI === undefined) return;
 		const finalDetails = finalizeSlashResult(response);
 		pi.sendMessage({
 			customType: SLASH_RESULT_TYPE,
 			content: buildSlashExportText(response),
-			display: !ctx.hasUI,
+			display: !hasUI,
 			details: finalDetails,
 		});
 		persistSlashSessionSnapshot(ctx);
-		if (ctx.hasUI) {
+		if (hasUI) {
 			ctx.ui.setStatus("subagent-slash", undefined);
 		}
-		if (response.isError && ctx.hasUI) {
+		if (response.isError && hasUI) {
 			ctx.ui.notify(response.errorText || "Subagent failed", "error");
 		}
 	} catch (error) {
+		if (signal?.aborted || isStaleExtensionContextError(error)) return;
 		const message = error instanceof Error ? error.message : String(error);
+		const hasUI = slashHasUI(ctx);
+		if (hasUI === undefined) return;
 		const failedDetails = failSlashResult(requestId, params, message);
 		pi.sendMessage({
 			customType: SLASH_RESULT_TYPE,
 			content: `## Subagent result\n\n${message}`,
-			display: !ctx.hasUI,
+			display: !hasUI,
 			details: failedDetails,
 		});
 		persistSlashSessionSnapshot(ctx);
-		if (ctx.hasUI) {
+		if (hasUI) {
 			ctx.ui.setStatus("subagent-slash", undefined);
 		}
 		if (message === "Cancelled") {
-			if (ctx.hasUI) ctx.ui.notify("Cancelled", "warning");
+			if (hasUI) ctx.ui.notify("Cancelled", "warning");
 			return;
 		}
-		if (ctx.hasUI) ctx.ui.notify(message, "error");
+		if (hasUI) ctx.ui.notify(message, "error");
 	}
 }
 
-function launchSlashSubagent(
-	pi: ExtensionAPI,
-	ctx: ExtensionContext,
-	params: SubagentParamsLike,
-): void {
-	void runSlashSubagent(pi, ctx, params);
-}
-
 function slashRunWorkflowScript(key: string, child: Record<string, unknown>): string {
 	return `return runs.run(${JSON.stringify(key)}, ${JSON.stringify(child)})`;
 }
@@ -649,12 +839,23 @@ export function registerSlashCommands(
 	pi: ExtensionAPI,
 	state: SubagentState,
 	options: { fleetKeybindings?: FleetKeybindingsConfig; foregroundDetachShortcut?: string } = {},
-): void {
+): { dispose: () => void } {
 	let fleetOpen = false;
+	let disposed = false;
+	const pendingRequests = new Set<AbortController>();
+	const runCommand = (ctx: ExtensionContext, params: SubagentParamsLike): Promise<void> => {
+		if (disposed) return Promise.resolve();
+		const controller = new AbortController();
+		pendingRequests.add(controller);
+		return runSlashSubagent(pi, ctx, params, controller.signal).finally(() => pendingRequests.delete(controller));
+	};
+	const launchCommand = (ctx: ExtensionContext, params: SubagentParamsLike): void => {
+		void runCommand(ctx, params);
+	};
 	const showFleet = async (ctx: ExtensionContext) => {
 		state.lastUiContext = ctx;
 		if (!ctx.hasUI) {
-			await runSlashSubagent(pi, ctx, { action: "status", view: "fleet" });
+			await runCommand(ctx, { action: "status", view: "fleet" });
 			return;
 		}
 		if (fleetOpen) {
@@ -710,21 +911,21 @@ export function registerSlashCommands(
 			if (inline.skill !== undefined) child.skill = inline.skill;
 			if (inline.model) child.model = inline.model;
 			if (fork) child.context = "fork";
-			launchSlashSubagent(pi, ctx, { workflowScript: slashRunWorkflowScript("run", child), async: bg ? true : false });
+			launchCommand(ctx, { workflowScript: slashRunWorkflowScript("run", child), async: bg ? true : false });
 		},
 	});
 
 	pi.registerCommand("subagent-cost", {
 		description: "Show parent and subagent child usage cost for this session",
 		handler: async (_args, ctx) => {
-			sendSlashText(pi, buildSubagentCostReport(ctx));
+			sendSlashText(pi, buildSubagentCostReport(ctx, state));
 		},
 	});
 
 	pi.registerCommand("subagents-doctor", {
 		description: "Show subagent diagnostics",
 		handler: async (_args, ctx) => {
-			await runSlashSubagent(pi, ctx, { action: "doctor" });
+			await runCommand(ctx, { action: "doctor" });
 		},
 	});
 
@@ -756,7 +957,7 @@ export function registerSlashCommands(
 				ctx.ui.notify("Usage: /subagents-guide [topic]", "error");
 				return;
 			}
-			await runSlashSubagent(pi, ctx, { action: "guide", ...(topic ? { topic } : {}) });
+			await runCommand(ctx, { action: "guide", ...(topic ? { topic } : {}) });
 		},
 	});
 
@@ -769,7 +970,7 @@ export function registerSlashCommands(
 				ctx.ui.notify("Usage: /subagents-refine <agent>", "error");
 				return;
 			}
-			await runSlashSubagent(pi, ctx, { action: "refine", agent: parts[0] });
+			await runCommand(ctx, { action: "refine", agent: parts[0] });
 		},
 	});
 
@@ -820,11 +1021,15 @@ export function registerSlashCommands(
 	}
 
 	pi.registerCommand("subagents-stop", {
-		description: "Stop a current-session async subagent run",
+		description: "Stop a current-session async subagent run, or one child of it with /subagents-stop <run-id> <child-id>",
 		handler: async (args, ctx) => {
-			const id = args.trim();
+			const [id, childId, ...extra] = args.trim().split(/\s+/).filter(Boolean);
+			if (extra.length > 0) {
+				sendSlashText(pi, "Usage: /subagents-stop [run-id] [child-id]");
+				return;
+			}
 			if (id) {
-				await runSlashSubagent(pi, ctx, { action: "stop", id });
+				await runCommand(ctx, childId ? { action: "stop", id, childId } : { action: "stop", id });
 				return;
 			}
 
@@ -856,27 +1061,91 @@ export function registerSlashCommands(
 			);
 			if (!result?.confirmed || !result.target) return;
 			if (result.target.kind === "scheduled") {
-				await runSlashSubagent(pi, ctx, { action: "schedule.pause", id: result.target.id });
+				await runCommand(ctx, { action: "schedule.pause", id: result.target.id });
 				return;
 			}
-			await runSlashSubagent(pi, ctx, { action: "stop", id: result.target.id });
+			await runCommand(ctx, { action: "stop", id: result.target.id });
+		},
+	});
+
+	pi.registerCommand("subagents-steer", {
+		description: "Steer a live async subagent run with a message, or one child of it with --child <child-id>",
+		handler: async (args, ctx) => {
+			const tokens = args.trim().split(/\s+/).filter(Boolean);
+			const usage = "Usage: /subagents-steer <run-id> [--child <child-id>] <message>";
+			const [id, ...rest] = tokens;
+			if (!id || id.startsWith("--")) {
+				sendSlashText(pi, usage);
+				return;
+			}
+			// Only the optional child selector is parsed as a flag. Everything
+			// after the run id (or selector) is free-form message text, including
+			// a leading token such as `--verbose`.
+			let childId: string | undefined;
+			let messageStart = 0;
+			if (rest[0] === "--child" && rest[1] && !rest[1].startsWith("--")) {
+				childId = rest[1];
+				messageStart = 2;
+			}
+			const message = rest.slice(messageStart).join(" ").trim();
+			if (!message) {
+				sendSlashText(pi, usage);
+				return;
+			}
+			let targetId = id;
+			let childIndex: number | undefined;
+			if (childId !== undefined) {
+				const sessionId = state.currentSessionId ?? ctx.sessionManager.getSessionId() ?? undefined;
+				const run = listAsyncRuns(DIRS.async, {
+					runId: id,
+					states: ["queued", "running", "paused"],
+					...(sessionId ? { sessionId } : {}),
+				})[0];
+				const status = run ? readStatus(run.asyncDir) : null;
+				if (!run || !status) {
+					sendSlashText(pi, `No current-session async run found for '${id}'.`);
+					return;
+				}
+				const resolutionStatus = {
+					...status,
+					steps: status.steps?.map((step, index) => ({ ...step, children: run.steps[index]?.children ?? step.children })),
+				};
+				const resolution = resolveAsyncStatusChild(resolutionStatus, childId, { includeNested: true });
+				if (!resolution.ok) {
+					sendSlashText(pi, resolution.message);
+					return;
+				}
+				if (resolution.child.nested) targetId = resolution.child.nested.id;
+				else if (resolution.child.step.runId) targetId = resolution.child.step.runId;
+				else childIndex = resolution.child.index;
+			}
+			await runCommand(ctx, {
+				action: "steer",
+				id: targetId,
+				message,
+				...(childIndex !== undefined ? { index: childIndex } : {}),
+				// Host-style exact-child authority, matching the extension RPC
+				// nonRecoveringSteer guarantee: never swap the addressed child for
+				// a pause-and-revive replacement after a missed acknowledgment.
+				steeringRecovery: false,
+			});
 		},
 	});
 
 	registerPromptWorkflowCommands({
 		pi,
 		run: async (params, ctx) => {
-			launchSlashSubagent(pi, ctx, params);
+			launchCommand(ctx, params);
 		},
 	});
 
 	pi.registerCommand("subagents-models", {
 		description: "Show runtime-loaded builtin subagent models",
 		getArgumentCompletions: makeBuiltinAgentNameCompletions(),
-		handler: async (args, ctx) => {
-			const trimmed = args.trim();
-			if (!trimmed) {
-				await runSlashSubagent(pi, ctx, { action: "models" });
+			handler: async (args, ctx) => {
+				const trimmed = args.trim();
+				if (!trimmed) {
+					await runCommand(ctx, { action: "models" });
 				return;
 			}
 			const parts = trimmed.split(/\s+/).filter(Boolean);
@@ -889,7 +1158,7 @@ export function registerSlashCommands(
 				ctx.ui.notify(`Unknown builtin agent: ${agent}`, "error");
 				return;
 			}
-			await runSlashSubagent(pi, ctx, { action: "models", agent });
+			await runCommand(ctx, { action: "models", agent });
 		},
 	});
 
@@ -1062,4 +1331,14 @@ export function registerSlashCommands(
 		},
 	});
 
+	return {
+		dispose: () => {
+			if (disposed) return;
+			disposed = true;
+			// A reload revokes the command context; do not let delayed responses
+			// resume a command against the old Pi context.
+			for (const controller of pendingRequests) controller.abort();
+			pendingRequests.clear();
+		},
+	};
 }