@ghoulm370/pi-subagent-ui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ghoulm370
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @ghoulm370/pi-subagent-ui
+
+A [pi](https://github.com/earendil-works/pi-coding-agent) extension that adds a **`subagent`** tool with live status and TUI widgets. Delegate focused work (review, testing, planning, research, analysis) to specialized subagents with isolated context and persisted child sessions.
+
+Supports three run modes: **single**, **parallel** (`tasks`), and **chain** (`chain`, with `{previous}` templating).
+
+## Features
+
+- **Three orchestration modes**
+  - `single` — one agent + one task
+  - `parallel` — run many tasks concurrently (configurable, default 3, max 8, up to 16 tasks)
+  - `chain` — sequential tasks; each task may embed the previous output via `{previous}`
+- **Multi-source agent discovery** (later sources override earlier ones by name)
+  1. pi-web agents from `~/.pi/agent/agents.json` (global defaults)
+  2. User markdown agents at `~/.pi/agent/agents/*.md`
+  3. Project-local agents at `<cwd>/.pi/agents/*.md` (opt-in via `agentScope`)
+- **Isolated child context** — each subagent runs in its own `AgentSession` with its own resource loader, injected with a "you are a subagent" instruction so it doesn't recurse.
+- **Live status** — TUI widget + status bar + `subagent:*` events for web/TUI consumers.
+- **Persisted & restorable** — runs are written to a `<session>.subagents.json` sidecar and restored on `session_start`, so refreshes/session switches keep history.
+- **Resilient** — per-task timeout, abort propagation, and `stopReason: error/aborted` detection all mark tasks correctly.
+- **Usage accounting** — input/output/cache/cost/turns aggregated per task and per run.
+- **Safety rails** — project-local agents require explicit UI confirmation; the available-agent catalog is injected into context to prevent hallucinated agent names.
+
+## Install
+
+```bash
+npm install @ghoulm370/pi-subagent-ui
+```
+
+Pi auto-discovers the extension via the `pi.extensions` field in `package.json`. No build step — pi loads the TypeScript source directly.
+
+## Usage
+
+Read the **"Available subagents for the `subagent` tool"** list that is injected into context, then call the tool with an exact agent `name` or `id`.
+
+### Single
+
+```ts
+subagent({
+  agent: "code-reviewer",
+  task: "Review the current diff for correctness and edge cases"
+})
+```
+
+### Parallel
+
+```ts
+subagent({
+  tasks: [
+    { agent: "researcher", task: "Summarize the market context for X" },
+    { agent: "risk-reviewer", task: "List implementation risks for X" }
+  ],
+  concurrency: 2
+})
+```
+
+### Chain
+
+```ts
+subagent({
+  chain: [
+    { agent: "analyst", task: "Analyze the current implementation" },
+    { agent: "planner", task: "Create an execution plan from this analysis:\n{previous}" }
+  ]
+})
+```
+
+### Per-task overrides
+
+Each task item accepts optional `cwd`, `model` (`provider/model-id`), `thinking`, `tools` (allowlist), and `maxRuntimeMs`.
+
+## Parameters
+
+| Field                 | Type                              | Description                                            |
+| --------------------- | --------------------------------- | ------------------------------------------------------ |
+| `agent` + `task`      | `string`                          | Single mode                                            |
+| `tasks`               | `TaskItem[]`                      | Parallel mode                                          |
+| `chain`               | `TaskItem[]`                      | Sequential mode; `{previous}` replaced with prior output |
+| `agentScope`          | `"user" \| "project" \| "both"`   | Default `"user"`                                       |
+| `confirmProjectAgents`| `boolean`                         | Default `true`; require UI confirm for project agents  |
+| `concurrency`         | `number`                          | Parallel concurrency (default 3, max 8)               |
+| `model`               | `string`                          | `provider/model-id` override for single mode          |
+| `thinking`            | `string`                          | Thinking-level override                                |
+| `tools`               | `string[]`                        | Tool allowlist override (default read-only)            |
+| `maxRuntimeMs`        | `number`                          | Per-task timeout (default 10 min)                      |
+
+Exactly one mode (`single`, `tasks`, or `chain`) must be provided.
+
+## Defining agents
+
+### Markdown (user or project)
+
+`~/.pi/agent/agents/my-agent.md` or `<repo>/.pi/agents/my-agent.md`:
+
+```markdown
+---
+name: code-reviewer
+description: Reviews diffs for correctness and edge cases
+tools: read, grep, find, ls
+model: zenmux/claude-sonnet-4-6
+thinking: medium
+---
+
+You are a meticulous code reviewer. Focus on correctness, edge cases,
+and regressions. Return a concise, actionable summary.
+```
+
+### pi-web JSON
+
+Configured through pi-web's `~/.pi/agent/agents.json`.
+
+## Events
+
+Emitted on the pi event bus for web/TUI consumers:
+
+- `subagent:run-created` / `subagent:run-updated` / `subagent:run-completed`
+- `subagent:task-updated`
+- `subagent:session-event` (forwarded child `message_end` / `tool_execution_*`)
+- `subagent:runs-restored` (after sidecar reload on `session_start`)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ghoulm370/pi-subagent-ui",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Pi extension that adds a subagent tool with live status/widgets for pi-web.",
+  "license": "MIT",
+  "author": "ghoulm370",
+  "main": "./src/index.ts",
+  "files": [
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "subagent",
+    "agent-orchestration",
+    "pi-web"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.78.0",
+    "@earendil-works/pi-coding-agent": "^0.78.0",
+    "@earendil-works/pi-tui": "^0.78.0",
+    "typebox": "^1.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/pi-subagent-ui/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: pi-subagent-ui
+description: Delegate focused review, testing, planning, research, and analysis work to configured Pi subagents through the `subagent` tool.
+---
+
+# Pi Subagent UI
+
+Use this skill when specialized or parallel subagent work would improve quality without stuffing the full parent transcript into each child.
+
+## Required First Step
+
+Before every `subagent` call, read the injected "Available subagents for the `subagent` tool" list. It contains each usable agent's `name`, optional `id`, source, tools/model hints, and description.
+
+Use only an exact `name` or `id` from that list. Do not invent generic names such as `pi`, `reviewer`, `tester`, `analyst`, or `planner` unless they appear in the list.
+
+## How To Choose
+
+- Match the task to the agent description.
+- Prefer a specialized configured agent when its description fits.
+- For generic work, choose the most general configured agent from the list.
+- Use `agentScope: "both"` only when you intentionally want project-local `.pi/agents` definitions included.
+
+## How To Invoke
+
+Single subagent:
+
+```ts
+subagent({
+  agent: "exact-agent-name-or-id",
+  task: "Review the current diff for correctness and edge cases"
+})
+```
+
+Parallel subagents:
+
+```ts
+subagent({
+  tasks: [
+    { agent: "exact-agent-name-or-id", task: "Research the current market context" },
+    { agent: "another-exact-agent-name-or-id", task: "Review the implementation risks" }
+  ],
+  concurrency: 2
+})
+```
+
+Chain mode:
+
+```ts
+subagent({
+  chain: [
+    { agent: "exact-agent-name-or-id", task: "Analyze the current implementation" },
+    { agent: "another-exact-agent-name-or-id", task: "Create an execution plan from this analysis:\n{previous}" }
+  ]
+})
+```
+
+## Agent Sources
+
+The subagent tool discovers agents from:
+
+1. pi-web agents configured in `~/.pi/agent/agents.json`.
+2. User-level markdown agents in `~/.pi/agent/agents/*.md`.
+3. Project-local markdown agents in `.pi/agents/*.md` when `agentScope` includes project.
+
+## Guardrails
+
+- Keep child prompts concise and task-specific.
+- Ask for concise final outputs.
+- Prefer read-only work unless the user explicitly wants implementation.
+- Never call `subagent` with an agent name that was not listed in the injected available-subagents context.

package/src/agents.ts

@@ -0,0 +1,213 @@
+/**
+ * Agent discovery and configuration
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export type AgentScope = "user" | "project" | "both";
+export type AgentSource = "user" | "project" | "pi-web";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	thinking?: string;
+	systemPrompt: string;
+	promptMode?: "append" | "replace";
+	source: AgentSource;
+	filePath: string;
+	id?: string;
+	resources?: { extensions?: string[]; skills?: string[]; prompts?: string[] };
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+interface PiWebAgentEntry {
+	id: string;
+	name: string;
+	description: string;
+	promptMode: "append" | "replace";
+	systemPrompt: string;
+	toolNames: string[];
+	resources?: { extensions?: string[]; skills?: string[]; prompts?: string[] };
+	defaultModel?: { provider: string; modelId: string };
+	defaultThinkingLevel?: string;
+	builtIn?: boolean;
+}
+
+interface PiWebAgentsJson {
+	version: number;
+	agents: PiWebAgentEntry[];
+}
+
+function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
+	const agents: AgentConfig[] = [];
+
+	if (!fs.existsSync(dir)) {
+		return agents;
+	}
+
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return agents;
+	}
+
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".md")) continue;
+		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+		const filePath = path.join(dir, entry.name);
+		let content: string;
+		try {
+			content = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+
+		if (!frontmatter.name || !frontmatter.description) {
+			continue;
+		}
+
+		const tools = frontmatter.tools
+			?.split(",")
+			.map((t: string) => t.trim())
+			.filter(Boolean);
+
+		agents.push({
+			name: frontmatter.name,
+			description: frontmatter.description,
+			tools: tools && tools.length > 0 ? tools : undefined,
+			model: frontmatter.model,
+			thinking: frontmatter.thinking,
+			systemPrompt: body,
+			source,
+			filePath,
+		});
+	}
+
+	return agents;
+}
+
+function loadPiWebAgents(agentDir: string): AgentConfig[] {
+	const filePath = path.join(agentDir, "agents.json");
+	if (!fs.existsSync(filePath)) return [];
+
+	let data: PiWebAgentsJson;
+	try {
+		data = JSON.parse(fs.readFileSync(filePath, "utf-8")) as PiWebAgentsJson;
+	} catch {
+		return [];
+	}
+	if (!data.agents || !Array.isArray(data.agents)) return [];
+
+	return data.agents.map((agent): AgentConfig => ({
+			name: agent.name,
+			description: agent.description,
+			tools: agent.toolNames && agent.toolNames.length > 0 ? agent.toolNames : undefined,
+			model: agent.defaultModel ? `${agent.defaultModel.provider}/${agent.defaultModel.modelId}` : undefined,
+			thinking: agent.defaultThinkingLevel,
+			systemPrompt: agent.systemPrompt,
+			promptMode: agent.promptMode,
+			source: "pi-web",
+			filePath,
+			id: agent.id,
+			resources: agent.resources,
+		}));
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		const candidate = path.join(currentDir, ".pi", "agents");
+		if (isDirectory(candidate)) return candidate;
+
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
+	const userDir = path.join(getAgentDir(), "agents");
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+	const piWebAgents = loadPiWebAgents(getAgentDir());
+
+	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+
+	const agentMap = new Map<string, AgentConfig>();
+
+	// pi-web agents act as global defaults; local markdown agents override them.
+	for (const agent of piWebAgents) agentMap.set(agent.name, agent);
+	if (scope === "both" || scope === "user") {
+		for (const agent of userAgents) agentMap.set(agent.name, agent);
+	}
+	if (scope === "both" || scope === "project") {
+		for (const agent of projectAgents) agentMap.set(agent.name, agent);
+	}
+
+	return { agents: Array.from(agentMap.values()), projectAgentsDir };
+}
+
+export function formatAgentList(agents: AgentConfig[], maxItems: number): { text: string; remaining: number } {
+	if (agents.length === 0) return { text: "none", remaining: 0 };
+	const listed = agents.slice(0, maxItems);
+	const remaining = agents.length - listed.length;
+	return {
+		text: listed.map((a) => `${a.name} (${a.source}): ${a.description}`).join("; "),
+		remaining,
+	};
+}
+
+export function agentDisplayName(agent: AgentConfig): string {
+	return agent.id ? `${agent.name} [id: ${agent.id}] (${agent.source})` : `${agent.name} (${agent.source})`;
+}
+
+export function formatAvailableAgents(agents: AgentConfig[]): string {
+	return agents.length > 0 ? agents.map(agentDisplayName).join(", ") : "none";
+}
+
+function optionalAgentFields(agent: AgentConfig): string {
+	const parts: string[] = [];
+	if (agent.id) parts.push(`id: ${agent.id}`);
+	if (agent.model) parts.push(`model: ${agent.model}`);
+	if (agent.thinking) parts.push(`thinking: ${agent.thinking}`);
+	if (agent.tools?.length) parts.push(`tools: ${agent.tools.join(", ")}`);
+	return parts.length > 0 ? ` [${parts.join("; ")}]` : "";
+}
+
+export function formatAgentCatalog(agents: AgentConfig[]): string {
+	if (agents.length === 0) return "No subagents are configured.";
+	return agents
+		.map((agent) => `- name: ${agent.name}\n  description: ${agent.description || "(no description)"}\n  source: ${agent.source}${optionalAgentFields(agent)}`)
+		.join("\n");
+}
+
+export function resolveAgent(agents: AgentConfig[], requested: string | undefined): AgentConfig | undefined {
+	const raw = requested?.trim();
+	if (!raw) return undefined;
+	const normalized = raw.toLowerCase();
+	const exact = agents.find((agent) => agent.name === raw || agent.id === raw);
+	if (exact) return exact;
+	const caseInsensitive = agents.find((agent) => agent.name.toLowerCase() === normalized || agent.id?.toLowerCase() === normalized);
+	if (caseInsensitive) return caseInsensitive;
+	return undefined;
+}

package/src/index.ts

@@ -0,0 +1,744 @@
+import type { AgentSessionEvent, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	createAgentSession,
+	DefaultResourceLoader,
+	getAgentDir,
+	getMarkdownTheme,
+	SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { type AgentConfig, type AgentScope, discoverAgents, formatAgentCatalog, formatAvailableAgents, resolveAgent } from "./agents.ts";
+
+const DEFAULT_CONCURRENCY = 3;
+const MAX_CONCURRENCY = 8;
+const MAX_TASKS = 16;
+const DEFAULT_RUNTIME_MS = 10 * 60 * 1000;
+const DEFAULT_READONLY_TOOLS = ["read", "grep", "find", "ls"];
+const FINAL_OUTPUT_CAP = 24 * 1024;
+
+type RunMode = "single" | "parallel" | "chain";
+type TaskStatus = "queued" | "starting" | "running" | "completed" | "failed" | "aborted";
+type RunStatus = "queued" | "running" | "completed" | "failed" | "aborted";
+
+interface UsageStats {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	turns: number;
+}
+
+interface TaskInput {
+	id?: string;
+	agent: string;
+	task: string;
+	cwd?: string;
+	model?: string;
+	thinking?: string;
+	tools?: string[];
+	maxRuntimeMs?: number;
+}
+
+interface TaskSnapshot {
+	id: string;
+	runId: string;
+	index: number;
+	agent: string;
+	task: string;
+	cwd: string;
+	status: TaskStatus;
+	agentSource?: "user" | "project" | "pi-web" | "unknown";
+	sessionId?: string;
+	sessionFile?: string;
+	model?: string;
+	thinking?: string;
+	tools?: string[];
+	startedAt?: number;
+	endedAt?: number;
+	currentTool?: { toolCallId: string; toolName: string; args: unknown; startedAt: number };
+	usage: UsageStats;
+	finalText?: string;
+	error?: string;
+}
+
+interface RunSnapshot {
+	id: string;
+	parentSessionId?: string;
+	parentToolCallId: string;
+	mode: RunMode;
+	status: RunStatus;
+	createdAt: number;
+	startedAt?: number;
+	endedAt?: number;
+	concurrency: number;
+	tasks: TaskSnapshot[];
+	aggregateUsage: UsageStats;
+}
+
+interface ToolDetails {
+	run: RunSnapshot;
+	agents: Array<{ name: string; description: string; source: string; filePath: string; id?: string }>;
+}
+
+interface ChildFailure {
+	status: Extract<TaskStatus, "failed" | "aborted">;
+	message: string;
+}
+
+function newId(prefix: string): string {
+	return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function emptyUsage(): UsageStats {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+}
+
+function aggregateUsage(tasks: TaskSnapshot[]): UsageStats {
+	const total = emptyUsage();
+	for (const task of tasks) {
+		total.input += task.usage.input;
+		total.output += task.usage.output;
+		total.cacheRead += task.usage.cacheRead;
+		total.cacheWrite += task.usage.cacheWrite;
+		total.cost += task.usage.cost;
+		total.turns += task.usage.turns;
+	}
+	return total;
+}
+
+function truncateText(text: string, max = FINAL_OUTPUT_CAP): string {
+	if (Buffer.byteLength(text, "utf8") <= max) return text;
+	let out = text.slice(0, max);
+	while (Buffer.byteLength(out, "utf8") > max) out = out.slice(0, -1);
+	return `${out}\n\n[Output truncated. Full child session is available in the session file.]`;
+}
+
+function previewValue(value: unknown, max = 1024): unknown {
+	if (typeof value === "string") return truncateText(value, max);
+	try {
+		return truncateText(JSON.stringify(value), max);
+	} catch {
+		return String(value);
+	}
+}
+
+function getFirstText(message: any): string {
+	for (const part of message?.content ?? []) {
+		if (part?.type === "text" && typeof part.text === "string") return part.text;
+	}
+	return "";
+}
+
+function getParentSessionFile(ctx: ExtensionContext): string | undefined {
+	try {
+		return ctx.sessionManager.getSessionFile?.();
+	} catch {
+		return undefined;
+	}
+}
+
+function getAssistantFailure(message: any): ChildFailure | undefined {
+	if (message?.role !== "assistant") return undefined;
+	if (message.stopReason === "error") {
+		return { status: "failed", message: message.errorMessage || "Subagent failed with an assistant error." };
+	}
+	if (message.stopReason === "aborted") {
+		return { status: "aborted", message: message.errorMessage || "Subagent was aborted." };
+	}
+	return undefined;
+}
+
+function getLastAssistantFailure(messages: any[] | undefined): ChildFailure | undefined {
+	for (const message of [...(messages ?? [])].reverse()) {
+		const failure = getAssistantFailure(message);
+		if (failure) return failure;
+		if (message?.role === "assistant") return undefined;
+	}
+	return undefined;
+}
+
+function makeChildFailureError(failure: ChildFailure): Error {
+	const error = new Error(failure.message);
+	(error as Error & { subagentStatus?: ChildFailure["status"] }).subagentStatus = failure.status;
+	return error;
+}
+
+function updateUsageFromMessage(task: TaskSnapshot, message: any): void {
+	if (message?.role !== "assistant") return;
+	task.usage.turns += 1;
+	const usage = message.usage;
+	if (!usage) return;
+	task.usage.input += usage.input ?? 0;
+	task.usage.output += usage.output ?? 0;
+	task.usage.cacheRead += usage.cacheRead ?? 0;
+	task.usage.cacheWrite += usage.cacheWrite ?? 0;
+	task.usage.cost += usage.cost?.total ?? usage.cost ?? 0;
+	if (message.model && !task.model) task.model = message.model;
+}
+
+function formatUsage(usage: UsageStats): string {
+	const parts: string[] = [];
+	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+	if (usage.input) parts.push(`in ${usage.input}`);
+	if (usage.output) parts.push(`out ${usage.output}`);
+	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+	return parts.join(" · ");
+}
+
+function statusIcon(status: TaskStatus | RunStatus): string {
+	if (status === "completed") return "✓";
+	if (status === "failed") return "✗";
+	if (status === "aborted") return "⏹";
+	if (status === "queued") return "○";
+	return "⏳";
+}
+
+function renderWidgetLines(run: RunSnapshot): string[] {
+	const done = run.tasks.filter((t) => ["completed", "failed", "aborted"].includes(t.status)).length;
+	const lines = [`Subagents ${statusIcon(run.status)} ${run.mode}: ${done}/${run.tasks.length} done`];
+	for (const task of run.tasks.slice(0, 8)) {
+		const tool = task.currentTool ? ` · ${task.currentTool.toolName}` : "";
+		lines.push(`${statusIcon(task.status)} ${task.agent}: ${task.status}${tool}`);
+	}
+	if (run.tasks.length > 8) lines.push(`… +${run.tasks.length - 8} more`);
+	return lines;
+}
+
+function makeSummary(run: RunSnapshot): string {
+	const succeeded = run.tasks.filter((t) => t.status === "completed").length;
+	const failed = run.tasks.filter((t) => t.status === "failed").length;
+	const aborted = run.tasks.filter((t) => t.status === "aborted").length;
+	const lines = [`Subagents ${run.mode} finished: ${succeeded}/${run.tasks.length} succeeded${failed ? `, ${failed} failed` : ""}${aborted ? `, ${aborted} aborted` : ""}.`];
+	const usage = formatUsage(run.aggregateUsage);
+	if (usage) lines.push(`Usage: ${usage}`);
+	for (const task of run.tasks) {
+		const heading = `\n## ${task.agent} ${statusIcon(task.status)}`;
+		const session = task.sessionId ? `\nSession: ${task.sessionId}${task.sessionFile ? ` (${task.sessionFile})` : ""}` : "";
+		const body = task.error ? `Error: ${task.error}` : truncateText(task.finalText || "(no output)");
+		lines.push(`${heading}\n${body}${session}`);
+	}
+	return lines.join("\n");
+}
+
+function cloneRun(run: RunSnapshot): RunSnapshot {
+	return JSON.parse(JSON.stringify(run)) as RunSnapshot;
+}
+
+function parseModelRef(ref: string | undefined): { provider: string; modelId: string } | undefined {
+	if (!ref) return undefined;
+	const index = ref.indexOf("/");
+	if (index <= 0 || index === ref.length - 1) return undefined;
+	return { provider: ref.slice(0, index), modelId: ref.slice(index + 1) };
+}
+
+function makeAgentCatalogContext(cwd: string, scope: AgentScope = "user"): string {
+	const discovery = discoverAgents(cwd, scope);
+	return [
+		"Available subagents for the `subagent` tool:",
+		formatAgentCatalog(discovery.agents),
+		"",
+		"Rules:",
+		"- Use only an exact `name` or `id` from this list in subagent calls.",
+		"- Do not invent agent names such as `pi`, `reviewer`, `tester`, or `analyst` unless they appear above.",
+		"- Choose agents by matching the task to each agent description. If multiple tasks are similar (e.g., all are search, research, or analysis), use the SAME most suitable agent for all of them — do NOT spread similar tasks across different agents just because they are available.",
+		"- Use `agentScope: \"both\"` only when intentionally including project-local `.pi/agents` definitions.",
+	].join("\n");
+}
+
+function appendContextMessage<TMessage>(messages: TMessage[], text: string): TMessage[] {
+	return [
+		...messages,
+		{
+			role: "user",
+			content: [{ type: "text", text }],
+			timestamp: Date.now(),
+		} as TMessage,
+	];
+}
+
+function normalizeTask(input: TaskInput, runId: string, index: number, defaultCwd: string): TaskSnapshot {
+	return {
+		id: input.id ?? `task_${index + 1}`,
+		runId,
+		index,
+		agent: input.agent,
+		task: input.task,
+		cwd: input.cwd ?? defaultCwd,
+		status: "queued",
+		model: input.model,
+		thinking: input.thinking,
+		tools: input.tools,
+		usage: emptyUsage(),
+	};
+}
+
+async function mapWithConcurrency<T>(items: T[], concurrency: number, fn: (item: T, index: number) => Promise<void>): Promise<void> {
+	let next = 0;
+	const workers = Array.from({ length: Math.max(1, Math.min(concurrency, items.length)) }, async () => {
+		while (next < items.length) {
+			const index = next++;
+			await fn(items[index], index);
+		}
+	});
+	await Promise.all(workers);
+}
+
+class SubagentManager {
+	private runs = new Map<string, RunSnapshot>();
+	private eventSeq = 0;
+
+	constructor(private readonly pi: ExtensionAPI) {}
+
+	listRuns(): RunSnapshot[] {
+		return Array.from(this.runs.values()).sort((a, b) => b.createdAt - a.createdAt);
+	}
+
+	clearRuns(): void {
+		this.runs.clear();
+	}
+
+	async restoreFromSidecar(ctx: ExtensionContext): Promise<void> {
+		const parentFile = getParentSessionFile(ctx);
+		if (!parentFile) return;
+		const sidecar = parentFile.replace(/\.jsonl$/, ".subagents.json");
+		let runs: RunSnapshot[] | undefined;
+		try {
+			const { readFileSync, existsSync } = await import("fs");
+			if (!existsSync(sidecar)) return;
+			const raw = JSON.parse(readFileSync(sidecar, "utf-8"));
+			if (!Array.isArray(raw)) return;
+			runs = raw as RunSnapshot[];
+		} catch {
+			return;
+		}
+		let added = 0;
+		for (const run of runs ?? []) {
+			if (!run?.id || this.runs.has(run.id)) continue;
+			this.runs.set(run.id, run);
+			added += 1;
+		}
+		if (added > 0) {
+			this.emit("subagent:runs-restored", { count: added });
+			if (ctx.hasUI) {
+				const latest = this.listRuns()[0];
+				if (latest) {
+					ctx.ui.setStatus("subagents", `subagents: restored ${added} run${added > 1 ? "s" : ""}`);
+					ctx.ui.setWidget("subagents", renderWidgetLines(latest), { placement: "aboveEditor" });
+				}
+			}
+		}
+	}
+
+	private emit(type: string, payload: Record<string, unknown>): void {
+		this.pi.events.emit(type, { type, timestamp: Date.now(), ...payload });
+	}
+
+	private updateRun(run: RunSnapshot, ctx?: ExtensionContext, onUpdate?: (partial: any) => void): void {
+		run.aggregateUsage = aggregateUsage(run.tasks);
+		this.runs.set(run.id, run);
+		this.emit("subagent:run-updated", { run: cloneRun(run) });
+		if (ctx?.hasUI) {
+			ctx.ui.setStatus("subagents", `subagents: ${run.tasks.filter((t) => t.status === "running" || t.status === "starting").length} running`);
+			ctx.ui.setWidget("subagents", renderWidgetLines(run), { placement: "aboveEditor" });
+		}
+		onUpdate?.({ content: [{ type: "text", text: renderWidgetLines(run).join("\n") }], details: { run: cloneRun(run) } });
+	}
+
+	private updateTask(run: RunSnapshot, task: TaskSnapshot, patch: Partial<TaskSnapshot>, ctx: ExtensionContext, onUpdate?: (partial: any) => void): void {
+		Object.assign(task, patch);
+		this.emit("subagent:task-updated", { runId: run.id, taskId: task.id, patch, task: { ...task } });
+		this.updateRun(run, ctx, onUpdate);
+	}
+
+	private async runChild(
+		run: RunSnapshot,
+		task: TaskSnapshot,
+		input: TaskInput,
+		agents: AgentConfig[],
+		ctx: ExtensionContext,
+		signal: AbortSignal | undefined,
+		onUpdate?: (partial: any) => void,
+	): Promise<void> {
+		const requestedAgent = task.agent;
+		const agent = resolveAgent(agents, requestedAgent);
+		if (!agent) {
+			this.updateTask(run, task, {
+				status: "failed",
+				error: `Unknown agent: ${requestedAgent}. Available agents: ${formatAvailableAgents(agents)}`,
+				endedAt: Date.now(),
+				agentSource: "unknown",
+			}, ctx, onUpdate);
+			return;
+		}
+
+		this.updateTask(run, task, {
+			status: "starting",
+			agent: agent.name,
+			startedAt: Date.now(),
+			agentSource: agent.source,
+			model: input.model ?? agent.model,
+			thinking: input.thinking ?? agent.thinking,
+			tools: input.tools ?? agent.tools ?? DEFAULT_READONLY_TOOLS,
+		}, ctx, onUpdate);
+
+		let child: Awaited<ReturnType<typeof createAgentSession>>["session"] | undefined;
+		let unsubscribe: (() => void) | undefined;
+		let timeout: ReturnType<typeof setTimeout> | undefined;
+		let abortListener: (() => void) | undefined;
+		let pendingFailure: ChildFailure | undefined;
+		let failChildEnd: ((error: Error) => void) | undefined;
+		let childEndResolve: (() => void) | undefined;
+
+		try {
+			const modelRef = parseModelRef(input.model ?? agent.model);
+			const model = modelRef ? ctx.modelRegistry.find(modelRef.provider, modelRef.modelId) : undefined;
+			if (modelRef && !model) throw new Error(`Model not found: ${modelRef.provider}/${modelRef.modelId}`);
+
+			const subagentInstruction = "You are running as a subagent. Do not call subagent/delegation tools unless the parent explicitly asks you to. Return a concise final answer for the parent agent.";
+			const isPiWebAgent = agent.source === "pi-web";
+
+			const loaderOptions: ConstructorParameters<typeof DefaultResourceLoader>[0] = {
+				cwd: task.cwd,
+				agentDir: getAgentDir(),
+				noExtensions: !isPiWebAgent,
+				additionalExtensionPaths: isPiWebAgent ? agent.resources?.extensions : undefined,
+				additionalSkillPaths: isPiWebAgent ? agent.resources?.skills : undefined,
+				additionalPromptTemplatePaths: isPiWebAgent ? agent.resources?.prompts : undefined,
+			};
+
+			if (isPiWebAgent && agent.promptMode === "replace") {
+				loaderOptions.systemPrompt = agent.systemPrompt.trim();
+				loaderOptions.appendSystemPrompt = [subagentInstruction];
+			} else {
+				const appendPrompt = [agent.systemPrompt.trim(), subagentInstruction].filter(Boolean).join("\n\n");
+				loaderOptions.appendSystemPromptOverride = (base) => [...base, appendPrompt];
+			}
+
+			const loader = new DefaultResourceLoader(loaderOptions);
+			await loader.reload();
+
+			const created = await createAgentSession({
+				cwd: task.cwd,
+				resourceLoader: loader,
+				sessionManager: SessionManager.create(task.cwd, undefined, { parentSession: getParentSessionFile(ctx) }),
+				model,
+				thinkingLevel: (input.thinking ?? agent.thinking) as any,
+				tools: input.tools ?? agent.tools ?? DEFAULT_READONLY_TOOLS,
+				modelRegistry: ctx.modelRegistry,
+			});
+			child = created.session;
+			child.setSessionName?.(`subagent: ${agent.name}`);
+			this.updateTask(run, task, { status: "running", sessionId: child.sessionId, sessionFile: child.sessionFile }, ctx, onUpdate);
+
+			const childFailurePromise = new Promise<never>((_, reject) => {
+				failChildEnd = reject;
+			});
+			const childEndPromise = new Promise<void>((resolve) => {
+				childEndResolve = resolve;
+			});
+
+			unsubscribe = child.subscribe((event: AgentSessionEvent) => {
+				if (event.type === "message_end" || event.type === "tool_execution_start" || event.type === "tool_execution_end") {
+					this.emit("subagent:session-event", {
+						runId: run.id,
+						taskId: task.id,
+						sessionId: child?.sessionId,
+						sessionFile: child?.sessionFile,
+						seq: ++this.eventSeq,
+						event: { type: event.type },
+					});
+				}
+
+				if (event.type === "tool_execution_start") {
+					this.updateTask(run, task, {
+						currentTool: { toolCallId: (event as any).toolCallId, toolName: (event as any).toolName, args: previewValue((event as any).args), startedAt: Date.now() },
+					}, ctx, onUpdate);
+				}
+				if (event.type === "tool_execution_end") {
+					this.updateTask(run, task, { currentTool: undefined }, ctx, onUpdate);
+				}
+				if (event.type === "message_end") {
+					const message = (event as any).message;
+					updateUsageFromMessage(task, message);
+					const text = getFirstText(message);
+					if (message?.role === "assistant" && text) task.finalText = truncateText(text);
+					pendingFailure = getAssistantFailure(message);
+					this.updateRun(run, ctx, onUpdate);
+				}
+				if (event.type === "agent_end") {
+					const willRetry = Boolean((event as any).willRetry);
+					const failure = getLastAssistantFailure((event as any).messages);
+					if (failure && !willRetry) {
+						pendingFailure = failure;
+						failChildEnd?.(makeChildFailureError(failure));
+					} else if (!willRetry) {
+						childEndResolve?.();
+					}
+				}
+			});
+
+			if (signal) {
+				const listener = () => void child?.abort();
+				signal.addEventListener("abort", listener, { once: true });
+				abortListener = () => signal.removeEventListener("abort", listener);
+			}
+
+			const maxRuntimeMs = input.maxRuntimeMs ?? DEFAULT_RUNTIME_MS;
+			const promptPromise = child.prompt(task.task, { source: "extension" as any });
+			const timeoutPromise = new Promise<never>((_, reject) => {
+				timeout = setTimeout(() => reject(new Error(`Subagent timed out after ${maxRuntimeMs}ms`)), maxRuntimeMs);
+			});
+			await Promise.race([promptPromise, childFailurePromise, childEndPromise, timeoutPromise]);
+			if (timeout) clearTimeout(timeout);
+			pendingFailure ??= getLastAssistantFailure(child.messages as any[]);
+			if (pendingFailure) throw makeChildFailureError(pendingFailure);
+
+			const finalText = task.finalText || truncateText(child.messages.map(getFirstText).filter(Boolean).at(-1) || "");
+			this.updateTask(run, task, { status: "completed", finalText, currentTool: undefined, endedAt: Date.now() }, ctx, onUpdate);
+		} catch (err) {
+			if (timeout) clearTimeout(timeout);
+			const aborted = signal?.aborted;
+			const subagentStatus = (err as Error & { subagentStatus?: ChildFailure["status"] })?.subagentStatus;
+			try { await child?.abort(); } catch { /* ignore */ }
+			this.updateTask(run, task, {
+				status: aborted ? "aborted" : subagentStatus ?? "failed",
+				error: err instanceof Error ? err.message : String(err),
+				currentTool: undefined,
+				endedAt: Date.now(),
+			}, ctx, onUpdate);
+		} finally {
+			abortListener?.();
+			unsubscribe?.();
+			child?.dispose();
+		}
+	}
+
+	async run(params: any, toolCallId: string, signal: AbortSignal | undefined, onUpdate: ((partial: any) => void) | undefined, ctx: ExtensionContext): Promise<ToolDetails> {
+		const agentScope: AgentScope = params.agentScope ?? "user";
+		const discovery = discoverAgents(ctx.cwd, agentScope);
+		const agents = discovery.agents;
+
+		const hasChain = (params.chain?.length ?? 0) > 0;
+		const hasTasks = (params.tasks?.length ?? 0) > 0;
+		const hasSingle = Boolean(params.agent && params.task);
+		if (Number(hasChain) + Number(hasTasks) + Number(hasSingle) !== 1) {
+			throw new Error(`Provide exactly one subagent mode. Available agents: ${agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none"}`);
+		}
+
+		const requested = new Set<string>();
+		if (hasSingle) requested.add(params.agent);
+		for (const t of params.tasks ?? []) requested.add(t.agent);
+		for (const t of params.chain ?? []) requested.add(t.agent);
+
+		if ((agentScope === "project" || agentScope === "both") && (params.confirmProjectAgents ?? true) && ctx.hasUI) {
+			const projectAgents = [...requested]
+				.map((name) => resolveAgent(agents, name))
+				.filter((a): a is AgentConfig => a?.source === "project");
+			if (projectAgents.length > 0) {
+				const ok = await ctx.ui.confirm(
+					"Run project-local subagents?",
+					`Agents: ${projectAgents.map((a) => a.name).join(", ")}\nSource: ${discovery.projectAgentsDir}\n\nProject agents are repo-controlled. Continue only for trusted repositories.`,
+				);
+				if (!ok) throw new Error("Canceled: project-local subagents not approved.");
+			}
+		}
+
+		const mode: RunMode = hasChain ? "chain" : hasTasks ? "parallel" : "single";
+		const runId = newId("run");
+		const inputs: TaskInput[] = hasSingle
+			? [{ agent: params.agent, task: params.task, cwd: params.cwd, model: params.model, thinking: params.thinking, tools: params.tools, maxRuntimeMs: params.maxRuntimeMs }]
+			: hasTasks
+				? params.tasks
+				: params.chain;
+		if (inputs.length > MAX_TASKS) throw new Error(`Too many subagent tasks (${inputs.length}). Max is ${MAX_TASKS}.`);
+
+		const run: RunSnapshot = {
+			id: runId,
+			parentSessionId: ctx.sessionManager.getSessionId?.(),
+			parentToolCallId: toolCallId,
+			mode,
+			status: "queued",
+			createdAt: Date.now(),
+			concurrency: Math.max(1, Math.min(params.concurrency ?? DEFAULT_CONCURRENCY, MAX_CONCURRENCY)),
+			tasks: inputs.map((input, index) => normalizeTask(input, runId, index, input.cwd ?? params.cwd ?? ctx.cwd)),
+			aggregateUsage: emptyUsage(),
+		};
+		this.runs.set(run.id, run);
+		this.emit("subagent:run-created", { run: cloneRun(run) });
+		this.updateRun(run, ctx, onUpdate);
+
+		run.status = "running";
+		run.startedAt = Date.now();
+		this.updateRun(run, ctx, onUpdate);
+
+		if (mode === "chain") {
+			let previous = "";
+			for (let i = 0; i < inputs.length; i++) {
+				if (signal?.aborted) {
+					this.updateTask(run, run.tasks[i], { status: "aborted", error: "Aborted before start", endedAt: Date.now() }, ctx, onUpdate);
+					continue;
+				}
+				const input = { ...inputs[i], task: inputs[i].task.replace(/\{previous\}/g, previous) };
+				run.tasks[i].task = input.task;
+				await this.runChild(run, run.tasks[i], input, agents, ctx, signal, onUpdate);
+				if (run.tasks[i].status !== "completed") break;
+				previous = run.tasks[i].finalText ?? "";
+			}
+		} else {
+			await mapWithConcurrency(run.tasks, mode === "single" ? 1 : run.concurrency, async (task, index) => {
+				await this.runChild(run, task, inputs[index], agents, ctx, signal, onUpdate);
+			});
+		}
+
+		const failed = run.tasks.some((t) => t.status === "failed");
+		const aborted = run.tasks.some((t) => t.status === "aborted") || signal?.aborted;
+		run.status = aborted ? "aborted" : failed ? "failed" : "completed";
+		run.endedAt = Date.now();
+		this.updateRun(run, ctx, onUpdate);
+		this.emit("subagent:run-completed", { runId: run.id, status: run.status, run: cloneRun(run), aggregateUsage: run.aggregateUsage });
+
+		// Persist all subagent runs to a sidecar JSON file next to the parent
+		// session, so the UI can restore them across refreshes / session restarts
+		// without polluting the main .jsonl file.
+		try {
+			const parentFile = getParentSessionFile(ctx);
+			if (parentFile) {
+				const { writeFileSync } = await import("fs");
+				const sidecar = parentFile.replace(/\.jsonl$/, ".subagents.json");
+				const allRuns = this.listRuns().map((r) => cloneRun(r));
+				writeFileSync(sidecar, JSON.stringify(allRuns, null, 2));
+			}
+		} catch {
+			// silently ignore persistence errors
+		}
+		if (ctx.hasUI) {
+			ctx.ui.setStatus("subagents", `subagents: ${run.status}`);
+			ctx.ui.setWidget("subagents", renderWidgetLines(run), { placement: "aboveEditor" });
+		}
+		return {
+			run: cloneRun(run),
+			agents: agents.map((agent) => ({ name: agent.name, description: agent.description, source: agent.source, filePath: agent.filePath, id: agent.id })),
+		};
+	}
+}
+
+const TaskItem = Type.Object({
+	id: Type.Optional(Type.String({ description: "Optional stable task id" })),
+	agent: Type.String({ description: "Exact agent name or id from the injected available subagents list" }),
+	task: Type.String({ description: "Task to delegate to the agent" }),
+	cwd: Type.Optional(Type.String({ description: "Working directory for this task" })),
+	model: Type.Optional(Type.String({ description: "Model override as provider/model-id" })),
+	thinking: Type.Optional(Type.String({ description: "Thinking level override" })),
+	tools: Type.Optional(Type.Array(Type.String(), { description: "Tool allowlist for this task" })),
+	maxRuntimeMs: Type.Optional(Type.Number({ description: "Per-task timeout in milliseconds" })),
+});
+
+const SubagentParams = Type.Object({
+	agent: Type.Optional(Type.String({ description: "Exact agent name or id from the injected available subagents list for single mode" })),
+	task: Type.Optional(Type.String({ description: "Task for single mode" })),
+	tasks: Type.Optional(Type.Array(TaskItem, { description: "Parallel tasks" })),
+	chain: Type.Optional(Type.Array(TaskItem, { description: "Sequential tasks. Each task may use {previous}." })),
+	agentScope: Type.Optional(StringEnum(["user", "project", "both"] as const, { default: "user" })),
+	confirmProjectAgents: Type.Optional(Type.Boolean({ default: true })),
+	cwd: Type.Optional(Type.String({ description: "Default working directory" })),
+	model: Type.Optional(Type.String({ description: "Model override for single mode as provider/model-id" })),
+	thinking: Type.Optional(Type.String({ description: "Thinking override for single mode" })),
+	tools: Type.Optional(Type.Array(Type.String(), { description: "Tool allowlist override for single mode" })),
+	concurrency: Type.Optional(Type.Number({ description: `Parallel concurrency. Default ${DEFAULT_CONCURRENCY}, max ${MAX_CONCURRENCY}.` })),
+	maxRuntimeMs: Type.Optional(Type.Number({ description: "Per-task timeout for single mode" })),
+});
+
+export default function (pi: ExtensionAPI) {
+	const manager = new SubagentManager(pi);
+
+	pi.registerCommand("subagents", {
+		description: "Show recent subagent runs",
+		handler: async (_args, ctx) => {
+			const runs = manager.listRuns().slice(0, 10);
+			if (runs.length === 0) {
+				ctx.ui.notify("No subagent runs in this session.", "info");
+				return;
+			}
+			ctx.ui.setWidget("subagents", runs.flatMap((run) => renderWidgetLines(run).concat("")), { placement: "aboveEditor" });
+			ctx.ui.notify(`Showing ${runs.length} subagent run(s).`, "info");
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		await manager.restoreFromSidecar(ctx);
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		if (ctx?.hasUI) {
+			try {
+				ctx.ui.setStatus("subagents", "");
+				ctx.ui.setWidget("subagents", [], { placement: "aboveEditor" });
+			} catch {
+				/* ignore UI teardown errors */
+			}
+		}
+		manager.clearRuns();
+	});
+
+	pi.on("context", async (event, ctx) => {
+		return { messages: appendContextMessage(event.messages, makeAgentCatalogContext(ctx.cwd)) };
+	});
+
+	pi.registerTool<typeof SubagentParams, ToolDetails>({
+		name: "subagent",
+		label: "Subagent",
+		description: [
+			"Delegate work to specialized subagents with isolated context and persisted child sessions.",
+			"Use exactly one mode: single (agent+task), parallel (tasks), or chain (chain with optional {previous}).",
+			"Agents can be pi-web configured agents (referenced by name or id), markdown files under ~/.pi/agent/agents, or project-local .pi/agents when agentScope includes project.",
+			"Read the injected available subagents list before calling this tool, and choose an exact agent name or id from it.",
+		].join(" "),
+		promptSnippet: "Delegate analysis/review/test/planning work to specialized subagents.",
+		promptGuidelines: [
+			"Use subagent when independent review, testing, research, or parallel analysis would improve quality.",
+			"Use only exact configured agent names or ids from the injected available subagents list.",
+			"Choose agents by matching the task to their descriptions; do not invent generic names. For multiple similar tasks, reuse the same most suitable agent instead of spreading them across different agents.",
+			"Keep subagent tasks focused and ask for concise final outputs; do not pass the full parent transcript unless needed.",
+			"Prefer read-only subagent tools unless the user explicitly asks for implementation work.",
+		],
+		parameters: SubagentParams,
+		executionMode: "sequential",
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			const details = await manager.run(params, toolCallId, signal, onUpdate, ctx);
+			return {
+				content: [{ type: "text", text: makeSummary(details.run) }],
+				details,
+			};
+		},
+		renderCall(args, theme) {
+			const mode = args.chain?.length ? `chain ${args.chain.length}` : args.tasks?.length ? `parallel ${args.tasks.length}` : `single ${args.agent ?? "?"}`;
+			return new Text(`${theme.fg("toolTitle", theme.bold("subagent"))} ${theme.fg("accent", mode)}`, 0, 0);
+		},
+		renderResult(result, { expanded, isPartial }, theme) {
+			const run = result.details?.run;
+			if (!run) return new Text(result.content[0]?.type === "text" ? result.content[0].text : "", 0, 0);
+			const header = `${isPartial ? "⏳" : statusIcon(run.status)} ${theme.fg("toolTitle", theme.bold(`subagents ${run.mode}`))} ${theme.fg("accent", `${run.tasks.filter((t) => t.status === "completed").length}/${run.tasks.length}`)} ${theme.fg("muted", run.status)}`;
+			if (!expanded) {
+				const lines = [header, ...run.tasks.map((task) => `  ${statusIcon(task.status)} ${task.agent}: ${task.status}${task.currentTool ? ` · ${task.currentTool.toolName}` : ""}`)];
+				const usage = formatUsage(run.aggregateUsage);
+				if (usage) lines.push(theme.fg("dim", usage));
+				return new Text(lines.join("\n"), 0, 0);
+			}
+			const container = new Container();
+			container.addChild(new Text(header, 0, 0));
+			const mdTheme = getMarkdownTheme();
+			for (const task of run.tasks) {
+				container.addChild(new Spacer(1));
+				container.addChild(new Text(`${statusIcon(task.status)} ${theme.fg("accent", task.agent)} ${theme.fg("muted", task.sessionId ?? "")}`, 0, 0));
+				if (task.error) container.addChild(new Text(theme.fg("error", task.error), 0, 0));
+				else if (task.finalText) container.addChild(new Markdown(task.finalText.trim(), 0, 0, mdTheme));
+				const usage = formatUsage(task.usage);
+				if (usage) container.addChild(new Text(theme.fg("dim", usage), 0, 0));
+			}
+			return container;
+		},
+	});
+}