@rohaquinlop/pi-subagents 0.3.0 → 0.5.0

package/index.ts

@@ -14,8 +14,11 @@ import { Container, Markdown, Spacer, Text, visibleWidth } from "@earendil-works
 import { Type } from "@sinclair/typebox";
 import "./tools/safe-bash";
 
-import type { AgentConfig } from "./lib/types";
-import { discoverAgents, mergeAgents } from "./lib/helpers";
+import type { AgentConfig, AgentUsage, PipelineStepResult, PipelineResult, LoopIterationResult, LoopResult } from "./lib/types";
+import { discoverAgents, mergeAgents, substitutePlaceholders, formatConnectorContext } from "./lib/helpers";
+import { zeroUsage, accumulateUsage, validateAgents, MAX_LOOP_CONTEXT, parseJudgeVerdict } from "./lib/pipeline-helpers";
+import { buildSubagentErrorContent, buildPipelineErrorContent, buildLoopErrorContent } from "./lib/error-helpers";
+import { detectCycle } from "./lib/loop-detector";
 
 interface ToolEvent {
 	tool: string;
@@ -54,6 +57,7 @@ interface AgentProgress {
 	durationMs: number;
 	lastMessage: string;
 	error?: string;
+	warning?: string;
 }
 
 interface AgentResult {
@@ -64,17 +68,21 @@ interface AgentResult {
 	progress: AgentProgress;
 	model?: string;
 	contextWindow?: number;
-	usage: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: number; turns: number };
+	usage: AgentUsage;
 }
 
 interface Details {
-	results: AgentResult[];
+	results?: AgentResult[];
+	pipelineResult?: PipelineResult & { currentStep?: number };
+	loopResult?: LoopResult & { currentIteration?: number };
 }
 
 // ── Config ─────────────────────────────────────────────────────────────
 
 interface ExtensionConfig {
 	maxConcurrency?: number;
+	subagentTimeoutMs?: number;      // wall-clock, default 600000 (10 min). 0 = disabled.
+	subagentIdleTimeoutMs?: number;  // no-stdout watchdog, default 300000 (5 min). 0 = disabled.
 }
 
 const EXT_DIR = path.dirname(new URL(import.meta.url).pathname);
@@ -82,6 +90,10 @@ const AGENTS_DIR = path.join(EXT_DIR, "agents");
 const TOOLS_DIR = path.join(EXT_DIR, "tools");
 const CONFIG_PATH = path.join(EXT_DIR, "config.json");
 const DEFAULT_MAX_CONCURRENCY = 4;
+const DEFAULT_SUBAGENT_TIMEOUT_MS = 600_000;     // 10 minutes
+const DEFAULT_SUBAGENT_IDLE_TIMEOUT_MS = 300_000; // 5 minutes
+
+let extensionConfig: ExtensionConfig = {};
 
 function loadConfig(): ExtensionConfig {
 	try {
@@ -196,6 +208,7 @@ const MODEL_EXTENSIONS: ModelExtension[] = buildModelExtensions();
 // ── Agent Discovery & Registration ────────────────────────────────────
 
 let agents: AgentConfig[] = [];
+let semaphore: Semaphore;
 
 // Read once at module load. If we're a child subagent process whose parent
 // pinned an allowlist, we silently ignore any agent (built-in OR registered
@@ -475,6 +488,11 @@ function flatten(s: string): string {
 // doesn't need to read inline anyway.
 const MAX_ARG_PREVIEW = 4000;
 
+// Hard cap on recentTools entries to prevent unbounded memory growth in
+// long-running subagents. Generous for expanded-view history; matches the
+// callHistory trim pattern.
+const MAX_RECENT_TOOLS = 50;
+
 function extractToolArgsPreview(args: Record<string, unknown>): string {
 	const cap = (s: string) => (s.length > MAX_ARG_PREVIEW ? s.slice(0, MAX_ARG_PREVIEW) + "…" : s);
 	if (args.command) return cap(flatten(String(args.command)));
@@ -498,7 +516,7 @@ async function runSubagent(
 	task: string,
 	cwd: string,
 	signal: AbortSignal | undefined,
-	onUpdate?: (progress: AgentProgress, usage: AgentResult["usage"]) => void,
+	onUpdate?: (progress: AgentProgress, usage: AgentResult["usage"], finalExitCode?: number) => void,
 ): Promise<AgentResult> {
 	const { args, tempDir, childEnv } = await buildPiArgs(agent, task, cwd);
 	const command = args[0];
@@ -540,14 +558,73 @@ async function runSubagent(
 
 		let buf = "";
 		let stderrBuf = "";
+		let resolved = false;
+		let wallTimer: ReturnType<typeof setTimeout> | undefined;
+		let idleTimer: ReturnType<typeof setTimeout> | undefined;
+		let inFlightToolCount = 0;
+		let childClosed = false;
+		let sigkillTimer: ReturnType<typeof setTimeout> | undefined;
+		let callHistory: string[] = [];	// sliding window of tool-call signatures for cycle detection
+
+		const safeResolve = (code: number) => {
+			if (resolved) return;
+			resolved = true;
+			clearTimeout(wallTimer);
+			clearTimeout(idleTimer);
+			clearTimeout(sigkillTimer);
+			if (signal) signal.removeEventListener("abort", abortKill);
+			resolve(code);
+		};
+
+		// Wall-clock timeout
+		const timeoutMs = extensionConfig.subagentTimeoutMs ?? DEFAULT_SUBAGENT_TIMEOUT_MS;
+		if (timeoutMs > 0) {
+			wallTimer = setTimeout(() => {
+				if (!progress.error) progress.error = `Subagent timed out after ${Math.round(timeoutMs / 1000)}s`;
+				proc.kill("SIGTERM");
+				clearTimeout(sigkillTimer);
+				sigkillTimer = setTimeout(() => {
+					if (!childClosed) proc.kill("SIGKILL");
+				}, 5000);
+			}, timeoutMs);
+		}
+
+		// Idle (no-stdout) watchdog
+		const idleMs = extensionConfig.subagentIdleTimeoutMs ?? DEFAULT_SUBAGENT_IDLE_TIMEOUT_MS;
+		const resetIdle = () => {
+			if (idleMs <= 0) return;
+			clearTimeout(idleTimer);
+			idleTimer = setTimeout(() => {
+				if (!progress.error) progress.error = `Subagent idle for ${Math.round(idleMs / 1000)}s — likely stuck`;
+				proc.kill("SIGTERM");
+				clearTimeout(sigkillTimer);
+				sigkillTimer = setTimeout(() => {
+					if (!childClosed) proc.kill("SIGKILL");
+				}, 5000);
+			}, idleMs);
+		};
+		resetIdle();
+
+		const pauseIdle = () => {
+			clearTimeout(idleTimer);
+			idleTimer = undefined;
+		};
+		const resumeIdle = () => {
+			if (inFlightToolCount === 0) resetIdle();
+		};
+
+		const MAX_STDERR_BYTES = 100_000;
 
 		const processLine = (line: string) => {
+			if (inFlightToolCount === 0) resetIdle();
 			if (!line.trim()) return;
 			try {
 				const evt = JSON.parse(line) as any;
 				progress.durationMs = Date.now() - startTime;
 
 				if (evt.type === "tool_execution_start") {
+					inFlightToolCount++;
+					pauseIdle();
 					progress.toolCount++;
 					progress.recentTools.push({
 						tool: evt.toolName,
@@ -555,6 +632,37 @@ async function runSubagent(
 						toolCallId: evt.toolCallId,
 						status: "running",
 					});
+					// Trim oldest completed entries, but never evict an in-flight tool —
+					// otherwise tool_execution_end's .find(toolCallId) would no-op and leave a
+					// permanently-"running" ghost.
+					while (progress.recentTools.length > MAX_RECENT_TOOLS) {
+						const idx = progress.recentTools.findIndex((t) => t.status !== "running");
+						if (idx === -1) break; // only running entries left — don't evict in-flight
+						progress.recentTools.splice(idx, 1);
+					}
+					// ── Cycle detection (parent-side, context-free) ──
+					// Signature = toolName + args preview. Two calls with different args
+					// (different file, or same file different content) → different sig.
+					const sig = `${evt.toolName}:${extractToolArgsPreview((evt.args || {}) as Record<string, unknown>)}`;
+					const cycleResult = detectCycle(callHistory, sig);
+					callHistory.push(sig);
+					if (callHistory.length > 24) callHistory = callHistory.slice(-24);
+
+					if (cycleResult.cycle) {
+						const toolNames = (cycleResult.pattern || []).map((s) => {
+							const colonIdx = s.indexOf(":");
+							return colonIdx >= 0 ? s.slice(0, colonIdx) : s;
+						});
+						const patternStr = toolNames.join("→");
+						if (!progress.error) {
+							progress.error = `Subagent stuck in a tool-call loop: repeating ${patternStr}`;
+						}
+						proc.kill("SIGTERM");
+						clearTimeout(sigkillTimer);
+						sigkillTimer = setTimeout(() => {
+							if (!childClosed) proc.kill("SIGKILL");
+						}, 5000);
+					}
 					fireUpdate();
 				}
 
@@ -589,6 +697,8 @@ async function runSubagent(
 							hit.children = finalChildren as AgentResult[];
 						}
 					}
+					inFlightToolCount = Math.max(0, inFlightToolCount - 1);
+					resumeIdle();
 					fireUpdate();
 				}
 
@@ -655,26 +765,37 @@ async function runSubagent(
 		});
 
 		proc.stderr.on("data", (d: Buffer) => {
+			if (stderrBuf.length >= MAX_STDERR_BYTES) return;
 			stderrBuf += d.toString();
+			if (stderrBuf.length >= MAX_STDERR_BYTES) {
+				stderrBuf = stderrBuf.slice(0, MAX_STDERR_BYTES) + "\n[stderr truncated]";
+			}
 		});
 
 		proc.on("close", (code) => {
+			childClosed = true;
 			if (buf.trim()) processLine(buf);
 			if (code !== 0 && stderrBuf.trim() && !progress.error) {
 				progress.error = stderrBuf.trim();
+			} else if (code === 0 && stderrBuf.trim()) {
+				// Non-fatal: surface stderr (e.g. deprecation warnings) on a successful exit.
+				progress.warning = stderrBuf.trim().slice(0, 2000);
 			}
-			resolve(code ?? 1);
+			safeResolve(code ?? 1);
 		});
 
-		proc.on("error", () => resolve(1));
+		proc.on("error", () => safeResolve(1));
 
+		const abortKill = () => {
+			proc.kill("SIGTERM");
+			clearTimeout(sigkillTimer);
+			sigkillTimer = setTimeout(() => {
+				if (!childClosed) proc.kill("SIGKILL");
+			}, 3000);
+		};
 		if (signal) {
-			const kill = () => {
-				proc.kill("SIGTERM");
-				setTimeout(() => !proc.killed && proc.kill("SIGKILL"), 3000);
-			};
-			if (signal.aborted) kill();
-			else signal.addEventListener("abort", kill, { once: true });
+			if (signal.aborted) abortKill();
+			else signal.addEventListener("abort", abortKill, { once: true });
 		}
 	});
 
@@ -686,6 +807,13 @@ async function runSubagent(
 	result.exitCode = exitCode;
 	progress.status = exitCode === 0 && !progress.error ? "completed" : "failed";
 	progress.durationMs = Date.now() - startTime;
+
+	// Push the terminal status to the live renderer so the TUI doesn't keep
+	// showing "running" after the child has exited. Pass exitCode so callers
+	// that hold a live result object (the subagent tool) can sync its exitCode
+	// and render the correct ✓/✗ icon instead of the -1 placeholder.
+	onUpdate?.(progress, result.usage, exitCode);
+
 	if (progress.error) result.output = result.output || `Error: ${progress.error}`;
 
 	// Truncate output if very large
@@ -896,14 +1024,355 @@ function renderAgentProgress(
 		addLine(theme.fg("error", `Error: ${prog.error}`));
 	}
 
+	if (prog.warning) {
+		addLine(theme.fg("warning", `Warning: ${prog.warning}`));
+	}
+
+	return c;
+}
+
+// ── Pipeline Execution ────────────────────────────────────────────────
+
+async function runPipeline(
+	steps: Array<{ agent: string; task: string; connector?: string }>,
+	cwd: string,
+	signal: AbortSignal | undefined,
+	onUpdate?: (stepIndex: number, progress: AgentProgress, usage: AgentUsage) => void,
+): Promise<PipelineResult> {
+	const results: PipelineStepResult[] = [];
+	let previousOutput = "";
+	let totalUsage = zeroUsage();
+	const startTime = Date.now();
+
+	for (let i = 0; i < steps.length; i++) {
+		if (signal?.aborted) break;
+
+		const step = steps[i];
+		const agent = agents.find((a) => a.name === step.agent);
+		if (!agent) {
+			const errMsg = `Unknown agent: ${step.agent}`;
+			results.push({
+				agent: step.agent, task: step.task, output: `Error: ${errMsg}`,
+				exitCode: 1, usage: zeroUsage(), durationMs: 0,
+			});
+			return {
+				steps: results, finalOutput: previousOutput || "(no output)",
+				stoppedAt: i, error: errMsg,
+				totalUsage, totalDurationMs: Date.now() - startTime,
+			};
+		}
+
+		// Build task with {previous} substitution
+		let taskWithContext = step.task;
+		if (previousOutput && taskWithContext.includes("{previous}")) {
+			// Apply connector formatting if available (step-level overrides agent-level)
+			const connector = step.connector ?? agent.connector;
+			const formattedOutput = formatConnectorContext(previousOutput, connector);
+			taskWithContext = substitutePlaceholders(step.task, formattedOutput);
+		}
+
+		const stepStart = Date.now();
+		const result = await semaphore.run(() =>
+			runSubagent(agent, taskWithContext, cwd, signal, (progress, usage) => {
+				onUpdate?.(i, progress, usage);
+			}),
+		);
+
+		const stepResult: PipelineStepResult = {
+			agent: step.agent, task: step.task, output: result.output,
+			exitCode: result.exitCode, usage: result.usage,
+			durationMs: Date.now() - stepStart,
+		};
+		results.push(stepResult);
+		totalUsage = accumulateUsage(totalUsage, result.usage);
+		previousOutput = result.output;
+
+		// Stop on error — surface the failing step's error as finalOutput (the pipeline
+		// tool returns finalOutput as content, so the main LLM sees the actual failure,
+		// not the previous step's success text).
+		if (result.exitCode !== 0 || result.progress.error) {
+			const errorDetail = buildPipelineErrorContent(i, step.agent, result);
+			return {
+				steps: results, finalOutput: errorDetail,
+				stoppedAt: i, error: result.progress.error || `Agent ${step.agent} exited with code ${result.exitCode}`,
+				totalUsage, totalDurationMs: Date.now() - startTime,
+			};
+		}
+	}
+
+	return {
+		steps: results, finalOutput: previousOutput || "(no output)",
+		totalUsage, totalDurationMs: Date.now() - startTime,
+	};
+}
+
+// ── Loop Execution ─────────────────────────────────────────────────────
+
+async function runLoop(
+	agentName: string,
+	task: string,
+	maxIterations: number,
+	judge: { agent: string; criteria: string } | undefined,
+	cwd: string,
+	signal: AbortSignal | undefined,
+	onUpdate?: (iteration: number, progress: AgentProgress, usage: AgentUsage) => void,
+): Promise<LoopResult> {
+	const agent = agents.find((a) => a.name === agentName);
+	if (!agent) throw new Error(`Unknown agent: ${agentName}`);
+
+	const iterations: LoopIterationResult[] = [];
+	let priorOutputs: string[] = [];
+	let stoppedBecause: LoopResult["stoppedBecause"] = "max_iterations";
+	let totalUsage = zeroUsage();
+	const startTime = Date.now();
+
+	for (let i = 0; i < maxIterations; i++) {
+		if (signal?.aborted) break;
+
+		// Build task with accumulated context
+		let fullTask = task;
+		if (priorOutputs.length > 0) {
+			// Enforce MAX_LOOP_CONTEXT budget: drop oldest iterations first
+			let totalContext = 0;
+			let keptOutputs: string[] = [];
+			for (let j = priorOutputs.length - 1; j >= 0; j--) {
+				const block = `--- Iteration ${j + 1} output ---\n${priorOutputs[j]}`;
+				if (totalContext + block.length <= MAX_LOOP_CONTEXT) {
+					keptOutputs.unshift(block);
+					totalContext += block.length;
+				} else {
+					break;
+				}
+			}
+			const contextBlock = keptOutputs.join("\n\n");
+			fullTask = `${task}\n\n## Prior iterations:\n${contextBlock}`;
+		}
+
+		const iterStart = Date.now();
+		const result = await semaphore.run(() =>
+			runSubagent(agent, fullTask, cwd, signal, (progress, usage) => {
+				onUpdate?.(i, progress, usage);
+			}),
+		);
+
+		const iterResult: LoopIterationResult = {
+			iteration: i + 1, output: result.output,
+			exitCode: result.exitCode, usage: result.usage,
+			durationMs: Date.now() - iterStart,
+		};
+		totalUsage = accumulateUsage(totalUsage, result.usage);
+
+		// Judge evaluation (if configured)
+		if (judge && result.exitCode === 0 && !result.progress.error) {
+			const judgeAgent = agents.find((a) => a.name === judge.agent);
+			if (judgeAgent) {
+				const judgePrompt = `Evaluate this output against the criteria below. Respond with YES if satisfied, or NO with specific feedback.\n\nCriteria: ${judge.criteria}\n\nOutput to evaluate:\n${result.output}`;
+				const judgeResult = await semaphore.run(() =>
+					runSubagent(judgeAgent, judgePrompt, cwd, signal),
+				);
+				totalUsage = accumulateUsage(totalUsage, judgeResult.usage);
+
+				// Parse judge verdict
+				const satisfied = parseJudgeVerdict(judgeResult.output);
+
+				iterResult.judgeVerdict = { satisfied, response: judgeResult.output };
+
+				if (satisfied) {
+					iterations.push(iterResult);
+					stoppedBecause = "judge_satisfied";
+					return {
+						iterations, finalOutput: result.output,
+						stoppedBecause, totalUsage, totalDurationMs: Date.now() - startTime,
+					};
+				}
+			}
+		}
+
+		iterations.push(iterResult);
+		priorOutputs.push(result.output);
+
+		if (result.exitCode !== 0 || result.progress.error) {
+			stoppedBecause = "error";
+			const errorDetail = buildLoopErrorContent(i, agentName, result);
+			return {
+				iterations, finalOutput: errorDetail,
+				stoppedBecause, totalUsage, totalDurationMs: Date.now() - startTime,
+			};
+		}
+	}
+
+	return {
+		iterations, finalOutput: priorOutputs[priorOutputs.length - 1] || "(no output)",
+		stoppedBecause: "max_iterations",
+		totalUsage, totalDurationMs: Date.now() - startTime,
+	};
+}
+
+// ── Pipeline / Loop Rendering ─────────────────────────────────────────
+
+function renderPipelineResult(
+	result: PipelineResult,
+	theme: Theme,
+	expanded: boolean,
+	w: number,
+): Container {
+	const c = new Container();
+
+	// Header
+	c.addChild(new Text(
+		`${theme.fg("toolTitle", theme.bold("pipeline"))} — ${result.steps.length} steps · ${formatDuration(result.totalDurationMs)}`,
+		0, 0,
+	));
+	c.addChild(new Spacer(1));
+
+	// Steps
+	for (let i = 0; i < result.steps.length; i++) {
+		const step = result.steps[i];
+		const icon = step.exitCode === 0
+			? theme.fg("success", "✓")
+			: theme.fg("error", "✗");
+
+		if (!expanded) {
+			const arrow = i < result.steps.length - 1 && result.steps[i].exitCode === 0 && result.stoppedAt === undefined
+				? theme.fg("dim", " → ")
+				: "";
+			c.addChild(new Text(
+				`  ${icon} ${theme.fg("accent", step.agent)}${arrow}`,
+				0, 0,
+			));
+		} else {
+			c.addChild(new Text(
+				`  ${icon} ${theme.fg("accent", step.agent)} — ${formatDuration(step.durationMs)}`,
+				0, 0,
+			));
+			c.addChild(new Text(
+				`    ${theme.fg("dim", "Task:")} ${truncLine(step.task, w - 20)}`,
+				0, 0,
+			));
+			if (step.output) {
+				c.addChild(new Spacer(1));
+				const mdTheme = getMarkdownTheme();
+				c.addChild(new Markdown(step.output, 2, 0, mdTheme));
+			}
+			if (i < result.steps.length - 1 && result.stoppedAt === undefined) {
+				c.addChild(new Text(theme.fg("dim", "  ↓"), 0, 0));
+			}
+		}
+	}
+
+	// Show running indicator if pipeline is still executing
+	if (result.currentStep !== undefined && result.currentStep >= result.steps.length) {
+		if (!expanded) {
+			const hasCompletedSteps = result.steps.length > 0;
+			const lastCompletedOk = hasCompletedSteps && result.steps[result.steps.length - 1].exitCode === 0;
+			const arrow = hasCompletedSteps && lastCompletedOk ? theme.fg("dim", " → ") : "";
+			c.addChild(new Text(
+				`  ${arrow}${theme.fg("warning", "⟳")} ${theme.fg("dim", "running...")}`,
+				0, 0,
+			));
+		}
+	}
+
+	// Error message if pipeline failed
+	if (result.error) {
+		c.addChild(new Spacer(1));
+		c.addChild(new Text(theme.fg("error", `Stopped at step ${(result.stoppedAt ?? 0) + 1}: ${result.error}`), 0, 0));
+	}
+
+	// Usage summary
+	c.addChild(new Spacer(1));
+	const usageParts: string[] = [];
+	if (result.totalUsage.input) usageParts.push(theme.fg("dim", `↑${formatTokens(result.totalUsage.input)}`));
+	if (result.totalUsage.output) usageParts.push(theme.fg("dim", `↓${formatTokens(result.totalUsage.output)}`));
+	if (result.totalUsage.cost) usageParts.push(theme.fg("dim", `$${result.totalUsage.cost.toFixed(3)}`));
+	if (usageParts.length) c.addChild(new Text(usageParts.join(" "), 0, 0));
+
+	return c;
+}
+
+function renderLoopResult(
+	result: LoopResult,
+	theme: Theme,
+	expanded: boolean,
+	w: number,
+): Container {
+	const c = new Container();
+
+	const stoppedLabel = result.stoppedBecause === "judge_satisfied"
+		? theme.fg("success", "judge satisfied")
+		: result.stoppedBecause === "error"
+			? theme.fg("error", "stopped (error)")
+			: theme.fg("dim", `max ${result.iterations.length} iterations`);
+
+	// Header
+	c.addChild(new Text(
+		`${theme.fg("toolTitle", theme.bold("loop"))} — ${result.iterations.length} iterations · ${stoppedLabel} · ${formatDuration(result.totalDurationMs)}`,
+		0, 0,
+	));
+	c.addChild(new Spacer(1));
+
+	// Iterations
+	result.iterations.forEach((iter, idx) => {
+		const icon = iter.exitCode === 0
+			? theme.fg("success", "✓")
+			: theme.fg("error", "✗");
+
+		const verdictStr = iter.judgeVerdict
+			? (iter.judgeVerdict.satisfied
+				? theme.fg("success", " (YES)")
+				: theme.fg("warning", " (NO)"))
+			: "";
+
+		if (!expanded) {
+			const isLast = idx === result.iterations.length - 1;
+			const arrow = isLast ? "" : theme.fg("dim", " → ");
+			c.addChild(new Text(
+				`  ${icon} ${theme.fg("accent", `Iteration ${iter.iteration}`)}${verdictStr}${arrow}`,
+				0, 0,
+			));
+		} else {
+			c.addChild(new Text(
+				`  ${icon} ${theme.fg("accent", `Iteration ${iter.iteration}`)}${verdictStr} — ${formatDuration(iter.durationMs)}`,
+				0, 0,
+			));
+			if (iter.output) {
+				const mdTheme = getMarkdownTheme();
+				c.addChild(new Markdown(iter.output, 2, 0, mdTheme));
+			}
+			if (iter.judgeVerdict && !iter.judgeVerdict.satisfied) {
+				c.addChild(new Text(theme.fg("dim", "  ↓ refine"), 0, 0));
+			}
+		}
+	});
+
+	// Show running indicator if loop is still executing
+	if (result.currentIteration !== undefined && result.currentIteration >= result.iterations.length) {
+		if (!expanded) {
+			const hasCompleted = result.iterations.length > 0;
+			const arrow = hasCompleted ? theme.fg("dim", " → ") : "";
+			c.addChild(new Text(
+				`  ${arrow}${theme.fg("warning", "⟳")} ${theme.fg("dim", "refining...")}`,
+				0, 0,
+			));
+		}
+	}
+
+	// Usage summary
+	c.addChild(new Spacer(1));
+	const usageParts: string[] = [];
+	if (result.totalUsage.input) usageParts.push(theme.fg("dim", `↑${formatTokens(result.totalUsage.input)}`));
+	if (result.totalUsage.output) usageParts.push(theme.fg("dim", `↓${formatTokens(result.totalUsage.output)}`));
+	if (result.totalUsage.cost) usageParts.push(theme.fg("dim", `$${result.totalUsage.cost.toFixed(3)}`));
+	if (usageParts.length) c.addChild(new Text(usageParts.join(" "), 0, 0));
+
 	return c;
 }
 
 // ── Extension ─────────────────────────────────────────────────────────
 
 export default function (pi: ExtensionAPI) {
-	const config = loadConfig();
-	const semaphore = new Semaphore(config.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY);
+	extensionConfig = loadConfig();
+	semaphore = new Semaphore(extensionConfig.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY);
 	agents = loadAgents();
 
 	// If spawned as a child by a parent subagent process, PI_SUBAGENT_ALLOWED
@@ -925,6 +1394,7 @@ export default function (pi: ExtensionAPI) {
 			"Use subagent to delegate *reasoning and decisions*: codebase exploration (scout), web research (researcher), or isolated code changes (worker)",
 			"For multiple independent subagent tasks, emit multiple `subagent` tool calls in the same turn — they run in parallel automatically.",
 			"Subagents have NO context from the current conversation — include ALL necessary context in the task description",
+			"When a subagent returns an error, read it carefully. For transient failures (timeout, API/network), retry once with the same task plus 'Previous attempt failed with: {error}'. For structural failures (wrong approach, missing context), simplify the task or switch agents. If it persists after retry, report to the user with the specific error.",
 		],
 		parameters: Type.Object({
 			agent: Type.String({ description: "Name of the agent to invoke" }),
@@ -959,9 +1429,10 @@ export default function (pi: ExtensionAPI) {
 			};
 
 			const result = await semaphore.run(() =>
-				runSubagent(agent, params.task!, params.cwd ?? cwd, signal, (progress, usage) => {
+				runSubagent(agent, params.task!, params.cwd ?? cwd, signal, (progress, usage, finalExitCode) => {
 					liveResult.progress = progress;
 					liveResult.usage = { ...usage };
+					if (finalExitCode !== undefined) liveResult.exitCode = finalExitCode;
 					onUpdate?.({
 						content: [{ type: "text", text: "(running...)" }],
 						details: { results: [liveResult] },
@@ -971,8 +1442,11 @@ export default function (pi: ExtensionAPI) {
 
 			result.contextWindow = contextWindow;
 			const isError = result.exitCode !== 0 || !!result.progress.error;
+			const contentText = isError
+				? buildSubagentErrorContent(result)
+				: (result.output || "(no output)");
 			return {
-				content: [{ type: "text", text: result.output || "(no output)" }],
+				content: [{ type: "text", text: contentText }],
 				details: { results: [result] },
 				...(isError ? { isError: true } : {}),
 			};
@@ -1022,7 +1496,7 @@ export default function (pi: ExtensionAPI) {
 		// ── Render: result ──
 		renderResult(result, options, theme, context) {
 			const details = result.details as Details | undefined;
-			if (!details?.results?.length) {
+			if (!details) {
 				const t = result.content[0];
 				const text = t?.type === "text" ? t.text : "(no output)";
 				return new Text(text.slice(0, 200), 0, 0);
@@ -1030,8 +1504,264 @@ export default function (pi: ExtensionAPI) {
 
 			const w = getTermWidth() - 4;
 			const expanded = options.expanded;
-			const c = new Container();
-			c.addChild(renderAgentProgress(details.results[0], theme, expanded, w));
+
+			// Pipeline result
+			if (details.pipelineResult) {
+				return renderPipelineResult(details.pipelineResult, theme, expanded, w);
+			}
+
+			// Loop result
+			if (details.loopResult) {
+				return renderLoopResult(details.loopResult, theme, expanded, w);
+			}
+
+			// Single agent result (existing behavior)
+			if (details.results?.length) {
+				const c = new Container();
+				c.addChild(renderAgentProgress(details.results[0], theme, expanded, w));
+				return c;
+			}
+
+			// Fallback
+			const t = result.content[0];
+			const text = t?.type === "text" ? t.text : "(no output)";
+			return new Text(text.slice(0, 200), 0, 0);
+		},
+	});
+
+	// ── Pipeline Tool ────────────────────────────────────────────────────
+
+	pi.registerTool({
+		name: "pipeline",
+		label: "Pipeline",
+		description:
+			"Run 2–5 agents in sequence. Each agent's output feeds as {previous} context into the next agent's task. Use for multi-stage workflows like scout → planner → worker.",
+		promptSnippet: "Run sequential multi-agent pipelines",
+		promptGuidelines: [
+			"Use pipeline when a task naturally decomposes into sequential agent roles (e.g. explore → plan → implement → review).",
+			"Each step receives the previous step's output automatically via {previous} placeholder substitution.",
+			"Pipelines stop on first error. The finalOutput is the failing step's error detail.",
+			"When a pipeline fails at a step, the error identifies which step and why. Retry the failing step with a simpler task, or re-scope the pipeline. Early-step (exploration) failures → retry the whole pipeline with a more focused scope.",
+		],
+		parameters: Type.Object({
+			steps: Type.Array(
+				Type.Object({
+					agent: Type.String({ description: "Agent name for this step" }),
+					task: Type.String({ description: "Task description. Use {previous} to reference the prior step's output." }),
+					connector: Type.Optional(Type.String({ description: "Override agent's default connector template for this step. Format: \"## Header\\n\\n{output}\"" })),
+				}),
+				{ minItems: 2, maxItems: 5, description: "Sequential steps (2–5). Each step's agent output feeds into the next step's task via {previous}." },
+			),
+			cwd: Type.Optional(Type.String({ description: "Working directory for all agent processes" })),
+		}),
+
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			const cwd = params.cwd ?? ctx.cwd;
+
+			if (!params.steps || params.steps.length < 2) {
+				throw new Error("pipeline requires at least 2 steps");
+			}
+
+			// Validate all agents exist
+			const agentNames = params.steps.map((s: { agent: string }) => s.agent);
+			const missing = validateAgents(agentNames, agents);
+			if (missing) {
+				const available = agents.map((a) => a.name).join(", ") || "none";
+				throw new Error(`Unknown agent in pipeline: ${missing}. Available agents: ${available}`);
+			}
+
+			const liveResult: Details = {
+				pipelineResult: {
+					steps: [],
+					currentStep: 0,
+					finalOutput: "",
+					totalUsage: zeroUsage(),
+					totalDurationMs: 0,
+				},
+			};
+
+			const result = await runPipeline(
+				params.steps,
+				cwd,
+				signal,
+				(stepIndex, progress, usage) => {
+					const pResult = liveResult.pipelineResult!;
+					pResult.currentStep = stepIndex;
+					// Update live result with latest step progress
+					if (progress.status === "running") {
+						// Ensure step slot exists for live rendering
+						if (stepIndex === pResult.steps.length) {
+							pResult.steps.push({
+								agent: params.steps[stepIndex].agent,
+								task: params.steps[stepIndex].task,
+								output: "",
+								exitCode: -1, // sentinel: not yet done
+								usage,
+								durationMs: progress.durationMs,
+							});
+						}
+					}
+					if (progress.status === "completed" || progress.status === "failed") {
+						const stepResult: PipelineStepResult = {
+							agent: params.steps[stepIndex].agent,
+							task: params.steps[stepIndex].task,
+							output: progress.lastMessage || "",
+							exitCode: progress.status === "failed" ? 1 : 0,
+							usage,
+							durationMs: progress.durationMs,
+						};
+						// Replace placeholder or push
+						while (pResult.steps.length <= stepIndex) {
+							pResult.steps.push({...stepResult, output: "", exitCode: -1, usage: zeroUsage()});
+						}
+						pResult.steps[stepIndex] = stepResult;
+					}
+				onUpdate?.({
+					content: [{ type: "text", text: `Pipeline: step ${stepIndex + 1}/${params.steps.length}` }],
+					details: liveResult,
+				});
+			},
+		);
+
+			const isError = result.stoppedAt !== undefined;
+			return {
+				content: [{ type: "text", text: result.finalOutput || "(no output)" }],
+				details: { pipelineResult: result },
+				...(isError ? { isError: true } : {}),
+			};
+		},
+
+		renderCall(args, theme, context) {
+			if (!context.expanded) {
+				if (!args.steps) {
+					return new Text(theme.fg("toolTitle", theme.bold("pipeline")), 0, 0);
+				}
+				const stepNames = args.steps.map((s: { agent?: string }) => s?.agent || "?").join(" → ");
+				return new Text(
+					`${theme.fg("toolTitle", theme.bold("pipeline"))} ${theme.fg("accent", stepNames)}`,
+					0, 0,
+				);
+			}
+
+			const c = context.lastComponent instanceof Container
+				? (context.lastComponent.clear(), context.lastComponent)
+				: new Container();
+			const stepCount = args.steps?.length || 0;
+			c.addChild(new Text(`${theme.fg("toolTitle", theme.bold("pipeline"))} — ${stepCount} steps`, 0, 0));
+			if (args.steps) {
+				c.addChild(new Spacer(1));
+				for (let i = 0; i < args.steps.length; i++) {
+					const step = args.steps[i];
+					const agentLabel = step.agent ? theme.fg("accent", step.agent) : "?";
+					const taskPreview = step.task ? truncLine(step.task, 60) : "";
+					c.addChild(new Text(`  ${theme.fg("dim", `${i + 1}.`)} ${agentLabel} ${theme.fg("dim", taskPreview)}`, 0, 0));
+				}
+			}
+			return c;
+		},
+	});
+
+	// ── Loop Tool ─────────────────────────────────────────────────────────
+
+	pi.registerTool({
+		name: "loop",
+		label: "Loop",
+		description:
+			"Run the same agent 2–5 times, passing prior iteration outputs as context. Optionally use a judge agent to evaluate quality and stop early.",
+		promptSnippet: "Run iterative refinement loops with optional judge",
+		promptGuidelines: [
+			"Use loop for tasks that benefit from iterative refinement (e.g. drafting → reviewing → polishing).",
+			"Configure a judge agent to stop early when quality is sufficient, avoiding wasted iterations.",
+			"Each iteration receives all prior outputs as context, enabling progressive improvement.",
+			"When a loop iteration fails, the error shows which iteration. Reduce max_iterations or simplify the task; if the judge consistently rejects, refine the criteria or switch judge agent.",
+		],
+		parameters: Type.Object({
+			agent: Type.String({ description: "Agent name to run in the loop" }),
+			task: Type.String({ description: "Task description for each iteration" }),
+			max_iterations: Type.Optional(Type.Number({ minimum: 2, maximum: 5, default: 3, description: "Maximum number of iterations (2–5, default 3)" })),
+			judge: Type.Optional(Type.Object({
+				agent: Type.String({ description: "Judge agent name" }),
+				criteria: Type.String({ description: "Quality criteria. Judge responds YES if satisfied, NO otherwise." }),
+			}, { description: "Optional judge agent to evaluate each iteration and stop early when quality is sufficient" })),
+			cwd: Type.Optional(Type.String({ description: "Working directory for agent processes" })),
+		}),
+
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			const cwd = params.cwd ?? ctx.cwd;
+			const maxIterations = params.max_iterations ?? 3;
+
+			// Validate agent exists
+			const agentNames = [params.agent];
+			if (params.judge) agentNames.push(params.judge.agent);
+			const missing = validateAgents(agentNames, agents);
+			if (missing) {
+				const available = agents.map((a) => a.name).join(", ") || "none";
+				throw new Error(`Unknown agent in loop: ${missing}. Available agents: ${available}`);
+			}
+
+			const liveResult: Details = {
+				loopResult: {
+					iterations: [],
+					currentIteration: 0,
+					finalOutput: "",
+					stoppedBecause: "max_iterations",
+					totalUsage: zeroUsage(),
+					totalDurationMs: 0,
+				},
+			};
+
+			const result = await runLoop(
+				params.agent,
+				params.task,
+				maxIterations,
+				params.judge,
+				cwd,
+				signal,
+				(iteration, progress, usage) => {
+					const lResult = liveResult.loopResult!;
+					lResult.currentIteration = iteration;
+					onUpdate?.({
+						content: [{ type: "text", text: `Loop: iteration ${iteration + 1}/${maxIterations}` }],
+						details: liveResult,
+					});
+				},
+			);
+
+			const isError = result.stoppedBecause === "error";
+			return {
+				content: [{ type: "text", text: result.finalOutput || "(no output)" }],
+				details: { loopResult: result },
+				...(isError ? { isError: true } : {}),
+			};
+		},
+
+		renderCall(args, theme, context) {
+			if (!context.expanded) {
+				if (!args.agent) {
+					return new Text(theme.fg("toolTitle", theme.bold("loop")), 0, 0);
+				}
+				const maxIter = args.max_iterations || 3;
+				const judgeStr = args.judge ? ` (judge: ${theme.fg("accent", (args.judge as { agent?: string }).agent || "?")})` : "";
+				return new Text(
+					`${theme.fg("toolTitle", theme.bold("loop"))} ${theme.fg("accent", args.agent)} × ${maxIter}${judgeStr}`,
+					0, 0,
+				);
+			}
+
+			const c = context.lastComponent instanceof Container
+				? (context.lastComponent.clear(), context.lastComponent)
+				: new Container();
+			const maxIter = args.max_iterations || 3;
+			c.addChild(new Text(`${theme.fg("toolTitle", theme.bold("loop"))} ${theme.fg("accent", args.agent || "?")} × ${maxIter}`, 0, 0));
+			if (args.task) {
+				c.addChild(new Spacer(1));
+				c.addChild(new Text(theme.fg("text", args.task), 0, 0));
+			}
+			if (args.judge) {
+				const j = args.judge as { agent?: string; criteria?: string };
+				c.addChild(new Spacer(1));
+				c.addChild(new Text(`${theme.fg("dim", "Judge:")} ${theme.fg("accent", j.agent || "?")} — ${theme.fg("dim", j.criteria || "")}`, 0, 0));
+			}
 			return c;
 		},
 	});