pi-subagents 0.17.4 → 0.18.0

package/subagent-executor.ts

@@ -23,9 +23,11 @@ import {
 import { discoverAvailableSkills, normalizeSkillInput } from "./skills.ts";
 import { executeAsyncChain, executeAsyncSingle, isAsyncAvailable } from "./async-execution.ts";
 import { createForkContextResolver } from "./fork-context.ts";
-import { applyIntercomBridgeToAgent, resolveIntercomBridge, resolveIntercomSessionTarget } from "./intercom-bridge.ts";
+import { applyIntercomBridgeToAgent, resolveIntercomBridge, resolveIntercomSessionTarget, resolveSubagentIntercomTarget, type IntercomBridgeState } from "./intercom-bridge.ts";
+import { formatControlIntercomMessage, formatControlNoticeMessage, resolveControlConfig, shouldNotifyControlEvent } from "./subagent-control.ts";
 import { finalizeSingleOutput, injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.ts";
-import { compactForegroundDetails, getSingleResultOutput, mapConcurrent, resolveChildCwd } from "./utils.ts";
+import { compactForegroundDetails, getSingleResultOutput, mapConcurrent, readStatus, resolveChildCwd } from "./utils.ts";
+import { inspectSubagentStatus } from "./run-status.ts";
 import { applyForceTopLevelAsyncOverride } from "./top-level-async.ts";
 import {
 	cleanupWorktrees,
@@ -40,12 +42,17 @@ import {
 	type AgentProgress,
 	type ArtifactConfig,
 	type ArtifactPaths,
+	type ControlConfig,
+	type ControlEvent,
 	type Details,
 	type ExtensionConfig,
 	type MaxOutputConfig,
+	type ResolvedControlConfig,
 	type SingleResult,
 	type SubagentState,
 	DEFAULT_ARTIFACT_CONFIG,
+	SUBAGENT_CONTROL_EVENT,
+	SUBAGENT_CONTROL_INTERCOM_EVENT,
 	checkSubagentDepth,
 	resolveTopLevelParallelConcurrency,
 	resolveTopLevelParallelMaxTasks,
@@ -54,6 +61,8 @@ import {
 	wrapForkTask,
 } from "./types.ts";
 
+const ASYNC_INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
+
 interface TaskParam {
 	agent: string;
 	task: string;
@@ -65,6 +74,9 @@ interface TaskParam {
 
 export interface SubagentParamsLike {
 	action?: string;
+	id?: string;
+	runId?: string;
+	dir?: string;
 	agent?: string;
 	task?: string;
 	chain?: ChainStep[];
@@ -75,6 +87,7 @@ export interface SubagentParamsLike {
 	async?: boolean;
 	clarify?: boolean;
 	share?: boolean;
+	control?: ControlConfig;
 	sessionDir?: string;
 	cwd?: string;
 	maxOutput?: MaxOutputConfig;
@@ -114,12 +127,131 @@ interface ExecutionContextData {
 	artifactsDir: string;
 	backgroundRequestedWhileClarifying: boolean;
 	effectiveAsync: boolean;
+	controlConfig: ResolvedControlConfig;
+	intercomBridge: IntercomBridgeState;
 }
 
 function resolveRequestedCwd(runtimeCwd: string, requestedCwd: string | undefined): string {
 	return requestedCwd ? path.resolve(runtimeCwd, requestedCwd) : runtimeCwd;
 }
 
+function getForegroundControl(state: SubagentState, runId: string | undefined) {
+	if (runId) return state.foregroundControls.get(runId);
+	if (state.lastForegroundControlId) {
+		const latest = state.foregroundControls.get(state.lastForegroundControlId);
+		if (latest) return latest;
+	}
+	let newest: (SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never) | undefined;
+	for (const control of state.foregroundControls.values()) {
+		if (!newest || control.updatedAt > newest.updatedAt) newest = control;
+	}
+	return newest;
+}
+
+function formatForegroundActivity(control: SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never): string | undefined {
+	if (control.currentTool && control.currentToolStartedAt) {
+		return `tool ${control.currentTool} for ${Math.floor(Math.max(0, Date.now() - control.currentToolStartedAt) / 1000)}s`;
+	}
+	if (!control.lastActivityAt) return control.currentActivityState === "needs_attention" ? "needs attention" : undefined;
+	const seconds = Math.floor(Math.max(0, Date.now() - control.lastActivityAt) / 1000);
+	return control.currentActivityState === "needs_attention" ? `no activity for ${seconds}s` : `active ${seconds}s ago`;
+}
+
+function foregroundStatusResult(control: SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never): AgentToolResult<Details> {
+	const lines = [
+		`Run: ${control.runId}`,
+		"State: running",
+		`Mode: ${control.mode}`,
+		control.currentAgent ? `Current: ${control.currentAgent}${control.currentIndex !== undefined ? ` step ${control.currentIndex + 1}` : ""}` : undefined,
+		formatForegroundActivity(control) ? `Activity: ${formatForegroundActivity(control)}` : undefined,
+	].filter((line): line is string => Boolean(line));
+	return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "management", results: [] } };
+}
+
+function getAsyncInterruptTarget(state: SubagentState, runId: string | undefined): { asyncId: string; asyncDir: string } | undefined {
+	if (runId) {
+		const direct = state.asyncJobs.get(runId);
+		if (direct) return { asyncId: direct.asyncId, asyncDir: direct.asyncDir };
+	}
+	let newest: { asyncId: string; asyncDir: string; updatedAt: number } | undefined;
+	for (const job of state.asyncJobs.values()) {
+		if (job.status !== "running") continue;
+		if (!newest || (job.updatedAt ?? 0) > newest.updatedAt) {
+			newest = { asyncId: job.asyncId, asyncDir: job.asyncDir, updatedAt: job.updatedAt ?? 0 };
+		}
+	}
+	return newest ? { asyncId: newest.asyncId, asyncDir: newest.asyncDir } : undefined;
+}
+
+function emitControlNotification(input: {
+	pi: ExtensionAPI;
+	controlConfig: ResolvedControlConfig;
+	intercomBridge: IntercomBridgeState;
+	event: ControlEvent;
+}): void {
+	if (!shouldNotifyControlEvent(input.controlConfig, input.event)) return;
+	const childIntercomTarget = input.intercomBridge.active
+		? resolveSubagentIntercomTarget(input.event.runId, input.event.agent, input.event.index)
+		: undefined;
+	const payload = {
+		event: input.event,
+		source: "foreground" as const,
+		childIntercomTarget,
+		noticeText: formatControlNoticeMessage(input.event, childIntercomTarget),
+	};
+	if (input.controlConfig.notifyChannels.includes("event")) {
+		input.pi.events.emit(SUBAGENT_CONTROL_EVENT, payload);
+	}
+	if (input.controlConfig.notifyChannels.includes("intercom") && input.intercomBridge.active && input.intercomBridge.orchestratorTarget) {
+		input.pi.events.emit(SUBAGENT_CONTROL_INTERCOM_EVENT, {
+			...payload,
+			to: input.intercomBridge.orchestratorTarget,
+			message: formatControlIntercomMessage(input.event, childIntercomTarget),
+		});
+	}
+}
+
+function interruptAsyncRun(state: SubagentState, runId: string | undefined): AgentToolResult<Details> | null {
+	const target = getAsyncInterruptTarget(state, runId);
+	if (!target) return null;
+	const status = readStatus(target.asyncDir);
+	if (!status || status.state !== "running" || typeof status.pid !== "number") {
+		return {
+			content: [{ type: "text", text: `No running async run with an interrupt-capable pid was found for '${runId ?? "current"}'.` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+	try {
+		process.kill(status.pid, ASYNC_INTERRUPT_SIGNAL);
+		const tracked = state.asyncJobs.get(target.asyncId);
+		if (tracked) {
+			tracked.activityState = undefined;
+			tracked.updatedAt = Date.now();
+		}
+		return {
+			content: [{ type: "text", text: `Interrupt requested for async run ${target.asyncId}.` }],
+			details: { mode: "management", results: [] },
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return {
+			content: [{ type: "text", text: `Failed to interrupt async run ${target.asyncId}: ${message}` }],
+			isError: true,
+			details: { mode: "management", results: [] },
+		};
+	}
+}
+
+function createForegroundControlNotifier(data: Pick<ExecutionContextData, "controlConfig" | "intercomBridge">, deps: Pick<ExecutorDeps, "pi">): (event: ControlEvent) => void {
+	return (event) => emitControlNotification({
+		pi: deps.pi,
+		controlConfig: data.controlConfig,
+		intercomBridge: data.intercomBridge,
+		event,
+	});
+}
+
 function validateExecutionInput(
 	params: SubagentParamsLike,
 	agents: AgentConfig[],
@@ -346,6 +478,8 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 		artifactConfig,
 		artifactsDir,
 		effectiveAsync,
+		controlConfig,
+		intercomBridge,
 	} = data;
 	const hasChain = (params.chain?.length ?? 0) > 0;
 	const hasTasks = (params.tasks?.length ?? 0) > 0;
@@ -395,6 +529,8 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 	}));
 	const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
 	const currentProvider = ctx.model?.provider;
+	const controlIntercomTarget = intercomBridge.active ? intercomBridge.orchestratorTarget : undefined;
+	const childIntercomTarget = intercomBridge.active ? (agent: string, index: number) => resolveSubagentIntercomTarget(id, agent, index) : undefined;
 
 	if (hasTasks && params.tasks) {
 		const agentConfigs = params.tasks.map((task) => agents.find((agent) => agent.name === task.agent));
@@ -429,6 +565,9 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			maxSubagentDepth: currentMaxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+			controlConfig,
+			controlIntercomTarget,
+			childIntercomTarget,
 		});
 	}
 
@@ -452,6 +591,9 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			maxSubagentDepth: currentMaxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+			controlConfig,
+			controlIntercomTarget,
+			childIntercomTarget,
 		});
 	}
 
@@ -489,6 +631,9 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			maxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+			controlConfig,
+			controlIntercomTarget,
+			childIntercomTarget: childIntercomTarget ? (agent, index) => childIntercomTarget(agent, index) : undefined,
 		});
 	}
 
@@ -510,7 +655,11 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 		artifactConfig,
 		onUpdate,
 		sessionRoot,
+		controlConfig,
 	} = data;
+	const onControlEvent = createForegroundControlNotifier(data, deps);
+	const childIntercomTarget = data.intercomBridge.active ? resolveSubagentIntercomTarget : undefined;
+	const foregroundControl = deps.state.foregroundControls.get(runId);
 	const normalized = normalizeSkillInput(params.skill);
 	const chainSkills = normalized === false ? [] : (normalized ?? []);
 	const chain = wrapChainTasksForFork(params.chain as ChainStep[], params.context);
@@ -531,6 +680,10 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 		includeProgress: params.includeProgress,
 		clarify: params.clarify,
 		onUpdate,
+		onControlEvent,
+		controlConfig,
+		childIntercomTarget: childIntercomTarget ? (agent, index) => childIntercomTarget(runId, agent, index) : undefined,
+		foregroundControl,
 		chainSkills,
 		chainDir: params.chainDir,
 		maxSubagentDepth: currentMaxSubagentDepth,
@@ -574,6 +727,9 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 			maxSubagentDepth: currentMaxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+			controlConfig,
+			controlIntercomTarget: data.intercomBridge.active ? data.intercomBridge.orchestratorTarget : undefined,
+			childIntercomTarget: data.intercomBridge.active ? (agent, index) => resolveSubagentIntercomTarget(runId, agent, index) : undefined,
 		});
 	}
 
@@ -599,6 +755,10 @@ interface ForegroundParallelRunInput {
 	modelOverrides: (string | undefined)[];
 	skillOverrides: (string[] | false | undefined)[];
 	behaviors: Array<ReturnType<typeof resolveStepBehavior>>;
+	controlConfig: ResolvedControlConfig;
+	onControlEvent?: (event: ControlEvent) => void;
+	childIntercomTarget?: (agent: string, index: number) => string | undefined;
+	foregroundControl?: SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never;
 	concurrencyLimit: number;
 	liveResults: (SingleResult | undefined)[];
 	liveProgress: (AgentProgress | undefined)[];
@@ -687,9 +847,24 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 		const overrideSkills = input.skillOverrides[index];
 		const effectiveSkills = overrideSkills === undefined ? input.behaviors[index]?.skills : overrideSkills;
 		const taskCwd = resolveParallelTaskCwd(task, input.paramsCwd, input.worktreeSetup, index);
+		const interruptController = new AbortController();
+		if (input.foregroundControl) {
+			input.foregroundControl.currentAgent = task.agent;
+			input.foregroundControl.currentIndex = index;
+			input.foregroundControl.currentActivityState = undefined;
+			input.foregroundControl.updatedAt = Date.now();
+			input.foregroundControl.interrupt = () => {
+				if (interruptController.signal.aborted) return false;
+				interruptController.abort();
+				input.foregroundControl!.currentActivityState = undefined;
+				input.foregroundControl!.updatedAt = Date.now();
+				return true;
+			};
+		}
 		return runSync(input.ctx.cwd, input.agents, task.agent, input.taskTexts[index]!, {
 			cwd: taskCwd,
 			signal: input.signal,
+			interruptSignal: interruptController.signal,
 			runId: input.runId,
 			index,
 			sessionDir: input.sessionDirForIndex(index),
@@ -699,14 +874,27 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			artifactConfig: input.artifactConfig,
 			maxOutput: input.maxOutput,
 			maxSubagentDepth: input.maxSubagentDepths[index],
+			controlConfig: input.controlConfig,
+			onControlEvent: input.onControlEvent,
+			intercomSessionName: input.childIntercomTarget?.(task.agent, index),
 			modelOverride: input.modelOverrides[index],
 			availableModels: input.availableModels,
 			preferredModelProvider: input.ctx.model?.provider,
 			skills: effectiveSkills === false ? [] : effectiveSkills,
-			onUpdate: input.onUpdate
-				? (progressUpdate) => {
+				onUpdate: input.onUpdate
+					? (progressUpdate) => {
 						const stepResults = progressUpdate.details?.results || [];
 						const stepProgress = progressUpdate.details?.progress || [];
+						if (input.foregroundControl && stepProgress.length > 0) {
+							const current = stepProgress[0];
+							input.foregroundControl.currentAgent = task.agent;
+							input.foregroundControl.currentIndex = index;
+							input.foregroundControl.currentActivityState = current?.activityState;
+							input.foregroundControl.lastActivityAt = current?.lastActivityAt;
+							input.foregroundControl.currentTool = current?.currentTool;
+							input.foregroundControl.currentToolStartedAt = current?.currentToolStartedAt;
+							input.foregroundControl.updatedAt = Date.now();
+						}
 						if (stepResults.length > 0) input.liveResults[index] = stepResults[0];
 						if (stepProgress.length > 0) input.liveProgress[index] = stepProgress[0];
 						const mergedResults = input.liveResults.filter((result): result is SingleResult => result !== undefined);
@@ -717,11 +905,17 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 								mode: "parallel",
 								results: mergedResults,
 								progress: mergedProgress,
+								controlEvents: progressUpdate.details?.controlEvents,
 								totalSteps: input.tasks.length,
 							},
 						});
 					}
 				: undefined,
+		}).finally(() => {
+			if (input.foregroundControl?.currentIndex === index) {
+				input.foregroundControl.interrupt = undefined;
+				input.foregroundControl.updatedAt = Date.now();
+			}
 		});
 	});
 }
@@ -742,7 +936,10 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 		backgroundRequestedWhileClarifying,
 		onUpdate,
 		sessionRoot,
+		controlConfig,
 	} = data;
+	const onControlEvent = createForegroundControlNotifier(data, deps);
+	const childIntercomTarget = data.intercomBridge.active ? resolveSubagentIntercomTarget : undefined;
 	const allProgress: AgentProgress[] = [];
 	const allArtifactPaths: ArtifactPaths[] = [];
 	const tasks = params.tasks!;
@@ -866,6 +1063,9 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 				maxSubagentDepth: currentMaxSubagentDepth,
 				worktreeSetupHook: deps.config.worktreeSetupHook,
 				worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+				controlConfig,
+				controlIntercomTarget: data.intercomBridge.active ? data.intercomBridge.orchestratorTarget : undefined,
+				childIntercomTarget: data.intercomBridge.active ? (agent, index) => resolveSubagentIntercomTarget(runId, agent, index) : undefined,
 			});
 		}
 	}
@@ -873,6 +1073,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 	const behaviors = agentConfigs.map((config) => resolveStepBehavior(config, {}));
 	const liveResults: (SingleResult | undefined)[] = new Array(tasks.length).fill(undefined);
 	const liveProgress: (AgentProgress | undefined)[] = new Array(tasks.length).fill(undefined);
+	const foregroundControl = deps.state.foregroundControls.get(runId);
 	const { setup: worktreeSetup, errorResult } = createParallelWorktreeSetup(
 		params.worktree,
 		effectiveCwd,
@@ -908,6 +1109,10 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			modelOverrides,
 			skillOverrides,
 			behaviors,
+			controlConfig,
+			onControlEvent,
+			childIntercomTarget: childIntercomTarget ? (agent, index) => childIntercomTarget(runId, agent, index) : undefined,
+			foregroundControl,
 			concurrencyLimit: parallelConcurrency,
 			maxSubagentDepths,
 			liveResults,
@@ -925,6 +1130,19 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			if (result.artifactPaths) allArtifactPaths.push(result.artifactPaths);
 		}
 
+		const interrupted = results.find((result) => result.interrupted);
+		if (interrupted) {
+			return {
+				content: [{ type: "text", text: `Parallel run paused after interrupt (${interrupted.agent}). Waiting for explicit next action.` }],
+				details: compactForegroundDetails({
+					mode: "parallel",
+					results,
+					progress: params.includeProgress ? allProgress : undefined,
+					artifacts: allArtifactPaths.length ? { dir: artifactsDir, files: allArtifactPaths } : undefined,
+				}),
+			};
+		}
+
 		const worktreeSuffix = buildParallelWorktreeSuffix(worktreeSetup, artifactsDir, tasks);
 		const ok = results.filter((result) => result.exitCode === 0).length;
 		const downgradeNote = backgroundRequestedWhileClarifying ? " (background requested, but clarify kept this run foreground)" : "";
@@ -972,7 +1190,10 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		artifactsDir,
 		onUpdate,
 		sessionRoot,
+		controlConfig,
 	} = data;
+	const onControlEvent = createForegroundControlNotifier(data, deps);
+	const childIntercomTarget = data.intercomBridge.active ? resolveSubagentIntercomTarget(runId, params.agent!, undefined) : undefined;
 	const allProgress: AgentProgress[] = [];
 	const allArtifactPaths: ArtifactPaths[] = [];
 	const agentConfig = agents.find((a) => a.name === params.agent);
@@ -1068,6 +1289,9 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 				maxSubagentDepth,
 				worktreeSetupHook: deps.config.worktreeSetupHook,
 				worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+				controlConfig,
+				controlIntercomTarget: data.intercomBridge.active ? data.intercomBridge.orchestratorTarget : undefined,
+				childIntercomTarget: data.intercomBridge.active ? (agent, index) => resolveSubagentIntercomTarget(runId, agent, index) : undefined,
 			});
 		}
 	}
@@ -1085,10 +1309,42 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	} else {
 		effectiveSkills = skillOverride;
 	}
+	const interruptController = new AbortController();
+	const foregroundControl = deps.state.foregroundControls.get(runId);
+	if (foregroundControl) {
+		foregroundControl.currentAgent = params.agent;
+		foregroundControl.currentIndex = 0;
+		foregroundControl.currentActivityState = undefined;
+		foregroundControl.updatedAt = Date.now();
+		foregroundControl.interrupt = () => {
+			if (interruptController.signal.aborted) return false;
+			interruptController.abort();
+			foregroundControl.currentActivityState = undefined;
+			foregroundControl.updatedAt = Date.now();
+			return true;
+		};
+	}
+
+	const forwardSingleUpdate = onUpdate
+		? (update: AgentToolResult<Details>) => {
+			if (foregroundControl) {
+				const firstProgress = update.details?.progress?.[0];
+				foregroundControl.currentAgent = params.agent;
+				foregroundControl.currentIndex = firstProgress?.index ?? 0;
+				foregroundControl.currentActivityState = firstProgress?.activityState;
+				foregroundControl.lastActivityAt = firstProgress?.lastActivityAt;
+				foregroundControl.currentTool = firstProgress?.currentTool;
+				foregroundControl.currentToolStartedAt = firstProgress?.currentToolStartedAt;
+				foregroundControl.updatedAt = Date.now();
+			}
+			onUpdate(update);
+		}
+		: undefined;
 
 	const r = await runSync(ctx.cwd, agents, params.agent!, task, {
 		cwd: effectiveCwd,
 		signal,
+		interruptSignal: interruptController.signal,
 		allowIntercomDetach: agentConfig.systemPrompt?.includes("Intercom orchestration channel:") === true,
 		intercomEvents: deps.pi.events,
 		runId,
@@ -1100,12 +1356,23 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		maxOutput: params.maxOutput,
 		outputPath,
 		maxSubagentDepth,
-		onUpdate,
+		onUpdate: forwardSingleUpdate,
+		controlConfig,
+		onControlEvent,
+		intercomSessionName: childIntercomTarget,
 		modelOverride,
 		availableModels,
 		preferredModelProvider: currentProvider,
 		skills: effectiveSkills,
 	});
+	if (foregroundControl?.currentIndex === 0) {
+		foregroundControl.interrupt = undefined;
+		foregroundControl.currentActivityState = r.progress?.activityState;
+		foregroundControl.lastActivityAt = r.progress?.lastActivityAt;
+		foregroundControl.currentTool = r.progress?.currentTool;
+		foregroundControl.currentToolStartedAt = r.progress?.currentToolStartedAt;
+		foregroundControl.updatedAt = Date.now();
+	}
 	recordRun(params.agent!, cleanTask, r.exitCode, r.progressSummary?.durationMs ?? 0);
 
 	if (r.progress) allProgress.push(r.progress);
@@ -1134,6 +1401,19 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		};
 	}
 
+	if (r.interrupted) {
+		return {
+			content: [{ type: "text", text: `Run paused after interrupt (${params.agent}). Waiting for explicit next action.` }],
+			details: compactForegroundDetails({
+				mode: "single",
+				results: [r],
+				progress: params.includeProgress ? allProgress : undefined,
+				artifacts: allArtifactPaths.length ? { dir: artifactsDir, files: allArtifactPaths } : undefined,
+				truncation: r.truncation,
+			}),
+		};
+	}
+
 	if (r.exitCode !== 0)
 		return {
 			content: [{ type: "text", text: r.error || "Failed" }],
@@ -1175,10 +1455,44 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		ctx: ExtensionContext,
 	): Promise<AgentToolResult<Details>> => {
 		deps.state.baseCwd = ctx.cwd;
+		deps.state.foregroundControls ??= new Map();
+		deps.state.lastForegroundControlId ??= null;
 		const requestCwd = resolveRequestedCwd(ctx.cwd, params.cwd);
 		const paramsWithResolvedCwd = params.cwd === undefined ? params : { ...params, cwd: requestCwd };
 		if (params.action) {
-			const validActions = ["list", "get", "create", "update", "delete"];
+			if (params.action === "status") {
+				const foreground = getForegroundControl(deps.state, paramsWithResolvedCwd.id ?? paramsWithResolvedCwd.runId);
+				if (foreground) return foregroundStatusResult(foreground);
+				return inspectSubagentStatus(paramsWithResolvedCwd);
+			}
+			if (params.action === "interrupt") {
+				const targetRunId = paramsWithResolvedCwd.runId ?? paramsWithResolvedCwd.id;
+				const foreground = getForegroundControl(deps.state, targetRunId);
+				if (foreground?.interrupt) {
+					const interrupted = foreground.interrupt();
+					if (interrupted) {
+						foreground.updatedAt = Date.now();
+						foreground.currentActivityState = undefined;
+						return {
+							content: [{ type: "text", text: `Interrupt requested for foreground run ${foreground.runId}.` }],
+							details: { mode: "management", results: [] },
+						};
+					}
+					return {
+						content: [{ type: "text", text: `Foreground run ${foreground.runId} has no active child step to interrupt.` }],
+						isError: true,
+						details: { mode: "management", results: [] },
+					};
+				}
+				const asyncInterruptResult = interruptAsyncRun(deps.state, targetRunId);
+				if (asyncInterruptResult) return asyncInterruptResult;
+				return {
+					content: [{ type: "text", text: "No interrupt-capable run found in this session." }],
+					isError: true,
+					details: { mode: "management", results: [] },
+				};
+			}
+			const validActions = ["list", "get", "create", "update", "delete", "status", "interrupt"];
 			if (!validActions.includes(params.action)) {
 				return {
 					content: [{ type: "text", text: `Unknown action: ${params.action}. Valid: ${validActions.join(", ")}` }],
@@ -1260,6 +1574,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		const backgroundRequestedWhileClarifying = hasTasks && requestedAsync && effectiveParams.clarify === true;
 		const effectiveAsync = requestedAsync
 			&& (hasChain ? effectiveParams.clarify === false : effectiveParams.clarify !== true);
+		const controlConfig = resolveControlConfig(deps.config.control, effectiveParams.control);
 
 		const artifactConfig: ArtifactConfig = {
 			...DEFAULT_ARTIFACT_CONFIG,
@@ -1308,8 +1623,28 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 			artifactsDir,
 			backgroundRequestedWhileClarifying,
 			effectiveAsync,
+			controlConfig,
+			intercomBridge,
 		};
 
+		const foregroundMode: "single" | "parallel" | "chain" = hasChain ? "chain" : hasTasks ? "parallel" : "single";
+		const foregroundControl = effectiveAsync
+			? undefined
+			: {
+				runId,
+				mode: foregroundMode,
+				startedAt: Date.now(),
+				updatedAt: Date.now(),
+				currentAgent: undefined,
+				currentIndex: undefined,
+				currentActivityState: undefined,
+				interrupt: undefined,
+			};
+		if (foregroundControl) {
+			deps.state.foregroundControls.set(runId, foregroundControl);
+			deps.state.lastForegroundControlId = runId;
+		}
+
 		try {
 			const asyncResult = runAsyncPath(execData, deps);
 			if (asyncResult) return withForkContext(asyncResult, effectiveParams.context);
@@ -1327,6 +1662,13 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 			}
 		} catch (error) {
 			return toExecutionErrorResult(normalizedParams, error);
+		} finally {
+			if (foregroundControl) {
+				deps.state.foregroundControls.delete(runId);
+				if (deps.state.lastForegroundControlId === runId) {
+					deps.state.lastForegroundControlId = null;
+				}
+			}
 		}
 
 		return withForkContext({

package/subagent-prompt-runtime.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
 export const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
 export const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
+export const SUBAGENT_INTERCOM_SESSION_NAME_ENV = "PI_SUBAGENT_INTERCOM_SESSION_NAME";
 
 const PROJECT_CONTEXT_HEADER = "\n\n# Project Context\n\nProject-specific instructions and guidelines:\n\n";
 const SKILLS_HEADER = "\n\nThe following skills provide specialized instructions for specific tasks.";
@@ -54,6 +55,11 @@ export function rewriteSubagentPrompt(
 
 export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	pi.on("before_agent_start", async (event) => {
+		const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
+		if (intercomSessionName && typeof pi.setSessionName === "function") {
+			pi.setSessionName(intercomSessionName);
+		}
+
 		const inheritProjectContext = readBooleanEnv(SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV);
 		const inheritSkills = readBooleanEnv(SUBAGENT_INHERIT_SKILLS_ENV);
 		if (inheritProjectContext === undefined && inheritSkills === undefined) return;