@ferris1225/pi-subagents 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Focused sub-agent delegation for pi: explore / plan / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -16,7 +16,7 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { discoverAgents, type AgentConfig } from "./agents.ts";
 import { getConfigPath, loadConfig } from "./config.ts";
@@ -32,12 +32,13 @@ import {
 	isFailedResult,
 	mapWithConcurrencyLimit,
 	runSingleAgent,
-	truncateParallelOutput,
 	type OnUpdateCallback,
 	type SingleResult,
 	type SubagentDetails,
+	type SubagentLiveEvent,
 	type UsageStats,
 } from "./spawn.ts";
+import { monitor, openSubagentOverlay, statusIcon } from "./monitor.ts";
 
 const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
@@ -121,6 +122,7 @@ export default function (pi: ExtensionAPI): void {
 		parameters: SubagentParams,
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			monitor.beginTurn();
 			const config = await loadConfig(configPath);
 			const discovery = discoverAgents(ctx.cwd, {
 				scope: config.agentScope,
@@ -186,6 +188,27 @@ export default function (pi: ExtensionAPI): void {
 				};
 
 				const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
+					const resolvedModel = agents.find((a) => a.name === t.agent)?.model;
+					const runId = monitor.addRun(t.agent, resolvedModel);
+					const onLive = (e: SubagentLiveEvent): void => {
+						switch (e.kind) {
+							case "status":
+								monitor.setStatus(runId, e.status);
+								break;
+							case "usage":
+								monitor.setUsage(runId, e.usage, e.model);
+								break;
+							case "tool_start":
+								monitor.appendTranscript(runId, { kind: "tool", text: `▸ ${e.toolName}(${typeof e.args === "object" ? JSON.stringify(e.args).slice(0, 120) : String(e.args).slice(0, 120)})` });
+								break;
+							case "tool_end":
+								monitor.appendTranscript(runId, { kind: e.isError ? "error" : "status", text: `${e.isError ? "✗" : "✓"} ${e.toolName}` });
+								break;
+							case "text_delta":
+								monitor.appendTextDelta(runId, e.delta);
+								break;
+						}
+					};
 					const perTaskUpdate: OnUpdateCallback | undefined = onUpdate
 						? (partial) => {
 								const current = partial.details?.results[0];
@@ -203,6 +226,7 @@ export default function (pi: ExtensionAPI): void {
 						cwd: t.cwd,
 						signal,
 						onUpdate: perTaskUpdate,
+						onLive,
 						makeDetails: makeDetails("parallel"),
 					});
 					allResults[index] = result;
@@ -212,7 +236,7 @@ export default function (pi: ExtensionAPI): void {
 
 				const successCount = results.filter((r) => !isFailedResult(r)).length;
 				const summaries = results.map((r) => {
-					const output = truncateParallelOutput(getResultOutput(r));
+					const output = getResultOutput(r);
 					const status = isFailedResult(r) ? "failed" : "completed";
 					const usage = formatUsage(r.usage);
 					return `### [${r.agent}] ${status}${usage ? ` (${usage})` : ""}\n\n${output}`;
@@ -229,6 +253,27 @@ export default function (pi: ExtensionAPI): void {
 			}
 
 			// ---- Single mode ----
+			const resolvedModel = agents.find((a) => a.name === params.agent)?.model;
+			const runId = monitor.addRun(params.agent as string, resolvedModel);
+			const onLive = (e: SubagentLiveEvent): void => {
+				switch (e.kind) {
+					case "status":
+						monitor.setStatus(runId, e.status);
+						break;
+					case "usage":
+						monitor.setUsage(runId, e.usage, e.model);
+						break;
+					case "tool_start":
+						monitor.appendTranscript(runId, { kind: "tool", text: `▸ ${e.toolName}(${typeof e.args === "object" ? JSON.stringify(e.args).slice(0, 120) : String(e.args).slice(0, 120)})` });
+						break;
+					case "tool_end":
+						monitor.appendTranscript(runId, { kind: e.isError ? "error" : "status", text: `${e.isError ? "✗" : "✓"} ${e.toolName}` });
+						break;
+					case "text_delta":
+						monitor.appendTextDelta(runId, e.delta);
+						break;
+				}
+			};
 			const result = await runSingleAgent({
 				defaultCwd: ctx.cwd,
 				agent: agents.find((a) => a.name === params.agent),
@@ -237,6 +282,7 @@ export default function (pi: ExtensionAPI): void {
 				cwd: params.cwd,
 				signal,
 				onUpdate,
+				onLive,
 				makeDetails: makeDetails("single"),
 			});
 
@@ -275,13 +321,27 @@ export default function (pi: ExtensionAPI): void {
 		renderResult(result, _options, theme) {
 			const details = result.details as SubagentDetails | undefined;
 			if (!details || details.results.length === 0) return new Text(theme.fg("dim", "(no output)"), 0, 0);
-			const usage = formatUsage(aggregateUsage(details.results));
-			const header =
-				details.mode === "parallel"
-					? `${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${details.results.length})`)}`
-					: `${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", details.results[0].agent)}`;
-			const suffix = usage ? `  ${theme.fg("dim", usage)}` : "";
-			return new Text(header + suffix, 0, 0);
+
+			if (details.mode === "single") {
+				const r = details.results[0];
+				const icon = statusIcon(isFailedResult(r) ? "failed" : "done", theme);
+				const usage = formatUsage(r.usage);
+				const model = r.model ?? "?";
+				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${usage ? ` · ${usage}` : ""}`)}`;
+				return new Text(line, 0, 0);
+			}
+
+			// Parallel mode: header + one compact line per agent
+			const lines: string[] = [
+				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${details.results.length})`)}`,
+			];
+			for (const r of details.results) {
+				const icon = statusIcon(isFailedResult(r) ? "failed" : "done", theme);
+				const usage = formatUsage(r.usage);
+				const model = r.model ?? "?";
+				lines.push(`  ${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${usage ? ` · ${usage}` : ""}`)}`);
+			}
+			return new Text(lines.join("\n"), 0, 0);
 		},
 	});
 
@@ -292,6 +352,55 @@ export default function (pi: ExtensionAPI): void {
 		},
 	});
 
+	// Persistent widget above the editor showing live sub-agent status.
+	pi.on("session_start", (_e, ctx) => {
+		if (ctx.mode !== "tui") return;
+		ctx.ui.setWidget(
+			"pi-subagents",
+			(tui, theme) => {
+				const unsub = monitor.subscribe(() => tui.requestRender());
+				return {
+					render(width: number): string[] {
+						const runs = monitor.getRuns();
+						if (runs.length === 0) return [];
+						const lines = runs.map((r) => {
+							const icon = statusIcon(r.status, theme);
+							return truncateToWidth(` ${icon} ${monitor.summarize(r)}`, width, "");
+						});
+						lines.push(truncateToWidth(theme.fg("dim", " ctrl+shift+a / /subagents to inspect"), width, ""));
+						return lines;
+					},
+					invalidate() {},
+					dispose() {
+						unsub();
+					},
+				};
+			},
+			{ placement: "aboveEditor" },
+		);
+	});
+
+	// Drill-down overlay command.
+	pi.registerCommand("subagents", {
+		description: "Inspect running/recent sub-agents (model, tokens, live transcript)",
+		handler: async (_args, ctx) => {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("The sub-agent monitor requires Pi's interactive TUI.", "warning");
+				return;
+			}
+			await openSubagentOverlay(ctx);
+		},
+	});
+
+	// Keyboard shortcut for the overlay.
+	pi.registerShortcut("ctrl+shift+a", {
+		description: "Open sub-agent monitor",
+		handler: async (ctx) => {
+			if (ctx.mode !== "tui") return;
+			await openSubagentOverlay(ctx);
+		},
+	});
+
 	// Proactive dispatch: inject the delegation directive into the parent system prompt.
 	pi.on("before_agent_start", async (event, ctx) => {
 		const config = await loadConfig(configPath);

package/src/monitor.ts

@@ -0,0 +1,370 @@
+/**
+ * Sub-agent monitor: a module-level singleton store that tracks subagent runs
+ * for the current turn, plus a drill-down overlay component for live inspection.
+ *
+ * The store notifies subscribers on every mutation so the persistent widget and
+ * the overlay can re-render. The overlay shows a list of runs (↑/↓ + Enter) and
+ * a detail view with the live transcript (auto-tailing, scrollable).
+ */
+
+import {
+	matchesKey,
+	truncateToWidth,
+	type Component,
+	type Focusable,
+	type TUI,
+} from "@earendil-works/pi-tui";
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { UsageStats } from "./spawn.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type RunStatus = "queued" | "running" | "done" | "failed";
+
+export interface TranscriptLine {
+	kind: "tool" | "text" | "status" | "error";
+	text: string;
+}
+
+export interface RunView {
+	id: number;
+	agent: string;
+	model?: string;
+	status: RunStatus;
+	usage: UsageStats;
+	transcript: TranscriptLine[];
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+function formatTokens(count: number): string {
+	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
+	return String(count);
+}
+
+export function formatUsageCompact(usage: UsageStats): string {
+	const parts: string[] = [];
+	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+	return parts.join(" ");
+}
+
+// ---------------------------------------------------------------------------
+// MonitorStore
+// ---------------------------------------------------------------------------
+
+export class MonitorStore {
+	private runs: RunView[] = [];
+	private nextId = 1;
+	private subscribers = new Set<() => void>();
+
+	beginTurn(): void {
+		// Clear finished runs from a previous turn, but keep any still-active
+		// (queued/running) ones so a concurrent sub-agent call is not wiped.
+		this.runs = this.runs.filter((r) => r.status === "queued" || r.status === "running");
+		this.notify();
+	}
+
+	addRun(agent: string, model?: string): number {
+		const id = this.nextId++;
+		this.runs.push({
+			id,
+			agent,
+			model,
+			status: "queued",
+			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+			transcript: [],
+		});
+		this.notify();
+		return id;
+	}
+
+	setStatus(id: number, status: RunStatus): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.status = status;
+		this.notify();
+	}
+
+	setUsage(id: number, usage: UsageStats, model?: string): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.usage = { ...usage };
+		if (model) run.model = model;
+		this.notify();
+	}
+
+	appendTranscript(id: number, line: TranscriptLine): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.transcript.push(line);
+		this.notify();
+	}
+
+	/** Append streamed assistant text, merging consecutive deltas into coherent
+	 * lines (split only on real newlines) instead of one line per token fragment. */
+	appendTextDelta(id: number, delta: string): void {
+		const run = this.find(id);
+		if (!run || delta.length === 0) return;
+		const segments = delta.split("\n");
+		for (let i = 0; i < segments.length; i++) {
+			const seg = segments[i];
+			const last = run.transcript[run.transcript.length - 1];
+			if (i === 0 && last && last.kind === "text") {
+				last.text += seg;
+			} else {
+				run.transcript.push({ kind: "text", text: seg });
+			}
+		}
+		this.notify();
+	}
+
+	getRuns(): RunView[] {
+		return this.runs;
+	}
+
+	subscribe(cb: () => void): () => void {
+		this.subscribers.add(cb);
+		return () => {
+			this.subscribers.delete(cb);
+		};
+	}
+
+	summarize(run: RunView): string {
+		const usage = formatUsageCompact(run.usage);
+		const parts = [run.agent];
+		if (run.model) parts.push(run.model);
+		if (usage) parts.push(usage);
+		parts.push(run.status);
+		return parts.join(" · ");
+	}
+
+	private find(id: number): RunView | undefined {
+		return this.runs.find((r) => r.id === id);
+	}
+
+	private notify(): void {
+		for (const cb of this.subscribers) {
+			try {
+				cb();
+			} catch {
+				/* subscriber errors must not break the store */
+			}
+		}
+	}
+}
+
+export const monitor = new MonitorStore();
+
+// ---------------------------------------------------------------------------
+// Status icons
+// ---------------------------------------------------------------------------
+
+export function statusIcon(status: RunStatus, theme: Theme): string {
+	switch (status) {
+		case "running":
+			return theme.fg("accent", "●");
+		case "done":
+			return theme.fg("success", "✓");
+		case "failed":
+			return theme.fg("error", "✗");
+		default:
+			return theme.fg("dim", "○");
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Overlay component
+// ---------------------------------------------------------------------------
+
+class SubagentOverlay implements Component, Focusable {
+	private _focused = false;
+	private mode: "list" | "detail" = "list";
+	private cursor = 0;
+	private scroll = 0;
+	private cachedWidth = -1;
+	private cachedLines: string[] = [];
+	private closed = false;
+
+	private readonly unsub: () => void;
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly theme: Theme,
+		private readonly done: (result: void) => void,
+	) {
+		this.unsub = monitor.subscribe(() => {
+			this.invalidate();
+			this.tui.requestRender();
+		});
+	}
+
+	get focused(): boolean {
+		return this._focused;
+	}
+
+	set focused(value: boolean) {
+		this._focused = value;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = -1;
+		this.cachedLines = [];
+	}
+
+	handleInput(data: string): void {
+		if (this.mode === "list") {
+			const runs = monitor.getRuns();
+			if (matchesKey(data, "up")) {
+				if (runs.length > 0) this.cursor = this.cursor === 0 ? runs.length - 1 : this.cursor - 1;
+			} else if (matchesKey(data, "down")) {
+				if (runs.length > 0) this.cursor = this.cursor === runs.length - 1 ? 0 : this.cursor + 1;
+			} else if (matchesKey(data, "return")) {
+				if (runs.length > 0) {
+					this.mode = "detail";
+					this.scrollToBottom();
+				}
+			} else if (matchesKey(data, "escape")) {
+				this.close();
+				return;
+			}
+		} else {
+			if (matchesKey(data, "up")) {
+				this.scroll = Math.max(0, this.scroll - 1);
+			} else if (matchesKey(data, "down")) {
+				this.scroll++;
+			} else if (matchesKey(data, "escape")) {
+				this.mode = "list";
+			}
+		}
+		this.invalidate();
+		this.tui.requestRender();
+	}
+
+	render(width: number): string[] {
+		if (this.cachedWidth === width && this.cachedLines.length > 0) return this.cachedLines;
+
+		const t = this.theme;
+		const fit = (line: string): string => truncateToWidth(line, width, "");
+		const border = fit(t.fg("border", "─".repeat(Math.max(1, width))));
+
+		const lines: string[] = [];
+
+		if (this.mode === "list") {
+			lines.push(border);
+			lines.push(fit(t.fg("accent", t.bold(" Sub-agents"))));
+			lines.push(border);
+
+			const runs = monitor.getRuns();
+			if (runs.length === 0) {
+				lines.push(fit(t.fg("dim", "  (no sub-agent runs this turn)")));
+			} else {
+				this.cursor = Math.max(0, Math.min(this.cursor, runs.length - 1));
+				for (let i = 0; i < runs.length; i++) {
+					const run = runs[i];
+					const isCursor = i === this.cursor;
+					const mark = isCursor ? t.fg("accent", "❯ ") : "  ";
+					const icon = statusIcon(run.status, t);
+					const usage = formatUsageCompact(run.usage);
+					const parts = [run.agent];
+					if (run.model) parts.push(run.model);
+					if (usage) parts.push(usage);
+					parts.push(run.status);
+					const label = isCursor ? t.fg("accent", t.bold(parts.join(" · "))) : parts.join(" · ");
+					lines.push(fit(`${mark}${icon} ${label}`));
+				}
+			}
+
+			lines.push(border);
+			lines.push(fit(t.fg("dim", " ↑↓ select · enter open · esc close")));
+			lines.push(border);
+		} else {
+			const runs = monitor.getRuns();
+			const run = runs[this.cursor];
+
+			lines.push(border);
+			if (run) {
+				const headerParts = [run.agent];
+				if (run.model) headerParts.push(run.model);
+				lines.push(fit(t.fg("accent", t.bold(` ${headerParts.join(" · ")}`))));
+				const usage = formatUsageCompact(run.usage);
+				const statusLine = ` ${statusIcon(run.status, t)} ${run.status}${usage ? ` · ${usage}` : ""}`;
+				lines.push(fit(statusLine));
+			} else {
+				lines.push(fit(t.fg("dim", " (no run selected)")));
+			}
+			lines.push(border);
+
+			if (run) {
+				// Available height for transcript: total minus header(4) + footer(2)
+				const transcriptLines = run.transcript;
+				const availHeight = Math.max(1, 40 - 6); // reasonable default; actual height varies
+				this.scroll = Math.max(0, Math.min(this.scroll, Math.max(0, transcriptLines.length - availHeight)));
+
+				// Auto-tail: if scroll is at the bottom, keep it there
+				const maxScroll = Math.max(0, transcriptLines.length - availHeight);
+				if (this.scroll >= maxScroll - 1) this.scroll = maxScroll;
+
+				const visible = transcriptLines.slice(this.scroll, this.scroll + availHeight);
+				for (const entry of visible) {
+					const color =
+						entry.kind === "tool"
+							? "accent"
+							: entry.kind === "error"
+								? "error"
+								: entry.kind === "status"
+									? "dim"
+									: "text";
+					lines.push(fit(t.fg(color, ` ${entry.text}`)));
+				}
+				if (transcriptLines.length === 0) {
+					lines.push(fit(t.fg("dim", " (waiting for output…)")));
+				}
+			}
+
+			lines.push(border);
+			lines.push(fit(t.fg("dim", " ↑↓ scroll · esc back")));
+			lines.push(border);
+		}
+
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+
+	dispose(): void {
+		if (!this.closed) {
+			this.closed = true;
+			this.unsub();
+		}
+	}
+
+	private scrollToBottom(): void {
+		const runs = monitor.getRuns();
+		const run = runs[this.cursor];
+		if (run) this.scroll = Math.max(0, run.transcript.length);
+	}
+
+	private close(): void {
+		this.closed = true;
+		this.unsub();
+		this.done();
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+export async function openSubagentOverlay(ctx: ExtensionContext): Promise<void> {
+	await ctx.ui.custom<void>((tui, theme, _kb, done) => new SubagentOverlay(tui, theme, done), {
+		overlay: true,
+	});
+}

package/src/spawn.ts

@@ -20,7 +20,6 @@ import type { AgentConfig, AgentSource } from "./agents.ts";
 
 export const MAX_PARALLEL_TASKS = 8;
 export const MAX_CONCURRENCY = 4;
-export const PER_TASK_OUTPUT_CAP = 50 * 1024;
 /** Max nesting depth for sub-agent -> sub-agent spawning (recursion guard). */
 export const MAX_SUBAGENT_DEPTH = 2;
 export const DEPTH_ENV_VAR = "PI_SUBAGENT_DEPTH";
@@ -55,6 +54,13 @@ export interface SubagentDetails {
 
 export type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
 
+export type SubagentLiveEvent =
+	| { kind: "status"; status: "queued" | "running" | "done" | "failed" }
+	| { kind: "usage"; usage: UsageStats; model?: string }
+	| { kind: "tool_start"; toolName: string; args: unknown }
+	| { kind: "tool_end"; toolName: string; isError: boolean }
+	| { kind: "text_delta"; delta: string };
+
 function emptyUsage(): UsageStats {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
 }
@@ -82,15 +88,6 @@ export function getResultOutput(result: SingleResult): string {
 	return getFinalOutput(result.messages) || "(no output)";
 }
 
-export function truncateParallelOutput(output: string): string {
-	const byteLength = Buffer.byteLength(output, "utf8");
-	if (byteLength <= PER_TASK_OUTPUT_CAP) return output;
-	let truncated = output.slice(0, PER_TASK_OUTPUT_CAP);
-	while (Buffer.byteLength(truncated, "utf8") > PER_TASK_OUTPUT_CAP) truncated = truncated.slice(0, -1);
-	const omitted = byteLength - Buffer.byteLength(truncated, "utf8");
-	return `${truncated}\n\n[Output truncated: ${omitted} bytes omitted. Full output preserved in tool details.]`;
-}
-
 export async function mapWithConcurrencyLimit<TIn, TOut>(
 	items: TIn[],
 	concurrency: number,
@@ -148,13 +145,14 @@ export interface RunSingleOptions {
 	cwd?: string;
 	signal?: AbortSignal;
 	onUpdate?: OnUpdateCallback;
+	onLive?: (e: SubagentLiveEvent) => void;
 	makeDetails: (results: SingleResult[]) => SubagentDetails;
 	env?: NodeJS.ProcessEnv;
 }
 
 /** Spawn one agent as an isolated pi child process and collect its output. */
 export async function runSingleAgent(options: RunSingleOptions): Promise<SingleResult> {
-	const { agent, agentName, task, cwd, signal, onUpdate, makeDetails } = options;
+	const { agent, agentName, task, cwd, signal, onUpdate, onLive, makeDetails } = options;
 
 	if (!agent) {
 		return {
@@ -230,6 +228,42 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 					return;
 				}
 
+				// Live event: agent started
+				if (event.type === "agent_start" || event.type === "turn_start") {
+					if (onLive) {
+						try {
+							onLive({ kind: "status", status: "running" });
+						} catch { /* never throw from event handling */ }
+					}
+				}
+
+				// Live event: streamed assistant text
+				if (event.type === "message_update" && event.assistantMessageEvent?.type === "text_delta") {
+					if (onLive) {
+						try {
+							onLive({ kind: "text_delta", delta: event.assistantMessageEvent.delta ?? "" });
+						} catch { /* never throw from event handling */ }
+					}
+				}
+
+				// Live event: tool execution started
+				if (event.type === "tool_execution_start") {
+					if (onLive) {
+						try {
+							onLive({ kind: "tool_start", toolName: event.toolName ?? "unknown", args: event.args });
+						} catch { /* never throw from event handling */ }
+					}
+				}
+
+				// Live event: tool execution ended
+				if (event.type === "tool_execution_end") {
+					if (onLive) {
+						try {
+							onLive({ kind: "tool_end", toolName: event.toolName ?? "unknown", isError: Boolean(event.isError) });
+						} catch { /* never throw from event handling */ }
+					}
+				}
+
 				if (event.type === "message_end" && event.message) {
 					const msg = event.message as Message;
 					currentResult.messages.push(msg);
@@ -248,6 +282,12 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 						if ((msg as any).stopReason) currentResult.stopReason = (msg as any).stopReason;
 						if ((msg as any).errorMessage) currentResult.errorMessage = (msg as any).errorMessage;
 					}
+					// Live event: usage snapshot after accumulation
+					if (onLive) {
+						try {
+							onLive({ kind: "usage", usage: { ...currentResult.usage }, model: currentResult.model });
+						} catch { /* never throw from event handling */ }
+					}
 					emitUpdate();
 				}
 
@@ -256,7 +296,6 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 					emitUpdate();
 				}
 			};
-
 			proc.stdout.on("data", (data) => {
 				buffer += data.toString();
 				const lines = buffer.split("\n");
@@ -270,6 +309,13 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 
 			proc.on("close", (code) => {
 				if (buffer.trim()) processLine(buffer);
+				// Live event: final status derived from exit code
+				if (onLive) {
+					try {
+						const failed = (code ?? 0) !== 0 || currentResult.stopReason === "error" || currentResult.stopReason === "aborted";
+						onLive({ kind: "status", status: failed ? "failed" : "done" });
+					} catch { /* never throw from event handling */ }
+				}
 				resolve(code ?? 0);
 			});
 
@@ -289,7 +335,14 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 		});
 
 		currentResult.exitCode = exitCode;
-		if (wasAborted) throw new Error("Subagent was aborted");
+		if (wasAborted) {
+			if (onLive) {
+				try {
+					onLive({ kind: "status", status: "failed" });
+				} catch { /* never throw from event handling */ }
+			}
+			throw new Error("Subagent was aborted");
+		}
 		return currentResult;
 	} finally {
 		if (tmpPromptPath)