@ryan_nookpi/pi-extension-subagent 0.2.0 → 0.3.0

package/README.md

@@ -67,7 +67,7 @@ Implement the requested changes and verify them.
 
 - `runtime`: `pi` (default) or `claude`
 - `model`: runtime-compatible model ID
-- `thinking`: `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`
+- `thinking`: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`
 - `tools`: comma-separated tool names
 
 Omitted model, thinking, and tools values use that runtime's defaults.

package/commands.ts

@@ -2226,83 +2226,90 @@ export function registerAll(pi: ExtensionAPI, store: SubagentStore): void {
 		ctx.ui.notify(parts.join(", ") || "Nothing to do.", parts.length ? (aborted ? "warning" : "info") : "info");
 		return { action: "handled" as const };
 	});
+}
 
-	// ── onTerminalInput hack: auto-redirect <>7 to /sub:peek 7 ───────────
-	let unsubTerminalInput: (() => void) | null = null;
+// ── onTerminalInput hack: auto-redirect <>7 to /sub:peek 7 ───────────
+let unsubTerminalInput: (() => void) | null = null;
 
-	function registerTerminalInputRedirect(ctx: any): void {
-		// Unsubscribe previous listener to avoid duplicates on session change.
-		unsubTerminalInput?.();
-		unsubTerminalInput = null;
+function registerTerminalInputRedirect(ctx: any): void {
+	// Unsubscribe previous listener to avoid duplicates on session change.
+	unsubTerminalInput?.();
+	unsubTerminalInput = null;
 
-		unsubTerminalInput = ctx.ui.onTerminalInput((data: string) => {
-			// Only intercept Enter key (all terminal variants).
-			if (!matchesKey(data, "enter")) return undefined;
+	unsubTerminalInput = ctx.ui.onTerminalInput((data: string) => {
+		// Only intercept Enter key (all terminal variants).
+		if (!matchesKey(data, "enter")) return undefined;
 
-			const editorText = (ctx.ui.getEditorText() ?? "").trim();
+		const editorText = (ctx.ui.getEditorText() ?? "").trim();
 
-			// <>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
-			}
+		// <>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
+		}
 
-			return undefined;
-		});
-	}
+		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 -->";
-
-	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;
-				}
+// ── 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;
+
+	// 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;
 		}
+	} catch {
+		return;
+	}
 
-		if (!latestEntry?.data) return;
+	if (!latestEntry?.data) 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;
-		}
-		if (!agentName) 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;
+	}
+	if (!agentName) 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;
+	// 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;
 
-		// Prepend persona block with marker
-		const personaBlock = `${PERSONA_MARKER}\n${agentConfig.systemPrompt}`;
-		return {
-			systemPrompt: `${personaBlock}\n\n${event.systemPrompt}`,
-		};
-	});
+	// Prepend persona block with marker
+	const personaBlock = `${PERSONA_MARKER}\n${agentConfig.systemPrompt}`;
+	return {
+		systemPrompt: `${personaBlock}\n\n${event.systemPrompt}`,
+	};
+}
 
-	pi.on("session_start", async (_event, ctx) => {
-		restoreRunsFromSession(store, ctx, pi);
-		registerTerminalInputRedirect(ctx);
-	});
+/** 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);
+}
 
-	pi.on("session_shutdown", () => {
-		unsubTerminalInput?.();
-		unsubTerminalInput = null;
-	});
+/** 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,86 @@
  * 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.
- */
-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.
+ *   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.
  */
-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;
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { HANG_CHECK_INTERVAL_MS } from "./constants.js";
 
-		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);
+interface SubagentCore {
+	store: import("./store.js").SubagentStore;
+	commands: typeof import("./commands.js");
+	escalation: typeof import("./escalation.js");
+	lifecycle: typeof import("./lifecycle.js");
 }
 
 export default function (pi: ExtensionAPI) {
-	const store = createStore();
-	registerAskMasterTool(pi);
-	registerAll(pi, store);
+	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();
+			commands.registerAll(pi, store);
+			core = { store, commands, escalation, lifecycle };
+			return core;
+		})();
+		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;
+	};
+
+	// 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 +97,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,97 +1,98 @@
 {
-  "name": "@ryan_nookpi/pi-extension-subagent",
-  "version": "0.2.0",
-  "description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Jonghakseo/pi-extension.git",
-    "directory": "packages/subagent"
-  },
-  "bugs": {
-    "url": "https://github.com/Jonghakseo/pi-extension/issues"
-  },
-  "homepage": "https://github.com/Jonghakseo/pi-extension/tree/main/packages/subagent#readme",
-  "type": "module",
-  "keywords": [
-    "pi-package",
-    "subagent",
-    "delegation"
-  ],
-  "files": [
-    "above-widget.ts",
-    "agents.ts",
-    "claude-args.ts",
-    "claude-sdk-runner.ts",
-    "claude-sdk-stream-adapter.ts",
-    "claude-sidecar-writer.ts",
-    "claude-stream-parser.ts",
-    "cli.ts",
-    "commands.ts",
-    "config.ts",
-    "constants.ts",
-    "context-limits.ts",
-    "display-task.ts",
-    "escalation.ts",
-    "format.ts",
-    "group-pending.ts",
-    "index.ts",
-    "invocation-queue.ts",
-    "live-preview.ts",
-    "persisted-session.ts",
-    "replay.ts",
-    "retry.ts",
-    "run-utils.ts",
-    "runner.ts",
-    "session.ts",
-    "starter-pack.ts",
-    "store.ts",
-    "tool-execute.ts",
-    "tool-render.ts",
-    "types.ts",
-    "widget.ts",
-    "utils/agent-utils.ts",
-    "utils/short-label.ts",
-    "utils/string-utils.ts",
-    "utils/format-utils.ts",
-    "utils/time-utils.ts",
-    "seeds",
-    "README.md"
-  ],
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.98",
-    "yaml": "^2.9.0"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "typebox": "*"
-  },
-  "peerDependenciesMeta": {
-    "@earendil-works/pi-ai": {
-      "optional": true
-    },
-    "@earendil-works/pi-agent-core": {
-      "optional": true
-    },
-    "@earendil-works/pi-coding-agent": {
-      "optional": true
-    },
-    "@earendil-works/pi-tui": {
-      "optional": true
-    },
-    "typebox": {
-      "optional": true
-    }
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+	"name": "@ryan_nookpi/pi-extension-subagent",
+	"version": "0.3.0",
+	"description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Jonghakseo/pi-extension.git",
+		"directory": "packages/subagent"
+	},
+	"bugs": {
+		"url": "https://github.com/Jonghakseo/pi-extension/issues"
+	},
+	"homepage": "https://github.com/Jonghakseo/pi-extension/tree/main/packages/subagent#readme",
+	"type": "module",
+	"keywords": [
+		"pi-package",
+		"subagent",
+		"delegation"
+	],
+	"files": [
+		"above-widget.ts",
+		"agents.ts",
+		"claude-args.ts",
+		"claude-sdk-runner.ts",
+		"claude-sdk-stream-adapter.ts",
+		"claude-sidecar-writer.ts",
+		"claude-stream-parser.ts",
+		"cli.ts",
+		"commands.ts",
+		"config.ts",
+		"constants.ts",
+		"context-limits.ts",
+		"display-task.ts",
+		"escalation.ts",
+		"format.ts",
+		"group-pending.ts",
+		"index.ts",
+		"lifecycle.ts",
+		"invocation-queue.ts",
+		"live-preview.ts",
+		"persisted-session.ts",
+		"replay.ts",
+		"retry.ts",
+		"run-utils.ts",
+		"runner.ts",
+		"session.ts",
+		"starter-pack.ts",
+		"store.ts",
+		"tool-execute.ts",
+		"tool-render.ts",
+		"types.ts",
+		"widget.ts",
+		"utils/agent-utils.ts",
+		"utils/short-label.ts",
+		"utils/string-utils.ts",
+		"utils/format-utils.ts",
+		"utils/time-utils.ts",
+		"seeds",
+		"README.md"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"dependencies": {
+		"@anthropic-ai/claude-agent-sdk": "^0.2.98",
+		"yaml": "^2.9.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-agent-core": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"peerDependenciesMeta": {
+		"@earendil-works/pi-ai": {
+			"optional": true
+		},
+		"@earendil-works/pi-agent-core": {
+			"optional": true
+		},
+		"@earendil-works/pi-coding-agent": {
+			"optional": true
+		},
+		"@earendil-works/pi-tui": {
+			"optional": true
+		},
+		"typebox": {
+			"optional": true
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/utils/agent-utils.ts

@@ -20,7 +20,7 @@ export interface AgentAliasMatch<T extends AgentConfigLike = AgentConfigLike> {
 	ambiguousAgents: T[];
 }
 
-export const AGENT_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+export const AGENT_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 export type AgentThinkingLevel = (typeof AGENT_THINKING_LEVELS)[number];
 
 // ── Constants ────────────────────────────────────────────────────────────────