@d3ara1n/pi-subagent 0.1.0 → 0.3.0

package/README.md

@@ -2,7 +2,22 @@
 
 Role-based subagent orchestration for [pi](https://github.com/earendil-works/pi).
 
-Provides a `delegate` tool that lets the main model delegate tasks to specialized pi child processes with configurable model roles, real-time TUI progress, and AI-generated summaries.
+Provides a `delegate` tool that lets the main model offload tasks to specialized pi child processes with configurable model roles, real-time TUI progress, and AI-generated summaries.
+
+## Design Philosophy
+
+**The main model is the decision maker; subagents are executors.**
+
+Your primary AI has the most complete context — it knows the full conversation history, project structure, and task at hand. Subagents are spawned with **clean, isolated contexts** to handle specific, well-defined tasks without polluting the main model's context window.
+
+This means:
+- **Subagents don't plan** — the main model decides what needs to be done and provides a clear task description
+- **Subagents don't orchestrate** — if a task requires multiple steps, the main model examines each result and decides the next move
+- **Subagents don't inherit history** — they don't need the full conversation; just a precise task description
+- **Multiple subagents can run in parallel** — emit multiple `delegate` calls in one turn; pi executes them concurrently
+- **Subagents can nest subagents** — a `worker` can delegate exploration to `explorer` without returning to the main model
+
+> This design intentionally excludes chain pipelines and context-forking — those patterns are better suited when subagents act as advisors (planner, oracle), not executors.
 
 ## How it works
 
@@ -15,17 +30,21 @@ Provides a `delegate` tool that lets the main model delegate tasks to specialize
 
 ## Built-in Roles
 
-| Role | Model Role | Tools | Description |
-|------|-----------|-------|-------------|
-| `explorer` | fast | read, bash, find, grep, glob | Fast code search (read-only) |
-| `reviewer` | heavy | read, bash, grep, glob | Deep code review (read-only) |
-| `worker` | default | read, bash, edit, write, grep, glob | Implementation with file editing |
-| `researcher` | fast | web_search, fetch_content, read | Web research and docs lookup |
+| Role | Model Role | Tools | Can Delegate To | Description |
+|------|-----------|-------|-----------------|-------------|
+| `explorer` | fast | read, find, grep, glob | — | Fast code search (read-only, no bash) |
+| `reviewer` | heavy | read, bash, grep, glob | — | Deep code review (read-only, bash for git/log) |
+| `worker` | default | read, bash, edit, write, grep, glob, delegate | explorer, researcher | Implementation — the only role that can modify files |
+| `researcher` | fast | web_search, fetch_content, read, bash, delegate | explorer | Web research + GitHub repo analysis |
+
+**Nested delegation**: `worker` and `researcher` can spawn their own subagents. This keeps the main model's context clean — a worker can explore unfamiliar code via an `explorer` subagent without returning intermediate results to the main model.
+
+**Parallel execution**: To run multiple subagents concurrently, emit multiple `delegate` calls in a single turn. Pi's framework executes them in parallel automatically, with each subagent getting its own TUI progress display.
 
 ## TUI Display
 
 - **During execution**: Shows role, elapsed time, turn count, and live tool calls
-- **Collapsed result**: `✓ explorer · 找到了登录/注册/token三块逻辑` + recent tool calls + usage stats
+- **Collapsed result**: `✓ explorer · Found login, registration, and token logic` + recent tool calls + usage stats
 - **Expanded result** (Ctrl+O): Full task text, all tool calls, final output as rendered Markdown, and usage details
 
 ## Requirements
@@ -37,7 +56,7 @@ Provides a `delegate` tool that lets the main model delegate tasks to specialize
 ## Installation
 
 ```bash
-pi extension add @d3ara1n/pi-subagent
+pi install @d3ara1n/pi-subagent
 ```
 
 ## Configuration
@@ -51,7 +70,7 @@ Edit `~/.pi/agent/settings.json`:
     "timeoutMs": 300000,
 
     // Summary generation — uses a lightweight model to create
-    // a one-line Chinese summary for the TUI display
+    // a one-line summary for the TUI display
     "summary": {
       "role": "utility",    // pi-model-roles role for summarization
       "enabled": true        // set false to disable
@@ -62,8 +81,51 @@ Edit `~/.pi/agent/settings.json`:
 
 All fields are optional. Defaults: `timeoutMs: 300000`, `summary.role: "utility"`, `summary.enabled: true`.
 
+### Agent Overrides
+
+Override, disable, or add subagent roles via `agentOverrides`. Built-in and custom roles are treated equally — all descriptions, examples, and decision triggers feed into the LLM's prompt dynamically.
+
+```jsonc
+{
+  "subagent": {
+    "agentOverrides": {
+      // ── Override a built-in role (only specify changed fields) ──
+      "worker": {
+        "role": "heavy"               // use a stronger model
+      },
+
+      // ── Disable a built-in role ──
+      "reviewer": {
+        "disabled": true
+      },
+
+      // ── Add a custom role (all required fields must be provided) ──
+      "tester": {
+        "role": "default",
+        "description": "Test automation & QA — write and run tests, validate fixes. Tools: read, bash, edit, write, grep. Can delegate to explorer.",
+        "examples": [
+          "Write unit tests for the auth module",
+          "Run the test suite and fix failing tests"
+        ],
+        "decisionTrigger": "Task writes or runs tests?",
+        "tools": ["read", "bash", "edit", "write", "grep"],
+        "systemPrompt": "QA engineer. Write tests, run them, fix failures. After each change, re-run affected tests."
+      }
+    }
+  }
+}
+```
+
+**Required fields for custom roles:** `role`, `description`, `examples`, `decisionTrigger`, `tools`, `systemPrompt`.
+
+**Optional fields:** `subagentRoles` (roles this role can spawn via delegate), `fallbackRole` (backup pi-model-roles role on provider errors).
+
+Invalid custom roles (missing required fields) are silently skipped with an error notification at session start.
+
 ## Usage (by the main model)
 
+Delegate tasks that would generate many tool calls or verbose output to keep your own context clean:
+
 ```json
 {
   "role": "explorer",
@@ -71,6 +133,24 @@ All fields are optional. Defaults: `timeoutMs: 300000`, `summary.role: "utility"
 }
 ```
 
+**Role-specific examples:**
+
+| Role | Example task | Why delegate? |
+|------|-------------|---------------|
+| `explorer` | `"Map the routing structure of src/api/"` | You only need the conclusion, not every grep result |
+| `reviewer` | `"Review error handling in auth.ts for security issues"` | Review output is longform; keep it isolated |
+| `worker` | `"Rename all snake_case fields to camelCase in src/models/"` | Your context stays focused on high-level intent |
+| `researcher` | `"Find the React 19 migration guide and summarize breaking changes"` | Search results are noisy; get a clean summary |
+
+**Parallel usage:** emit multiple `delegate` calls in a single turn:
+
+```json
+[
+  { "role": "explorer", "task": "Map the repository structure" },
+  { "role": "researcher", "task": "Find latest docs on the library used here" }
+]
+```
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "0.1.0",
+  "version": "0.3.0",
+  "type": "module",
   "description": "Role-based subagent orchestration for pi — delegates tasks to specialized pi child processes with configurable model roles",
   "main": "src/index.ts",
   "keywords": [

package/src/config.ts

@@ -59,5 +59,6 @@ export function loadSubagentConfig(cwd?: string): SubagentConfig {
 			role: rawSummary?.role ?? DEFAULT_CONFIG.summary.role,
 			enabled: rawSummary?.enabled ?? DEFAULT_CONFIG.summary.enabled,
 		},
+		agentOverrides: raw.agentOverrides ?? {},
 	};
 }

package/src/index.ts

@@ -15,11 +15,11 @@ import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import type { ModelRolesAPI } from "@d3ara1n/pi-model-roles";
 import { getModelRolesAPI } from "@d3ara1n/pi-model-roles";
-import type { SubagentConfig, SubagentDetails, SubagentResult } from "./types.ts";
+import type { SubagentConfig, SubagentDetails, SubagentResult, SubagentRole, ToolStatus, ActivityEntry } from "./types.ts";
 import { DEFAULT_CONFIG } from "./types.ts";
 import { loadSubagentConfig } from "./config.ts";
 import { BUILTIN_ROLES } from "./roles.ts";
-import { spawnSubagent } from "./spawn.ts";
+import { spawnSubagent, getPiInvocation } from "./spawn.ts";
 import * as os from "node:os";
 
 // ── Helpers ────────────────────────────────────────────────────────
@@ -44,25 +44,23 @@ function formatUsageStats(usage: SubagentResult["usage"], model?: string): strin
 }
 
 type DisplayItem =
-	| { type: "text"; text: string }
-	| { type: "toolCall"; name: string; args: Record<string, any> };
-
-function getDisplayItems(messages: SubagentResult["messages"]): DisplayItem[] {
-	const items: DisplayItem[] = [];
-	for (const msg of messages) {
-		if (msg.role === "assistant") {
-			for (const part of msg.content) {
-				if (part.type === "text" && part.text) items.push({ type: "text", text: part.text });
-				else if (part.type === "toolCall" && part.name)
-					items.push({ type: "toolCall", name: part.name, args: part.arguments ?? {} });
-			}
-		}
-	}
-	return items;
+	| { type: "toolCall"; name: string; args: Record<string, any>; status?: ToolStatus }
+	| { type: "thinking"; status?: ToolStatus };
+
+/** Map the real-time activity log into renderable display items (in order). */
+function buildDisplayItems(activityLog: ActivityEntry[]): DisplayItem[] {
+	return activityLog.map((a) =>
+		a.kind === "thinking"
+			? { type: "thinking", status: a.status }
+			: { type: "toolCall", name: a.toolName ?? "?", args: a.args ?? {}, status: a.status },
+	);
 }
 
 function shortenPath(p: string): string {
 	const home = os.homedir();
+	if (process.platform === "win32") {
+		return p.toLowerCase().startsWith(home.toLowerCase()) ? `~${p.slice(home.length)}` : p;
+	}
 	return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
 }
 
@@ -123,6 +121,35 @@ function formatToolCall(
 	}
 }
 
+/** Per-tool-call visual styling: prefix glyph + color function keyed by status. */
+function statusStyle(
+	status: ToolStatus | undefined,
+	fg: (color: string, text: string) => string,
+): { prefix: string; color: (c: string, text: string) => string } {
+	switch (status) {
+		case "running":
+			return { prefix: fg("accent", "\u25CF "), color: fg };
+		case "failed":
+			return { prefix: fg("error", "\u2717 "), color: (_c, text) => fg("error", text) };
+		case "done":
+		default:
+			return { prefix: fg("dim", "\u2192 "), color: (_c, text) => fg("dim", text) };
+	}
+}
+
+/** Render a thinking-block row: diamond glyph + label, colored by status.
+ * Running = hollow diamond (unformed thought); done = solid diamond (settled). */
+function formatThinking(
+	status: ToolStatus | undefined,
+	fg: (color: string, text: string) => string,
+): string {
+	if (status === "running") {
+		return fg("accent", "\u25C7 thinking");
+	}
+	// done (or unknown) — dim past tense, solid diamond
+	return fg("dim", "\u25C6 thought");
+}
+
 function renderDisplayItems(
 	items: DisplayItem[],
 	limit: number | undefined,
@@ -133,11 +160,11 @@ function renderDisplayItems(
 	let text = "";
 	if (skipped > 0) text += fg("muted", `... ${skipped} earlier items\n`);
 	for (const item of toShow) {
-		if (item.type === "text") {
-			const preview = item.text.split("\n").slice(0, 3).join("\n");
-			text += `${fg("toolOutput", preview.length > 120 ? preview.slice(0, 120) + "..." : preview)}\n`;
+		if (item.type === "thinking") {
+			text += `${formatThinking(item.status, fg)}\n`;
 		} else {
-			text += `${fg("muted", "\u2192 ")}${formatToolCall(item.name, item.args, fg)}\n`;
+			const { prefix, color } = statusStyle(item.status, fg);
+			text += `${prefix}${formatToolCall(item.name, item.args, color)}\n`;
 		}
 	}
 	return text.trimEnd();
@@ -172,12 +199,20 @@ async function generateSummary(
 		const resolved = await rolesApi.resolveRoleAsync(summaryConfig.role);
 		if (!resolved.model) return undefined;
 
+		// Truncate large outputs to avoid wasting summary tokens (keep head + tail)
+		const SUMMARY_MAX_INPUT = 4000;
+		let summaryInput = outputText;
+		if (summaryInput.length > SUMMARY_MAX_INPUT) {
+			const half = Math.floor(SUMMARY_MAX_INPUT / 2);
+			summaryInput = summaryInput.slice(0, half) + "\n\n... [truncated for summary] ...\n\n" + summaryInput.slice(-half);
+		}
+
 		const result = await complete(
 			resolved.model,
 			{
 				systemPrompt:
-					"Summarize the following agent output in one concise Chinese sentence (max 60 characters). Focus on what was accomplished, not how. Output only the summary, no preamble.",
-				messages: [{ role: "user", content: outputText }],
+					"Summarize the following agent output in one concise sentence (max 60 characters). Respond in the same language as the input. Focus on what was accomplished, not how. Output only the summary, no preamble.",
+				messages: [{ role: "user", content: summaryInput, timestamp: Date.now() }],
 			},
 			{
 				maxTokens: 100,
@@ -194,7 +229,12 @@ async function generateSummary(
 
 		return text || undefined;
 	} catch {
-		return undefined;
+		// Fall back to manual truncation: use first line of output as summary
+		const trimmed = outputText.trim();
+		if (!trimmed) return undefined;
+		const firstLine = trimmed.split("\n")[0];
+		if (firstLine.length <= 65) return firstLine;
+		return firstLine.slice(0, 62) + "...";
 	}
 }
 
@@ -203,51 +243,126 @@ async function generateSummary(
 export default function subagentExtension(pi: ExtensionAPI) {
 	let config: SubagentConfig = DEFAULT_CONFIG;
 
+	// If spawned as a child by a parent subagent, PI_SUBAGENT_ALLOWED restricts
+	// which roles are available. Filter before any tool description sees them.
+	const ALLOWLIST: string[] | undefined = (() => {
+		const raw = process.env.PI_SUBAGENT_ALLOWED;
+		if (!raw) return undefined;
+		const list = raw.split(",").map((s) => s.trim()).filter(Boolean);
+		return list.length > 0 ? list : undefined;
+	})();
+
+	const availableRoles: Record<string, SubagentRole> = {};
+	for (const [name, role] of Object.entries(BUILTIN_ROLES)) {
+		if (!ALLOWLIST || ALLOWLIST.includes(name)) {
+			availableRoles[name] = role;
+		}
+	}
+
+	// Mutable guidelines array — rebuilt in session_start to reflect agentOverrides
+	const guidelines: string[] = [];
+
+	function rebuildGuidelines(roles: Record<string, SubagentRole>): void {
+		const entries = Object.entries(roles);
+		const exampleLines: string[] = [];
+		const decisionLines: string[] = [];
+
+		for (const [name, role] of entries) {
+			// Decision flow
+			decisionLines.push(`  ${role.decisionTrigger} → delegate(${name})`);
+
+			// Concrete examples — one line per role with comma-separated examples
+			const quotedExamples = role.examples.map((e) => `"${e}"`).join(", ");
+			exampleLines.push(`  delegate(${name}):  ${quotedExamples}`);
+		}
+
+		guidelines.length = 0;
+		guidelines.push(
+			"WHEN TO DELEGATE — offload substantial work when you only need the result:",
+			"",
+			"- Delegate ONLY when a task involves significant work (heavy analysis, multi-step investigation, large-scope changes) AND you only care about the conclusion, not intermediate steps.",
+			"- DO NOT delegate simple tasks: a single read, a one-line edit, a basic grep. Just do them yourself.",
+			"- DO NOT delegate straightforward file modifications touching 1-2 files. Use edit/write directly.",
+			"- Delegation has overhead (spawning a child process). Reserve it for tasks that would genuinely clutter your context with 3+ turns of raw tool output.",
+			"",
+			"AVAILABLE ROLES:",
+			...entries.map(([name, role]) => `  - ${name}: ${role.description}`),
+			"",
+			"DECISION FLOW (which role for what):",
+			"",
+			...decisionLines,
+			"",
+			"CONCRETE EXAMPLES of good delegation targets:",
+			"",
+			...exampleLines,
+			"",
+			"For multiple independent substantial tasks, emit multiple delegate calls in one turn — they run in parallel.",
+			"Include ALL necessary context — subagents have no access to this conversation.",
+		);
+	}
+
+	// Apply agent overrides on top of built-in roles
+	function applyAgentOverrides(roles: Record<string, SubagentRole>, overrides: Record<string, any>): void {
+		for (const [name, override] of Object.entries(overrides)) {
+			if (override.disabled) {
+				delete roles[name];
+			} else if (roles[name]) {
+				roles[name] = { ...roles[name], ...override };
+			} else {
+				// Custom role — must provide all required fields (validated in session_start)
+				roles[name] = override as SubagentRole;
+			}
+		}
+	}
+
+	// Initial guidelines from built-in roles
+	rebuildGuidelines(availableRoles);
+
 	pi.on("session_start", async (_event, ctx) => {
 		config = loadSubagentConfig(ctx.cwd);
+		applyAgentOverrides(availableRoles, config.agentOverrides);
+
+		// Validate custom roles (skip built-in roles — they already have all fields)
+		const REQUIRED_FIELDS = ["role", "description", "examples", "decisionTrigger", "tools", "systemPrompt"] as const;
+		for (const [name, role] of Object.entries(availableRoles)) {
+			if (name in BUILTIN_ROLES) continue;
+			const missing = REQUIRED_FIELDS.filter((f) => !(f in (role as any)));
+			if (missing.length > 0) {
+				delete availableRoles[name];
+				ctx.ui.notify(
+					`[pi-subagent] Custom role "${name}" skipped — missing: ${missing.join(", ")}. Required: ${REQUIRED_FIELDS.join(", ")}.`,
+					"error",
+				);
+			}
+		}
+
+		rebuildGuidelines(availableRoles);
 	});
 
 	pi.registerTool({
 		name: "delegate",
 		label: "Delegate to subagent",
-		description: [
-			"Delegate a task to a specialized subagent with isolated context.",
-			"Available roles:",
-			"  - explorer: fast code search and navigation (read-only)",
-			"  - reviewer: deep code review with evidence (read-only)",
-			"  - worker: implementation with file editing capabilities",
-			"  - researcher: web research and documentation lookup",
-			"",
-			"Progress is shown in real-time via TUI (tool calls, turns, elapsed time).",
-			"Use Ctrl+O on a completed result to see full details.",
-			"",
-			"Note: Subagents only have built-in tools (read, bash, edit, write, grep, glob, find, web_search, fetch_content). They do NOT have access to MCP tools or custom tools from the main session.",
-		].join("\n"),
+		description: "Offload work to a specialized subagent to keep your own context clean and focused. Prefer this over doing work yourself when a task would generate many tool calls or verbose output. Subagents have isolated context — include all necessary info in the task description.",
+		promptSnippet: "Delegate tasks to specialized subagents",
+		promptGuidelines: guidelines,
 
 		parameters: Type.Object({
-			role: Type.Union(
-				[
-					Type.Literal("explorer"),
-					Type.Literal("reviewer"),
-					Type.Literal("worker"),
-					Type.Literal("researcher"),
-				],
-				{ description: "Subagent role to use" },
-			),
+			role: Type.String({ description: "Subagent role to use" }),
 			task: Type.String({ description: "Specific task for the subagent" }),
 			cwd: Type.Optional(Type.String({ description: "Working directory (defaults to current)" })),
 		}),
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
-			const roleDef = BUILTIN_ROLES[params.role];
+			const roleDef = availableRoles[params.role];
 			if (!roleDef) {
 				return {
 					content: [
 						{
 							type: "text",
-							text: `Unknown subagent role: ${params.role}. Available: ${Object.keys(BUILTIN_ROLES).join(", ")}`,
+							text: `Unknown subagent role: ${params.role}. Available: ${Object.keys(availableRoles).join(", ")}`,
 						},
 					],
+					details: undefined as any,
 				};
 			}
 
@@ -258,6 +373,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
 			} catch {
 				return {
 					content: [{ type: "text", text: "pi-model-roles is not initialized. Cannot resolve model for subagent." }],
+					details: undefined as any,
 				};
 			}
 
@@ -265,6 +381,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
 			if (!resolved.model) {
 				return {
 					content: [{ type: "text", text: `Role "${roleDef.role}" could not be resolved. Model not available.` }],
+					details: undefined as any,
 				};
 			}
 
@@ -281,6 +398,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
 					output: "",
 					stderr: "",
 					usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+					activityLog: [],
 				};
 				onUpdate({
 					content: [{ type: "text", text: `${params.role}: running...` }],
@@ -289,10 +407,11 @@ export default function subagentExtension(pi: ExtensionAPI) {
 			}
 
 			try {
-				const result = await spawnSubagent(modelRef, params.task, {
+				let result = await spawnSubagent(modelRef, params.task, {
 					cwd: params.cwd ?? ctx.cwd,
 					tools: roleDef.tools,
 					systemPrompt: roleDef.systemPrompt,
+					subagentRoles: roleDef.subagentRoles,
 					timeoutMs: config.timeoutMs,
 					signal,
 					onProgress: (partial) => {
@@ -316,6 +435,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
 							},
 							model: partial.model,
 							stopReason: partial.stopReason,
+							activityLog: partial.activityLog ?? [],
 						};
 						const statusText = `${params.role}  ${elapsed}s  ${liveResult.usage.turns} turn${liveResult.usage.turns !== 1 ? "s" : ""}`;
 						onUpdate({
@@ -325,6 +445,27 @@ export default function subagentExtension(pi: ExtensionAPI) {
 					},
 				});
 
+				// Retry with fallback role on provider errors (quota, auth, timeout, etc.)
+				if ((result.exitCode !== 0 || result.errorMessage) && roleDef.fallbackRole) {
+					const isProviderError = /429|quota|rate.?limit|auth|timeout|exhausted|unavailable/i.test(
+						(result.stderr || "") + (result.errorMessage || ""),
+					);
+					if (isProviderError) {
+						const fallback = await rolesApi.resolveRoleAsync(roleDef.fallbackRole);
+						if (fallback.model) {
+							const fbRef = `${fallback.model.provider}/${fallback.model.id}`;
+							result = await spawnSubagent(fbRef, params.task, {
+								cwd: params.cwd ?? ctx.cwd,
+								tools: roleDef.tools,
+								systemPrompt: roleDef.systemPrompt,
+								subagentRoles: roleDef.subagentRoles,
+								timeoutMs: config.timeoutMs,
+								signal,
+							});
+						}
+					}
+				}
+
 				// Generate summary for TUI display
 				if (config.summary.enabled && result.output.trim()) {
 					result.summary = await generateSummary(rolesApi, result.output, config.summary);
@@ -399,7 +540,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
 			} else {
 				icon = theme.fg("success", "\u2713");
 			}
-			const displayItems = getDisplayItems(r.messages);
+			const displayItems = buildDisplayItems(r.activityLog);
 			const finalOutput = getFinalOutput(r.messages);
 			const mdTheme = getMarkdownTheme();
 
@@ -420,20 +561,21 @@ export default function subagentExtension(pi: ExtensionAPI) {
 				}
 
 				container.addChild(new Spacer(1));
-				const toolCalls = displayItems.filter((item) => item.type === "toolCall");
-				if (toolCalls.length === 0) {
+				const activity = displayItems.filter((item) => item.type === "toolCall" || item.type === "thinking");
+				if (activity.length === 0) {
 					const runningLabel = isRunning ? "(waiting for first event...)" : "(none)";
 					container.addChild(new Text(theme.fg("muted", runningLabel), 0, 0));
 				} else {
-					for (const item of toolCalls) {
-						container.addChild(
-							new Text(
-								theme.fg("muted", "\u2192 ") +
-									formatToolCall(item.name, item.args, theme.fg.bind(theme)),
-								0,
-								0,
-							),
-						);
+					const fg = theme.fg.bind(theme) as (color: string, text: string) => string;
+					for (const item of activity) {
+						if (item.type === "thinking") {
+							container.addChild(new Text(formatThinking(item.status, fg), 0, 0));
+						} else {
+							const { prefix, color } = statusStyle(item.status, fg);
+							container.addChild(
+								new Text(prefix + formatToolCall(item.name, item.args, color), 0, 0),
+							);
+						}
 					}
 				}
 
@@ -457,11 +599,11 @@ export default function subagentExtension(pi: ExtensionAPI) {
 
 			if (isRunning) {
 				// Running: show recent tool calls only
-				const toolCalls = displayItems.filter((item) => item.type === "toolCall");
-				if (toolCalls.length === 0) {
+				const activity = displayItems.filter((item) => item.type === "toolCall" || item.type === "thinking");
+				if (activity.length === 0) {
 					text += `\n${theme.fg("muted", "(running...)")}`;
 				} else {
-					const rendered = renderDisplayItems(toolCalls, 5, theme.fg.bind(theme));
+					const rendered = renderDisplayItems(activity, 5, theme.fg.bind(theme) as (color: string, text: string) => string);
 					if (rendered) text += `\n${rendered}`;
 				}
 			} else {
@@ -469,8 +611,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
 				if (r.summary) {
 					text += ` ${theme.fg("dim", "\u00b7")} ${theme.fg("text", r.summary)}`;
 				}
-				if (isError && r.errorMessage) {
-					text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
+				if (isError) {
+					const errMsg = r.errorMessage || (r.stderr ? r.stderr.trim().split("\n")[0].slice(0, 80) : r.stopReason);
+					if (errMsg) text += `\n${theme.fg("error", `Error: ${errMsg}`)}`;
 				}
 				const usageStr = formatUsageStats(r.usage, r.model);
 				if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
@@ -478,4 +621,59 @@ export default function subagentExtension(pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 	});
+
+	pi.registerCommand("subagent:doctor", {
+		description: "Diagnose pi-subagent configuration and dependencies",
+		handler: async (_args, ctx) => {
+			const lines: string[] = [];
+			let allOk = true;
+
+			// 1. pi executable
+			const inv = getPiInvocation(["--version"]);
+			lines.push(`[\u2713] pi invocation: ${inv.command} ${inv.args.slice(0, 1).join(" ")}`);
+
+			// 2. pi-model-roles
+			try {
+				const api = getModelRolesAPI();
+				lines.push("[\u2713] pi-model-roles: loaded");
+
+				// 3. config
+				try {
+					const cfg = loadSubagentConfig(ctx.cwd);
+					lines.push(`[\u2713] config: timeout=${cfg.timeoutMs}ms summary=${cfg.summary.enabled ? cfg.summary.role : "off"}`);
+				} catch {
+					lines.push("[\u2717] config: failed to load");
+					allOk = false;
+				}
+
+				// 4. roles
+				for (const [name, role] of Object.entries(availableRoles)) {
+					try {
+						const resolved = await api.resolveRoleAsync(role.role);
+						if (resolved.model) {
+							lines.push(`[\u2713] role ${name}: \u2192 ${resolved.model.provider}/${resolved.model.id}`);
+						} else {
+							lines.push(`[\u2717] role ${name}: model not resolved (role config: ${role.role})`);
+							allOk = false;
+						}
+					} catch {
+						lines.push(`[\u2717] role ${name}: resolution failed`);
+						allOk = false;
+					}
+				}
+			} catch {
+				lines.push("[\u2717] pi-model-roles: not initialized");
+				allOk = false;
+			}
+
+			// 5. ALLOWLIST
+			const allowed = process.env.PI_SUBAGENT_ALLOWED;
+			if (allowed) {
+				lines.push(`[i] PI_SUBAGENT_ALLOWED: ${allowed}`);
+			}
+
+			const summary = allOk ? "All checks passed" : "Some checks failed";
+			ctx.ui.notify(`${summary}\n\n${lines.join("\n")}`, "info");
+		},
+	});
 }

package/src/roles.ts

@@ -11,47 +11,99 @@ import type { SubagentRole } from "./types.ts";
 export const BUILTIN_ROLES: Record<string, SubagentRole> = {
   explorer: {
     role: "fast",
-    tools: ["read", "bash", "find", "grep", "glob"],
+    fallbackRole: "default",
+    description: "READ-ONLY codebase exploration — locate files, grep symbols, trace imports, explain structures. Tools: read, find, grep, glob. NO bash, NO edits, NO web access.",
+    examples: [
+      "Find where auth middleware is implemented",
+      "Map the routing structure",
+    ],
+    decisionTrigger: "Task finds or maps code without touch?",
+    tools: ["read", "find", "grep", "glob"],
     systemPrompt: [
-      "You are a fast code explorer. Investigate the codebase and answer the task query.",
-      "You must NOT edit any files.",
+      "Fast code explorer. You have READ-ONLY tools only — no commands, no edits.",
+      "Grep/find to locate → read key sections only → identify types, interfaces, functions.",
+      "Never read entire files. Target specific line ranges.",
       "",
-      "Output accurately and concisely. State findings directly with file paths and line numbers.",
-      "Keep the final output as short as possible while preserving all actionable information.",
+      "Output format (keep each section brief):",
+      "## Files: file paths with line ranges and one-line descriptions",
+      "## Findings: key types/functions with minimal code snippets",
+      "## Summary: direct answer to the task question",
     ].join("\n"),
   },
   reviewer: {
     role: "heavy",
+    fallbackRole: "default",
+    description: "READ-ONLY code review & analysis — audit code, assess architecture, review diffs. Tools: read, bash, grep, glob. Has bash (git diff/log, test runs). NO edits, NO web access.",
+    examples: [
+      "Review the error handling in src/api/ for security issues",
+      "Audit this PR diff for performance regressions",
+    ],
+    decisionTrigger: "Task audits or reviews code quality?",
     tools: ["read", "bash", "grep", "glob"],
     systemPrompt: [
-      "You are a senior code reviewer. Inspect code for correctness, maintainability, and security issues.",
-      "You must NOT edit any files.",
+      "Senior code reviewer. READ-ONLY — you must NOT modify any file.",
+      "bash is for read-only commands only (git diff/log/show, test runs). Never use sed, tee, echo >, or any write command.",
+      "Provide evidence-backed findings with file:line references.",
       "",
-      "Provide evidence-backed findings with file/line references.",
-      'Use bash only for read-only commands: git diff, git log, git show.',
-      "",
-      "Output accurately and concisely. Prioritize critical issues first.",
+      "Output format (prioritize critical issues first):",
+      "## Issues: severity + file:line + description + suggested fix",
+      "## Observations: notable patterns or design concerns",
+      "## Summary: overall assessment in 1-2 sentences",
     ].join("\n"),
   },
   worker: {
     role: "default",
-    tools: ["read", "bash", "edit", "write", "grep", "glob"],
+    description: "the ONLY role that can MODIFY files — edit, write, refactor, fix, implement. Tools: read, bash, edit, write, grep, glob, delegate. Can delegate to explorer/researcher.",
+    examples: [
+      "Rename all snake_case fields to camelCase",
+      "Add input validation to POST /login",
+    ],
+    decisionTrigger: "Task modifies files?",
+    tools: ["read", "bash", "edit", "write", "grep", "glob", "delegate"],
+    subagentRoles: ["explorer", "researcher"],
     systemPrompt: [
-      "You are an implementation worker. Follow the given plan precisely.",
-      "Make minimal, focused changes. Validate your work after each change.",
+      "Implementation worker. Work autonomously — all context is in the task description.",
+      "Always read a file before editing it. Make minimal, focused changes.",
+      "After each change, validate: run tests, check syntax, verify behavior.",
+      "",
+      "## Protecting your context",
+      "You have a `delegate` tool. Use it to offload exploration and research:",
+      "- delegate(role=explorer) when you need to map unfamiliar code before editing",
+      "- delegate(role=researcher) when you need external docs or library references",
+      "Don't delegate tasks you can do with a single read or grep.",
       "",
-      "When finished, report what you changed and what validation you ran.",
-      "Output accurately and concisely — summarize changes, don't repeat full diffs.",
+      "Output format (be brief — summarize, don't paste full diffs):",
+      "## Changes: list each file touched and what changed",
+      "## Verification: what you ran to confirm correctness",
     ].join("\n"),
   },
   researcher: {
     role: "fast",
-    tools: ["web_search", "fetch_content", "read"],
+    fallbackRole: "default",
+    description: "the ONLY role with WEB ACCESS — search docs, fetch pages, analyze GitHub repos. Tools: web_search, fetch_content, read, bash, delegate. Can clone repos & delegate to explorer.",
+    examples: [
+      "Find the React 19 migration guide",
+      "Check GitHub issue #1234 for context",
+    ],
+    decisionTrigger: "Task searches web or GitHub?",
+    tools: ["web_search", "fetch_content", "read", "bash", "delegate"],
+    subagentRoles: ["explorer"],
     systemPrompt: [
-      "You are a web researcher. Find relevant documentation, examples, and best practices.",
+      "Web researcher. Search with varied angles, prefer official docs over blogs.",
+      "If first results are insufficient, refine queries and search again.",
+      "",
+      "## GitHub repo analysis",
+      "When the task requires analyzing a GitHub repo:",
+      "1. git clone the repo into PI_SUBAGENT_TMPDIR (must exist)",
+      "2. Use `delegate` with role=explorer to investigate the cloned codebase — pass the repo path and the research question",
+      "3. Combine explorer findings with any web search results",
+      "",
+      "bash is for git clone and read-only commands only. Never modify files.",
       "",
-      "Return concise summaries with source links.",
-      "Output accurately and concisely — state key findings first, then supporting details if needed.",
+      "Output format:",
+      "## Answer: direct answer to the question (2-3 sentences)",
+      "## Sources: list of URLs used",
+      "## Gaps: what could not be answered",
     ].join("\n"),
   },
 };

package/src/spawn.ts

@@ -10,28 +10,106 @@ 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 { fileURLToPath } from "node:url";
 import type { SubagentMessage, SubagentResult } from "./types.ts";
 
-/** Determine how to invoke pi.
+/** Maximum task length before writing to a temp file (avoids CLI arg limits). */
+const TASK_CHAR_LIMIT = 8000;
+
+/** Maximum output characters returned to the main model. Larger outputs are truncated. */
+const MAX_OUTPUT_CHARS = 50_000;
+
+const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
+
+function isRunnableScript(filePath: string): boolean {
+	try {
+		if (!fs.existsSync(filePath)) return false;
+		return /\.(?:mjs|cjs|js)$/i.test(filePath);
+	} catch {
+		return false;
+	}
+}
+
+function findPiPackageRootFromEntry(entryPoint: string): string | undefined {
+	let dir = path.dirname(entryPoint);
+	while (dir !== path.dirname(dir)) {
+		const pkgPath = path.join(dir, "package.json");
+		if (fs.existsSync(pkgPath)) {
+			try {
+				const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as { name?: unknown };
+				if (pkg.name === PI_CODING_AGENT_PACKAGE) return dir;
+			} catch {
+				/* ignore */
+			}
+		}
+		dir = path.dirname(dir);
+	}
+	return undefined;
+}
+
+function resolveWindowsPiCliScript(args: string[]): { command: string; args: string[] } | undefined {
+	// Strategy 1: Use process.argv[1] if it's a runnable script
+	// (works when pi is run via `bun pi` or `bunx pi` — argv[1] is the real CLI path)
+	const argv1 = process.argv[1];
+	if (argv1) {
+		const argvPath = path.isAbsolute(argv1) ? argv1 : path.resolve(argv1);
+		if (isRunnableScript(argvPath)) {
+			return { command: process.execPath, args: [argvPath, ...args] };
+		}
+	}
+
+	// Strategy 2: Resolve pi-coding-agent package via import.meta.resolve,
+	// then read the bin field from its package.json
+	try {
+		const resolved = fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PACKAGE));
+		const root = findPiPackageRootFromEntry(resolved);
+		if (root) {
+			const pkgPath = path.join(root, "package.json");
+			const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as {
+				bin?: string | Record<string, string>;
+			};
+			const binField = pkg.bin;
+			const binPath =
+				typeof binField === "string"
+					? binField
+					: binField?.pi ?? Object.values(binField ?? {})[0];
+			if (binPath) {
+				const candidate = path.resolve(root, binPath);
+				if (isRunnableScript(candidate)) {
+					return { command: process.execPath, args: [candidate, ...args] };
+				}
+			}
+		}
+	} catch {
+		/* fall through */
+	}
+
+	return undefined;
+}
+
+/**
+ * Determine how to invoke pi.
  *
- * Always uses the `pi` CLI command. On Windows with Bun-compiled pi,
- * process.execPath returns a virtual path (B:/~BUN/root/pi.exe) that
- * leaks into the child model's context and causes it to run stray
- * diagnostic commands. Using the `pi` command from PATH avoids this.
+ * On Windows, attempts to find the pi CLI script via:
+ *   1. process.argv[1] (when run via `bun pi` or `bunx pi`)
+ *   2. import.meta.resolve of @earendil-works/pi-coding-agent → bin field
+ * If found, spawns process.execPath (bun) with the script path.
+ * Falls back to `pi` from PATH if neither works.
+ *
+ * On non-Windows, always uses the `pi` CLI command from PATH.
+ *
+ * This avoids the standalone compiled pi.exe's process.execPath
+ * (virtual Bun path like B:/~BUN/root/pi.exe) ever being passed
+ * to the child process, while still working when `pi` is not in PATH.
  */
-function getPiInvocation(args: string[]): { command: string; args: string[] } {
+export function getPiInvocation(args: string[]): { command: string; args: string[] } {
+	if (process.platform === "win32") {
+		const winResult = resolveWindowsPiCliScript(args);
+		if (winResult) return winResult;
+	}
 	return { command: "pi", args };
 }
 
-/** Write a system prompt to a temp file for --append-system-prompt. */
-async function writeTempPromptFile(prefix: string, content: string): Promise<{ dir: string; filePath: string }> {
-	const tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
-	const safeName = prefix.replace(/[^\w.-]+/g, "_");
-	const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
-	await fs.promises.writeFile(filePath, content, { encoding: "utf-8", mode: 0o600 });
-	return { dir: tmpDir, filePath };
-}
-
 /**
  * Spawn a pi child process with the given model and configuration.
  * Fires onProgress on each JSON event for streaming TUI updates.
@@ -48,6 +126,7 @@ export async function spawnSubagent(
 		cwd?: string;
 		tools?: string[];
 		systemPrompt?: string;
+		subagentRoles?: string[];
 		timeoutMs?: number;
 		signal?: AbortSignal;
 		onProgress?: (update: Partial<SubagentResult>) => void;
@@ -61,6 +140,7 @@ export async function spawnSubagent(
 		output: "",
 		stderr: "",
 		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+		activityLog: [],
 	};
 
 	let tmpDir: string | null = null;
@@ -74,14 +154,23 @@ export async function spawnSubagent(
 			args.push("--tools", options.tools.join(","));
 		}
 
-		if (options.systemPrompt?.trim()) {
-			const tmp = await writeTempPromptFile("delegate", options.systemPrompt);
-			tmpDir = tmp.dir;
-			tmpFile = tmp.filePath;
-			args.push("--append-system-prompt", tmpFile);
-		}
+		// Always create temp dir — used for prompt file, long task file, and as PI_SUBAGENT_TMPDIR for subagent work (e.g. git clone)
+		tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
 
-		args.push(`Task: ${task}`);
+		const promptContent = options.systemPrompt?.trim()
+			? options.systemPrompt + `\n\nPI_SUBAGENT_TMPDIR=${tmpDir}`
+			: `PI_SUBAGENT_TMPDIR=${tmpDir}`;
+		tmpFile = path.join(tmpDir, "prompt.md");
+		await fs.promises.writeFile(tmpFile, promptContent, { encoding: "utf-8", mode: 0o600 });
+		args.push("--append-system-prompt", tmpFile);
+
+		if (task.length > TASK_CHAR_LIMIT) {
+			const taskPath = path.join(tmpDir, "task.md");
+			await fs.promises.writeFile(taskPath, task, { encoding: "utf-8", mode: 0o600 });
+			args.push(`@${taskPath}`);
+		} else {
+			args.push(`Task: ${task}`);
+		}
 
 		// Spawn process
 		const invocation = getPiInvocation(args);
@@ -95,9 +184,12 @@ export async function spawnSubagent(
 				usage: { ...result.usage },
 				model: result.model,
 				stopReason: result.stopReason,
+				activityLog: result.activityLog.map((a) => ({ ...a })),
 			});
 		};
 
+		let thinkingCounter = 0;
+
 		const processLine = (line: string) => {
 			if (!line.trim()) return;
 			let event: any;
@@ -137,15 +229,63 @@ export async function spawnSubagent(
 				emitProgress();
 			}
 
-			if (event.type === "tool_result_end" && event.message) {
-				result.messages.push(event.message as SubagentMessage);
+			// Activity log: track thinking blocks and tool calls in arrival order.
+			// Both update in place so the TUI reflects real-time state.
+			if (event.type === "tool_execution_start" && event.toolCallId) {
+				result.activityLog.push({
+					kind: "toolCall",
+					id: event.toolCallId,
+					status: "running",
+					toolName: event.toolName,
+					args: event.args ?? {},
+				});
 				emitProgress();
+			} else if (event.type === "tool_execution_end" && event.toolCallId) {
+				const entry = result.activityLog.find((a) => a.id === event.toolCallId);
+				if (entry) entry.status = event.isError ? "failed" : "done";
+				emitProgress();
+			}
+
+			// Thinking-block lifecycle: pi wraps thinking_start/end inside
+			// message_update.assistantMessageEvent. These arrive BEFORE message_end,
+			// so we can't rely on messages[] to show real-time thinking state —
+			// register them in the activity log directly.
+			const aev = event.assistantMessageEvent;
+			if (event.type === "message_update" && aev) {
+				if (aev.type === "thinking_start") {
+					result.activityLog.push({
+						kind: "thinking",
+						id: `thinking-${thinkingCounter++}`,
+						status: "running",
+					});
+					emitProgress();
+				} else if (aev.type === "thinking_end") {
+					// Mark the most recent still-running thinking block as done.
+					for (let i = result.activityLog.length - 1; i >= 0; i--) {
+						if (result.activityLog[i].kind === "thinking" && result.activityLog[i].status === "running") {
+							result.activityLog[i].status = "done";
+							break;
+						}
+					}
+					emitProgress();
+				}
 			}
 		};
 
+		// Build env with optional subagent allowlist and tmpdir for researcher role
+		const childEnv: NodeJS.ProcessEnv = { ...process.env };
+		if (options.subagentRoles && options.subagentRoles.length > 0) {
+			childEnv.PI_SUBAGENT_ALLOWED = options.subagentRoles.join(",");
+		}
+		// Expose tmpdir as env var so subagent bash commands (e.g. git clone) can use it
+		childEnv.PI_SUBAGENT_TMPDIR = tmpDir;
+
+		let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+
 		const exitCode = await new Promise<number>((resolve) => {
 			const proc = spawn(invocation.command, invocation.args, {
 				cwd: options.cwd,
+				env: childEnv,
 				shell: false,
 				stdio: ["ignore", "pipe", "pipe"],
 			});
@@ -162,6 +302,7 @@ export async function spawnSubagent(
 			});
 
 			proc.on("close", (code) => {
+				if (timeoutHandle) clearTimeout(timeoutHandle);
 				if (buffer.trim()) processLine(buffer);
 				resolve(code ?? 0);
 			});
@@ -185,7 +326,7 @@ export async function spawnSubagent(
 
 			// Handle timeout
 			if (options.timeoutMs && options.timeoutMs > 0) {
-				setTimeout(() => {
+				timeoutHandle = setTimeout(() => {
 					if (!proc.killed) {
 						proc.kill("SIGTERM");
 						setTimeout(() => {
@@ -198,10 +339,16 @@ export async function spawnSubagent(
 
 		result.exitCode = exitCode;
 		if (wasAborted) throw new Error("Subagent was aborted");
+
+		// Truncate large outputs: keep head (findings) + tail (summary), drop middle
+		if (result.output.length > MAX_OUTPUT_CHARS) {
+			const head = result.output.slice(0, 30_000);
+			const tail = result.output.slice(-(MAX_OUTPUT_CHARS - 30_050));
+			result.output = `[Output truncated — ${result.output.length} chars total]\n\n${head}\n\n... [truncated] ...\n\n${tail}`;
+		}
 	} finally {
-		// Cleanup temp files
-		if (tmpFile) try { fs.unlinkSync(tmpFile); } catch { /* ignore */ }
-		if (tmpDir) try { fs.rmdirSync(tmpDir); } catch { /* ignore */ }
+		// Cleanup temp directory and all contents
+		if (tmpDir) try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* ignore */ }
 	}
 
 	return result;

package/src/types.ts

@@ -6,6 +6,12 @@
 export interface SubagentConfig {
   timeoutMs: number;
   summary: SubagentSummaryConfig;
+  /**
+   * Per-role overrides from settings.json. Keyed by role name.
+   * - Override built-in roles: provide fields to merge.
+   * - Disable built-in roles: set `disabled: true`.
+   */
+  agentOverrides: Record<string, Partial<SubagentRole> & { disabled?: boolean }>;
 }
 
 export interface SubagentSummaryConfig {
@@ -16,16 +22,41 @@ export interface SubagentSummaryConfig {
 export const DEFAULT_CONFIG: SubagentConfig = {
   timeoutMs: 300_000,
   summary: { role: "utility", enabled: true },
+  agentOverrides: {},
 };
 
 /** A built-in subagent role definition. */
 export interface SubagentRole {
   /** pi-model-roles role name to use for this subagent */
   role: string;
+  /** One-line description for the LLM prompt — what this role does and what tools it has */
+  description: string;
+  /** Example tasks to show in CONCRETE EXAMPLES section */
+  examples: string[];
+  /** Decision flow trigger phrase, e.g. "Task modifies files?" */
+  decisionTrigger: string;
   /** System prompt for the subagent */
   systemPrompt: string;
   /** Tools available to this subagent */
   tools: string[];
+  /** If this role has `delegate`, restrict which roles it may spawn. undefined = no restriction. */
+  subagentRoles?: string[];
+  /** Fallback pi-model-roles role name when this role's model is unavailable (provider error). Defaults to "default". */
+  fallbackRole?: string;
+}
+
+/** Status of an individual tool call within a subagent run. */
+export type ToolStatus = "running" | "done" | "failed";
+
+/** A single entry in the real-time activity log (thinking block or tool call). */
+export interface ActivityEntry {
+  kind: "thinking" | "toolCall";
+  /** Synthetic id (thinking-N) or the toolCallId from the event stream. */
+  id: string;
+  status: ToolStatus;
+  /** Tool name + args (toolCall only). */
+  toolName?: string;
+  args?: Record<string, any>;
 }
 
 /** Usage statistics from a subagent execution. */
@@ -87,6 +118,8 @@ export interface SubagentResult {
   stopReason?: string;
   /** Error message if failed */
   errorMessage?: string;
+  /** Real-time activity log: thinking blocks and tool calls in arrival order. */
+  activityLog: ActivityEntry[];
 }
 
 /** TUI details structure passed via tool result details. */