pi-subagents 0.17.4 → 0.18.0

package/subagent-runner.ts

@@ -8,15 +8,26 @@ import { appendJsonl, getArtifactPaths } from "./artifacts.ts";
 import { getPiSpawnCommand } from "./pi-spawn.ts";
 import { captureSingleOutputSnapshot, resolveSingleOutput } from "./single-output.ts";
 import {
+	type ActivityState,
 	type ArtifactConfig,
 	type ArtifactPaths,
 	type ModelAttempt,
+	type ResolvedControlConfig,
 	type Usage,
 	DEFAULT_MAX_OUTPUT,
 	type MaxOutputConfig,
 	truncateOutput,
 	getSubagentDepthEnv,
 } from "./types.ts";
+import {
+	DEFAULT_CONTROL_CONFIG,
+	buildControlEvent,
+	deriveActivityState,
+	claimControlNotification,
+	formatControlIntercomMessage,
+	formatControlNoticeMessage,
+	shouldEmitControlEvent,
+} from "./subagent-control.ts";
 import {
 	type RunnerSubagentStep as SubagentStep,
 	type RunnerStep,
@@ -60,6 +71,9 @@ interface SubagentRunConfig {
 	piArgv1?: string;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	controlConfig?: ResolvedControlConfig;
+	controlIntercomTarget?: string;
+	childIntercomTargets?: Array<string | undefined>;
 }
 
 interface StepResult {
@@ -75,6 +89,7 @@ interface StepResult {
 }
 
 const require = createRequire(import.meta.url);
+const ASYNC_INTERRUPT_SIGNAL: NodeJS.Signals = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
 
 function findLatestSessionFile(sessionDir: string): string | null {
 	try {
@@ -95,6 +110,18 @@ function emptyUsage(): Usage {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
 }
 
+function tokenUsageFromAttempts(attempts: ModelAttempt[] | undefined): TokenUsage | null {
+	if (!attempts || attempts.length === 0) return null;
+	let input = 0;
+	let output = 0;
+	for (const attempt of attempts) {
+		input += attempt.usage?.input ?? 0;
+		output += attempt.usage?.output ?? 0;
+	}
+	const total = input + output;
+	return total > 0 ? { input, output, total } : null;
+}
+
 interface ChildEventContext {
 	eventsPath: string;
 	runId: string;
@@ -133,6 +160,7 @@ interface RunPiStreamingResult {
 	model?: string;
 	error?: string;
 	finalOutput: string;
+	interrupted?: boolean;
 }
 
 function runPiStreaming(
@@ -144,6 +172,7 @@ function runPiStreaming(
 	piArgv1?: string,
 	maxSubagentDepth?: number,
 	childEventContext?: ChildEventContext,
+	registerInterrupt?: (interrupt: (() => void) | undefined) => void,
 ): Promise<RunPiStreamingResult> {
 	return new Promise((resolve) => {
 		const outputStream = fs.createWriteStream(outputFile, { flags: "w" });
@@ -160,6 +189,7 @@ function runPiStreaming(
 		const usage = emptyUsage();
 		let model: string | undefined;
 		let error: string | undefined;
+		let interrupted = false;
 		const rawStdoutLines: string[] = [];
 
 		const writeOutputLine = (line: string) => {
@@ -267,6 +297,15 @@ function runPiStreaming(
 		child.stderr.on("data", (chunk: Buffer) => {
 			processStderrText(chunk.toString());
 		});
+		registerInterrupt?.(() => {
+			if (settled) return;
+			interrupted = true;
+			if (!error) error = "Interrupted. Waiting for explicit next action.";
+			trySignalChild(child, "SIGINT");
+			setTimeout(() => {
+				if (!settled) trySignalChild(child, "SIGTERM");
+			}, 1000).unref?.();
+		});
 		const clearDrainTimers = () => {
 			if (finalDrainTimer) {
 				clearTimeout(finalDrainTimer);
@@ -301,6 +340,7 @@ function runPiStreaming(
 		});
 		child.on("close", (exitCode, signal) => {
 			settled = true;
+			registerInterrupt?.(undefined);
 			clearDrainTimers();
 			clearStdioGuard();
 			if (stdoutBuf.trim()) processStdoutLine(stdoutBuf);
@@ -309,17 +349,19 @@ function runPiStreaming(
 			const finalOutput = getFinalOutput(messages) || rawStdoutLines.join("\n").trim();
 			resolve({
 				stderr,
-				exitCode: forcedTerminationSignal || signal ? (exitCode ?? 1) : exitCode,
+				exitCode: interrupted ? 0 : forcedTerminationSignal || signal ? (exitCode ?? 1) : exitCode,
 				messages,
 				usage,
 				model,
-				error,
+				error: interrupted ? undefined : error,
 				finalOutput,
+				interrupted,
 			});
 		});
 
 		child.on("error", (spawnError) => {
 			settled = true;
+			registerInterrupt?.(undefined);
 			clearDrainTimers();
 			clearStdioGuard();
 			outputStream.end();
@@ -481,6 +523,8 @@ interface SingleStepContext {
 	outputFile: string;
 	piPackageRoot?: string;
 	piArgv1?: string;
+	registerInterrupt?: (interrupt: (() => void) | undefined) => void;
+	childIntercomTarget?: string;
 }
 
 /** Run a single pi agent step, returning output and metadata */
@@ -496,6 +540,7 @@ async function runSingleStep(
 	attemptedModels?: string[];
 	modelAttempts?: ModelAttempt[];
 	artifactPaths?: ArtifactPaths;
+	interrupted?: boolean;
 }> {
 	const placeholderRegex = new RegExp(ctx.placeholder.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
 	const task = step.task.replace(placeholderRegex, () => ctx.previousOutput);
@@ -541,6 +586,7 @@ async function runSingleStep(
 			systemPromptMode: step.systemPromptMode,
 			mcpDirectTools: step.mcpDirectTools,
 			promptFileStem: step.agent,
+			intercomSessionName: ctx.childIntercomTarget,
 		});
 		const run = await runPiStreaming(
 			args,
@@ -551,6 +597,7 @@ async function runSingleStep(
 			ctx.piArgv1,
 			step.maxSubagentDepth,
 			{ eventsPath, runId: ctx.id, stepIndex: ctx.flatIndex, agent: step.agent },
+			ctx.registerInterrupt,
 		);
 		cleanupTempDir(tempDir);
 
@@ -627,13 +674,18 @@ async function runSingleStep(
 		attemptedModels: attemptedModels.length > 0 ? attemptedModels : undefined,
 		modelAttempts,
 		artifactPaths,
+		interrupted: finalResult?.interrupted,
 	};
 }
 
 type RunnerStatusPayload = {
 	runId: string;
 	mode: "single" | "chain";
-	state: "queued" | "running" | "complete" | "failed";
+	state: "queued" | "running" | "complete" | "failed" | "paused";
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
 	startedAt: number;
 	endedAt?: number;
 	lastUpdate: number;
@@ -643,6 +695,10 @@ type RunnerStatusPayload = {
 	steps: Array<{
 		agent: string;
 		status: "pending" | "running" | "complete" | "failed";
+		activityState?: ActivityState;
+		lastActivityAt?: number;
+		currentTool?: string;
+		currentToolStartedAt?: number;
 		startedAt?: number;
 		endedAt?: number;
 		durationMs?: number;
@@ -715,8 +771,11 @@ function markParallelGroupRunning(input: {
 		const flatTaskIndex = input.groupStartFlatIndex + taskIndex;
 		input.statusPayload.steps[flatTaskIndex].status = "running";
 		input.statusPayload.steps[flatTaskIndex].startedAt = input.groupStartTime;
+		input.statusPayload.steps[flatTaskIndex].lastActivityAt = input.groupStartTime;
 	}
 	input.statusPayload.currentStep = input.groupStartFlatIndex;
+	input.statusPayload.activityState = undefined;
+	input.statusPayload.lastActivityAt = input.groupStartTime;
 	input.statusPayload.lastUpdate = input.groupStartTime;
 	input.statusPayload.outputFile = path.join(input.asyncDir, `output-${input.groupStartFlatIndex}.log`);
 	writeJson(input.statusPath, input.statusPayload);
@@ -769,6 +828,11 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 	const statusPath = path.join(asyncDir, "status.json");
 	const eventsPath = path.join(asyncDir, "events.jsonl");
 	const logPath = path.join(asyncDir, `subagent-log-${id}.md`);
+	const controlConfig = config.controlConfig ?? DEFAULT_CONTROL_CONFIG;
+	let activeChildInterrupt: (() => void) | undefined;
+	let interrupted = false;
+	let currentActivityState: ActivityState | undefined;
+	let activityTimer: NodeJS.Timeout | undefined;
 	let previousCumulativeTokens: TokenUsage = { input: 0, output: 0, total: 0 };
 	let latestSessionFile: string | undefined;
 
@@ -780,6 +844,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		runId: id,
 		mode: flatSteps.length > 1 ? "chain" : "single",
 		state: "running",
+		lastActivityAt: overallStartTime,
 		startedAt: overallStartTime,
 		lastUpdate: overallStartTime,
 		pid: process.pid,
@@ -799,6 +864,107 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 
 	fs.mkdirSync(asyncDir, { recursive: true });
 	writeJson(statusPath, statusPayload);
+
+	const currentStepAgent = () => statusPayload.steps[statusPayload.currentStep]?.agent ?? flatSteps[statusPayload.currentStep]?.agent ?? "subagent";
+	const currentOutputActivityAt = (): number => {
+		const runningIndexes = statusPayload.steps
+			.map((step, index) => step.status === "running" ? index : -1)
+			.filter((index) => index >= 0);
+		let lastActivityAt = statusPayload.steps[statusPayload.currentStep]?.startedAt ?? overallStartTime;
+		for (const index of runningIndexes.length > 0 ? runningIndexes : [statusPayload.currentStep]) {
+			try {
+				lastActivityAt = Math.max(lastActivityAt, fs.statSync(path.join(asyncDir, `output-${index}.log`)).mtimeMs);
+			} catch {
+				// Missing output files are normal before a child writes its first line.
+			}
+		}
+		return lastActivityAt;
+	};
+	const emittedControlEventKeys = new Set<string>();
+	const appendControlEvent = (event: ReturnType<typeof buildControlEvent>) => {
+		const childIntercomTarget = config.childIntercomTargets?.[statusPayload.currentStep];
+		if (controlConfig.notifyChannels.length === 0 || !claimControlNotification(controlConfig, event, emittedControlEventKeys, childIntercomTarget)) return;
+		appendJsonl(eventsPath, JSON.stringify({
+			type: "subagent.control",
+			event,
+			channels: controlConfig.notifyChannels,
+			childIntercomTarget,
+			noticeText: formatControlNoticeMessage(event, childIntercomTarget),
+			...(config.controlIntercomTarget && controlConfig.notifyChannels.includes("intercom") ? {
+				intercom: {
+					to: config.controlIntercomTarget,
+					message: formatControlIntercomMessage(event, childIntercomTarget),
+				},
+			} : {}),
+		}));
+	};
+	const updateRunnerActivityState = (now: number): boolean => {
+		const lastActivityAt = currentOutputActivityAt();
+		const next = deriveActivityState({
+			config: controlConfig,
+			startedAt: overallStartTime,
+			lastActivityAt,
+			now,
+		});
+		if (next === currentActivityState && statusPayload.lastActivityAt === lastActivityAt) return false;
+		const previous = currentActivityState;
+		currentActivityState = next;
+		statusPayload.activityState = next;
+		statusPayload.lastActivityAt = lastActivityAt;
+		for (const step of statusPayload.steps) {
+			if (step.status === "running") {
+				step.activityState = next;
+				step.lastActivityAt = lastActivityAt;
+			}
+		}
+		statusPayload.lastUpdate = now;
+		if (shouldEmitControlEvent(controlConfig, previous, next)) {
+			const event = buildControlEvent({
+				from: previous,
+				to: next,
+				runId: id,
+				agent: currentStepAgent(),
+				index: statusPayload.currentStep,
+				ts: now,
+				lastActivityAt,
+			});
+			appendControlEvent(event);
+		}
+		writeJson(statusPath, statusPayload);
+		return true;
+	};
+	if (controlConfig.enabled) {
+		activityTimer = setInterval(() => {
+			if (statusPayload.state !== "running") return;
+			const now = Date.now();
+			updateRunnerActivityState(now);
+		}, 1000);
+		activityTimer.unref?.();
+	}
+
+	const interruptRunner = () => {
+		if (interrupted || statusPayload.state !== "running") return;
+		interrupted = true;
+		const now = Date.now();
+		statusPayload.state = "paused";
+		currentActivityState = undefined;
+		statusPayload.activityState = undefined;
+		statusPayload.lastUpdate = now;
+		const current = statusPayload.steps[statusPayload.currentStep];
+		if (current?.status === "running") {
+			current.activityState = undefined;
+			current.endedAt = now;
+			current.durationMs = current.startedAt ? now - current.startedAt : undefined;
+		}
+		writeJson(statusPath, statusPayload);
+		appendJsonl(eventsPath, JSON.stringify({
+			type: "subagent.run.paused",
+			ts: now,
+			runId: id,
+		}));
+		activeChildInterrupt?.();
+	};
+	process.on(ASYNC_INTERRUPT_SIGNAL, interruptRunner);
 	appendJsonl(
 		eventsPath,
 		JSON.stringify({
@@ -814,6 +980,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 	let flatIndex = 0;
 
 	for (let stepIndex = 0; stepIndex < steps.length; stepIndex++) {
+		if (interrupted) break;
 		const step = steps[stepIndex];
 
 		if (isParallelGroup(step)) {
@@ -912,6 +1079,10 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 							outputFile: path.join(asyncDir, `output-${fi}.log`),
 							piPackageRoot: config.piPackageRoot,
 							piArgv1: config.piArgv1,
+							childIntercomTarget: config.childIntercomTargets?.[fi],
+							registerInterrupt: (interrupt) => {
+								activeChildInterrupt = interrupt;
+							},
 						});
 						if (task.sessionFile) {
 							latestSessionFile = task.sessionFile;
@@ -944,24 +1115,23 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 
 				flatIndex += group.parallel.length;
 
-				if (config.sessionDir) {
-					for (let t = 0; t < group.parallel.length; t++) {
-						const taskSessionDir = path.join(config.sessionDir, `parallel-${t}`);
-						const taskTokens = parseSessionTokens(taskSessionDir);
-						if (taskTokens) {
-							const fi = groupStartFlatIndex + t;
-							statusPayload.steps[fi].tokens = taskTokens;
-							previousCumulativeTokens = {
-								input: previousCumulativeTokens.input + taskTokens.input,
-								output: previousCumulativeTokens.output + taskTokens.output,
-								total: previousCumulativeTokens.total + taskTokens.total,
-							};
-						}
-					}
-					statusPayload.totalTokens = { ...previousCumulativeTokens };
-					statusPayload.lastUpdate = Date.now();
-					writeJson(statusPath, statusPayload);
+				for (let t = 0; t < group.parallel.length; t++) {
+					const fi = groupStartFlatIndex + t;
+					const sessionTokens = config.sessionDir
+						? parseSessionTokens(path.join(config.sessionDir, `parallel-${t}`))
+						: null;
+					const taskTokens = sessionTokens ?? tokenUsageFromAttempts(parallelResults[t]?.modelAttempts);
+					if (!taskTokens) continue;
+					statusPayload.steps[fi].tokens = taskTokens;
+					previousCumulativeTokens = {
+						input: previousCumulativeTokens.input + taskTokens.input,
+						output: previousCumulativeTokens.output + taskTokens.output,
+						total: previousCumulativeTokens.total + taskTokens.total,
+					};
 				}
+				statusPayload.totalTokens = { ...previousCumulativeTokens };
+				statusPayload.lastUpdate = Date.now();
+				writeJson(statusPath, statusPayload);
 
 				for (const pr of parallelResults) {
 					results.push({
@@ -1007,8 +1177,12 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 			const stepStartTime = Date.now();
 			statusPayload.currentStep = flatIndex;
 			statusPayload.steps[flatIndex].status = "running";
+			statusPayload.steps[flatIndex].activityState = undefined;
+			statusPayload.activityState = undefined;
 			statusPayload.steps[flatIndex].skills = seqStep.skills;
 			statusPayload.steps[flatIndex].startedAt = stepStartTime;
+			statusPayload.steps[flatIndex].lastActivityAt = stepStartTime;
+			statusPayload.lastActivityAt = stepStartTime;
 			statusPayload.lastUpdate = stepStartTime;
 			statusPayload.outputFile = path.join(asyncDir, `output-${flatIndex}.log`);
 			writeJson(statusPath, statusPayload);
@@ -1029,6 +1203,10 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				outputFile: path.join(asyncDir, `output-${flatIndex}.log`),
 				piPackageRoot: config.piPackageRoot,
 				piArgv1: config.piArgv1,
+				childIntercomTarget: config.childIntercomTargets?.[flatIndex],
+				registerInterrupt: (interrupt) => {
+					activeChildInterrupt = interrupt;
+				},
 			});
 			if (seqStep.sessionFile) {
 				latestSessionFile = seqStep.sessionFile;
@@ -1046,7 +1224,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 			});
 
 			const cumulativeTokens = config.sessionDir ? parseSessionTokens(config.sessionDir) : null;
-			const stepTokens: TokenUsage | null = cumulativeTokens
+			let stepTokens: TokenUsage | null = cumulativeTokens
 				? {
 						input: cumulativeTokens.input - previousCumulativeTokens.input,
 						output: cumulativeTokens.output - previousCumulativeTokens.output,
@@ -1055,6 +1233,15 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				: null;
 			if (cumulativeTokens) {
 				previousCumulativeTokens = cumulativeTokens;
+			} else {
+				stepTokens = tokenUsageFromAttempts(singleResult.modelAttempts);
+				if (stepTokens) {
+					previousCumulativeTokens = {
+						input: previousCumulativeTokens.input + stepTokens.input,
+						output: previousCumulativeTokens.output + stepTokens.output,
+						total: previousCumulativeTokens.total + stepTokens.total,
+					};
+				}
 			}
 
 			const stepEndTime = Date.now();
@@ -1137,9 +1324,14 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		}
 	}
 
+	if (activityTimer) {
+		clearInterval(activityTimer);
+		activityTimer = undefined;
+	}
 	const effectiveSessionFile = sessionFile ?? latestSessionFile;
 	const runEndedAt = Date.now();
-	statusPayload.state = results.every((r) => r.success) ? "complete" : "failed";
+	statusPayload.state = interrupted ? "paused" : results.every((r) => r.success) ? "complete" : "failed";
+	statusPayload.activityState = undefined;
 	statusPayload.endedAt = runEndedAt;
 	statusPayload.lastUpdate = runEndedAt;
 	statusPayload.sessionFile = effectiveSessionFile;
@@ -1186,8 +1378,9 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		writeJson(resultPath, {
 			id,
 			agent: agentName,
-			success: results.every((r) => r.success),
-			summary,
+			success: !interrupted && results.every((r) => r.success),
+			state: interrupted ? "paused" : results.every((r) => r.success) ? "complete" : "failed",
+			summary: interrupted ? "Paused after interrupt. Waiting for explicit next action." : summary,
 			results: results.map((r) => ({
 				agent: r.agent,
 				output: r.output,
@@ -1199,7 +1392,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				artifactPaths: r.artifactPaths,
 				truncated: r.truncated,
 			})),
-			exitCode: results.every((r) => r.success) ? 0 : 1,
+			exitCode: interrupted || results.every((r) => r.success) ? 0 : 1,
 			timestamp: runEndedAt,
 			durationMs: runEndedAt - overallStartTime,
 			truncated,

package/subagents-status.ts

@@ -25,6 +25,7 @@ function statusColor(theme: Theme, status: AsyncRunSummary["state"]): string {
 		case "queued": return theme.fg("accent", status);
 		case "complete": return theme.fg("success", status);
 		case "failed": return theme.fg("error", status);
+		case "paused": return theme.fg("warning", status);
 	}
 }
 
@@ -33,6 +34,7 @@ function stepStatusColor(theme: Theme, status: string): string {
 	if (status === "pending") return theme.fg("dim", status);
 	if (status === "complete" || status === "completed") return theme.fg("success", status);
 	if (status === "failed") return theme.fg("error", status);
+	if (status === "paused") return theme.fg("warning", status);
 	return status;
 }
 
@@ -170,7 +172,12 @@ export class SubagentsStatusComponent implements Component {
 				: "";
 			const duration = step.durationMs !== undefined ? ` | ${formatDuration(step.durationMs)}` : "";
 			const tokens = step.tokens ? ` | ${formatTokens(step.tokens.total)} tok` : "";
-			const line = `  ${step.index + 1}. ${step.agent} | ${stepStatusColor(this.theme, step.status)}${model}${attempts}${duration}${tokens}`;
+			const activity = step.lastActivityAt
+				? step.activityState === "needs_attention"
+					? ` | no activity for ${formatDuration(Math.max(0, Date.now() - step.lastActivityAt))}`
+					: ` | active ${formatDuration(Math.max(0, Date.now() - step.lastActivityAt))} ago`
+				: "";
+			const line = `  ${step.index + 1}. ${step.agent} | ${stepStatusColor(this.theme, step.status)}${activity}${model}${attempts}${duration}${tokens}`;
 			lines.push(row(truncateToWidth(line, innerW), width, this.theme));
 			if (step.error) {
 				lines.push(row(truncateToWidth(`     ${step.error}`, innerW), width, this.theme));

package/types.ts

@@ -40,6 +40,35 @@ export interface TokenUsage {
 	total: number;
 }
 
+export type ActivityState = "needs_attention";
+export type ControlEventType = "needs_attention";
+export type ControlNotificationChannel = "event" | "async" | "intercom";
+
+export interface ControlConfig {
+	enabled?: boolean;
+	needsAttentionAfterMs?: number;
+	notifyOn?: ControlEventType[];
+	notifyChannels?: ControlNotificationChannel[];
+}
+
+export interface ResolvedControlConfig {
+	enabled: boolean;
+	needsAttentionAfterMs: number;
+	notifyOn: ControlEventType[];
+	notifyChannels: ControlNotificationChannel[];
+}
+
+export interface ControlEvent {
+	type: ControlEventType;
+	from?: ActivityState;
+	to: ActivityState;
+	ts: number;
+	agent: string;
+	index?: number;
+	runId: string;
+	message: string;
+}
+
 // ============================================================================
 // Progress Tracking
 // ============================================================================
@@ -48,6 +77,7 @@ export interface AgentProgress {
 	index: number;
 	agent: string;
 	status: "pending" | "running" | "completed" | "failed" | "detached";
+	activityState?: ActivityState;
 	task: string;
 	skills?: string[];
 	lastActivityAt?: number;
@@ -92,11 +122,13 @@ export interface SingleResult {
 	exitCode: number;
 	detached?: boolean;
 	detachedReason?: string;
+	interrupted?: boolean;
 	messages?: Message[];
 	usage: Usage;
 	model?: string;
 	attemptedModels?: string[];
 	modelAttempts?: ModelAttempt[];
+	controlEvents?: ControlEvent[];
 	error?: string;
 	sessionFile?: string;
 	skills?: string[];
@@ -115,6 +147,7 @@ export interface Details {
 	mode: "single" | "parallel" | "chain" | "management";
 	context?: "fresh" | "fork";
 	results: SingleResult[];
+	controlEvents?: ControlEvent[];
 	asyncId?: string;
 	asyncDir?: string;
 	progress?: AgentProgress[];
@@ -162,15 +195,26 @@ export interface ArtifactConfig {
 export interface AsyncStatus {
 	runId: string;
 	mode: "single" | "chain";
-	state: "queued" | "running" | "complete" | "failed";
+	state: "queued" | "running" | "complete" | "failed" | "paused";
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
 	startedAt: number;
 	endedAt?: number;
 	lastUpdate?: number;
+	pid?: number;
 	cwd?: string;
 	currentStep?: number;
 	steps?: Array<{
 		agent: string;
 		status: string;
+		activityState?: ActivityState;
+		lastActivityAt?: number;
+		currentTool?: string;
+		currentToolStartedAt?: number;
+		startedAt?: number;
+		endedAt?: number;
 		durationMs?: number;
 		tokens?: TokenUsage;
 		skills?: string[];
@@ -188,7 +232,11 @@ export interface AsyncStatus {
 export interface AsyncJobState {
 	asyncId: string;
 	asyncDir: string;
-	status: "queued" | "running" | "complete" | "failed";
+	status: "queued" | "running" | "complete" | "failed" | "paused";
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
 	mode?: "single" | "chain";
 	agents?: string[];
 	currentStep?: number;
@@ -199,12 +247,27 @@ export interface AsyncJobState {
 	outputFile?: string;
 	totalTokens?: TokenUsage;
 	sessionFile?: string;
+	controlEventCursor?: number;
 }
 
 export interface SubagentState {
 	baseCwd: string;
 	currentSessionId: string | null;
 	asyncJobs: Map<string, AsyncJobState>;
+	foregroundControls: Map<string, {
+		runId: string;
+		mode: "single" | "parallel" | "chain";
+		startedAt: number;
+		updatedAt: number;
+		currentAgent?: string;
+		currentIndex?: number;
+		currentActivityState?: ActivityState;
+		lastActivityAt?: number;
+		currentTool?: string;
+		currentToolStartedAt?: number;
+		interrupt?: () => boolean;
+	}>;
+	lastForegroundControlId: string | null;
 	cleanupTimers: Map<string, ReturnType<typeof setTimeout>>;
 	lastUiContext: ExtensionContext | null;
 	poller: NodeJS.Timeout | null;
@@ -243,6 +306,10 @@ export interface IntercomEventBus {
 
 export const INTERCOM_DETACH_REQUEST_EVENT = "pi-intercom:detach-request";
 export const INTERCOM_DETACH_RESPONSE_EVENT = "pi-intercom:detach-response";
+export const SUBAGENT_ASYNC_STARTED_EVENT = "subagent:async-started";
+export const SUBAGENT_ASYNC_COMPLETE_EVENT = "subagent:async-complete";
+export const SUBAGENT_CONTROL_EVENT = "subagent:control-event";
+export const SUBAGENT_CONTROL_INTERCOM_EVENT = "subagent:control-intercom";
 
 // ============================================================================
 // Execution Options
@@ -251,9 +318,13 @@ export const INTERCOM_DETACH_RESPONSE_EVENT = "pi-intercom:detach-response";
 export interface RunSyncOptions {
 	cwd?: string;
 	signal?: AbortSignal;
+	interruptSignal?: AbortSignal;
 	allowIntercomDetach?: boolean;
 	intercomEvents?: IntercomEventBus;
 	onUpdate?: (r: import("@mariozechner/pi-agent-core").AgentToolResult<Details>) => void;
+	onControlEvent?: (event: ControlEvent) => void;
+	controlConfig?: ResolvedControlConfig;
+	intercomSessionName?: string;
 	maxOutput?: MaxOutputConfig;
 	artifactsDir?: string;
 	artifactConfig?: ArtifactConfig;
@@ -291,6 +362,7 @@ export interface ExtensionConfig {
 	forceTopLevelAsync?: boolean;
 	defaultSessionDir?: string;
 	maxSubagentDepth?: number;
+	control?: ControlConfig;
 	parallel?: TopLevelParallelConfig;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;

package/utils.ts

@@ -231,6 +231,7 @@ function compactCompletedProgress(progress: AgentProgress): AgentProgress {
 		index: progress.index,
 		agent: progress.agent,
 		status: progress.status,
+		activityState: progress.activityState,
 		task: progress.task,
 		skills: progress.skills,
 		toolCount: progress.toolCount,