@narumitw/pi-subagents 0.13.0 → 0.14.0

package/src/subagents.ts

@@ -12,808 +12,16 @@
  * Uses JSON mode to capture structured output from subagents.
  */
 
-import { spawn } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { Message } from "@earendil-works/pi-ai";
-import { StringEnum } from "@earendil-works/pi-ai";
-import {
-	type ExtensionAPI,
-	getAgentDir,
-	getMarkdownTheme,
-	withFileMutationQueue,
-	DynamicBorder,
-} from "@earendil-works/pi-coding-agent";
-import {
-	Container,
-	Markdown,
-	Spacer,
-	Text,
-	type SelectItem,
-	SelectList,
-	Key,
-	matchesKey,
-	truncateToWidth,
-} from "@earendil-works/pi-tui";
-import { Type } from "typebox";
-import {
-	THINKING_LEVELS,
-	type AgentConfig,
-	type AgentScope,
-	type AgentSource,
-	type SubagentAgentConfig,
-	type SubagentSettings,
-	type SubagentThinkingLevel,
-	discoverAgents,
-	isThinkingLevel,
-} from "./agents.js";
-
-const MAX_PARALLEL_TASKS = 8;
-const MAX_CONCURRENCY = 4;
-const COLLAPSED_ITEM_COUNT = 10;
-const DEFAULT_TIMEOUT_MS = parsePositiveInteger(process.env.PI_SUBAGENT_TIMEOUT_MS) ?? 10 * 60 * 1000;
-const KILL_GRACE_MS = 5000;
-const STATUS_KEY = "subagents";
-const activeStatuses = new Map<string, string>();
-
-export function parsePositiveInteger(value: string | undefined): number | undefined {
-	if (!value) return undefined;
-	const parsed = Number.parseInt(value, 10);
-	return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
-}
-
-interface StatusContext {
-	ui: { setStatus: (key: string, value: string | undefined) => void };
-}
-
-function startSubagentStatus(ctx: StatusContext, toolCallId: string, status: string) {
-	let cleared = false;
-
-	const update = (nextStatus: string) => {
-		if (cleared) return;
-		activeStatuses.set(toolCallId, nextStatus);
-		publishSubagentStatus(ctx);
-	};
-
-	update(status);
-
-	return {
-		update,
-		clear() {
-			if (cleared) return;
-			cleared = true;
-			activeStatuses.delete(toolCallId);
-			publishSubagentStatus(ctx);
-		},
-	};
-}
-
-function publishSubagentStatus(ctx: StatusContext) {
-	const statuses = [...activeStatuses.values()];
-	if (statuses.length === 0) {
-		ctx.ui.setStatus(STATUS_KEY, undefined);
-		return;
-	}
-
-	const suffix = statuses.length > 1 ? ` +${statuses.length - 1}` : "";
-	ctx.ui.setStatus(STATUS_KEY, `${statuses[0]}${suffix}`);
-}
-
-function singleStatus(agent: string): string {
-	return `${agent}`;
-}
-
-function chainStatus(step: number, total: number, agent?: string): string {
-	return `chain ${step}/${total}${agent ? ` ${agent}` : ""}`;
-}
-
-function parallelStatus(done: number, total: number, running: number): string {
-	return `parallel ${done}/${total} done${running > 0 ? ` ${running} running` : ""}`;
-}
-
-function fanInStatus(agent: string): string {
-	return `fan-in ${agent}`;
-}
-
-export function formatTokens(count: number): string {
-	if (count < 1000) return count.toString();
-	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
-	if (count < 1000000) return `${Math.round(count / 1000)}k`;
-	return `${(count / 1000000).toFixed(1)}M`;
-}
-
-export function formatUsageStats(
-	usage: {
-		input: number;
-		output: number;
-		cacheRead: number;
-		cacheWrite: number;
-		cost: number;
-		contextTokens?: number;
-		turns?: number;
-	},
-	model?: string,
-	thinkingLevel?: SubagentThinkingLevel,
-): string {
-	const parts: string[] = [];
-	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
-	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.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
-	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
-	if (usage.contextTokens && usage.contextTokens > 0) {
-		parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
-	}
-	if (model) parts.push(model);
-	if (thinkingLevel) parts.push(`thinking:${thinkingLevel}`);
-	return parts.join(" ");
-}
-
-function formatToolCall(
-	toolName: string,
-	args: Record<string, unknown>,
-	themeFg: (color: any, 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 = (args.command as string) || "...";
-			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 filePath = shortenPath(rawPath);
-			const offset = args.offset as number | undefined;
-			const limit = args.limit as number | undefined;
-			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 = (args.file_path || args.path || "...") as string;
-			const filePath = shortenPath(rawPath);
-			const content = (args.content || "") as string;
-			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 = (args.file_path || args.path || "...") as string;
-			return themeFg("muted", "edit ") + themeFg("accent", shortenPath(rawPath));
-		}
-		case "ls": {
-			const rawPath = (args.path || ".") as string;
-			return themeFg("muted", "ls ") + themeFg("accent", shortenPath(rawPath));
-		}
-		case "find": {
-			const pattern = (args.pattern || "*") as string;
-			const rawPath = (args.path || ".") as string;
-			return themeFg("muted", "find ") + themeFg("accent", pattern) + themeFg("dim", ` in ${shortenPath(rawPath)}`);
-		}
-		case "grep": {
-			const pattern = (args.pattern || "") as string;
-			const rawPath = (args.path || ".") as string;
-			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}`);
-		}
-	}
-}
-
-interface UsageStats {
-	input: number;
-	output: number;
-	cacheRead: number;
-	cacheWrite: number;
-	cost: number;
-	contextTokens: number;
-	turns: number;
-}
-
-interface SingleResult {
-	agent: string;
-	agentSource: AgentSource | "unknown";
-	task: string;
-	exitCode: number;
-	messages: Message[];
-	stderr: string;
-	usage: UsageStats;
-	model?: string;
-	thinkingLevel?: SubagentThinkingLevel;
-	stopReason?: string;
-	errorMessage?: string;
-	step?: number;
-	finalOutput?: string;
-	timedOut?: boolean;
-	timeoutMs?: number;
-}
-
-interface SubagentDetails {
-	mode: "single" | "parallel" | "chain";
-	agentScope: AgentScope;
-	projectAgentsDir: string | null;
-	results: SingleResult[];
-	aggregator?: SingleResult;
-}
-
-function getFinalOutput(messages: Message[]): string {
-	for (let i = messages.length - 1; i >= 0; i--) {
-		const msg = messages[i];
-		if (msg.role === "assistant") {
-			for (const part of msg.content) {
-				if (part.type === "text") return part.text;
-			}
-		}
-	}
-	return "";
-}
-
-function getResultFinalOutput(result: SingleResult): string {
-	return result.finalOutput ?? getFinalOutput(result.messages);
-}
-
-function buildFanInContext(results: SingleResult[]): string {
-	return results
-		.map((result, index) => {
-			const status = result.exitCode === 0 ? "completed" : result.exitCode === -1 ? "running" : "failed";
-			const output = getResultFinalOutput(result);
-			const error = result.errorMessage || result.stderr.trim();
-			return [
-				`## Result ${index + 1}: ${result.agent} (${status})`,
-				`Task: ${result.task}`,
-				output ? `Output:\n${output}` : error ? `Error:\n${error}` : "Output: (no output)",
-			].join("\n\n");
-		})
-		.join("\n\n---\n\n");
-}
-
-type DisplayItem = { type: "text"; text: string } | { type: "toolCall"; name: string; args: Record<string, any> };
-
-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") items.push({ type: "text", text: part.text });
-				else if (part.type === "toolCall") items.push({ type: "toolCall", name: part.name, args: part.arguments });
-			}
-		}
-	}
-	return items;
-}
-
-async function mapWithConcurrencyLimit<TIn, TOut>(
-	items: TIn[],
-	concurrency: number,
-	fn: (item: TIn, index: number) => Promise<TOut>,
-): Promise<TOut[]> {
-	if (items.length === 0) return [];
-	const limit = Math.max(1, Math.min(concurrency, items.length));
-	const results: TOut[] = new Array(items.length);
-	let nextIndex = 0;
-	const workers = new Array(limit).fill(null).map(async () => {
-		while (true) {
-			const current = nextIndex++;
-			if (current >= items.length) return;
-			results[current] = await fn(items[current], current);
-		}
-	});
-	await Promise.all(workers);
-	return results;
-}
-
-async function writePromptToTempFile(agentName: string, prompt: string): Promise<{ dir: string; filePath: string }> {
-	const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
-	const safeName = agentName.replace(/[^\w.-]+/g, "_");
-	const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
-	await withFileMutationQueue(filePath, async () => {
-		await fs.promises.writeFile(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
-	});
-	return { dir: tmpDir, filePath };
-}
-
-export function buildPiArgs(options: {
-	model?: string;
-	thinkingLevel?: SubagentThinkingLevel;
-	tools?: string[];
-	systemPromptPath?: string;
-	task: string;
-}): string[] {
-	const args: string[] = ["--mode", "json", "-p", "--no-session"];
-	if (options.model) args.push("--model", options.model);
-	if (options.thinkingLevel) args.push("--thinking", options.thinkingLevel);
-	if (Array.isArray(options.tools)) {
-		if (options.tools.length > 0) args.push("--tools", options.tools.join(","));
-		else args.push("--no-tools");
-	}
-	if (options.systemPromptPath) args.push("--append-system-prompt", options.systemPromptPath);
-	args.push(`Task: ${options.task}`);
-	return args;
-}
-
-function getPiInvocation(args: string[]): { command: string; args: string[] } {
-	const currentScript = process.argv[1];
-	const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
-	if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
-		return { command: process.execPath, args: [currentScript, ...args] };
-	}
-
-	const execName = path.basename(process.execPath).toLowerCase();
-	const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
-	if (!isGenericRuntime) {
-		return { command: process.execPath, args };
-	}
-
-	return { command: "pi", args };
-}
-
-function terminateProcess(proc: ReturnType<typeof spawn>) {
-	if (proc.killed) return;
-	if (process.platform !== "win32" && proc.pid) {
-		try {
-			process.kill(-proc.pid, "SIGTERM");
-		} catch {
-			proc.kill("SIGTERM");
-		}
-	} else {
-		proc.kill("SIGTERM");
-	}
-
-	setTimeout(() => {
-		if (proc.killed) return;
-		if (process.platform !== "win32" && proc.pid) {
-			try {
-				process.kill(-proc.pid, "SIGKILL");
-			} catch {
-				proc.kill("SIGKILL");
-			}
-		} else {
-			proc.kill("SIGKILL");
-		}
-	}, KILL_GRACE_MS).unref();
-}
-
-type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
-
-async function runSingleAgent(
-	defaultCwd: string,
-	agents: AgentConfig[],
-	agentName: string,
-	task: string,
-	cwd: string | undefined,
-	step: number | undefined,
-	signal: AbortSignal | undefined,
-	thinkingLevel: SubagentThinkingLevel | undefined,
-	timeoutMs: number,
-	onUpdate: OnUpdateCallback | undefined,
-	makeDetails: (results: SingleResult[]) => SubagentDetails,
-): Promise<SingleResult> {
-	const agent = agents.find((a) => a.name === agentName);
-
-	if (!agent) {
-		const available = agents.map((a) => `"${a.name}"`).join(", ") || "none";
-		return {
-			agent: agentName,
-			agentSource: "unknown",
-			task,
-			exitCode: 1,
-			messages: [],
-			stderr: `Unknown agent: "${agentName}". Available agents: ${available}.`,
-			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-			thinkingLevel,
-			step,
-			finalOutput: "",
-		};
-	}
-
-	let tmpPromptDir: string | null = null;
-	let tmpPromptPath: string | null = null;
-
-	const currentResult: SingleResult = {
-		agent: agentName,
-		agentSource: agent.source,
-		task,
-		exitCode: 0,
-		messages: [],
-		stderr: "",
-		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-		model: agent.model ?? undefined,
-		thinkingLevel,
-		step,
-		timeoutMs,
-	};
-
-	const emitUpdate = () => {
-		currentResult.finalOutput = getFinalOutput(currentResult.messages);
-		if (onUpdate) {
-			onUpdate({
-				content: [{ type: "text", text: currentResult.finalOutput || "(running...)" }],
-				details: makeDetails([currentResult]),
-			});
-		}
-	};
-
-	try {
-		if (agent.systemPrompt.trim()) {
-			const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt);
-			tmpPromptDir = tmp.dir;
-			tmpPromptPath = tmp.filePath;
-		}
-
-		const args = buildPiArgs({
-			model: agent.model,
-			thinkingLevel,
-			tools: agent.tools,
-			systemPromptPath: tmpPromptPath ?? undefined,
-			task,
-		});
-		let wasAborted = false;
-		let timedOut = false;
-
-		const exitCode = await new Promise<number>((resolve) => {
-			const invocation = getPiInvocation(args);
-			let settled = false;
-			const finish = (code: number) => {
-				if (settled) return;
-				settled = true;
-				clearTimeout(timeout);
-				resolve(code);
-			};
-			const proc = spawn(invocation.command, invocation.args, {
-				cwd: cwd ?? defaultCwd,
-				detached: process.platform !== "win32",
-				shell: false,
-				stdio: ["ignore", "pipe", "pipe"],
-			});
-			let buffer = "";
-			const timeout = setTimeout(() => {
-				timedOut = true;
-				currentResult.timedOut = true;
-				currentResult.stopReason = "timeout";
-				currentResult.errorMessage = `Subagent timed out after ${timeoutMs}ms`;
-				currentResult.stderr += `${currentResult.stderr ? "\n" : ""}Subagent timed out after ${timeoutMs}ms.`;
-				emitUpdate();
-				terminateProcess(proc);
-			}, timeoutMs);
-			timeout.unref();
-
-			const processLine = (line: string) => {
-				if (!line.trim()) return;
-				let event: any;
-				try {
-					event = JSON.parse(line);
-				} catch {
-					return;
-				}
-
-				if (event.type === "message_end" && event.message) {
-					const msg = event.message as Message;
-					currentResult.messages.push(msg);
-
-					if (msg.role === "assistant") {
-						currentResult.usage.turns++;
-						const usage = msg.usage;
-						if (usage) {
-							currentResult.usage.input += usage.input || 0;
-							currentResult.usage.output += usage.output || 0;
-							currentResult.usage.cacheRead += usage.cacheRead || 0;
-							currentResult.usage.cacheWrite += usage.cacheWrite || 0;
-							currentResult.usage.cost += usage.cost?.total || 0;
-							currentResult.usage.contextTokens = usage.totalTokens || 0;
-						}
-						if (!currentResult.model && msg.model) currentResult.model = msg.model;
-						if (msg.stopReason) currentResult.stopReason = msg.stopReason;
-						if (msg.errorMessage) currentResult.errorMessage = msg.errorMessage;
-					}
-					emitUpdate();
-				}
-
-				if (event.type === "tool_result_end" && event.message) {
-					currentResult.messages.push(event.message as Message);
-					emitUpdate();
-				}
-			};
-
-			proc.stdout.on("data", (data) => {
-				buffer += data.toString();
-				const lines = buffer.split("\n");
-				buffer = lines.pop() || "";
-				for (const line of lines) processLine(line);
-			});
-
-			proc.stderr.on("data", (data) => {
-				currentResult.stderr += data.toString();
-			});
-
-			proc.on("close", (code) => {
-				if (buffer.trim()) processLine(buffer);
-				finish(timedOut ? 124 : (code ?? 0));
-			});
-
-			proc.on("error", (error) => {
-				currentResult.errorMessage = error.message;
-				currentResult.stderr += `${currentResult.stderr ? "\n" : ""}${error.message}`;
-				finish(1);
-			});
-
-			if (signal) {
-				const killProc = () => {
-					wasAborted = true;
-					currentResult.stopReason = "aborted";
-					currentResult.errorMessage = "Subagent was aborted";
-					terminateProcess(proc);
-				};
-				if (signal.aborted) killProc();
-				else signal.addEventListener("abort", killProc, { once: true });
-			}
-		});
-
-		currentResult.exitCode = exitCode;
-		currentResult.finalOutput = getFinalOutput(currentResult.messages);
-		if (wasAborted && !timedOut) throw new Error("Subagent was aborted");
-		return currentResult;
-	} finally {
-		if (tmpPromptPath)
-			try {
-				fs.unlinkSync(tmpPromptPath);
-			} catch {
-				/* ignore */
-			}
-		if (tmpPromptDir)
-			try {
-				fs.rmdirSync(tmpPromptDir);
-			} catch {
-				/* ignore */
-			}
-	}
-}
-
-const TimeoutMs = Type.Number({
-	description:
-		"Hard timeout in milliseconds for each subagent subprocess. Defaults to PI_SUBAGENT_TIMEOUT_MS or 600000.",
-	minimum: 1,
-});
-
-const ThinkingLevelSchema = StringEnum(THINKING_LEVELS, {
-	description: "Pi thinking level for the subagent process: off, minimal, low, medium, high, or xhigh.",
-});
-
-const TaskItem = Type.Object({
-	agent: Type.String({ description: "Name of the agent to invoke" }),
-	task: Type.String({ description: "Task to delegate to the agent" }),
-	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
-	timeoutMs: Type.Optional(TimeoutMs),
-	thinkingLevel: Type.Optional(ThinkingLevelSchema),
-});
-
-const ChainItem = Type.Object({
-	agent: Type.String({ description: "Name of the agent to invoke" }),
-	task: Type.String({ description: "Task with optional {previous} placeholder for prior output" }),
-	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
-	timeoutMs: Type.Optional(TimeoutMs),
-	thinkingLevel: Type.Optional(ThinkingLevelSchema),
-});
-
-const AggregatorItem = Type.Object({
-	agent: Type.String({ description: "Name of the fan-in agent to invoke after parallel tasks complete" }),
-	task: Type.String({ description: "Fan-in task. Use {previous} to include all parallel outputs." }),
-	cwd: Type.Optional(Type.String({ description: "Working directory for the aggregator process" })),
-	timeoutMs: Type.Optional(TimeoutMs),
-	thinkingLevel: Type.Optional(ThinkingLevelSchema),
-});
-
-const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
-	description: 'Which agent directories to use. Default: "user". Use "both" to include project-local agents.',
-	default: "user",
-});
-
-const SubagentParams = Type.Object({
-	agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (for single mode)" })),
-	task: Type.Optional(Type.String({ description: "Task to delegate (for single mode)" })),
-	tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
-	chain: Type.Optional(Type.Array(ChainItem, { description: "Array of {agent, task} for sequential execution" })),
-	aggregator: Type.Optional(AggregatorItem),
-	agentScope: Type.Optional(AgentScopeSchema),
-	confirmProjectAgents: Type.Optional(
-		Type.Boolean({ description: "Prompt before running project-local agents. Default: true.", default: true }),
-	),
-	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
-	timeoutMs: Type.Optional(TimeoutMs),
-	thinkingLevel: Type.Optional(ThinkingLevelSchema),
-});
-
-// ---- Settings helpers ----
-
-function hasOwn(obj: object, key: PropertyKey): boolean {
-	return Object.hasOwn(obj, key);
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isStringArray(value: unknown): value is string[] {
-	return Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-
-function isPositiveNumber(value: unknown): value is number {
-	return typeof value === "number" && Number.isFinite(value) && value >= 1;
-}
-
-export function normalizeAgentSettings(value: unknown): SubagentAgentConfig | undefined {
-	if (!isPlainObject(value)) return undefined;
-
-	const config: SubagentAgentConfig = {};
-	let hasKnownField = false;
-
-	if (hasOwn(value, "tools")) {
-		if (!isStringArray(value.tools)) return undefined;
-		config.tools = value.tools;
-		hasKnownField = true;
-	}
-
-	if (hasOwn(value, "model")) {
-		if (value.model !== null && typeof value.model !== "string") return undefined;
-		config.model = value.model;
-		hasKnownField = true;
-	}
-
-	if (hasOwn(value, "thinkingLevel")) {
-		if (value.thinkingLevel !== null && !isThinkingLevel(value.thinkingLevel)) return undefined;
-		config.thinkingLevel = value.thinkingLevel;
-		hasKnownField = true;
-	}
-
-	if (hasOwn(value, "timeoutMs")) {
-		if (value.timeoutMs !== null && !isPositiveNumber(value.timeoutMs)) return undefined;
-		config.timeoutMs = value.timeoutMs;
-		hasKnownField = true;
-	}
-
-	return hasKnownField ? config : undefined;
-}
-
-export function normalizeSubagentSettings(value: unknown): SubagentSettings | undefined {
-	if (!isPlainObject(value)) return undefined;
-	if (!hasOwn(value, "agents")) return {};
-	if (!isPlainObject(value.agents)) return undefined;
-
-	const agents: Record<string, SubagentAgentConfig> = {};
-	for (const [name, rawConfig] of Object.entries(value.agents)) {
-		const config = normalizeAgentSettings(rawConfig);
-		if (config) agents[name] = config;
-	}
-
-	return Object.keys(agents).length > 0 ? { agents } : {};
-}
-
-function readSubagentSettings(): SubagentSettings | undefined {
-	const configPath = path.join(getAgentDir(), "pi-subagents-config.json");
-	if (!fs.existsSync(configPath)) return undefined;
-	try {
-		return normalizeSubagentSettings(JSON.parse(fs.readFileSync(configPath, "utf-8")));
-	} catch {
-		return undefined;
-	}
-}
-
-function saveSubagentConfig(settings: SubagentSettings): void {
-	const agentDir = getAgentDir();
-	fs.mkdirSync(agentDir, { recursive: true });
-
-	const configPath = path.join(agentDir, "pi-subagents-config.json");
-	fs.writeFileSync(configPath, `${JSON.stringify(settings, null, "\t")}\n`, "utf-8");
-}
-
-export function uniqueToolNames(tools: string[]): string[] {
-	return [...new Set(tools)];
-}
-
-export function sameToolSet(left: string[], right: string[]): boolean {
-	const leftSet = new Set(left);
-	const rightSet = new Set(right);
-	if (leftSet.size !== rightSet.size) return false;
-	return [...leftSet].every((tool) => rightSet.has(tool));
-}
-
-export function resolveSubagentThinkingLevel(
-	agents: readonly Pick<AgentConfig, "name" | "thinkingLevel">[],
-	agentName: string,
-	topLevelThinkingLevel?: SubagentThinkingLevel,
-	localThinkingLevel?: SubagentThinkingLevel,
-): SubagentThinkingLevel | undefined {
-	return localThinkingLevel ?? topLevelThinkingLevel ?? agents.find((agent) => agent.name === agentName)?.thinkingLevel;
-}
-
-function hasAnyAgentOverride(config: SubagentAgentConfig): boolean {
-	return (
-		hasOwn(config, "tools") ||
-		hasOwn(config, "model") ||
-		hasOwn(config, "thinkingLevel") ||
-		hasOwn(config, "timeoutMs")
-	);
-}
-
-// ---- Tool toggle component ----
-
-class ToolToggleList {
-	private items: { name: string; selected: boolean }[];
-	private cursor = 0;
-	private cachedWidth?: number;
-	private cachedLines?: string[];
-	onDone?: (selected: string[]) => void;
-	onCancel?: () => void;
-
-	constructor(tools: string[], selected: Set<string>) {
-		this.items = tools.map((name) => ({ name, selected: selected.has(name) }));
-	}
-
-	private getSelectedNames(): string[] {
-		return this.items.filter((i) => i.selected).map((i) => i.name);
-	}
-
-	handleInput(data: string): void {
-		if (matchesKey(data, Key.escape)) {
-			this.onCancel?.();
-			return;
-		}
-		if (data === "s" || data === "S") {
-			this.onDone?.(this.getSelectedNames());
-			return;
-		}
-		if (this.items.length === 0) return;
-
-		if (matchesKey(data, Key.up) && this.cursor > 0) {
-			this.cursor--;
-			this.invalidate();
-		} else if (matchesKey(data, Key.down) && this.cursor < this.items.length - 1) {
-			this.cursor++;
-			this.invalidate();
-		} else if (matchesKey(data, Key.enter) || matchesKey(data, Key.space)) {
-			this.items[this.cursor].selected = !this.items[this.cursor].selected;
-			this.invalidate();
-		}
-	}
-
-	render(width: number): string[] {
-		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
-		this.cachedWidth = width;
-		this.cachedLines = this.items.map((item, i) => {
-			const pointer = i === this.cursor ? ">" : " ";
-			const check = item.selected ? "✓" : "○";
-			return truncateToWidth(`${pointer} ${check} ${item.name}`, width);
-		});
-		return this.cachedLines;
-	}
-
-	invalidate(): void {
-		this.cachedWidth = undefined;
-		this.cachedLines = undefined;
-	}
-}
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerSubagentConfigCommand } from "./config-ui.js";
+import { SubagentParams } from "./params.js";
+import { executeSubagent } from "./execution.js";
+import { renderSubagentCall, renderSubagentResult } from "./render.js";
+import type { SubagentDetails } from "./runner.js";
+import { registerStatefulSubagents } from "./stateful.js";
 
 export default function (pi: ExtensionAPI) {
-	pi.registerTool({
+	pi.registerTool<typeof SubagentParams, SubagentDetails>({
 		name: "subagent",
 		label: "Subagent",
 		description: [
@@ -827,8 +35,12 @@ export default function (pi: ExtensionAPI) {
 			"Decide whether to spawn 0, 1, or multiple subagents for independent research, review, verification, or multi-step work in isolated Pi processes.",
 		promptGuidelines: [
 			"Use subagent only when delegation fits; the main agent should decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
-			"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, or tasks requiring frequent user back-and-forth.",
-			"Use one subagent for isolated research, broad command output, planning, or independent review/verification that benefits from a separate context.",
+			"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work needed for the main agent's next action.",
+			"A single blocking subagent call should be used only when independent context, high-volume output isolation, or an external review is worth waiting for; otherwise do the task in the main agent.",
+			"For one-shot parallel work, use a single subagent call with tasks instead of repeated subagent_spawn calls, even when the user explicitly requests multiple agents.",
+			"When subagent_spawn is available, use it only when detached delegation has a concrete parallel, isolation, or specialization benefit; otherwise keep the work in the main agent.",
+			"After detached spawn, continue useful non-overlapping work when available, or call subagent_wait when coordination is the only useful next action; do not yield permanently while delegated work remains unresolved.",
+			"Consume detached completion messages and synthesize their results before finishing; interrupt or close agents that are no longer needed.",
 			"Use subagent parallel mode with 2-4 parallel read-only subagents when work has broad independent branches; prefer scout or reviewer for fan-out and add an aggregator when synthesis helps.",
 			"Use more than 4 subagent tasks only when clearly justified by distinct independent branches, and stay within the existing hard max 8 parallel tasks.",
 			"Do not use subagent parallel mode for write-heavy implementation touching the same files or shared state; serialize those changes in the main agent or one worker.",
@@ -838,891 +50,33 @@ export default function (pi: ExtensionAPI) {
 		parameters: SubagentParams,
 
 		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			const agentScope: AgentScope = params.agentScope ?? "user";
-			const config = readSubagentSettings();
-			const discovery = discoverAgents(ctx.cwd, agentScope, config);
-			const agents = discovery.agents;
-			const confirmProjectAgents = params.confirmProjectAgents ?? true;
-			const resolveTimeoutMs = (agentName: string, localTimeoutMs?: number) =>
-				localTimeoutMs ??
-				params.timeoutMs ??
-				agents.find((agent) => agent.name === agentName)?.timeoutMs ??
-				DEFAULT_TIMEOUT_MS;
-			const resolveThinkingLevel = (agentName: string, localThinkingLevel?: SubagentThinkingLevel) =>
-				resolveSubagentThinkingLevel(agents, agentName, params.thinkingLevel, localThinkingLevel);
-
-			const hasChain = (params.chain?.length ?? 0) > 0;
-			const hasTasks = (params.tasks?.length ?? 0) > 0;
-			const hasSingle = Boolean(params.agent && params.task);
-			const modeCount = Number(hasChain) + Number(hasTasks) + Number(hasSingle);
-
-			const makeDetails =
-				(mode: "single" | "parallel" | "chain") =>
-				(results: SingleResult[], aggregator?: SingleResult): SubagentDetails => ({
-					mode,
-					agentScope,
-					projectAgentsDir: discovery.projectAgentsDir,
-					results,
-					aggregator,
-				});
-
-			if (modeCount !== 1 || (params.aggregator && !hasTasks)) {
-				const available = agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
-				const reason =
-					modeCount !== 1
-						? "Provide exactly one mode."
-						: "Aggregator is only valid with parallel tasks.";
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Invalid parameters. ${reason}\nAvailable agents: ${available}`,
-						},
-					],
-					details: makeDetails("single")([]),
-				};
-			}
-
-			if ((agentScope === "project" || agentScope === "both") && confirmProjectAgents && ctx.hasUI) {
-				const requestedAgentNames = new Set<string>();
-				if (params.chain) for (const step of params.chain) requestedAgentNames.add(step.agent);
-				if (params.tasks) for (const t of params.tasks) requestedAgentNames.add(t.agent);
-				if (params.aggregator) requestedAgentNames.add(params.aggregator.agent);
-				if (params.agent) requestedAgentNames.add(params.agent);
-
-				const projectAgentsRequested = Array.from(requestedAgentNames)
-					.map((name) => agents.find((a) => a.name === name))
-					.filter((a): a is AgentConfig => a?.source === "project");
-
-				if (projectAgentsRequested.length > 0) {
-					const names = projectAgentsRequested.map((a) => a.name).join(", ");
-					const dir = discovery.projectAgentsDir ?? "(unknown)";
-					const ok = await ctx.ui.confirm(
-						"Run project-local agents?",
-						`Agents: ${names}\nSource: ${dir}\n\nProject agents are repo-controlled. Only continue for trusted repositories.`,
-					);
-					if (!ok)
-						return {
-							content: [{ type: "text", text: "Canceled: project-local agents not approved." }],
-							details: makeDetails(hasChain ? "chain" : hasTasks ? "parallel" : "single")([]),
-						};
-				}
-			}
-
-			if (params.chain && params.chain.length > 0) {
-				const results: SingleResult[] = [];
-				let previousOutput = "";
-				const status = startSubagentStatus(ctx, toolCallId, chainStatus(0, params.chain.length));
-
-				try {
-					for (let i = 0; i < params.chain.length; i++) {
-						const step = params.chain[i];
-						status.update(chainStatus(i + 1, params.chain.length, step.agent));
-						const taskWithContext = step.task.replace(/\{previous\}/g, previousOutput);
-
-						// Create update callback that includes all previous results
-						const chainUpdate: OnUpdateCallback | undefined = onUpdate
-							? (partial) => {
-									// Combine completed results with current streaming result
-									const currentResult = partial.details?.results[0];
-									if (currentResult) {
-										const allResults = [...results, currentResult];
-										onUpdate({
-											content: partial.content,
-											details: makeDetails("chain")(allResults),
-										});
-									}
-								}
-							: undefined;
-
-						const result = await runSingleAgent(
-							ctx.cwd,
-							agents,
-							step.agent,
-							taskWithContext,
-							step.cwd,
-							i + 1,
-							signal,
-							resolveThinkingLevel(step.agent, step.thinkingLevel),
-							resolveTimeoutMs(step.agent, step.timeoutMs),
-							chainUpdate,
-							makeDetails("chain"),
-						);
-						results.push(result);
-
-						const isError =
-							result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
-						if (isError) {
-							const errorMsg = result.errorMessage || result.stderr || getResultFinalOutput(result) || "(no output)";
-							return {
-								content: [{ type: "text", text: `Chain stopped at step ${i + 1} (${step.agent}): ${errorMsg}` }],
-								details: makeDetails("chain")(results),
-								isError: true,
-							};
-						}
-						previousOutput = getResultFinalOutput(result);
-					}
-					return {
-						content: [{ type: "text", text: getResultFinalOutput(results[results.length - 1]) || "(no output)" }],
-						details: makeDetails("chain")(results),
-					};
-				} finally {
-					status.clear();
-				}
-			}
-
-			if (params.tasks && params.tasks.length > 0) {
-				if (params.tasks.length > MAX_PARALLEL_TASKS)
-					return {
-						content: [
-							{
-								type: "text",
-								text: `Too many parallel tasks (${params.tasks.length}). Max is ${MAX_PARALLEL_TASKS}.`,
-							},
-						],
-						details: makeDetails("parallel")([]),
-					};
-
-				const status = startSubagentStatus(ctx, toolCallId, parallelStatus(0, params.tasks.length, params.tasks.length));
-
-				try {
-					// Track all results for streaming updates
-					const allResults: SingleResult[] = new Array(params.tasks.length);
-
-					// Initialize placeholder results
-					for (let i = 0; i < params.tasks.length; i++) {
-						allResults[i] = {
-							agent: params.tasks[i].agent,
-							agentSource: "unknown",
-							task: params.tasks[i].task,
-							exitCode: -1, // -1 = still running
-							messages: [],
-							stderr: "",
-							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-							thinkingLevel: resolveThinkingLevel(params.tasks[i].agent, params.tasks[i].thinkingLevel),
-							finalOutput: "",
-						};
-					}
-
-					let doneCount = 0;
-					let runningCount = params.tasks.length;
-
-					const emitParallelUpdate = () => {
-						status.update(parallelStatus(doneCount, allResults.length, runningCount));
-						if (onUpdate) {
-							onUpdate({
-								content: [
-									{
-										type: "text",
-										text: `Parallel: ${doneCount}/${allResults.length} done, ${runningCount} running...`,
-									},
-								],
-								details: makeDetails("parallel")([...allResults]),
-							});
-						}
-					};
-
-					const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
-						const result = await runSingleAgent(
-							ctx.cwd,
-							agents,
-							t.agent,
-							t.task,
-							t.cwd,
-							undefined,
-							signal,
-							resolveThinkingLevel(t.agent, t.thinkingLevel),
-							resolveTimeoutMs(t.agent, t.timeoutMs),
-							// Per-task update callback
-							(partial) => {
-								if (partial.details?.results[0]) {
-									allResults[index] = { ...partial.details.results[0], exitCode: -1 };
-									emitParallelUpdate();
-								}
-							},
-							makeDetails("parallel"),
-						);
-						allResults[index] = result;
-						doneCount += 1;
-						runningCount -= 1;
-						emitParallelUpdate();
-						return result;
-					});
-
-					let aggregatorResult: SingleResult | undefined;
-					if (params.aggregator) {
-						const aggregator = params.aggregator;
-						status.update(fanInStatus(aggregator.agent));
-						const fanInContext = buildFanInContext(results);
-						const aggregatorTask = aggregator.task.includes("{previous}")
-							? aggregator.task.replace(/\{previous\}/g, fanInContext)
-							: `${aggregator.task}\n\nParallel task outputs:\n\n${fanInContext}`;
-						aggregatorResult = await runSingleAgent(
-							ctx.cwd,
-							agents,
-							aggregator.agent,
-							aggregatorTask,
-							aggregator.cwd,
-							undefined,
-							signal,
-							resolveThinkingLevel(aggregator.agent, aggregator.thinkingLevel),
-							resolveTimeoutMs(aggregator.agent, aggregator.timeoutMs),
-							(partial) => {
-								status.update(fanInStatus(aggregator.agent));
-								if (onUpdate && partial.details?.results[0]) {
-									onUpdate({
-										content: partial.content,
-										details: makeDetails("parallel")(results, partial.details.results[0]),
-									});
-								}
-							},
-							makeDetails("parallel"),
-						);
-					}
-
-					const successCount = results.filter((r) => r.exitCode === 0).length;
-					const summaries = results.map((r) => {
-						const output = getResultFinalOutput(r);
-						const error = r.errorMessage || r.stderr.trim();
-						const summaryText = output || error;
-						const preview = summaryText.slice(0, 160) + (summaryText.length > 160 ? "..." : "");
-						return `[${r.agent}] ${r.exitCode === 0 ? "completed" : "failed"}: ${preview || "(no output)"}`;
-					});
-					const aggregatorOutput = aggregatorResult ? getResultFinalOutput(aggregatorResult) : "";
-					const aggregatorError = aggregatorResult?.errorMessage || aggregatorResult?.stderr.trim() || "";
-					return {
-						content: [
-							{
-								type: "text",
-								text: aggregatorResult
-									? aggregatorOutput || aggregatorError || `(aggregator ${aggregatorResult.agent} produced no output)`
-									: `Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join("\n\n")}`,
-							},
-						],
-						details: makeDetails("parallel")(results, aggregatorResult),
-						isError: aggregatorResult
-							? aggregatorResult.exitCode !== 0 ||
-								aggregatorResult.stopReason === "error" ||
-								aggregatorResult.stopReason === "aborted"
-							: undefined,
-					};
-				} finally {
-					status.clear();
-				}
-			}
-
-			if (params.agent && params.task) {
-				const status = startSubagentStatus(ctx, toolCallId, singleStatus(params.agent));
-
-				try {
-					const result = await runSingleAgent(
-						ctx.cwd,
-						agents,
-						params.agent,
-						params.task,
-						params.cwd,
-						undefined,
-						signal,
-						resolveThinkingLevel(params.agent, params.thinkingLevel),
-						resolveTimeoutMs(params.agent, params.timeoutMs),
-						onUpdate,
-						makeDetails("single"),
-					);
-					const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
-					if (isError) {
-						const errorMsg = result.errorMessage || result.stderr || getResultFinalOutput(result) || "(no output)";
-						return {
-							content: [{ type: "text", text: `Agent ${result.stopReason || "failed"}: ${errorMsg}` }],
-							details: makeDetails("single")([result]),
-							isError: true,
-						};
-					}
-					return {
-						content: [{ type: "text", text: getResultFinalOutput(result) || "(no output)" }],
-						details: makeDetails("single")([result]),
-					};
-				} finally {
-					status.clear();
-				}
-			}
-
-			const available = agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
-			return {
-				content: [{ type: "text", text: `Invalid parameters. Available agents: ${available}` }],
-				details: makeDetails("single")([]),
-			};
+			return executeSubagent(toolCallId, params, signal, onUpdate, ctx);
 		},
 
-		renderCall(args, theme, _context) {
-			const scope: AgentScope = args.agentScope ?? "user";
-			if (args.chain && args.chain.length > 0) {
-				let text =
-					theme.fg("toolTitle", theme.bold("subagent ")) +
-					theme.fg("accent", `chain (${args.chain.length} steps)`) +
-					theme.fg("muted", ` [${scope}]`);
-				for (let i = 0; i < Math.min(args.chain.length, 3); i++) {
-					const step = args.chain[i];
-					// Clean up {previous} placeholder for display
-					const cleanTask = step.task.replace(/\{previous\}/g, "").trim();
-					const preview = cleanTask.length > 40 ? `${cleanTask.slice(0, 40)}...` : cleanTask;
-					text +=
-						"\n  " +
-						theme.fg("muted", `${i + 1}.`) +
-						" " +
-						theme.fg("accent", step.agent) +
-						theme.fg("dim", ` ${preview}`);
-				}
-				if (args.chain.length > 3) text += `\n  ${theme.fg("muted", `... +${args.chain.length - 3} more`)}`;
-				return new Text(text, 0, 0);
-			}
-			if (args.tasks && args.tasks.length > 0) {
-				let text =
-					theme.fg("toolTitle", theme.bold("subagent ")) +
-					theme.fg("accent", `parallel (${args.tasks.length} tasks)`) +
-					theme.fg("muted", ` [${scope}]`);
-				for (const t of args.tasks.slice(0, 3)) {
-					const preview = t.task.length > 40 ? `${t.task.slice(0, 40)}...` : t.task;
-					text += `\n  ${theme.fg("accent", t.agent)}${theme.fg("dim", ` ${preview}`)}`;
-				}
-				if (args.tasks.length > 3) text += `\n  ${theme.fg("muted", `... +${args.tasks.length - 3} more`)}`;
-				if (args.aggregator) {
-					const preview =
-						args.aggregator.task.length > 40 ? `${args.aggregator.task.slice(0, 40)}...` : args.aggregator.task;
-					text += `\n  ${theme.fg("muted", "fan-in → ")}${theme.fg("accent", args.aggregator.agent)}${theme.fg(
-						"dim",
-						` ${preview}`,
-					)}`;
-				}
-				return new Text(text, 0, 0);
-			}
-			const agentName = args.agent || "...";
-			const preview = args.task ? (args.task.length > 60 ? `${args.task.slice(0, 60)}...` : args.task) : "...";
-			let text =
-				theme.fg("toolTitle", theme.bold("subagent ")) +
-				theme.fg("accent", agentName) +
-				theme.fg("muted", ` [${scope}]`);
-			text += `\n  ${theme.fg("dim", preview)}`;
-			return new Text(text, 0, 0);
+		renderCall(args, theme) {
+			return renderSubagentCall(args, theme);
 		},
 
-		renderResult(result, { expanded }, theme, _context) {
-			const details = result.details as SubagentDetails | undefined;
-			if (!details || details.results.length === 0) {
-				const text = result.content[0];
-				return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
-			}
-
-			const mdTheme = getMarkdownTheme();
-
-			const renderDisplayItems = (items: DisplayItem[], limit?: number) => {
-				const toShow = limit ? items.slice(-limit) : items;
-				const skipped = limit && items.length > limit ? items.length - limit : 0;
-				let text = "";
-				if (skipped > 0) text += theme.fg("muted", `... ${skipped} earlier items\n`);
-				for (const item of toShow) {
-					if (item.type === "text") {
-						const preview = expanded ? item.text : item.text.split("\n").slice(0, 3).join("\n");
-						text += `${theme.fg("toolOutput", preview)}\n`;
-					} else {
-						text += `${theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme))}\n`;
-					}
-				}
-				return text.trimEnd();
-			};
-
-			if (details.mode === "single" && details.results.length === 1) {
-				const r = details.results[0];
-				const isError = r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";
-				const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
-				const displayItems = getDisplayItems(r.messages);
-				const finalOutput = getResultFinalOutput(r);
-
-				if (expanded) {
-					const container = new Container();
-					let header = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
-					if (isError && r.stopReason) header += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
-					container.addChild(new Text(header, 0, 0));
-					if (isError && r.errorMessage)
-						container.addChild(new Text(theme.fg("error", `Error: ${r.errorMessage}`), 0, 0));
-					container.addChild(new Spacer(1));
-					container.addChild(new Text(theme.fg("muted", "─── Task ───"), 0, 0));
-					container.addChild(new Text(theme.fg("dim", r.task), 0, 0));
-					container.addChild(new Spacer(1));
-					container.addChild(new Text(theme.fg("muted", "─── Output ───"), 0, 0));
-					if (displayItems.length === 0 && !finalOutput) {
-						container.addChild(new Text(theme.fg("muted", "(no output)"), 0, 0));
-					} else {
-						for (const item of displayItems) {
-							if (item.type === "toolCall")
-								container.addChild(
-									new Text(
-										theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme)),
-										0,
-										0,
-									),
-								);
-						}
-						if (finalOutput) {
-							container.addChild(new Spacer(1));
-							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
-						}
-					}
-					const usageStr = formatUsageStats(r.usage, r.model, r.thinkingLevel);
-					if (usageStr) {
-						container.addChild(new Spacer(1));
-						container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
-					}
-					return container;
-				}
-
-				let text = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
-				if (isError && r.stopReason) text += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
-				if (isError && r.errorMessage) text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
-				else if (displayItems.length === 0) text += `\n${theme.fg("muted", "(no output)")}`;
-				else {
-					text += `\n${renderDisplayItems(displayItems, COLLAPSED_ITEM_COUNT)}`;
-					if (displayItems.length > COLLAPSED_ITEM_COUNT) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
-				}
-				const usageStr = formatUsageStats(r.usage, r.model, r.thinkingLevel);
-				if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
-				return new Text(text, 0, 0);
-			}
-
-			const aggregateUsage = (results: SingleResult[]) => {
-				const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
-				for (const r of results) {
-					total.input += r.usage.input;
-					total.output += r.usage.output;
-					total.cacheRead += r.usage.cacheRead;
-					total.cacheWrite += r.usage.cacheWrite;
-					total.cost += r.usage.cost;
-					total.turns += r.usage.turns;
-				}
-				return total;
-			};
-
-			if (details.mode === "chain") {
-				const successCount = details.results.filter((r) => r.exitCode === 0).length;
-				const icon = successCount === details.results.length ? theme.fg("success", "✓") : theme.fg("error", "✗");
-
-				if (expanded) {
-					const container = new Container();
-					container.addChild(
-						new Text(
-							icon +
-								" " +
-								theme.fg("toolTitle", theme.bold("chain ")) +
-								theme.fg("accent", `${successCount}/${details.results.length} steps`),
-							0,
-							0,
-						),
-					);
-
-					for (const r of details.results) {
-						const rIcon = r.exitCode === 0 ? theme.fg("success", "✓") : theme.fg("error", "✗");
-						const displayItems = getDisplayItems(r.messages);
-						const finalOutput = getResultFinalOutput(r);
-
-						container.addChild(new Spacer(1));
-						container.addChild(
-							new Text(
-								`${theme.fg("muted", `─── Step ${r.step}: `) + theme.fg("accent", r.agent)} ${rIcon}`,
-								0,
-								0,
-							),
-						);
-						container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", r.task), 0, 0));
-
-						// Show tool calls
-						for (const item of displayItems) {
-							if (item.type === "toolCall") {
-								container.addChild(
-									new Text(
-										theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme)),
-										0,
-										0,
-									),
-								);
-							}
-						}
-
-						// Show final output as markdown
-						if (finalOutput) {
-							container.addChild(new Spacer(1));
-							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
-						}
-
-						const stepUsage = formatUsageStats(r.usage, r.model, r.thinkingLevel);
-						if (stepUsage) container.addChild(new Text(theme.fg("dim", stepUsage), 0, 0));
-					}
-
-					const usageStr = formatUsageStats(aggregateUsage(details.results));
-					if (usageStr) {
-						container.addChild(new Spacer(1));
-						container.addChild(new Text(theme.fg("dim", `Total: ${usageStr}`), 0, 0));
-					}
-					return container;
-				}
-
-				// Collapsed view
-				let text =
-					icon +
-					" " +
-					theme.fg("toolTitle", theme.bold("chain ")) +
-					theme.fg("accent", `${successCount}/${details.results.length} steps`);
-				for (const r of details.results) {
-					const rIcon = r.exitCode === 0 ? theme.fg("success", "✓") : theme.fg("error", "✗");
-					const displayItems = getDisplayItems(r.messages);
-					text += `\n\n${theme.fg("muted", `─── Step ${r.step}: `)}${theme.fg("accent", r.agent)} ${rIcon}`;
-					if (displayItems.length === 0) text += `\n${theme.fg("muted", "(no output)")}`;
-					else text += `\n${renderDisplayItems(displayItems, 5)}`;
-				}
-				const usageStr = formatUsageStats(aggregateUsage(details.results));
-				if (usageStr) text += `\n\n${theme.fg("dim", `Total: ${usageStr}`)}`;
-				text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
-				return new Text(text, 0, 0);
-			}
-
-			if (details.mode === "parallel") {
-				const running = details.results.filter((r) => r.exitCode === -1).length;
-				const successCount = details.results.filter((r) => r.exitCode === 0).length;
-				const failCount = details.results.filter((r) => r.exitCode > 0).length;
-				const aggregator = details.aggregator;
-				const aggregatorRunning = aggregator?.exitCode === -1;
-				const aggregatorFailed = aggregator ? aggregator.exitCode > 0 || aggregator.stopReason === "error" : false;
-				const isRunning = running > 0 || aggregatorRunning;
-				const icon = isRunning
-					? theme.fg("warning", "⏳")
-					: failCount > 0 || aggregatorFailed
-						? theme.fg("warning", "◐")
-						: theme.fg("success", "✓");
-				const status = isRunning
-					? aggregatorRunning
-						? `${successCount + failCount}/${details.results.length} done, fan-in running`
-						: `${successCount + failCount}/${details.results.length} done, ${running} running`
-					: aggregator
-						? `${successCount}/${details.results.length} tasks + fan-in`
-						: `${successCount}/${details.results.length} tasks`;
-
-				if (expanded && !isRunning) {
-					const container = new Container();
-					container.addChild(
-						new Text(
-							`${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`,
-							0,
-							0,
-						),
-					);
-
-					for (const r of details.results) {
-						const rIcon = r.exitCode === 0 ? theme.fg("success", "✓") : theme.fg("error", "✗");
-						const displayItems = getDisplayItems(r.messages);
-						const finalOutput = getResultFinalOutput(r);
-
-						container.addChild(new Spacer(1));
-						container.addChild(
-							new Text(`${theme.fg("muted", "─── ") + theme.fg("accent", r.agent)} ${rIcon}`, 0, 0),
-						);
-						container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", r.task), 0, 0));
-
-						// Show tool calls
-						for (const item of displayItems) {
-							if (item.type === "toolCall") {
-								container.addChild(
-									new Text(
-										theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme)),
-										0,
-										0,
-									),
-								);
-							}
-						}
-
-						// Show final output as markdown
-						if (finalOutput) {
-							container.addChild(new Spacer(1));
-							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
-						}
-
-						const taskUsage = formatUsageStats(r.usage, r.model, r.thinkingLevel);
-						if (taskUsage) container.addChild(new Text(theme.fg("dim", taskUsage), 0, 0));
-					}
-
-					if (aggregator) {
-						const rIcon = aggregator.exitCode === 0 ? theme.fg("success", "✓") : theme.fg("error", "✗");
-						const displayItems = getDisplayItems(aggregator.messages);
-						const finalOutput = getResultFinalOutput(aggregator);
-
-						container.addChild(new Spacer(1));
-						container.addChild(
-							new Text(
-								`${theme.fg("muted", "─── fan-in → ") + theme.fg("accent", aggregator.agent)} ${rIcon}`,
-								0,
-								0,
-							),
-						);
-						container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", aggregator.task), 0, 0));
-						for (const item of displayItems) {
-							if (item.type === "toolCall") {
-								container.addChild(
-									new Text(
-										theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme.fg.bind(theme)),
-										0,
-										0,
-									),
-								);
-							}
-						}
-						if (finalOutput) {
-							container.addChild(new Spacer(1));
-							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
-						}
-						const fanInUsage = formatUsageStats(aggregator.usage, aggregator.model, aggregator.thinkingLevel);
-						if (fanInUsage) container.addChild(new Text(theme.fg("dim", fanInUsage), 0, 0));
-					}
-
-					const usageResults = aggregator ? [...details.results, aggregator] : details.results;
-					const usageStr = formatUsageStats(aggregateUsage(usageResults));
-					if (usageStr) {
-						container.addChild(new Spacer(1));
-						container.addChild(new Text(theme.fg("dim", `Total: ${usageStr}`), 0, 0));
-					}
-					return container;
-				}
-
-				// Collapsed view (or still running)
-				let text = `${icon} ${theme.fg("toolTitle", theme.bold("parallel "))}${theme.fg("accent", status)}`;
-				for (const r of details.results) {
-					const rIcon =
-						r.exitCode === -1
-							? theme.fg("warning", "⏳")
-							: r.exitCode === 0
-								? theme.fg("success", "✓")
-								: theme.fg("error", "✗");
-					const displayItems = getDisplayItems(r.messages);
-					text += `\n\n${theme.fg("muted", "─── ")}${theme.fg("accent", r.agent)} ${rIcon}`;
-					if (displayItems.length === 0)
-						text += `\n${theme.fg("muted", r.exitCode === -1 ? "(running...)" : "(no output)")}`;
-					else text += `\n${renderDisplayItems(displayItems, 5)}`;
-				}
-				if (aggregator) {
-					const rIcon =
-						aggregator.exitCode === -1
-							? theme.fg("warning", "⏳")
-							: aggregator.exitCode === 0
-								? theme.fg("success", "✓")
-								: theme.fg("error", "✗");
-					const displayItems = getDisplayItems(aggregator.messages);
-					text += `\n\n${theme.fg("muted", "─── fan-in → ")}${theme.fg("accent", aggregator.agent)} ${rIcon}`;
-					if (displayItems.length === 0)
-						text += `\n${theme.fg("muted", aggregator.exitCode === -1 ? "(running...)" : "(no output)")}`;
-					else text += `\n${renderDisplayItems(displayItems, 5)}`;
-				}
-				if (!isRunning) {
-					const usageResults = aggregator ? [...details.results, aggregator] : details.results;
-					const usageStr = formatUsageStats(aggregateUsage(usageResults));
-					if (usageStr) text += `\n\n${theme.fg("dim", `Total: ${usageStr}`)}`;
-				}
-				if (!expanded) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
-				return new Text(text, 0, 0);
-			}
-
-			const text = result.content[0];
-			return new Text(text?.type === "text" ? text.text : "(no output)", 0, 0);
+		renderResult(result, options, theme) {
+			return renderSubagentResult(result, options, theme);
 		},
 	});
 
-	// ---- Configuration command ----
-
-	pi.registerCommand("subagents:config", {
-		description: "Configure which tools each subagent can use",
-		handler: async (_args, ctx) => {
-			if (!ctx.hasUI) {
-				return;
-			}
-
-			// Get current settings
-			const currentSettings = readSubagentSettings() ?? {};
-			const currentAgents = currentSettings.agents ?? {};
-
-			// Discover agents to show which ones are available
-			const discovery = discoverAgents(ctx.cwd, "user", currentSettings);
-			const agents = discovery.agents;
-
-			if (agents.length === 0) {
-				ctx.ui.notify("No agents found", "warning");
-				return;
-			}
-
-			// Loop: agent selection → tool toggle (Esc in tools returns here)
-			while (true) {
-				// Step 1: pick an agent to configure
-				const agentItems: SelectItem[] = agents.map((a) => {
-					const cfg = currentAgents[a.name];
-					const hasToolsOverride = cfg ? hasOwn(cfg, "tools") : false;
-					const toolSummary = hasToolsOverride
-						? cfg?.tools && cfg.tools.length > 0
-							? cfg.tools.join(", ")
-							: "none"
-						: "defaults";
-					return {
-						value: a.name,
-						label: a.name,
-						description: `${a.source} · tools: ${toolSummary}`,
-					};
-				});
-
-				const agentName = await 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("Subagent Tool Configuration")), 1, 0),
-					);
-					container.addChild(new Spacer(1));
-					container.addChild(
-						new Text(theme.fg("muted", "Select an agent to configure its allowed tools:"), 1, 0),
-					);
-					container.addChild(new Spacer(1));
-					const selectList = new SelectList(agentItems, Math.min(agentItems.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 cancel"), 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();
-						},
-					};
-				});
-
-				if (!agentName) return;
-
-				const agent = agents.find((a) => a.name === agentName);
-				if (!agent) return;
-
-				// Step 2: toggle tools for the selected agent
-				// Discover without overrides to get original built-in/frontmatter defaults.
-				// The main discovery above applies saved overrides, so agent.tools is already
-				// overridden — using it for the reset-to-default comparison would match the
-				// override against itself and silently delete it on a no-op save.
-				const defaultDiscovery = discoverAgents(ctx.cwd, "user");
-				const defaultTools = defaultDiscovery.agents.find((a) => a.name === agentName)?.tools;
-				const currentAgentSettings = currentAgents[agentName];
-				const configuredTools =
-					currentAgentSettings && hasOwn(currentAgentSettings, "tools")
-						? (currentAgentSettings.tools ?? [])
-						: undefined;
-
-				// Get all available tools from pi's registry
-				const allTools = uniqueToolNames(pi.getAllTools().map((t) => t.name)).sort((a, b) =>
-					a.localeCompare(b),
-				);
-				const currentTools = uniqueToolNames(configuredTools ?? defaultTools ?? allTools);
-				// Sort: currently selected tools first, then rest alphabetically. Preserve
-				// unavailable configured tools so saving does not silently drop them.
-				const currentSet = new Set(currentTools);
-				const selectedFirst = [...currentTools, ...allTools.filter((t) => !currentSet.has(t))];
-
-				const selectedTools = await ctx.ui.custom<string[] | null>((tui, theme, _kb, done) => {
-					const toggleList = new ToolToggleList(selectedFirst, currentSet);
-
-					const container = new Container();
-					container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
-					container.addChild(
-						new Text(
-							theme.fg("accent", theme.bold(`${agentName} tools`)) +
-								theme.fg("muted", ` (${agent.source})`),
-							1,
-							0,
-						),
-					);
-					container.addChild(new Spacer(1));
-					container.addChild(
-						new Text(theme.fg("muted", "Toggle tools with Enter/Space. S to save, Esc to cancel."), 1, 0),
-					);
-					container.addChild(new Spacer(1));
-
-					const listContainer = new Container();
-					listContainer.addChild({
-						render: (w: number) => toggleList.render(w),
-						invalidate: () => toggleList.invalidate(),
-					});
-					container.addChild(listContainer);
-
-					container.addChild(new Spacer(1));
-					container.addChild(
-						new Text(theme.fg("dim", "↑↓ navigate · enter/space toggle · S save · esc cancel"), 1, 0),
-					);
-					container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
-
-					toggleList.onDone = (tools) => done(tools);
-					toggleList.onCancel = () => done(null);
-
-					return {
-						render: (w: number) => container.render(w),
-						invalidate: () => container.invalidate(),
-						handleInput: (data: string) => {
-							toggleList.handleInput(data);
-							tui.requestRender();
-						},
-					};
-				});
-
-				// null means user cancelled — loop back to agent selection
-				if (selectedTools === null) continue;
-
-				// Save to global settings
-				const updatedAgents = { ...currentAgents };
-				let restoredDefaults = false;
-
-				const isSameAsDefault =
-					defaultTools === undefined
-						? sameToolSet(selectedTools, allTools)
-						: sameToolSet(selectedTools, defaultTools);
-
-				if (isSameAsDefault) {
-					// Tools match defaults — remove only the tools override.
-					// Keep other settings (model, timeoutMs) if present.
-					const existing = updatedAgents[agentName];
-					if (existing) {
-						const nextConfig = { ...existing };
-						delete nextConfig.tools;
-						if (hasAnyAgentOverride(nextConfig)) updatedAgents[agentName] = nextConfig;
-						else delete updatedAgents[agentName];
-					}
-					restoredDefaults = true;
-				} else {
-					updatedAgents[agentName] = {
-						...updatedAgents[agentName],
-						tools: selectedTools,
-					};
-				}
-
-				const newSettings: SubagentSettings = {
-					...currentSettings,
-					agents: Object.keys(updatedAgents).length > 0 ? updatedAgents : undefined,
-				};
-
-				saveSubagentConfig(newSettings);
-				const message = restoredDefaults
-					? `${agentName}: defaults restored`
-					: `${agentName}: ${selectedTools.length} tool${selectedTools.length !== 1 ? "s" : ""} configured`;
-				ctx.ui.notify(message, "info");
-				// Saved — exit the loop
-				break;
-			}
-		},
+	pi.on("tool_result", (event) => {
+		if (event.toolName !== "subagent") return;
+		if ((event.details as (SubagentDetails & { isError?: boolean }) | undefined)?.isError) return { isError: true };
 	});
-}
+
+	registerSubagentConfigCommand(pi);
+	registerStatefulSubagents(pi);
+}
+export { formatTokens, formatUsageStats } from "./render.js";
+export { buildPiArgs } from "./runner.js";
+export {
+	normalizeAgentSettings,
+	normalizeSubagentSettings,
+	resolveSubagentThinkingLevel,
+	sameToolSet,
+	uniqueToolNames,
+} from "./settings.js";
+export { parsePositiveInteger } from "./execution.js";