@arhen/pi-core-subagent 1.3.25 → 1.3.27

package/README.md

@@ -50,7 +50,7 @@ flowchart LR
 - **A bad graph fails before it spawns.** Unknown ids, self-edges and cycles are rejected at call time — never halfway through a run with three children already burning tokens.
 - **Proof is an exit code, never a self-report.** Tasks are asked for a runnable `Verify:` command; the leader checks `git diff --stat`. Agents auditing their own work score ~0. ([why](#why-9-is-a-verification-command-not-a-self-report))
 - **No ceremony without edges.** Six independent reviewers stay six independent reviewers — no waves, no gates, no graph vocabulary imposed on flat work.
-- **No agent files, no discovery.** The leader defines every subagent inline per call — name, system prompt, toolset. Nothing is read from or written to disk.
+- **Agent files respected.** A spawn goal (name + task) that matches a user agent file's `description` (`.agents/agents`, `.claude/agents`, `.pi/agents` — project then home) loads that file — body = system prompt, frontmatter `model`/`tools` apply, file `model` validated against the pi model registry. File wins over inline; no match → on-demand definition.
 - **Two toolsets only.** Read-only (`read, grep, find, ls` — default) or write (`read, grep, find, ls, bash, edit, write` — `write: true`). No per-agent tool config surface.
 - **In-process** — children are `AgentSession`s in the same runtime. No process spawn, no context bleed.
 - **Zero parent-context injection.** No catalog, no context hook. 6 slim tools total.
@@ -83,7 +83,7 @@ The dotted arrows are the whole point: a child may burn 200k tokens reading file
 
 ## Usage — the leader invents the agents
 
-Define agents inline per call — never creates or reads agent files. Model resolution: explicit `provider/model-id` (or bare id) via the pi model registry → agent-file `model` → the parent's current model → settings default.
+Define agents inline per call, or reference a named agent file (see [Agent files](#agent-files)). Model resolution: explicit `model` → agent-file `model` (validated against the pi model registry) → the parent's current model → settings default.
 
 ```json
 {
@@ -116,6 +116,27 @@ Chain — `{previous}` is replaced with the prior agent's output:
 }
 ```
 
+## Agent files
+
+A user agent file in an agents directory is matched by its `description` frontmatter against the spawn goal (`agent` name + `task`) — not by name. When matched, the file is **authoritative**: body = system prompt, frontmatter `model`/`tools` apply, inline `prompt`/`model`/`tools` are ignored. No match → the inline on-demand definition stands. The model stays in control: it names the agent and states the goal; user files that describe that goal take over.
+
+```md
+---
+name: api-reviewer
+description: reviews APIs for auth, rate limiting, and error handling
+model: claude-opus-4-6
+tools: read, grep, find, ls
+---
+You are a strict API reviewer. Check auth, rate limiting, and error handling. Cite file:line.
+```
+
+**Lookup order** (first directory with a match wins):
+
+1. `.agents/agents/` then `.claude/agents/` then `.pi/agents/` in each directory from the task `cwd` up to the filesystem root (nearest ancestor wins).
+2. Home: `~/.agents/agents/` (single source) → `~/.claude/agents/` → `~/.pi/agents/`.
+
+Within a directory the file with the highest description-overlap score wins (≥2 shared meaningful tokens). A file `model` is validated against the pi model registry (unknown model fails the task with a catalog message). Files without a `description` frontmatter never match.
+
 ## Graph mode — `needs`
 
 `parallel` runs everything at once; `chain` runs everything one at a time. Most real work is neither. Give a task an `id` and list the ids it `needs`:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.25",
+	"version": "1.3.27",
 	"type": "module",
 	"description": "pi extension: fast in-process subagents with a dependency-graph scheduler (needs edges gate tasks and carry upstream output into dependent prompts), plus background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
 	"license": "MIT",

package/src/agentfile.ts

@@ -0,0 +1,132 @@
+/** Agent-file resolution — matched by description (goal), not by name.
+ *  The model names a subagent with a goal (name + task); user agent files in
+ *  `.agents/agents`, `.claude/agents`, `.pi/agents` are scored by token overlap
+ *  between their `description` frontmatter and that goal. Best match wins;
+ *  ties break by directory priority. A matched file is authoritative (file wins
+ *  over inline prompt/model/tools). No match → inline on-demand definition. */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export interface AgentFileInfo {
+	body: string;
+	model?: string;
+	tools?: string[];
+	description?: string;
+}
+
+const AGENT_DIRS = [".agents/agents", ".claude/agents", ".pi/agents"] as const;
+const STOP = new Set([
+	"the",
+	"a",
+	"an",
+	"of",
+	"for",
+	"and",
+	"or",
+	"to",
+	"in",
+	"on",
+	"with",
+	"by",
+	"at",
+	"during",
+	"your",
+	"you",
+	"their",
+	"its",
+	"is",
+	"are",
+	"be",
+	"as",
+	"how",
+	"what",
+	"when",
+	"who",
+]);
+
+/** Lowercase, split, drop stopwords, strip plural -s/-es. */
+function tokens(text: string): string[] {
+	return (text.toLowerCase().match(/[a-z0-9]+/g) ?? [])
+		.filter((t) => !STOP.has(t) && t.length > 1)
+		.map((t) => {
+			if (t.endsWith("ing") && t.length > 5) t = t.slice(0, -3);
+			if (t.endsWith("es") && t.length > 4) t = t.slice(0, -2);
+			else if (t.endsWith("s") && t.length > 3) t = t.slice(0, -1);
+			return t;
+		});
+}
+
+function score(query: string[], desc: string[]): number {
+	let shared = 0;
+	for (const t of query) if (desc.includes(t)) shared += 1;
+	return shared >= 2 ? shared : 0;
+}
+
+function readAgentFile(dir: string): AgentFileInfo[] {
+	if (!existsSync(dir)) return [];
+	const out: AgentFileInfo[] = [];
+	for (const entry of readdirSync(dir)) {
+		if (!entry.endsWith(".md")) continue;
+		const { frontmatter, body } = parseFrontmatter(readFileSync(join(dir, entry), "utf8"));
+		const tools =
+			typeof frontmatter.tools === "string"
+				? frontmatter.tools
+						.split(",")
+						.map((t) => t.trim())
+						.filter(Boolean)
+				: Array.isArray(frontmatter.tools)
+					? frontmatter.tools.map(String)
+					: undefined;
+		out.push({
+			body,
+			model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
+			tools: tools?.length ? tools : undefined,
+			description: typeof frontmatter.description === "string" ? frontmatter.description : undefined,
+		});
+	}
+	return out;
+}
+
+/**
+ * Best agent-file match for a spawn goal. Order: `.agents/agents` (single
+ * source) → `.claude/agents` → `.pi/agents` per cwd ancestor (nearest first),
+ * then home (`~/.agents` → `~/.claude` → `~/.pi`). Within a dir, highest
+ * description-overlap score wins; the first dir with a match is returned.
+ * `agentDir` is the pi agent dir (`~/.pi/agent`); home is derived from it.
+ */
+export function resolveAgentFile(name: string, task: string, cwd: string, agentDir: string): AgentFileInfo | undefined {
+	const query = tokens(`${name} ${task}`);
+	let dir = cwd;
+	while (true) {
+		for (const sub of AGENT_DIRS) {
+			let best: AgentFileInfo | undefined;
+			let bestScore = 0;
+			for (const file of readAgentFile(join(dir, sub))) {
+				const s = score(query, tokens(file.description ?? ""));
+				if (s > bestScore) {
+					best = file;
+					bestScore = s;
+				}
+			}
+			if (best) return best; // first dir with any match wins (priority over score)
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	const home = dirname(dirname(agentDir)); // ~/.pi/agent → ~
+	for (const sub of AGENT_DIRS) {
+		let best: AgentFileInfo | undefined;
+		let bestScore = 0;
+		for (const file of readAgentFile(join(home, sub))) {
+			const s = score(query, tokens(file.description ?? ""));
+			if (s > bestScore) {
+				best = file;
+				bestScore = s;
+			}
+		}
+		if (best) return best;
+	}
+	return undefined;
+}

package/src/index.ts

@@ -127,7 +127,7 @@ export default function (pi: ExtensionAPI) {
 		// ponytail: this string is billed on every request. No example block — an example
 		// biases the model toward one shape; guidelines + JSON schema describe all of them.
 		description:
-			"Run isolated subagents (own context, own session). You invent each agent: name, optional system prompt, toolset (read-only default, write:true to edit). Use `agent`+`task` for one, `tasks` for many. `needs` declares dependency edges: a task waits for its needs and receives their outputs prepended to its prompt. Every run is background: the call returns a runId immediately and completion notifies you. Set autoAwait:true when you need the result before your next step — the call parks until the run finishes and returns runId + final result in one response. allowIntercom:true lets children talk to you and each other.",
+			"Run isolated subagents (own context, own session). You invent each agent: name, optional system prompt, toolset (read-only default, write:true to edit). Use `agent`+`task` for one, `tasks` for many. `needs` declares dependency edges: a task waits for its needs and receives their outputs prepended to its prompt. If a user agent file in `.agents/agents`, `.claude/agents`, or `.pi/agents` (project dirs, then home) has a `description` matching the spawn goal (name + task), that file is authoritative: body = system prompt, frontmatter `model`/`tools` apply, inline prompt/model/tools ignored. No match → the inline definition stands. Every run is background: the call returns a runId immediately and completion notifies you. Set autoAwait:true when you need the result before your next step — the call parks until the run finishes and returns runId + final result in one response. allowIntercom:true lets children talk to you and each other.",
 		promptSnippet: "Define and delegate work to specialized subagents.",
 		promptGuidelines: [
 			"Use subagent when independent review, testing, research, or parallel analysis improves quality.",
@@ -135,7 +135,7 @@ export default function (pi: ExtensionAPI) {
 			"Order comes from `needs`, not from separate calls: give tasks an `id`, list the ids each depends on. Tasks with no unmet needs run in parallel; dependents receive their upstream outputs automatically — do not restate them.",
 			"Prefer flat `tasks` (plain parallel) unless a real dependency exists — only add `needs` edges when ordering genuinely matters.",
 			"End each task with a runnable check, e.g. 'Verify: npx tsc --noEmit && bun test'. A subagent's claim of success is not evidence.",
-			"Define each agent yourself: invented name, focused system prompt, and read-only (default) or write:true. Prefer read-only.",
+			"Define each agent yourself: invented name, focused system prompt, and read-only (default) or write:true. Prefer read-only. A user agent file (`.agents/agents`, `.claude/agents`, `.pi/agents` — project first, then home) whose `description` matches the spawn goal (name + task) takes over: its body is the system prompt, frontmatter `model`/`tools` apply and are validated against the model registry. Matching is by description, not name — name the agent whatever fits the goal.",
 			"When you need a run's result before your next step, spawn with autoAwait:true — the call returns runId + final result in one response. Otherwise spawn background and settle results (await_subagent / subagent_result) before continuing dependent work.",
 			"For long multi-task runs, don't autoAwait the whole run: spawn background, then loop await_subagent with short timeoutMs slices (e.g. 20s), processing whichever tasks completed in each slice while the rest keep running. You get incremental results instead of one big wait.",
 			"allowIntercom:true only when a child may need to ask you something.",

package/src/manager.ts

@@ -16,6 +16,7 @@ import {
 	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import type { TUI } from "@earendil-works/pi-tui";
+import { resolveAgentFile } from "./agentfile.ts";
 import { CHILD_TALK_TOOLS, type ChildHandlers, createChildTools, createWatchdog, type Watchdog } from "./child.ts";
 import {
 	activitySnippet,
@@ -631,18 +632,20 @@ export class SubagentManager {
 	): Promise<void> {
 		if (TERMINAL.includes(task.status)) return; // canceled while queued
 
-		// Inline params win; otherwise fall back to an existing agent file
-		// (~/.agents, .pi/agents, user dir). Never creates files.
-		const prompt = input.prompt?.trim();
+		// Matched user agent file (`.agents/agents` etc., by description): the file
+		// is authoritative — body = system prompt, frontmatter model/tools win over
+		// inline. No match → inline on-demand definition as usual.
+		const file = resolveAgentFile(input.agent, input.task, task.cwd, getAgentDir());
+		const prompt = file?.body ?? input.prompt?.trim();
 		const thinking = input.thinking;
-		const baseTools = input.tools ?? (input.write ? WRITE_TOOLS : READONLY_TOOLS);
+		const baseTools = file?.tools ?? input.tools ?? (input.write ? WRITE_TOOLS : READONLY_TOOLS);
 		const tools = [...baseTools, ...(run.allowIntercom ? CHILD_TALK_TOOLS : [])];
 
 		// Model + thinking resolve against the pi model registry; a bad request
 		// fails the TASK with a helpful message, not the whole run.
 		let model: Model<Api> | undefined;
 		try {
-			model = resolveChildModel(ctx, input.model);
+			model = resolveChildModel(ctx, file?.model ?? input.model);
 			validateThinking(model, thinking);
 		} catch (err) {
 			this.updateTask(