@bacnh85/pi-subagent 0.3.1 → 0.4.1

package/README.md

@@ -11,6 +11,7 @@ Minimal-overhead sub-agent extension for pi. Delegate tasks to specialized agent
 - **Abort support**: Esc propagates to all sub-agents
 - **TUI rendering**: Collapsed/expanded views with tool-call formatting and usage stats
 - **Bundled agents**: scout, reviewer, worker — overridable with your own
+- **Thread viewing**: `/agent` slash command to view subagent threads in isolation
 
 ## Install
 
@@ -29,6 +30,17 @@ pi -e ./extensions/pi-subagent
 
 ## Usage
 
+### Thread Viewing (`/agent`)
+
+After running subagents, type `/agent` to view individual subagent threads:
+
+1. A picker shows `Main [default]` + all subagent threads with status icons
+2. Select a thread to view its full output (task, tool calls, final result, usage stats)
+3. Within the viewer: `Esc` to close, `Alt+←`/`Alt+→` to cycle between threads, `↑/↓` to scroll
+
+This is useful when running many parallel subagents — instead of Ctrl+O to
+see all output at once, you can focus on one thread at a time.
+
 ### Single agent
 
 ```

package/agents.ts

@@ -32,6 +32,7 @@ interface AgentCache {
 	userDir: string;
 	projectDir: string | null;
 	bundledDir: string;
+	scope: AgentScope;
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
 	/** File-level signature per directory (name:mtime:size for each .md file) */
@@ -69,20 +70,22 @@ function loadAgentsFromDir(dir: string, source: "user" | "project" | "bundled"):
 			continue;
 		}
 
-		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		const { frontmatter, body } = parseFrontmatter<Record<string, unknown>>(content);
 
-		if (!frontmatter.name || !frontmatter.description) continue;
+		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") continue;
 
-		const tools = frontmatter.tools
-			?.split(",")
-			.map((t: string) => t.trim())
-			.filter(Boolean);
+		const tools =
+			typeof frontmatter.tools === "string"
+				? frontmatter.tools.split(",").map((t) => t.trim()).filter(Boolean)
+				: Array.isArray(frontmatter.tools)
+					? (frontmatter.tools as unknown[]).filter((t): t is string => typeof t === "string")
+					: undefined;
 
 		agents.push({
 			name: frontmatter.name,
 			description: frontmatter.description,
 			tools: tools && tools.length > 0 ? tools : undefined,
-			model: frontmatter.model || undefined,
+			model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
 			systemPrompt: body,
 			source,
 			filePath,
@@ -151,7 +154,8 @@ export function discoverAgents(
 		_cache &&
 		_cache.userDir === userDir &&
 		_cache.projectDir === projectAgentsDir &&
-		_cache.bundledDir === bundledAgentsDir
+		_cache.bundledDir === bundledAgentsDir &&
+		_cache.scope === scope
 	) {
 		let stale = false;
 		for (const [dir, cachedSig] of _cache.dirSignatures) {
@@ -195,6 +199,7 @@ export function discoverAgents(
 		userDir,
 		projectDir: projectAgentsDir,
 		bundledDir: bundledAgentsDir,
+		scope,
 		agents,
 		projectAgentsDir,
 		dirSignatures,

package/index.ts

@@ -20,12 +20,13 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import {
 	AuthStorage,
 	CONFIG_DIR_NAME,
+	DynamicBorder,
 	type ExtensionAPI,
 	getAgentDir,
 	getMarkdownTheme,
 	ModelRegistry,
 } from "@earendil-works/pi-coding-agent";
-import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { Container, Markdown, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 import { type AgentConfig, type AgentScope, discoverAgents, formatAgentList, invalidateAgentCache } from "./agents.ts";
@@ -42,6 +43,8 @@ import {
 	formatUsageStats,
 	renderSingleResult,
 } from "./render.ts";
+import { type SubagentThread, threadStore } from "./threads.ts";
+import { ThreadViewer, type ThreadViewerCallbacks } from "./thread-viewer.ts";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -159,9 +162,10 @@ interface SubagentDetails {
 // ---------------------------------------------------------------------------
 
 export default function (pi: ExtensionAPI) {
-	// Invalidate agent cache on reload so edited agent files take effect
+	// Invalidate agent cache + clear thread store on reload
 	pi.on("session_start", (event) => {
 		if (event.reason === "reload") invalidateAgentCache();
+		threadStore.clear();
 	});
 
 	// Proactively steer agents toward sub-agent delegation when users mention it
@@ -372,6 +376,7 @@ export default function (pi: ExtensionAPI) {
 				cwd: string | undefined,
 				parentSignal?: AbortSignal,
 				timeoutMs?: number,
+			onProgress?: (partial: SubAgentResult) => void,
 			): Promise<SubAgentResult> {
 				const agent = agents.find((a) => a.name === agentName);
 
@@ -444,6 +449,7 @@ export default function (pi: ExtensionAPI) {
 					modelRegistry,
 					signal: combinedSignal,
 					agentName,
+					onMessage: onProgress,
 				});
 
 				// Clean up timeout
@@ -469,10 +475,21 @@ export default function (pi: ExtensionAPI) {
 					const step = params.chain[i];
 					const taskWithContext = step.task.replace(/\{previous\}/g, previousOutput);
 
+					const thread = threadStore.createThread({
+						agentName: step.agent,
+						task: taskWithContext,
+						mode: "chain-step",
+						toolCallId: _toolCallId,
+					});
 					const result = await runOne(
 						step.agent, taskWithContext, step.cwd,
 						signal, step.timeout ?? params.timeout,
+						(partial) => threadStore.updateThread(thread.id, { result: partial }),
 					);
+					threadStore.updateThread(thread.id, {
+						status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
+						result,
+					});
 					results.push(result);
 
 					const isError = isFailedResult(result);
@@ -539,13 +556,21 @@ export default function (pi: ExtensionAPI) {
 
 				const abortOnFailure = params.abortOnFailure ?? false;
 				const parallelController = new AbortController();
+				let abortCause: "parent" | "sibling" | undefined;
 
 				// Combine parent signal with parallel abort controller
 				let parallelSignal: AbortSignal = parallelController.signal;
 				if (signal) {
 					// Always link parent abort into parallelController so queued tasks see aborted state
-					if (signal.aborted) parallelController.abort();
-					else signal.addEventListener("abort", () => parallelController.abort(), { once: true });
+					if (signal.aborted) {
+						abortCause = "parent";
+						parallelController.abort();
+					} else {
+						signal.addEventListener("abort", () => {
+							if (!abortCause) abortCause = "parent";
+							parallelController.abort();
+						}, { once: true });
+					}
 					if (typeof (AbortSignal as any).any === "function") {
 						parallelSignal = (AbortSignal as any).any([signal, parallelController.signal]);
 					} else {
@@ -553,6 +578,16 @@ export default function (pi: ExtensionAPI) {
 					}
 				}
 
+				// Pre-create threads for all parallel tasks
+				const parallelThreads = params.tasks.map((t) =>
+					threadStore.createThread({
+						agentName: t.agent,
+						task: t.task,
+						mode: "parallel-task",
+						toolCallId: _toolCallId,
+					}),
+				);
+
 				const allResults: SubAgentResult[] = new Array(params.tasks.length);
 				// Initialize placeholder results for streaming
 				for (let i = 0; i < params.tasks.length; i++) {
@@ -596,21 +631,32 @@ export default function (pi: ExtensionAPI) {
 								stderr: "",
 								usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
 								stopReason: "aborted",
-								errorMessage: parallelController.signal.aborted
-								? "Cancelled: sibling task failed"
-								: "Cancelled: parent operation aborted",
+								errorMessage:
+									abortCause === "sibling"
+									? "Cancelled: sibling task failed"
+									: "Cancelled: parent operation aborted",
 							};
 							allResults[index] = skippedResult;
+							threadStore.updateThread(parallelThreads[index].id, {
+								status: "aborted",
+								result: skippedResult,
+							});
 							emitParallelUpdate();
 							return skippedResult;
 						}
 						const result = await runOne(
 							t.agent, t.task, t.cwd,
 							parallelSignal, t.timeout ?? params.timeout,
+						(partial) => threadStore.updateThread(parallelThreads[index].id, { result: partial }),
 						);
 						allResults[index] = result;
+						threadStore.updateThread(parallelThreads[index].id, {
+							status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
+							result,
+						});
 						// Early-abort: if this task failed and abortOnFailure is set
 						if (abortOnFailure && isFailedResult(result)) {
+							abortCause = "sibling";
 							parallelController.abort();
 						}
 						emitParallelUpdate();
@@ -643,10 +689,21 @@ export default function (pi: ExtensionAPI) {
 
 			// --- Single mode ---
 			if (params.agent && params.task) {
+				const thread = threadStore.createThread({
+					agentName: params.agent,
+					task: params.task,
+					mode: "single",
+					toolCallId: _toolCallId,
+				});
 				const result = await runOne(
 					params.agent, params.task, params.cwd,
 					signal, params.timeout,
+					(partial) => threadStore.updateThread(thread.id, { result: partial }),
 				);
+				threadStore.updateThread(thread.id, {
+					status: isFailedResult(result) ? (result.stopReason === "aborted" ? "aborted" : "failed") : "completed",
+					result,
+				});
 				const isError = isFailedResult(result);
 
 				if (onUpdate) {
@@ -921,4 +978,241 @@ export default function (pi: ExtensionAPI) {
 			return new Text(fallback?.type === "text" ? fallback.text : "(no output)", 0, 0);
 		},
 	});
-}
+	// /agent command — switch between subagent threads.
+	// When a thread is selected, the viewer replaces the main TUI (not overlay).
+	pi.registerCommand("agent", {
+		description: "Switch to a subagent thread to view its work in isolation",
+		handler: async (_args, ctx) => {
+			// Show picker overlay
+			const selectedId = await showAgentPicker(ctx, buildPickerItems(threadStore.getAllThreads()));
+			if (!selectedId) return; // Cancelled — stay in current view
+
+			// Main selected — close viewer if active, return to conversation
+			if (selectedId === "__main__") {
+				if (activeViewerDone) {
+					activeViewerDone();
+					activeViewerDone = null;
+				}
+				return;
+			}
+
+			// Close existing viewer (if any) before opening new one
+			if (activeViewerDone) {
+				activeViewerDone();
+				activeViewerDone = null;
+			}
+
+			// Show thread viewer (re-resolve against current store)
+			const freshThreads = threadStore.getAllThreads();
+			const idx = freshThreads.findIndex((t) => t.id === selectedId);
+			if (idx === -1) {
+				ctx.ui.notify("Selected subagent thread no longer exists.", "warning");
+				return;
+			}
+
+			await showThreadViewer(ctx, freshThreads, idx);
+		},
+	});
+
+	// ---------------------------------------------------------------------------
+	// Module-level viewer state (so /agent can close an active viewer)
+	// ---------------------------------------------------------------------------
+	let activeViewerDone: (() => void) | null = null;
+
+	// ---------------------------------------------------------------------------
+	// Picker helpers (shared between /agent handler and Ctrl+P in viewer)
+	// ---------------------------------------------------------------------------
+
+	interface PickerItem { value: string; label: string; description: string }
+
+	function buildPickerItems(threads: SubagentThread[]): PickerItem[] {
+		const items: PickerItem[] = [
+			{ value: "__main__", label: "Main [default]", description: "(current)" },
+		];
+		for (const t of threads) {
+			let statusIcon: string;
+			switch (t.status) {
+				case "running": statusIcon = "⏳"; break;
+				case "completed": statusIcon = "✓"; break;
+				case "failed": statusIcon = "✗"; break;
+				case "aborted": statusIcon = "✗"; break;
+			}
+			let modeTag = "";
+			if (t.mode === "parallel-task") modeTag = " [parallel]";
+			else if (t.mode === "chain-step") modeTag = " [chain]";
+			const label = `${statusIcon} ${t.agentName}${modeTag}`;
+			const desc = t.task.length > 60 ? `${t.task.slice(0, 57)}...` : t.task;
+			items.push({ value: t.id, label, description: desc });
+		}
+		return items;
+	}
+
+	async function showAgentPicker(
+		ctx: { ui: { custom: <T>(factory: any, opts?: any) => Promise<T> } },
+		items: PickerItem[],
+	): Promise<string | null> {
+		return ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+			const container = new Container();
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+			container.addChild(new Text(theme.fg("accent", theme.bold("Subagents")), 1, 0));
+			container.addChild(new Text(theme.fg("dim", "⌥ + ← previous, ⌥ + → next."), 1, 0));
+
+			const selectList = new SelectList(
+				items.map((it) => ({ value: it.value, label: it.label, description: it.description })),
+				Math.min(items.length + 2, 15),
+				{
+					selectedPrefix: (t: string) => theme.fg("accent", t),
+					selectedText: (t: string) => theme.fg("accent", t),
+					description: (t: string) => theme.fg("muted", t),
+					scrollInfo: (t: string) => theme.fg("dim", t),
+					noMatch: (t: string) => theme.fg("warning", t),
+				},
+			);
+			selectList.onSelect = (item) => done(item.value);
+			selectList.onCancel = () => done(null);
+			container.addChild(selectList);
+
+			container.addChild(new Text(
+				`${theme.fg("dim", "↑↓ navigate · enter select · esc back")}`,
+				1, 0,
+			));
+
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+			return {
+				render: (w: number) => container.render(w),
+				invalidate: () => container.invalidate(),
+				handleInput: (data: string) => { selectList.handleInput(data); tui.requestRender(); },
+			};
+		}, { overlay: true });
+	}
+
+	// Helper: show thread viewer as overlay so editor remains visible.
+	// Uses dynamic thread list + store subscriptions for live progress.
+	// Ctrl+P opens picker overlay to jump to any thread.
+	async function showThreadViewer(
+		ctx: { ui: { custom: <T>(factory: any, opts?: any) => Promise<T> } },
+		_threads: SubagentThread[],
+		startIndex: number,
+	): Promise<void> {
+		let currentIndex = startIndex;
+
+		// Resolve thread list dynamically
+		const getThreads = () => threadStore.getAllThreads();
+
+		// Overlay mode: viewer appears above editor, Esc dismisses
+		await ctx.ui.custom<void>((tui, theme, _kb, done) => {
+			let unsubscribe: (() => void) | undefined;
+			let closed = false;
+
+			const cleanup = () => {
+				if (unsubscribe) {
+					unsubscribe();
+					unsubscribe = undefined;
+				}
+			};
+
+			const close = () => {
+				if (closed) return;
+				closed = true;
+				cleanup();
+				activeViewerDone = null;
+				done();
+			};
+
+			// Track this viewer so /agent can close it before opening a new one
+			activeViewerDone = close;
+
+			function makeCallbacks(): ThreadViewerCallbacks {
+				const list = getThreads();
+				return {
+					onClose: close,
+					onPrev: () => {
+						const current = getThreads();
+						if (currentIndex > 0) {
+							currentIndex--;
+							viewer.setThread(current[currentIndex], makeCallbacks());
+							tui.requestRender();
+						}
+					},
+					onNext: () => {
+						const current = getThreads();
+						if (currentIndex < current.length - 1) {
+							currentIndex++;
+							viewer.setThread(current[currentIndex], makeCallbacks());
+							tui.requestRender();
+						}
+					},
+					hasPrev: currentIndex > 0,
+					hasNext: currentIndex < list.length - 1,
+				};
+			}
+
+			const list = getThreads();
+			if (list.length === 0 || currentIndex < 0 || currentIndex >= list.length) {
+				close();
+				return {
+					render: (_w: number) => [],
+					invalidate: () => {},
+					handleInput: (_data: string) => {},
+					dispose: () => {
+					cleanup();
+					if (activeViewerDone === close) activeViewerDone = null;
+					closed = true;
+				},
+				};
+			}
+
+			const viewer = new ThreadViewer(list[currentIndex], makeCallbacks(), theme);
+			let pickerOpen = false;
+
+			// Subscribe to thread store for live updates (after viewer is created)
+			unsubscribe = threadStore.subscribe(() => {
+				const current = getThreads();
+				if (current.length === 0) {
+					close();
+					return;
+				}
+				currentIndex = Math.min(currentIndex, current.length - 1);
+				viewer.setThread(current[currentIndex], makeCallbacks());
+				tui.requestRender();
+			});
+
+			return {
+				render: (w: number) => viewer.render(w),
+				invalidate: () => viewer.invalidate(),
+				handleInput: (data: string) => {
+					// Ctrl+P opens the picker to jump between threads
+					if (data === "\x10") {
+			if (!pickerOpen) {
+				pickerOpen = true;
+				openThreadPicker().finally(() => { pickerOpen = false; });
+			}
+						return;
+					}
+					viewer.handleInput(data);
+					tui.requestRender();
+				},
+				dispose: () => {
+					cleanup();
+					if (activeViewerDone === close) activeViewerDone = null;
+					closed = true;
+				},
+			};
+
+			// Opens picker overlay on top of viewer to jump to any thread
+			async function openThreadPicker() {
+				const items = buildPickerItems(getThreads());
+				const selectedId = await showAgentPicker(ctx, items);
+				if (!selectedId) return;
+				if (selectedId === "__main__") { close(); return; }
+				const idx = getThreads().findIndex((t) => t.id === selectedId);
+				if (idx >= 0) {
+					currentIndex = idx;
+					viewer.setThread(getThreads()[currentIndex], makeCallbacks());
+					tui.requestRender();
+				}
+			}
+		}, { overlay: true, overlayOptions: { maxHeight: "70%" } }); // Overlay: editor stays visible below
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Minimal-overhead sub-agent extension for pi. Delegate tasks to specialized agents with isolated context using the pi SDK in-process.",
   "type": "module",
   "license": "MIT",
@@ -30,6 +30,8 @@
     "agents.ts",
     "runner.ts",
     "render.ts",
+    "threads.ts",
+    "thread-viewer.ts",
     "agents/",
     "agent-format.md"
   ],

package/render.ts

@@ -12,6 +12,24 @@ import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import type { Message } from "@earendil-works/pi-ai";
 import { type SubAgentResult, isFailedResult, getResultOutput } from "./runner.ts";
 
+// ---------------------------------------------------------------------------
+// Safe type guards
+// ---------------------------------------------------------------------------
+
+function asString(value: unknown, fallback = "..."): string {
+	return typeof value === "string" ? value : fallback;
+}
+
+function asNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: {};
+}
+
 // ---------------------------------------------------------------------------
 // Display helpers
 // ---------------------------------------------------------------------------
@@ -53,15 +71,15 @@ function formatToolCall(
 
 	switch (toolName) {
 		case "bash": {
-			const command = (args.command as string) || "...";
+			const command = asString(args.command);
 			const preview = command.length > 60 ? `${command.slice(0, 60)}...` : command;
 			return themeFg("muted", "$ ") + themeFg("toolOutput", preview);
 		}
 		case "read": {
-			const rawPath = (args.file_path || args.path || "...") as string;
+			const rawPath = asString(args.file_path ?? args.path);
 			const filePath = shortenPath(rawPath);
-			const offset = args.offset as number | undefined;
-			const limit = args.limit as number | undefined;
+			const offset = asNumber(args.offset);
+			const limit = asNumber(args.limit);
 			let text = themeFg("accent", filePath);
 			if (offset !== undefined || limit !== undefined) {
 				const startLine = offset ?? 1;
@@ -71,24 +89,24 @@ function formatToolCall(
 			return themeFg("muted", "read ") + text;
 		}
 		case "write": {
-			const rawPath = (args.file_path || args.path || "...") as string;
-			const content = (args.content || "") as string;
+			const rawPath = asString(args.file_path ?? args.path);
+			const content = asString(args.content, "");
 			const lines = content.split("\n").length;
 			let text = themeFg("muted", "write ") + themeFg("accent", shortenPath(rawPath));
 			if (lines > 1) text += themeFg("dim", ` (${lines} lines)`);
 			return text;
 		}
 		case "edit": {
-			const rawPath = (args.file_path || args.path || "...") as string;
+			const rawPath = asString(args.file_path ?? args.path);
 			return themeFg("muted", "edit ") + themeFg("accent", shortenPath(rawPath));
 		}
 		case "ls": {
-			const rawPath = (args.path || ".") as string;
+			const rawPath = asString(args.path, ".");
 			return themeFg("muted", "ls ") + themeFg("accent", shortenPath(rawPath));
 		}
 		case "find": {
-			const pattern = (args.pattern || "*") as string;
-			const rawPath = (args.path || ".") as string;
+			const pattern = asString(args.pattern, "*");
+			const rawPath = asString(args.path, ".");
 			return (
 				themeFg("muted", "find ") +
 				themeFg("accent", pattern) +
@@ -96,8 +114,8 @@ function formatToolCall(
 			);
 		}
 		case "grep": {
-			const pattern = (args.pattern || "") as string;
-			const rawPath = (args.path || ".") as string;
+			const pattern = asString(args.pattern);
+			const rawPath = asString(args.path, ".");
 			return (
 				themeFg("muted", "grep ") +
 				themeFg("accent", `/${pattern}/`) +
@@ -127,7 +145,7 @@ function getDisplayItems(messages: Message[]): DisplayItem[] {
 					items.push({
 						type: "toolCall",
 						name: part.name,
-						args: part.arguments as Record<string, unknown>,
+						args: asRecord(part.arguments),
 					});
 				}
 			}

package/runner.ts

@@ -67,6 +67,7 @@ export async function runSubAgent(options: {
 	signal?: AbortSignal;
 	agentName?: string;
 	onUpdate?: (text: string) => void;
+	onMessage?: (partialResult: SubAgentResult) => void;
 }): Promise<SubAgentResult> {
 	const {
 		cwd,
@@ -79,6 +80,7 @@ export async function runSubAgent(options: {
 		signal,
 		agentName = "subagent",
 		onUpdate,
+		onMessage,
 	} = options;
 
 	const result: SubAgentResult = {
@@ -111,6 +113,13 @@ export async function runSubAgent(options: {
 	});
 
 	try {
+		if (signal?.aborted) {
+			result.exitCode = 1;
+			result.stopReason = "aborted";
+			result.errorMessage = "Sub-agent aborted before start";
+			return result;
+		}
+
 		const { session } = await createAgentSession({
 			cwd,
 			model,
@@ -124,6 +133,7 @@ export async function runSubAgent(options: {
 		});
 
 		let cleanupAbort: (() => void) | undefined;
+		let cleanupEventAbort: (() => void) | undefined;
 		try {
 			// Wire abort signal
 			if (signal) {
@@ -142,6 +152,13 @@ export async function runSubAgent(options: {
 
 			// Collect all messages and usage stats from events
 			const eventPromise = new Promise<void>((resolve, reject) => {
+				let settled = false;
+				const finish = (fn: () => void) => {
+					if (settled) return;
+					settled = true;
+					fn();
+				};
+
 				const unsubscribe = session.subscribe((event) => {
 					try {
 						switch (event.type) {
@@ -165,6 +182,7 @@ export async function runSubAgent(options: {
 								}
 								// Collect all messages for extraction
 								result.messages.push(msg as unknown as Message);
+								if (onMessage) onMessage({ ...result, messages: [...result.messages] });
 								break;
 							}
 							case "agent_end": {
@@ -172,25 +190,47 @@ export async function runSubAgent(options: {
 								if (result.messages.length === 0 && event.messages) {
 									result.messages = event.messages as unknown as Message[];
 								}
-								unsubscribe();
-								resolve();
+								finish(() => {
+									unsubscribe();
+									resolve();
+								});
 								break;
 							}
 						}
 					} catch (err) {
-						unsubscribe();
-						reject(err);
+						finish(() => {
+							unsubscribe();
+							reject(err);
+						});
 					}
 				});
+
+				// Resolve on abort so the eventPromise doesn't hang
+				if (signal) {
+					const onAbortResolve = () => {
+						finish(() => {
+							result.exitCode = 1;
+							result.stopReason = "aborted";
+							if (!result.errorMessage) result.errorMessage = "Sub-agent aborted";
+							unsubscribe();
+							resolve();
+						});
+					};
+					signal.addEventListener("abort", onAbortResolve, { once: true });
+					cleanupEventAbort = () => signal.removeEventListener("abort", onAbortResolve);
+				}
 			});
 
 			await session.prompt(task);
 			await eventPromise;
 
-			result.exitCode = 0;
+			if (result.stopReason !== "aborted") {
+				result.exitCode = 0;
+			}
 			return result;
 		} finally {
 			cleanupAbort?.();
+			cleanupEventAbort?.();
 			try {
 				session.dispose();
 			} catch {

package/thread-viewer.ts

@@ -0,0 +1,393 @@
+/**
+ * Thread Viewer — Overlay TUI component for pi-subagent.
+ *
+ * Displays a single subagent thread's full output in an overlay.
+ * Supports keyboard navigation between threads and scrolling.
+ */
+
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { matchesKey, Key, truncateToWidth, Markdown } from "@earendil-works/pi-tui";
+import type { Message } from "@earendil-works/pi-ai";
+
+import { type SubAgentResult, isFailedResult, getResultOutput, getFinalOutput } from "./runner.ts";
+import { formatUsageStats } from "./render.ts";
+import type { SubagentThread } from "./threads.ts";
+import * as os from "node:os";
+
+// ---------------------------------------------------------------------------
+// Safe type guards for tool-call arguments
+// ---------------------------------------------------------------------------
+
+function asString(value: unknown, fallback = "..."): string {
+	return typeof value === "string" ? value : fallback;
+}
+
+function asNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: {};
+}
+
+// ---------------------------------------------------------------------------
+// Tool-call formatting (same as render.ts)
+// ---------------------------------------------------------------------------
+
+function formatToolCall(
+	toolName: string,
+	args: Record<string, unknown>,
+	themeFg: (color: string, text: string) => string,
+): string {
+	const shortenPath = (p: string) => {
+		const home = os.homedir();
+		return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+	};
+
+	switch (toolName) {
+		case "bash": {
+			const command = asString(args.command);
+			const preview = command.length > 60 ? `${command.slice(0, 60)}...` : command;
+			return themeFg("muted", "$ ") + themeFg("toolOutput", preview);
+		}
+		case "read": {
+			const rawPath = asString(args.file_path ?? args.path);
+			const filePath = shortenPath(rawPath);
+			const offset = asNumber(args.offset);
+			const limit = asNumber(args.limit);
+			let text = themeFg("accent", filePath);
+			if (offset !== undefined || limit !== undefined) {
+				const startLine = offset ?? 1;
+				const endLine = limit !== undefined ? startLine + limit - 1 : "";
+				text += themeFg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
+			}
+			return themeFg("muted", "read ") + text;
+		}
+		case "write": {
+			const rawPath = asString(args.file_path ?? args.path);
+			const filePath = shortenPath(rawPath);
+			const content = asString(args.content, "");
+			const lines = content.split("\n").length;
+			let text = themeFg("muted", "write ") + themeFg("accent", filePath);
+			if (lines > 1) text += themeFg("dim", ` (${lines} lines)`);
+			return text;
+		}
+		case "edit": {
+			const rawPath = asString(args.file_path ?? args.path);
+			return themeFg("muted", "edit ") + themeFg("accent", shortenPath(rawPath));
+		}
+		case "ls": {
+			const rawPath = asString(args.path, ".");
+			return themeFg("muted", "ls ") + themeFg("accent", shortenPath(rawPath));
+		}
+		case "find": {
+			const pattern = asString(args.pattern, "*");
+			const rawPath = asString(args.path, ".");
+			return (
+				themeFg("muted", "find ") +
+				themeFg("accent", pattern) +
+				themeFg("dim", ` in ${shortenPath(rawPath)}`)
+			);
+		}
+		case "grep": {
+			const pattern = asString(args.pattern);
+			const rawPath = asString(args.path, ".");
+			return (
+				themeFg("muted", "grep ") +
+				themeFg("accent", `/${pattern}/`) +
+				themeFg("dim", ` in ${shortenPath(rawPath)}`)
+			);
+		}
+		default: {
+			const argsStr = JSON.stringify(args);
+			const preview = argsStr.length > 50 ? `${argsStr.slice(0, 50)}...` : argsStr;
+			return themeFg("accent", toolName) + themeFg("dim", ` ${preview}`);
+		}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Display helpers
+// ---------------------------------------------------------------------------
+
+type DisplayItem =
+	| { type: "text"; text: string }
+	| { type: "toolCall"; name: string; args: Record<string, unknown> };
+
+function getDisplayItems(messages: Message[]): DisplayItem[] {
+	const items: DisplayItem[] = [];
+	for (const msg of messages) {
+		if (msg.role === "assistant") {
+			for (const part of msg.content) {
+				if (part.type === "text" && part.text.trim()) {
+					items.push({ type: "text", text: part.text });
+				} else if (part.type === "toolCall") {
+					items.push({
+						type: "toolCall",
+						name: part.name,
+						args: asRecord(part.arguments),
+					});
+				}
+			}
+		}
+	}
+	return items;
+}
+
+// ---------------------------------------------------------------------------
+// Theme types
+// ---------------------------------------------------------------------------
+
+interface ViewerTheme {
+	fg: (color: string, text: string) => string;
+	bold: (text: string) => string;
+}
+
+// ---------------------------------------------------------------------------
+// Thread Viewer Component
+// ---------------------------------------------------------------------------
+
+export interface ThreadViewerCallbacks {
+	onClose: () => void;
+	onPrev: () => void;
+	onNext: () => void;
+	hasPrev: boolean;
+	hasNext: boolean;
+}
+
+/** Viewport height for the overlay (estimated lines). Must be > 3. */
+const OVERLAY_HEIGHT = 24;
+
+export class ThreadViewer {
+	private thread: SubagentThread;
+	private callbacks: ThreadViewerCallbacks;
+	private theme: ViewerTheme;
+	private scrollOffset = 0;
+	private cachedWidth?: number;
+	private cachedUpdatedAt?: number;
+	private cachedLines?: string[];
+
+	constructor(thread: SubagentThread, callbacks: ThreadViewerCallbacks, theme: ViewerTheme) {
+		this.thread = thread;
+		this.callbacks = callbacks;
+		this.theme = theme;
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, Key.escape)) {
+			this.callbacks.onClose();
+			return;
+		}
+		if (matchesKey(data, Key.alt("left"))) {
+			if (this.callbacks.hasPrev) {
+				this.scrollOffset = 0;
+				this.callbacks.onPrev();
+			}
+			return;
+		}
+		if (matchesKey(data, Key.alt("right"))) {
+			if (this.callbacks.hasNext) {
+				this.scrollOffset = 0;
+				this.callbacks.onNext();
+			}
+			return;
+		}
+		if (matchesKey(data, Key.up)) {
+			if (this.scrollOffset > 0) {
+				this.scrollOffset--;
+				this.invalidate();
+			}
+			return;
+		}
+		if (matchesKey(data, Key.down)) {
+			this.scrollOffset++;
+			this.invalidate();
+			return;
+		}
+		if (matchesKey(data, Key.pageUp)) {
+			this.scrollOffset = Math.max(0, this.scrollOffset - OVERLAY_HEIGHT);
+			this.invalidate();
+			return;
+		}
+		if (matchesKey(data, Key.pageDown)) {
+			this.scrollOffset += OVERLAY_HEIGHT;
+			this.invalidate();
+			return;
+		}
+	}
+
+	render(width: number): string[] {
+		// Use updatedAt in cache key so running→completed transitions bust the cache
+		if (
+			this.cachedLines &&
+			this.cachedWidth === width &&
+			this.cachedUpdatedAt === this.thread.updatedAt
+		) {
+			return this.renderVisible(this.cachedLines, width);
+		}
+
+		const t = this.theme;
+		const lines: string[] = [];
+		const result = this.thread.result;
+		const isErr = result ? isFailedResult(result) : false;
+		const status = this.thread.status;
+
+		// Status icon
+		let icon: string;
+		if (status === "running") icon = t.fg("warning", "⏳");
+		else if (status === "aborted") icon = t.fg("error", "✗");
+		else if (isErr) icon = t.fg("error", "✗");
+		else icon = t.fg("success", "✓");
+
+		// Mode label
+		let modeLabel = "";
+		if (this.thread.mode === "parallel-task") modeLabel = t.fg("muted", " [parallel]");
+		else if (this.thread.mode === "chain-step") modeLabel = t.fg("muted", " [chain]");
+
+		// Header
+		let header = `${icon} ${t.fg("toolTitle", t.bold(this.thread.agentName))}${modeLabel}`;
+		if (status === "running") header += ` ${t.fg("warning", "(running...)")}`;
+		else if (status === "aborted") header += ` ${t.fg("error", "[aborted]")}`;
+		if (result && isErr && result.stopReason && result.stopReason !== "error" && result.stopReason !== "aborted") {
+			const reasonColor = result.stopReason === "timeout" ? "warning" : "error";
+			header += ` ${t.fg(reasonColor, `[${result.stopReason}]`)}`;
+		}
+		lines.push(truncateToWidth(header, width));
+
+		// Error message
+		if (result && isErr && result.errorMessage) {
+			const msgColor = result.stopReason === "timeout" ? "warning" : "error";
+			lines.push(truncateToWidth(t.fg(msgColor, `Error: ${result.errorMessage}`), width));
+		}
+
+		lines.push("");
+
+		// Task
+		lines.push(truncateToWidth(t.fg("muted", "─── Task ───"), width));
+		lines.push(truncateToWidth(t.fg("dim", this.thread.task), width));
+		lines.push("");
+
+		if (status === "running" && (!result || result.messages.length === 0)) {
+			lines.push(truncateToWidth(t.fg("muted", "(waiting for first message...)"), width));
+		} else if (result) {
+			const displayItems = getDisplayItems(result.messages);
+			const finalOutput = getFinalOutput(result.messages);
+
+			lines.push(truncateToWidth(t.fg("muted", "─── Output ───"), width));
+
+			if (displayItems.length === 0 && !finalOutput) {
+				lines.push(truncateToWidth(t.fg("muted", "(no output)"), width));
+			} else {
+				const mdTheme = getMarkdownTheme();
+
+				// Show all display items: text + tool calls
+				for (const item of displayItems) {
+					if (item.type === "toolCall") {
+						lines.push(
+							truncateToWidth(
+								t.fg("muted", "→ ") + formatToolCall(item.name, item.args, t.fg.bind(t)),
+								width,
+							),
+						);
+					} else {
+						// Assistant text — render as markdown
+						const contentWidth = Math.max(1, width - 2);
+						const md = new Markdown(item.text.trim(), 0, 0, mdTheme);
+						const mdLines = md.render(contentWidth);
+						for (const mdLine of mdLines) {
+							lines.push(`  ${truncateToWidth(mdLine, contentWidth)}`);
+						}
+					}
+				}
+				// Check if final output not already shown
+				const finalAlreadyShown = finalOutput && displayItems.some(
+					(it) => it.type === "text" && it.text.includes(finalOutput.slice(0, 100)),
+				);
+				if (finalOutput && !finalAlreadyShown) {
+					const contentWidth = Math.max(1, width - 2);
+					const md = new Markdown(finalOutput.trim(), 0, 0, mdTheme);
+					for (const mdLine of md.render(contentWidth)) {
+						lines.push(`  ${truncateToWidth(mdLine, contentWidth)}`);
+					}
+				}
+			}
+
+			// Usage stats
+			const usageStr = formatUsageStats(result.usage, result.model);
+			if (usageStr) {
+				lines.push("");
+				lines.push(truncateToWidth(t.fg("dim", usageStr), width));
+			}
+		}
+
+		lines.push("");
+
+		// Footer navigation hints
+		const navParts: string[] = [];
+		navParts.push("Esc close");
+		if (this.callbacks.hasPrev) navParts.push("alt+← prev");
+		if (this.callbacks.hasNext) navParts.push("alt+→ next");
+		navParts.push("↑↓ scroll");
+		lines.push(truncateToWidth(t.fg("dim", navParts.join(" · ")), width));
+
+		this.cachedLines = lines;
+		this.cachedWidth = width;
+		this.cachedUpdatedAt = this.thread.updatedAt;
+
+		return this.renderVisible(lines, width);
+	}
+
+	private renderVisible(allLines: string[], width: number): string[] {
+		const total = allLines.length;
+		const maxVisible = Math.max(3, OVERLAY_HEIGHT);
+
+		// Clamp scrollOffset so the last page shows a full viewport minus one indicator line
+		const maxOffset =
+			total > maxVisible
+				? Math.max(0, total - (maxVisible - 1))
+				: 0;
+		const offset = Math.max(0, Math.min(this.scrollOffset, maxOffset));
+
+		// Reserve space for scroll indicators
+		const aboveShown = offset > 0;
+		const belowShown = offset + maxVisible < total;
+		const indicatorLines = (aboveShown ? 1 : 0) + (belowShown ? 1 : 0);
+		const bodyHeight = Math.max(1, maxVisible - indicatorLines);
+
+		const visible = allLines.slice(offset, offset + bodyHeight);
+
+		// Scroll indicator at top
+		if (aboveShown) {
+			visible.unshift(truncateToWidth(
+				this.theme.fg("muted", `↑ ${offset} more lines above`),
+				width,
+			));
+		}
+		// Scroll indicator at bottom
+		if (belowShown) {
+			const remaining = total - offset - bodyHeight;
+			visible.push(truncateToWidth(
+				this.theme.fg("muted", `↓ ${remaining} more lines below`),
+				width,
+			));
+		}
+
+		return visible;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedUpdatedAt = undefined;
+		this.cachedLines = undefined;
+	}
+
+	/** Update the thread being displayed (for prev/next navigation). */
+	setThread(thread: SubagentThread, callbacks: ThreadViewerCallbacks): void {
+		this.thread = thread;
+		this.callbacks = callbacks;
+		this.scrollOffset = 0;
+		this.invalidate();
+	}
+}

package/threads.ts

@@ -0,0 +1,116 @@
+/**
+ * Thread Store for pi-subagent.
+ *
+ * In-memory registry tracking all subagent invocations during a pi session.
+ * Enables the /agent command to list and switch between subagent threads.
+ * Supports subscriptions so UIs can react to thread status changes.
+ */
+
+import type { SubAgentResult } from "./runner.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ThreadMode = "single" | "parallel-task" | "chain-step";
+export type ThreadStatus = "running" | "completed" | "failed" | "aborted";
+
+export interface SubagentThread {
+	id: string;
+	agentName: string;
+	task: string;
+	mode: ThreadMode;
+	status: ThreadStatus;
+	result?: SubAgentResult;
+	toolCallId?: string;
+	createdAt: number;
+	updatedAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// Thread Store
+// ---------------------------------------------------------------------------
+
+export class ThreadStore {
+	private threads = new Map<string, SubagentThread>();
+	private order: string[] = [];
+	private listeners = new Set<() => void>();
+
+	/** Subscribe to thread store changes. Returns an unsubscribe function. */
+	subscribe(listener: () => void): () => void {
+		this.listeners.add(listener);
+		return () => { this.listeners.delete(listener); };
+	}
+
+	private notify(): void {
+		for (const listener of this.listeners) {
+			try { listener(); } catch { /* best effort */ }
+		}
+	}
+
+	createThread(params: {
+		agentName: string;
+		task: string;
+		mode: ThreadMode;
+		toolCallId?: string;
+	}): SubagentThread {
+		const id = cryptoGenId();
+		const now = Date.now();
+		const thread: SubagentThread = {
+			id,
+			agentName: params.agentName,
+			task: params.task,
+			mode: params.mode,
+			status: "running",
+			toolCallId: params.toolCallId,
+			createdAt: now,
+			updatedAt: now,
+		};
+		this.threads.set(id, thread);
+		this.order.push(id);
+		this.notify();
+		return thread;
+	}
+
+	updateThread(id: string, updates: Partial<Pick<SubagentThread, "status" | "result">>): void {
+		const thread = this.threads.get(id);
+		if (!thread) return;
+		if (updates.status) thread.status = updates.status;
+		if (updates.result) thread.result = updates.result;
+		thread.updatedAt = Date.now();
+		this.notify();
+	}
+
+	getThread(id: string): SubagentThread | undefined {
+		return this.threads.get(id);
+	}
+
+	getAllThreads(): SubagentThread[] {
+		return this.order.map((id) => this.threads.get(id)!).filter(Boolean);
+	}
+
+	clear(): void {
+		this.threads.clear();
+		this.order = [];
+		this.notify();
+	}
+}
+
+/** Singleton instance. */
+export const threadStore = new ThreadStore();
+
+// ---------------------------------------------------------------------------
+// ID generation (UUID v4 style, good enough for in-memory use)
+// ---------------------------------------------------------------------------
+
+function cryptoGenId(): string {
+	if (typeof crypto !== "undefined" && crypto.randomUUID) {
+		return crypto.randomUUID();
+	}
+	// Fallback for environments without crypto (very unlikely in Node)
+	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+		const r = (Math.random() * 16) | 0;
+		const v = c === "x" ? r : (r & 0x3) | 0x8;
+		return v.toString(16);
+	});
+}