@fitchmultz/pi-subagents 0.0.0-stage → 0.44.4

package/src/extension/compact-tools.ts

@@ -0,0 +1,114 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "../shared/native-typebox.ts";
+import { createSubagentExecutor, normalizeSubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
+import type { SubagentExecutionResult, SubagentState } from "../shared/types.ts";
+import { activateTools, restoreLazyTools } from "../shared/lazy-tools.ts";
+import { runHistoryIndex } from "../runs/shared/history-index.ts";
+import type { HistoryRunOptions } from "../history/types.ts";
+import { listSupervisorQuestionsAsync } from "../runs/shared/supervisor-questions.ts";
+import { renderSubagentResult } from "../tui/render.ts";
+import { AgentRunsParams, DelegateParams } from "./schemas.ts";
+import { normalizeEverydayParams } from "./tool-input.ts";
+
+type Executor = ReturnType<typeof createSubagentExecutor>;
+type AdaptResult = (result: SubagentExecutionResult, ctx: ExtensionContext) => SubagentExecutionResult;
+
+export function registerCompactSubagentTools(pi: ExtensionAPI, options: {
+	executor: Executor;
+	state: SubagentState;
+	adapt: AdaptResult;
+	guidelines: readonly string[];
+	childSafe?: boolean;
+	keepAdvancedActive?: boolean;
+	listRuns?: (params: HistoryRunOptions, ctx: ExtensionContext) => Promise<SubagentExecutionResult>;
+	asyncByDefault: boolean;
+}): () => Promise<void> {
+	const { executor, adapt, guidelines, childSafe, asyncByDefault, state } = options;
+	let checking: { owner: string | null | undefined; promise: Promise<void> } | undefined;
+	const checkRuns = (): Promise<void> => {
+		if (pi.getActiveTools().includes("agent_runs") || !state.ownedRuns?.size) return Promise.resolve();
+		const owner = state.lastUiContext?.sessionManager.getSessionId() ?? state.currentSessionId;
+		if (checking?.owner === owner) return checking.promise;
+		const promise = Promise.resolve().then(async () => {
+			try {
+				const index = await runHistoryIndex(state);
+				const needed = await index.needsControls();
+				if (state.historyIndex === index && needed) activateTools(pi, ["agent_runs"]);
+			} catch {
+				// An unavailable browse index cannot establish that genuine owned work is inert.
+				if ((state.lastUiContext?.sessionManager.getSessionId() ?? state.currentSessionId) === owner && state.ownedRuns?.size) activateTools(pi, ["agent_runs"]);
+			} finally { if (checking?.promise === promise) checking = undefined; }
+		});
+		checking = { owner, promise };
+		return promise;
+	};
+	const reconcileRuns = () => checkRuns();
+	const onRunsChanged = state.onRunsChanged;
+	state.onRunsChanged = () => { reconcileRuns(); onRunsChanged?.(); };
+	const asyncDescription = asyncByDefault ? "Background by default; false waits for the result." : "Foreground by default; true detaches work. Use false when the result must appear in your report.";
+	pi.registerTool({
+		name: "delegate",
+		label: "Delegate",
+		description: `Delegate one bounded task to a configured agent. For profiles/history, load_subagent({advanced:false}) enables agent_runs. Delegation enables run controls automatically. ${asyncDescription} Use worktree for an isolated writer, acceptance for explicit requirements, and fresh context for independent review. Fresh handoffs must include relevant exact user instructions and settled decisions or readable source references, not just summaries, alongside the bounded task. Advanced workflows remain behind load_subagent.`,
+		...(childSafe ? { promptGuidelines: [...guidelines] } : {}),
+		parameters: Type.Object({ ...DelegateParams.properties, async: Type.Optional(Type.Boolean({ description: asyncDescription })) }, { additionalProperties: false }),
+		async execute(id, params, signal, onUpdate, ctx) {
+			const { worktree, context, async: background, ...task } = normalizeEverydayParams(params);
+			const request = worktree
+				? { tasks: [task], worktree: true, context, async: background, cwd: task.cwd }
+				: { ...task, context, async: background };
+			const result = await executor.execute(id, normalizeSubagentParamsLike(request), signal, onUpdate, ctx);
+			await checkRuns();
+			return adapt(result, ctx);
+		},
+		renderResult: renderSubagentResult,
+	});
+	pi.registerTool({
+		name: "agent_runs",
+		defaultActive: false,
+		label: "Agent Runs",
+		description: `List ${childSafe ? "only this child's directly owned" : "your delegated"} runs across working directories (questions/failures, then live work, then unreviewed results; 20 per page). Filter globally by agent/state/text, sort, and page with the returned cursor. history reads 100 bounded native-entry previews; search finds saved visible text using words or quoted phrases, not operators or prefixes. Browse freshness is not completion or delivery proof. Inspect concise results, paths and continuations; full:true includes the full task/configuration. Answer durable questions, nudge, stop, continue, or save parent-only review. Review notes are not sent to children; put actionable instructions in continue/nudge. Inspect/review/nudge never restart finished work. Continue/answer can launch a saved child; async:false waits for its actual result. Saved continuations keep settings unless agent selects a current profile; model overrides win. Live guidance never mutates model or acceptance. profiles lists roles, sources, context and model/thinking/fallback defaults. History survives reload.`,
+		parameters: AgentRunsParams,
+		async execute(id, params, signal, onUpdate, ctx) {
+			const normalized = normalizeEverydayParams(params, true);
+			if (params.action === "list" && !params.id && options.listRuns) return adapt(await options.listRuns({ ...normalized, signal }, ctx), ctx);
+			const actions = { list: "status", inspect: "status", history: "history", search: "search", nudge: "nudge", stop: "interrupt", continue: "resume", profiles: "list", questions: "questions", answer: "answer", review: "review" };
+			return adapt(await executor.execute(id, normalizeSubagentParamsLike({ ...normalized, action: actions[params.action] }), signal, onUpdate, ctx), ctx);
+		},
+		renderResult: renderSubagentResult,
+	});
+	pi.registerTool({
+		name: "load_subagent",
+		label: "Load Subagent",
+		description: `Enable agent_runs for profiles, history and run controls; advanced:false loads only those controls. By default also enable advanced subagent orchestration: parallel groups, chains, saved workflows, detailed overrides, get, extend and doctor.${childSafe ? " Agent-definition mutations remain blocked." : " Includes agent-definition management."} Ordinary delegation and control use delegate and agent_runs. After loading advanced workflows, call subagent with { action: "list" } before execution.`,
+		promptSnippet: "Discover profiles/history with advanced:false, or load full subagent orchestration by default.",
+		parameters: Type.Object({ advanced: Type.Optional(Type.Boolean({ description: "Also enable advanced orchestration (default true); false loads only agent_runs for profiles, history and controls." })) }),
+		async execute(_id, params) {
+			const advanced = params.advanced !== false;
+			if (advanced && !pi.getAllTools().some((tool) => tool.name === "subagent" && !("namespace" in tool && tool.namespace))) {
+				throw new Error("Subagent is unavailable because the full tool is excluded from this session.");
+			}
+			if (!advanced && !pi.getAllTools().some((tool) => tool.name === "agent_runs" && !("namespace" in tool && tool.namespace))) throw new Error("Run controls are excluded from this session.");
+			const added = !pi.getActiveTools().includes(advanced ? "subagent" : "agent_runs");
+			activateTools(pi, advanced ? ["agent_runs", "subagent"] : ["agent_runs"]);
+			return {
+				content: [{ type: "text" as const, text: advanced ? [`Subagent ${added ? "enabled" : "already enabled"}.`, ...guidelines.map((line) => `- ${line}`)].join("\n") : "Run controls enabled. Use agent_runs({action:'profiles'}) to discover agents; list, history, or search browses owned saved work." }],
+				details: {},
+			};
+		},
+	});
+	const reconcile = async (ctx: ExtensionContext) => {
+		if (options.keepAdvancedActive) activateTools(pi, ["subagent"]);
+		await checkRuns();
+		if (!pi.getActiveTools().includes("agent_runs") && (await listSupervisorQuestionsAsync(ctx.sessionManager.getSessionId())).some((question) => question.state === "awaiting_input" || question.state === "answer_pending")) activateTools(pi, ["agent_runs"]);
+	};
+	const restore = async (event: { reason?: string }, ctx: ExtensionContext) => {
+		if (event.reason !== "reload") restoreLazyTools(pi, ctx, "load_subagent", ["subagent", "agent_runs"]);
+		await reconcile(ctx);
+	};
+	pi.on("session_start", restore);
+	pi.on("session_tree", (_event, ctx) => reconcile(ctx));
+	pi.on("session_compact", (_event, ctx) => reconcile(ctx));
+	pi.on("before_agent_start", (_event, ctx) => reconcile(ctx));
+	return reconcileRuns;
+}

package/src/extension/config.ts

@@ -0,0 +1,23 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionConfig } from "../shared/types.ts";
+import { getAgentDir } from "../shared/utils.ts";
+
+export function loadConfig(): ExtensionConfig {
+	const configPath = path.join(getAgentDir(), "extensions", "subagent", "config.json");
+	try {
+		if (fs.existsSync(configPath)) {
+			const config = JSON.parse(fs.readFileSync(configPath, "utf-8")) as ExtensionConfig;
+			const trust = config.projectTrust;
+			const childRuns = typeof trust === "object" && trust !== null ? trust.childRuns : trust;
+			if (childRuns !== undefined && childRuns !== "inherit" && childRuns !== "approve" && childRuns !== "no-approve") {
+				console.error(`Invalid projectTrust in '${configPath}'; child runs will use no-approve.`);
+				config.projectTrust = "no-approve";
+			}
+			return config;
+		}
+	} catch (error) {
+		console.error(`Failed to load subagent config from '${configPath}':`, error);
+	}
+	return {};
+}

package/src/extension/control-notices.ts

@@ -0,0 +1,47 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { controlNotificationKey, formatControlNoticeMessage, isObsoleteIdleNotice } from "../runs/shared/subagent-control.ts";
+import type { ControlEvent } from "../shared/types.ts";
+
+export const SUBAGENT_CONTROL_MESSAGE_TYPE = "subagent_control_notice";
+
+export interface SubagentControlMessageDetails {
+	event: ControlEvent;
+	source?: "foreground" | "async";
+	asyncDir?: string;
+	childIntercomTarget?: string;
+	noticeText?: string;
+}
+
+export function controlNoticeTarget(details: SubagentControlMessageDetails): string | undefined {
+	return details.childIntercomTarget;
+}
+
+export function formatSubagentControlNotice(details: SubagentControlMessageDetails, content?: string): string {
+	return details.noticeText ?? content ?? formatControlNoticeMessage(details.event, controlNoticeTarget(details));
+}
+
+export function handleSubagentControlNotice(input: {
+	pi: Pick<ExtensionAPI, "sendMessage">;
+	visibleControlNotices: Set<string>;
+	details: SubagentControlMessageDetails;
+}): void {
+	if (!input.details?.event || isObsoleteIdleNotice(input.details)) return;
+	const childIntercomTarget = controlNoticeTarget(input.details);
+	const key = controlNotificationKey(input.details.event, childIntercomTarget);
+	if (input.visibleControlNotices.has(key)) return;
+	input.visibleControlNotices.add(key);
+	const noticeText = input.details.noticeText ?? formatControlNoticeMessage(input.details.event, childIntercomTarget);
+	input.pi.sendMessage(
+		{
+			customType: SUBAGENT_CONTROL_MESSAGE_TYPE,
+			content: noticeText,
+			display: true,
+			details: { ...input.details, childIntercomTarget, noticeText },
+		},
+		// Async completion-guard notices stay visible but let the matching completion
+		// result deliver the single automatic wakeup. In a parallel group that result
+		// arrives only after all siblings finish, so reaction to a mid-group guard
+		// notice is bounded by the longest-running sibling.
+		{ triggerTurn: !(input.details.source === "async" && input.details.event.reason === "completion_guard") },
+	);
+}

package/src/extension/doctor.ts

@@ -0,0 +1,171 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { VERSION as PI_VERSION, getPackageDir } from "@earendil-works/pi-coding-agent";
+import { EXTENSION_BUILD } from "./build-info.ts";
+import { discoverAgentsAll, type AgentSource } from "../agents/agents.ts";
+import { discoverAvailableSkills, type SkillSource } from "../agents/skills.ts";
+import {
+	ASYNC_DIR,
+	CHAIN_RUNS_DIR,
+	RESULTS_DIR,
+	TEMP_ROOT_DIR,
+	type ExtensionConfig,
+	type SubagentState,
+	type SubagentIntercomConnection,
+} from "../shared/types.ts";
+
+interface DoctorReportInput {
+	cwd: string;
+	nativeSessionCwd?: string;
+	config: ExtensionConfig;
+	state: SubagentState;
+	requestedSessionDir?: string;
+	currentSessionFile?: string | null;
+	currentSessionId?: string | null;
+	orchestratorTarget?: string;
+	connection?: SubagentIntercomConnection;
+	sessionError?: string;
+	expandTilde?: (value: string) => string;
+	projectTrusted?: boolean;
+}
+
+const PI_PACKAGE_DIR = getPackageDir();
+const EXTENSION_MODULE = fileURLToPath(import.meta.url);
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+
+function lineFromCheck(label: string, check: () => string): string {
+	try {
+		return check();
+	} catch (error) {
+		return `- ${label}: failed — ${errorText(error)}`;
+	}
+}
+
+function formatExistingDirectory(label: string, dirPath: string): string {
+	try {
+		if (!fs.existsSync(dirPath)) return `- ${label}: missing (${dirPath})`;
+		const stats = fs.statSync(dirPath);
+		if (!stats.isDirectory()) throw new Error(`not a directory: ${dirPath}`);
+		fs.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
+		return `- ${label}: ok (${dirPath})`;
+	} catch (error) {
+		return `- ${label}: failed (${dirPath}) — ${errorText(error)}`;
+	}
+}
+
+function formatSourceCounts(counts: Record<AgentSource, number>): string {
+	return `builtin ${counts.builtin}, package ${counts.package}, user ${counts.user}, project ${counts.project}`;
+}
+
+function formatSkillSourceCounts(skills: Array<{ source: SkillSource }>): string {
+	const counts = new Map<SkillSource, number>();
+	for (const skill of skills) counts.set(skill.source, (counts.get(skill.source) ?? 0) + 1);
+	const ordered: SkillSource[] = [
+		"project",
+		"project-settings",
+		"project-package",
+		"user",
+		"user-settings",
+		"user-package",
+		"extension",
+		"builtin",
+		"unknown",
+	];
+	const parts = ordered
+		.map((source) => `${source} ${counts.get(source) ?? 0}`)
+		.filter((part) => !part.endsWith(" 0"));
+	return parts.length > 0 ? parts.join(", ") : "none";
+}
+
+function formatConfiguredSessionDir(input: DoctorReportInput): string {
+	if (input.requestedSessionDir) {
+		return path.resolve(input.expandTilde?.(input.requestedSessionDir) ?? input.requestedSessionDir);
+	}
+	if (input.config.defaultSessionDir) {
+		return path.resolve(input.expandTilde?.(input.config.defaultSessionDir) ?? input.config.defaultSessionDir);
+	}
+	return "not configured";
+}
+
+function formatSessionLines(input: DoctorReportInput): string[] {
+	const sessionFile = input.currentSessionFile ?? null;
+	const lines = [
+		lineFromCheck("configured session dir", () => `- configured session dir: ${formatConfiguredSessionDir(input)}`),
+		`- current session file: ${sessionFile ?? "not available"}`,
+		`- current session dir: ${sessionFile ? path.dirname(sessionFile) : "not available"}`,
+		`- current session id: ${input.currentSessionId ?? input.state.currentSessionId ?? "not available"}`,
+	];
+	if (input.sessionError) lines.push(`- session manager: failed — ${input.sessionError}`);
+	return lines;
+}
+
+function formatDiscovery(input: DoctorReportInput): string[] {
+	return [
+		lineFromCheck("agents/chains", () => {
+			const discovered = discoverAgentsAll(input.cwd, { projectTrusted: input.projectTrusted ?? true });
+			const agentCounts = {
+				builtin: discovered.builtin.length,
+				package: discovered.package.length,
+				user: discovered.user.length,
+				project: discovered.project.length,
+			};
+			const chainCounts = discovered.chains.reduce<Record<AgentSource, number>>((counts, chain) => {
+				counts[chain.source] += 1;
+				return counts;
+			}, { builtin: 0, package: 0, user: 0, project: 0 });
+			return [
+				`- agents: total ${agentCounts.builtin + agentCounts.package + agentCounts.user + agentCounts.project} (${formatSourceCounts(agentCounts)})`,
+				`- chains: total ${discovered.chains.length} (${formatSourceCounts(chainCounts)})`,
+			].join("\n");
+		}),
+		lineFromCheck("skills", () => {
+			const skills = discoverAvailableSkills(input.cwd, { projectTrusted: input.projectTrusted ?? true });
+			return `- skills: total ${skills.length} (${formatSkillSourceCounts(skills)})`;
+		}),
+	];
+}
+
+function formatIntercomSection(input: DoctorReportInput): string[] {
+	return [
+		`- bridge: ${input.connection ? "responding" : "unavailable (no live health response)"}`,
+		`- connection: ${input.connection?.status ?? "unknown"}${input.connection?.reason ? ` — ${input.connection.reason}` : ""}`,
+		`- broker session id: ${input.connection?.sessionId ?? "not available"}`,
+		`- orchestrator target: ${input.orchestratorTarget?.trim() || "not available"}`,
+	];
+}
+
+export function buildDoctorReport(input: DoctorReportInput): string {
+	const lines = [
+		"Subagents doctor report",
+		"",
+		"Runtime",
+		`- Native session cwd: ${input.nativeSessionCwd ?? input.cwd}`,
+		...(input.nativeSessionCwd && input.nativeSessionCwd !== input.cwd ? [`- Requested cwd: ${input.cwd}`] : []),
+		`- Node: ${process.version}`,
+		`- process: ${process.pid} (${process.execPath})`,
+		`- loaded Pi version: ${PI_VERSION}`,
+		`- Pi package directory: ${PI_PACKAGE_DIR} (Pi resource path; may be overridden)`,
+		"- native queue contract: not verified (version alone does not identify fork patches)",
+		`- loaded pi-subagents build: ${EXTENSION_BUILD.version && EXTENSION_BUILD.sha256 ? `${EXTENSION_BUILD.version} (runtime SHA-256 ${EXTENSION_BUILD.sha256})` : "unknown (unbuilt source)"}`,
+		`- extension module: ${EXTENSION_MODULE}`,
+		"- async support: available (Node >=24)",
+		...formatSessionLines(input),
+		"",
+		"Filesystem",
+		formatExistingDirectory("temp root", TEMP_ROOT_DIR),
+		formatExistingDirectory("async runs", ASYNC_DIR),
+		formatExistingDirectory("results", RESULTS_DIR),
+		formatExistingDirectory("chain runs", CHAIN_RUNS_DIR),
+		"",
+		"Discovery",
+		...formatDiscovery(input),
+		"",
+		"Intercom",
+		...formatIntercomSection(input),
+	];
+	return lines.join("\n");
+}

package/src/extension/fanout-child.ts

@@ -0,0 +1,312 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { discoverAgents } from "../agents/agents.ts";
+import { getArtifactsDir } from "../shared/artifacts.ts";
+import { createSubagentExecutor, normalizeSubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
+import { interruptAsyncRun } from "../runs/foreground/foreground-control.ts";
+import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_EAGER_TOOL_ENV, SUBAGENT_PARENT_CHILD_INDEX_ENV } from "../runs/shared/pi-args.ts";
+import { readNestedControlRequests, resolveNestedRouteFromEnv, writeNestedControlResult } from "../runs/shared/nested-events.ts";
+import { deliverSubagentIntercomMessageEvent } from "../intercom/result-intercom.ts";
+import { resolveSubagentIntercomTarget } from "../intercom/intercom-bridge.ts";
+import { readStatus } from "../shared/utils.ts";
+import { SubagentParams } from "./schemas.ts";
+import { loadConfig } from "./config.ts";
+import { registerCompactSubagentTools } from "./compact-tools.ts";
+import { registerToolResultAdapter } from "./tool-result.ts";
+import { renderSubagentResult } from "../tui/render.ts";
+import { type Details, type SubagentExecutionResult, type SubagentState } from "../shared/types.ts";
+import { finalizedChildUsage, registerParentUsage } from "../runs/shared/parent-usage.ts";
+import { resolveCurrentSessionId } from "../shared/session-identity.ts";
+import { OWNED_RUN_ENTRY, ownedRunList, restoreOwnedRunsAsync } from "../runs/shared/run-records.ts";
+import { closeRunHistory, startRunHistory } from "../runs/shared/history-index.ts";
+import { createCompletionDelivery } from "../runs/background/completion-delivery.ts";
+
+function getSubagentSessionRoot(parentSessionFile: string | null): string {
+	if (parentSessionFile) {
+		const baseName = path.basename(parentSessionFile, ".jsonl");
+		const sessionsDir = path.dirname(parentSessionFile);
+		return path.join(sessionsDir, baseName);
+	}
+	return fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
+}
+
+function expandTilde(p: string): string {
+	return p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
+}
+
+function createChildSafeState(): SubagentState {
+	return {
+		baseCwd: "",
+		currentSessionId: null,
+		asyncJobs: new Map(),
+		foregroundRuns: new Map(),
+		cleanupTimers: new Map(),
+		lastUiContext: null,
+		poller: null,
+		completionSeen: new Map(),
+		watcher: null,
+		watcherRestartTimer: null,
+		resultFileCoalescer: {
+			schedule: () => false,
+			clear: () => {},
+		},
+	};
+}
+
+function addBounded(set: Set<string>, value: string, max = 1000): void {
+	set.add(value);
+	while (set.size > max) set.delete(set.values().next().value!);
+}
+
+function startNestedControlInboxListener(pi: ExtensionAPI, state: SubagentState, isRestoring: () => boolean): NodeJS.Timeout | undefined {
+	let route;
+	try {
+		route = resolveNestedRouteFromEnv();
+	} catch {
+		return undefined;
+	}
+	if (!route) return undefined;
+	const seen = new Set<string>();
+	const seenFiles = new Set<string>();
+	const inFlight = new Set<string>();
+	const pendingResults = new Map<string, Parameters<typeof writeNestedControlResult>[1]>();
+	const parsedChildIndex = Number(process.env[SUBAGENT_PARENT_CHILD_INDEX_ENV]);
+	const localChildIndex = Number.isInteger(parsedChildIndex) && parsedChildIndex >= 0 ? parsedChildIndex : undefined;
+	const timer = setInterval(() => {
+		if (isRestoring()) return;
+		try {
+			for (const request of readNestedControlRequests(route, seenFiles)) {
+				if (seen.has(request.requestId) || inFlight.has(request.requestId)) continue;
+				if (request.targetChildIndex !== undefined && request.targetChildIndex !== localChildIndex) continue;
+				const owned = state.ownedRuns?.get(request.targetRunId);
+				const asyncJob = state.asyncJobs.get(request.targetRunId);
+				if (!owned && !asyncJob && (request.targetChildIndex !== undefined || Date.now() - request.ts < 400)) continue;
+				inFlight.add(request.requestId);
+				void (async () => {
+					const claimPath = `${request.filePath}.claimed`;
+					try {
+						let result = pendingResults.get(request.requestId);
+						if (!result && pendingResults.size >= 100) {
+							result = {
+								ts: Date.now(),
+								requestId: request.requestId,
+								targetRunId: request.targetRunId,
+								ok: false,
+								message: "Nested control result queue is full; retry after pending results are delivered.",
+							};
+						}
+						if (!result) {
+							try {
+								const claimFd = fs.openSync(claimPath, "wx", 0o600);
+								try { fs.writeFileSync(claimFd, `${request.requestId}\n`, "utf-8"); } finally { fs.closeSync(claimFd); }
+							} catch (error) {
+								const code = error && typeof error === "object" && "code" in error ? (error as { code?: unknown }).code : undefined;
+								result = {
+									ts: Date.now(),
+									requestId: request.requestId,
+									targetRunId: request.targetRunId,
+									ok: false,
+									message: code === "EEXIST"
+										? "Nested control request was already claimed; refusing to execute it again because the original outcome is unavailable."
+										: `Failed to claim nested control request safely: ${error instanceof Error ? error.message : String(error)}`,
+								};
+							}
+						}
+						if (!result) {
+							let ok = false;
+							let message = "Control request failed.";
+							try {
+								const asyncDir = state.ownedRuns?.get(request.targetRunId)?.asyncDir ?? state.asyncJobs.get(request.targetRunId)?.asyncDir;
+								const status = asyncDir ? readStatus(asyncDir) : null;
+								if (!status || status.state !== "running") {
+									message = `Nested run ${request.targetRunId} is not active in this fanout child.`;
+								} else if (request.action === "interrupt") {
+									const receipt = interruptAsyncRun(state, request.targetRunId, request.index);
+									ok = Boolean(receipt && !receipt.isError);
+									message = receipt?.content.map((part) => part.type === "text" ? part.text : "").join("\n") ?? "Nested run is not interruptible.";
+								} else if (!request.message?.trim()) {
+									message = "Nested resume requires message.";
+								} else {
+									const index = request.index ?? status.steps?.findIndex((step) => step.status === "running") ?? -1;
+									const step = status.steps?.[index];
+									const agent = step?.status === "running" ? step.agent : undefined;
+									if (!agent) {
+										message = `Nested run ${request.targetRunId} has no active child message route.`;
+									} else {
+										const target = resolveSubagentIntercomTarget(request.targetRunId, agent, index);
+										ok = await deliverSubagentIntercomMessageEvent(
+											pi.events,
+											target,
+											`Follow-up for nested run ${request.targetRunId} (${agent}):\n\n${request.message.trim()}`,
+											500,
+											{ source: "nested-resume", runId: request.targetRunId, agent, index },
+										);
+										message = ok
+											? `Delivered follow-up to live nested run ${request.targetRunId}.`
+											: `Nested child intercom target is not registered: ${target}`;
+									}
+								}
+							} catch (error) {
+								message = error instanceof Error ? error.message : String(error);
+							}
+							result = { ts: Date.now(), requestId: request.requestId, targetRunId: request.targetRunId, ok, message };
+						}
+						try {
+							writeNestedControlResult(route, result);
+						} catch (error) {
+							if (pendingResults.size < 100 || pendingResults.has(request.requestId)) pendingResults.set(request.requestId, result);
+							console.error(`Failed to write nested control result for request '${request.requestId}' targeting '${request.targetRunId}' via inbox '${route.controlInbox}'; keeping request for retry:`, error);
+							return;
+						}
+						pendingResults.delete(request.requestId);
+						addBounded(seen, request.requestId);
+						addBounded(seenFiles, path.basename(request.filePath));
+						let requestRemoved = false;
+						try {
+							fs.unlinkSync(request.filePath);
+							requestRemoved = true;
+						} catch (error) {
+							const code = error && typeof error === "object" && "code" in error ? (error as { code?: unknown }).code : undefined;
+							requestRemoved = code === "ENOENT";
+						}
+						if (requestRemoved) {
+							try { fs.unlinkSync(claimPath); } catch {}
+						}
+					} finally {
+						inFlight.delete(request.requestId);
+					}
+				})();
+			}
+		} catch (error) {
+			console.error(`Failed to poll nested control inbox '${route.controlInbox}' for root '${route.rootRunId}':`, error);
+		}
+	}, 200);
+	timer.unref?.();
+	return timer;
+}
+
+export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI): void {
+	if (process.env[SUBAGENT_CHILD_ENV] !== "1" || process.env[SUBAGENT_FANOUT_CHILD_ENV] !== "1") return;
+
+	const globalStore = globalThis as Record<string, unknown>;
+	const registeredKey = "__piSubagentFanoutChildRegisteredApis";
+	const registeredApis = globalStore[registeredKey] instanceof WeakSet
+		? globalStore[registeredKey] as WeakSet<ExtensionAPI>
+		: new WeakSet<ExtensionAPI>();
+	globalStore[registeredKey] = registeredApis;
+	if (registeredApis.has(pi)) return;
+	registeredApis.add(pi);
+
+	const controlInboxCleanupStoreKey = "__piSubagentFanoutChildControlInboxCleanup";
+	const previousControlInboxCleanup = globalStore[controlInboxCleanupStoreKey];
+	if (typeof previousControlInboxCleanup === "function") {
+		try {
+			previousControlInboxCleanup();
+		} catch {
+			// Best effort cleanup for stale timers from an older reload.
+		}
+	}
+
+	const config = loadConfig();
+	const state = createChildSafeState();
+	state.persistOwnedRun = (run) => pi.appendEntry(OWNED_RUN_ENTRY, run);
+	let sessionReset: Promise<void> | undefined;
+	const ensureSessionState = (ctx: ExtensionContext): void | Promise<void> => {
+		const sessionId = resolveCurrentSessionId(ctx.sessionManager);
+		if (sessionReset) return sessionReset;
+		if (state.currentSessionId === sessionId) { state.lastUiContext = ctx; return; }
+		sessionReset = (async () => {
+			await completionDelivery.stopAndJoin();
+			state.lastUiContext = ctx;
+			void closeRunHistory(state).catch((error) => console.error("Could not close child history:", error));
+			state.foregroundRuns?.clear();
+			await restoreOwnedRunsAsync(state, ctx);
+			state.currentSessionId = sessionId;
+			startRunHistory(state, ctx);
+			completionDelivery.start();
+		})().finally(() => { sessionReset = undefined; });
+		return sessionReset;
+	};
+	pi.on("session_start", async (_event, ctx) => {
+		await ensureSessionState(ctx);
+	});
+	const executor = createSubagentExecutor({
+		pi,
+		state,
+		config,
+		// Keep the stock nested default foreground so evidence returns before this caller exits.
+		asyncByDefault: config.asyncByDefault === true,
+		tempArtifactsDir: getArtifactsDir(null),
+		getSubagentSessionRoot,
+		expandTilde,
+		discoverAgents,
+		allowMutatingManagementActions: false,
+		ensureSessionState,
+	});
+
+	const compact = config.compactChildTools !== false;
+	const toolNames = compact ? ["subagent", "delegate", "agent_runs"] : ["subagent"];
+	const parentUsage = registerParentUsage(pi, toolNames);
+	const completionDelivery = createCompletionDelivery(pi, state, parentUsage);
+	const adaptToolResult = registerToolResultAdapter(pi, toolNames);
+	const toRegisteredToolResult = (result: SubagentExecutionResult, ctx: ExtensionContext) => adaptToolResult(
+		result.details.wait?.status === "completed" && result.details.run?.ownerSessionId === ctx.sessionManager.getSessionId()
+			? parentUsage.attach(result, finalizedChildUsage(result.details.run.children, result.details.wait.index), ctx)
+			: result,
+	);
+	const acceptanceGuidelines = [
+		"For goal-style requests such as /goal, goal, active goal, or work until evidence says done, use explicit acceptance on the delegated run: criteria for the target, evidence/verify for proof, stopRules for constraints, and maxFinalizationTurns for the bounded loop.",
+		"For implementation handoffs from a plan, PRD, spec, issue, or broad fix, put implementation instructions and plan paths in task, and put the definition of done, evidence, verification commands, constraints, and loop cap in acceptance.",
+	];
+	const guidelines = [
+		"Delegate useful helper work within your assigned task when it saves time or improves quality; the original parent owns integration and final delivery.",
+		"Nested execution defaults to foreground unless configuration explicitly opts into async. Set async:false whenever the nested result must appear in this child's report; use async:true only for intentionally detached work.",
+		compact
+			? "Use load_subagent({advanced:false}), then agent_runs({action:'profiles'}) before delegation unless the executable agent is already known. Use load_subagent for advanced workflows."
+			: "Use subagent action:list before nested execution unless the executable nested agent is already known from the task context.",
+		"Do not use subagent child-safe mode for agent config mutation actions; create, update, and delete are blocked here.",
+	];
+	if (compact) registerCompactSubagentTools(pi, { executor, state, adapt: toRegisteredToolResult, guidelines: [...guidelines, ...acceptanceGuidelines], childSafe: true,
+		asyncByDefault: config.asyncByDefault === true, keepAdvancedActive: process.env[SUBAGENT_EAGER_TOOL_ENV] === "1",
+		listRuns: async (params, ctx) => { await ensureSessionState(ctx); return ownedRunList(state, params); },
+	});
+	const tool: ToolDefinition<typeof SubagentParams, Details> = {
+		name: "subagent",
+		defaultActive: !compact,
+		label: "Subagent",
+		description: [
+			"Delegate to subagents from child-safe fanout mode.",
+			...acceptanceGuidelines,
+			"Allowed management/control actions: list, get, status, history, search, nudge, interrupt, extend, resume, questions, answer, review, doctor. History/search browse only directly owned saved work; bounded previews and index freshness are not canonical proof. Exact status is concise; full:true includes the full task/configuration. Review notes are parent-only, not sent to children. Put actionable instructions in resume/nudge. Resume/answer overrides do not amend live acceptance.",
+			"Agent config mutation actions create, update, and delete are blocked in this mode.",
+		].join("\n"),
+		promptSnippet: "Delegate nested child-safe subagent work from an explicitly allowed fanout child.",
+		promptGuidelines: guidelines,
+		parameters: SubagentParams,
+		async execute(id, params, signal, onUpdate, ctx) {
+			return toRegisteredToolResult(await executor.execute(id, normalizeSubagentParamsLike(params), signal, onUpdate, ctx), ctx);
+		},
+		renderResult: renderSubagentResult,
+	};
+
+	pi.registerTool(tool);
+
+	const controlInboxTimer = startNestedControlInboxListener(pi, state, () => sessionReset !== undefined);
+	const clearControlInboxTimer = (): Promise<void> => {
+		if (controlInboxTimer) clearInterval(controlInboxTimer);
+		completionDelivery.stop();
+		return closeRunHistory(state);
+	};
+	globalStore[controlInboxCleanupStoreKey] = clearControlInboxTimer;
+
+	pi.on("session_shutdown", async () => {
+		if (controlInboxTimer) clearInterval(controlInboxTimer);
+		await completionDelivery.stopAndJoin({ preservePending: true });
+		await closeRunHistory(state);
+		if (globalStore[controlInboxCleanupStoreKey] === clearControlInboxTimer) {
+			delete globalStore[controlInboxCleanupStoreKey];
+		}
+	});
+}