pi-subagents 0.8.5 → 0.9.1

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## [Unreleased]
 
+## [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 `[built]` 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
+- **Builtin agents** — the extension now ships with a default set of agent definitions in `agents/`. These are loaded with lowest priority so user and project agents always override them. New users get a useful set of agents out of the box without manual setup.
+  - `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.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).
+
+### Fixed
+- Async subagent session sharing no longer fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`. The runner tried `require.resolve("@mariozechner/pi-coding-agent/package.json")` to find pi's HTML export module, but pi's `exports` map doesn't include that subpath. The fix resolves the package root in the main pi process by walking up from `process.argv[1]` and passes it to the spawned runner through the config, bypassing `require.resolve` entirely. The Windows CLI resolution fallback in `getPiSpawnCommand` benefits from the same walk-up function.
+
 ## [0.8.5] - 2026-02-16
 
 ### Fixed

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" ? "[built]" : 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));
 
@@ -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" ? "[built]" : 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,12 +5,15 @@
 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";
 
 export type AgentScope = "user" | "project" | "both";
 
+export type AgentSource = "builtin" | "user" | "project";
+
 export interface AgentConfig {
 	name: string;
 	description: string;
@@ -19,7 +22,7 @@ export interface AgentConfig {
 	model?: string;
 	thinking?: string;
 	systemPrompt: string;
-	source: "user" | "project";
+	source: AgentSource;
 	filePath: string;
 	skills?: string[];
 	extensions?: string[];
@@ -44,7 +47,7 @@ export interface ChainStepConfig {
 export interface ChainConfig {
 	name: string;
 	description: string;
-	source: "user" | "project";
+	source: AgentSource;
 	filePath: string;
 	steps: ChainStepConfig[];
 	extraFields?: Record<string, string>;
@@ -85,7 +88,7 @@ function parseFrontmatter(content: string): { frontmatter: Record<string, string
 	return { frontmatter, body };
 }
 
-function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
+function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 
 	if (!fs.existsSync(dir)) {
@@ -184,7 +187,7 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 	return agents;
 }
 
-function loadChainsFromDir(dir: string, source: "user" | "project"): ChainConfig[] {
+function loadChainsFromDir(dir: string, source: AgentSource): ChainConfig[] {
 	const chains: ChainConfig[] = [];
 
 	if (!fs.existsSync(dir)) {
@@ -240,18 +243,22 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
 	}
 }
 
+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");
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
 
+	const builtinAgents = loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin");
 	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
 	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
-	const agents = mergeAgentsForScope(scope, userAgents, projectAgents);
+	const agents = mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents);
 
 	return { agents, projectAgentsDir };
 }
 
 export function discoverAgentsAll(cwd: string): {
+	builtin: AgentConfig[];
 	user: AgentConfig[];
 	project: AgentConfig[];
 	chains: ChainConfig[];
@@ -261,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 = [
@@ -268,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/async-execution.ts

@@ -13,6 +13,7 @@ import type { AgentConfig } from "./agents.js";
 import { applyThinkingSuffix } from "./execution.js";
 import { injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.js";
 import { isParallelStep, resolveStepBehavior, type ChainStep, type SequentialStep, type StepOverrides } from "./settings.js";
+import { resolvePiPackageRoot } from "./pi-spawn.js";
 import { buildSkillInjection, normalizeSkillInput, resolveSkills } from "./skills.js";
 import {
 	type ArtifactConfig,
@@ -23,6 +24,7 @@ import {
 } from "./types.js";
 
 const require = createRequire(import.meta.url);
+const piPackageRoot = resolvePiPackageRoot();
 const jitiCliPath: string | undefined = (() => {
 	const candidates: Array<() => string> = [
 		() => path.join(path.dirname(require.resolve("jiti/package.json")), "lib/jiti-cli.mjs"),
@@ -188,6 +190,7 @@ export function executeAsyncChain(
 			sessionDir: sessionRoot ? path.join(sessionRoot, `async-${id}`) : undefined,
 			asyncDir,
 			sessionId: ctx.currentSessionId,
+			piPackageRoot,
 		},
 		id,
 		runnerCwd,
@@ -265,6 +268,7 @@ export function executeAsyncSingle(
 			sessionDir: sessionRoot ? path.join(sessionRoot, `async-${id}`) : undefined,
 			asyncDir,
 			sessionId: ctx.currentSessionId,
+			piPackageRoot,
 		},
 		id,
 		runnerCwd,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.8.5",
+  "version": "0.9.1",
   "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/pi-spawn.ts

@@ -4,6 +4,22 @@ import * as path from "node:path";
 
 const require = createRequire(import.meta.url);
 
+export function resolvePiPackageRoot(): string | undefined {
+	try {
+		const entry = process.argv[1];
+		if (!entry) return undefined;
+		let dir = path.dirname(fs.realpathSync(entry));
+		while (dir !== path.dirname(dir)) {
+			try {
+				const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf-8"));
+				if (pkg.name === "@mariozechner/pi-coding-agent") return dir;
+			} catch {}
+			dir = path.dirname(dir);
+		}
+	} catch {}
+	return undefined;
+}
+
 export interface PiSpawnDeps {
 	platform?: NodeJS.Platform;
 	execPath?: string;
@@ -11,6 +27,7 @@ export interface PiSpawnDeps {
 	existsSync?: (filePath: string) => boolean;
 	readFileSync?: (filePath: string, encoding: "utf-8") => string;
 	resolvePackageJson?: () => string;
+	piPackageRoot?: string;
 }
 
 export interface PiSpawnCommand {
@@ -40,7 +57,11 @@ export function resolveWindowsPiCliScript(deps: PiSpawnDeps = {}): string | unde
 	}
 
 	try {
-		const resolvePackageJson = deps.resolvePackageJson ?? (() => require.resolve("@mariozechner/pi-coding-agent/package.json"));
+		const resolvePackageJson = deps.resolvePackageJson ?? (() => {
+			const root = deps.piPackageRoot ?? resolvePiPackageRoot();
+			if (root) return path.join(root, "package.json");
+			return require.resolve("@mariozechner/pi-coding-agent/package.json");
+		});
 		const packageJsonPath = resolvePackageJson();
 		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as {
 			bin?: string | Record<string, string>;

package/subagent-runner.ts

@@ -44,6 +44,7 @@ interface SubagentRunConfig {
 	sessionDir?: string;
 	asyncDir: string;
 	sessionId?: string | null;
+	piPackageRoot?: string;
 }
 
 interface StepResult {
@@ -134,8 +135,8 @@ function runPiStreaming(
 	});
 }
 
-async function exportSessionHtml(sessionFile: string, outputDir: string): Promise<string> {
-	const pkgRoot = path.dirname(require.resolve("@mariozechner/pi-coding-agent/package.json"));
+async function exportSessionHtml(sessionFile: string, outputDir: string, piPackageRoot?: string): Promise<string> {
+	const pkgRoot = piPackageRoot ?? path.dirname(require.resolve("@mariozechner/pi-coding-agent/package.json"));
 	const exportModulePath = path.join(pkgRoot, "dist", "core", "export-html", "index.js");
 	const moduleUrl = pathToFileURL(exportModulePath).href;
 	const mod = await import(moduleUrl);
@@ -516,7 +517,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		sessionFile = findLatestSessionFile(config.sessionDir) ?? undefined;
 		if (sessionFile) {
 			try {
-				const htmlPath = await exportSessionHtml(sessionFile, config.sessionDir);
+				const htmlPath = await exportSessionHtml(sessionFile, config.sessionDir, config.piPackageRoot);
 				const share = createShareLink(htmlPath);
 				if ("error" in share) shareError = share.error;
 				else {