@arhen/pi-core-subagent 1.3.26 → 1.3.28

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.28",
 	"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/format.ts

@@ -15,7 +15,7 @@ import {
 } from "./types.ts";
 
 /** Cap on a single child's final output (and on full-run summaries). */
-export const FINAL_OUTPUT_CAP = 24 * 1024;
+const FINAL_OUTPUT_CAP = 24 * 1024;
 
 export function truncateText(text: string, max = FINAL_OUTPUT_CAP): string {
 	if (Buffer.byteLength(text, "utf8") <= max) return text;
@@ -29,7 +29,7 @@ export function getFirstText(message: AssistantMessage): string {
 	}
 	return "";
 }
-export function fmtTokens(n: number): string {
+function fmtTokens(n: number): string {
 	return n >= 1000 ? `${(n / 1000).toFixed(1).replace(/\.0$/, "")}k` : String(n);
 }
 export function formatUsage(usage: UsageStats): string {
@@ -48,18 +48,18 @@ export function statusIcon(status: TaskStatus | RunStatus): string {
 	if (status === "queued") return "○";
 	return "•";
 }
-export function fmtDuration(ms: number | undefined): string {
+function fmtDuration(ms: number | undefined): string {
 	if (ms === undefined || !Number.isFinite(ms)) return "–";
 	const s = Math.max(0, Math.round(ms / 1000));
 	return s >= 60 ? `${Math.floor(s / 60)}m${s % 60}s` : `${s}s`;
 }
-export function taskTimer(task: TaskSnapshot): string {
+function taskTimer(task: TaskSnapshot): string {
 	if (task.startedAt === undefined) return "–";
 	const end = task.endedAt ?? Date.now();
 	const running = !TERMINAL.includes(task.status);
 	return `${running ? "running " : ""}${fmtDuration(end - task.startedAt)}`;
 }
-export function taskStatsWithUsage(task: TaskSnapshot): string {
+function taskStatsWithUsage(task: TaskSnapshot): string {
 	const stats = `${task.toolCalls ?? 0} tools`;
 	const usage = formatUsage(task.usage);
 	return `${stats}${usage ? ` · ${usage}` : ""}`;
@@ -82,7 +82,7 @@ export function colorNums(text: string, theme: Theme): string {
  * Themed one-liner. Finished tasks dim entirely (stats included); live tasks
  * keep the agent name readable with themed numbers.
  */
-export function themedTaskLine(task: TaskSnapshot, theme: Theme, activity = ""): string {
+function themedTaskLine(task: TaskSnapshot, theme: Theme, activity = ""): string {
 	const tail = `${taskStatsWithUsage(task)} · ${taskTimer(task)}`;
 	// Queued task with unmet needs: show the gate it's waiting on instead of empty stats.
 	const gate =
@@ -101,7 +101,7 @@ export function themedTaskLine(task: TaskSnapshot, theme: Theme, activity = ""):
  * unknown/custom tools then read fine too. Add a case only if one reads badly.
  */
 // Order matters: the most specific arg wins (grep's pattern beats its path).
-export const ARG_KEYS = [
+const ARG_KEYS = [
 	"pattern",
 	"query",
 	"command",
@@ -132,7 +132,7 @@ export function activitySnippet(text: string): string {
 }
 
 /** Mailbox/intercom tools — while one is the task's last activity, the agent is "talking". */
-export const TALK_TOOLS = ["poll_agent_messages", "send_agent_message", "ask_parent", "notify_parent"];
+const TALK_TOOLS = ["poll_agent_messages", "send_agent_message", "ask_parent", "notify_parent"];
 export function isTalking(task: TaskSnapshot): boolean {
 	const a = task.lastActivity?.toLowerCase() ?? "";
 	return TALK_TOOLS.some((t) => a.startsWith(t));
@@ -155,7 +155,7 @@ export function compactLines(run: RunSnapshot): string[] {
  *   └─ ✓ reviewer · 6 tools · 44s
  * Static icons (no animation); latest activity + tool count + runtime per agent.
  */
-export const WIDGET_MAX_LINES = 10;
+const WIDGET_MAX_LINES = 10;
 
 export class SubagentsWidget implements Component {
 	constructor(

package/src/graph.ts

@@ -85,7 +85,7 @@ export function applyUpstream(task: string, needs: string[], outputs: Map<string
 	return `${blocks.join("\n\n")}\n\n---\n\n${body}`;
 }
 
-export async function mapWithConcurrency<T>(
+async function mapWithConcurrency<T>(
 	items: T[],
 	concurrency: number,
 	fn: (item: T, index: number) => Promise<void>,

package/src/index.ts

@@ -1,11 +1,11 @@
 /**
- * minimalist-subagents — pi extension.
+ * pi-core-subagent — in-process subagents.
  *
  * Fast in-process subagents (isolated AgentSessions, no process spawn).
  * Modes: single / parallel / chain. Background runs, cancel, intercom
  * (ask/notify/update the leader) and agent↔agent mailbox (send/poll).
  *
- * Context discipline: 6 slim parent tools, one-line catalog injected per
+ * Context discipline: 7 slim parent tools, one-line catalog injected per
  * request (cached), background completions notify with a 3-line summary
  * instead of full outputs, and run updates are throttled (no per-event
  * deep clones).
@@ -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

@@ -47,21 +47,21 @@ import {
 export const DEFAULT_CONCURRENCY = 3;
 export const MAX_CONCURRENCY = 8;
 /** No default wall-clock cap: a subagent runs until its task is done, it stalls, or the user aborts. */
-export const DEFAULT_RUNTIME_MS = 0;
-export const DEFAULT_STALL_MS = 180_000; // 3 min: long model thinking streams emit no events, but they're not stalled.
-export const READONLY_TOOLS = ["read", "grep", "find", "ls"];
-export const WRITE_TOOLS = ["read", "grep", "find", "ls", "bash", "edit", "write"];
+const DEFAULT_RUNTIME_MS = 0;
+const DEFAULT_STALL_MS = 180_000; // 3 min: long model thinking streams emit no events, but they're not stalled.
+const READONLY_TOOLS = ["read", "grep", "find", "ls"];
+const WRITE_TOOLS = ["read", "grep", "find", "ls", "bash", "edit", "write"];
 const WIDGET_THROTTLE_MS = 150;
 
 // ── helpers ──────────────────────────────────────────────────────────────
 
-export function newId(prefix: string): string {
+function newId(prefix: string): string {
 	return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 }
-export function emptyUsage(): UsageStats {
+function emptyUsage(): UsageStats {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
 }
-export function aggregateUsage(tasks: TaskSnapshot[]): UsageStats {
+function aggregateUsage(tasks: TaskSnapshot[]): UsageStats {
 	const total = emptyUsage();
 	for (const task of tasks) {
 		total.input += task.usage.input;
@@ -73,7 +73,7 @@ export function aggregateUsage(tasks: TaskSnapshot[]): UsageStats {
 	}
 	return total;
 }
-export function getParentSessionFile(ctx: ExtensionContext): string | undefined {
+function getParentSessionFile(ctx: ExtensionContext): string | undefined {
 	try {
 		return ctx.sessionManager.getSessionFile?.();
 	} catch {
@@ -92,7 +92,7 @@ export function classifyFailure(
 	if (stopReason === "aborted") return { status: "aborted", message: errorMessage || "Subagent was aborted." };
 	return { status: "failed", message: errorMessage || `Subagent ended with stopReason "${stopReason}".` };
 }
-export function lastAssistantFailure(
+function lastAssistantFailure(
 	messages: AssistantMessage[] | undefined,
 ): { status: "failed" | "aborted"; message: string } | undefined {
 	for (const message of [...(messages ?? [])].reverse()) {
@@ -101,12 +101,12 @@ export function lastAssistantFailure(
 	}
 	return undefined;
 }
-export function failureError(failure: { status: "failed" | "aborted"; message: string }): Error {
+function failureError(failure: { status: "failed" | "aborted"; message: string }): Error {
 	const error = new Error(failure.message);
 	(error as Error & { subagentStatus?: string }).subagentStatus = failure.status;
 	return error;
 }
-export function updateUsageFromMessage(task: TaskSnapshot, message: AssistantMessage): void {
+function updateUsageFromMessage(task: TaskSnapshot, message: AssistantMessage): void {
 	if (message?.role !== "assistant") return;
 	task.usage.turns += 1;
 	const usage = message.usage;
@@ -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(
@@ -1079,7 +1080,6 @@ export class SubagentManager {
 		s(cloneRun(run));
 	}
 
-	/** Child→leader messages collected while the parent is parked in await_subagent. */
 	/** Child→leader messages collected while the parent is parked in await_subagent. */
 	private parked = new Map<string, { msgs: ParkedMsg[]; wake: () => void }>();