@ryan_nookpi/pi-extension-subagent 0.2.1 → 0.3.1

package/commands.ts

@@ -42,6 +42,7 @@ import {
 } from "./group-pending.js";
 import { enqueueSubagentInvocation } from "./invocation-queue.js";
 import { appendDisplayTaskUpdate, getSessionFileSize } from "./persisted-session.js";
+import { SUBAGENT_COMMANDS, type SubagentCommandName } from "./registration-manifest.js";
 import { readSessionReplayItems, SubagentSessionReplayOverlay } from "./replay.js";
 import { invokeWithAutoRetry, MAX_SUBAGENT_AUTO_RETRIES } from "./retry.js";
 import { getLatestRun, removeRun, trimCommandRunHistory } from "./run-utils.js";
@@ -890,7 +891,18 @@ function finalizeHumanOnlyCompletion(
 	store.globalLiveRuns.delete(runId);
 }
 
-export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
+export type SubagentCommandDefinition = Parameters<ExtensionAPI["registerCommand"]>[1];
+
+export interface SubagentRegistrations {
+	commands: ReadonlyMap<SubagentCommandName, SubagentCommandDefinition>;
+}
+
+export function registerAll(pi: ExtensionAPI, store: SubagentStore): SubagentRegistrations {
+	const commandDefinitions = new Map<SubagentCommandName, SubagentCommandDefinition>();
+	const defineCommand = (name: SubagentCommandName, definition: SubagentCommandDefinition): void => {
+		commandDefinitions.set(name, definition);
+	};
+
 	pi.registerTool({
 		name: "list-agents",
 		label: "List Agents",
@@ -958,8 +970,7 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 	});
 
 	const subCommand = {
-		description:
-			"Run a subagent in a dedicated sub-session: /sub:isolate <agent|alias> <task>, /sub:isolate <runId> <task>, /sub:isolate <task> (uses configured defaultAgent)",
+		description: SUBAGENT_COMMANDS["sub:isolate"],
 		getArgumentCompletions: (argumentPrefix: string) => {
 			const trimmedStart = argumentPrefix.trimStart();
 			if (trimmedStart.includes(" ")) return null;
@@ -1574,10 +1585,10 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	};
 
-	pi.registerCommand("sub:isolate", subCommand);
+	defineCommand("sub:isolate", subCommand);
 
-	pi.registerCommand("sub:main", {
-		description: "Run a subagent with main-session context inheritance: /sub:main <agent|alias> <task>",
+	defineCommand("sub:main", {
+		description: SUBAGENT_COMMANDS["sub:main"],
 		getArgumentCompletions: subCommand.getArgumentCompletions,
 		handler: async (args, ctx) => {
 			captureSwitchSession(store, ctx);
@@ -1586,8 +1597,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("subagents", {
-		description: "List available subagents and offer the starter pack when none are configured",
+	defineCommand("subagents", {
+		description: SUBAGENT_COMMANDS.subagents,
 		handler: async (_args, ctx) => {
 			captureSwitchSession(store, ctx);
 			const starterPack = await offerStarterPackIfEmpty(ctx);
@@ -1619,8 +1630,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("sub:peek", {
-		description: "Show the latest response from a subagent in an overlay: /sub:peek [runId]",
+	defineCommand("sub:peek", {
+		description: SUBAGENT_COMMANDS["sub:peek"],
 		getArgumentCompletions: (argumentPrefix) => {
 			const trimmedStart = argumentPrefix.trimStart();
 			if (trimmedStart.includes(" ")) return null;
@@ -1643,8 +1654,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("sub:open", {
-		description: "Open a subagent session replay overlay: /sub:open [runId]",
+	defineCommand("sub:open", {
+		description: SUBAGENT_COMMANDS["sub:open"],
 		getArgumentCompletions: (argumentPrefix) => {
 			const trimmedStart = argumentPrefix.trimStart();
 			if (trimmedStart.includes(" ")) return null;
@@ -1735,8 +1746,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("sub:history", {
-		description: "Show all subagent run history (including removed) in an overlay: /sub:history",
+	defineCommand("sub:history", {
+		description: SUBAGENT_COMMANDS["sub:history"],
 		handler: async (_args, ctx) => {
 			captureSwitchSession(store, ctx);
 
@@ -1787,8 +1798,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		},
 	});
 
-	pi.registerCommand("sub:rm", {
-		description: "Remove one /sub job entry (aborts it if running): /sub:rm [runId]",
+	defineCommand("sub:rm", {
+		description: SUBAGENT_COMMANDS["sub:rm"],
 		handler: async (args, ctx) => {
 			captureSwitchSession(store, ctx);
 			const raw = (args ?? "").trim();
@@ -1871,8 +1882,8 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		ctx.ui.notify(`Cleared ${removed} finished subagent job(s).`, "info");
 	};
 
-	pi.registerCommand("sub:clear", {
-		description: "Clear /sub job widget entries. /sub:clear (finished only) or /sub:clear all",
+	defineCommand("sub:clear", {
+		description: SUBAGENT_COMMANDS["sub:clear"],
 		handler: async (args, ctx) => {
 			await handleSubClear(args, ctx);
 		},
@@ -1947,23 +1958,16 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		ctx.ui.notify("Usage: /sub:abort [runId|all]", "info");
 	};
 
-	pi.registerCommand("sub:abort", {
-		description: "Abort running subagent job(s). /sub:abort [runId|all]",
+	defineCommand("sub:abort", {
+		description: SUBAGENT_COMMANDS["sub:abort"],
 		handler: async (args, ctx) => {
 			captureSwitchSession(store, ctx);
 			await handleSubAbort(args, ctx);
 		},
 	});
 
-	// Only actual keyboard shortcuts appear in the /hotkeys Extensions section.
-	// NOTE: plain ">" is a real keybinding and hijacks editor text input,
-	// so the hidden subagent prefix is documented via footer/status hints instead.
-	pi.registerShortcut(">>" as any, {
-		description: "Run subagent task",
-		handler: async () => {
-			// Documentation-only entry.
-		},
-	});
+	// Text-prefix shortcuts are registered synchronously in index.ts for
+	// /hotkeys visibility. Their actual routing remains in the input handlers below.
 
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") {
@@ -2073,13 +2077,6 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 	});
 
 	// #<runId> shortcut: resume a subagent run (e.g. #42 keep going)
-	pi.registerShortcut("#<runId>" as any, {
-		description: "Resume subagent run: #<runId> <task>",
-		handler: async () => {
-			// Documentation-only entry.
-		},
-	});
-
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") {
 			return { action: "continue" as const };
@@ -2126,20 +2123,6 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 	});
 
 	// << shortcut: abort running jobs or clear finished jobs
-	pi.registerShortcut("<<" as any, {
-		description: "Abort or clear subagent runs",
-		handler: async () => {
-			// Documentation-only entry.
-		},
-	});
-
-	pi.registerShortcut("<<<" as any, {
-		description: "Clear finished subagent jobs (= /sub:clear). <<< all to clear all",
-		handler: async () => {
-			// Documentation-only entry.
-		},
-	});
-
 	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") {
 			return { action: "continue" as const };
@@ -2227,82 +2210,98 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		return { action: "handled" as const };
 	});
 
-	// ── onTerminalInput hack: auto-redirect <>7 to /sub:peek 7 ───────────
-	let unsubTerminalInput: (() => void) | null = null;
+	const missingCommands = (Object.keys(SUBAGENT_COMMANDS) as SubagentCommandName[]).filter(
+		(name) => !commandDefinitions.has(name),
+	);
+	if (missingCommands.length > 0) {
+		throw new Error(`Missing subagent command definitions: ${missingCommands.join(", ")}`);
+	}
 
-	function registerTerminalInputRedirect(ctx: any): void {
-		// Unsubscribe previous listener to avoid duplicates on session change.
-		unsubTerminalInput?.();
-		unsubTerminalInput = null;
+	return { commands: commandDefinitions };
+}
 
-		unsubTerminalInput = ctx.ui.onTerminalInput((data: string) => {
-			// Only intercept Enter key (all terminal variants).
-			if (!matchesKey(data, "enter")) return undefined;
+// ── onTerminalInput hack: auto-redirect <>7 to /sub:peek 7 ───────────
+let unsubTerminalInput: (() => void) | null = null;
 
-			const editorText = (ctx.ui.getEditorText() ?? "").trim();
+function registerTerminalInputRedirect(ctx: any): void {
+	// Unsubscribe previous listener to avoid duplicates on session change.
+	unsubTerminalInput?.();
+	unsubTerminalInput = null;
 
-			// <>7  →  /sub:peek 7
-			const compactPeekMatch = /^<>(\d+)$/.exec(editorText);
-			if (compactPeekMatch?.[1]) {
-				ctx.ui.setEditorText(`/sub:peek ${compactPeekMatch[1]}`);
-				return undefined; // let Enter proceed with rewritten text
-			}
+	unsubTerminalInput = ctx.ui.onTerminalInput((data: string) => {
+		// Only intercept Enter key (all terminal variants).
+		if (!matchesKey(data, "enter")) return undefined;
 
-			return undefined;
-		});
-	}
+		const editorText = (ctx.ui.getEditorText() ?? "").trim();
 
-	// ── Persona injection for sub-trans child sessions ──────────────────
-	// When the user switches into a subagent session via <> / /sub:trans
-	// and sends normal chat prompts, prepend the subagent's system prompt
-	// so the main agent responds with that persona.
-	const PERSONA_MARKER = "<!-- subagent-persona-injected -->";
-
-	pi.on("before_agent_start", async (event, ctx) => {
-		// Skip if persona marker already present (avoid double-inject)
-		if (event.systemPrompt.includes(PERSONA_MARKER)) return;
-
-		// Find latest PARENT_ENTRY_TYPE entry to determine if this is a sub-trans child session
-		let latestEntry: any = null;
-		try {
-			const entries = ctx.sessionManager?.getEntries?.() ?? [];
-			for (const entry of entries) {
-				if ((entry as any).type === "custom" && (entry as any).customType === PARENT_ENTRY_TYPE) {
-					latestEntry = entry;
-				}
-			}
-		} catch {
-			return;
+		// <>7  →  /sub:peek 7
+		const compactPeekMatch = /^<>(\d+)$/.exec(editorText);
+		if (compactPeekMatch?.[1]) {
+			ctx.ui.setEditorText(`/sub:peek ${compactPeekMatch[1]}`);
+			return undefined; // let Enter proceed with rewritten text
 		}
 
-		if (!latestEntry?.data) return;
+		return undefined;
+	});
+}
+
+// ── Persona injection for sub-trans child sessions ──────────────────
+// When the user switches into a subagent session via <> / /sub:trans
+// and sends normal chat prompts, prepend the subagent's system prompt
+// so the main agent responds with that persona.
+const PERSONA_MARKER = "<!-- subagent-persona-injected -->";
+
+/** before_agent_start handler; index.ts registers the wrapper that awaits the lazy core. */
+export async function handleBeforeAgentStart(
+	event: { systemPrompt: string },
+	ctx: ExtensionContext,
+	store: SubagentStore,
+): Promise<{ systemPrompt: string } | undefined> {
+	// Skip if persona marker already present (avoid double-inject)
+	if (event.systemPrompt.includes(PERSONA_MARKER)) return;
 
-		// Resolve agent name: data.agent (new entries) or fallback via runId (legacy entries)
-		let agentName: string | undefined = latestEntry.data.agent;
-		if (!agentName && latestEntry.data.runId != null) {
-			agentName = store.commandRuns.get(latestEntry.data.runId)?.agent;
+	// Find latest PARENT_ENTRY_TYPE entry to determine if this is a sub-trans child session
+	let latestEntry: any = null;
+	try {
+		const entries = ctx.sessionManager?.getEntries?.() ?? [];
+		for (const entry of entries) {
+			if ((entry as any).type === "custom" && (entry as any).customType === PARENT_ENTRY_TYPE) {
+				latestEntry = entry;
+			}
 		}
-		if (!agentName) return;
+	} catch {
+		return;
+	}
 
-		// Discover agents and find exact match
-		const discovery = discoverAgents(ctx.cwd);
-		const agentConfig = discovery.agents.find((a) => a.name.toLowerCase() === agentName?.toLowerCase());
-		if (!agentConfig?.systemPrompt?.trim()) return;
+	if (!latestEntry?.data) return;
 
-		// Prepend persona block with marker
-		const personaBlock = `${PERSONA_MARKER}\n${agentConfig.systemPrompt}`;
-		return {
-			systemPrompt: `${personaBlock}\n\n${event.systemPrompt}`,
-		};
-	});
+	// Resolve agent name: data.agent (new entries) or fallback via runId (legacy entries)
+	let agentName: string | undefined = latestEntry.data.agent;
+	if (!agentName && latestEntry.data.runId != null) {
+		agentName = store.commandRuns.get(latestEntry.data.runId)?.agent;
+	}
+	if (!agentName) return;
 
-	pi.on("session_start", async (_event, ctx) => {
-		restoreRunsFromSession(store, ctx, pi);
-		registerTerminalInputRedirect(ctx);
-	});
+	// Discover agents and find exact match
+	const discovery = discoverAgents(ctx.cwd);
+	const agentConfig = discovery.agents.find((a) => a.name.toLowerCase() === agentName?.toLowerCase());
+	if (!agentConfig?.systemPrompt?.trim()) return;
 
-	pi.on("session_shutdown", () => {
-		unsubTerminalInput?.();
-		unsubTerminalInput = null;
-	});
+	// Prepend persona block with marker
+	const personaBlock = `${PERSONA_MARKER}\n${agentConfig.systemPrompt}`;
+	return {
+		systemPrompt: `${personaBlock}\n\n${event.systemPrompt}`,
+	};
+}
+
+/** session_start handler; index.ts invokes this once the lazy core is loaded. */
+export function handleSessionStart(pi: ExtensionAPI, store: SubagentStore, ctx: ExtensionContext): void {
+	restoreRunsFromSession(store, ctx, pi);
+	registerTerminalInputRedirect(ctx);
+}
+
+/** session_shutdown handler; index.ts invokes this after shutting down runs. */
+export function handleSessionShutdown(): void {
+	unsubTerminalInput?.();
+	unsubTerminalInput = null;
 }

package/escalation.ts

@@ -49,70 +49,71 @@ export function writeEscalationRecord(sessionFile: string, message: string, cont
  *   - Reads + deletes the escalation file (IPC)
  *   - Surfaces the message to the master
  */
-export function registerAskMasterTool(pi: ExtensionAPI): void {
-	pi.on("session_start", (_event, ctx) => {
-		const sessionFile = ctx.sessionManager.getSessionFile();
-		if (!isSubagentSession(sessionFile)) return;
+export function maybeRegisterAskMaster(
+	pi: ExtensionAPI,
+	ctx: { sessionManager: { getSessionFile(): string | undefined } },
+): void {
+	const sessionFile = ctx.sessionManager.getSessionFile();
+	if (!isSubagentSession(sessionFile)) return;
 
-		pi.registerTool({
-			name: "ask_master",
-			label: "Ask Master",
-			description: [
-				"Calling this tool terminates the process immediately. No further work can be performed afterward.",
-				"Sends a message to the master and terminates the current process.",
-				"The master will review the message and respond appropriately.",
-				"",
-				"Use when:",
-				"- A decision about how to proceed is required",
-				"- Confirmation is needed before a risky operation such as deletion, deployment, or migration",
-				"- An unexpected situation requires the master’s judgment",
-			].join("\n"),
-			promptSnippet: "Ask the master for a decision. WARNING: calling this tool terminates your session immediately.",
-			promptGuidelines: [
-				"ask_master terminates your process — only call when you truly cannot proceed without the master's decision.",
-				"Exhaust available tools and context first before resorting to ask_master.",
-				"When calling, always include actionable options and your recommendation in the message.",
-			],
-			parameters: Type.Object({
-				message: Type.String({
-					description:
-						"Message for the master. Explain why a decision is needed, what must be decided, the available options, and your recommendation.",
-				}),
-				context: Type.Optional(
-					Type.String({
-						description: "Additional context, such as current progress, discovered issues, and options",
-					}),
-				),
+	pi.registerTool({
+		name: "ask_master",
+		label: "Ask Master",
+		description: [
+			"Calling this tool terminates the process immediately. No further work can be performed afterward.",
+			"Sends a message to the master and terminates the current process.",
+			"The master will review the message and respond appropriately.",
+			"",
+			"Use when:",
+			"- A decision about how to proceed is required",
+			"- Confirmation is needed before a risky operation such as deletion, deployment, or migration",
+			"- An unexpected situation requires the master’s judgment",
+		].join("\n"),
+		promptSnippet: "Ask the master for a decision. WARNING: calling this tool terminates your session immediately.",
+		promptGuidelines: [
+			"ask_master terminates your process — only call when you truly cannot proceed without the master's decision.",
+			"Exhaust available tools and context first before resorting to ask_master.",
+			"When calling, always include actionable options and your recommendation in the message.",
+		],
+		parameters: Type.Object({
+			message: Type.String({
+				description:
+					"Message for the master. Explain why a decision is needed, what must be decided, the available options, and your recommendation.",
 			}),
-			execute: async (_toolCallId, rawParams) => {
-				const params = rawParams as { message: string; context?: string };
-				const activeSessionFile = sessionFile;
-				if (!activeSessionFile) {
-					return {
-						content: [
-							{
-								type: "text" as const,
-								text: "[ask_master] Error: Missing subagent session file. Escalation not written.",
-							},
-						],
-						details: { message: params.message, context: params.context, error: true },
-						terminate: true,
-					};
-				}
-
-				try {
-					writeEscalationRecord(activeSessionFile, params.message, params.context);
-				} catch (err) {
-					process.stderr.write(`[ask_master] Failed to write escalation file: ${err}\n`);
-				}
-
+			context: Type.Optional(
+				Type.String({
+					description: "Additional context, such as current progress, discovered issues, and options",
+				}),
+			),
+		}),
+		execute: async (_toolCallId, rawParams) => {
+			const params = rawParams as { message: string; context?: string };
+			const activeSessionFile = sessionFile;
+			if (!activeSessionFile) {
 				return {
-					content: [{ type: "text" as const, text: `Escalated to master: ${params.message}` }],
-					details: { message: params.message, context: params.context, error: false },
+					content: [
+						{
+							type: "text" as const,
+							text: "[ask_master] Error: Missing subagent session file. Escalation not written.",
+						},
+					],
+					details: { message: params.message, context: params.context, error: true },
 					terminate: true,
 				};
-			},
-		});
+			}
+
+			try {
+				writeEscalationRecord(activeSessionFile, params.message, params.context);
+			} catch (err) {
+				process.stderr.write(`[ask_master] Failed to write escalation file: ${err}\n`);
+			}
+
+			return {
+				content: [{ type: "text" as const, text: `Escalated to master: ${params.message}` }],
+				details: { message: params.message, context: params.context, error: false },
+				terminate: true,
+			};
+		},
 	});
 }
 

package/index.ts

@@ -9,183 +9,124 @@
  * Uses JSON mode to capture structured output from subagents.
  *
  * Architecture:
- *   types.ts    — Type definitions, interfaces, Typebox schemas
- *   store.ts    — Shared state (SubagentStore) and state-mutation helpers
- *   format.ts   — Token/usage/tool-call formatting utilities
- *   session.ts  — Session file management and context helpers
- *   runner.ts   — Subagent process execution, agent matching, concurrency
- *   replay.ts   — Session replay viewer (TUI overlay)
- *   widget.ts   — Run status widget (above-editor display)
- *   commands.ts — Tool handler, slash-commands, event handlers
- *   index.ts    — Orchestrator (this file)
- */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { cleanupPixelTimer } from "./above-widget.js";
-import { registerAll } from "./commands.js";
-import { HANG_CHECK_INTERVAL_MS, HANG_TIMEOUT_MS } from "./constants.js";
-import { registerAskMasterTool } from "./escalation.js";
-import { getSessionFileMtimeMs, readPersistedSessionSnapshot } from "./persisted-session.js";
-import { getLastNonEmptyLine } from "./runner.js";
-import { createStore, type SubagentStore } from "./store.js";
-import type { CommandRunState } from "./types.js";
-import { cleanupCommandRunsWidgetTimer, updateCommandRunsWidget } from "./widget.js";
-
-function reconcileRunWithPersistedSession(run: CommandRunState): void {
-	if (!run.sessionFile) return;
-
-	const mtimeMs = getSessionFileMtimeMs(run.sessionFile);
-	if (mtimeMs && mtimeMs > run.lastActivityAt) {
-		run.lastActivityAt = mtimeMs;
-	}
-
-	const snapshot = readPersistedSessionSnapshot(run.sessionFile, {
-		startOffset: run.persistedSessionBaseOffset,
-	});
-	if (snapshot.latestActivityAt && snapshot.latestActivityAt > run.lastActivityAt) {
-		run.lastActivityAt = snapshot.latestActivityAt;
-	}
-	if (!snapshot.isTerminal) return;
-
-	const exitCode =
-		snapshot.completionMarker?.exitCode ??
-		(snapshot.terminalStopReason === "error" || snapshot.terminalStopReason === "aborted" ? 1 : 0);
-	run.status = exitCode === 0 ? "done" : "error";
-	if (snapshot.finalOutput) {
-		run.lastOutput = snapshot.finalOutput;
-		run.lastLine = getLastNonEmptyLine(snapshot.finalOutput) || run.lastLine;
-	}
-	if (snapshot.latestActivityAt) {
-		run.elapsedMs = Math.max(run.elapsedMs, snapshot.latestActivityAt - run.startedAt);
-	}
-}
-
-/**
- * Abort all session-scoped child processes before Pi invalidates this
- * extension runtime. A non-triggering failure entry is persisted so returning
- * to the old session explains why the run stopped.
+ *   types.ts     — Type definitions, interfaces, Typebox schemas
+ *   store.ts     — Shared state (SubagentStore) and state-mutation helpers
+ *   format.ts    — Token/usage/tool-call formatting utilities
+ *   session.ts   — Session file management and context helpers
+ *   runner.ts    — Subagent process execution, agent matching, concurrency
+ *   replay.ts    — Session replay viewer (TUI overlay)
+ *   widget.ts    — Run status widget (above-editor display)
+ *   commands.ts  — Tool handler, slash-commands, event handlers
+ *   lifecycle.ts — Hang detection sweeps and shutdown cleanup
+ *   index.ts     — Thin boot orchestrator (this file)
+ *
+ * Boot strategy: this entrypoint imports only constants and registers thin
+ * event wrappers, then loads the heavy module graph lazily in the background.
+ * before_agent_start awaits the lazy core so tools (subagent, list-agents,
+ * ask_master) are always registered before the first agent turn — including
+ * headless (`pi -p`) runs.
  */
-type SessionShutdownReason = "quit" | "reload" | "new" | "resume" | "fork";
 
-export function shutdownSubagentRuns(store: SubagentStore, pi: ExtensionAPI, reason: SessionShutdownReason): void {
-	if (store.disposed) return;
-	store.disposed = true;
-
-	const activeRuns = new Map<number, CommandRunState>();
-	for (const [runId, run] of store.commandRuns) activeRuns.set(runId, run);
-	for (const [runId, entry] of store.globalLiveRuns) activeRuns.set(runId, entry.runState);
-
-	for (const [runId, run] of activeRuns) {
-		if (run.status !== "running") continue;
-		const message = `Aborted because the parent pi session ${reason} is shutting down.`;
-		run.status = "error";
-		run.elapsedMs = Date.now() - run.startedAt;
-		run.lastActivityAt = Date.now();
-		run.lastLine = message;
-		run.lastOutput = message;
-		run.removed = true;
-
-		const controller = run.abortController ?? store.globalLiveRuns.get(runId)?.abortController;
-		controller?.abort();
-		run.abortController = undefined;
-
-		if (run.deliveryMode === "humanOnly") continue;
-		try {
-			pi.sendMessage(
-				{
-					customType: run.source === "tool" ? "subagent-tool" : "subagent-command",
-					content: `[subagent:${run.agent}#${runId}] failed\n\n${message}`,
-					display: false,
-					details: {
-						runId,
-						agent: run.agent,
-						task: run.task,
-						displayTask: run.displayTask,
-						status: "error",
-						error: message,
-						startedAt: run.startedAt,
-						elapsedMs: run.elapsedMs,
-						lastActivityAt: run.lastActivityAt,
-						sessionFile: run.sessionFile,
-					},
-				},
-				{ deliverAs: "followUp", triggerTurn: false },
-			);
-		} catch {
-			// The runtime may already be closing; aborting the child remains the priority.
-		}
-	}
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { HANG_CHECK_INTERVAL_MS } from "./constants.js";
+import { SUBAGENT_COMMANDS, SUBAGENT_SHORTCUTS, type SubagentCommandName } from "./registration-manifest.js";
 
-	store.globalLiveRuns.clear();
-	store.batchGroups.clear();
-	store.pipelines.clear();
-	store.recentLaunchTimestamps.clear();
-	store.commandRuns.clear();
-	store.commandWidgetCtx = null;
-	store.pixelWidgetCtx = null;
-	cleanupCommandRunsWidgetTimer();
+interface SubagentCore {
+	store: import("./store.js").SubagentStore;
+	commands: typeof import("./commands.js");
+	registrations: import("./commands.js").SubagentRegistrations;
+	escalation: typeof import("./escalation.js");
+	lifecycle: typeof import("./lifecycle.js");
 }
 
-/**
- * Sweep active runs for inactivity. The normal run finalizer owns completion
- * delivery so an auto-abort cannot emit two follow-up messages.
- */
-export function checkForHungRuns(store: SubagentStore, _pi: ExtensionAPI): void {
-	if (store.disposed) return;
-	const now = Date.now();
-	const processed = new Set<number>();
-
-	function tryAbort(runId: number, run: CommandRunState): void {
-		reconcileRunWithPersistedSession(run);
-		// Skip if already completed/aborted or not running
-		if (run.status !== "running") return;
-		if (!run.lastActivityAt) return;
-		// Guard: skip runs already auto-aborted (prevents duplicate abort/followUp)
-		if (run.lastLine?.startsWith("Auto-aborted:")) return;
-
-		const idleMs = now - run.lastActivityAt;
-		if (idleMs < HANG_TIMEOUT_MS) return;
-
-		// Try to abort via run's own controller, then globalLiveRuns fallback
-		const globalEntry = store.globalLiveRuns.get(runId);
-		const controller = run.abortController ?? globalEntry?.abortController;
-
-		const reason = `Auto-aborted: no activity for ${Math.round(idleMs / 1000)}s`;
-		run.lastLine = reason;
-		run.lastOutput = reason;
-		run.status = "error";
-		run.autoAbortReason = reason;
-
-		if (controller) {
-			controller.abort();
-		}
-	}
-
-	// Sweep commandRuns first
-	for (const [runId, run] of store.commandRuns) {
-		processed.add(runId);
-		tryAbort(runId, run);
+export default function (pi: ExtensionAPI) {
+	let core: SubagentCore | null = null;
+	let corePromise: Promise<SubagentCore> | null = null;
+	/** Serializes session lifecycle work so events apply in dispatch order. */
+	let chain: Promise<void> = Promise.resolve();
+
+	const loadCore = (): Promise<SubagentCore> => {
+		corePromise ??= (async () => {
+			const [commands, escalation, lifecycle, storeMod] = await Promise.all([
+				import("./commands.js"),
+				import("./escalation.js"),
+				import("./lifecycle.js"),
+				import("./store.js"),
+			]);
+			const store = storeMod.createStore();
+			const registrations = commands.registerAll(pi, store);
+			core = { store, commands, registrations, escalation, lifecycle };
+			return core;
+		})().catch((error) => {
+			corePromise = null;
+			throw error;
+		});
+		return corePromise;
+	};
+
+	const enqueue = (fn: (core: SubagentCore) => void): Promise<void> => {
+		chain = chain
+			.then(() => loadCore())
+			.then(fn)
+			.catch((err) => {
+				process.stderr.write(`[subagent] deferred init failed: ${err instanceof Error ? err.message : err}\n`);
+			});
+		return chain;
+	};
+
+	const getCommandDefinition = async (name: SubagentCommandName) => {
+		const loaded = await loadCore();
+		await chain;
+		const definition = loaded.registrations.commands.get(name);
+		if (!definition) throw new Error(`Subagent command definition not found: ${name}`);
+		return definition;
+	};
+
+	// Register lightweight proxies synchronously so Pi's initial autocomplete
+	// and command registry contain every subagent command before lazy core load.
+	for (const [name, description] of Object.entries(SUBAGENT_COMMANDS) as Array<[SubagentCommandName, string]>) {
+		pi.registerCommand(name, {
+			description,
+			getArgumentCompletions: async (prefix) => {
+				const definition = await getCommandDefinition(name);
+				return definition.getArgumentCompletions?.(prefix) ?? null;
+			},
+			handler: async (args, ctx) => {
+				const definition = await getCommandDefinition(name);
+				return definition.handler(args, ctx);
+			},
+		});
 	}
 
-	// Sweep registry-only runs that are not present in the current widget view.
-	for (const [runId, entry] of store.globalLiveRuns) {
-		if (processed.has(runId)) continue;
-		tryAbort(runId, entry.runState);
+	// These entries document text-prefix shortcuts in /hotkeys. Actual routing
+	// remains in commands.ts input handlers after the lazy core is loaded.
+	for (const [shortcut, description] of Object.entries(SUBAGENT_SHORTCUTS)) {
+		pi.registerShortcut(shortcut as never, {
+			description,
+			handler: async () => {},
+		});
 	}
 
-	updateCommandRunsWidget(store);
-}
-
-export default function (pi: ExtensionAPI) {
-	const store = createStore();
-	registerAskMasterTool(pi);
-	registerAll(pi, store);
+	// Start loading in the background without blocking extension boot.
+	// setTimeout keeps the load out of the boot path's microtask drains.
+	setTimeout(() => {
+		void loadCore().catch(() => {
+			// Reported when the first enqueue/await surfaces the failure.
+		});
+	}, 0);
 
 	let hangCheckTimer: ReturnType<typeof setInterval> | undefined;
-	pi.on("session_start", () => {
-		store.disposed = false;
+
+	pi.on("session_start", (_event, ctx) => {
+		enqueue((c) => {
+			c.store.disposed = false;
+			c.commands.handleSessionStart(pi, c.store, ctx as unknown as ExtensionContext);
+			c.escalation.maybeRegisterAskMaster(pi, ctx);
+		});
 		if (!hangCheckTimer) {
-			hangCheckTimer = setInterval(() => checkForHungRuns(store, pi), HANG_CHECK_INTERVAL_MS);
+			hangCheckTimer = setInterval(() => {
+				if (core) core.lifecycle.checkForHungRuns(core.store, pi);
+			}, HANG_CHECK_INTERVAL_MS);
 		}
 	});
 
@@ -194,7 +135,25 @@ export default function (pi: ExtensionAPI) {
 			clearInterval(hangCheckTimer);
 			hangCheckTimer = undefined;
 		}
-		shutdownSubagentRuns(store, pi, event.reason);
-		cleanupPixelTimer();
+		// Wait for any queued session_start work so its loadCore() is visible here.
+		await chain;
+		if (!corePromise) return;
+		const c = await loadCore();
+		c.lifecycle.shutdownSubagentRuns(c.store, pi, event.reason);
+		c.commands.handleSessionShutdown();
+		c.lifecycle.cleanupPixelTimer();
+	});
+
+	pi.on("before_agent_start", async (event, ctx) => {
+		const c = await loadCore();
+		await chain;
+		return c.commands.handleBeforeAgentStart(event, ctx, c.store);
+	});
+
+	// If input arrives while the core is still loading, awaiting here lets the
+	// live handler-array dispatch reach the shortcut handlers registerAll adds.
+	pi.on("input", async () => {
+		if (!core) await loadCore().catch(() => {});
+		return { action: "continue" as const };
 	});
 }

package/lifecycle.ts

@@ -0,0 +1,161 @@
+/**
+ * Session lifecycle helpers: hang detection sweeps and shutdown cleanup.
+ *
+ * Kept out of index.ts so the boot entrypoint stays import-light; index.ts
+ * loads this module lazily.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { HANG_TIMEOUT_MS } from "./constants.js";
+import { getSessionFileMtimeMs, readPersistedSessionSnapshot } from "./persisted-session.js";
+import { getLastNonEmptyLine } from "./runner.js";
+import type { SubagentStore } from "./store.js";
+import type { CommandRunState } from "./types.js";
+import { cleanupCommandRunsWidgetTimer, updateCommandRunsWidget } from "./widget.js";
+
+export { cleanupPixelTimer } from "./above-widget.js";
+
+function reconcileRunWithPersistedSession(run: CommandRunState): void {
+	if (!run.sessionFile) return;
+
+	const mtimeMs = getSessionFileMtimeMs(run.sessionFile);
+	if (mtimeMs && mtimeMs > run.lastActivityAt) {
+		run.lastActivityAt = mtimeMs;
+	}
+
+	const snapshot = readPersistedSessionSnapshot(run.sessionFile, {
+		startOffset: run.persistedSessionBaseOffset,
+	});
+	if (snapshot.latestActivityAt && snapshot.latestActivityAt > run.lastActivityAt) {
+		run.lastActivityAt = snapshot.latestActivityAt;
+	}
+	if (!snapshot.isTerminal) return;
+
+	const exitCode =
+		snapshot.completionMarker?.exitCode ??
+		(snapshot.terminalStopReason === "error" || snapshot.terminalStopReason === "aborted" ? 1 : 0);
+	run.status = exitCode === 0 ? "done" : "error";
+	if (snapshot.finalOutput) {
+		run.lastOutput = snapshot.finalOutput;
+		run.lastLine = getLastNonEmptyLine(snapshot.finalOutput) || run.lastLine;
+	}
+	if (snapshot.latestActivityAt) {
+		run.elapsedMs = Math.max(run.elapsedMs, snapshot.latestActivityAt - run.startedAt);
+	}
+}
+
+/**
+ * Abort all session-scoped child processes before Pi invalidates this
+ * extension runtime. A non-triggering failure entry is persisted so returning
+ * to the old session explains why the run stopped.
+ */
+export type SessionShutdownReason = "quit" | "reload" | "new" | "resume" | "fork";
+
+export function shutdownSubagentRuns(store: SubagentStore, pi: ExtensionAPI, reason: SessionShutdownReason): void {
+	if (store.disposed) return;
+	store.disposed = true;
+
+	const activeRuns = new Map<number, CommandRunState>();
+	for (const [runId, run] of store.commandRuns) activeRuns.set(runId, run);
+	for (const [runId, entry] of store.globalLiveRuns) activeRuns.set(runId, entry.runState);
+
+	for (const [runId, run] of activeRuns) {
+		if (run.status !== "running") continue;
+		const message = `Aborted because the parent pi session ${reason} is shutting down.`;
+		run.status = "error";
+		run.elapsedMs = Date.now() - run.startedAt;
+		run.lastActivityAt = Date.now();
+		run.lastLine = message;
+		run.lastOutput = message;
+		run.removed = true;
+
+		const controller = run.abortController ?? store.globalLiveRuns.get(runId)?.abortController;
+		controller?.abort();
+		run.abortController = undefined;
+
+		if (run.deliveryMode === "humanOnly") continue;
+		try {
+			pi.sendMessage(
+				{
+					customType: run.source === "tool" ? "subagent-tool" : "subagent-command",
+					content: `[subagent:${run.agent}#${runId}] failed\n\n${message}`,
+					display: false,
+					details: {
+						runId,
+						agent: run.agent,
+						task: run.task,
+						displayTask: run.displayTask,
+						status: "error",
+						error: message,
+						startedAt: run.startedAt,
+						elapsedMs: run.elapsedMs,
+						lastActivityAt: run.lastActivityAt,
+						sessionFile: run.sessionFile,
+					},
+				},
+				{ deliverAs: "followUp", triggerTurn: false },
+			);
+		} catch {
+			// The runtime may already be closing; aborting the child remains the priority.
+		}
+	}
+
+	store.globalLiveRuns.clear();
+	store.batchGroups.clear();
+	store.pipelines.clear();
+	store.recentLaunchTimestamps.clear();
+	store.commandRuns.clear();
+	store.commandWidgetCtx = null;
+	store.pixelWidgetCtx = null;
+	cleanupCommandRunsWidgetTimer();
+}
+
+/**
+ * Sweep active runs for inactivity. The normal run finalizer owns completion
+ * delivery so an auto-abort cannot emit two follow-up messages.
+ */
+export function checkForHungRuns(store: SubagentStore, _pi: ExtensionAPI): void {
+	if (store.disposed) return;
+	const now = Date.now();
+	const processed = new Set<number>();
+
+	function tryAbort(runId: number, run: CommandRunState): void {
+		reconcileRunWithPersistedSession(run);
+		// Skip if already completed/aborted or not running
+		if (run.status !== "running") return;
+		if (!run.lastActivityAt) return;
+		// Guard: skip runs already auto-aborted (prevents duplicate abort/followUp)
+		if (run.lastLine?.startsWith("Auto-aborted:")) return;
+
+		const idleMs = now - run.lastActivityAt;
+		if (idleMs < HANG_TIMEOUT_MS) return;
+
+		// Try to abort via run's own controller, then globalLiveRuns fallback
+		const globalEntry = store.globalLiveRuns.get(runId);
+		const controller = run.abortController ?? globalEntry?.abortController;
+
+		const reason = `Auto-aborted: no activity for ${Math.round(idleMs / 1000)}s`;
+		run.lastLine = reason;
+		run.lastOutput = reason;
+		run.status = "error";
+		run.autoAbortReason = reason;
+
+		if (controller) {
+			controller.abort();
+		}
+	}
+
+	// Sweep commandRuns first
+	for (const [runId, run] of store.commandRuns) {
+		processed.add(runId);
+		tryAbort(runId, run);
+	}
+
+	// Sweep registry-only runs that are not present in the current widget view.
+	for (const [runId, entry] of store.globalLiveRuns) {
+		if (processed.has(runId)) continue;
+		tryAbort(runId, entry.runState);
+	}
+
+	updateCommandRunsWidget(store);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryan_nookpi/pi-extension-subagent",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
   "license": "MIT",
   "repository": {
@@ -36,10 +36,12 @@
     "format.ts",
     "group-pending.ts",
     "index.ts",
+    "lifecycle.ts",
     "invocation-queue.ts",
     "live-preview.ts",
     "persisted-session.ts",
     "replay.ts",
+    "registration-manifest.ts",
     "retry.ts",
     "run-utils.ts",
     "runner.ts",

package/registration-manifest.ts

@@ -0,0 +1,23 @@
+export const SUBAGENT_COMMANDS = {
+	"sub:isolate":
+		"Run a subagent in a dedicated sub-session: /sub:isolate <agent|alias> <task>, /sub:isolate <runId> <task>, /sub:isolate <task> (uses configured defaultAgent)",
+	"sub:main": "Run a subagent with main-session context inheritance: /sub:main <agent|alias> <task>",
+	subagents: "List available subagents and offer the starter pack when none are configured",
+	"sub:peek": "Show the latest response from a subagent in an overlay: /sub:peek [runId]",
+	"sub:open": "Open a subagent session replay overlay: /sub:open [runId]",
+	"sub:history": "Show all subagent run history (including removed) in an overlay: /sub:history",
+	"sub:rm": "Remove one /sub job entry (aborts it if running): /sub:rm [runId]",
+	"sub:clear": "Clear /sub job widget entries. /sub:clear (finished only) or /sub:clear all",
+	"sub:abort": "Abort running subagent job(s). /sub:abort [runId|all]",
+} as const;
+
+export type SubagentCommandName = keyof typeof SUBAGENT_COMMANDS;
+
+export const SUBAGENT_SHORTCUTS = {
+	">>": "Run subagent task",
+	"#<runId>": "Resume subagent run: #<runId> <task>",
+	"<<": "Abort or clear subagent runs",
+	"<<<": "Clear finished subagent jobs (= /sub:clear). <<< all to clear all",
+} as const;
+
+export type SubagentShortcutName = keyof typeof SUBAGENT_SHORTCUTS;