@arhen/pi-core-subagent 1.3.24 → 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`:
@@ -238,7 +259,7 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 
 | Tool | Purpose |
 |---|---|
-| `subagent` | single / `tasks` (parallel or graph via `needs`) / `chain` (`{previous}`); background is the default (`background:false` for inline result in this turn); `allowIntercom:true` enables child talk tools; `notifyPerTask` (default true) wakes you as each task completes (background runs only) |
+| `subagent` | single / `tasks` (parallel or graph via `needs`) / `chain` (`{previous}`); every run is background — returns a runId, completion notifies you; `autoAwait:true` parks the call until the run finishes and returns the final result inline; `allowIntercom:true` enables child talk tools; `notifyPerTask` (default true) wakes you as each task completes |
 | `subagent_status` | live per-task snapshot (non-blocking), including each child's session file path |
 | `subagent_result` | full output of a run or one task |
 | `await_subagent` | block until a run finishes (optional `timeoutMs`) |
@@ -248,7 +269,7 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 
 ### Per-task fields
 
-`agent` (name you invent — required), `task` (required), `prompt` (system prompt, optional — minimal default used), `write` (toolset, default read-only), plus optional `model` (`provider/model-id`), `thinking` (validated enum: `off|minimal|low|medium|high|xhigh|max`), `tools` (explicit allowlist), `cwd`, `maxRuntimeMs`, `id`, `needs` (dependency edges — see [Graph mode](#graph-mode--needs)). Top-level only: `background`, `notifyPerTask`, `allowIntercom`, `concurrency`.
+`agent` (name you invent — required), `task` (required), `prompt` (system prompt, optional — minimal default used), `write` (toolset, default read-only), plus optional `model` (`provider/model-id`), `thinking` (validated enum: `off|minimal|low|medium|high|xhigh|max`), `tools` (explicit allowlist), `cwd`, `maxRuntimeMs`, `id`, `needs` (dependency edges — see [Graph mode](#graph-mode--needs)). Top-level only: `autoAwait`, `notifyPerTask`, `allowIntercom`, `concurrency`.
 
 ### Child talk tools (when `allowIntercom: true`)
 
@@ -259,13 +280,12 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 | `send_agent_message` | message to a sibling subagent's mailbox (`to` = its task id, or `"leader"`) |
 | `poll_agent_messages` | drain this subagent's mailbox |
 
-> **Intercom anti-deadlock:** children are told to never block indefinitely on intercom replies — `ask_parent` keeps the stall watchdog fed while awaiting a parent reply (background runs), and sibling polls are capped (~5 tries) with a proceed-with-best-judgment fallback. Gated siblings (later waves) may not be running yet — waiting on them is the top stall cause, so children are instructed not to.
+> **Intercom anti-deadlock:** children are told to never block indefinitely on intercom replies — `ask_parent` keeps the stall watchdog fed while awaiting a parent reply, and sibling polls are capped (~5 tries) with a proceed-with-best-judgment fallback. Gated siblings (later waves) may not be running yet — waiting on them is the top stall cause, so children are instructed not to.
 
 ## Commands
 
 - `/subagents` — list runs; `/subagents peek` (or `ctrl+shift+a`) — browsable pane
-- `/subagents auto-bg on|off` — toggle background-by-default for subagent calls (persists to `~/.pi/agent/subagents-config.json`; default on). `off` makes calls block until the run finishes, result inline in the same turn. Bare `/subagents auto-bg` shows the current state.
-- `/subagents auto-limit on|off` — toggle leader-imposed `maxRuntimeMs` caps (persists to the same config; default on). `off` strips ALL task timeouts: tasks run unlimited until done, stalled, or aborted — only for runs where a hard bound is genuinely required is a cap kept (none, when off). Bare `/subagents auto-limit` shows the current state.
+- `/subagents auto-limit on|off` — toggle leader-imposed `maxRuntimeMs` caps (persists to `~/.pi/agent/subagents-config.json`; default on). `off` strips ALL task timeouts: tasks run unlimited until done, stalled, or aborted — only for runs where a hard bound is genuinely required is a cap kept (none, when off). Bare `/subagents auto-limit` shows the current state.
 
 ## Peek — `/subagents peek` or `ctrl+shift+a`
 

package/package.json

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

@@ -213,7 +213,7 @@ export function makeSummary(run: RunSnapshot): string {
 	const aborted = run.tasks.filter((t) => t.status === "aborted").length;
 	const done = TERMINAL.includes(run.status) ? "finished" : "running";
 	const lines = [
-		`Run ${run.id}: Subagents ${run.mode}${run.background ? " (background)" : ""} ${done}: ${succeeded}/${run.tasks.length} succeeded${failed ? `, ${failed} failed` : ""}${aborted ? `, ${aborted} aborted` : ""}.`,
+		`Run ${run.id}: Subagents ${run.mode} ${done}: ${succeeded}/${run.tasks.length} succeeded${failed ? `, ${failed} failed` : ""}${aborted ? `, ${aborted} aborted` : ""}.`,
 	];
 	const usage = formatUsage(run.aggregateUsage);
 	if (usage) lines.push(`Usage: ${usage}`);

package/src/index.ts

@@ -16,15 +16,7 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
-import {
-	compactLines,
-	formatUsage,
-	makeSummary,
-	statusIcon,
-	taskLine,
-	themedTaskLine,
-	truncateText,
-} from "./format.ts";
+import { compactLines, formatUsage, makeSummary, statusIcon, taskLine, truncateText } from "./format.ts";
 import { waveNotation } from "./graph.ts";
 import { cloneRun, SubagentManager } from "./manager.ts";
 import { createPeekPane, type PeekTask } from "./peek.ts";
@@ -77,8 +69,7 @@ export default function (pi: ExtensionAPI) {
 		);
 	};
 	pi.registerCommand("subagents", {
-		description:
-			"List subagent runs. `/subagents peek` opens the browsable pane; `/subagents auto-bg on|off` toggles background-by-default.",
+		description: "List subagent runs. `/subagents peek` opens the browsable pane.",
 		handler: async (args, ctx) => {
 			const arg = String(args ?? "")
 				.trim()
@@ -100,22 +91,6 @@ export default function (pi: ExtensionAPI) {
 				}
 				return;
 			}
-			if (arg === "auto-bg" || arg.startsWith("auto-bg ")) {
-				const value = arg.split(/\s+/)[1];
-				if (value === "on" || value === "off") {
-					const next = manager.setAutoBg(value === "on");
-					ctx.ui.notify(
-						`auto-bg ${next ? "on" : "off"} — subagent calls default to ${next ? "background" : "blocking (inline result)"}.`,
-						"info",
-					);
-				} else {
-					ctx.ui.notify(
-						`auto-bg is ${manager.autoBgOn ? "on" : "off"} — use \`/subagents auto-bg on|off\` to change it.`,
-						"info",
-					);
-				}
-				return;
-			}
 			const runs = manager.listRuns().slice(0, 10);
 			if (runs.length === 0) {
 				ctx.ui.notify("No subagent runs in this session.", "info");
@@ -152,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. background is the default (returns a runId immediately; toggle via `/subagents auto-bg off`); set background:false when you need the result inline in this turn. 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.",
@@ -160,29 +135,34 @@ 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.",
-			"Prefer blocking (background:false) whenever the run's result is something you must wait for before your next step — do not default to background for work you depend on inline. When a background run is active, settle its pending results and task dependencies (await_subagent / subagent_result, then continue dependent work) before starting unrelated work.",
-			"For long multi-task runs, don't park the whole turn on one blocking call: start it in the 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 blocking wait.",
+			"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.",
 		],
 		parameters: SubagentParams,
 		executionMode: "parallel", // sibling subagent calls run concurrently, not serialized
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const typed = params as SubagentParamsShape;
-			if ((typed.background ?? manager.autoBgOn) && typed.background !== false) {
-				const details = manager.startInBackground(typed, ctx);
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nUse subagent_status / subagent_result / await_subagent / reply_subagent / subagent_cancel to interact.`,
-						},
-					],
-					details,
-				};
+			const details = manager.startInBackground(typed, ctx);
+			if (typed.autoAwait) {
+				// awaitRun wakes on every child→leader message (ask/notify/done) — that's the
+				// slice-loop feature. autoAwait wants the final result: re-park until terminal.
+				let run = details.run;
+				while (!TERMINAL.includes(run.status)) {
+					run = (await manager.awaitRun(details.run.id))?.run ?? run;
+				}
+				return { content: [{ type: "text", text: makeSummary(run) }], details: { run } };
 			}
-			const details = await manager.runBlocking(typed, signal, onUpdate, ctx);
-			return { content: [{ type: "text", text: makeSummary(details.run) }], details };
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nUse subagent_status / subagent_result / await_subagent / reply_subagent / subagent_cancel to interact.`,
+					},
+				],
+				details,
+			};
 		},
 		renderCall(args, theme) {
 			// ponytail: args stream in partially, so mode is unknowable until JSON closes. Show "preparing…" instead of a wrong "single ?".
@@ -194,9 +174,7 @@ export default function (pi: ExtensionAPI) {
 					: args.agent
 						? `single ${args.agent}`
 						: "preparing…";
-			const flags = [(args.background ?? manager.autoBgOn) ? "bg" : "blocking", args.allowIntercom ? "a2a" : ""]
-				.filter(Boolean)
-				.join(" · ");
+			const flags = [args.autoAwait ? "await" : "bg", args.allowIntercom ? "a2a" : ""].filter(Boolean).join(" · ");
 			// Params used, dimmed: model, thinking, toolset, per-task write count.
 			const tasks = args.tasks ?? args.chain ?? [];
 			const writeCount = tasks.filter((t) => t.write).length;
@@ -237,18 +215,12 @@ export default function (pi: ExtensionAPI) {
 			const run = result.details?.run;
 			if (!run) return new Text(result.content[0]?.type === "text" ? result.content[0].text : "", 0, 0);
 			// ponytail: mode/count already shown on the call line above; result header only adds progress + status.
-			const header = `${statusIcon(run.status)} ${theme.fg("accent", `${run.tasks.filter((t) => t.status === "completed").length}/${run.tasks.length} done`)}${run.background ? ` ${theme.fg("muted", "(background)")}` : ""} ${theme.fg("muted", run.status)}`;
+			const header = `${statusIcon(run.status)} ${theme.fg("accent", `${run.tasks.filter((t) => t.status === "completed").length}/${run.tasks.length} done`)} ${theme.fg("muted", run.status)}`;
 			if (!expanded) {
-				// Background: the spawn snapshot is always "0 tools" noise and the footer widget
-				// already shows live per-task state — keep the card to the header only.
-				if (run.background) {
-					const usage = formatUsage(run.aggregateUsage);
-					return new Text(usage ? `${header}\n${theme.fg("dim", usage)}` : header, 0, 0);
-				}
-				const lines = [header, ...run.tasks.map((task) => `  ${themedTaskLine(task, theme)}`)];
+				// Every run is background: the spawn snapshot is always "0 tools" noise and the footer
+				// widget already shows live per-task state — keep the card to the header only.
 				const usage = formatUsage(run.aggregateUsage);
-				if (usage) lines.push(theme.fg("dim", usage));
-				return new Text(lines.join("\n"), 0, 0);
+				return new Text(usage ? `${header}\n${theme.fg("dim", usage)}` : header, 0, 0);
 			}
 			const lines = [header];
 			for (const task of run.tasks) {

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,
@@ -211,9 +212,6 @@ export class SubagentManager {
 	private widgetRuns: RunSnapshot[] = [];
 	private eventSeq = 0;
 
-	/** Default for `background` when the agent doesn't say — toggle via `/subagents auto-bg on|off`. */
-	private autoBg = true;
-
 	/** When false, strip leader-imposed maxRuntimeMs so tasks run unlimited — toggle via `/subagents auto-limit on|off`. */
 	private autoLimit = true;
 
@@ -222,37 +220,21 @@ export class SubagentManager {
 	constructor(private readonly pi: ExtensionAPI) {
 		try {
 			const cfg = JSON.parse(readFileSync(join(getAgentDir(), "subagents-config.json"), "utf8"));
-			if (typeof cfg.autoBg === "boolean") this.autoBg = cfg.autoBg;
 			if (typeof cfg.autoLimit === "boolean") this.autoLimit = cfg.autoLimit;
 		} catch {
 			/* no config yet — defaults */
 		}
 	}
 
-	/** Flip the background-by-default flag; persists to the agent dir. Returns the new value. */
-	setAutoBg(on: boolean): boolean {
-		this.autoBg = on;
-		void writeFile(
-			join(getAgentDir(), "subagents-config.json"),
-			JSON.stringify({ autoBg: on, autoLimit: this.autoLimit }, null, 2),
-		).catch(() => {});
-		return on;
-	}
-
 	/** Flip the auto-limit flag; persists to the agent dir. Returns the new value. */
 	setAutoLimit(on: boolean): boolean {
 		this.autoLimit = on;
-		void writeFile(
-			join(getAgentDir(), "subagents-config.json"),
-			JSON.stringify({ autoBg: this.autoBg, autoLimit: on }, null, 2),
-		).catch(() => {});
+		void writeFile(join(getAgentDir(), "subagents-config.json"), JSON.stringify({ autoLimit: on }, null, 2)).catch(
+			() => {},
+		);
 		return on;
 	}
 
-	get autoBgOn(): boolean {
-		return this.autoBg;
-	}
-
 	get autoLimitOn(): boolean {
 		return this.autoLimit;
 	}
@@ -392,7 +374,7 @@ export class SubagentManager {
 		if (kind !== "asked" && run.awaited) return; // parent already got the result via await_subagent
 		const body =
 			kind === "asked"
-				? `A background subagent is asking you a question (task ${extra?.taskId}): ${extra?.question ?? ""}\nReply with reply_subagent(runId: "${run.id}", taskId: "${extra?.taskId}", message: ...).`
+				? `A subagent is asking you a question (task ${extra?.taskId}): ${extra?.question ?? ""}\nReply with reply_subagent(runId: "${run.id}", taskId: "${extra?.taskId}", message: ...).`
 				: makeNotice(run, kind);
 		try {
 			this.pi.sendUserMessage(body, { deliverAs: "followUp" });
@@ -509,13 +491,6 @@ export class SubagentManager {
 				if (this.collectParked(run.id, { kind: "ask", taskId: task.id, agent: task.agent, text: question })) {
 					return "Your question was delivered to the parent (they're waiting on this run). Keep working; the answer arrives via the pending reply.";
 				}
-				// A blocking run's parent can't reply mid-tool (followUp only fires after the
-				// tool returns) — only background runs can truly wait for the answer.
-				if (!run.background) {
-					this.updateTask(run, task, { status: "running" }, ctx);
-					this.liveChildren.get(`${run.id}:${task.id}`)?.touchWatchdog();
-					return "Parent cannot answer while this run is blocking. Continue autonomously with your best judgment.";
-				}
 				this.notifyParent(run, "asked", { taskId: task.id, question });
 				// M3: a waiting child is not stalled — keep the watchdog fed until the reply.
 				const keepAlive = setInterval(() => this.liveChildren.get(`${run.id}:${task.id}`)?.touchWatchdog(), 30_000);
@@ -657,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(
@@ -890,7 +866,6 @@ export class SubagentManager {
 			id: newId("run"),
 			mode,
 			status: "queued",
-			background: params.background ?? this.autoBg,
 			allowIntercom: Boolean(params.allowIntercom),
 			notifyPerTask: params.notifyPerTask ?? true,
 			createdAt: Date.now(),
@@ -965,7 +940,7 @@ export class SubagentManager {
 					onUpdate,
 				);
 				if (task.status === "completed") outputs.set(task.id, task.finalText ?? "");
-				if (run.notifyPerTask && run.background && TERMINAL.includes(task.status)) {
+				if (run.notifyPerTask && TERMINAL.includes(task.status)) {
 					this.notifyTask(run, task, task.status as "completed" | "failed" | "aborted");
 				}
 			},
@@ -1012,17 +987,7 @@ export class SubagentManager {
 		this.persist(ctx);
 	}
 
-	async runBlocking(
-		params: SubagentParamsShape,
-		signal: AbortSignal | undefined,
-		onUpdate: ((partial: any) => void) | undefined,
-		ctx: ExtensionContext,
-	): Promise<RunDetails> {
-		const { run, inputs } = this.createRun(params, ctx);
-		await this.executeTasks(run, inputs, ctx, signal, onUpdate);
-		return { run: cloneRun(run) };
-	}
-
+	/** Spawn a run that keeps executing after this call returns. Every run is background. */
 	startInBackground(params: SubagentParamsShape, ctx: ExtensionContext): RunDetails {
 		const { run, inputs } = this.createRun(params, ctx);
 		void this.executeTasks(run, inputs, ctx, undefined, undefined)
@@ -1050,7 +1015,7 @@ export class SubagentManager {
 				this.notifyParent(run, "failed");
 				this.persist(ctx);
 			});
-		return { run: cloneRun(run), background: true };
+		return { run: cloneRun(run) };
 	}
 
 	/** Push a steering message into a live child's session. Returns false when unknown or not running. */

package/src/schemas.ts

@@ -55,17 +55,15 @@ export const SubagentParams = Type.Object({
 				"Per-task timeout, ms. Omit for no cap (default): tasks run until done, stalled, or user-aborted. Do not add arbitrary caps — only set when a hard bound is genuinely required.",
 		}),
 	),
-	background: Type.Optional(
+	autoAwait: Type.Optional(
 		Type.Boolean({
 			description:
-				"Fire-and-forget: return immediately with a runId; you'll be notified on completion. Default true — set false when you need the result inline in this turn.",
-			default: true,
+				"Start the run in the background, then park this tool call until it finishes and return the final result inline (runId + summary in one response). Default false.",
 		}),
 	),
 	notifyPerTask: Type.Optional(
 		Type.Boolean({
-			description:
-				"Wake you (queued follow-up turn) as each task completes — background runs only, since blocking runs can't be woken mid-tool. Default true.",
+			description: "Wake you (queued follow-up turn) as each task completes. Default true.",
 			default: true,
 		}),
 	),

package/src/types.ts

@@ -47,7 +47,6 @@ export interface RunSnapshot {
 	id: string;
 	mode: RunMode;
 	status: RunStatus;
-	background: boolean;
 	allowIntercom: boolean;
 	notifyPerTask: boolean;
 	createdAt: number;
@@ -62,7 +61,6 @@ export interface RunSnapshot {
 
 export interface RunDetails {
 	run: RunSnapshot;
-	background?: boolean;
 }
 
 export interface PendingReply {