@ferris1225/pi-subagents 4.2.5 → 4.2.8

package/agents/executor.md

@@ -1,53 +1,53 @@
----
-name: executor
-description: Default route for any delegated, self-contained task — implement, fix, refactor, test, clean up, sync docs, or merge fan-out results — then verify and hand off.
-thinking: high
-# No `tools` field => inherits all tools (full capability).
----
-
-You are an executor agent with full capabilities in an isolated context window. You own one delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
-
-Repository instructions (AGENTS.md) and any skills available in this session apply to you as to any agent: follow their process for the domains they own (language style, tests, debugging, cleanup discipline, verification). Where a skill covers the same ground as this brief, the skill's discipline wins — except for the release boundary below, which always wins.
-
-## Procedure
-
-1. **Context.** Read the brief fully, plus referenced files and images, before acting. If critical context is missing, state what is missing rather than guessing.
-2. **Plan.** Inspect existing code and conventions first; form the smallest coherent root-cause change that satisfies the brief. Prefer the design that deletes complexity over one that rearranges it. No unrelated refactors or standalone docs work unless the brief asks.
-3. **Implement.** Preserve the user's work; limit edits to the request plus required validation. Follow the project's error handling, naming, and style. Synchronize README/docs/comments your change directly affects; never defer that drift.
-4. **Verify.** Run the project's format/build/tests when they exist. NEVER report an unrun check as passed — report it as unavailable or a pre-existing failure, with the exact error.
-
-## Cleanup work
-
-When the brief authorizes cleanup (dead code, duplication, simplification), a candidate is not a deletion: re-read the load-bearing files and repeat the decisive searches yourself — never inherit proof from another agent's report. Search the whole repository for consumers before removing anything, and keep a candidate when a real consumer exists, dynamic reachability is unresolved, or the cut removes a user capability, public API, persisted format, or compatibility path unless the brief explicitly approves it. Consolidate semantically equivalent duplicates by extracting the smallest stable shared helper and migrating every in-scope caller. Finding no safe cut and making zero edits is valid.
-
-## Merging inputs
-
-When the brief names several inputs (result artifacts, reports, logs), read every input fully before writing. Deduplicate restatements into one attributed entry, verify disagreements with a short read when a cited file settles them, and report surviving conflicts side by side instead of averaging them away. Stay within the named inputs; report what they cannot answer as a gap.
-
-## Boundaries
-
-- Never commit, push, publish, tag, release, or bump a package version — the caller owns every release action, even when repository instructions normally automate release after green checks.
-- Children are leaf processes: you cannot dispatch sub-agents.
-- Never change runtime behavior to make documentation true; report the defect instead.
-
-## Output format
-
-Return only the concrete outcome. Do not repeat the task brief, the plan, the root-cause investigation, or the tool chronology.
-
-## Completed
-
-What was done, in a few lines.
-
-## Files Changed
-
-- `path/to/file.ts` — what changed.
-
-## Verification
-
-Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean; `vitest` 12 passed). State explicitly anything you could not run and why.
-
-## Notes (only when material)
-
-Unresolved blockers, rejected requirements, or decisions the caller must know. Omit when nothing actionable.
-
-Keep the final response comfortably below the 40-line delivery cap unless the result genuinely requires more.
+---
+name: executor
+description: A self-contained unit that changes the repository or condenses inputs — implement, fix, refactor, test, clean up, sync docs, merge fan-out results — carried through verification to a result-only handoff.
+thinking: high
+# No `tools` field => inherits all tools (full capability).
+---
+
+You are an executor agent with full capabilities in an isolated context window. You own one delegated, self-contained task end to end so the main conversation stays clean. You have NOT got the caller's conversation history — the task brief is your source of truth.
+
+Repository instructions (AGENTS.md) and any skills available in this session apply to you as to any agent: follow their process for the domains they own (language style, tests, debugging, cleanup discipline, verification). Where a skill covers the same ground as this brief, the skill's discipline wins — except for the release boundary below, which always wins.
+
+## Procedure
+
+1. **Context.** Read the brief fully, plus referenced files and images, before acting. If critical context is missing, state what is missing rather than guessing.
+2. **Plan.** Inspect existing code and conventions first; form the smallest coherent root-cause change that satisfies the brief. Prefer the design that deletes complexity over one that rearranges it. No unrelated refactors or standalone docs work unless the brief asks.
+3. **Implement.** Preserve the user's work; limit edits to the request plus required validation. Follow the project's error handling, naming, and style. Synchronize README/docs/comments your change directly affects; never defer that drift.
+4. **Verify.** Run the project's format/build/tests when they exist. NEVER report an unrun check as passed — report it as unavailable or a pre-existing failure, with the exact error.
+
+## Conditional playbooks
+
+Skip both unless the brief matches one.
+
+**Cleanup** (dead code, duplication, simplification): a candidate is not a deletion. Re-read the load-bearing files and repeat the decisive searches yourself — never inherit proof from another agent's report — and search the whole repository for consumers first. Keep a candidate when a real consumer exists, dynamic reachability is unresolved, or the cut removes a user capability, public API, persisted format, or compatibility path the brief did not explicitly approve. Finding no safe cut and making zero edits is valid.
+
+**Merging inputs** (result artifacts, reports, logs): read every named input fully before writing, deduplicate restatements into one attributed entry, and report surviving conflicts side by side instead of averaging them away. Stay within the named inputs; report what they cannot answer as a gap.
+
+## Boundaries
+
+- Never commit, push, publish, tag, release, or bump a package version — the caller owns every release action, even when repository instructions normally automate release after green checks.
+- Children are leaf processes: you cannot dispatch sub-agents.
+- Never change runtime behavior to make documentation true; report the defect instead.
+
+## Output format
+
+Return only the concrete outcome. Do not repeat the task brief, the plan, the root-cause investigation, or the tool chronology.
+
+## Completed
+
+What was done, in a few lines.
+
+## Files Changed
+
+- `path/to/file.ts` — what changed.
+
+## Verification
+
+Which checks you ACTUALLY ran and their result (e.g. `tsc --noEmit` clean; `vitest` 12 passed). State explicitly anything you could not run and why.
+
+## Notes (only when material)
+
+Unresolved blockers, rejected requirements, or decisions the caller must know. Omit when nothing actionable.
+
+Keep the final response comfortably below the 40-line delivery cap unless the result genuinely requires more.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.2.5",
+  "version": "4.2.8",
   "description": "A managed sub-agent team for pi: specialized roles, pre-commit documentation sync, retained threads, auto-fix chains, model fallback, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",
@@ -29,8 +29,7 @@
   },
   "scripts": {
     "check": "tsc --noEmit",
-    "test": "vitest run tests",
-    "prepack": "npm run check && npm test"
+    "prepack": "npm run check"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": ">=0.84.4",
@@ -46,8 +45,7 @@
     "@earendil-works/pi-tui": "^0.84.4",
     "@types/node": "^22.10.0",
     "typebox": "^1.3.9",
-    "typescript": "^5.9.0",
-    "vitest": "^4.1.0"
+    "typescript": "^5.9.0"
   },
   "engines": {
     "node": ">=22.19.0"

package/src/agents.ts

@@ -1,237 +1,237 @@
-/**
- * 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 { THINKING_LEVEL_VALUES, type AgentScope, type ThinkingLevel } from "./config.ts";
-import type { IsolationMode } from "./worktree.ts";
-
-export type AgentSource = "builtin" | "user" | "project";
-
-export interface AgentConfig {
-	name: string;
-	description: string;
-	tools?: string[];
-	/** Model ref this run was routed to; filled in by dispatch, never declared by the agent file. */
-	model?: string;
-	/** Per-agent default thinking strength (frontmatter `thinking`); config override wins. */
-	thinking?: ThinkingLevel;
-	/** Role-declared default isolation (frontmatter `isolation`); an explicit
-	 * per-call request wins, and `worktree` applies to write-capable roles only. */
-	isolation?: IsolationMode;
-	systemPrompt: string;
-	source: AgentSource;
-	filePath: string;
-}
-
-const SHELL_TOOL_NAMES = new Set(["bash", "powershell"]);
-/** The shell that actually fits the host: PowerShell on Windows, Bash elsewhere.
- * Only used to break a tie when the parent has both enabled — a parent running a
- * single shell is followed as configured, whatever it is. */
-const NATIVE_SHELL_TOOL = process.platform === "win32" ? "powershell" : "bash";
-const PI_BUILTIN_TOOL_NAMES = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"]);
-export const SUBAGENT_TOOL_NAMES = [
-	"subagent",
-	"subagent_control",
-	"subagent_stop",
-] as const;
-const SUBAGENT_TOOL_NAME_SET = new Set<string>(SUBAGENT_TOOL_NAMES);
-
-/** Resolve every child against the parent's live tool selection. Roles without
- * an allowlist inherit the complete active set. Explicit lists keep only their
- * declared Pi built-ins, adapt an existing shell slot, and gain active extension/
- * SDK tools. pi-subagents controls are always removed so children stay leaves.
- *
- * A declared shell is one slot, so it resolves to one shell: the parent's, and
- * the host-native one when the parent runs both. A child never inherits a shell
- * the parent does not have — Pi's `--tools` allowlist overrides the child's own
- * `defaultTools` setting, so naming a shell the user disabled would hand it a
- * terminal they deliberately turned off. */
-export function resolveAgentTools(
-	agent: AgentConfig,
-	activeToolNames: readonly string[],
-): AgentConfig {
-	const active = [...new Set(activeToolNames)].filter((tool) => !SUBAGENT_TOOL_NAME_SET.has(tool));
-	if (!agent.tools) return { ...agent, tools: active };
-
-	const parentShellTools = active.filter((tool) => SHELL_TOOL_NAMES.has(tool));
-	const activeShellTools = parentShellTools.length > 1 && parentShellTools.includes(NATIVE_SHELL_TOOL)
-		? [NATIVE_SHELL_TOOL]
-		: parentShellTools;
-	const tools: string[] = [];
-	let shellAdapted = false;
-	for (const tool of agent.tools) {
-		if (SHELL_TOOL_NAMES.has(tool)) {
-			if (!shellAdapted) tools.push(...activeShellTools);
-			shellAdapted = true;
-		} else if (PI_BUILTIN_TOOL_NAMES.has(tool) && !tools.includes(tool)) {
-			tools.push(tool);
-		}
-	}
-	for (const tool of active) {
-		if (PI_BUILTIN_TOOL_NAMES.has(tool) || tools.includes(tool)) continue;
-		tools.push(tool);
-	}
-	return { ...agent, tools };
-}
-
-/** Filesystem-write capability used by worktree admission and repository-lane
- * safety. Built-in read-only role names remain read-only even when overridden;
- * an omitted tool list inherits the parent's active set, so it counts as
- * write-capable unless the parent itself is read-only. */
-export function isWriteCapableAgent(
-	agent: Pick<AgentConfig, "name" | "tools">,
-): boolean {
-	if (agent.name === "explorer") return false;
-	if (agent.name === "executor") return true;
-	if (!agent.tools) return true;
-	return agent.tools.includes("edit") || agent.tools.includes("write");
-}
-
-const here = dirname(fileURLToPath(import.meta.url));
-/** <package>/agents — the agents shipped with this extension. */
-export const BUILTIN_AGENTS_DIR = join(here, "..", "agents");
-
-/** Agents shipped with the package (used by the setup wizard for per-agent defaults). */
-export function loadBuiltinAgents(): AgentConfig[] {
-	return loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin");
-}
-
-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);
-		// YAML values are not guaranteed strings; anything non-string is invalid for these fields.
-		const str = (value: unknown): string | undefined => (typeof value === "string" ? value : undefined);
-		const name = str(frontmatter.name);
-		const description = str(frontmatter.description);
-		// name + description are required; skip malformed files silently.
-		if (!name || !description) continue;
-
-		const rawTools = str(frontmatter.tools);
-		const tools = rawTools
-			?.split(",")
-			.map((t) => t.trim())
-			.filter(Boolean);
-		const rawThinking = str(frontmatter.thinking)?.trim();
-		const thinking = (THINKING_LEVEL_VALUES as readonly string[]).includes(rawThinking ?? "")
-			? (rawThinking as ThinkingLevel)
-			: undefined;
-		const rawIsolation = str(frontmatter.isolation)?.trim();
-		const isolation = rawIsolation === "worktree" || rawIsolation === "shared"
-			? (rawIsolation as IsolationMode)
-			: undefined;
-
-		agents.push({
-			name,
-			description,
-			tools: tools && tools.length > 0 ? tools : undefined,
-			...(thinking ? { thinking } : {}),
-			...(isolation ? { isolation } : {}),
-			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, only agents whose name is listed are returned. */
-	enabledNames?: readonly string[];
-	/** Project-controlled prompts are loaded only after Pi trusts the project. */
-	projectTrusted?: boolean;
-	/** Override the built-in agents directory (used by tests). */
-	builtinDir?: string;
-}
-
-/**
- * Discover agents across scopes and apply the enabled-name filter.
- * Override priority for the same name: project > user > builtin.
- */
-export function discoverAgents(cwd: string, options: DiscoverOptions = {}): { agents: AgentConfig[] } {
-	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 || options.projectTrusted !== true
-			? []
-			: 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 !== undefined) {
-		const enabled = new Set(options.enabledNames);
-		agents = agents.filter((agent) => enabled.has(agent.name));
-	}
-
-	return { agents };
-}
-
-/** One-line catalog entry for system-prompt injection and error messages. */
-export function formatCatalogEntry(agent: AgentConfig): string {
-	return `- ${agent.name}: ${agent.description}`;
-}
+/**
+ * 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 { THINKING_LEVEL_VALUES, type AgentScope, type ThinkingLevel } from "./config.ts";
+import type { IsolationMode } from "./worktree.ts";
+
+export type AgentSource = "builtin" | "user" | "project";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	/** Model ref this run was routed to; filled in by dispatch, never declared by the agent file. */
+	model?: string;
+	/** Per-agent default thinking strength (frontmatter `thinking`); config override wins. */
+	thinking?: ThinkingLevel;
+	/** Role-declared default isolation (frontmatter `isolation`); an explicit
+	 * per-call request wins, and `worktree` applies to write-capable roles only. */
+	isolation?: IsolationMode;
+	systemPrompt: string;
+	source: AgentSource;
+	filePath: string;
+}
+
+const SHELL_TOOL_NAMES = new Set(["bash", "powershell"]);
+/** The shell that actually fits the host: PowerShell on Windows, Bash elsewhere.
+ * Only used to break a tie when the parent has both enabled — a parent running a
+ * single shell is followed as configured, whatever it is. */
+const NATIVE_SHELL_TOOL = process.platform === "win32" ? "powershell" : "bash";
+const PI_BUILTIN_TOOL_NAMES = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"]);
+export const SUBAGENT_TOOL_NAMES = [
+	"subagent",
+	"subagent_control",
+	"subagent_stop",
+] as const;
+const SUBAGENT_TOOL_NAME_SET = new Set<string>(SUBAGENT_TOOL_NAMES);
+
+/** Resolve every child against the parent's live tool selection. Roles without
+ * an allowlist inherit the complete active set. Explicit lists keep only their
+ * declared Pi built-ins, adapt an existing shell slot, and gain active extension/
+ * SDK tools. pi-subagents controls are always removed so children stay leaves.
+ *
+ * A declared shell is one slot, so it resolves to one shell: the parent's, and
+ * the host-native one when the parent runs both. A child never inherits a shell
+ * the parent does not have — Pi's `--tools` allowlist overrides the child's own
+ * `defaultTools` setting, so naming a shell the user disabled would hand it a
+ * terminal they deliberately turned off. */
+export function resolveAgentTools(
+	agent: AgentConfig,
+	activeToolNames: readonly string[],
+): AgentConfig {
+	const active = [...new Set(activeToolNames)].filter((tool) => !SUBAGENT_TOOL_NAME_SET.has(tool));
+	if (!agent.tools) return { ...agent, tools: active };
+
+	const parentShellTools = active.filter((tool) => SHELL_TOOL_NAMES.has(tool));
+	const activeShellTools = parentShellTools.length > 1 && parentShellTools.includes(NATIVE_SHELL_TOOL)
+		? [NATIVE_SHELL_TOOL]
+		: parentShellTools;
+	const tools: string[] = [];
+	let shellAdapted = false;
+	for (const tool of agent.tools) {
+		if (SHELL_TOOL_NAMES.has(tool)) {
+			if (!shellAdapted) tools.push(...activeShellTools);
+			shellAdapted = true;
+		} else if (PI_BUILTIN_TOOL_NAMES.has(tool) && !tools.includes(tool)) {
+			tools.push(tool);
+		}
+	}
+	for (const tool of active) {
+		if (PI_BUILTIN_TOOL_NAMES.has(tool) || tools.includes(tool)) continue;
+		tools.push(tool);
+	}
+	return { ...agent, tools };
+}
+
+/** Filesystem-write capability used by worktree admission and repository-lane
+ * safety. Built-in read-only role names remain read-only even when overridden;
+ * an omitted tool list inherits the parent's active set, so it counts as
+ * write-capable unless the parent itself is read-only. */
+export function isWriteCapableAgent(
+	agent: Pick<AgentConfig, "name" | "tools">,
+): boolean {
+	if (agent.name === "explorer") return false;
+	if (agent.name === "executor") return true;
+	if (!agent.tools) return true;
+	return agent.tools.includes("edit") || agent.tools.includes("write");
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+/** <package>/agents — the agents shipped with this extension. */
+export const BUILTIN_AGENTS_DIR = join(here, "..", "agents");
+
+/** Agents shipped with the package (used by the setup wizard for per-agent defaults). */
+export function loadBuiltinAgents(): AgentConfig[] {
+	return loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin");
+}
+
+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);
+		// YAML values are not guaranteed strings; anything non-string is invalid for these fields.
+		const str = (value: unknown): string | undefined => (typeof value === "string" ? value : undefined);
+		const name = str(frontmatter.name);
+		const description = str(frontmatter.description);
+		// name + description are required; skip malformed files silently.
+		if (!name || !description) continue;
+
+		const rawTools = str(frontmatter.tools);
+		const tools = rawTools
+			?.split(",")
+			.map((t) => t.trim())
+			.filter(Boolean);
+		const rawThinking = str(frontmatter.thinking)?.trim();
+		const thinking = (THINKING_LEVEL_VALUES as readonly string[]).includes(rawThinking ?? "")
+			? (rawThinking as ThinkingLevel)
+			: undefined;
+		const rawIsolation = str(frontmatter.isolation)?.trim();
+		const isolation = rawIsolation === "worktree" || rawIsolation === "shared"
+			? (rawIsolation as IsolationMode)
+			: undefined;
+
+		agents.push({
+			name,
+			description,
+			tools: tools && tools.length > 0 ? tools : undefined,
+			...(thinking ? { thinking } : {}),
+			...(isolation ? { isolation } : {}),
+			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, only agents whose name is listed are returned. */
+	enabledNames?: readonly string[];
+	/** Project-controlled prompts are loaded only after Pi trusts the project. */
+	projectTrusted?: boolean;
+	/** Override the built-in agents directory (used by tests). */
+	builtinDir?: string;
+}
+
+/**
+ * Discover agents across scopes and apply the enabled-name filter.
+ * Override priority for the same name: project > user > builtin.
+ */
+export function discoverAgents(cwd: string, options: DiscoverOptions = {}): { agents: AgentConfig[] } {
+	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 || options.projectTrusted !== true
+			? []
+			: 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 !== undefined) {
+		const enabled = new Set(options.enabledNames);
+		agents = agents.filter((agent) => enabled.has(agent.name));
+	}
+
+	return { agents };
+}
+
+/** One-line catalog entry for system-prompt injection and error messages. */
+export function formatCatalogEntry(agent: AgentConfig): string {
+	return `- ${agent.name}: ${agent.description}`;
+}