pi-subagents 0.17.5 → 0.18.0

package/result-watcher.ts

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { buildCompletionKey, markSeenWithTtl } from "./completion-dedupe.js";
 import { createFileCoalescer } from "./file-coalescer.js";
-import type { SubagentState } from "./types.js";
+import { SUBAGENT_ASYNC_COMPLETE_EVENT, type SubagentState } from "./types.js";
 
 function isNotFoundError(error: unknown): boolean {
 	return typeof error === "object"
@@ -36,13 +36,11 @@ export function createResultWatcher(
 			const now = Date.now();
 			const completionKey = buildCompletionKey(data, `result:${file}`);
 			if (markSeenWithTtl(state.completionSeen, completionKey, now, completionTtlMs)) {
-				try {
-					fs.unlinkSync(resultPath);
-				} catch {}
+				fs.unlinkSync(resultPath);
 				return;
 			}
 
-			pi.events.emit("subagent:complete", data);
+			pi.events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, data);
 			fs.unlinkSync(resultPath);
 		} catch (error) {
 			if (isNotFoundError(error)) return;

package/run-status.ts

@@ -0,0 +1,134 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import { formatAsyncRunList, listAsyncRuns } from "./async-status.ts";
+import { ASYNC_DIR, RESULTS_DIR, type Details } from "./types.ts";
+import { findByPrefix, readStatus } from "./utils.ts";
+
+export interface RunStatusParams {
+	action?: "status";
+	id?: string;
+	runId?: string;
+	dir?: string;
+}
+
+function activityText(activityState: unknown, lastActivityAt: unknown): string | undefined {
+	if (typeof lastActivityAt !== "number") return undefined;
+	const seconds = Math.floor(Math.max(0, Date.now() - lastActivityAt) / 1000);
+	return activityState === "needs_attention" ? `no activity for ${seconds}s` : `active ${seconds}s ago`;
+}
+
+export function inspectSubagentStatus(params: RunStatusParams): AgentToolResult<Details> {
+	if (!params.id && !params.runId && !params.dir) {
+		try {
+			const runs = listAsyncRuns(ASYNC_DIR, { states: ["queued", "running"] });
+			return {
+				content: [{ type: "text", text: formatAsyncRunList(runs) }],
+				details: { mode: "single", results: [] },
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text", text: message }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+	}
+
+	let asyncDir: string | null = null;
+	let resolvedId = params.id ?? params.runId;
+
+	if (params.dir) {
+		asyncDir = path.resolve(params.dir);
+	} else if (resolvedId) {
+		const direct = path.join(ASYNC_DIR, resolvedId);
+		if (fs.existsSync(direct)) {
+			asyncDir = direct;
+		} else {
+			const match = findByPrefix(ASYNC_DIR, resolvedId);
+			if (match) {
+				asyncDir = match;
+				resolvedId = path.basename(match);
+			}
+		}
+	}
+
+	const resultPath = resolvedId && !asyncDir ? findByPrefix(RESULTS_DIR, resolvedId, ".json") : null;
+
+	if (!asyncDir && !resultPath) {
+		return {
+			content: [{ type: "text", text: "Async run not found. Provide id or dir." }],
+			isError: true,
+			details: { mode: "single", results: [] },
+		};
+	}
+
+	if (asyncDir) {
+		let status;
+		try {
+			status = readStatus(asyncDir);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text", text: message }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+		const logPath = path.join(asyncDir, `subagent-log-${resolvedId ?? "unknown"}.md`);
+		const eventsPath = path.join(asyncDir, "events.jsonl");
+		if (status) {
+			const stepsTotal = status.steps?.length ?? 1;
+			const current = status.currentStep !== undefined ? status.currentStep + 1 : undefined;
+			const stepLine = current !== undefined ? `Step: ${current}/${stepsTotal}` : `Steps: ${stepsTotal}`;
+			const started = new Date(status.startedAt).toISOString();
+			const updated = status.lastUpdate ? new Date(status.lastUpdate).toISOString() : "n/a";
+			const statusActivityText = status.state === "running" ? activityText(status.activityState, status.lastActivityAt) : undefined;
+
+			const lines = [
+				`Run: ${status.runId}`,
+				`State: ${status.state}`,
+				statusActivityText ? `Activity: ${statusActivityText}` : undefined,
+				`Mode: ${status.mode}`,
+				stepLine,
+				`Started: ${started}`,
+				`Updated: ${updated}`,
+				`Dir: ${asyncDir}`,
+			].filter((line): line is string => Boolean(line));
+			for (const [index, step] of (status.steps ?? []).entries()) {
+				const stepActivityText = step.status === "running" ? activityText(step.activityState, step.lastActivityAt) : undefined;
+				lines.push(`Step ${index + 1}: ${step.agent} ${step.status}${stepActivityText ? `, ${stepActivityText}` : ""}`);
+			}
+			if (status.sessionFile) lines.push(`Session: ${status.sessionFile}`);
+			if (fs.existsSync(logPath)) lines.push(`Log: ${logPath}`);
+			if (fs.existsSync(eventsPath)) lines.push(`Events: ${eventsPath}`);
+
+			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [] } };
+		}
+	}
+
+	if (resultPath) {
+		try {
+			const raw = fs.readFileSync(resultPath, "utf-8");
+			const data = JSON.parse(raw) as { id?: string; success?: boolean; summary?: string; exitCode?: number; state?: string };
+			const status = data.success ? "complete" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
+			const lines = [`Run: ${data.id ?? resolvedId}`, `State: ${status}`, `Result: ${resultPath}`];
+			if (data.summary) lines.push("", data.summary);
+			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [] } };
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text", text: `Failed to read async result file: ${message}` }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+	}
+
+	return {
+		content: [{ type: "text", text: "Status file not found." }],
+		isError: true,
+		details: { mode: "single", results: [] },
+	};
+}

package/schemas.ts

@@ -58,10 +58,14 @@ export const ParallelStepSchema = Type.Object({
 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" })),
+	enabled: Type.Optional(Type.Boolean({ description: "Enable/disable subagent control attention tracking for this run" })),
+	needsAttentionAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "No-observed-activity window before a run needs attention" })),
+	notifyOn: Type.Optional(Type.Array(Type.String({ enum: ["needs_attention"] }), {
+		description: "Control event types that should notify the parent/orchestrator. Defaults to needs_attention.",
+	})),
+	notifyChannels: Type.Optional(Type.Array(Type.String({ enum: ["event", "async", "intercom"] }), {
+		description: "Notification channels to use when available. Defaults to event, async, and intercom.",
+	})),
 });
 
 export const SubagentParams = Type.Object({
@@ -69,10 +73,16 @@ export const SubagentParams = Type.Object({
 	task: Type.Optional(Type.String({ description: "Task (SINGLE mode)" })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({
-		description: "Action: management ('list','get','create','update','delete') or control ('interrupt'). Omit for execution mode."
+		description: "Action: management ('list','get','create','update','delete') or control ('status','interrupt'). Omit for execution mode."
+	})),
+	id: Type.Optional(Type.String({
+		description: "Run id or prefix for action='status' or action='interrupt'."
 	})),
 	runId: Type.Optional(Type.String({
-		description: "Target run ID for action='interrupt'. Defaults to the most recently active controllable run in this session."
+		description: "Target run ID for action='interrupt'. Defaults to the most recently active controllable run in this session. Prefer id for new calls."
+	})),
+	dir: Type.Optional(Type.String({
+		description: "Async run directory for action='status'."
 	})),
 	// Chain identifier for management (can't reuse 'chain' — that's the execution array)
 	chainName: Type.Optional(Type.String({
@@ -112,9 +122,3 @@ export const SubagentParams = Type.Object({
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for single agent (e.g. 'anthropic/claude-sonnet-4')" })),
 });
-
-export const StatusParams = Type.Object({
-	action: Type.Optional(Type.String({ description: "Action: 'list' to show active async runs, or omit to inspect one run by id/dir" })),
-	id: Type.Optional(Type.String({ description: "Async run id or prefix" })),
-	dir: Type.Optional(Type.String({ description: "Async run directory (overrides id search)" })),
-});

package/skills/pi-subagents/SKILL.md

@@ -20,12 +20,12 @@ 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
+- **Subagent control**: watch needs-attention 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
 
-Agents can use the `subagent(...)` and `subagent_status(...)` tools directly.
+Agents can use the `subagent(...)` tool directly for execution, management, status, and control.
 Humans often use the slash-command layer instead:
 
 - `/run` — launch a single agent
@@ -45,14 +45,14 @@ and user/project agents override builtins with the same name.
 | Agent | Purpose | Model | Typical output / role |
 |-------|---------|-------|------------------------|
 | `scout` | Fast codebase recon | `openai-codex/gpt-5.4-mini` | Writes `context.md` handoff material |
-| `planner` | Creates implementation plans | `openai-codex/gpt-5.4` | Writes `plan.md` |
-| `worker` | General implementation | `openai-codex/gpt-5.4` | Edits code directly |
-| `reviewer` | Review-and-fix specialist | `openai-codex/gpt-5.3-codex:high` | Can edit/fix reviewed code |
-| `context-builder` | Requirements/codebase handoff builder | `openai-codex/gpt-5.4` | Writes structured context files |
-| `researcher` | Web research brief generator | `openai-codex/gpt-5.4` | Writes `research.md` |
+| `planner` | Creates implementation plans | `openai-codex/gpt-5.5` | Writes `plan.md` |
+| `worker` | General implementation | `openai-codex/gpt-5.5` | Edits code directly |
+| `reviewer` | Review-and-fix specialist | `openai-codex/gpt-5.5` | Can edit/fix reviewed code |
+| `context-builder` | Requirements/codebase handoff builder | `openai-codex/gpt-5.5` | Writes structured context files |
+| `researcher` | Web research brief generator | `openai-codex/gpt-5.5` | Writes `research.md` |
 | `delegate` | Lightweight generic delegate | inherits parent model | No fixed output; generic delegated work |
-| `oracle` | Decision-consistency advisory review | `openai-codex/gpt-5.4:high` | Advisory review, intercom coordination |
-| `oracle-executor` | Implementation after approval | `openai-codex/gpt-5.3-codex:high` | Single-writer implementation after approval |
+| `oracle` | Decision-consistency advisory review | `openai-codex/gpt-5.5` | Advisory review, intercom coordination |
+| `oracle-executor` | Implementation after approval | `openai-codex/gpt-5.5` | Single-writer implementation after approval |
 
 Override builtin defaults via settings before copying full agent files when a
 small tweak is enough.
@@ -145,14 +145,13 @@ subagent({
 })
 ```
 
-Inspect async runs with the `subagent_status(...)` tool or the
-`/subagents-status` slash command.
+Inspect async runs with `subagent({ action: "status", id: "..." })`, `subagent({ action: "status" })` for active runs, 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`.
+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 `queued`, `running`, `paused`, `complete`, or `failed`. Activity reporting is factual: it tracks the last observed activity time and the current tool when known. It does not pretend to know that a child is truly stuck.
 
-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.
+Default behavior is intentionally conservative. When no activity has been observed past the configured threshold, the run emits a `needs_attention` control event. Foreground runs can push this as a `subagent:control-event` event, and async runs persist it to `events.jsonl` so the parent tracker can surface it without constant manual polling. Notification-worthy control events are also inserted into the visible transcript so both the user and the parent agent can see them, with a proactive hint plus concrete `nudge`, `status`, and `interrupt` options. Visible notifications fire once per child run and attention state.
 
 Use soft interrupt when a child is clearly blocked or drifting and the parent needs to regain control:
 
@@ -160,28 +159,29 @@ Use soft interrupt when a child is clearly blocked or drifting and the parent ne
 subagent({ action: "interrupt" })
 ```
 
-Pass `runId` when targeting a specific controllable run:
+Pass `id` when targeting a specific controllable run:
 
 ```typescript
-subagent({ action: "interrupt", runId: "abc123" })
+subagent({ action: "interrupt", id: "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:
+Per-run control thresholds can be overridden when a task legitimately runs without observable output for longer than usual:
 
 ```typescript
 subagent({
   agent: "worker",
   task: "Run the slow migration test suite",
   control: {
-    quietAfterMs: 60000,
-    stalledAfterMs: 300000,
-    parentMode: "transitions"
+    needsAttentionAfterMs: 300000,
+    notifyOn: ["needs_attention"]
   }
 })
 ```
 
+If the run already has an active intercom bridge target, needs-attention notifications can also prepare a compact intercom ping for the orchestrator. When a child route is available, the ping tells the orchestrator which agent needs attention and includes the exact `intercom({ action: "send", to: "..." })` target for a nudge. Do not invent a target or ask the child to self-report when no bridge exists.
+
 ## Clarify TUI
 
 Single and parallel runs support a clarification TUI when you want to preview or
@@ -369,7 +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`.
+- **Attention signals are not lifecycle state.** `needs_attention` means no activity has been observed past the configured threshold. `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
@@ -400,7 +400,7 @@ 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.
+Use subagent control proactively when a delegated run emits `needs_attention`, or when a human asks you to regain control. Do not interrupt just because a child has briefly produced no output. Silence can be normal during long tool calls, test runs, or model reasoning.
 
 ### Name sessions meaningfully
 

package/slash-live-state.ts

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

package/subagent-control.ts

@@ -3,14 +3,19 @@ import {
 	type ControlConfig,
 	type ControlEvent,
 	type ControlEventType,
+	type ControlNotificationChannel,
 	type ResolvedControlConfig,
 } from "./types.ts";
 
+const CONTROL_EVENT_TYPES: ControlEventType[] = ["needs_attention"];
+const CONTROL_NOTIFICATION_CHANNELS: ControlNotificationChannel[] = ["event", "async", "intercom"];
+const DEFAULT_NOTIFY_ON: ControlEventType[] = ["needs_attention"];
+
 export const DEFAULT_CONTROL_CONFIG: ResolvedControlConfig = {
 	enabled: true,
-	quietAfterMs: 15_000,
-	stalledAfterMs: 60_000,
-	parentMode: "transitions",
+	needsAttentionAfterMs: 60_000,
+	notifyOn: DEFAULT_NOTIFY_ON,
+	notifyChannels: CONTROL_NOTIFICATION_CHANNELS,
 };
 
 function parsePositiveInt(value: unknown): number | undefined {
@@ -19,24 +24,33 @@ function parsePositiveInt(value: unknown): number | undefined {
 	return value;
 }
 
+function parseControlList<T extends string>(value: unknown, allowed: readonly T[]): T[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	if (value.length === 0) return [];
+	const allowedSet = new Set(allowed);
+	const parsed = value.filter((entry): entry is T => typeof entry === "string" && allowedSet.has(entry as T));
+	return parsed.length > 0 ? Array.from(new Set(parsed)) : undefined;
+}
+
 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);
+	const needsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs)
+		?? parsePositiveInt(globalConfig?.needsAttentionAfterMs)
+		?? DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs;
+	const notifyOn = parseControlList(override?.notifyOn, CONTROL_EVENT_TYPES)
+		?? parseControlList(globalConfig?.notifyOn, CONTROL_EVENT_TYPES)
+		?? DEFAULT_CONTROL_CONFIG.notifyOn;
+	const notifyChannels = parseControlList(override?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
+		?? parseControlList(globalConfig?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
+		?? DEFAULT_CONTROL_CONFIG.notifyChannels;
 	return {
 		enabled,
-		quietAfterMs,
-		stalledAfterMs,
-		parentMode: parentMode === "verbose" ? "verbose" : "transitions",
+		needsAttentionAfterMs,
+		notifyOn: [...notifyOn],
+		notifyChannels: [...notifyChannels],
 	};
 }
 
@@ -44,57 +58,40 @@ 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";
+	return ageMs > input.config.needsAttentionAfterMs ? "needs_attention" : undefined;
 }
 
 export function shouldEmitControlEvent(
 	config: ResolvedControlConfig,
 	from: ActivityState | undefined,
-	to: ActivityState,
+	to: ActivityState | undefined,
 ): 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;
+	return config.enabled && from !== to && to === "needs_attention";
 }
 
 export function buildControlEvent(input: {
-	from: ActivityState | undefined;
+	from?: ActivityState;
 	to: ActivityState;
 	runId: string;
 	agent: string;
 	index?: number;
 	ts?: number;
+	lastActivityAt?: 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})`;
+	const elapsedMs = input.lastActivityAt ? Math.max(0, ts - input.lastActivityAt) : undefined;
+	const elapsedSeconds = elapsedMs !== undefined ? Math.floor(elapsedMs / 1000) : undefined;
+	const message = elapsedSeconds !== undefined
+		? `${input.agent} needs attention (no observed activity for ${elapsedSeconds}s)`
+		: `${input.agent} needs attention`;
 	return {
-		type,
+		type: "needs_attention",
 		from: input.from,
 		to: input.to,
 		ts,
@@ -104,3 +101,48 @@ export function buildControlEvent(input: {
 		message,
 	};
 }
+
+export function shouldNotifyControlEvent(config: ResolvedControlConfig, event: ControlEvent): boolean {
+	return config.enabled && config.notifyOn.includes(event.type);
+}
+
+export function controlNotificationKey(event: ControlEvent, childIntercomTarget?: string): string {
+	const childKey = childIntercomTarget ?? (event.index !== undefined ? `${event.runId}:${event.index}` : event.runId);
+	return `${childKey}:${event.type}`;
+}
+
+export function claimControlNotification(config: ResolvedControlConfig, event: ControlEvent, seenKeys: Set<string>, childIntercomTarget?: string): boolean {
+	if (!shouldNotifyControlEvent(config, event)) return false;
+	const key = controlNotificationKey(event, childIntercomTarget);
+	if (seenKeys.has(key)) return false;
+	seenKeys.add(key);
+	return true;
+}
+
+export function formatControlNoticeMessage(event: ControlEvent, childIntercomTarget?: string): string {
+	const runTarget = event.runId;
+	const nudgeCommand = childIntercomTarget
+		? `intercom({ action: "send", to: "${childIntercomTarget}", message: "What are you blocked on? Reply with the smallest next step or ask for a decision." })`
+		: undefined;
+	return [
+		`Subagent needs attention: ${event.agent}`,
+		`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+		`Signal: ${event.message}`,
+		"Hint: Inspect status first unless the run is clearly blocked.",
+		childIntercomTarget
+			? `Nudge: ${nudgeCommand}`
+			: "Nudge: no child message route registered",
+		`Status: subagent({ action: "status", id: "${runTarget}" })`,
+		`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
+	].join("\n");
+}
+
+export function formatControlIntercomMessage(event: ControlEvent, childIntercomTarget?: string): string {
+	return [
+		"subagent needs attention",
+		"",
+		`${event.agent} needs attention in run ${event.runId}.`,
+		"",
+		formatControlNoticeMessage(event, childIntercomTarget),
+	].join("\n");
+}