@arhen/pi-core-subagent 1.3.26 → 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.
-- **Agent files respected.** An `agent` name matching `.agents/agents/<name>.md`, `.claude/agents/<name>.md`, or `.pi/agents/<name>.md` loads that file — body = system prompt, frontmatter `model`/`tools` apply, `model` is validated against the pi model registry. Inline params override the file. Project dirs win over home (`~/.agents` single source → `~/.claude` → `~/.pi`).
+- **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.
@@ -118,24 +118,24 @@ Chain — `{previous}` is replaced with the prior agent's output:
 
 ## Agent files
 
-An `agent` name that matches `<name>.md` in an agents directory loads that file — no inline `prompt` needed. The file body becomes the system prompt; `model` and `tools` frontmatter apply.
+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: Strict API reviewer — auth, rate limiting, error handling
+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 match wins):
+**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/`.
 
-**Precedence** — inline params always win over the file: `prompt` overrides the body, `model` overrides frontmatter `model`, `tools`/`write` override frontmatter `tools`. A file `model` is validated against the pi model registry (unknown model fails the task with a catalog message). Files without frontmatter work too — the whole file is the system prompt.
+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`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.26",
+	"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

@@ -1,5 +1,10 @@
-/** Named agent-file resolution (.agents/.claude/.pi agents dirs). */
-import { existsSync, readFileSync } from "node:fs";
+/** 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";
 
@@ -7,46 +12,104 @@ export interface AgentFileInfo {
 	body: string;
 	model?: string;
 	tools?: string[];
+	description?: string;
 }
 
 const AGENT_DIRS = [".agents/agents", ".claude/agents", ".pi/agents"] as const;
-/** Agent names become file paths — refuse anything that could traverse. */
-const SAFE_NAME = /^[\w.-]+$/;
+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",
+]);
 
-function readAgentFile(dir: string, name: string): AgentFileInfo | undefined {
-	if (!existsSync(dir)) return undefined;
-	const path = join(dir, `${name}.md`);
-	if (!existsSync(path)) return undefined;
-	const { frontmatter, body } = parseFrontmatter(readFileSync(path, "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;
-	return {
-		body,
-		model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
-		tools: tools?.length ? tools : undefined,
-	};
+/** 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;
 }
 
 /**
- * Look up `<name>.md` in agent dirs. Order: for each ancestor of `cwd` (nearest
- * first): `.agents/agents` (single source per the ~/.agents spec) → `.claude/agents`
- * → `.pi/agents`; then home: `~/.agents/agents` → `~/.claude/agents` → `~/.pi/agents`.
- * First match wins. `agentDir` is the pi agent dir (`~/.pi/agent`); home is derived from it.
+ * 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, cwd: string, agentDir: string): AgentFileInfo | undefined {
-	if (!SAFE_NAME.test(name)) return undefined;
+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) {
-			const hit = readAgentFile(join(dir, sub), name);
-			if (hit) return hit;
+			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;
@@ -54,8 +117,16 @@ export function resolveAgentFile(name: string, cwd: string, agentDir: string): A
 	}
 	const home = dirname(dirname(agentDir)); // ~/.pi/agent → ~
 	for (const sub of AGENT_DIRS) {
-		const hit = readAgentFile(join(home, sub), name);
-		if (hit) return hit;
+		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. An `agent` name matching a file in `.agents/agents`, `.claude/agents`, or `.pi/agents` (project dirs, then home) loads it: body = system prompt, frontmatter `model`/`tools` apply; inline prompt/model/tools/write override the file. 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. An `agent` name that matches an existing file in `.agents/agents`, `.claude/agents`, or `.pi/agents` (project first, then home) loads that agent — body = system prompt, frontmatter `model`/`tools` apply, file `model` is validated against the model registry; inline params override the file. Files without frontmatter work too.",
+			"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

@@ -632,19 +632,20 @@ export class SubagentManager {
 	): Promise<void> {
 		if (TERMINAL.includes(task.status)) return; // canceled while queued
 
-		// Named agent file (`.agents/agents` etc.): body = system prompt, frontmatter
-		// model/tools fill gaps. Inline params always win over the file.
-		const file = resolveAgentFile(input.agent, task.cwd, getAgentDir());
-		const prompt = input.prompt?.trim() ?? file?.body;
+		// 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 : (file?.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 ?? file?.model);
+			model = resolveChildModel(ctx, file?.model ?? input.model);
 			validateThinking(model, thinking);
 		} catch (err) {
 			this.updateTask(