@ferris1225/pi-subagents 0.1.0

package/src/agents.ts

@@ -0,0 +1,157 @@
+/**
+ * Agent discovery.
+ *
+ * Agents are Markdown files (YAML frontmatter + body-as-system-prompt) loaded from
+ * three scopes with override priority  builtin < user < project  (same `name` wins
+ * at the higher scope). Discovery is re-run on every invocation so editing a file or
+ * dropping a new one takes effect mid-session without a reload.
+ *
+ *   builtin : <package>/agents            (shipped with this extension)
+ *   user    : <agentDir>/agents           (~/.pi/agent/agents)
+ *   project : <cwd...>/.pi/agents         (nearest, walking up)
+ */
+
+import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import type { AgentScope } from "./config.ts";
+
+export type AgentSource = "builtin" | "user" | "project";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	systemPrompt: string;
+	source: AgentSource;
+	filePath: string;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+/** <package>/agents — the agents shipped with this extension. */
+export const BUILTIN_AGENTS_DIR = join(here, "..", "agents");
+
+function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
+	const agents: AgentConfig[] = [];
+	if (!existsSync(dir)) return agents;
+
+	let entries: Dirent[];
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return agents;
+	}
+
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".md")) continue;
+		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+		const filePath = join(dir, entry.name);
+		let content: string;
+		try {
+			content = readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+
+		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		// name + description are required; skip malformed files silently.
+		if (!frontmatter.name || !frontmatter.description) continue;
+
+		const tools = frontmatter.tools
+			?.split(",")
+			.map((t) => t.trim())
+			.filter(Boolean);
+
+		agents.push({
+			name: frontmatter.name,
+			description: frontmatter.description,
+			tools: tools && tools.length > 0 ? tools : undefined,
+			model: frontmatter.model,
+			systemPrompt: body,
+			source,
+			filePath,
+		});
+	}
+
+	return agents;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		const candidate = join(currentDir, CONFIG_DIR_NAME, "agents");
+		if (isDirectory(candidate)) return candidate;
+		const parentDir = dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+export interface DiscoverOptions {
+	/** Which directories to read from. Default: "user". */
+	scope?: AgentScope;
+	/** If provided and non-empty, only agents whose name is listed are returned. */
+	enabledNames?: readonly string[];
+	/** Per-agent model override ("provider/model-id"), keyed by agent name. */
+	modelOverrides?: Record<string, string>;
+	/** Override the built-in agents directory (used by tests). */
+	builtinDir?: string;
+}
+
+/**
+ * Discover agents across scopes, apply enable-filter and model overrides.
+ * Override priority for the same name: project > user > builtin.
+ */
+export function discoverAgents(cwd: string, options: DiscoverOptions = {}): AgentDiscoveryResult {
+	const scope = options.scope ?? "user";
+	const builtinDir = options.builtinDir ?? BUILTIN_AGENTS_DIR;
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+
+	const builtin = loadAgentsFromDir(builtinDir, "builtin");
+	const user = scope === "project" ? [] : loadAgentsFromDir(join(getAgentDir(), "agents"), "user");
+	const project =
+		scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+
+	// Merge with override priority builtin < user < project.
+	const byName = new Map<string, AgentConfig>();
+	for (const agent of builtin) byName.set(agent.name, agent);
+	for (const agent of user) byName.set(agent.name, agent);
+	for (const agent of project) byName.set(agent.name, agent);
+
+	let agents = Array.from(byName.values());
+
+	if (options.enabledNames && options.enabledNames.length > 0) {
+		const enabled = new Set(options.enabledNames);
+		agents = agents.filter((agent) => enabled.has(agent.name));
+	}
+
+	if (options.modelOverrides) {
+		agents = agents.map((agent) => {
+			const override = options.modelOverrides?.[agent.name];
+			return override ? { ...agent, model: override } : agent;
+		});
+	}
+
+	return { agents, projectAgentsDir };
+}
+
+/** One-line catalog entry for system-prompt injection and error messages. */
+export function formatCatalogEntry(agent: AgentConfig): string {
+	return `- ${agent.name}: ${agent.description}`;
+}

package/src/config.ts

@@ -0,0 +1,155 @@
+/**
+ * Configuration load/save for pi-subagents.
+ *
+ * Config lives at <agentDir>/pi-subagents.json (agentDir defaults to ~/.pi/agent
+ * and honors PI_CODING_AGENT_DIR). Parsing is defensive: invalid fields fall back
+ * to defaults instead of throwing, so a hand-edited or partially-written file can
+ * never break the extension at runtime.
+ */
+
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+
+/** Full catalog of agents shipped with the package (selectable in /subagents-setup). */
+export const BUILTIN_AGENT_NAMES = ["explore", "plan", "worker", "reviewer"] as const;
+export type BuiltinAgentName = (typeof BUILTIN_AGENT_NAMES)[number];
+
+/** Agents enabled out of the box. `plan` ships but is opt-in: a worker plans internally. */
+export const DEFAULT_ENABLED_AGENTS: readonly string[] = ["explore", "worker", "reviewer"];
+
+export const AGENT_SCOPE_VALUES = ["user", "project", "both"] as const;
+export type AgentScope = (typeof AGENT_SCOPE_VALUES)[number];
+
+export const CONFIG_FILE_NAME = "pi-subagents.json";
+
+export interface SubagentsConfig {
+	/** Agent names that are discoverable and injected. Default: explore, worker, reviewer. */
+	enabledAgents: string[];
+	/** Per-agent model override, keyed by agent name, as "provider/model-id". */
+	agentModels: Record<string, string>;
+	/** Whether to inject the delegation directive into the parent system prompt. Default: true. */
+	proactiveInjection: boolean;
+	/** Which agent directories to discover from. Default: "user". */
+	agentScope: AgentScope;
+}
+
+export const DEFAULT_CONFIG: SubagentsConfig = {
+	enabledAgents: [...DEFAULT_ENABLED_AGENTS],
+	agentModels: {},
+	proactiveInjection: true,
+	agentScope: "user",
+};
+
+export function getConfigPath(agentDir: string = getAgentDir()): string {
+	return join(agentDir, CONFIG_FILE_NAME);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isAgentScope(value: unknown): value is AgentScope {
+	return typeof value === "string" && (AGENT_SCOPE_VALUES as readonly string[]).includes(value);
+}
+
+function isModelReference(value: unknown): value is string {
+	if (typeof value !== "string") return false;
+	const normalized = value.trim();
+	const slash = normalized.indexOf("/");
+	return slash > 0 && slash < normalized.length - 1 && !/\s/u.test(normalized);
+}
+
+/**
+ * Merge a raw parsed JSON value over the defaults, dropping invalid fields.
+ * Exported for tests.
+ */
+export function normalizeConfig(raw: unknown): SubagentsConfig {
+	if (!isRecord(raw)) return { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_CONFIG.enabledAgents] };
+
+	const config: SubagentsConfig = {
+		enabledAgents: [...DEFAULT_CONFIG.enabledAgents],
+		agentModels: {},
+		proactiveInjection: DEFAULT_CONFIG.proactiveInjection,
+		agentScope: DEFAULT_CONFIG.agentScope,
+	};
+
+	if (Array.isArray(raw.enabledAgents)) {
+		const names = raw.enabledAgents.filter(
+			(name): name is string => typeof name === "string" && name.trim().length > 0,
+		);
+		// An explicitly empty array is honored (disables all agents); otherwise keep valid names.
+		config.enabledAgents = [...new Set(names.map((name) => name.trim()))];
+	}
+
+	if (isRecord(raw.agentModels)) {
+		for (const [key, value] of Object.entries(raw.agentModels)) {
+			if (isModelReference(value)) config.agentModels[key.trim()] = value.trim();
+		}
+	}
+
+	if (typeof raw.proactiveInjection === "boolean") {
+		config.proactiveInjection = raw.proactiveInjection;
+	}
+
+	if (isAgentScope(raw.agentScope)) {
+		config.agentScope = raw.agentScope;
+	}
+
+	return config;
+}
+
+/**
+ * Load config. A missing file is a normal state and yields the defaults (not an error).
+ * A corrupt file also falls back to defaults rather than throwing, so startup never breaks.
+ */
+export async function loadConfig(configPath: string = getConfigPath()): Promise<SubagentsConfig> {
+	let text: string;
+	try {
+		text = await readFile(configPath, "utf8");
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") {
+			return { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_CONFIG.enabledAgents] };
+		}
+		// Unreadable for another reason: fall back to defaults but do not crash startup.
+		return { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_CONFIG.enabledAgents] };
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_CONFIG.enabledAgents] };
+	}
+
+	return normalizeConfig(parsed);
+}
+
+/**
+ * Save config atomically (temp file + rename) serialized through pi's per-file
+ * mutation queue so concurrent writers cannot interleave.
+ */
+export async function saveConfig(
+	config: SubagentsConfig,
+	configPath: string = getConfigPath(),
+): Promise<void> {
+	const normalized = normalizeConfig(config);
+	await mkdir(dirname(configPath), { recursive: true });
+	await withFileMutationQueue(configPath, async () => {
+		const temporaryPath = `${configPath}.${process.pid}.${Date.now()}.tmp`;
+		try {
+			await writeFile(temporaryPath, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
+			await rename(temporaryPath, configPath);
+		} finally {
+			await rm(temporaryPath, { force: true }).catch(() => undefined);
+		}
+	});
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error;
+}
+
+export function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/index.ts

@@ -0,0 +1,307 @@
+/**
+ * pi-subagents — focused sub-agent delegation for pi.
+ *
+ * Registers:
+ *   - a `subagent` tool that runs explore/plan/worker/reviewer agents as isolated
+ *     `pi` child processes (single or parallel),
+ *   - a `/subagents-setup` command for selection-only configuration,
+ *   - a `before_agent_start` hook that injects a delegation directive into the
+ *     parent system prompt so the main model uses the tool proactively.
+ *
+ * The tool is NOT registered inside nested sub-agent processes beyond
+ * MAX_SUBAGENT_DEPTH, which both prevents runaway recursion and keeps child
+ * context windows clean.
+ */
+
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { discoverAgents, type AgentConfig } from "./agents.ts";
+import { getConfigPath, loadConfig } from "./config.ts";
+import { buildDelegationDirective } from "./prompt.ts";
+import { runSetup } from "./setup.ts";
+import {
+	MAX_CONCURRENCY,
+	MAX_PARALLEL_TASKS,
+	MAX_SUBAGENT_DEPTH,
+	currentSubagentDepth,
+	getFinalOutput,
+	getResultOutput,
+	isFailedResult,
+	mapWithConcurrencyLimit,
+	runSingleAgent,
+	truncateParallelOutput,
+	type OnUpdateCallback,
+	type SingleResult,
+	type SubagentDetails,
+	type UsageStats,
+} from "./spawn.ts";
+
+const TaskItem = Type.Object({
+	agent: Type.String({ description: "Name of the agent to invoke" }),
+	task: Type.String({ description: "Self-contained task to delegate (the agent has no memory of this conversation)" }),
+	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
+});
+
+const SubagentParams = Type.Object({
+	agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (single mode)" })),
+	task: Type.Optional(Type.String({ description: "Self-contained task to delegate (single mode)" })),
+	tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
+	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
+});
+
+function emptyUsage(): UsageStats {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
+}
+
+function aggregateUsage(results: SingleResult[]): UsageStats {
+	const total = emptyUsage();
+	for (const r of results) {
+		total.input += r.usage.input;
+		total.output += r.usage.output;
+		total.cacheRead += r.usage.cacheRead;
+		total.cacheWrite += r.usage.cacheWrite;
+		total.cost += r.usage.cost;
+		total.turns += r.usage.turns;
+	}
+	return total;
+}
+
+function formatTokens(count: number): string {
+	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
+	return String(count);
+}
+
+function formatUsage(usage: UsageStats): string {
+	const parts: string[] = [];
+	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+	return parts.join(" ");
+}
+
+export default function (pi: ExtensionAPI): void {
+	const configPath = getConfigPath(getAgentDir());
+
+	// Recursion guard: do not register the tool deep inside nested sub-agents.
+	if (currentSubagentDepth() >= MAX_SUBAGENT_DEPTH) {
+		pi.registerCommand("subagents-setup", {
+			description: "Configure pi-subagents (disabled in nested sub-agent processes)",
+			handler: async (_args, ctx) => {
+				ctx.ui.notify("pi-subagents setup is unavailable inside a nested sub-agent.", "warning");
+			},
+		});
+		return;
+	}
+
+	pi.registerTool({
+		name: "subagent",
+		label: "Subagent",
+		description: [
+			"Delegate a discrete, self-contained task to a specialized sub-agent running in an ISOLATED context window.",
+			"Agents: explore (read-only codebase recon), plan (implementation plan, opt-in), worker (implement/fix/refactor/test, full tools), reviewer (adversarial pre-commit review, read-only).",
+			"Modes: single ({agent, task}) or parallel ({tasks: [{agent, task}, ...]}).",
+			"Use it to keep the main conversation clean: delegate the work, then orchestrate and verify the results yourself.",
+			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output).",
+		].join(" "),
+		promptSnippet:
+			"Delegate discrete tasks to isolated sub-agents: explore (read-only search), worker (implement), reviewer (adversarial pre-commit review); plan is opt-in.",
+		promptGuidelines: [
+			"Use subagent to delegate discrete, self-contained tasks so the main context stays clean; do orchestration and verification yourself.",
+			"Use subagent with agent 'explore' for broad or open-ended code search before large changes.",
+			"Use subagent with agent 'worker' to implement a well-scoped task; it plans internally.",
+			"Use subagent with agent 'reviewer' for a fresh read-only review before reporting work done or committing.",
+			"Run independent tasks in parallel by passing a tasks array to subagent; keep dependent work sequential.",
+		],
+		parameters: SubagentParams,
+
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const config = await loadConfig(configPath);
+			const discovery = discoverAgents(ctx.cwd, {
+				scope: config.agentScope,
+				enabledNames: config.enabledAgents,
+			});
+
+			// Effective model precedence: setup override > current session model > frontmatter default.
+			const sessionRef = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+			const agents: AgentConfig[] = discovery.agents.map((agent) => ({
+				...agent,
+				model: config.agentModels[agent.name] ?? sessionRef ?? agent.model,
+			}));
+
+			const hasTasks = (params.tasks?.length ?? 0) > 0;
+			const hasSingle = Boolean(params.agent && params.task);
+
+			const makeDetails =
+				(mode: "single" | "parallel") =>
+				(results: SingleResult[]): SubagentDetails => ({ mode, results });
+
+			const catalog = agents.map((a) => a.name).join(", ") || "none";
+
+			if (Number(hasTasks) + Number(hasSingle) !== 1) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Invalid parameters. Provide exactly one mode: single {agent, task} or parallel {tasks: [...]}. Enabled agents: ${catalog}.`,
+						},
+					],
+					details: makeDetails("single")([]),
+				};
+			}
+
+			// ---- Parallel mode ----
+			if (params.tasks && params.tasks.length > 0) {
+				if (params.tasks.length > MAX_PARALLEL_TASKS) {
+					return {
+						content: [
+							{ type: "text", text: `Too many parallel tasks (${params.tasks.length}). Max is ${MAX_PARALLEL_TASKS}.` },
+						],
+						details: makeDetails("parallel")([]),
+					};
+				}
+
+				const allResults: SingleResult[] = params.tasks.map((t) => ({
+					agent: t.agent,
+					agentSource: "unknown",
+					task: t.task,
+					exitCode: -1,
+					messages: [],
+					stderr: "",
+					usage: emptyUsage(),
+				}));
+
+				const emitParallelUpdate = (): void => {
+					if (!onUpdate) return;
+					const done = allResults.filter((r) => r.exitCode !== -1).length;
+					onUpdate({
+						content: [{ type: "text", text: `Parallel: ${done}/${allResults.length} done...` }],
+						details: makeDetails("parallel")([...allResults]),
+					});
+				};
+
+				const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
+					const perTaskUpdate: OnUpdateCallback | undefined = onUpdate
+						? (partial) => {
+								const current = partial.details?.results[0];
+								if (current) {
+									allResults[index] = current;
+									emitParallelUpdate();
+								}
+							}
+						: undefined;
+					const result = await runSingleAgent({
+						defaultCwd: ctx.cwd,
+						agent: agents.find((a) => a.name === t.agent),
+						agentName: t.agent,
+						task: t.task,
+						cwd: t.cwd,
+						signal,
+						onUpdate: perTaskUpdate,
+						makeDetails: makeDetails("parallel"),
+					});
+					allResults[index] = result;
+					emitParallelUpdate();
+					return result;
+				});
+
+				const successCount = results.filter((r) => !isFailedResult(r)).length;
+				const summaries = results.map((r) => {
+					const output = truncateParallelOutput(getResultOutput(r));
+					const status = isFailedResult(r) ? "failed" : "completed";
+					const usage = formatUsage(r.usage);
+					return `### [${r.agent}] ${status}${usage ? ` (${usage})` : ""}\n\n${output}`;
+				});
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Parallel: ${successCount}/${results.length} succeeded\n\n${summaries.join("\n\n---\n\n")}`,
+						},
+					],
+					details: makeDetails("parallel")(results),
+				};
+			}
+
+			// ---- Single mode ----
+			const result = await runSingleAgent({
+				defaultCwd: ctx.cwd,
+				agent: agents.find((a) => a.name === params.agent),
+				agentName: params.agent as string,
+				task: params.task as string,
+				cwd: params.cwd,
+				signal,
+				onUpdate,
+				makeDetails: makeDetails("single"),
+			});
+
+			if (isFailedResult(result)) {
+				return {
+					content: [{ type: "text", text: `Agent ${result.agent} ${result.stopReason || "failed"}: ${getResultOutput(result)}` }],
+					details: makeDetails("single")([result]),
+					isError: true,
+				};
+			}
+			return {
+				content: [{ type: "text", text: getFinalOutput(result.messages) || "(no output)" }],
+				details: makeDetails("single")([result]),
+			};
+		},
+
+		renderCall(args, theme) {
+			if (args.tasks && args.tasks.length > 0) {
+				let text = `${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${args.tasks.length})`)}`;
+				for (const t of args.tasks.slice(0, 4)) {
+					const preview = t.task.length > 48 ? `${t.task.slice(0, 48)}…` : t.task;
+					text += `\n  ${theme.fg("accent", t.agent)} ${theme.fg("dim", preview)}`;
+				}
+				if (args.tasks.length > 4) text += `\n  ${theme.fg("dim", `… +${args.tasks.length - 4} more`)}`;
+				return new Text(text, 0, 0);
+			}
+			const task: string = args.task ?? "";
+			const preview = task.length > 60 ? `${task.slice(0, 60)}…` : task;
+			return new Text(
+				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent ?? "?")} ${theme.fg("dim", preview)}`,
+				0,
+				0,
+			);
+		},
+
+		renderResult(result, _options, theme) {
+			const details = result.details as SubagentDetails | undefined;
+			if (!details || details.results.length === 0) return new Text(theme.fg("dim", "(no output)"), 0, 0);
+			const usage = formatUsage(aggregateUsage(details.results));
+			const header =
+				details.mode === "parallel"
+					? `${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${details.results.length})`)}`
+					: `${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", details.results[0].agent)}`;
+			const suffix = usage ? `  ${theme.fg("dim", usage)}` : "";
+			return new Text(header + suffix, 0, 0);
+		},
+	});
+
+	pi.registerCommand("subagents-setup", {
+		description: "Configure pi-subagents: enable agents, pick per-agent models, toggle proactive injection",
+		handler: async (_args, ctx) => {
+			await runSetup(ctx, configPath);
+		},
+	});
+
+	// Proactive dispatch: inject the delegation directive into the parent system prompt.
+	pi.on("before_agent_start", async (event, ctx) => {
+		const config = await loadConfig(configPath);
+		if (!config.proactiveInjection) return undefined;
+		const { agents } = discoverAgents(ctx.cwd, {
+			scope: config.agentScope,
+			enabledNames: config.enabledAgents,
+		});
+		const directive = buildDelegationDirective(agents);
+		if (!directive) return undefined;
+		return { systemPrompt: `${event.systemPrompt}\n${directive}` };
+	});
+}

package/src/prompt.ts

@@ -0,0 +1,57 @@
+/**
+ * Builds the delegation directive injected into the parent model's system prompt
+ * via the `before_agent_start` hook. This is the lever that makes the main model
+ * actually USE the subagent tool proactively (pi never shows it the per-agent
+ * descriptions otherwise).
+ *
+ * The directive is a self-contained replacement for the "Sub-agent Dispatch" and
+ * "Review, Verification & Commit" sections users otherwise keep in a global
+ * AGENTS.md — so installing this extension lets them delete those sections without
+ * losing the behavior. (Other AGENTS.md sections — Behavior, Git & Security,
+ * platform/language rules — are unrelated and stay put.)
+ */
+
+import type { AgentConfig } from "./agents.ts";
+import { formatCatalogEntry } from "./agents.ts";
+
+/** Compact role routing hints, emitted only for roles that are enabled. */
+const ROLE_ROUTING: Record<string, string> = {
+	explore: "explore — broad/open-ended code search, \"where is X\", multi-file lookups (read-only, cheap).",
+	plan: "plan — a separate, human-reviewable implementation plan before any code (read-only).",
+	worker: "worker — implement/fix/refactor/test a well-scoped task (full tools; plans internally).",
+	reviewer: "reviewer — adversarial pre-commit review of a diff (read-only; independent context).",
+};
+
+export function buildDelegationDirective(agents: AgentConfig[]): string {
+	if (agents.length === 0) return "";
+
+	const catalog = agents.map(formatCatalogEntry).join("\n");
+	const routing = agents
+		.map((a) => ROLE_ROUTING[a.name])
+		.filter((line): line is string => Boolean(line))
+		.map((line) => `- ${line}`)
+		.join("\n");
+	const hasReviewer = agents.some((a) => a.name === "reviewer");
+	const hasMultiple = agents.length > 1;
+
+	return `
+## Sub-agent delegation (pi-subagents)
+
+You have a \`subagent\` tool that runs specialized agents in ISOLATED context windows.
+Delegate discrete, self-contained tasks to it instead of doing everything inline, so the
+main window stays focused on orchestration, synthesis, and verification.
+
+Available agents:
+${catalog}
+
+${routing ? `Routing:\n${routing}\n` : ""}Dispatch discipline:
+- Default to delegating every discrete task to a sub-agent; do the orchestration and verification yourself in the main window.
+- Only handle inline: pure Q&A, a single trivial edit/lookup, or when the user explicitly says to do it directly. When in doubt, delegate.
+- For an already-known or trivial target, use a direct search/read tool (e.g. grep/find/read) — do not over-delegate a one-line lookup.
+${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list. Keep dependent work sequential (e.g. explore, then worker, then reviewer).\n" : ""}- Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
+- Trust but verify: a sub-agent's summary describes intent, not outcome. Check the actual changes/results before reporting work done.
+
+Review & verification:
+- Never report an unrun check as passed; report it as unavailable or as a pre-existing failure.
+${hasReviewer ? "- For non-trivial diffs, run one fresh read-only `reviewer` sub-agent before reporting done. Fix only concrete blockers and re-review at most once.\n- Use multi-model cross-review only when explicitly requested or for genuinely high-risk changes (security, unsafe/FFI, persistence-migration, concurrency). Reviewers are read-only; only the main agent edits.\n" : ""}- Commit or push only when explicitly requested, applicable checks pass, and no accepted blockers remain.`;
+}