@d3ara1n/pi-subagent 0.1.0 → 0.2.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,12 +30,16 @@ 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
 
@@ -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,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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 } 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 ────────────────────────────────────────────────────────
@@ -63,6 +63,9 @@ function getDisplayItems(messages: SubagentResult["messages"]): DisplayItem[] {
 
 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;
 }
 
@@ -172,12 +175,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 }],
+				messages: [{ role: "user", content: summaryInput }],
 			},
 			{
 				maxTokens: 100,
@@ -194,7 +205,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,49 +219,123 @@ 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(", ")}`,
 						},
 					],
 				};
@@ -289,10 +379,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) => {
@@ -325,6 +416,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);
@@ -469,8 +581,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 +591,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.
+ *
+ * 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.
  *
- * 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.
+ * 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;
@@ -74,14 +153,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);
@@ -143,9 +231,20 @@ export async function spawnSubagent(
 			}
 		};
 
+		// 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 +261,7 @@ export async function spawnSubagent(
 			});
 
 			proc.on("close", (code) => {
+				if (timeoutHandle) clearTimeout(timeoutHandle);
 				if (buffer.trim()) processLine(buffer);
 				resolve(code ?? 0);
 			});
@@ -185,7 +285,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 +298,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,27 @@ 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;
 }
 
 /** Usage statistics from a subagent execution. */