@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/src/runs/shared/session-cwd-preload.ts

@@ -0,0 +1,27 @@
+import { realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// Node loads this before Pi selects its session and creates cwd-bound services.
+// Use the SDK beside the actual CLI (bundled or unbundled), never our dev peer.
+const configuration = process.env.PI_SUBAGENT_SESSION_CWD;
+if (configuration) {
+	const { sessionFile, cwd, nodeOptions } = JSON.parse(configuration) as {
+		sessionFile: string;
+		cwd: string;
+		nodeOptions?: string;
+	};
+	const sdkUrl = pathToFileURL(join(dirname(realpathSync(process.argv[1])), "index.js"));
+	const { SessionManager }: typeof import("@earendil-works/pi-coding-agent") = await import(sdkUrl.href);
+	const open = SessionManager.open;
+	SessionManager.open = (file, sessionDir, cwdOverride) => {
+		if (resolve(file) !== sessionFile) return open(file, sessionDir, cwdOverride);
+		SessionManager.open = open;
+		// Keep the preload through a native launcher, then clear it before tools or nested children start.
+		delete process.env.PI_SUBAGENT_SESSION_CWD;
+		if (nodeOptions === undefined) delete process.env.NODE_OPTIONS;
+		else process.env.NODE_OPTIONS = nodeOptions;
+		// Public Pi SDK override preserves the file, header, identity and history.
+		return open(file, sessionDir, cwd);
+	};
+}

package/src/runs/shared/single-output.ts

@@ -0,0 +1,267 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { OutputMode, SavedOutputReference } from "../../shared/types.ts";
+
+export interface SingleOutputSnapshot {
+	exists: boolean;
+	mtimeMs?: number;
+	ctimeMs?: number;
+	size?: number;
+	ino?: number;
+}
+
+export interface SingleOutputCleanupResult {
+	path: string;
+	action: "deleted" | "already-missing" | "skipped";
+	reason?: string;
+	error?: string;
+}
+
+export function normalizeSingleOutputOverride(
+	output: string | boolean | undefined,
+	defaultOutput: string | false | undefined,
+): string | false | undefined {
+	if (output === false || output === "false") return false;
+	if (output === true || output === "true") return defaultOutput;
+	if (typeof output === "string" && output.length > 0) return output;
+	return undefined;
+}
+
+export function resolveSingleOutputPath(
+	output: string | boolean | undefined,
+	runtimeCwd: string,
+	requestedCwd?: string,
+): string | undefined {
+	if (typeof output !== "string" || !output || output === "false" || output === "true") return undefined;
+	if (path.isAbsolute(output)) return output;
+	const baseCwd = requestedCwd
+		? (path.isAbsolute(requestedCwd) ? requestedCwd : path.resolve(runtimeCwd, requestedCwd))
+		: runtimeCwd;
+	return path.resolve(baseCwd, output);
+}
+
+function safeOutputSegment(value: string, fallback: string): string {
+	const sanitized = value.replace(/[^\w.-]/g, "_").replace(/^\.+$/, "");
+	return sanitized || fallback;
+}
+
+export function materializeAgentDefaultOutputPath(params: {
+	output: string | false | undefined;
+	artifactsDir: string;
+	runId: string;
+	agent: string;
+	index?: number | string;
+}): string | false | undefined {
+	if (typeof params.output !== "string" || !params.output || params.output === "false" || params.output === "true") return params.output;
+	if (path.isAbsolute(params.output)) return params.output;
+	const suffix = params.index !== undefined ? `_${safeOutputSegment(String(params.index), "index")}` : "";
+	const safeAgent = safeOutputSegment(params.agent, "agent");
+	const safeBaseName = safeOutputSegment(path.basename(params.output), "output.md");
+	return path.join(params.artifactsDir, "requested-outputs", `${params.runId}_${safeAgent}${suffix}_${safeBaseName}`);
+}
+
+export function injectSingleOutputInstruction(task: string, outputPath: string | undefined): string {
+	if (!outputPath) return task;
+	return `${task}\n\n---\n**Output:** Write your findings to: ${outputPath}`;
+}
+
+function countLines(text: string): number {
+	if (!text) return 0;
+	const newlineMatches = text.match(/\r\n|\r|\n/g);
+	return (newlineMatches?.length ?? 0) + (/[\r\n]$/.test(text) ? 0 : 1);
+}
+
+function formatByteSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = ["KB", "MB", "GB", "TB"];
+	let value = bytes / 1024;
+	let unitIndex = 0;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex++;
+	}
+	return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+
+export function formatSavedOutputReference(savedPath: string, fullOutput: string): SavedOutputReference {
+	const absolutePath = path.resolve(savedPath);
+	const bytes = Buffer.byteLength(fullOutput, "utf-8");
+	const lines = countLines(fullOutput);
+	return {
+		path: absolutePath,
+		bytes,
+		lines,
+		message: `Output saved to: ${absolutePath} (${formatByteSize(bytes)}, ${lines} ${lines === 1 ? "line" : "lines"}). Read this file if needed.`,
+	};
+}
+
+export function formatConsumedOutputReference(outputPath: string, fullOutput: string, cleanup: SingleOutputCleanupResult): SavedOutputReference {
+	const absolutePath = path.resolve(outputPath);
+	const bytes = Buffer.byteLength(fullOutput, "utf-8");
+	const lines = countLines(fullOutput);
+	const status = cleanup.action === "deleted"
+		? "removed after capture"
+		: cleanup.action === "already-missing"
+			? "already absent after capture"
+			: `not removed${cleanup.reason ? `: ${cleanup.reason}` : ""}`;
+	return {
+		path: absolutePath,
+		bytes,
+		lines,
+		message: `Output file consumed: ${absolutePath} (${formatByteSize(bytes)}, ${lines} ${lines === 1 ? "line" : "lines"}); ${status}.`,
+	};
+}
+
+export function findDuplicateOutputPath(
+	items: ReadonlyArray<{ agent: string; outputPath?: string }>,
+): string | undefined {
+	const seen = new Map<string, { index: number; agent: string }>();
+	for (let index = 0; index < items.length; index++) {
+		const outputPath = items[index]?.outputPath;
+		if (!outputPath) continue;
+		const previous = seen.get(outputPath);
+		if (previous) {
+			return `Parallel tasks ${previous.index + 1} (${previous.agent}) and ${index + 1} (${items[index]!.agent}) resolve output to the same path: ${outputPath}. Use distinct output paths.`;
+		}
+		seen.set(outputPath, { index, agent: items[index]!.agent });
+	}
+	return undefined;
+}
+
+export function validateFileOnlyOutputMode(outputMode: OutputMode | undefined, outputPath: string | undefined, context: string): string | undefined {
+	if (outputMode === "file-only" && !outputPath) {
+		return `${context} sets outputMode: "file-only" but does not configure an output file. Set output to a path or use outputMode: "inline".`;
+	}
+	return undefined;
+}
+
+export function captureSingleOutputSnapshot(outputPath: string | undefined): SingleOutputSnapshot | undefined {
+	if (!outputPath) return undefined;
+	try {
+		const stat = fs.statSync(outputPath);
+		return { exists: true, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, size: stat.size, ino: stat.ino };
+	} catch {
+		// The snapshot is advisory; resolveSingleOutput reports concrete read/write failures.
+		return { exists: false };
+	}
+}
+
+function matchesSnapshot(stat: fs.Stats, snapshot: SingleOutputSnapshot | undefined): boolean {
+	return snapshot?.exists === true
+		&& stat.mtimeMs === snapshot.mtimeMs
+		&& stat.ctimeMs === snapshot.ctimeMs
+		&& stat.size === snapshot.size
+		&& stat.ino === snapshot.ino;
+}
+
+function persistSingleOutput(
+	outputPath: string | undefined,
+	fullOutput: string,
+): { savedPath?: string; error?: string } {
+	if (!outputPath) return {};
+	try {
+		fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+		fs.writeFileSync(outputPath, fullOutput, "utf-8");
+		return { savedPath: outputPath };
+	} catch (err) {
+		return { error: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+export function resolveSingleOutput(
+	outputPath: string | undefined,
+	fallbackOutput: string,
+	beforeRun: SingleOutputSnapshot | undefined,
+): { fullOutput: string; savedPath?: string; saveError?: string; writtenSnapshot?: SingleOutputSnapshot } {
+	if (!outputPath) return { fullOutput: fallbackOutput };
+
+	try {
+		const stat = fs.statSync(outputPath);
+		if (!matchesSnapshot(stat, beforeRun)) {
+			// ponytail: acceptance and downstream prompts explicitly request this full
+			// individual output; it must fit their heap. Inspection uses readOutputPage.
+			return { fullOutput: fs.readFileSync(outputPath, "utf-8"), savedPath: outputPath };
+		}
+	} catch (error) {
+		const code = error && typeof error === "object" && "code" in error ? (error as { code?: unknown }).code : undefined;
+		if (code !== "ENOENT" && code !== "ENOTDIR") {
+			return {
+				fullOutput: fallbackOutput,
+				saveError: `Failed to read changed output file: ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+	}
+
+	const save = persistSingleOutput(outputPath, fallbackOutput);
+	if (save.savedPath) return { fullOutput: fallbackOutput, savedPath: save.savedPath, writtenSnapshot: captureSingleOutputSnapshot(save.savedPath) };
+	return { fullOutput: fallbackOutput, saveError: save.error };
+}
+
+export function cleanupSingleOutputFile(
+	outputPath: string | undefined,
+	fullOutput: string,
+	beforeRun: SingleOutputSnapshot | undefined,
+): SingleOutputCleanupResult | undefined {
+	if (!outputPath) return undefined;
+	const absolutePath = path.resolve(outputPath);
+	try {
+		const stat = fs.statSync(outputPath);
+		const fd = fs.openSync(outputPath, "r");
+		let equal = stat.size === Buffer.byteLength(fullOutput);
+		try {
+			let position = 0;
+			for (let start = 0; equal && start < fullOutput.length;) {
+				let end = Math.min(start + 16384, fullOutput.length);
+				if (end < fullOutput.length && /[\uD800-\uDBFF]/.test(fullOutput[end - 1]!)) end--;
+				const expected = Buffer.from(fullOutput.slice(start, end));
+				const actual = Buffer.allocUnsafe(expected.length);
+				equal = fs.readSync(fd, actual, 0, actual.length, position) === actual.length && actual.equals(expected);
+				position += expected.length; start = end;
+			}
+			const current = fs.fstatSync(fd), located = fs.statSync(outputPath);
+			equal &&= current.ino === stat.ino && current.size === stat.size && current.ctimeMs === stat.ctimeMs
+				&& located.ino === current.ino && located.dev === current.dev && located.ctimeMs === current.ctimeMs;
+		} finally { fs.closeSync(fd); }
+		if (!equal) {
+			return { path: absolutePath, action: "skipped", reason: "file changed after capture" };
+		}
+		if (matchesSnapshot(stat, beforeRun)) {
+			return { path: absolutePath, action: "skipped", reason: "file preexisted and was unchanged" };
+		}
+		fs.unlinkSync(outputPath);
+		return { path: absolutePath, action: "deleted" };
+	} catch (error) {
+		const code = error && typeof error === "object" && "code" in error ? (error as { code?: unknown }).code : undefined;
+		if (code === "ENOENT" || code === "ENOTDIR") return { path: absolutePath, action: "already-missing" };
+		return { path: absolutePath, action: "skipped", error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+export function finalizeSingleOutput(params: {
+	fullOutput: string;
+	truncatedOutput?: string;
+	outputPath?: string;
+	outputMode?: OutputMode;
+	exitCode: number;
+	savedPath?: string;
+	outputReference?: SavedOutputReference;
+	saveError?: string;
+	cleanup?: SingleOutputCleanupResult;
+}): { displayOutput: string; savedPath?: string; outputReference?: SavedOutputReference; saveError?: string } {
+	let displayOutput = params.truncatedOutput || params.fullOutput;
+	if (params.exitCode === 0 && params.savedPath) {
+		const outputReference = params.outputReference ?? (params.cleanup && params.outputMode !== "file-only"
+			? formatConsumedOutputReference(params.savedPath, params.fullOutput, params.cleanup)
+			: formatSavedOutputReference(params.savedPath, params.fullOutput));
+		if (params.outputMode === "file-only") {
+			return { displayOutput: outputReference.message, savedPath: params.savedPath, outputReference };
+		}
+		displayOutput += `\n\n${outputReference.message}`;
+		return { displayOutput, savedPath: params.cleanup ? undefined : params.savedPath, outputReference };
+	}
+	if (params.exitCode === 0 && params.saveError && params.outputPath) {
+		displayOutput += `\n\nOutput file error: ${params.outputPath}\n${params.saveError}`;
+		return { displayOutput, saveError: params.saveError };
+	}
+	return { displayOutput };
+}

package/src/runs/shared/streaming-text.ts

@@ -0,0 +1,18 @@
+import type { JsonAgentSessionEvent } from "@earendil-works/pi-coding-agent";
+
+type TextEvent = {
+	type?: string;
+	message?: { role: string };
+	assistantMessageEvent?: Extract<JsonAgentSessionEvent, { type: "message_update" }>["assistantMessageEvent"];
+};
+
+/** Native JSON stdout sends text deltas, not cumulative message/partial snapshots. */
+export function updateStreamingText(current: string | undefined, event: TextEvent): string | undefined {
+	if (event.type === "agent_start" || event.type === "message_end" && event.message?.role === "assistant") return undefined;
+	if (event.type === "message_start" && event.message?.role === "assistant") return "";
+	if (event.type !== "message_update") return current;
+	const update = event.assistantMessageEvent;
+	if (update?.type === "text_start") return current ? `${current}\n\n` : "";
+	if (update?.type === "text_delta") return ((current ?? "") + update.delta).slice(-8192);
+	return current;
+}

package/src/runs/shared/structured-output.ts

@@ -0,0 +1,68 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Compile } from "../../shared/native-typebox.ts";
+import type { JsonSchemaObject } from "../../shared/types.ts";
+
+export const STRUCTURED_OUTPUT_SCHEMA_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA";
+export const STRUCTURED_OUTPUT_CAPTURE_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE";
+
+export interface StructuredOutputRuntime {
+	schema: JsonSchemaObject;
+	schemaPath: string;
+	outputPath: string;
+}
+
+interface CompiledJsonSchema {
+	Check(value: unknown): boolean;
+	Errors(value: unknown): Iterable<{ instancePath?: string; message?: string }>;
+}
+
+export function assertJsonSchemaObject(schema: unknown, label = "outputSchema"): asserts schema is JsonSchemaObject {
+	if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+		throw new Error(`${label} must be a JSON Schema object.`);
+	}
+}
+
+export function createStructuredOutputRuntime(schema: JsonSchemaObject, baseDir?: string): StructuredOutputRuntime {
+	assertJsonSchemaObject(schema);
+	const rootDir = baseDir ?? os.tmpdir();
+	fs.mkdirSync(rootDir, { recursive: true });
+	const dir = fs.mkdtempSync(path.join(rootDir, "pi-subagent-structured-"));
+	const schemaPath = path.join(dir, "schema.json");
+	const outputPath = path.join(dir, "output.json");
+	fs.writeFileSync(schemaPath, JSON.stringify(schema), { mode: 0o600 });
+	return { schema, schemaPath, outputPath };
+}
+
+export function validateStructuredOutputValue(schema: JsonSchemaObject, value: unknown): { status: "valid" } | { status: "invalid"; message: string } {
+	let validator: CompiledJsonSchema;
+	try {
+		validator = (Compile as (schema: unknown) => CompiledJsonSchema)(schema);
+	} catch (error) {
+		return { status: "invalid", message: `invalid outputSchema: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	if (validator.Check(value)) return { status: "valid" };
+	const errors = [...validator.Errors(value)]
+		.slice(0, 8)
+		.map((error) => {
+			const pathText = error.instancePath ? error.instancePath.replace(/^\//, "").replace(/\//g, ".") : "root";
+			return `${pathText}: ${error.message}`;
+		});
+	return { status: "invalid", message: errors.join("; ") || "schema validation failed" };
+}
+
+export function readStructuredOutput(runtime: StructuredOutputRuntime): { value?: unknown; error?: string } {
+	if (!fs.existsSync(runtime.outputPath)) {
+		return { error: "Missing structured_output call; this step has outputSchema and must finish by calling structured_output." };
+	}
+	let value: unknown;
+	try {
+		value = JSON.parse(fs.readFileSync(runtime.outputPath, "utf-8"));
+	} catch (error) {
+		return { error: `Failed to read structured output: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	const validation = validateStructuredOutputValue(runtime.schema, value);
+	if (validation.status === "invalid") return { error: `Structured output validation failed: ${validation.message}` };
+	return { value };
+}

package/src/runs/shared/subagent-control.ts

@@ -0,0 +1,219 @@
+import {
+	type ActivityState,
+	type ControlConfig,
+	type ControlEvent,
+	type ControlEventType,
+	type ControlNotificationChannel,
+	type ResolvedControlConfig,
+} from "../../shared/types.ts";
+
+import { formatRunAction } from "../../shared/status-format.ts";
+import { readStatus } from "../../shared/utils.ts";
+import { getRunMetadataDir } from "./supervisor-questions.ts";
+
+export function isObsoleteIdleNotice(details: { event: ControlEvent; asyncDir?: string }): boolean {
+	const event = details?.event;
+	if (!event || event.reason !== "idle" || event.supervisorQuestion) return false;
+	let status;
+	try {
+		status = readStatus(details.asyncDir ?? getRunMetadataDir(event.runId));
+	} catch {
+		// Without readable terminal evidence, retain the actionable notice.
+		return false;
+	}
+	if (!status || status.runId !== event.runId) return false;
+	const child = event.index === undefined ? undefined : status.steps?.[event.index];
+	return ["complete", "failed", "blocked", "paused"].includes(status.state)
+		|| Boolean(child && ["complete", "completed", "failed", "blocked", "paused", "timed-out"].includes(child.status));
+}
+
+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,
+	needsAttentionAfterMs: 10 * 60_000,
+	failedToolAttemptsBeforeAttention: 3,
+	notifyOn: DEFAULT_NOTIFY_ON,
+	notifyChannels: CONTROL_NOTIFICATION_CHANNELS,
+};
+
+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;
+}
+
+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 needsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs)
+		?? parsePositiveInt(globalConfig?.needsAttentionAfterMs)
+		?? DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs;
+	const failedToolAttemptsBeforeAttention = parsePositiveInt(override?.failedToolAttemptsBeforeAttention)
+		?? parsePositiveInt(globalConfig?.failedToolAttemptsBeforeAttention)
+		?? DEFAULT_CONTROL_CONFIG.failedToolAttemptsBeforeAttention;
+	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,
+		needsAttentionAfterMs,
+		failedToolAttemptsBeforeAttention,
+		notifyOn: [...notifyOn],
+		notifyChannels: [...notifyChannels],
+	};
+}
+
+export function deriveActivityState(input: {
+	config: ResolvedControlConfig;
+	startedAt: number;
+	lastActivityAt?: number;
+	now?: number;
+}): ActivityState | undefined {
+	if (!input.config.enabled) return undefined;
+	const now = input.now ?? Date.now();
+	const lastActivity = input.lastActivityAt ?? input.startedAt;
+	const ageMs = Math.max(0, now - lastActivity);
+	return ageMs > input.config.needsAttentionAfterMs ? "needs_attention" : undefined;
+}
+
+export function buildControlEvent(input: {
+	type?: ControlEventType;
+	from?: ActivityState;
+	to: ActivityState;
+	runId: string;
+	agent: string;
+	index?: number;
+	ts?: number;
+	lastActivityAt?: number;
+	message?: string;
+	reason?: ControlEvent["reason"];
+	turns?: number;
+	tokens?: number;
+	toolCount?: number;
+	currentTool?: string;
+	currentToolDurationMs?: number;
+	currentPath?: string;
+	elapsedMs?: number;
+	recentFailureSummary?: string;
+	supervisorQuestion?: ControlEvent["supervisorQuestion"];
+}): ControlEvent {
+	const ts = input.ts ?? Date.now();
+	const type = input.type ?? "needs_attention";
+	const elapsedMs = input.elapsedMs ?? (input.lastActivityAt !== undefined ? Math.max(0, ts - input.lastActivityAt) : undefined);
+	const elapsedSeconds = elapsedMs !== undefined ? Math.floor(elapsedMs / 1000) : undefined;
+	const question = input.supervisorQuestion;
+	const observation = input.currentTool
+		? `${input.currentTool} still active${input.currentToolDurationMs !== undefined ? ` for ${Math.floor(input.currentToolDurationMs / 1000)}s` : ""}${elapsedSeconds !== undefined ? `; no observed output/events for ${elapsedSeconds}s` : ""}`
+		: elapsedSeconds !== undefined ? `no observed activity for ${elapsedSeconds}s` : undefined;
+	const signal = question
+		? question.state === "awaiting_input" ? `Waiting for supervisor input (question ${question.questionId})` : `Supervisor answer saved for question ${question.questionId}; delivery unconfirmed`
+		: `${input.agent} needs attention`;
+	const message = input.message ?? `${signal}${observation ? ` (${observation})` : ""}`;
+	return {
+		type,
+		...(input.from ? { from: input.from } : {}),
+		to: input.to,
+		ts,
+		runId: input.runId,
+		agent: input.agent,
+		...(input.index !== undefined ? { index: input.index } : {}),
+		message,
+		reason: input.reason ?? "idle",
+		...(input.turns !== undefined ? { turns: input.turns } : {}),
+		...(input.tokens !== undefined ? { tokens: input.tokens } : {}),
+		...(input.toolCount !== undefined ? { toolCount: input.toolCount } : {}),
+		...(input.currentTool ? { currentTool: input.currentTool } : {}),
+		...(input.currentToolDurationMs !== undefined ? { currentToolDurationMs: input.currentToolDurationMs } : {}),
+		...(input.currentPath ? { currentPath: input.currentPath } : {}),
+		...(elapsedMs !== undefined ? { elapsedMs } : {}),
+		...(input.recentFailureSummary ? { recentFailureSummary: input.recentFailureSummary } : {}),
+		...(question ? { supervisorQuestion: question } : {}),
+	};
+}
+
+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}:${event.reason ?? "idle"}`;
+}
+
+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, childSafe = false): string {
+	const runTarget = event.runId;
+	if (event.reason === "completion_guard") {
+		return [
+			`Subagent failed: ${event.agent}`,
+			`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+			`Signal: ${event.message}`,
+			"Next: read the output artifact or session from the subagent result, then retry with a more explicit implementation prompt or handle the fix directly.",
+			childIntercomTarget ? `Run intercom target (may be inactive): ${childIntercomTarget}` : undefined,
+		].filter((line): line is string => Boolean(line)).join("\n");
+	}
+
+	const nudgeCommand = formatRunAction("nudge", runTarget, { ...(event.index !== undefined ? { index: event.index } : {}), message: "What are you blocked on? Reply with the smallest next step, or state the exact decision you need." }, childSafe);
+	const question = event.supervisorQuestion;
+	const askCommand = childIntercomTarget
+		? `intercom({ action: "ask", to: "${childIntercomTarget}", delivery: "steer", message: "What are you blocked on? Reply with the smallest next step, or state the exact decision you need." })`
+		: undefined;
+	return [
+		`Subagent needs attention: ${event.agent}`,
+		`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+		`Signal: ${event.message}`,
+		event.recentFailureSummary ? `Recent failures: ${event.recentFailureSummary}` : undefined,
+		...(question ? [
+			`Question ID: ${question.questionId}`,
+			question.state === "answer_pending" ? "The saved answer has not been confirmed delivered. Inspect the child and retry the same answer; do not assume it resumed." : "Answer the saved question so the child can continue.",
+			`Questions: ${formatRunAction("questions", runTarget, {}, childSafe)}`,
+			`Answer: ${formatRunAction("answer", runTarget, { questionId: question.questionId, message: question.answer ?? "..." }, childSafe)}`,
+		] : [
+			event.reason === "idle" && event.currentTool ? "Hint: Inspect command progress. A long-running tool may still be running or hung; elapsed time alone does not prove either." : "Hint: Inspect status first unless the run is clearly blocked.",
+			`Nudge (preferred live coordination): ${nudgeCommand}`,
+			childIntercomTarget
+				? `Ask (blocking wait only; parent must remain alive): ${askCommand}`
+				: "Ask (blocking wait only): no child message route registered",
+		]),
+		`Status: ${formatRunAction("status", runTarget, {}, childSafe)}`,
+		`${childSafe ? "Interrupt" : "Stop"}: ${formatRunAction("interrupt", runTarget, {}, childSafe)}`,
+	].filter((line): line is string => Boolean(line)).join("\n");
+}
+
+export function formatControlIntercomMessage(event: ControlEvent, childIntercomTarget?: string, childSafe = false): string {
+	const statusLabel = event.reason === "completion_guard"
+		? "subagent failed"
+		: "subagent needs attention";
+	return [
+		statusLabel,
+		"",
+		event.reason === "completion_guard"
+			? `${event.agent} failed in run ${event.runId}.`
+			: `${event.agent} needs attention in run ${event.runId}.`,
+		"",
+		formatControlNoticeMessage(event, childIntercomTarget, childSafe),
+	].join("\n");
+}