pi-subagents 0.31.1 → 0.33.0

package/src/extension/index.ts

@@ -12,30 +12,36 @@
  *   { "asyncByDefault": true, "forceTopLevelAsync": true, "maxSubagentDepth": 1, "intercomBridge": { "mode": "always", "instructionFile": "./intercom-bridge.md" }, "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
  */
 
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import { type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { keyText, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
 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 } from "./schemas.ts";
+import { SubagentParams, WaitParams } from "./schemas.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 { 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 { waitForSubagents } from "../runs/background/wait.ts";
 import registerSubagentNotify, { type SubagentNotifyDetails } from "../runs/background/notify.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";
+import { buildSubagentToolDescription } from "./tool-description.ts";
 import {
 	type Details,
 	type SubagentState,
@@ -259,6 +265,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		baseCwd: "",
 		currentSessionId: null,
 		subagentInProgress: false,
+		subagentSpawns: { sessionId: null, count: 0 },
 		asyncJobs: new Map(),
 		foregroundRuns: new Map(),
 		foregroundControls: new Map(),
@@ -276,6 +283,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		},
 	};
 
+	const supervisorChannel = createNativeSupervisorChannel(pi, state);
 	const { startResultWatcher, primeExistingResults, stopResultWatcher } = createResultWatcher(
 		pi,
 		state,
@@ -287,6 +295,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 
 	const runtimeCleanup = () => {
 		stopResultWatcher();
+		scheduledRunManager.stop();
+		supervisorChannel.dispose();
 		clearPendingForegroundControlNotices(state);
 		if (state.poller) {
 			clearInterval(state.poller);
@@ -295,17 +305,33 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	};
 	globalStore[runtimeCleanupStoreKey] = runtimeCleanup;
 
-	const { ensurePoller, handleStarted, handleComplete, resetJobs } = createAsyncJobTracker(pi, state, ASYNC_DIR);
+	const { ensurePoller, handleStarted, handleComplete, resetJobs, restoreActiveJobs } = createAsyncJobTracker(pi, state, ASYNC_DIR);
+	let executorExecute: ((id: string, params: SubagentParamsLike, signal: AbortSignal, onUpdate: ((r: AgentToolResult<Details>) => void) | undefined, ctx: ExtensionContext) => Promise<AgentToolResult<Details>>) | undefined;
+	const scheduledRunManager = createScheduledRunManager({
+		config,
+		launch: (params, ctx, signal) => {
+			if (!executorExecute) {
+				return Promise.resolve({
+					content: [{ type: "text", text: "Scheduled subagent launch is unavailable (executor not ready)." }],
+					isError: true,
+					details: { mode: "management" as const, results: [] },
+				});
+			}
+			return executorExecute(randomUUID(), params, signal, undefined, ctx);
+		},
+	});
 	const executor = createSubagentExecutor({
 		pi,
 		state,
 		config,
 		asyncByDefault,
+		handleScheduledRunAction: (params, ctx) => scheduledRunManager.handleToolCall(params, ctx),
 		tempArtifactsDir,
 		getSubagentSessionRoot,
 		expandTilde,
 		discoverAgents,
 	});
+	executorExecute = executor.execute;
 
 	pi.registerMessageRenderer<SlashMessageDetails>(SLASH_RESULT_TYPE, (message, options, theme) => {
 		const details = resolveSlashMessageDetails(message.details);
@@ -345,7 +371,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			text += `\n  ${theme.fg("dim", `⎿  ${line}`)}`;
 		}
 		if (!options.expanded && trimmedPreview.includes("\n")) {
-			text += `\n  ${theme.fg("dim", "Ctrl+O full notification")}`;
+			const expandKey = keyText("app.tools.expand");
+			text += `\n  ${theme.fg("dim", `${expandKey} full notification`)}`;
 		}
 		if (details.sessionLabel && details.sessionValue) {
 			text += `\n  ${theme.fg("muted", `${details.sessionLabel}: ${shortenPath(details.sessionValue)}`)}`;
@@ -410,6 +437,12 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		},
 	});
 
+	const rpcBridge = registerSubagentRpcBridge({
+		events: pi.events,
+		getContext: () => state.lastUiContext,
+		execute: (id, params, signal, onUpdate, ctx) => executor.execute(id, params, signal, onUpdate, ctx),
+	});
+
 	function effectiveParallelTaskCount(tasks: Array<{ count?: unknown }> | undefined): number {
 		if (!tasks || tasks.length === 0) return 0;
 		return tasks.reduce((total, task) => {
@@ -421,40 +454,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const tool: ToolDefinition<typeof SubagentParams, Details> = {
 		name: "subagent",
 		label: "Subagent",
-		description: `Delegate to subagents or manage agent definitions.
-
-EXECUTION (use exactly ONE mode):
-• Before executing, use { action: "list" } to inspect configured agents/chains. Only execute agents listed as executable/non-disabled.
-• SINGLE: { agent, task? } - one task; omit task for self-contained agents
-• CHAIN: { chain: [{agent:"agent-a"}, {parallel:[{agent:"agent-b",count:3}]}] } - sequential pipeline with optional parallel fan-out
-• PARALLEL: { tasks: [{agent,task,count?,output?,reads?,progress?}, ...], concurrency?: number, worktree?: true } - concurrent execution (worktree: isolate each task in a git worktree)
-• Optional context: { context: "fresh" | "fork" } (explicit value overrides every child; when omitted, each requested agent uses its own defaultContext, otherwise "fresh"; inspect agent defaults via { action: "list" })
-• If { action: "list" } shows proactive skill subagent suggestions, consider a small fresh-context fanout for broad tasks where one of those skills would materially help
-
-CHAIN TEMPLATE VARIABLES (use in task strings):
-• {task} - The original task/request from the user
-• {previous} - Text response from the previous step (empty for first step)
-• {chain_dir} - Shared directory for chain files (e.g., <tmpdir>/pi-subagents-<scope>/chain-runs/abc123/)
-
-Example: { chain: [{agent:"agent-a", task:"Analyze {task}"}, {agent:"agent-b", task:"Plan based on {previous}"}] }
-
-MANAGEMENT (use action field, omit agent/task/chain/tasks):
-• { action: "list" } - discover executable agents/chains
-• { action: "get", agent: "name" } - full detail; packaged agents use dotted runtime names like "package.agent"
-• { action: "models", agent?: "name" } - show the runtime-loaded builtin subagent model mapping, optionally filtered to one builtin
-• { action: "create", config: { name: "custom-agent", package: "code-analysis", systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext, ... } }
-• { action: "update", agent: "code-analysis.custom-agent", config: { package: "analysis", ... } } - merge
-• { action: "delete", agent: "code-analysis.custom-agent" }
-• Use chainName for chain operations; packaged chains also use dotted runtime names
-
-CONTROL:
-• { action: "status", id: "..." } - inspect an async/background run by id or prefix
-• { action: "interrupt", id?: "..." } - soft-interrupt the current child turn and leave the run paused
-• { action: "resume", id: "...", message: "...", index?: 0 } - interrupt then follow up with a live async child, or revive a completed async/foreground child from its session
-• { action: "append-step", id: "...", chain: [{agent:"agent-c", task:"Use {previous}"}] } - append one step to the tail of a running async chain
-
-DIAGNOSTICS:
-• { action: "doctor" } - read-only report for runtime paths, discovery, sessions, and intercom`,
+		description: buildSubagentToolDescription(config),
 		parameters: SubagentParams,
 
 		execute(id, params, signal, onUpdate, ctx) {
@@ -471,7 +471,7 @@ DIAGNOSTICS:
 			}
 			const isParallel = (args.tasks?.length ?? 0) > 0;
 			const parallelCount = effectiveParallelTaskCount(args.tasks as Array<{ count?: unknown }> | undefined);
-			const asyncLabel = args.async === true && args.clarify !== true && !isParallel ? theme.fg("warning", " [async]") : "";
+			const asyncLabel = args.async === true && args.clarify !== true ? theme.fg("warning", " [async]") : "";
 			if (args.chain?.length)
 				return new Text(
 					`${theme.fg("toolTitle", theme.bold("subagent "))}chain (${args.chain.length})${asyncLabel}`,
@@ -480,7 +480,7 @@ DIAGNOSTICS:
 				);
 			if (isParallel)
 				return new Text(
-					`${theme.fg("toolTitle", theme.bold("subagent "))}parallel (${parallelCount})`,
+					`${theme.fg("toolTitle", theme.bold("subagent "))}parallel (${parallelCount})${asyncLabel}`,
 					0,
 					0,
 				);
@@ -504,6 +504,27 @@ DIAGNOSTICS:
 	};
 
 	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)
+
+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.`,
+		parameters: WaitParams,
+		execute(_id, params, signal, _onUpdate, _ctx) {
+			return waitForSubagents(params, signal, { state, events: pi.events });
+		},
+	};
+	pi.registerTool(waitTool);
+
 	registerSlashCommands(pi, state);
 
 	const eventUnsubscribeStoreKey = "__piSubagentEventUnsubscribes";
@@ -519,7 +540,7 @@ DIAGNOSTICS:
 			}
 		}
 	}
-	registerSubagentNotify(pi);
+	registerSubagentNotify(pi, state, { batchConfig: config.completionBatch });
 
 	const existingVisibleControlNotices = globalStore[controlNoticeSeenStoreKey];
 	const visibleControlNotices = existingVisibleControlNotices instanceof Set ? existingVisibleControlNotices as Set<string> : new Set<string>();
@@ -536,6 +557,7 @@ DIAGNOSTICS:
 		pi.events.on(SUBAGENT_ASYNC_STARTED_EVENT, handleStarted),
 		pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, handleComplete),
 		pi.events.on(SUBAGENT_CONTROL_EVENT, controlEventHandler),
+		rpcBridge.dispose,
 	];
 	globalStore[eventUnsubscribeStoreKey] = eventUnsubscribes;
 
@@ -564,6 +586,7 @@ DIAGNOSTICS:
 	const resetSessionState = (ctx: ExtensionContext) => {
 		state.baseCwd = ctx.cwd;
 		state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
+		state.subagentSpawns = { sessionId: state.currentSessionId, count: 0 };
 		// 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
@@ -579,12 +602,16 @@ DIAGNOSTICS:
 		cleanupSessionArtifacts(ctx);
 		clearPendingForegroundControlNotices(state);
 		resetJobs(ctx);
+		restoreActiveJobs(ctx);
+		scheduledRunManager.bindSession(ctx);
 		restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
 		primeExistingResults();
 	};
 
 	pi.on("session_start", (_event, ctx) => {
 		resetSessionState(ctx);
+		rpcBridge.emitReady(ctx);
+		supervisorChannel.start();
 	});
 
 	pi.on("session_shutdown", () => {
@@ -600,6 +627,7 @@ DIAGNOSTICS:
 			delete globalStore[eventUnsubscribeStoreKey];
 		}
 		stopResultWatcher();
+		scheduledRunManager.stop();
 		if (state.poller) clearInterval(state.poller);
 		state.poller = null;
 		clearPendingForegroundControlNotices(state);
@@ -613,6 +641,7 @@ DIAGNOSTICS:
 		slashBridge.dispose();
 		promptTemplateBridge.cancelAll();
 		promptTemplateBridge.dispose();
+		supervisorChannel.dispose();
 		if (globalStore[runtimeCleanupStoreKey] === runtimeCleanup) {
 			delete globalStore[runtimeCleanupStoreKey];
 		}

package/src/extension/rpc.ts

@@ -0,0 +1,369 @@
+import * as path from "node:path";
+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 { 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";
+
+export const SUBAGENT_RPC_PROTOCOL_VERSION = 1;
+export const SUBAGENT_RPC_REQUEST_EVENT = "subagents:rpc:v1:request";
+export const SUBAGENT_RPC_READY_EVENT = "subagents:rpc:v1:ready";
+export const SUBAGENT_RPC_REPLY_EVENT_PREFIX = "subagents:rpc:v1:reply:";
+
+export const SUBAGENT_RPC_METHODS = ["ping", "status", "spawn", "interrupt", "stop"] as const;
+export type SubagentRpcMethod = typeof SUBAGENT_RPC_METHODS[number];
+
+export interface SubagentRpcRequestEnvelope {
+	version: typeof SUBAGENT_RPC_PROTOCOL_VERSION;
+	requestId: string;
+	method: SubagentRpcMethod;
+	params?: unknown;
+	source?: {
+		extension?: string;
+		[key: string]: unknown;
+	};
+}
+
+export type SubagentRpcReplyEnvelope<T = unknown> = {
+	version: typeof SUBAGENT_RPC_PROTOCOL_VERSION;
+	requestId: string;
+	method?: SubagentRpcMethod;
+	success: true;
+	data: T;
+} | {
+	version: typeof SUBAGENT_RPC_PROTOCOL_VERSION;
+	requestId: string;
+	method?: SubagentRpcMethod;
+	success: false;
+	error: {
+		code: SubagentRpcErrorCode;
+		message: string;
+	};
+};
+
+type SubagentRpcErrorCode =
+	| "invalid_request"
+	| "invalid_params"
+	| "unsupported_version"
+	| "unsupported_method"
+	| "no_active_session"
+	| "execution_failed"
+	| "not_found"
+	| "invalid_state";
+
+interface EventBus {
+	on(event: string, handler: (data: unknown) => void): (() => void) | void;
+	emit(event: string, data: unknown): void;
+}
+
+interface RegisterSubagentRpcBridgeOptions {
+	events: EventBus;
+	getContext: () => ExtensionContext | null;
+	execute: (
+		id: string,
+		params: SubagentParamsLike,
+		signal: AbortSignal,
+		onUpdate: ((result: AgentToolResult<Details>) => void) | undefined,
+		ctx: ExtensionContext,
+	) => Promise<AgentToolResult<Details>>;
+	asyncDirRoot?: string;
+	resultsDir?: string;
+	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+	now?: () => number;
+}
+
+class SubagentRpcError extends Error {
+	readonly code: SubagentRpcErrorCode;
+
+	constructor(code: SubagentRpcErrorCode, message: string) {
+		super(message);
+		this.name = "SubagentRpcError";
+		this.code = code;
+	}
+}
+
+const subagentParamsValidator = Compile(SubagentParams);
+
+export function subagentRpcReplyEvent(requestId: string): string {
+	return `${SUBAGENT_RPC_REPLY_EVENT_PREFIX}${requestId}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function assertRequestId(value: unknown): string {
+	if (typeof value !== "string" || value.trim().length === 0 || /[\r\n]/.test(value)) {
+		throw new SubagentRpcError("invalid_request", "RPC requestId must be a non-empty string without newlines.");
+	}
+	return value;
+}
+
+function assertRecordParams(params: unknown, method: SubagentRpcMethod): Record<string, unknown> {
+	if (params === undefined) return {};
+	if (!isRecord(params)) throw new SubagentRpcError("invalid_params", `RPC ${method} params must be an object.`);
+	return params;
+}
+
+function assertSubagentParams(params: SubagentParamsLike, label: string): void {
+	if (subagentParamsValidator.Check(params)) return;
+	const messages = [...subagentParamsValidator.Errors(params)]
+		.slice(0, 4)
+		.map((error) => error.message);
+	throw new SubagentRpcError("invalid_params", `${label}: ${messages.join("; ") || "invalid subagent parameters"}`);
+}
+
+function textFromToolResult(result: AgentToolResult<Details>): string {
+	return result.content
+		.filter((part): part is { type: "text"; text: string } => part.type === "text")
+		.map((part) => part.text)
+		.join("\n");
+}
+
+function dataFromToolResult(result: AgentToolResult<Details>): { text: string; details?: Details; isError?: boolean } {
+	return {
+		text: textFromToolResult(result),
+		...(result.details ? { details: result.details } : {}),
+		...(result.isError ? { isError: true } : {}),
+	};
+}
+
+function failIfToolError(result: AgentToolResult<Details>): void {
+	if (!result.isError) return;
+	throw new SubagentRpcError("execution_failed", textFromToolResult(result) || "Subagent RPC execution failed.");
+}
+
+function normalizeTargetParams(params: unknown, method: SubagentRpcMethod): Pick<SubagentParamsLike, "id" | "runId" | "dir" | "index"> {
+	const input = assertRecordParams(params, method);
+	const output: Pick<SubagentParamsLike, "id" | "runId" | "dir" | "index"> = {};
+	if (input.id !== undefined) output.id = input.id as string;
+	if (input.runId !== undefined) output.runId = input.runId as string;
+	if (input.dir !== undefined) output.dir = input.dir as string;
+	if (input.index !== undefined) output.index = input.index as number;
+	return output;
+}
+
+function sessionData(ctx: ExtensionContext | null): { cwd?: string; sessionId?: string; sessionFile?: string | null } {
+	if (!ctx) return {};
+	return {
+		cwd: ctx.cwd,
+		sessionId: ctx.sessionManager.getSessionId() ?? undefined,
+		sessionFile: ctx.sessionManager.getSessionFile() ?? null,
+	};
+}
+
+function pingData(ctx: ExtensionContext | null) {
+	return {
+		version: SUBAGENT_RPC_PROTOCOL_VERSION,
+		methods: [...SUBAGENT_RPC_METHODS],
+		capabilities: {
+			status: true,
+			asyncSpawn: true,
+			interrupt: true,
+			stop: true,
+		},
+		events: {
+			ready: SUBAGENT_RPC_READY_EVENT,
+			request: SUBAGENT_RPC_REQUEST_EVENT,
+			replyPrefix: SUBAGENT_RPC_REPLY_EVENT_PREFIX,
+		},
+		session: sessionData(ctx),
+	};
+}
+
+async function executeChecked(
+	options: RegisterSubagentRpcBridgeOptions,
+	ctx: ExtensionContext,
+	requestId: string,
+	method: SubagentRpcMethod,
+	params: SubagentParamsLike,
+): Promise<{ text: string; details?: Details; isError?: boolean }> {
+	assertSubagentParams(params, `RPC ${method} params`);
+	const controller = new AbortController();
+	const result = await options.execute(`rpc-${method}-${requestId}`, params, controller.signal, undefined, ctx);
+	failIfToolError(result);
+	return dataFromToolResult(result);
+}
+
+function spawnParams(params: unknown): SubagentParamsLike {
+	const input = assertRecordParams(params, "spawn");
+	if (input.action !== undefined) {
+		throw new SubagentRpcError("invalid_params", "RPC spawn does not accept management/control actions. Use status or interrupt RPC methods instead.");
+	}
+	if (input.async === false) {
+		throw new SubagentRpcError("invalid_params", "RPC spawn only supports detached async launches; omit async or set async: true.");
+	}
+	if (input.clarify === true) {
+		throw new SubagentRpcError("invalid_params", "RPC spawn cannot open the clarify UI; omit clarify or set clarify: false.");
+	}
+	return { ...(input as SubagentParamsLike), async: true, clarify: false };
+}
+
+function stopAsyncRun(
+	params: unknown,
+	options: RegisterSubagentRpcBridgeOptions,
+	ctx: ExtensionContext,
+): { runId: string; asyncDir: string; previousState: string; state: "stopping"; message: string } {
+	const target = normalizeTargetParams(params, "stop");
+	assertSubagentParams({ action: "status", ...target }, "RPC stop target params");
+	const asyncDirRoot = options.asyncDirRoot ?? ASYNC_DIR;
+	const resultsDir = options.resultsDir ?? RESULTS_DIR;
+	let location;
+	try {
+		location = resolveAsyncRunLocation(target, asyncDirRoot, resultsDir);
+	} catch (error) {
+		throw new SubagentRpcError("invalid_params", error instanceof Error ? error.message : String(error));
+	}
+	if (!location.asyncDir) {
+		throw new SubagentRpcError("not_found", "Async run not found or already completed; stop requires a live async run directory.");
+	}
+
+	const currentSessionId = ctx.sessionManager.getSessionId();
+	const initialStatus = readStatus(location.asyncDir);
+	const initialRunId = initialStatus?.runId ?? location.resolvedId ?? path.basename(location.asyncDir);
+	if (!initialStatus) throw new SubagentRpcError("not_found", `Status file not found for async run '${initialRunId}'.`);
+	if (!currentSessionId || initialStatus.sessionId !== currentSessionId) {
+		throw new SubagentRpcError("not_found", `Async run '${initialRunId}' was not found in the active session.`);
+	}
+
+	let status;
+	try {
+		status = reconcileAsyncRun(location.asyncDir, { resultsDir, kill: options.kill, now: options.now }).status;
+	} catch (error) {
+		throw new SubagentRpcError("execution_failed", error instanceof Error ? error.message : String(error));
+	}
+	const runId = status?.runId ?? initialRunId;
+	if (!status) throw new SubagentRpcError("not_found", `Status file not found for async run '${runId}'.`);
+	if (status.sessionId !== currentSessionId) {
+		throw new SubagentRpcError("not_found", `Async run '${runId}' was not found in the active session.`);
+	}
+	if (status.state !== "running") {
+		throw new SubagentRpcError("invalid_state", `Async run ${runId} is ${status.state}; stop only supports running async runs.`);
+	}
+
+	try {
+		deliverTimeoutRequest({
+			asyncDir: location.asyncDir,
+			pid: status.pid,
+			kill: options.kill,
+			now: options.now,
+			source: "rpc-stop",
+		});
+	} catch (error) {
+		throw new SubagentRpcError("execution_failed", error instanceof Error ? error.message : String(error));
+	}
+
+	return {
+		runId,
+		asyncDir: location.asyncDir,
+		previousState: status.state,
+		state: "stopping",
+		message: `Stop requested for async run ${runId}.`,
+	};
+}
+
+async function handleRequest(
+	request: SubagentRpcRequestEnvelope,
+	options: RegisterSubagentRpcBridgeOptions,
+): Promise<unknown> {
+	const ctx = options.getContext();
+	if (request.method === "ping") return pingData(ctx);
+	if (!ctx) throw new SubagentRpcError("no_active_session", "No active extension context for subagent RPC.");
+
+	if (request.method === "spawn") {
+		return executeChecked(options, ctx, request.requestId, request.method, spawnParams(request.params));
+	}
+	if (request.method === "status") {
+		return executeChecked(options, ctx, request.requestId, request.method, { action: "status", ...normalizeTargetParams(request.params, "status") });
+	}
+	if (request.method === "interrupt") {
+		return executeChecked(options, ctx, request.requestId, request.method, { action: "interrupt", ...normalizeTargetParams(request.params, "interrupt") });
+	}
+	if (request.method === "stop") {
+		return stopAsyncRun(request.params, options, ctx);
+	}
+	throw new SubagentRpcError("unsupported_method", `Unsupported subagent RPC method: ${String(request.method)}`);
+}
+
+function parseRequest(raw: unknown): SubagentRpcRequestEnvelope {
+	if (!isRecord(raw)) throw new SubagentRpcError("invalid_request", "Subagent RPC request must be an object.");
+	const requestId = assertRequestId(raw.requestId);
+	if (raw.version !== SUBAGENT_RPC_PROTOCOL_VERSION) {
+		throw new SubagentRpcError("unsupported_version", `Unsupported subagent RPC version: ${String(raw.version)}.`);
+	}
+	if (typeof raw.method !== "string" || !(SUBAGENT_RPC_METHODS as readonly string[]).includes(raw.method)) {
+		throw new SubagentRpcError("unsupported_method", `Unsupported subagent RPC method: ${String(raw.method)}.`);
+	}
+	return {
+		version: SUBAGENT_RPC_PROTOCOL_VERSION,
+		requestId,
+		method: raw.method as SubagentRpcMethod,
+		...(raw.params !== undefined ? { params: raw.params } : {}),
+		...(isRecord(raw.source) ? { source: raw.source as SubagentRpcRequestEnvelope["source"] } : {}),
+	};
+}
+
+function safeReplyRequestId(raw: unknown): string {
+	if (!isRecord(raw)) return "unknown";
+	const requestId = raw.requestId;
+	return typeof requestId === "string" && requestId.trim().length > 0 && !/[\r\n]/.test(requestId)
+		? requestId
+		: "unknown";
+}
+
+function errorReply(raw: unknown, error: unknown): SubagentRpcReplyEnvelope {
+	const requestId = safeReplyRequestId(raw);
+	const method = isRecord(raw) && typeof raw.method === "string" && (SUBAGENT_RPC_METHODS as readonly string[]).includes(raw.method)
+		? raw.method as SubagentRpcMethod
+		: undefined;
+	const rpcError = error instanceof SubagentRpcError
+		? error
+		: new SubagentRpcError("execution_failed", error instanceof Error ? error.message : String(error));
+	return {
+		version: SUBAGENT_RPC_PROTOCOL_VERSION,
+		requestId,
+		...(method ? { method } : {}),
+		success: false,
+		error: {
+			code: rpcError.code,
+			message: rpcError.message,
+		},
+	};
+}
+
+export function registerSubagentRpcBridge(options: RegisterSubagentRpcBridgeOptions): {
+	emitReady: (ctx?: ExtensionContext | null) => void;
+	dispose: () => void;
+} {
+	const unsubscribe = options.events.on(SUBAGENT_RPC_REQUEST_EVENT, async (raw) => {
+		let request: SubagentRpcRequestEnvelope | undefined;
+		try {
+			request = parseRequest(raw);
+			const data = await handleRequest(request, options);
+			options.events.emit(subagentRpcReplyEvent(request.requestId), {
+				version: SUBAGENT_RPC_PROTOCOL_VERSION,
+				requestId: request.requestId,
+				method: request.method,
+				success: true,
+				data,
+			} satisfies SubagentRpcReplyEnvelope);
+		} catch (error) {
+			const reply = errorReply(request ?? raw, error);
+			options.events.emit(subagentRpcReplyEvent(reply.requestId), reply);
+		}
+	});
+
+	return {
+		emitReady: (ctx) => {
+			options.events.emit(SUBAGENT_RPC_READY_EVENT, pingData(ctx ?? options.getContext()));
+		},
+		dispose: () => {
+			if (typeof unsubscribe === "function") unsubscribe();
+		},
+	};
+}