pi-subagents 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [0.9.2] - 2026-02-19
+
+### Fixed
+- TUI crash on async subagent completion: "Rendered line exceeds terminal width." `render.ts` never truncated output to fit the terminal — widget lines (`agents.join(" -> ")`), chain visualizations, skills lists, and task previews could all exceed the terminal width. Added `truncLine` helper using pi-tui's `truncateToWidth`/`visibleWidth` and applied it to every `Text` widget and widget string. Task preview lengths are now dynamic based on terminal width instead of hardcoded.
+- Agent Manager scope badge showed `[built]` instead of `[builtin]` in list and detail views. Widened scope column to fit.
+
+## [0.9.1] - 2026-02-17
+
+### Fixed
+- Builtin agents were silently excluded from management listings, chain validation, and agent resolution. Added `allAgents()` helper that includes all three tiers (builtin, user, project) and applied it to `handleList`, `findAgents`, `availableNames`, and `unknownChainAgents`.
+- `resolveTarget` now blocks mutation of builtin agents with a clear error message suggesting the user create a same-named override, instead of allowing `fs.unlinkSync` or `fs.writeFileSync` on extension files.
+- Agent Manager TUI guards: delete and edit actions on builtin agents are blocked with an error status. Detail screen hides `[e]dit` from the footer for builtins. Scope badge shows `[builtin]` instead of falling through to `[proj]`.
+- Cloning a builtin agent set the scope to `"builtin"` at runtime (violating the `"user" | "project"` type), causing wrong badge display and the clone inheriting builtin protections until session reload. Now maps to `"user"`.
+- Agent Manager `loadEntries` suppresses builtins overridden by user/project agents, preventing duplicate entries in the TUI list.
+- `BUILTIN_AGENTS_DIR` resolved via `import.meta.url` instead of hardcoded `~/.pi/agent/extensions/subagent/agents` path. Works regardless of where the extension is installed.
+- `handleCreate` now warns when creating an agent that shadows a builtin (informational, not an error).
+
+### Changed
+- Simplified Agent Manager header from per-scope breakdown to total count (per-row badges already show scope).
+- Reviewer builtin model changed from `openai/gpt-5.2` to `openai-codex/gpt-5.3-codex`.
+- Removed `code-reviewer` builtin agent (redundant with `reviewer`).
+
 ## [0.9.0] - 2026-02-17
 
 ### Added
@@ -9,8 +31,7 @@
   - `scout` — fast codebase recon (claude-haiku-4-5)
   - `planner` — implementation plans from context (claude-opus-4-6, thinking: high)
   - `worker` — general-purpose execution (claude-sonnet-4-6)
-  - `reviewer` — validates implementation against plans (gpt-5.2, thinking: high)
-  - `code-reviewer` — bug hunting and code review (claude-opus-4-6, thinking: high)
+  - `reviewer` — validates implementation against plans (gpt-5.3-codex, thinking: high)
   - `context-builder` — analyzes requirements and codebase (claude-sonnet-4-6)
   - `researcher` — autonomous web research with search, evaluation, and synthesis (claude-sonnet-4-6)
 - **`"builtin"` agent source** — new third tier in agent discovery. Priority: builtin < user < project. Builtin agents appear in listings with a `[builtin]` badge and cannot be modified or deleted through management actions (create a same-named user agent to override instead).

package/README.md

@@ -26,13 +26,18 @@ Agents are markdown files with YAML frontmatter that define specialized subagent
 
 **Agent file locations:**
 
-| Scope | Path |
-|-------|------|
-| User | `~/.pi/agent/agents/{name}.md` |
-| Project | `.pi/agents/{name}.md` (searches up directory tree) |
+| Scope | Path | Priority |
+|-------|------|----------|
+| Builtin | `~/.pi/agent/extensions/subagent/agents/` | Lowest |
+| User | `~/.pi/agent/agents/{name}.md` | Medium |
+| Project | `.pi/agents/{name}.md` (searches up directory tree) | Highest |
 
 Use `agentScope` parameter to control discovery: `"user"`, `"project"`, or `"both"` (default; project takes priority).
 
+**Builtin agents:** The extension ships with ready-to-use agents — `scout`, `planner`, `worker`, `reviewer`, `context-builder`, and `researcher`. They load at lowest priority so any user or project agent with the same name overrides them. Builtin agents appear with a `[builtin]` badge in listings and cannot be modified through management actions (create a same-named user agent to override instead).
+
+> **Note:** The `researcher` agent uses `web_search`, `fetch_content`, and `get_search_content` tools which require the [pi-web-access](https://github.com/nicobailon/pi-web-access) extension. Install it with `pi install npm:pi-web-access`.
+
 **Agent frontmatter:**
 
 ```yaml

package/agent-management.ts

@@ -5,6 +5,7 @@ import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 import {
 	type AgentConfig,
 	type AgentScope,
+	type AgentSource,
 	type ChainConfig,
 	type ChainStepConfig,
 	discoverAgentsAll,
@@ -62,9 +63,13 @@ export function sanitizeName(name: string): string {
 	return name.toLowerCase().trim().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
 }
 
+function allAgents(d: { builtin: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] }): AgentConfig[] {
+	return [...d.builtin, ...d.user, ...d.project];
+}
+
 function availableNames(cwd: string, kind: "agent" | "chain"): string[] {
 	const d = discoverAgentsAll(cwd);
-	const items = kind === "agent" ? [...d.user, ...d.project] : d.chains;
+	const items = kind === "agent" ? allAgents(d) : d.chains;
 	return [...new Set(items.map((x) => x.name))].sort((a, b) => a.localeCompare(b));
 }
 
@@ -72,7 +77,7 @@ export function findAgents(name: string, cwd: string, scope: AgentScope = "both"
 	const d = discoverAgentsAll(cwd);
 	const raw = name.trim();
 	const sanitized = sanitizeName(raw);
-	return [...d.user, ...d.project]
+	return allAgents(d)
 		.filter((a) => (scope === "both" || a.source === scope) && (a.name === raw || a.name === sanitized))
 		.sort((a, b) => a.source.localeCompare(b.source));
 }
@@ -98,7 +103,7 @@ function nameExistsInScope(cwd: string, scope: ManagementScope, name: string, ex
 
 function unknownChainAgents(cwd: string, steps: ChainStepConfig[]): string[] {
 	const d = discoverAgentsAll(cwd);
-	const known = new Set([...d.user, ...d.project].map((a) => a.name));
+	const known = new Set(allAgents(d).map((a) => a.name));
 	return [...new Set(steps.map((s) => s.agent).filter((a) => !known.has(a)))].sort((a, b) => a.localeCompare(b));
 }
 
@@ -233,24 +238,28 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 	return undefined;
 }
 
-function resolveTarget<T extends { source: "user" | "project"; filePath: string }>(
+function resolveTarget<T extends { source: AgentSource; filePath: string }>(
 	kind: "agent" | "chain",
 	name: string,
 	matches: T[],
 	cwd: string,
 	scopeHint?: string,
 ): T | AgentToolResult<Details> {
-	if (matches.length === 0) {
+	const mutable = matches.filter((m) => m.source !== "builtin");
+	if (mutable.length === 0) {
+		if (matches.length > 0) {
+			return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' is builtin and cannot be modified. Create a same-named ${kind} in user or project scope to override it.`, true);
+		}
 		const available = availableNames(cwd, kind);
 		return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' not found. Available: ${available.join(", ") || "none"}.`, true);
 	}
-	if (matches.length === 1) return matches[0]!;
+	if (mutable.length === 1) return mutable[0]!;
 	const scope = asDisambiguationScope(scopeHint);
 	if (!scope) {
-		const paths = matches.map((m) => `${m.source}: ${m.filePath}`).join("\n");
+		const paths = mutable.map((m) => `${m.source}: ${m.filePath}`).join("\n");
 		return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' exists in both scopes. Specify agentScope: 'user' or 'project'.\n${paths}`, true);
 	}
-	const scoped = matches.filter((m) => m.source === scope);
+	const scoped = mutable.filter((m) => m.source === scope);
 	if (scoped.length === 0) return result(`${kind === "agent" ? "Agent" : "Chain"} '${name}' not found in scope '${scope}'.`, true);
 	if (scoped.length > 1) return result(`Multiple ${kind}s named '${name}' found in scope '${scope}': ${scoped.map((m) => m.filePath).join(", ")}`, true);
 	return scoped[0]!;
@@ -309,7 +318,7 @@ export function formatChainDetail(chain: ChainConfig): string {
 export function handleList(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	const scope = normalizeListScope(params.agentScope) ?? "both";
 	const d = discoverAgentsAll(ctx.cwd);
-	const agents = [...d.user, ...d.project].filter((a) => scope === "both" || a.source === scope).sort((a, b) => a.name.localeCompare(b.name));
+	const agents = allAgents(d).filter((a) => scope === "both" || a.source === "builtin" || a.source === scope).sort((a, b) => a.name.localeCompare(b.name));
 	const chains = d.chains.filter((c) => scope === "both" || c.source === scope).sort((a, b) => a.name.localeCompare(b.name));
 	const lines = ["Agents:", ...(agents.length ? agents.map((a) => `- ${a.name} (${a.source}): ${a.description}`) : ["- (none)"]), "", "Chains:", ...(chains.length ? chains.map((c) => `- ${c.name} (${c.source}): ${c.description}`) : ["- (none)"])];
 	return result(lines.join("\n"));
@@ -363,6 +372,7 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	const targetPath = path.join(targetDir, isChain ? `${name}.chain.md` : `${name}.md`);
 	if (fs.existsSync(targetPath)) return result(`File already exists at ${targetPath} but is not a valid ${isChain ? "chain" : "agent"} definition. Remove or rename it first.`, true);
 	const warnings: string[] = [];
+	if (!isChain && d.builtin.some((a) => a.name === name)) warnings.push(`Note: this shadows the builtin agent '${name}'.`);
 	if (isChain) {
 		const parsed = parseStepList(cfg.steps);
 		if (parsed.error) return result(parsed.error, true);

package/agent-manager-detail.ts

@@ -129,7 +129,7 @@ export function renderDetail(
 	theme: Theme,
 ): string[] {
 	const lines: string[] = [];
-	const scopeBadge = agent.source === "user" ? "[user]" : "[proj]";
+	const scopeBadge = agent.source === "builtin" ? "[builtin]" : agent.source === "project" ? "[proj]" : "[user]";
 	const headerText = ` ${agent.name} ${scopeBadge} ${formatPath(agent.filePath)} `;
 	lines.push(renderHeader(headerText, width, theme));
 	lines.push(row("", width, theme));
@@ -149,7 +149,10 @@ export function renderDetail(
 	const scrollInfo = formatScrollInfo(state.scrollOffset, Math.max(0, contentLines.length - (state.scrollOffset + DETAIL_VIEWPORT_HEIGHT)));
 	lines.push(row(scrollInfo ? ` ${theme.fg("dim", scrollInfo)}` : "", width, theme));
 
-	lines.push(renderFooter(" [l]aunch  [e]dit  [v] raw/resolved  [↑↓] scroll  [esc] back ", width, theme));
+	const footer = agent.source === "builtin"
+		? " [l]aunch  [v] raw/resolved  [↑↓] scroll  [esc] back "
+		: " [l]aunch  [e]dit  [v] raw/resolved  [↑↓] scroll  [esc] back ";
+	lines.push(renderFooter(footer, width, theme));
 	return lines;
 }
 

package/agent-manager-list.ts

@@ -1,4 +1,5 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
+import type { AgentSource } from "./agents.js";
 import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { pad, row, renderHeader, renderFooter, fuzzyFilter, formatScrollInfo } from "./render-helpers.js";
 
@@ -7,7 +8,7 @@ export interface ListAgent {
 	name: string;
 	description: string;
 	model?: string;
-	source: "user" | "project";
+	source: AgentSource;
 	kind: "agent" | "chain";
 	stepCount?: number;
 }
@@ -28,7 +29,7 @@ export type ListAction =
 	| { type: "run-parallel"; ids: string[] }
 	| { type: "close" };
 
-const LIST_VIEWPORT_HEIGHT = 12;
+const LIST_VIEWPORT_HEIGHT = 8;
 
 function selectionCount(selected: string[], id: string): number {
 	let count = 0;
@@ -162,11 +163,11 @@ export function renderList(
 	const filtered = fuzzyFilter(agents, state.filterQuery);
 	clampCursor(state, filtered);
 
-	const agentOnly = agents.filter((a) => a.kind === "agent");
-	const userCount = agentOnly.filter((a) => a.source === "user").length;
-	const projectCount = agentOnly.filter((a) => a.source === "project").length;
+	const agentCount = agents.filter((a) => a.kind === "agent").length;
 	const chainCount = agents.filter((a) => a.kind === "chain").length;
-	const headerText = ` Subagents [user: ${userCount}  project: ${projectCount}  chains: ${chainCount}] `;
+	const headerText = chainCount
+		? ` Subagents [${agentCount} agents  ${chainCount} chains] `
+		: ` Subagents [${agentCount}] `;
 	lines.push(renderHeader(headerText, width, theme));
 	lines.push(row("", width, theme));
 
@@ -189,7 +190,7 @@ export function renderList(
 		const innerW = width - 2;
 		const nameWidth = 16;
 		const modelWidth = 12;
-		const scopeWidth = 7;
+		const scopeWidth = 9;
 
 		for (let i = 0; i < visible.length; i++) {
 			const agent = visible[i]!;
@@ -207,7 +208,8 @@ export function renderList(
 			const modelDisplay = modelRaw.includes("/") ? modelRaw.split("/").pop() ?? modelRaw : modelRaw;
 			const nameText = isCursor ? theme.fg("accent", agent.name) : agent.name;
 			const modelText = theme.fg("dim", modelDisplay);
-			const scopeBadge = theme.fg("dim", agent.kind === "chain" ? "[chain]" : (agent.source === "user" ? "[user]" : "[proj]"));
+			const scopeLabel = agent.kind === "chain" ? "[chain]" : agent.source === "builtin" ? "[builtin]" : agent.source === "project" ? "[proj]" : "[user]";
+			const scopeBadge = theme.fg("dim", scopeLabel);
 			const descText = theme.fg("dim", agent.description);
 
 			const descWidth = Math.max(0, innerW - 1 - visibleWidth(prefix) - nameWidth - modelWidth - scopeWidth - 3);

package/agent-manager.ts

@@ -24,7 +24,7 @@ export type ManagerResult =
 	| { action: "launch-chain"; chain: ChainConfig; task: string; skipClarify?: boolean }
 	| undefined;
 
-export interface AgentData { user: AgentConfig[]; project: AgentConfig[]; chains: ChainConfig[]; userDir: string; projectDir: string | null; cwd: string; }
+export interface AgentData { builtin: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[]; chains: ChainConfig[]; userDir: string; projectDir: string | null; cwd: string; }
 type ManagerScreen = "list" | "detail" | "chain-detail" | "edit" | "edit-field" | "edit-prompt" | "task-input" | "confirm-delete" | "name-input" | "chain-edit" | "template-select" | "parallel-builder";
 interface AgentEntry { id: string; kind: "agent"; config: AgentConfig; isNew: boolean; }
 interface ChainEntry { id: string; kind: "chain"; config: ChainConfig; }
@@ -65,7 +65,8 @@ export class AgentManagerComponent implements Component {
 	constructor(private tui: TUI, private theme: Theme, private agentData: AgentData, private models: ModelInfo[], private skills: SkillInfo[], private done: (result: ManagerResult) => void) { this.loadEntries(); }
 
 	private loadEntries(): void {
-		const agents: AgentEntry[] = []; for (const config of this.agentData.user) agents.push({ id: `a${this.nextId++}`, kind: "agent", config: cloneConfig(config), isNew: false }); for (const config of this.agentData.project) agents.push({ id: `a${this.nextId++}`, kind: "agent", config: cloneConfig(config), isNew: false }); this.agents = agents;
+		const overridden = new Set([...this.agentData.user, ...this.agentData.project].map((c) => c.name));
+		const agents: AgentEntry[] = []; for (const config of this.agentData.builtin) { if (!overridden.has(config.name)) agents.push({ id: `a${this.nextId++}`, kind: "agent", config: cloneConfig(config), isNew: false }); } for (const config of this.agentData.user) agents.push({ id: `a${this.nextId++}`, kind: "agent", config: cloneConfig(config), isNew: false }); for (const config of this.agentData.project) agents.push({ id: `a${this.nextId++}`, kind: "agent", config: cloneConfig(config), isNew: false }); this.agents = agents;
 		const chains: ChainEntry[] = []; for (const config of this.agentData.chains) chains.push({ id: `c${this.nextId++}`, kind: "chain", config: cloneChainConfig(config) }); this.chains = chains;
 	}
 
@@ -104,8 +105,8 @@ export class AgentManagerComponent implements Component {
 
 	private enterNameInput(mode: NameInputState["mode"], sourceId?: string, template?: AgentTemplate): void {
 		const allowProject = Boolean(this.agentData.projectDir); let initial = ""; let scope: "user" | "project" = "user";
-		if (mode === "clone-agent" && sourceId) { const entry = this.getAgentEntry(sourceId); if (entry) { initial = `${entry.config.name}-copy`; scope = entry.config.source; } }
-		if (mode === "clone-chain" && sourceId) { const entry = this.getChainEntry(sourceId); if (entry) { initial = `${entry.config.name}-copy`; scope = entry.config.source; } }
+		if (mode === "clone-agent" && sourceId) { const entry = this.getAgentEntry(sourceId); if (entry) { initial = `${entry.config.name}-copy`; scope = entry.config.source === "project" ? "project" : "user"; } }
+		if (mode === "clone-chain" && sourceId) { const entry = this.getChainEntry(sourceId); if (entry) { initial = `${entry.config.name}-copy`; scope = entry.config.source === "project" ? "project" : "user"; } }
 		if (mode === "new-agent" && template && template.name !== "Blank") initial = slugTemplateName(template.name);
 		this.nameInputState = { mode, editor: createEditorState(initial), scope, allowProject, sourceId, template }; this.screen = "name-input";
 	}
@@ -334,12 +335,14 @@ export class AgentManagerComponent implements Component {
 		this.editState = null; this.enterDetail(entry); this.tui.requestRender();
 	}
 
+	private isBuiltin(id: string): boolean { const a = this.getAgentEntry(id); return a?.config.source === "builtin"; }
+
 	private handleListAction(action: ListAction): void {
 		switch (action.type) {
 			case "open-detail": { const agent = this.getAgentEntry(action.id); if (agent) { this.enterDetail(agent); return; } const chain = this.getChainEntry(action.id); if (chain) this.enterChainDetail(chain); return; }
 			case "clone": if (this.getAgentEntry(action.id)) this.enterNameInput("clone-agent", action.id); else if (this.getChainEntry(action.id)) this.enterNameInput("clone-chain", action.id); return;
 			case "new": this.enterTemplateSelect(); return;
-			case "delete": this.confirmDeleteId = action.id; this.screen = "confirm-delete"; return;
+			case "delete": { if (this.isBuiltin(action.id)) { this.statusMessage = { text: "Builtin agents cannot be deleted. Clone to user scope to override.", type: "error" }; return; } this.confirmDeleteId = action.id; this.screen = "confirm-delete"; return; }
 			case "run-chain": this.enterTaskInput(action.ids); return;
 			case "run-parallel": this.enterParallelBuilder(action.ids); return;
 			case "close": this.done(undefined); return;
@@ -348,7 +351,7 @@ export class AgentManagerComponent implements Component {
 
 	private handleDetailAction(action: DetailAction, entry: AgentEntry): void {
 		if (action.type === "back") { this.screen = "list"; return; }
-		if (action.type === "edit") { this.enterEdit(entry); return; }
+		if (action.type === "edit") { if (entry.config.source === "builtin") { this.statusMessage = { text: "Builtin agents cannot be edited. Clone to user scope to override.", type: "error" }; this.screen = "list"; return; } this.enterEdit(entry); return; }
 		if (action.type === "launch") { this.enterTaskInput([entry.id], "detail"); return; }
 	}
 

package/agent-selection.ts

@@ -4,9 +4,12 @@ export function mergeAgentsForScope(
 	scope: AgentScope,
 	userAgents: AgentConfig[],
 	projectAgents: AgentConfig[],
+	builtinAgents: AgentConfig[] = [],
 ): AgentConfig[] {
 	const agentMap = new Map<string, AgentConfig>();
 
+	for (const agent of builtinAgents) agentMap.set(agent.name, agent);
+
 	if (scope === "both") {
 		for (const agent of userAgents) agentMap.set(agent.name, agent);
 		for (const agent of projectAgents) agentMap.set(agent.name, agent);

package/agents/context-builder.md

@@ -0,0 +1,38 @@
+---
+name: context-builder
+description: Analyzes requirements and codebase, generates context and meta-prompt
+tools: read, grep, find, ls, bash, web_search
+model: claude-sonnet-4-6
+output: context.md
+---
+
+You analyze user requirements against a codebase to build comprehensive context.
+
+Given a user request (prose, user stories, requirements), you will:
+
+1. **Analyze the request** - Understand what the user wants to build
+2. **Search the codebase** - Find all relevant files, patterns, dependencies
+3. **Research if needed** - Look up APIs, libraries, best practices online
+4. **Generate output files** - You'll receive instructions about where to write
+
+When running in a chain, generate two files in the specified chain directory:
+
+**context.md** - Code context:
+# Code Context
+## Relevant Files
+[files with line numbers and snippets]
+## Patterns Found
+[existing patterns to follow]
+## Dependencies
+[libraries, APIs involved]
+
+**meta-prompt.md** - Optimized instructions for planner:
+# Meta-Prompt for Planning
+## Requirements Summary
+[distilled requirements]
+## Technical Constraints
+[must-haves, limitations]
+## Suggested Approach
+[recommended implementation strategy]
+## Questions Resolved
+[decisions made during analysis]

package/agents/planner.md

@@ -0,0 +1,46 @@
+---
+name: planner
+description: Creates implementation plans from context and requirements
+tools: read, grep, find, ls, write
+model: claude-opus-4-6
+thinking: high
+output: plan.md
+defaultReads: context.md
+---
+
+You are a planning specialist. You receive context and requirements, then produce a clear implementation plan.
+
+You must NOT make any changes. Only read, analyze, and plan.
+
+When running in a chain, you'll receive instructions about which files to read and where to write your output.
+
+Output format (plan.md):
+
+# Implementation Plan
+
+## Goal
+One sentence summary of what needs to be done.
+
+## Tasks
+Numbered steps, each small and actionable:
+1. **Task 1**: Description
+   - File: `path/to/file.ts`
+   - Changes: What to modify
+   - Acceptance: How to verify
+
+2. **Task 2**: Description
+   ...
+
+## Files to Modify
+- `path/to/file.ts` - what changes
+
+## New Files (if any)
+- `path/to/new.ts` - purpose
+
+## Dependencies
+Which tasks depend on others.
+
+## Risks
+Anything to watch out for.
+
+Keep the plan concrete. The worker agent will execute it.

package/agents/researcher.md

@@ -0,0 +1,51 @@
+---
+name: researcher
+description: Autonomous web researcher — searches, evaluates, and synthesizes a focused research brief
+tools: read, write, web_search, fetch_content, get_search_content
+model: anthropic/claude-sonnet-4-6
+output: research.md
+defaultProgress: true
+---
+
+You are a research specialist. Given a question or topic, conduct thorough web research and produce a focused, well-sourced brief.
+
+Process:
+1. Break the question into 2-4 searchable facets
+2. Search with `web_search` using `queries` (parallel, varied angles) and `curate: false`
+3. Read the answers. Identify what's well-covered, what has gaps, what's noise.
+4. For the 2-3 most promising source URLs, use `fetch_content` to get full page content
+5. Synthesize everything into a brief that directly answers the question
+
+Search strategy — always vary your angles:
+- Direct answer query (the obvious one)
+- Authoritative source query (official docs, specs, primary sources)
+- Practical experience query (case studies, benchmarks, real-world usage)
+- Recent developments query (only if the topic is time-sensitive)
+
+Evaluation — what to keep vs drop:
+- Official docs and primary sources outweigh blog posts and forum threads
+- Recent sources outweigh stale ones (check URL path for dates like /2025/01/)
+- Sources that directly address the question outweigh tangentially related ones
+- Diverse perspectives outweigh redundant coverage of the same point
+- Drop: SEO filler, outdated info, beginner tutorials (unless that's the audience)
+
+If the first round of searches doesn't fully answer the question, search again with refined queries targeting the gaps. Don't settle for partial answers when a follow-up search could fill them.
+
+Output format (research.md):
+
+# Research: [topic]
+
+## Summary
+2-3 sentence direct answer.
+
+## Findings
+Numbered findings with inline source citations:
+1. **Finding** — explanation. [Source](url)
+2. **Finding** — explanation. [Source](url)
+
+## Sources
+- Kept: Source Title (url) — why relevant
+- Dropped: Source Title — why excluded
+
+## Gaps
+What couldn't be answered. Suggested next steps.

package/agents/reviewer.md

@@ -0,0 +1,30 @@
+---
+name: reviewer
+description: Code review specialist that validates implementation and fixes issues
+tools: read, grep, find, ls, bash
+model: openai-codex/gpt-5.3-codex
+thinking: high
+defaultReads: plan.md, progress.md
+defaultProgress: true
+---
+
+You are a senior code reviewer. Analyze implementation against the plan.
+
+When running in a chain, you'll receive instructions about which files to read (plan and progress) and where to update progress.
+
+Bash is for read-only commands only: `git diff`, `git log`, `git show`.
+
+Review checklist:
+1. Implementation matches plan requirements
+2. Code quality and correctness
+3. Edge cases handled
+4. Security considerations
+
+If issues found, fix them directly.
+
+Update progress.md with:
+
+## Review
+- What's correct
+- Fixed: Issue and resolution
+- Note: Observations

package/agents/scout.md

@@ -0,0 +1,42 @@
+---
+name: scout
+description: Fast codebase recon that returns compressed context for handoff
+tools: read, grep, find, ls, bash, write
+model: anthropic/claude-haiku-4-5
+output: context.md
+defaultProgress: true
+---
+
+You are a scout. Quickly investigate a codebase and return structured findings.
+
+When running in a chain, you'll receive instructions about where to write your output.
+When running solo, write to the provided output path and summarize what you found.
+
+Thoroughness (infer from task, default medium):
+- Quick: Targeted lookups, key files only
+- Medium: Follow imports, read critical sections
+- Thorough: Trace all dependencies, check tests/types
+
+Strategy:
+1. grep/find to locate relevant code
+2. Read key sections (not entire files)
+3. Identify types, interfaces, key functions
+4. Note dependencies between files
+
+Your output format (context.md):
+
+# Code Context
+
+## Files Retrieved
+List with exact line ranges:
+1. `path/to/file.ts` (lines 10-50) - Description
+2. `path/to/other.ts` (lines 100-150) - Description
+
+## Key Code
+Critical types, interfaces, or functions with actual code snippets.
+
+## Architecture
+Brief explanation of how the pieces connect.
+
+## Start Here
+Which file to look at first and why.

package/agents/worker.md

@@ -0,0 +1,32 @@
+---
+name: worker
+description: General-purpose subagent with full capabilities, isolated context
+model: claude-sonnet-4-6
+defaultReads: context.md, plan.md
+defaultProgress: true
+---
+
+You are a worker agent with full capabilities. You operate in an isolated context window.
+
+When running in a chain, you'll receive instructions about:
+- Which files to read (context from previous steps)
+- Where to maintain progress tracking
+
+Work autonomously to complete the assigned task. Use all available tools as needed.
+
+Progress.md format:
+
+# Progress
+
+## Status
+[In Progress | Completed | Blocked]
+
+## Tasks
+- [x] Completed task
+- [ ] Current task
+
+## Files Changed
+- `path/to/file.ts` - what changed
+
+## Notes
+Any blockers or decisions.

package/agents.ts

@@ -5,6 +5,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { KNOWN_FIELDS } from "./agent-serializer.js";
 import { parseChain } from "./chain-serializer.js";
 import { mergeAgentsForScope } from "./agent-selection.js";
@@ -242,7 +243,7 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
 	}
 }
 
-const BUILTIN_AGENTS_DIR = path.join(os.homedir(), ".pi", "agent", "extensions", "subagent", "agents");
+const BUILTIN_AGENTS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "agents");
 
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
 	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
@@ -257,6 +258,7 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 }
 
 export function discoverAgentsAll(cwd: string): {
+	builtin: AgentConfig[];
 	user: AgentConfig[];
 	project: AgentConfig[];
 	chains: ChainConfig[];
@@ -266,6 +268,7 @@ export function discoverAgentsAll(cwd: string): {
 	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
 	const projectDir = findNearestProjectAgentsDir(cwd);
 
+	const builtin = loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin");
 	const user = loadAgentsFromDir(userDir, "user");
 	const project = projectDir ? loadAgentsFromDir(projectDir, "project") : [];
 	const chains = [
@@ -273,5 +276,5 @@ export function discoverAgentsAll(cwd: string): {
 		...(projectDir ? loadChainsFromDir(projectDir, "project") : []),
 	];
 
-	return { user, project, chains, userDir, projectDir };
+	return { builtin, user, project, chains, userDir, projectDir };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -29,6 +29,7 @@
     "*.ts",
     "!*.test.ts",
     "*.mjs",
+    "agents/",
     "README.md",
     "CHANGELOG.md"
   ],

package/render.ts

@@ -4,7 +4,7 @@
 
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import { getMarkdownTheme, type ExtensionContext } from "@mariozechner/pi-coding-agent";
-import { Container, Markdown, Spacer, Text, type Widget } from "@mariozechner/pi-tui";
+import { Container, Markdown, Spacer, Text, truncateToWidth, visibleWidth, type Widget } from "@mariozechner/pi-tui";
 import {
 	type AsyncJobState,
 	type Details,
@@ -16,6 +16,15 @@ import { getFinalOutput, getDisplayItems, getOutputTail, getLastActivity } from
 
 type Theme = ExtensionContext["ui"]["theme"];
 
+function getTermWidth(): number {
+	return process.stdout.columns || 120;
+}
+
+function truncLine(text: string, maxWidth: number): string {
+	if (visibleWidth(text) <= maxWidth) return text;
+	return truncateToWidth(text, maxWidth - 1) + "…";
+}
+
 // Track last rendered widget state to avoid no-op re-renders
 let lastWidgetHash = "";
 
@@ -67,6 +76,7 @@ export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void
 	lastWidgetHash = newHash;
 
 	const theme = ctx.ui.theme;
+	const w = getTermWidth();
 	const lines: string[] = [];
 	lines.push(theme.fg("accent", "Async subagents"));
 
@@ -90,12 +100,12 @@ export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void
 		const activityText = job.status === "running" ? getLastActivity(job.outputFile) : "";
 		const activitySuffix = activityText ? ` | ${theme.fg("dim", activityText)}` : "";
 
-		lines.push(`- ${id} ${status} | ${agentLabel} | ${stepText}${elapsed ? ` | ${elapsed}` : ""}${tokenText}${activitySuffix}`);
+		lines.push(truncLine(`- ${id} ${status} | ${agentLabel} | ${stepText}${elapsed ? ` | ${elapsed}` : ""}${tokenText}${activitySuffix}`, w));
 
 		if (job.status === "running" && job.outputFile) {
 			const tail = getOutputTail(job.outputFile, 3);
 			for (const line of tail) {
-				lines.push(theme.fg("dim", `  > ${line}`));
+				lines.push(truncLine(theme.fg("dim", `  > ${line}`), w));
 			}
 		}
 	}
@@ -114,7 +124,8 @@ export function renderSubagentResult(
 	const d = result.details;
 	if (!d || !d.results.length) {
 		const t = result.content[0];
-		return new Text(t?.type === "text" ? t.text : "(no output)", 0, 0);
+		const text = t?.type === "text" ? t.text : "(no output)";
+		return new Text(truncLine(text, getTermWidth() - 4), 0, 0);
 	}
 
 	const mdTheme = getMarkdownTheme();
@@ -135,37 +146,42 @@ export function renderSubagentResult(
 				? ` | ${r.progressSummary.toolCount} tools, ${formatTokens(r.progressSummary.tokens)} tok, ${formatDuration(r.progressSummary.durationMs)}`
 				: "";
 
+		const w = getTermWidth() - 4;
 		const c = new Container();
-		c.addChild(new Text(`${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${progressInfo}`, 0, 0));
+		c.addChild(new Text(truncLine(`${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${progressInfo}`, w), 0, 0));
 		c.addChild(new Spacer(1));
+		const taskMaxLen = Math.max(20, w - 8);
+		const taskPreview = r.task.length > taskMaxLen
+			? `${r.task.slice(0, taskMaxLen)}...`
+			: r.task;
 		c.addChild(
-			new Text(theme.fg("dim", `Task: ${r.task.slice(0, 150)}${r.task.length > 150 ? "..." : ""}`), 0, 0),
+			new Text(truncLine(theme.fg("dim", `Task: ${taskPreview}`), w), 0, 0),
 		);
 		c.addChild(new Spacer(1));
 
 		const items = getDisplayItems(r.messages);
 		for (const item of items) {
 			if (item.type === "tool")
-				c.addChild(new Text(theme.fg("muted", formatToolCall(item.name, item.args)), 0, 0));
+				c.addChild(new Text(truncLine(theme.fg("muted", formatToolCall(item.name, item.args)), w), 0, 0));
 		}
 		if (items.length) c.addChild(new Spacer(1));
 
 		if (output) c.addChild(new Markdown(output, 0, 0, mdTheme));
 		c.addChild(new Spacer(1));
 		if (r.skills?.length) {
-			c.addChild(new Text(theme.fg("dim", `Skills: ${r.skills.join(", ")}`), 0, 0));
+			c.addChild(new Text(truncLine(theme.fg("dim", `Skills: ${r.skills.join(", ")}`), w), 0, 0));
 		}
 		if (r.skillsWarning) {
-			c.addChild(new Text(theme.fg("warning", `⚠️ ${r.skillsWarning}`), 0, 0));
+			c.addChild(new Text(truncLine(theme.fg("warning", `⚠️ ${r.skillsWarning}`), w), 0, 0));
 		}
-		c.addChild(new Text(theme.fg("dim", formatUsage(r.usage, r.model)), 0, 0));
+		c.addChild(new Text(truncLine(theme.fg("dim", formatUsage(r.usage, r.model)), w), 0, 0));
 		if (r.sessionFile) {
-			c.addChild(new Text(theme.fg("dim", `Session: ${shortenPath(r.sessionFile)}`), 0, 0));
+			c.addChild(new Text(truncLine(theme.fg("dim", `Session: ${shortenPath(r.sessionFile)}`), w), 0, 0));
 		}
 
 		if (r.artifactPaths) {
 			c.addChild(new Spacer(1));
-			c.addChild(new Text(theme.fg("dim", `Artifacts: ${shortenPath(r.artifactPaths.outputPath)}`), 0, 0));
+			c.addChild(new Text(truncLine(theme.fg("dim", `Artifacts: ${shortenPath(r.artifactPaths.outputPath)}`), w), 0, 0));
 		}
 		return c;
 	}
@@ -231,7 +247,7 @@ export function renderSubagentResult(
 						&& Boolean(isComplete)
 						&& hasEmptyTextOutputWithoutOutputTarget(result.task, getFinalOutput(result.messages));
 					const isCurrent = i === (d.currentStepIndex ?? d.results.length);
-					const icon = isFailed
+					const stepIcon = isFailed
 						? theme.fg("error", "✗")
 						: isEmptyWithoutTarget
 							? theme.fg("warning", "⚠")
@@ -240,22 +256,23 @@ export function renderSubagentResult(
 								: isCurrent && hasRunning
 									? theme.fg("warning", "●")
 									: theme.fg("dim", "○");
-					return `${icon} ${agent}`;
+					return `${stepIcon} ${agent}`;
 				})
 				.join(theme.fg("dim", " → "))
 		: null;
 
+	const w = getTermWidth() - 4;
 	const c = new Container();
 	c.addChild(
 		new Text(
-			`${icon} ${theme.fg("toolTitle", theme.bold(modeLabel))}${stepInfo}${summaryStr}`,
+			truncLine(`${icon} ${theme.fg("toolTitle", theme.bold(modeLabel))}${stepInfo}${summaryStr}`, w),
 			0,
 			0,
 		),
 	);
 	// Show chain visualization
 	if (chainVis) {
-		c.addChild(new Text(`  ${chainVis}`, 0, 0));
+		c.addChild(new Text(truncLine(`  ${chainVis}`, w), 0, 0));
 	}
 
 	// === STATIC STEP LAYOUT (like clarification UI) ===
@@ -275,7 +292,7 @@ export function renderSubagentResult(
 
 		if (!r) {
 			// Pending step
-			c.addChild(new Text(theme.fg("dim", `  Step ${i + 1}: ${agentName}`), 0, 0));
+			c.addChild(new Text(truncLine(theme.fg("dim", `  Step ${i + 1}: ${agentName}`), w), 0, 0));
 			c.addChild(new Text(theme.fg("dim", `    status: ○ pending`), 0, 0));
 			c.addChild(new Spacer(1));
 			continue;
@@ -299,45 +316,46 @@ export function renderSubagentResult(
 		const stepHeader = rRunning
 			? `${statusIcon} Step ${i + 1}: ${theme.bold(theme.fg("warning", r.agent))}${modelDisplay}${stats}`
 			: `${statusIcon} Step ${i + 1}: ${theme.bold(r.agent)}${modelDisplay}${stats}`;
-		c.addChild(new Text(stepHeader, 0, 0));
+		c.addChild(new Text(truncLine(stepHeader, w), 0, 0));
 
-		const taskPreview = r.task.slice(0, 120) + (r.task.length > 120 ? "..." : "");
-		c.addChild(new Text(theme.fg("dim", `    task: ${taskPreview}`), 0, 0));
+		const taskMaxLen = Math.max(20, w - 12);
+		const taskPreview = r.task.slice(0, taskMaxLen) + (r.task.length > taskMaxLen ? "..." : "");
+		c.addChild(new Text(truncLine(theme.fg("dim", `    task: ${taskPreview}`), w), 0, 0));
 
 		const outputTarget = extractOutputTarget(r.task);
 		if (outputTarget) {
-			c.addChild(new Text(theme.fg("dim", `    output: ${outputTarget}`), 0, 0));
+			c.addChild(new Text(truncLine(theme.fg("dim", `    output: ${outputTarget}`), w), 0, 0));
 		}
 
 		if (r.skills?.length) {
-			c.addChild(new Text(theme.fg("dim", `    skills: ${r.skills.join(", ")}`), 0, 0));
+			c.addChild(new Text(truncLine(theme.fg("dim", `    skills: ${r.skills.join(", ")}`), w), 0, 0));
 		}
 		if (r.skillsWarning) {
-			c.addChild(new Text(theme.fg("warning", `    ⚠️ ${r.skillsWarning}`), 0, 0));
+			c.addChild(new Text(truncLine(theme.fg("warning", `    ⚠️ ${r.skillsWarning}`), w), 0, 0));
 		}
 
 		if (rRunning && rProg) {
 			if (rProg.skills?.length) {
-				c.addChild(new Text(theme.fg("accent", `    skills: ${rProg.skills.join(", ")}`), 0, 0));
+				c.addChild(new Text(truncLine(theme.fg("accent", `    skills: ${rProg.skills.join(", ")}`), w), 0, 0));
 			}
 			// Current tool for running step
 			if (rProg.currentTool) {
 				const toolLine = rProg.currentToolArgs
 					? `${rProg.currentTool}: ${rProg.currentToolArgs.slice(0, 100)}${rProg.currentToolArgs.length > 100 ? "..." : ""}`
 					: rProg.currentTool;
-				c.addChild(new Text(theme.fg("warning", `    > ${toolLine}`), 0, 0));
+				c.addChild(new Text(truncLine(theme.fg("warning", `    > ${toolLine}`), w), 0, 0));
 			}
 			// Recent tools
 			if (rProg.recentTools?.length) {
 				for (const t of rProg.recentTools.slice(0, 3)) {
 					const args = t.args.slice(0, 90) + (t.args.length > 90 ? "..." : "");
-					c.addChild(new Text(theme.fg("dim", `      ${t.tool}: ${args}`), 0, 0));
+					c.addChild(new Text(truncLine(theme.fg("dim", `      ${t.tool}: ${args}`), w), 0, 0));
 				}
 			}
 			// Recent output (limited)
 			const recentLines = (rProg.recentOutput ?? []).slice(-5);
 			for (const line of recentLines) {
-				c.addChild(new Text(theme.fg("dim", `      ${line.slice(0, 100)}${line.length > 100 ? "..." : ""}`), 0, 0));
+				c.addChild(new Text(truncLine(theme.fg("dim", `      ${line.slice(0, 100)}${line.length > 100 ? "..." : ""}`), w), 0, 0));
 			}
 		}
 
@@ -346,7 +364,7 @@ export function renderSubagentResult(
 
 	if (d.artifacts) {
 		c.addChild(new Spacer(1));
-		c.addChild(new Text(theme.fg("dim", `Artifacts dir: ${shortenPath(d.artifacts.dir)}`), 0, 0));
+		c.addChild(new Text(truncLine(theme.fg("dim", `Artifacts dir: ${shortenPath(d.artifacts.dir)}`), w), 0, 0));
 	}
 	return c;
 }