@arhen/pi-core-subagent 1.3.25 → 1.3.26

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.** 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`).
 - **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
+
+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.
+
+```md
+---
+name: api-reviewer
+description: Strict API reviewer — auth, rate limiting, 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):
+
+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.
+
 ## 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.26",
 	"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,61 @@
+/** Named agent-file resolution (.agents/.claude/.pi agents dirs). */
+import { existsSync, 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[];
+}
+
+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.-]+$/;
+
+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,
+	};
+}
+
+/**
+ * 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.
+ */
+export function resolveAgentFile(name: string, cwd: string, agentDir: string): AgentFileInfo | undefined {
+	if (!SAFE_NAME.test(name)) return undefined;
+	let dir = cwd;
+	while (true) {
+		for (const sub of AGENT_DIRS) {
+			const hit = readAgentFile(join(dir, sub), name);
+			if (hit) return hit;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	const home = dirname(dirname(agentDir)); // ~/.pi/agent → ~
+	for (const sub of AGENT_DIRS) {
+		const hit = readAgentFile(join(home, sub), name);
+		if (hit) return hit;
+	}
+	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. 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.",
 		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. 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.",
 			"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,19 @@ 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();
+		// 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;
 		const thinking = input.thinking;
-		const baseTools = input.tools ?? (input.write ? WRITE_TOOLS : READONLY_TOOLS);
+		const baseTools = input.tools ?? (input.write ? WRITE_TOOLS : (file?.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, input.model ?? file?.model);
 			validateThinking(model, thinking);
 		} catch (err) {
 			this.updateTask(