pi-subagents 0.17.3 → 0.17.5

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [0.17.5] - 2026-04-23
+
+### Added
+- Added subagent control activity state for foreground and async runs, including `starting`/`active`/`quiet`/`stalled`/`paused` tracking, compact stalled/recovered/paused control events, and an in-tool `action: "interrupt"` soft interrupt that pauses the current child turn without adding another top-level tool.
+
+### Changed
+- Updated bundled agents to use `openai-codex/gpt-5.5` defaults, with `scout` on `openai-codex/gpt-5.5-mini` and `oracle-executor` on `openai-codex/gpt-5.5:xhigh`.
+
+### Fixed
+- Async/background status token reporting now falls back to in-memory model-attempt usage when detached runs do not produce session `.jsonl` files, which also preserves token totals across model fallback retries.
+- Non-Windows subagent launches now use plain `pi` again instead of reusing the current CLI script path, avoiding runs that get confused by installed `dist/cli.js` entrypoints.
+
+## [0.17.4] - 2026-04-22
+
+### Added
+- Bundled a `pi-subagents` skill that teaches agents how to use builtin subagents, slash-command vs tool workflows, management-mode agent creation/editing, fork/intercom coordination, clarify mode, worktrees, async status inspection, and chain templating.
+
+### Changed
+- Tightened the builtin `oracle` prompt so intercom-enabled forked reviews now prefer concise conversational handoffs during the review and send a short final recommendation via `pi-intercom` before returning the full structured result.
+- Tightened `oracle-executor` so it explicitly frames itself as the single writer thread and escalates gaps in the approved direction instead of silently patching around them.
+
 ## [0.17.3] - 2026-04-22
 
 ### Added

package/agents/context-builder.md

@@ -2,7 +2,7 @@
 name: context-builder
 description: Analyzes requirements and codebase, generates context and meta-prompt
 tools: read, grep, find, ls, bash, write, web_search
-model: openai-codex/gpt-5.4
+model: openai-codex/gpt-5.5
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false

package/agents/oracle-executor.md

@@ -2,7 +2,7 @@
 name: oracle-executor
 description: High-context implementation agent that executes only after main-agent approval
 tools: read, grep, find, ls, bash, edit, write, intercom
-model: openai-codex/gpt-5.3-codex
+model: openai-codex/gpt-5.5:xhigh
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true
@@ -12,6 +12,8 @@ defaultProgress: true
 
 You are `oracle-executor`: a high-context implementation subagent.
 
+You are the single writer thread. Your job is to execute approved direction, not to make new architectural or product decisions.
+
 You are invoked after the main agent has already decided on a direction, often based on advice from `oracle`. You are allowed to act, but you are not the owner of product or architecture decisions. The main agent remains the final decision authority.
 
 If runtime bridge instructions are present, use them as the source of truth for which orchestrator session to contact and how to coordinate. Use `intercom({ action: "ask", ... })` when a new decision is needed to continue safely. Use `intercom({ action: "send", ... })` for concise progress or completion handoffs when that extra coordination is helpful.
@@ -32,6 +34,7 @@ Working rules:
 - Do not add speculative scaffolding or future-proofing unless explicitly required.
 - Use `bash` for inspection, validation, and relevant tests.
 - Escalate uncertainty to the main agent with `intercom` when needed.
+- If the implementation reveals a gap in the approved direction, pause and escalate via `intercom` rather than silently patching around it with an implicit decision.
 - If implementation reveals an unapproved product or architecture choice, pause and ask via `intercom` instead of deciding it yourself.
 - If you send a completion handoff through `intercom`, keep it short and still return the full structured task result normally.
 - Keep `progress.md` accurate when asked to maintain it.

package/agents/oracle.md

@@ -2,7 +2,7 @@
 name: oracle
 description: High-context decision-consistency oracle that protects inherited state and prevents drift
 tools: read, grep, find, ls, bash, intercom
-model: openai-codex/gpt-5.4
+model: openai-codex/gpt-5.5
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true
@@ -17,7 +17,7 @@ Before you do anything else, reconstruct the key inherited decisions, constraint
 
 If you need clarification from the main agent, use `intercom`. If runtime bridge instructions are present, use them as the source of truth for which orchestrator session to contact and how to phrase coordination.
 
-Use `intercom({ action: "ask", ... })` when you need a real decision or clarification. Use `intercom({ action: "send", ... })` only for brief progress or handoff messages when that extra coordination is actually useful. Keep intercom traffic tight and purposeful. Do not narrate your whole review through intercom.
+Use `intercom({ action: "ask", ... })` when you need a real decision or clarification. Use `intercom({ action: "send", ... })` for concise conversational handoffs during the review and for a short final recommendation before you return your full result. Keep intercom traffic tight and purposeful. Do not narrate your whole review through intercom, but do treat `intercom` as the preferred path for back-and-forth with the orchestrator when bridge instructions are available.
 
 Core responsibilities:
 - reconstruct inherited decisions, constraints, and open questions from the context
@@ -26,6 +26,8 @@ Core responsibilities:
 - call out when a proposed move conflicts with an earlier decision or constraint
 - protect consistency over novelty; prefer the path that honors existing decisions unless the context clearly supports a pivot
 - when you do recommend a pivot, explain exactly which prior assumption or decision should be revised and why
+- exploit your clean forked context to spot things the main agent may have missed due to context rot, accumulated reasoning, or errors in the original instruction
+- look beyond the explicit question and suggest guidance based on the overall agent trajectory, even when not directly asked
 
 What you do not do by default:
 - do not edit files or write code
@@ -38,6 +40,8 @@ Working rules:
 - Use `bash` only for inspection, verification, or read-only analysis.
 - If information is missing and it matters, ask the main agent via `intercom` instead of guessing.
 - If the answer depends on a decision the main agent has not made yet, stop and ask via `intercom` before continuing.
+- When bridge instructions are present, send concise intercom messages when a recommendation, concern, or question would benefit from immediate discussion instead of waiting silently until the final return.
+- Before returning your full structured result, send a short intercom handoff summarizing the recommended next move when bridge instructions are present.
 - Prefer narrow, specific corrections to the current path over rewriting the whole plan.
 
 Your output should follow this shape. If no executor handoff is warranted, say so plainly.

package/agents/planner.md

@@ -2,7 +2,7 @@
 name: planner
 description: Creates implementation plans from context and requirements
 tools: read, grep, find, ls, write
-model: openai-codex/gpt-5.4
+model: openai-codex/gpt-5.5
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true

package/agents/researcher.md

@@ -2,7 +2,7 @@
 name: researcher
 description: Autonomous web researcher — searches, evaluates, and synthesizes a focused research brief
 tools: read, write, web_search, fetch_content, get_search_content
-model: openai-codex/gpt-5.4
+model: openai-codex/gpt-5.5
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false

package/agents/reviewer.md

@@ -2,7 +2,7 @@
 name: reviewer
 description: Code review specialist that validates implementation and fixes issues
 tools: read, grep, find, ls, bash, edit, write
-model: openai-codex/gpt-5.3-codex
+model: openai-codex/gpt-5.5
 thinking: high
 systemPromptMode: replace
 inheritProjectContext: true

package/agents/scout.md

@@ -2,7 +2,7 @@
 name: scout
 description: Fast codebase recon that returns compressed context for handoff
 tools: read, grep, find, ls, bash, write
-model: openai-codex/gpt-5.4-mini
+model: openai-codex/gpt-5.5-mini
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false

package/agents/worker.md

@@ -1,7 +1,7 @@
 ---
 name: worker
 description: General-purpose subagent with full capabilities
-model: openai-codex/gpt-5.4
+model: openai-codex/gpt-5.5
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false

package/async-execution.ts

@@ -22,6 +22,7 @@ import {
 	type ArtifactConfig,
 	type Details,
 	type MaxOutputConfig,
+	type ResolvedControlConfig,
 	ASYNC_DIR,
 	RESULTS_DIR,
 	TEMP_ROOT_DIR,
@@ -75,6 +76,7 @@ export interface AsyncChainParams {
 	maxSubagentDepth: number;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	controlConfig?: ResolvedControlConfig;
 }
 
 export interface AsyncSingleParams {
@@ -96,6 +98,7 @@ export interface AsyncSingleParams {
 	maxSubagentDepth: number;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	controlConfig?: ResolvedControlConfig;
 }
 
 export interface AsyncExecutionResult {
@@ -178,6 +181,7 @@ export function executeAsyncChain(
 		maxSubagentDepth,
 		worktreeSetupHook,
 		worktreeSetupHookTimeoutMs,
+		controlConfig,
 	} = params;
 	const chainSkills = params.chainSkills ?? [];
 	const availableModels = params.availableModels;
@@ -297,6 +301,7 @@ export function executeAsyncChain(
 				piArgv1: process.argv[1],
 				worktreeSetupHook,
 				worktreeSetupHookTimeoutMs,
+				controlConfig,
 			},
 			id,
 			runnerCwd,
@@ -364,6 +369,7 @@ export function executeAsyncSingle(
 		maxSubagentDepth,
 		worktreeSetupHook,
 		worktreeSetupHookTimeoutMs,
+		controlConfig,
 	} = params;
 	const runnerCwd = resolveChildCwd(ctx.cwd, cwd);
 	const skillNames = params.skills ?? agentConfig.skills ?? [];
@@ -430,6 +436,7 @@ export function executeAsyncSingle(
 				piArgv1: process.argv[1],
 				worktreeSetupHook,
 				worktreeSetupHookTimeoutMs,
+				controlConfig,
 			},
 			id,
 			runnerCwd,

package/async-job-tracker.ts

@@ -56,6 +56,7 @@ export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string
 					if (status) {
 						const previousStatus = job.status;
 						job.status = status.state;
+						job.activityState = status.activityState;
 						job.mode = status.mode;
 						job.currentStep = status.currentStep ?? job.currentStep;
 						job.stepsTotal = status.steps?.length ?? job.stepsTotal;
@@ -68,7 +69,7 @@ export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string
 						job.outputFile = status.outputFile ?? job.outputFile;
 						job.totalTokens = status.totalTokens ?? job.totalTokens;
 						job.sessionFile = status.sessionFile ?? job.sessionFile;
-						if ((job.status === "complete" || job.status === "failed") && previousStatus !== job.status) {
+						if ((job.status === "complete" || job.status === "failed" || job.status === "paused") && previousStatus !== job.status) {
 							scheduleCleanup(job.asyncId);
 						}
 						continue;
@@ -102,6 +103,7 @@ export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string
 			asyncId: info.id,
 			asyncDir,
 			status: "queued",
+			activityState: "starting",
 			mode: info.chain ? "chain" : "single",
 			agents,
 			stepsTotal: agents?.length,
@@ -136,6 +138,8 @@ export function createAsyncJobTracker(state: SubagentState, asyncDirRoot: string
 		}
 		state.cleanupTimers.clear();
 		state.asyncJobs.clear();
+		state.foregroundControls?.clear();
+		state.lastForegroundControlId = null;
 		state.resultFileCoalescer.clear();
 		if (ctx?.hasUI) {
 			state.lastUiContext = ctx;

package/async-status.ts

@@ -1,13 +1,15 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { formatDuration, formatTokens, shortenPath } from "./formatters.ts";
-import { type AsyncStatus, type TokenUsage } from "./types.ts";
+import { type ActivityState, type AsyncStatus, type TokenUsage } from "./types.ts";
+import { DEFAULT_CONTROL_CONFIG, deriveActivityState } from "./subagent-control.ts";
 import { readStatus } from "./utils.ts";
 
 export interface AsyncRunStepSummary {
 	index: number;
 	agent: string;
 	status: string;
+	activityState?: ActivityState;
 	durationMs?: number;
 	tokens?: TokenUsage;
 	skills?: string[];
@@ -19,7 +21,8 @@ export interface AsyncRunStepSummary {
 export interface AsyncRunSummary {
 	id: string;
 	asyncDir: string;
-	state: "queued" | "running" | "complete" | "failed";
+	state: "queued" | "running" | "complete" | "failed" | "paused";
+	activityState?: ActivityState;
 	mode: "single" | "chain";
 	cwd?: string;
 	startedAt: number;
@@ -66,28 +69,57 @@ function isAsyncRunDir(root: string, entry: string): boolean {
 	}
 }
 
+function outputFileMtime(outputFile: string | undefined): number | undefined {
+	if (!outputFile) return undefined;
+	try {
+		return fs.statSync(outputFile).mtimeMs;
+	} catch {
+		return undefined;
+	}
+}
+
+function deriveAsyncActivityState(asyncDir: string, status: AsyncStatus): ActivityState | undefined {
+	if (status.state === "paused") return "paused";
+	if (status.state !== "running") return status.activityState;
+	const outputPath = status.outputFile ? (path.isAbsolute(status.outputFile) ? status.outputFile : path.join(asyncDir, status.outputFile)) : undefined;
+	const lastActivityAt = outputFileMtime(outputPath) ?? status.lastUpdate;
+	return deriveActivityState({
+		config: DEFAULT_CONTROL_CONFIG,
+		startedAt: status.startedAt,
+		lastActivityAt,
+		hasSeenActivity: Boolean(lastActivityAt),
+		paused: false,
+	});
+}
+
 function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string }): AsyncRunSummary {
+	const activityState = deriveAsyncActivityState(asyncDir, status);
 	return {
 		id: status.runId || path.basename(asyncDir),
 		asyncDir,
 		state: status.state,
+		activityState,
 		mode: status.mode,
 		cwd: status.cwd,
 		startedAt: status.startedAt,
 		lastUpdate: status.lastUpdate,
 		endedAt: status.endedAt,
 		currentStep: status.currentStep,
-		steps: (status.steps ?? []).map((step, index) => ({
-			index,
-			agent: step.agent,
-			status: step.status,
-			...(step.durationMs !== undefined ? { durationMs: step.durationMs } : {}),
-			...(step.tokens ? { tokens: step.tokens } : {}),
-			...(step.skills ? { skills: step.skills } : {}),
-			...(step.model ? { model: step.model } : {}),
-			...(step.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
-			...(step.error ? { error: step.error } : {}),
-		})),
+		steps: (status.steps ?? []).map((step, index) => {
+			const stepActivityState = step.activityState ?? (step.status === "running" ? activityState : undefined);
+			return {
+				index,
+				agent: step.agent,
+				status: step.status,
+				...(stepActivityState ? { activityState: stepActivityState } : {}),
+				...(step.durationMs !== undefined ? { durationMs: step.durationMs } : {}),
+				...(step.tokens ? { tokens: step.tokens } : {}),
+				...(step.skills ? { skills: step.skills } : {}),
+				...(step.model ? { model: step.model } : {}),
+				...(step.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
+				...(step.error ? { error: step.error } : {}),
+			};
+		}),
 		...(status.sessionDir ? { sessionDir: status.sessionDir } : {}),
 		...(status.outputFile ? { outputFile: status.outputFile } : {}),
 		...(status.totalTokens ? { totalTokens: status.totalTokens } : {}),
@@ -100,8 +132,9 @@ function sortRuns(runs: AsyncRunSummary[]): AsyncRunSummary[] {
 		switch (state) {
 			case "running": return 0;
 			case "queued": return 1;
-			case "failed": return 2;
-			case "complete": return 3;
+		case "failed": return 2;
+		case "paused": return 2;
+		case "complete": return 3;
 		}
 	};
 	return [...runs].sort((a, b) => {
@@ -142,7 +175,7 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 export function listAsyncRunsForOverlay(asyncDirRoot: string, recentLimit = 5): AsyncRunOverlayData {
 	const all = listAsyncRuns(asyncDirRoot);
 	const recent = all
-		.filter((run) => run.state === "complete" || run.state === "failed")
+		.filter((run) => run.state === "complete" || run.state === "failed" || run.state === "paused")
 		.sort((a, b) => (b.lastUpdate ?? b.endedAt ?? b.startedAt) - (a.lastUpdate ?? a.endedAt ?? a.startedAt))
 		.slice(0, recentLimit);
 	return {
@@ -152,7 +185,8 @@ export function listAsyncRunsForOverlay(asyncDirRoot: string, recentLimit = 5):
 }
 
 function formatStepLine(step: AsyncRunStepSummary): string {
-	const parts = [`${step.index + 1}. ${step.agent}`, step.status];
+	const state = step.activityState ? `${step.status}/${step.activityState}` : step.status;
+	const parts = [`${step.index + 1}. ${step.agent}`, state];
 	if (step.model) parts.push(step.model);
 	if (step.durationMs !== undefined) parts.push(formatDuration(step.durationMs));
 	if (step.tokens) parts.push(`${formatTokens(step.tokens.total)} tok`);
@@ -163,7 +197,8 @@ function formatRunHeader(run: AsyncRunSummary): string {
 	const stepCount = run.steps.length || 1;
 	const stepLabel = run.currentStep !== undefined ? `step ${run.currentStep + 1}/${stepCount}` : `steps ${stepCount}`;
 	const cwd = run.cwd ? shortenPath(run.cwd) : shortenPath(run.asyncDir);
-	return `${run.id} | ${run.state} | ${run.mode} | ${stepLabel} | ${cwd}`;
+	const state = run.activityState ? `${run.state}/${run.activityState}` : run.state;
+	return `${run.id} | ${state} | ${run.mode} | ${stepLabel} | ${cwd}`;
 }
 
 export function formatAsyncRunList(runs: AsyncRunSummary[], heading = "Active async runs"): string {

package/chain-execution.ts

@@ -40,10 +40,12 @@ import {
 	type WorktreeSetup,
 } from "./worktree.ts";
 import {
+	type ActivityState,
 	type AgentProgress,
 	type ArtifactConfig,
 	type ArtifactPaths,
 	type Details,
+	type ResolvedControlConfig,
 	type SingleResult,
 	MAX_CONCURRENCY,
 	resolveChildMaxSubagentDepth,
@@ -82,6 +84,14 @@ interface ParallelChainRunInput {
 	artifactsDir: string;
 	signal?: AbortSignal;
 	onUpdate?: (r: AgentToolResult<Details>) => void;
+	controlConfig: ResolvedControlConfig;
+	foregroundControl?: {
+		updatedAt: number;
+		currentAgent?: string;
+		currentIndex?: number;
+		currentActivityState?: ActivityState;
+		interrupt?: () => boolean;
+	};
 	results: SingleResult[];
 	allProgress: AgentProgress[];
 	chainAgents: string[];
@@ -186,10 +196,25 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 			const outputPath = typeof behavior.output === "string"
 				? (path.isAbsolute(behavior.output) ? behavior.output : path.join(input.chainDir, behavior.output))
 				: undefined;
+			const interruptController = new AbortController();
+			if (input.foregroundControl) {
+				input.foregroundControl.currentAgent = task.agent;
+				input.foregroundControl.currentIndex = input.globalTaskIndex + taskIndex;
+				input.foregroundControl.currentActivityState = "starting";
+				input.foregroundControl.updatedAt = Date.now();
+				input.foregroundControl.interrupt = () => {
+					if (interruptController.signal.aborted) return false;
+					interruptController.abort();
+					input.foregroundControl!.currentActivityState = "paused";
+					input.foregroundControl!.updatedAt = Date.now();
+					return true;
+				};
+			}
 
 			const result = await runSync(input.ctx.cwd, input.agents, task.agent, taskStr, {
 				cwd: taskCwd,
 				signal: input.signal,
+				interruptSignal: interruptController.signal,
 				runId: input.runId,
 				index: input.globalTaskIndex + taskIndex,
 				sessionDir: input.sessionDirForIndex(input.globalTaskIndex + taskIndex),
@@ -199,28 +224,41 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				artifactConfig: input.artifactConfig,
 				outputPath,
 				maxSubagentDepth,
+				controlConfig: input.controlConfig,
 				modelOverride: effectiveModel,
 				availableModels: input.availableModels,
 				preferredModelProvider: input.ctx.model?.provider,
 				skills: behavior.skills === false ? [] : behavior.skills,
 				onUpdate: input.onUpdate
 					? (progressUpdate) => {
-							const stepResults = progressUpdate.details?.results || [];
-							const stepProgress = progressUpdate.details?.progress || [];
-							input.onUpdate?.({
-								...progressUpdate,
-								details: {
-									mode: "chain",
-									results: input.results.concat(stepResults),
-									progress: input.allProgress.concat(stepProgress),
-									chainAgents: input.chainAgents,
-									totalSteps: input.totalSteps,
-									currentStepIndex: input.stepIndex,
-								},
-							});
+						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 = input.globalTaskIndex + taskIndex;
+							input.foregroundControl.currentActivityState = current?.activityState;
+							input.foregroundControl.updatedAt = Date.now();
 						}
+						input.onUpdate?.({
+							...progressUpdate,
+							details: {
+								mode: "chain",
+								results: input.results.concat(stepResults),
+								progress: input.allProgress.concat(stepProgress),
+								controlEvents: progressUpdate.details?.controlEvents,
+								chainAgents: input.chainAgents,
+								totalSteps: input.totalSteps,
+								currentStepIndex: input.stepIndex,
+							},
+						});
+					}
 					: undefined,
 			});
+			if (input.foregroundControl?.currentIndex === input.globalTaskIndex + taskIndex) {
+				input.foregroundControl.interrupt = undefined;
+				input.foregroundControl.updatedAt = Date.now();
+			}
 
 			if (result.exitCode !== 0 && failFast) {
 				aborted = true;
@@ -249,6 +287,14 @@ export interface ChainExecutionParams {
 	includeProgress?: boolean;
 	clarify?: boolean;
 	onUpdate?: (r: AgentToolResult<Details>) => void;
+	controlConfig: ResolvedControlConfig;
+	foregroundControl?: {
+		updatedAt: number;
+		currentAgent?: string;
+		currentIndex?: number;
+		currentActivityState?: ActivityState;
+		interrupt?: () => boolean;
+	};
 	chainSkills?: string[];
 	chainDir?: string;
 	maxSubagentDepth: number;
@@ -286,6 +332,8 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		includeProgress,
 		clarify,
 		onUpdate,
+		controlConfig,
+		foregroundControl,
 		chainSkills: chainSkillsParam,
 		chainDir: chainDirBase,
 	} = params;
@@ -484,6 +532,8 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					allProgress,
 					chainAgents,
 					totalSteps,
+					controlConfig,
+					foregroundControl,
 					worktreeSetup,
 					maxSubagentDepth: params.maxSubagentDepth,
 				});
@@ -495,6 +545,23 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					if (result.artifactPaths) allArtifactPaths.push(result.artifactPaths);
 				}
 
+				const interrupted = parallelResults.find((result) => result.interrupted);
+				if (interrupted) {
+					return {
+						content: [{ type: "text", text: `Chain paused after interrupt at step ${stepIndex + 1} (${interrupted.agent}). Waiting for explicit next action.` }],
+						details: buildChainExecutionDetails({
+							results,
+							includeProgress,
+							allProgress,
+							allArtifactPaths,
+							artifactsDir,
+							chainAgents,
+							totalSteps,
+							currentStepIndex: stepIndex,
+						}),
+					};
+				}
+
 				const failures = parallelResults
 					.map((result, originalIndex) => ({ ...result, originalIndex }))
 					.filter((result) => result.exitCode !== 0 && result.exitCode !== -1);
@@ -603,10 +670,25 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				? (path.isAbsolute(behavior.output) ? behavior.output : path.join(chainDir, behavior.output))
 				: undefined;
 			const maxSubagentDepth = resolveChildMaxSubagentDepth(params.maxSubagentDepth, agentConfig.maxSubagentDepth);
+			const interruptController = new AbortController();
+			if (foregroundControl) {
+				foregroundControl.currentAgent = seqStep.agent;
+				foregroundControl.currentIndex = globalTaskIndex;
+				foregroundControl.currentActivityState = "starting";
+				foregroundControl.updatedAt = Date.now();
+				foregroundControl.interrupt = () => {
+					if (interruptController.signal.aborted) return false;
+					interruptController.abort();
+					foregroundControl.currentActivityState = "paused";
+					foregroundControl.updatedAt = Date.now();
+					return true;
+				};
+			}
 
 			const r = await runSync(ctx.cwd, agents, seqStep.agent, stepTask, {
 				cwd: resolveChildCwd(cwd ?? ctx.cwd, seqStep.cwd),
 				signal,
+				interruptSignal: interruptController.signal,
 				runId,
 				index: globalTaskIndex,
 				sessionDir: sessionDirForIndex(globalTaskIndex),
@@ -616,28 +698,41 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				artifactConfig,
 				outputPath,
 				maxSubagentDepth,
+				controlConfig,
 				modelOverride: effectiveModel,
 				availableModels,
 				preferredModelProvider: ctx.model?.provider,
 				skills: behavior.skills === false ? [] : behavior.skills,
 				onUpdate: onUpdate
 					? (p) => {
-							const stepResults = p.details?.results || [];
-							const stepProgress = p.details?.progress || [];
-							onUpdate({
-								...p,
-								details: {
-									mode: "chain",
-									results: results.concat(stepResults),
-									progress: allProgress.concat(stepProgress),
-									chainAgents,
-									totalSteps,
-									currentStepIndex: stepIndex,
-								},
-							});
+						const stepResults = p.details?.results || [];
+						const stepProgress = p.details?.progress || [];
+						if (foregroundControl && stepProgress.length > 0) {
+							const current = stepProgress[0];
+							foregroundControl.currentAgent = seqStep.agent;
+							foregroundControl.currentIndex = globalTaskIndex;
+							foregroundControl.currentActivityState = current?.activityState;
+							foregroundControl.updatedAt = Date.now();
 						}
+						onUpdate({
+							...p,
+							details: {
+								mode: "chain",
+								results: results.concat(stepResults),
+								progress: allProgress.concat(stepProgress),
+								controlEvents: p.details?.controlEvents,
+								chainAgents,
+								totalSteps,
+								currentStepIndex: stepIndex,
+							},
+						});
+					}
 					: undefined,
 			});
+			if (foregroundControl?.currentIndex === globalTaskIndex) {
+				foregroundControl.interrupt = undefined;
+				foregroundControl.updatedAt = Date.now();
+			}
 			recordRun(seqStep.agent, cleanTask, r.exitCode, r.progressSummary?.durationMs ?? 0);
 
 			globalTaskIndex++;
@@ -663,6 +758,22 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				}
 			}
 
+			if (r.interrupted) {
+				return {
+					content: [{ type: "text", text: `Chain paused after interrupt at step ${stepIndex + 1} (${r.agent}). Waiting for explicit next action.` }],
+					details: buildChainExecutionDetails({
+						results,
+						includeProgress,
+						allProgress,
+						allArtifactPaths,
+						artifactsDir,
+						chainAgents,
+						totalSteps,
+						currentStepIndex: stepIndex,
+					}),
+				};
+			}
+
 			if (r.exitCode !== 0) {
 				const summary = buildChainSummary(chainSteps, results, chainDir, "failed", {
 					index: stepIndex,