@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/src/extension/index.ts

@@ -0,0 +1,649 @@
+/**
+ * Subagent Tool
+ *
+ * Full-featured subagent with sync and async modes.
+ * - Async (default): Background execution, emits events when done
+ * - Sync: Streams output, renders markdown, tracks usage
+ *
+ * Modes: single (agent + task), parallel (tasks[]), chain (chain[] with {previous})
+ * Toggle: async parameter (default: true, configurable via config.json)
+ *
+ * Config file: ~/.pi/agent/extensions/subagent/config.json
+ *   { "asyncByDefault": false, "maxSubagentDepth": 1, "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
+ */
+
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { keyText, type ExtensionAPI, type ExtensionContext, type MessageRenderOptions, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
+import { discoverAgents } from "../agents/agents.ts";
+import { ARTIFACT_CLEANUP_DAYS, cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
+import { resolveCurrentSessionId } from "../shared/session-identity.ts";
+import { cleanupOldChainDirs } from "../shared/settings.ts";
+import { cleanupOldRunStorage, ensureSafeTempPath, ensureTempRoot } from "../shared/temp-root.ts";
+import { renderSubagentResult } from "../tui/render.ts";
+import { AgentViewController } from "../tui/agent-view.ts";
+import { withMouseExpansion } from "../tui/action-hints.ts";
+import { SubagentParams } from "./schemas.ts";
+import { createSubagentExecutor, normalizeSubagentParamsLike, resolveAsyncExecutionMode } from "../runs/foreground/subagent-executor.ts";
+import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
+import { OWNED_RUN_ENTRY, rememberOwnedRun, restoreOwnedRunsAsync } from "../runs/shared/run-records.ts";
+import { closeRunHistory, startRunHistory } from "../runs/shared/history-index.ts";
+import { finalizedChildUsage, registerParentUsage } from "../runs/shared/parent-usage.ts";
+import { createCompletionDelivery } from "../runs/background/completion-delivery.ts";
+import { isObsoleteIdleNotice } from "../runs/shared/subagent-control.ts";
+import { applyForceTopLevelAsyncOverride } from "../runs/background/top-level-async.ts";
+import { registerSlashCommands } from "../slash/slash-commands.ts";
+import { registerPromptTemplateDelegationBridge } from "../slash/prompt-template-bridge.ts";
+import { registerSlashSubagentBridge } from "../slash/slash-bridge.ts";
+import { clearSlashSnapshots, getSlashRenderableSnapshot, resolveSlashMessageDetails, restoreSlashFinalSnapshots, type SlashMessageDetails } from "../slash/slash-live-state.ts";
+import type { SubagentNotifyDetails } from "../runs/background/notify.ts";
+import { SUBAGENT_CHILD_ENV } from "../runs/shared/pi-args.ts";
+import { formatDuration, shortenPath } from "../shared/formatters.ts";
+import { isTuiContext } from "../shared/ui-mode.ts";
+import { loadConfig } from "./config.ts";
+import { registerToolResultAdapter } from "./tool-result.ts";
+import { registerCompactSubagentTools } from "./compact-tools.ts";
+import {
+	type Details,
+	type SubagentExecutionResult,
+	type SubagentState,
+	ASYNC_DIR,
+	RESULTS_DIR,
+	SLASH_RESULT_TYPE,
+	SUBAGENT_ASYNC_COMPLETE_EVENT,
+	SUBAGENT_ASYNC_STARTED_EVENT,
+	SUBAGENT_CONTROL_EVENT,
+	WIDGET_KEY,
+} from "../shared/types.ts";
+import {
+	formatSubagentControlNotice,
+	handleSubagentControlNotice,
+	SUBAGENT_CONTROL_MESSAGE_TYPE,
+	type SubagentControlMessageDetails,
+} from "./control-notices.ts";
+
+export { loadConfig } from "./config.ts";
+
+const SUBAGENT_TOOL_NAME = "subagent";
+const SUBAGENT_GUIDELINES = [
+	"Use subagent for materially parallelizable scouting, review, or implementation work where another focused agent adds value.",
+	"Top-level subagent execution uses the stock async default unless configuration opts out. Launch a small bounded fanout of independent agents as separate single-agent runs so each completion wakes the parent, with at most one writer. Use one tasks call for non-review fanout when all child results are required together, when shared concurrency/task limits are needed, or when multiple writers require worktree isolation; the parent receives one aggregate completion. If no useful parent work remains, end the turn and wait instead of polling; completion wakes the parent. This also applies when an incomplete active Pi goal needs child evidence: yield, then continue the goal after automatic completion delivery. Set async:false only for explicitly chosen foreground execution.",
+	"Before executing subagent runs, call subagent with { action: \"list\" } unless the requested executable agent or chain is already known from this conversation.",
+	"Keep the parent session responsible for final decisions, verification, and user-facing status; treat subagent output as evidence to review, not automatic truth.",
+	"Fresh-child handoffs must include relevant exact user instructions and settled decisions or readable source references alongside the bounded task; summaries do not replace original requirements.",
+	"Keep independent review as a separate parent-launched reviewer run after the worker; acceptance.review is unsupported.",
+	"For review-only tasks, omit acceptance unless the user explicitly requests a same-session acceptance contract; acceptance adds a finalization turn and is not independent review.",
+	"For live child guidance, answers, corrections, or blockers, inspect status and prefer action='nudge'; it sends a non-blocking steer that supplements the active task unless the message explicitly replaces it. Use the shown blocking intercom ask only when the parent must stay alive waiting for a reply.",
+	"Do not use subagent when a direct local tool call or small edit is cheaper than delegation.",
+] as const;
+
+/**
+ * Derive subagent session base directory from parent session file.
+ * If parent session is ~/.pi/agent/sessions/abc123.jsonl,
+ * returns ~/.pi/agent/sessions/abc123/ as the base.
+ * Callers add runId to create the actual session root: abc123/{runId}/
+ * Falls back to a unique temp directory if no parent session.
+ */
+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 ensureAccessibleDir(dirPath: string): void {
+	ensureSafeTempPath(dirPath);
+	fs.mkdirSync(dirPath, { recursive: true });
+	fs.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
+}
+
+function isSlashResultRunning(result: SubagentExecutionResult): boolean {
+	return result.details?.progress?.some((entry) => entry.status === "running")
+		|| result.details?.results.some((entry) => entry.progress?.status === "running")
+		|| false;
+}
+
+function isSlashResultError(result: SubagentExecutionResult): boolean {
+	return result.details?.results.some((entry) => entry.exitCode !== 0 && entry.progress?.status !== "running") || false;
+}
+
+function isStaleExtensionContextError(error: unknown): boolean {
+	return error instanceof Error && error.message.includes("Extension context no longer active");
+}
+
+function rebuildSlashResultContainer(
+	container: Container,
+	result: SubagentExecutionResult,
+	options: MessageRenderOptions,
+	theme: ExtensionContext["ui"]["theme"],
+): void {
+	container.clear();
+	if ("compactView" in options && options.compactView === true && !options.expanded) {
+		container.addChild(renderSubagentResult(result, options, theme));
+		return;
+	}
+	container.addChild(new Spacer(1));
+	const boxTheme = isSlashResultRunning(result) ? "toolPendingBg" : isSlashResultError(result) ? "toolErrorBg" : "toolSuccessBg";
+	const box = new Box(1, 1, (text: string) => theme.bg(boxTheme, text));
+	box.addChild(renderSubagentResult(result, options, theme));
+	container.addChild(box);
+}
+
+function createSlashResultComponent(
+	details: SlashMessageDetails,
+	options: MessageRenderOptions,
+	theme: ExtensionContext["ui"]["theme"],
+): Container {
+	const container = new Container();
+	let lastVersion = -1;
+	container.render = (width: number): string[] => {
+		const snapshot = getSlashRenderableSnapshot(details);
+		if (snapshot.version !== lastVersion) {
+			lastVersion = snapshot.version;
+			rebuildSlashResultContainer(container, snapshot.result, options, theme);
+		}
+		if ("compactView" in options && options.compactView === true && !options.expanded) {
+			const key = keyText("app.tools.expand");
+			const hint = key ? theme.fg("dim", ` · ${key}`) : "";
+			const [heading = ""] = Container.prototype.render.call(container, Math.max(1, width - options.outputPad - visibleWidth(hint)));
+			return [truncateToWidth(`${" ".repeat(options.outputPad)}${heading.replace(/\s+/g, " ").trimEnd()}${hint}`, width)];
+		}
+		return Container.prototype.render.call(container, width);
+	};
+	return container;
+}
+
+function parseSubagentNotifyContent(content: string): SubagentNotifyDetails | undefined {
+	const lines = content.split("\n");
+	const header = lines[0] ?? "";
+	const match = header.match(/^Background task (completed|failed|blocked|paused): \*\*(.+?)\*\*(?:\s+(\([^)]*\)))?$/);
+	if (!match) return undefined;
+	const body = lines.slice(2);
+	let sessionIndex = -1;
+	for (let i = body.length - 1; i >= 1; i--) {
+		if (body[i - 1]?.trim() === "" && /^(Session|Session file|Session share error):\s+/.test(body[i]!)) {
+			sessionIndex = i;
+			break;
+		}
+	}
+	const sessionLine = sessionIndex >= 0 ? body[sessionIndex] : undefined;
+	const resultLines = sessionIndex >= 0 ? body.slice(0, sessionIndex) : body;
+	const resultPreview = resultLines.join("\n").trim() || "(no output)";
+	let sessionLabel: string | undefined;
+	let sessionValue: string | undefined;
+	if (sessionLine) {
+		const separator = sessionLine.indexOf(":");
+		sessionLabel = sessionLine.slice(0, separator).toLowerCase();
+		sessionValue = sessionLine.slice(separator + 1).trim();
+	}
+	return {
+		agent: match[2]!,
+		status: match[1] as SubagentNotifyDetails["status"],
+		...(match[3] ? { taskInfo: match[3] } : {}),
+		resultPreview,
+		...(sessionLabel && sessionValue ? { sessionLabel, sessionValue } : {}),
+	};
+}
+
+class SubagentControlNoticeComponent implements Component {
+	private readonly details: SubagentControlMessageDetails;
+	private readonly theme: ExtensionContext["ui"]["theme"];
+
+	constructor(details: SubagentControlMessageDetails, theme: ExtensionContext["ui"]["theme"]) {
+		this.details = details;
+		this.theme = theme;
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const eventLabel = this.details.event.type.replaceAll("_", " ");
+		if (width < 3) return [truncateToWidth(`Subagent ${eventLabel}`, width)];
+		const bodyWidth = Math.max(1, width - 2);
+		const borderChar = "─";
+		const header = ` ⚠ Subagent ${eventLabel}: ${this.details.event.agent} `;
+		const headerText = truncateToWidth(header, bodyWidth, "");
+		const headerPadding = Math.max(0, bodyWidth - visibleWidth(headerText));
+		const lines = [this.theme.fg("accent", `╭${headerText}${borderChar.repeat(headerPadding)}╮`)];
+
+		for (const line of wrapTextWithAnsi(formatSubagentControlNotice(this.details), bodyWidth)) {
+			const text = truncateToWidth(line, bodyWidth, "");
+			const padding = Math.max(0, bodyWidth - visibleWidth(text));
+			lines.push(this.theme.fg("accent", `│${text}${" ".repeat(padding)}│`));
+		}
+		lines.push(this.theme.fg("accent", `╰${borderChar.repeat(bodyWidth)}╯`));
+		return lines;
+	}
+}
+
+export default function registerSubagentExtension(pi: ExtensionAPI): void {
+	if (process.env[SUBAGENT_CHILD_ENV] === "1") {
+		// Child runs get child-safe nested delegation from the explicit fanout-child
+		// runtime extension injected by buildPiArgs. Keep the parent extension inert
+		// when global package discovery also loads index.ts in the child process.
+		return;
+	}
+	try {
+		ensureTempRoot();
+	} catch (error) {
+		console.error(`[pi-subagents] temp storage setup failed: ${error instanceof Error ? error.message : String(error)}`);
+		return;
+	}
+	const globalStore = globalThis as Record<string, unknown>;
+	const runtimeCleanupStoreKey = "__piSubagentRuntimeCleanup";
+	const previousRuntimeCleanup = globalStore[runtimeCleanupStoreKey];
+	if (typeof previousRuntimeCleanup === "function") {
+		try {
+			previousRuntimeCleanup();
+		} catch {
+			// Best effort cleanup for stale timers from an older reload.
+		}
+	}
+
+	const config = loadConfig();
+	// Root calls default async; child-safe nested calls intentionally keep their stock foreground default.
+	const asyncByDefault = config.asyncByDefault !== false;
+	const tempArtifactsDir = getArtifactsDir(null);
+
+	let agentView: AgentViewController | undefined;
+	let sessionReset: Promise<void> | undefined;
+	const state: SubagentState = {
+		baseCwd: "",
+		currentSessionId: null,
+		asyncJobs: new Map(),
+		foregroundRuns: new Map(),
+		ownedRuns: new Map(),
+		persistOwnedRun: (run) => pi.appendEntry(OWNED_RUN_ENTRY, run),
+		cleanupTimers: new Map(),
+		lastUiContext: null,
+		poller: null,
+		completionSeen: new Map(),
+		watcher: null,
+		watcherRestartTimer: null,
+		resultFileCoalescer: {
+			schedule: () => false,
+			clear: () => {},
+		},
+	};
+
+	const runtimeCleanup = () => {
+		agentView?.dispose();
+		void closeRunHistory(state).catch((error) => console.error("Could not close subagent history:", error));
+		completionDelivery.stop();
+		if (state.poller) {
+			clearInterval(state.poller);
+			state.poller = null;
+		}
+	};
+	globalStore[runtimeCleanupStoreKey] = runtimeCleanup;
+
+	const { ensurePoller, handleStarted, handleComplete, restoreJobs, resetJobs } = createAsyncJobTracker(pi, state, ASYNC_DIR, { render: () => agentView?.refresh() });
+	const executor = createSubagentExecutor({
+		pi,
+		state,
+		config,
+		asyncByDefault,
+		tempArtifactsDir,
+		getSubagentSessionRoot,
+		expandTilde,
+		discoverAgents,
+		ensureSessionState: (ctx) => {
+			if (sessionReset) return sessionReset;
+			if (state.currentSessionId !== resolveCurrentSessionId(ctx.sessionManager)) return resetSessionState(ctx);
+		},
+	});
+
+	agentView = new AgentViewController(pi, state, (params, ctx) => executor.execute(randomUUID(), params, undefined, undefined, ctx));
+	state.onRunsChanged = () => agentView?.refresh();
+
+	pi.registerMessageRenderer<SlashMessageDetails>(SLASH_RESULT_TYPE, withMouseExpansion((message, options, theme) => {
+		const details = resolveSlashMessageDetails(message.details);
+		if (!details) return undefined;
+		return createSlashResultComponent(details, options, theme);
+	}));
+
+	pi.registerMessageRenderer<SubagentNotifyDetails>("subagent-notify", withMouseExpansion((message, options, theme) => {
+		const content = typeof message.content === "string" ? message.content : "";
+		const details = (message.details as SubagentNotifyDetails | undefined) ?? parseSubagentNotifyContent(content);
+		const compact = "compactView" in options && options.compactView === true && !options.expanded;
+		const compactPreview = (text: string): Component => ({
+			render(width) {
+				const key = keyText("app.tools.expand");
+				const hint = key ? theme.fg("dim", ` · ${key}`) : "";
+				const line = `${" ".repeat(options.outputPad)}${text.replace(/\s+/g, " ").trim()}`;
+				return [truncateToWidth(truncateToWidth(line, width - visibleWidth(hint)) + hint, width)];
+			},
+			invalidate() {},
+		});
+		if (!details) return compact
+			? compactPreview(content.split("\n").find((line) => line.trim()) || "(no output)")
+			: new Text(content, 0, 0);
+		const icon = details.status === "completed"
+			? theme.fg("success", "✓")
+			: details.status === "paused" || details.status === "blocked"
+				? theme.fg("warning", "■")
+				: theme.fg("error", "✗");
+		const parts: string[] = [];
+		if (details.taskInfo) parts.push(details.taskInfo);
+		if (details.durationMs !== undefined) parts.push(formatDuration(details.durationMs));
+		let text = `${icon} ${theme.bold(details.agent)} ${theme.fg("dim", details.status)}`;
+		if (parts.length > 0) text += ` ${theme.fg("dim", "·")} ${parts.map((part) => theme.fg("dim", part)).join(` ${theme.fg("dim", "·")} `)}`;
+		const trimmedPreview = details.resultPreview.trim();
+		if (compact) return compactPreview(`${text} · ${theme.fg("dim", trimmedPreview.split("\n", 1)[0] || "(no output)")}`);
+		const previewLines = options.expanded
+			? trimmedPreview.split("\n").filter((line) => line.trim())
+			: [trimmedPreview.split("\n", 1)[0] ?? ""].filter((line) => line.trim());
+		for (const line of previewLines.length > 0 ? previewLines : ["(no output)"]) {
+			text += `\n  ${theme.fg("dim", `⎿  ${line}`)}`;
+		}
+		const expandKey = keyText("app.tools.expand");
+		if (!options.expanded && expandKey) {
+			text += `\n  ${theme.fg("dim", `${expandKey} full notification`)}`;
+		}
+		if (details.sessionLabel && details.sessionValue) {
+			text += `\n  ${theme.fg("muted", `${details.sessionLabel}: ${shortenPath(details.sessionValue)}`)}`;
+		}
+		if (options.expanded) return new Text(text, 0, 0);
+		return {
+			render: (width) => text.split("\n").map((line) => truncateToWidth(line, width)),
+			invalidate() {},
+		};
+	}));
+
+	pi.registerMessageRenderer<SubagentControlMessageDetails>(SUBAGENT_CONTROL_MESSAGE_TYPE, (message, _options, theme) => {
+		const details = message.details as SubagentControlMessageDetails | undefined;
+		if (!details?.event) return undefined;
+		const content = typeof message.content === "string" ? message.content : undefined;
+		return new SubagentControlNoticeComponent({ ...details, noticeText: formatSubagentControlNotice(details, content) }, theme);
+	});
+
+	const slashBridge = registerSlashSubagentBridge({
+		events: pi.events,
+		getContext: () => state.lastUiContext,
+		execute: (id, params, signal, onUpdate, ctx, executionCwd) =>
+			executor.execute(id, params, signal, onUpdate, ctx, executionCwd),
+	});
+
+	const promptTemplateBridge = registerPromptTemplateDelegationBridge({
+		events: pi.events,
+		getContext: () => state.lastUiContext,
+		execute: async (requestId, request, signal, ctx, onUpdate) => {
+			if (request.tasks && request.tasks.length > 0) {
+				return executor.execute(
+					requestId,
+					{
+						tasks: request.tasks,
+						context: request.context,
+						cwd: request.cwd,
+						worktree: request.worktree,
+						async: false,
+						clarify: false,
+					},
+					signal,
+					onUpdate,
+					ctx,
+				);
+			}
+			return executor.execute(
+				requestId,
+				{
+					agent: request.agent,
+					task: request.task,
+					context: request.context,
+					cwd: request.cwd,
+					model: request.model,
+					async: false,
+					clarify: false,
+				},
+				signal,
+				onUpdate,
+				ctx,
+			);
+		},
+	});
+
+	function effectiveParallelTaskCount(tasks: Array<{ count?: unknown }> | undefined): number {
+		if (!tasks || tasks.length === 0) return 0;
+		return tasks.reduce((total, task) => {
+			const count = typeof task.count === "number" && Number.isInteger(task.count) && task.count >= 1 ? task.count : 1;
+			return total + count;
+		}, 0);
+	}
+
+	const toolNames = [SUBAGENT_TOOL_NAME, "delegate", "agent_runs"];
+	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 reconcileRunTools = registerCompactSubagentTools(pi, { executor, state, adapt: toRegisteredToolResult, guidelines: SUBAGENT_GUIDELINES, asyncByDefault });
+
+	const tool: ToolDefinition<typeof SubagentParams, Details> = {
+		name: SUBAGENT_TOOL_NAME,
+		defaultActive: false,
+		label: "Subagent",
+		description: `Delegate bounded work to configured Pi subagents, chains, or parallel reviewers; manage agent definitions; inspect/control async runs. Indexed status lists support global agent/state/text filters and sort/cursors; history pages bounded native previews and search finds saved visible words or one quoted phrase. Browse freshness is not canonical proof. Use exactly one execution mode (agent, tasks, or chain) or one management/control action. Before execution, use { action: "list" } to inspect configured agents/chains. Only execute agents listed as executable/non-disabled. Parallel tasks support output?,reads?,progress?. maxOutput accepts { bytes?: number, lines?: number }. Prefer acceptance for goal/spec handoffs and status/resume/interrupt/extend/nudge for active runs. Exact status is concise by default; full:true includes the full task/configuration. Review notes are parent-only, not sent to children; put actionable instructions in resume/nudge. Resume/answer preserves saved settings unless agent selects a current profile (including model/thinking/fallbacks); a separate model override wins. Live guidance never mutates model or acceptance.`,
+		parameters: SubagentParams,
+
+		async execute(id, params, signal, onUpdate, ctx) {
+			return toRegisteredToolResult(await executor.execute(id, normalizeSubagentParamsLike(params), signal, onUpdate, ctx), ctx);
+		},
+
+		renderCall(args, theme) {
+			if (args.action) {
+				const target = args.agent || args.chainName || "";
+				return new Text(
+					`${theme.fg("toolTitle", theme.bold("subagent "))}${args.action}${target ? ` ${theme.fg("accent", target)}` : ""}`,
+					0, 0,
+				);
+			}
+			const isParallel = (args.tasks?.length ?? 0) > 0;
+			const parallelCount = effectiveParallelTaskCount(args.tasks as Array<{ count?: unknown }> | undefined);
+			const renderedArgs = applyForceTopLevelAsyncOverride(args, 0, config.forceTopLevelAsync === true);
+			const asyncLabel = resolveAsyncExecutionMode(renderedArgs, asyncByDefault).effectiveAsync ? theme.fg("warning", " [async]") : "";
+			if (args.chain?.length)
+				return new Text(
+					`${theme.fg("toolTitle", theme.bold("subagent "))}chain (${args.chain.length})${asyncLabel}`,
+					0,
+					0,
+				);
+			if (isParallel)
+				return new Text(
+					`${theme.fg("toolTitle", theme.bold("subagent "))}parallel (${parallelCount})${asyncLabel}`,
+					0,
+					0,
+				);
+			return new Text(
+				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent || "?")}${asyncLabel}`,
+				0,
+				0,
+			);
+		},
+
+		renderResult: renderSubagentResult,
+
+	};
+
+	pi.registerTool(tool);
+
+	registerSlashCommands(pi, state);
+
+	const eventUnsubscribeStoreKey = "__piSubagentEventUnsubscribes";
+	const controlNoticeSeenStoreKey = "__piSubagentVisibleControlNotices";
+	const previousEventUnsubscribes = globalStore[eventUnsubscribeStoreKey];
+	if (Array.isArray(previousEventUnsubscribes)) {
+		for (const unsubscribe of previousEventUnsubscribes) {
+			if (typeof unsubscribe !== "function") continue;
+			try {
+				unsubscribe();
+			} catch {
+				// Best effort cleanup for stale handlers from an older reload.
+			}
+		}
+	}
+
+	const existingVisibleControlNotices = globalStore[controlNoticeSeenStoreKey];
+	const visibleControlNotices = existingVisibleControlNotices instanceof Set ? existingVisibleControlNotices as Set<string> : new Set<string>();
+	globalStore[controlNoticeSeenStoreKey] = visibleControlNotices;
+	const pendingIdleNotices = new Map<string, SubagentControlMessageDetails>();
+	const deliverControlNotice = (details: SubagentControlMessageDetails) => {
+		handleSubagentControlNotice({
+			pi,
+			visibleControlNotices,
+			details,
+		});
+	};
+	const controlEventHandler = (payload: unknown) => {
+		const details = payload as SubagentControlMessageDetails;
+		// The runner's event log retains the raw notice. Keep only its reference here
+		// until the current turn ends, rather than admitting stale work to Pi's queue.
+		if (details?.source === "async" && details.event?.reason === "idle" && !details.event.supervisorQuestion && state.lastUiContext && !state.lastUiContext.isIdle()) {
+			pendingIdleNotices.set(`${details.event.runId}:${details.event.index ?? ""}`, details);
+			return;
+		}
+		deliverControlNotice(details);
+	};
+	const flushIdleNotices = () => {
+		for (const details of pendingIdleNotices.values()) deliverControlNotice(details);
+		pendingIdleNotices.clear();
+	};
+	pi.on("turn_end", flushIdleNotices);
+	pi.on("agent_before_settle", flushIdleNotices);
+	pi.on("context", (event) => ({
+		messages: event.messages.filter((message) => message.role !== "custom"
+			|| message.customType !== SUBAGENT_CONTROL_MESSAGE_TYPE
+			|| !isObsoleteIdleNotice(message.details as SubagentControlMessageDetails)),
+	}));
+	const subscribeEvents = () => [
+		pi.events.on(SUBAGENT_ASYNC_STARTED_EVENT, (data) => {
+			handleStarted(data);
+			const started = data as import("../shared/types.ts").AsyncStartedEvent;
+			const run = started.id ? state.ownedRuns?.get(started.id) : undefined;
+			if (run) rememberOwnedRun(state, { ...run, source: "async", asyncDir: started.asyncDir, pid: started.pid });
+		}),
+		pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, handleComplete),
+		pi.events.on(SUBAGENT_CONTROL_EVENT, controlEventHandler),
+	];
+	let eventUnsubscribes = subscribeEvents();
+	globalStore[eventUnsubscribeStoreKey] = eventUnsubscribes;
+
+	pi.on("tool_result", (event, ctx) => {
+		if (![SUBAGENT_TOOL_NAME, "delegate", "agent_runs"].includes(event.toolName)) return;
+		if (!isTuiContext(ctx)) return;
+		state.lastUiContext = ctx;
+		if (state.asyncJobs.size > 0) {
+			agentView?.refresh();
+			const uiWithRender: ExtensionContext["ui"] & { requestRender?: () => void } = ctx.ui;
+			uiWithRender.requestRender?.();
+			ensurePoller();
+		}
+	});
+
+	const cleanupSessionArtifacts = async (ctx: ExtensionContext) => {
+		try {
+			const sessionFile = ctx.sessionManager.getSessionFile();
+			if (sessionFile) {
+				await cleanupOldArtifacts(getArtifactsDir(sessionFile), ARTIFACT_CLEANUP_DAYS);
+			}
+		} catch {
+			// Cleanup failures should not block session lifecycle events.
+		}
+	};
+
+	function resetSessionState(ctx: ExtensionContext): Promise<void> {
+		if (sessionReset) return sessionReset;
+		sessionReset = restoreSession(ctx).finally(() => { sessionReset = undefined; });
+		return sessionReset;
+	}
+
+	async function restoreSession(ctx: ExtensionContext): Promise<void> {
+		pendingIdleNotices.clear();
+		agentView?.dispose();
+		if (state.poller) clearInterval(state.poller);
+		state.poller = null;
+		await completionDelivery.stopAndJoin();
+		void closeRunHistory(state).catch((error) => console.error("Could not close subagent history:", error));
+		ensureAccessibleDir(RESULTS_DIR);
+		ensureAccessibleDir(ASYNC_DIR);
+		state.baseCwd = ctx.cwd;
+		state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
+		state.lastUiContext = ctx;
+		resetJobs();
+		const restoration = await restoreOwnedRunsAsync(state, ctx);
+		try {
+			restoreJobs(state.currentSessionId, ctx, restoration);
+		} catch (error) {
+			console.error("Failed to restore active async jobs:", error);
+			resetJobs(ctx);
+		}
+		startRunHistory(state, ctx);
+		void reconcileRunTools();
+		agentView?.start(ctx);
+		await cleanupOldRunStorage();
+		await cleanupOldChainDirs();
+		await cleanupAllArtifactDirs(ARTIFACT_CLEANUP_DAYS);
+		await cleanupSessionArtifacts(ctx);
+		restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
+		completionDelivery.start();
+	}
+
+	pi.on("session_start", async (_event, ctx) => {
+		if (!eventUnsubscribes.length) {
+			eventUnsubscribes = subscribeEvents();
+			globalStore[eventUnsubscribeStoreKey] = eventUnsubscribes;
+		}
+		await resetSessionState(ctx);
+		await reconcileRunTools();
+	});
+
+	pi.on("session_shutdown", async () => {
+		agentView?.dispose();
+		if (state.poller) clearInterval(state.poller);
+		state.poller = null;
+		await completionDelivery.stopAndJoin({ preservePending: true });
+		await closeRunHistory(state);
+		for (const unsubscribe of eventUnsubscribes) {
+			try {
+				unsubscribe();
+			} catch {
+				// Best effort cleanup during shutdown.
+			}
+		}
+		if (globalStore[eventUnsubscribeStoreKey] === eventUnsubscribes) {
+			delete globalStore[eventUnsubscribeStoreKey];
+		}
+		eventUnsubscribes = [];
+		for (const timer of state.cleanupTimers.values()) {
+			clearTimeout(timer);
+		}
+		state.cleanupTimers.clear();
+		state.asyncJobs.clear();
+		clearSlashSnapshots();
+		slashBridge.cancelAll();
+		slashBridge.dispose();
+		promptTemplateBridge.cancelAll();
+		promptTemplateBridge.dispose();
+		if (globalStore[runtimeCleanupStoreKey] === runtimeCleanup) {
+			delete globalStore[runtimeCleanupStoreKey];
+		}
+		try {
+			if (state.lastUiContext && isTuiContext(state.lastUiContext)) {
+				state.lastUiContext.ui.setWidget(WIDGET_KEY, undefined);
+			}
+		} catch (error) {
+			if (!isStaleExtensionContextError(error)) throw error;
+		}
+	});
+}