pi-subagents 0.17.4 → 0.17.5

package/execution.ts

@@ -14,6 +14,7 @@ import {
 import {
 	type AgentProgress,
 	type ArtifactPaths,
+	type ControlEvent,
 	type ModelAttempt,
 	type RunSyncOptions,
 	type SingleResult,
@@ -24,6 +25,12 @@ import {
 	truncateOutput,
 	getSubagentDepthEnv,
 } from "./types.ts";
+import {
+	DEFAULT_CONTROL_CONFIG,
+	buildControlEvent,
+	deriveActivityState,
+	shouldEmitControlEvent,
+} from "./subagent-control.ts";
 import {
 	getFinalOutput,
 	findLatestSessionFile,
@@ -86,6 +93,7 @@ function snapshotResult(result: SingleResult, progress: AgentProgress): SingleRe
 				usage: attempt.usage ? { ...attempt.usage } : undefined,
 			}))
 			: undefined,
+		controlEvents: result.controlEvents ? result.controlEvents.map((event) => ({ ...event })) : undefined,
 		progress,
 		progressSummary: result.progressSummary ? { ...result.progressSummary } : undefined,
 		artifactPaths: result.artifactPaths ? { ...result.artifactPaths } : undefined,
@@ -140,11 +148,19 @@ async function runSingleAttempt(
 		skills: shared.resolvedSkillNames,
 		skillsWarning: shared.skillsWarning,
 	};
+	const startTime = Date.now();
+	const controlConfig = options.controlConfig ?? DEFAULT_CONTROL_CONFIG;
+	let hasSeenActivity = false;
+	let pausedByInterrupt = false;
+	let interruptedByControl = false;
+	const allControlEvents: ControlEvent[] = [];
+	let pendingControlEvents: ControlEvent[] = [];
 
 	const progress: AgentProgress = {
 		index: options.index ?? 0,
 		agent: agent.name,
 		status: "running",
+		activityState: controlConfig.enabled ? "starting" : undefined,
 		task,
 		skills: shared.resolvedSkillNames,
 		recentTools: [],
@@ -152,11 +168,9 @@ async function runSingleAttempt(
 		toolCount: 0,
 		tokens: 0,
 		durationMs: 0,
-		lastActivityAt: Date.now(),
+		lastActivityAt: startTime,
 	};
 	result.progress = progress;
-
-	const startTime = Date.now();
 	const spawnEnv = { ...process.env, ...sharedEnv, ...getSubagentDepthEnv(options.maxSubagentDepth) };
 
 	const exitCode = await new Promise<number>((resolve) => {
@@ -173,6 +187,8 @@ async function runSingleAttempt(
 		let detached = false;
 		let intercomStarted = false;
 		let removeAbortListener: (() => void) | undefined;
+		let removeInterruptListener: (() => void) | undefined;
+		let activityTimer: NodeJS.Timeout | undefined;
 
 		const detachForIntercom = () => {
 			detached = true;
@@ -241,18 +257,64 @@ async function runSingleAttempt(
 			settled = true;
 			clearFinalDrainTimers();
 			clearStdioGuard();
+			if (activityTimer) {
+				clearInterval(activityTimer);
+				activityTimer = undefined;
+			}
 			unsubscribeIntercomDetach?.();
 			removeAbortListener?.();
+			removeInterruptListener?.();
 			resolve(code);
 		};
 
+		const drainPendingControlEvents = (): ControlEvent[] | undefined => {
+			if (pendingControlEvents.length === 0) return undefined;
+			const events = pendingControlEvents;
+			pendingControlEvents = [];
+			return events;
+		};
+
+		const updateActivityState = (now: number): boolean => {
+			const next = deriveActivityState({
+				config: controlConfig,
+				startedAt: startTime,
+				lastActivityAt: progress.lastActivityAt,
+				hasSeenActivity,
+				paused: pausedByInterrupt,
+				now,
+			});
+			if (!next || next === progress.activityState) return false;
+			const previous = progress.activityState;
+			progress.activityState = next;
+			if (shouldEmitControlEvent(controlConfig, previous, next)) {
+				const event = buildControlEvent({
+					from: previous,
+					to: next,
+					runId: options.runId,
+					agent: agent.name,
+					index: options.index,
+					ts: now,
+				});
+				allControlEvents.push(event);
+				pendingControlEvents.push(event);
+				options.onControlEvent?.(event);
+			}
+			return true;
+		};
+
 		const emitUpdateSnapshot = (text: string) => {
 			if (!options.onUpdate || processClosed) return;
 			const progressSnapshot = snapshotProgress(progress);
 			const resultSnapshot = snapshotResult(result, progressSnapshot);
+			const controlEvents = drainPendingControlEvents();
 			options.onUpdate({
 				content: [{ type: "text", text }],
-				details: { mode: "single", results: [resultSnapshot], progress: [progressSnapshot] },
+				details: {
+					mode: "single",
+					results: [resultSnapshot],
+					progress: [progressSnapshot],
+					controlEvents,
+				},
 			});
 		};
 
@@ -276,6 +338,8 @@ async function runSingleAttempt(
 			const now = Date.now();
 			progress.durationMs = now - startTime;
 			progress.lastActivityAt = now;
+			hasSeenActivity = true;
+			updateActivityState(now);
 
 			if (evt.type === "tool_execution_start") {
 				if (options.allowIntercomDetach && evt.toolName === "intercom") {
@@ -336,6 +400,18 @@ async function runSingleAttempt(
 			}
 		};
 
+		if (controlConfig.enabled) {
+			activityTimer = setInterval(() => {
+				if (processClosed || settled || detached) return;
+				const now = Date.now();
+				if (updateActivityState(now)) {
+					progress.durationMs = now - startTime;
+					fireUpdate();
+				}
+			}, 1000);
+			activityTimer.unref?.();
+		}
+
 		let stderrBuf = "";
 
 		const clearStdioGuard = attachPostExitStdioGuard(proc, { idleMs: 2000, hardMs: 8000 });
@@ -400,8 +476,62 @@ async function runSingleAttempt(
 				removeAbortListener = () => options.signal?.removeEventListener("abort", kill);
 			}
 		}
+
+		if (options.interruptSignal) {
+			const interrupt = () => {
+				if (processClosed || detached || settled) return;
+				interruptedByControl = true;
+				pausedByInterrupt = true;
+				progress.status = "running";
+				progress.durationMs = Date.now() - startTime;
+				result.interrupted = true;
+				result.finalOutput = "Interrupted. Waiting for explicit next action.";
+				const now = Date.now();
+				const previous = progress.activityState;
+				progress.activityState = "paused";
+				if (shouldEmitControlEvent(controlConfig, previous, "paused")) {
+					const event = buildControlEvent({
+						from: previous,
+						to: "paused",
+						runId: options.runId,
+						agent: agent.name,
+						index: options.index,
+						ts: now,
+					});
+					allControlEvents.push(event);
+					pendingControlEvents.push(event);
+					options.onControlEvent?.(event);
+				}
+				fireUpdate();
+				trySignalChild(proc, "SIGINT");
+				setTimeout(() => {
+					if (settled || processClosed || detached) return;
+					trySignalChild(proc, "SIGTERM");
+				}, 1000).unref?.();
+			};
+			if (options.interruptSignal.aborted) interrupt();
+			else {
+				options.interruptSignal.addEventListener("abort", interrupt, { once: true });
+				removeInterruptListener = () => options.interruptSignal?.removeEventListener("abort", interrupt);
+			}
+		}
 	});
 	result.exitCode = exitCode;
+	if (interruptedByControl) {
+		result.exitCode = 0;
+		result.interrupted = true;
+		result.error = undefined;
+		result.finalOutput = result.finalOutput || "Interrupted. Waiting for explicit next action.";
+		result.controlEvents = allControlEvents.length ? allControlEvents : undefined;
+		progress.activityState = "paused";
+		progress.durationMs = Date.now() - startTime;
+		result.progressSummary = {
+			toolCount: progress.toolCount,
+			tokens: progress.tokens,
+			durationMs: progress.durationMs,
+		};
+		return result;
+	}
 	if (result.detached) {
 		result.exitCode = 0;
 		result.finalOutput = "Detached for intercom coordination.";

package/index.ts

@@ -153,6 +153,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		baseCwd: process.cwd(),
 		currentSessionId: null,
 		asyncJobs: new Map(),
+		foregroundControls: new Map(),
+		lastForegroundControlId: null,
 		cleanupTimers: new Map(),
 		lastUiContext: null,
 		poller: null,
@@ -265,11 +267,14 @@ Example: { chain: [{agent:"scout", task:"Analyze {task}"}, {agent:"planner", tas
 
 MANAGEMENT (use action field, omit agent/task/chain/tasks):
 • { action: "list" } - discover agents/chains
-• { action: "get", agent: "name" } - full agent detail
+• { action: "get", agent: "name" } - full detail
 • { action: "create", config: { name, systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, ... } }
 • { action: "update", agent: "name", config: { ... } } - merge
 • { action: "delete", agent: "name" }
-• Use chainName for chain operations`,
+• Use chainName for chain operations
+
+CONTROL:
+• { action: "interrupt", runId?: "..." } - soft-interrupt the current child turn and leave the run paused`, 
 		parameters: SubagentParams,
 
 		execute(id, params, signal, onUpdate, ctx) {
@@ -389,13 +394,17 @@ MANAGEMENT (use action field, omit agent/task/chain/tasks):
 
 					const lines = [
 						`Run: ${status.runId}`,
-						`State: ${status.state}`,
+						`State: ${status.activityState ? `${status.state}/${status.activityState}` : status.state}`,
 						`Mode: ${status.mode}`,
 						stepLine,
 						`Started: ${started}`,
 						`Updated: ${updated}`,
 						`Dir: ${asyncDir}`,
 					];
+					for (const [index, step] of (status.steps ?? []).entries()) {
+						const stepState = step.activityState ? `${step.status}/${step.activityState}` : step.status;
+						lines.push(`Step ${index + 1}: ${step.agent} ${stepState}`);
+					}
 					if (status.sessionFile) lines.push(`Session: ${status.sessionFile}`);
 					if (fs.existsSync(logPath)) lines.push(`Log: ${logPath}`);
 					if (fs.existsSync(eventsPath)) lines.push(`Events: ${eventsPath}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.17.4",
+  "version": "0.17.5",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/pi-spawn.ts

@@ -83,12 +83,15 @@ export function resolveWindowsPiCliScript(deps: PiSpawnDeps = {}): string | unde
 }
 
 export function getPiSpawnCommand(args: string[], deps: PiSpawnDeps = {}): PiSpawnCommand {
-	const piCliPath = resolveWindowsPiCliScript(deps);
-	if (piCliPath) {
-		return {
-			command: deps.execPath ?? process.execPath,
-			args: [piCliPath, ...args],
-		};
+	const platform = deps.platform ?? process.platform;
+	if (platform === "win32") {
+		const piCliPath = resolveWindowsPiCliScript(deps);
+		if (piCliPath) {
+			return {
+				command: deps.execPath ?? process.execPath,
+				args: [piCliPath, ...args],
+			};
+		}
 	}
 
 	return { command: "pi", args };

package/render.ts

@@ -83,7 +83,7 @@ let lastWidgetHash = "";
 
 function computeWidgetHash(jobs: AsyncJobState[]): string {
 	return jobs.slice(0, MAX_WIDGET_JOBS).map(job =>
-		`${job.asyncId}:${job.status}:${job.currentStep}:${job.updatedAt}:${job.totalTokens?.total ?? 0}`
+		`${job.asyncId}:${job.status}:${job.activityState}:${job.currentStep}:${job.updatedAt}:${job.totalTokens?.total ?? 0}`
 	).join("|");
 }
 
@@ -142,6 +142,11 @@ function buildLiveStatusLine(progress: Pick<AgentProgress, "lastActivityAt">): s
 	return formatActivityLabel(progress.lastActivityAt);
 }
 
+function formatActivityState(state: AgentProgress["activityState"]): string | undefined {
+	if (!state) return undefined;
+	return `activity: ${state}`;
+}
+
 /**
  * Render the async jobs widget
  */
@@ -175,7 +180,9 @@ export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void
 				? theme.fg("success", "complete")
 				: job.status === "failed"
 					? theme.fg("error", "failed")
-					: theme.fg("warning", "running");
+					: job.status === "paused"
+						? theme.fg("warning", "paused")
+						: theme.fg("warning", "running");
 
 		const stepsTotal = job.stepsTotal ?? (job.agents?.length ?? 1);
 		const stepIndex = job.currentStep !== undefined ? job.currentStep + 1 : undefined;
@@ -185,12 +192,12 @@ export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void
 		const agentLabel = job.agents ? job.agents.join(" -> ") : (job.mode ?? "single");
 
 		const tokenText = job.totalTokens ? ` | ${formatTokens(job.totalTokens.total)} tok` : "";
-		const activityText = job.status === "running" ? getLastActivity(job.outputFile) : "";
+		const activityText = job.activityState ?? (job.status === "running" ? getLastActivity(job.outputFile) : "");
 		const activitySuffix = activityText ? ` | ${theme.fg("dim", activityText)}` : "";
 
 		lines.push(truncLine(`- ${id} ${status} | ${agentLabel} | ${stepText}${elapsed ? ` | ${elapsed}` : ""}${tokenText}${activitySuffix}`, w));
 
-		if (job.status === "running" && job.outputFile) {
+		if ((job.status === "running" || job.status === "paused") && job.outputFile) {
 			const tail = getOutputTail(job.outputFile, 3);
 			for (const line of tail) {
 				lines.push(truncLine(theme.fg("dim", `  > ${line}`), w));
@@ -259,6 +266,10 @@ export function renderSubagentResult(
 			if (toolLine) {
 				c.addChild(new Text(fit(theme.fg("warning", `> ${toolLine}`)), 0, 0));
 			}
+			const activityStateLine = formatActivityState(r.progress.activityState);
+			if (activityStateLine) {
+				c.addChild(new Text(fit(theme.fg("accent", activityStateLine)), 0, 0));
+			}
 			const liveStatusLine = buildLiveStatusLine(r.progress);
 			if (liveStatusLine) {
 				c.addChild(new Text(fit(theme.fg("accent", liveStatusLine)), 0, 0));
@@ -467,6 +478,10 @@ export function renderSubagentResult(
 			if (toolLine) {
 				c.addChild(new Text(fit(theme.fg("warning", `    > ${toolLine}`)), 0, 0));
 			}
+			const activityStateLine = formatActivityState(rProg.activityState);
+			if (activityStateLine) {
+				c.addChild(new Text(fit(theme.fg("accent", `    ${activityStateLine}`)), 0, 0));
+			}
 			const liveStatusLine = buildLiveStatusLine(rProg);
 			if (liveStatusLine) {
 				c.addChild(new Text(fit(theme.fg("accent", `    ${liveStatusLine}`)), 0, 0));

package/schemas.ts

@@ -57,12 +57,22 @@ export const ParallelStepSchema = Type.Object({
 // Note: Using Type.Any() for Google API compatibility (doesn't support anyOf)
 export const ChainItem = Type.Any({ description: "Chain step: either {agent, task?, ...} for sequential or {parallel: [...]} for concurrent execution" });
 
+export const ControlOverrides = Type.Object({
+	enabled: Type.Optional(Type.Boolean({ description: "Enable/disable subagent control activity tracking for this run" })),
+	quietAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "Idle window before activity moves from active to quiet" })),
+	stalledAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "Idle window before activity moves from quiet to stalled" })),
+	parentMode: Type.Optional(Type.String({ enum: ["transitions", "verbose"], description: "Parent-visible control event mode" })),
+});
+
 export const SubagentParams = Type.Object({
 	agent: Type.Optional(Type.String({ description: "Agent name (SINGLE mode) or target for management get/update/delete" })),
 	task: Type.Optional(Type.String({ description: "Task (SINGLE mode)" })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({
-		description: "Management action: 'list' (discover agents/chains), 'get' (full detail), 'create', 'update', 'delete'. Omit for execution mode."
+		description: "Action: management ('list','get','create','update','delete') or control ('interrupt'). Omit for execution mode."
+	})),
+	runId: Type.Optional(Type.String({
+		description: "Target run ID for action='interrupt'. Defaults to the most recently active controllable run in this session."
 	})),
 	// Chain identifier for management (can't reuse 'chain' — that's the execution array)
 	chainName: Type.Optional(Type.String({
@@ -96,6 +106,7 @@ export const SubagentParams = Type.Object({
 	),
 	// Clarification TUI
 	clarify: Type.Optional(Type.Boolean({ description: "Show TUI to preview/edit before execution (default: true for chains, false for single/parallel). Implies sync mode." })),
+	control: Type.Optional(ControlOverrides),
 	// Solo agent overrides
 	output: Type.Optional(Type.Any({ description: "Output file for single agent (string), or false to disable. Relative paths resolve against cwd." })),
 	skill: Type.Optional(SkillOverride),

package/skills/pi-subagents/SKILL.md

@@ -20,6 +20,7 @@ agents into a workflow, or create/edit agents and chains on demand.
 - **Recon and planning**: use `scout` or `context-builder`, then `planner`
 - **Parallel exploration**: run multiple non-conflicting tasks concurrently
 - **Long-running work**: launch async/background runs and inspect them later
+- **Subagent control**: watch clear stalled/paused signals and soft-interrupt only when a delegated run is genuinely blocked
 - **Agent authoring**: create, update, or override agents and chains for a project
 
 ## Tool vs Slash Commands
@@ -147,6 +148,40 @@ subagent({
 Inspect async runs with the `subagent_status(...)` tool or the
 `/subagents-status` slash command.
 
+### Subagent control
+
+Subagent control is the runtime visibility and intervention layer for delegated runs. It is separate from lifecycle status. Lifecycle status says whether a child is `running`, `completed`, `failed`, or detached. Activity state says what the child appears to be doing right now: `starting`, `active`, `quiet`, `stalled`, or `paused`.
+
+Default behavior is intentionally conservative. Routine `active` and `quiet` updates are mostly UI/status information. Clear transitions such as `stalled`, `recovered`, and `paused` are the signals worth acting on.
+
+Use soft interrupt when a child is clearly blocked or drifting and the parent needs to regain control:
+
+```typescript
+subagent({ action: "interrupt" })
+```
+
+Pass `runId` when targeting a specific controllable run:
+
+```typescript
+subagent({ action: "interrupt", runId: "abc123" })
+```
+
+A soft interrupt cancels the current child turn and leaves the run paused. It does not mean the delegated task succeeded or failed. After an interrupt, decide the next explicit action: resume with clearer instructions, replace the task, ask the user, or stop the workflow.
+
+Per-run control thresholds can be overridden when a task legitimately runs quiet for longer than usual:
+
+```typescript
+subagent({
+  agent: "worker",
+  task: "Run the slow migration test suite",
+  control: {
+    quietAfterMs: 60000,
+    stalledAfterMs: 300000,
+    parentMode: "transitions"
+  }
+})
+```
+
 ## Clarify TUI
 
 Single and parallel runs support a clarification TUI when you want to preview or
@@ -334,6 +369,7 @@ particular agent or with forked context.
   filtered contexts.
 - **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked
   unless configured otherwise.
+- **Control state is not lifecycle state.** `paused` means the child turn was intentionally interrupted or is awaiting direction; it is not the same as `failed`.
 - **Intercom asks are blocking.** A session can only maintain one pending outbound
   ask wait state at a time.
 - **Keep conversational authority clear.** Advisory subagents should not silently
@@ -362,6 +398,10 @@ Give subagents specific tasks rather than vague mandates.
 If a subagent encounters an unapproved product, architecture, or scope choice,
 it should coordinate back via `intercom` instead of deciding alone.
 
+### Intervene only on clear control signals
+
+Use subagent control proactively when a delegated run is explicitly `stalled` or `paused`, or when a human asks you to regain control. Do not interrupt just because a child is briefly `quiet`. Quiet can be normal during long tool calls, test runs, or model reasoning.
+
 ### Name sessions meaningfully
 
 Use `/name` so intercom targeting stays stable.

package/slash-live-state.ts

@@ -63,6 +63,7 @@ function createPlaceholderResult(
 			...(index !== undefined ? { index } : {}),
 			agent,
 			status,
+			activityState: status === "running" ? "starting" : undefined,
 			task,
 			recentTools: [],
 			recentOutput: [],
@@ -85,6 +86,7 @@ function buildParallelInitialResult(params: SubagentParamsLike): AgentToolResult
 				index,
 				agent: task.agent,
 				status: "running" as const,
+				activityState: "starting" as const,
 				task: task.task,
 				recentTools: [],
 				recentOutput: [],
@@ -140,6 +142,7 @@ function buildChainInitialResult(params: SubagentParamsLike): AgentToolResult<De
 				index,
 				agent: result.agent,
 				status: index === 0 ? "running" as const : "pending" as const,
+				activityState: index === 0 ? "starting" as const : undefined,
 				task: result.task,
 				recentTools: [],
 				recentOutput: [],
@@ -166,6 +169,7 @@ function buildSingleInitialResult(params: SubagentParamsLike): AgentToolResult<D
 			progress: [{
 				agent,
 				status: "running",
+				activityState: "starting",
 				task,
 				recentTools: [],
 				recentOutput: [],

package/subagent-control.ts

@@ -0,0 +1,106 @@
+import {
+	type ActivityState,
+	type ControlConfig,
+	type ControlEvent,
+	type ControlEventType,
+	type ResolvedControlConfig,
+} from "./types.ts";
+
+export const DEFAULT_CONTROL_CONFIG: ResolvedControlConfig = {
+	enabled: true,
+	quietAfterMs: 15_000,
+	stalledAfterMs: 60_000,
+	parentMode: "transitions",
+};
+
+function parsePositiveInt(value: unknown): number | undefined {
+	if (typeof value !== "number") return undefined;
+	if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) return undefined;
+	return value;
+}
+
+export function resolveControlConfig(
+	globalConfig?: ControlConfig,
+	override?: ControlConfig,
+): ResolvedControlConfig {
+	const enabled = override?.enabled ?? globalConfig?.enabled ?? DEFAULT_CONTROL_CONFIG.enabled;
+	const quietAfterMs = parsePositiveInt(override?.quietAfterMs)
+		?? parsePositiveInt(globalConfig?.quietAfterMs)
+		?? DEFAULT_CONTROL_CONFIG.quietAfterMs;
+	const stalledAfterRaw = parsePositiveInt(override?.stalledAfterMs)
+		?? parsePositiveInt(globalConfig?.stalledAfterMs)
+		?? DEFAULT_CONTROL_CONFIG.stalledAfterMs;
+	const parentMode = override?.parentMode ?? globalConfig?.parentMode ?? DEFAULT_CONTROL_CONFIG.parentMode;
+	const stalledAfterMs = Math.max(stalledAfterRaw, quietAfterMs + 1);
+	return {
+		enabled,
+		quietAfterMs,
+		stalledAfterMs,
+		parentMode: parentMode === "verbose" ? "verbose" : "transitions",
+	};
+}
+
+export function deriveActivityState(input: {
+	config: ResolvedControlConfig;
+	startedAt: number;
+	lastActivityAt?: number;
+	hasSeenActivity: boolean;
+	paused: boolean;
+	now?: number;
+}): ActivityState | undefined {
+	if (!input.config.enabled) return undefined;
+	if (input.paused) return "paused";
+	if (!input.hasSeenActivity) return "starting";
+	const now = input.now ?? Date.now();
+	const lastActivity = input.lastActivityAt ?? input.startedAt;
+	const ageMs = Math.max(0, now - lastActivity);
+	if (ageMs <= input.config.quietAfterMs) return "active";
+	if (ageMs <= input.config.stalledAfterMs) return "quiet";
+	return "stalled";
+}
+
+function controlEventType(from: ActivityState | undefined, to: ActivityState): ControlEventType {
+	if (to === "stalled") return "stalled";
+	if (to === "paused") return "paused";
+	if (from === "stalled" && to !== "stalled") return "recovered";
+	if (from === "paused" && to !== "paused") return "resumed";
+	return "activity";
+}
+
+export function shouldEmitControlEvent(
+	config: ResolvedControlConfig,
+	from: ActivityState | undefined,
+	to: ActivityState,
+): boolean {
+	if (!config.enabled || from === to) return false;
+	if (config.parentMode === "verbose") return true;
+	if (to === "stalled" || to === "paused") return true;
+	if (from === "stalled" && to !== "stalled") return true;
+	if (from === "paused" && to !== "paused") return true;
+	return false;
+}
+
+export function buildControlEvent(input: {
+	from: ActivityState | undefined;
+	to: ActivityState;
+	runId: string;
+	agent: string;
+	index?: number;
+	ts?: number;
+}): ControlEvent {
+	const ts = input.ts ?? Date.now();
+	const type = controlEventType(input.from, input.to);
+	const message = input.from
+		? `${input.agent} ${type} (${input.from} -> ${input.to})`
+		: `${input.agent} ${type} (${input.to})`;
+	return {
+		type,
+		from: input.from,
+		to: input.to,
+		ts,
+		runId: input.runId,
+		agent: input.agent,
+		index: input.index,
+		message,
+	};
+}