@arhen/pi-core-subagent 1.3.61 → 1.3.63

package/README.md

@@ -53,7 +53,7 @@ flowchart LR
 - **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, plus explicit override.** Read-only (`read, grep, find, ls, codemode` — default) or write (`read, grep, find, ls, bash, edit, write, codemode` — `write: true`); `tools:` sets an explicit per-task allowlist. Children run with `noExtensions`, so `codemode` is the one extension they get: it lets a child batch `tools.*` calls instead of spending a model turn per call.
 - **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. 7 slim tools total.
+- **Zero parent-context injection.** No catalog, no context hook. 9 slim tools total.
 - **Throttled updates** — widget/stream updates coalesce to ~6/s; no per-event deep clones.
 - **Bounded always** — a child is limited only by wall clock: explicit `maxRuntimeMs`, else the 1 h ceiling with `/subagents auto-limit on`, else the 6 h safety ceiling (default).
 
@@ -284,10 +284,13 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 
 **Resuming a failed child:** a child that dies mid-work (provider rate limit, timeout, network error) keeps its session JSONL and its worktree branch. `resume_subagent({ runId, taskId, model?: "openai/gpt-5", message? })` reopens that session with full context, re-attaches the branch, and prompts it to recap and continue — no respawn, no lost tokens. `model` swaps provider when the original one is exhausted. Refused for tasks that never started (no session file); those you respawn. Wait for the run to settle before resuming (the tool tells you if it hasn't).
 
+**Choosing a model:** `subagent_models` lists what this session may use — the same set `/scoped-models` shows when scoping is configured, and every model with usable credentials when it is not (the output states which case applies). Each row gives the exact `model` value to pass, the thinking levels the runtime honors, the context window, and pi's catalog price per million tokens (`free` only when the reported rates are zero; absent rates read `unavailable`; catalog rates are a planning guide, not a billing quote). `model` is optional: omit it to inherit the leader's current session model, or name one (a matched agent file's `model` frontmatter still wins) to pin the run. `~/.pi/agent/subagent-models.json` may shape the listing only — `prefer` sorts, `hide` omits, `default` is surfaced as a suggestion and never applied. It never grants or blocks a model: a hidden model still runs when named, because pi owns what may run.
+
 ## Tools
 
 | Tool | Purpose |
 |---|---|
+| `subagent_models` | list the models a subagent task may name, each with the exact `model` value, thinking levels the runtime honors, context window, and catalog price; scoped to the session's enabled set when scoping is configured, else the full available catalogue (the output says which) |
 | `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; children always carry talk tools (ask/notify/mailbox); `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 |
@@ -299,7 +302,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: `autoAwait`, `notifyPerTask`, `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`; omitted → the leader's current session model, a matched agent file's frontmatter wins), `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`, `concurrency`.
 
 ### Child talk tools (always on)
 
@@ -356,9 +359,9 @@ The extension has no multiplexer integration and does not want one: it exposes t
 
 ## Context budget
 
-- Parent tools: 7 schemas with short descriptions. **No catalog, no context hook** — nothing injected per request.
+- Parent tools: 9 schemas with short descriptions. **No catalog, no context hook** — nothing injected per request.
 - Background completion: 3-line notice. Full text only via `subagent_result`.
-- Children: isolated sessions; talk tools always injected; each child's prompt states its own task id and its siblings' so mailbox addressing works. Model resolution: explicit `provider/model-id` or bare id via the pi model registry → the parent's current model → settings default. Thinking levels validated against the resolved model's `thinkingLevelMap`.
+- Children: isolated sessions; talk tools always injected; each child's prompt states its own task id and its siblings' so mailbox addressing works. Model resolution: explicit `provider/model-id` or bare id via the pi model registry → the parent's current model → settings default. Thinking levels validated against the resolved model's `thinkingLevelMap`; `subagent_models` lists the levels the runtime honors when you need a safe set.
 
 ## What this is built on
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.61",
+	"version": "1.3.63",
 	"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",
@@ -29,11 +29,11 @@
 		"graph-protocol"
 	],
 	"peerDependencies": {
-		"@earendil-works/pi-ai": "^0.84.2",
-		"@earendil-works/pi-agent-core": "^0.84.2",
-		"@earendil-works/pi-coding-agent": "^0.84.2",
-		"@earendil-works/pi-tui": "^0.84.2",
-		"typebox": "^1.3.14"
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-agent-core": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
 	},
 	"pi": {
 		"extensions": [

package/src/format.ts

@@ -3,6 +3,8 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, truncateToWidth } from "@earendil-works/pi-tui";
 import {
 	MAX_TASKS,
+	type ModelCatalog,
+	type ModelPricing,
 	type RunSnapshot,
 	type RunStatus,
 	type TaskSnapshot,
@@ -246,8 +248,8 @@ export function makeTaskNotice(run: RunSnapshot, task: TaskSnapshot, kind: strin
 		isStartupFailure(task, kind)
 			? "Never started — stop and diagnose before spawning anything else: a config-level error (model, plan, auth, agent file) fails identically on every respawn."
 			: kind === "completed"
-				? `Use subagent_result(runId: "${run.id}", taskId: "${task.id}") for full output.`
-				: `Session file kept — resume_subagent(runId: "${run.id}", taskId: "${task.id}", model?: ...) revives it with full context. subagent_result for what it produced so far.`,
+				? `Use subagent_result({ runId: "${run.id}", taskId: "${task.id}" }) for full output.`
+				: `Session file kept — resume_subagent({ runId: "${run.id}", taskId: "${task.id}", model?: ... }) revives it with full context. subagent_result for what it produced so far.`,
 	].join("\n");
 }
 export function makeAskNotice(
@@ -255,7 +257,7 @@ export function makeAskNotice(
 	extra: { taskId?: string; agent?: string; question?: string; urgent?: boolean },
 ): string {
 	const who = extra.agent ? `${extra.agent} (${extra.taskId ?? "task"})` : (extra.taskId ?? "a subagent");
-	const reply = `reply_subagent(runId: "${run.id}", taskId: "${extra.taskId ?? ""}", message: ...)`;
+	const reply = `reply_subagent({ runId: "${run.id}", taskId: "${extra.taskId ?? ""}", message: ... })`;
 	return extra.urgent
 		? `[URGENT] Subagent ${who} is blocked and cannot continue until you answer: ${extra.question ?? ""}\nAnswer now, before your next step, with ${reply}.`
 		: `[not urgent] Subagent ${who} asks: ${extra.question ?? ""}\nIt waits while you keep working — finish your current step first if you want, then answer with ${reply}.`;
@@ -268,6 +270,79 @@ export function makeNotice(run: RunSnapshot, kind: string): string {
 	for (const task of run.tasks) {
 		lines.push(`- ${task.agent}: ${task.status}${task.error ? ` — ${truncateText(task.error, 200)}` : ""}`);
 	}
-	lines.push(`Use subagent_result(runId: "${run.id}") for full output.`);
+	lines.push(`Use subagent_result({ runId: "${run.id}" }) for full output.`);
 	return lines.join("\n");
 }
+
+/** Per-million-token rates, terse. A zero rate reads as "free"; absent rates are "unavailable", not free. */
+function priceTag(cost: ModelPricing | undefined): string {
+	if (!cost) return "unavailable (provider did not report rates)";
+	if (cost.input === 0 && cost.output === 0 && cost.cacheRead === 0 && cost.cacheWrite === 0) return "free";
+	const rate = (n: number) => (n === 0 ? "free" : `$${n.toFixed(n < 0.01 ? 4 : 2)}`);
+	const parts = [`in ${rate(cost.input)}`, `out ${rate(cost.output)}`];
+	if (cost.cacheRead === undefined) parts.push("cache-read unavailable");
+	else if (cost.cacheRead > 0) parts.push(`cache-read ${rate(cost.cacheRead)}`);
+	if (cost.cacheWrite === undefined) parts.push("cache-write unavailable");
+	else if (cost.cacheWrite > 0) parts.push(`cache-write ${rate(cost.cacheWrite)}`);
+	return `${parts.join(", ")} per Mtok`;
+}
+
+/**
+ * Render the model catalog as the `subagent_models` tool result. Pure, so the exact text an agent
+ * receives is testable: the tool handler holds no formatting of its own. Throws when the list is
+ * empty — the SDK tool loop discards a returned `isError` for any `execute` that does not throw.
+ */
+export function renderModelCatalog(catalog: ModelCatalog): {
+	content: { type: "text"; text: string }[];
+	details: ModelCatalog;
+} {
+	if (catalog.models.length === 0) {
+		throw new Error(
+			`No models can be listed for subagent tasks: ${catalog.unavailable ?? "the model registry returned no models"}. This is not an empty catalog — a task without \`model\` still inherits the session model, but naming one needs the references. Fix model configuration, then retry.`,
+		);
+	}
+	const lines = catalog.models.map((model) =>
+		[
+			`- model: "${model.reference}"`,
+			`    ${model.name}; ${model.contextWindow > 0 ? `${model.contextWindow.toLocaleString("en-US")} context` : "context window unreported"}`,
+			`    price: ${priceTag(model.cost)}`,
+			model.reasoning
+				? `    thinking levels: ${model.thinkingLevels.join(" | ")}`
+				: `    thinking: not supported — omit it or pass "off"`,
+		].join("\n"),
+	);
+	const heading =
+		catalog.scope === "session"
+			? `${catalog.models.length} model(s) enabled for this session. Pass the \`model\` value verbatim in a subagent task:`
+			: `${catalog.models.length} model(s) available — this session has no model scoping, so every model with usable credentials is listed. Pass the \`model\` value verbatim in a subagent task:`;
+	const suggestion = catalog.preferredDefault
+		? `\n\nThis configuration suggests \`model: "${catalog.preferredDefault}"\`. It is a preference, never applied automatically.`
+		: "";
+	const unlistedDefault = catalog.unlistedDefault
+		? `\n\nNOTE: configured default \`${catalog.unlistedDefault}\` is not in the displayed catalog; it is not suggested or applied.`
+		: "";
+	const hidden =
+		catalog.hidden && catalog.hidden > 0
+			? `\n\n${catalog.hidden} enabled model(s) are hidden by your model preferences.`
+			: "";
+	const unused = catalog.unusedPatterns?.length
+		? `\n\nNOTE: these preference patterns matched no listed model and did nothing: ${catalog.unusedPatterns.join(", ")}. They may target models that are not enabled.`
+		: "";
+	const ambiguous = catalog.ambiguous?.length
+		? `\n\nDo not pass these references: ${catalog.ambiguous.join(", ")} — ${catalog.reason}.`
+		: "";
+	const unresolved = catalog.unresolved?.length ? `\n\n${catalog.unresolvedReason}` : "";
+	const configError = catalog.configError
+		? `\n\nWARNING: the model preferences file could not be used (${catalog.configError}). Continuing with no preferences.`
+		: "";
+	const billing = "\n\nPrices are pi catalog list rates per Mtok, not a billing quote.";
+	return {
+		content: [
+			{
+				type: "text",
+				text: `${heading}\n${lines.join("\n")}${suggestion}${unlistedDefault}${hidden}${unused}${ambiguous}${unresolved}${configError}${billing}`,
+			},
+		],
+		details: catalog,
+	};
+}

package/src/index.ts

@@ -1,11 +1,23 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
-import { compactLines, formatUsage, makeSummary, statusIcon, taskLine, truncateText } from "./format.ts";
+import type { TSchema } from "typebox";
+import {
+	compactLines,
+	formatUsage,
+	makeSummary,
+	renderModelCatalog,
+	statusIcon,
+	taskLine,
+	truncateText,
+} from "./format.ts";
 import { waveNotation } from "./graph.ts";
 import { cloneRun, type ParkedMsg, SubagentManager } from "./manager.ts";
+import { listSelectableModels } from "./models.ts";
 import { createPeekPane, type PeekTask } from "./peek.ts";
+import { type AnyToolDefinition, createPresentation, isSubagentMode } from "./presentation.ts";
 import {
 	AwaitParam,
+	ModelsParam,
 	ReplyParam,
 	ResultParam,
 	ResumeParam,
@@ -14,11 +26,18 @@ import {
 	SubagentParams,
 	type SubagentParamsShape,
 } from "./schemas.ts";
-import { type RunDetails, type RunSnapshot, TERMINAL } from "./types.ts";
+import { type ModelCatalog, type RunDetails, type RunSnapshot, TERMINAL } from "./types.ts";
 import { cleanupMerged, ownerAlive, reapDeadWorktrees, repoRoot, sweepStale } from "./worktree.ts";
 
 export default function (pi: ExtensionAPI) {
 	const manager = new SubagentManager(pi);
+	const definitions: AnyToolDefinition[] = [];
+	const presentation = createPresentation(pi, definitions);
+	const defineTool = <TParams extends TSchema, TDetails = unknown, TState = any>(
+		definition: ToolDefinition<TParams, TDetails, TState>,
+	): void => {
+		definitions.push(definition as AnyToolDefinition);
+	};
 
 	const openPeek = async (ctx: ExtensionContext) => {
 		if (!ctx.hasUI) return;
@@ -55,11 +74,30 @@ export default function (pi: ExtensionAPI) {
 	};
 	pi.registerCommand("subagents", {
 		description:
-			"List subagent runs. `/subagents peek` opens the browsable pane; `/subagents auto-limit on|off` toggles the 1 h default runtime ceiling (default off = 6 h).",
+			"List subagent runs. `/subagents peek` opens the browsable pane; `/subagents mode [auto|direct|codemode]` reports or switches the tool exposure profile; `/subagents auto-limit on|off` toggles the 1 h default runtime ceiling (default off = 6 h).",
 		handler: async (args, ctx) => {
 			const arg = String(args ?? "")
 				.trim()
 				.toLowerCase();
+			if (arg === "mode" || arg.startsWith("mode ")) {
+				const value = arg.split(/\s+/)[1];
+				if (value === undefined) {
+					ctx.ui.notify(presentation.describe(), "info");
+				} else if (isSubagentMode(value)) {
+					presentation.setPreference(value);
+					// A switch during a streaming turn or an executing script would rewrite the loadout under
+					// a live call; defer it to the next request boundary in that case.
+					const idle = typeof ctx.isIdle === "function" ? ctx.isIdle() : true;
+					if (idle) presentation.sync();
+					ctx.ui.notify(
+						`Subagent exposure mode set to ${value}${idle ? "." : " — applies at the next request boundary."} ${presentation.describe()}`,
+						"info",
+					);
+				} else {
+					ctx.ui.notify(`Unknown subagent mode "${value}". Use \`/subagents mode auto|direct|codemode\`.`, "warning");
+				}
+				return;
+			}
 			if (arg === "peek") return openPeek(ctx);
 			if (arg === "auto-limit" || arg.startsWith("auto-limit ")) {
 				const value = arg.split(/\s+/)[1];
@@ -93,8 +131,19 @@ export default function (pi: ExtensionAPI) {
 		manager.turnActivity = false;
 	});
 
+	pi.on("before_agent_start", () => {
+		presentation.sync();
+	});
+	// Successive model turns of the same run are safe boundaries too: a codemode availability or
+	// helper-selection change made between turns must reach the next request without a new prompt.
+	pi.on("turn_start", () => {
+		presentation.sync();
+	});
+
 	pi.on("session_start", async (_event, ctx) => {
 		await manager.restoreFromSidecar(ctx);
+		presentation.restore(ctx);
+		presentation.sync();
 
 		const roots = new Set<string>();
 		const cwdRoot = repoRoot(ctx.cwd);
@@ -115,6 +164,11 @@ export default function (pi: ExtensionAPI) {
 			} catch {}
 		}
 	});
+	pi.on("session_tree", (_event, ctx) => {
+		presentation.restore(ctx);
+		presentation.sync();
+	});
+
 	pi.on("session_shutdown", async (_event, ctx) => {
 		if (ctx?.hasUI) {
 			try {
@@ -124,25 +178,36 @@ export default function (pi: ExtensionAPI) {
 		manager.clearRuns();
 	});
 
-	pi.registerTool<typeof SubagentParams, RunDetails>({
+	defineTool<typeof ModelsParam, ModelCatalog>({
+		name: "subagent_models",
+		label: "Subagent Models",
+		description:
+			"List the models a subagent task may name: the exact `model` value to pass, the thinking levels the runtime honors, the context window and catalog price. Scoped to this session's models when scoping is configured, else every usable model; ambiguous references are called out. Full reference: `describeNamespace('subagents')`.",
+		promptSnippet: "List the models a subagent task can name (reference, thinking levels, context, price).",
+		parameters: ModelsParam,
+		async execute(_id, _params, _signal, _onUpdate, ctx) {
+			return renderModelCatalog(listSelectableModels(ctx));
+		},
+	});
+
+	defineTool<typeof SubagentParams, RunDetails>({
 		name: "subagent",
 		label: "Subagent",
 
 		description:
-			"Run isolated subagents (own context, own session) in the background: returns a runId immediately, completion notifies you. One call = one agent (`agent`+`task`) or many (`tasks`, or `chain` with `{previous}`). `needs` edges gate tasks and prepend upstream outputs to their prompts. A user agent file (`.agents/agents`, `.claude/agents`, `.pi/agents`; project dirs, then home) whose `description` matches the goal is authoritative: body = system prompt, frontmatter `model`/`tools` apply, but explicit per-call `tools`/`write` override the file's tools. Write agents get an isolated git worktree; the result reports the branch. Children always carry talk tools (ask/notify the leader, message siblings).",
+			"Run isolated subagents (own context/session) in the background; returns a runId and completion notifies you. One call = one agent (`agent`+`task`) or many (`tasks`, `chain`, or `needs` edges that gate tasks and prepend upstream output). Write tasks use an isolated git worktree and report a branch; a matching agent file is authoritative (matched by description, body/model win). Full reference: `describeNamespace('subagents')`.",
 		promptSnippet: "Define and delegate work to specialized subagents.",
 		promptGuidelines: [
+			"`model` is optional: omit it to inherit your current session model, or name one (agent-file `model` frontmatter wins) to pin the run. Call subagent_models for the exact references, thinking levels, and prices this session may use.",
 			"Use subagent when independent review, testing, research, or parallel analysis improves quality.",
 			"Batch every sub-task in ONE call: subagent({ tasks: [...] }) — never multiple parallel subagent calls.",
 			"Declare ordering with `needs` edges on the tasks, never by splitting into separate calls; dependents receive upstream outputs automatically — do not restate them. Prefer flat `tasks` (plain parallel); add `needs` only when ordering genuinely matters.",
+			"Define each agent inline: invented name, focused system prompt, read-only by default (write:true to edit). Agent files are matched by description/goal, not name; a match is authoritative (body/model), and only per-call tools/write override its tools.",
+			"Write agents work in an isolated git worktree; review the branch diff and merge with `git merge --no-ff <branch>` when done.",
+			"After spawning, call subagent_status({ runId }) ONCE to confirm the tasks started; fix or respawn a task that died on spawn.",
 			"End each task with a runnable check, e.g. 'Verify: bun test'. A subagent's claim of success is not evidence.",
-			"Write agents work in an isolated git worktree; their changes land on a branch — review the diff, then merge with `git merge --no-ff <branch>`. Never leave a worktree branch unmerged at the end of the task.",
-			"Define each agent inline: invented name, focused system prompt, read-only by default (write:true to edit). A matched agent file takes over (see description); matching is by description, not name — name the agent whatever fits the goal.",
-			"Right after spawning, call subagent_status(runId) ONCE before any other work — a child that died on spawn (or never started) is invisible until far later otherwise. If it shows a task failed/never started, fix or respawn immediately.",
-			"Never block with nothing to do: if you have no work left after spawning, end your turn — completion notifies you and wakes a fresh turn with the results. await_subagent/autoAwait while idle only burns time and tokens.",
-			"A failed task interrupts you immediately as a steering message — handle it in the same turn (resume, swap model, re-dispatch) instead of finishing the plan on a broken intermediate result. Completes and aborts queue as follow-ups.",
-			"autoAwait:true only when this SAME turn must consume the result immediately. await_subagent is for syncing with your own parallel work — not the default follow-up to a spawn.",
-			"A task that failed mid-work (provider error, rate limit, timeout) keeps its session file and branch: resume_subagent(runId, taskId, model?) revives it with full context — prefer that over respawning. Respawn only when it never started (no session file).",
+			"When you have no work left, end your turn — completion notifies you. await_subagent/autoAwait only when this turn must consume the result immediately.",
+			"A failed task keeps its session file and branch: resume_subagent({ runId, taskId }) revives it; respawn only when it never started.",
 		],
 		parameters: SubagentParams,
 		executionMode: "parallel",
@@ -172,7 +237,7 @@ export default function (pi: ExtensionAPI) {
 						? `\n${asks.length} child(ren) waiting for your answer:\n${asks
 								.map(
 									(a) =>
-										`- ${a.agent} (${a.taskId}): ${a.text}\n  reply_subagent(runId: "${run.id}", taskId: "${a.taskId}", message: ...)`,
+										`- ${a.agent} (${a.taskId}): ${a.text}\n  reply_subagent({ runId: "${run.id}", taskId: "${a.taskId}", message: ... })`,
 								)
 								.join("\n")}\nAnswer each, then await_subagent again for the result.`
 						: "",
@@ -185,7 +250,7 @@ export default function (pi: ExtensionAPI) {
 				content: [
 					{
 						type: "text",
-						text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nNext: call subagent_status("${details.run.id}") now to confirm the tasks actually started before doing anything else.\nAfter that, completion will notify you — if you have no other work, end your turn instead of waiting.\nOther tools: subagent_result / reply_subagent / steer_subagent / resume_subagent / subagent_cancel.`,
+						text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nNext: call subagent_status({ runId: "${details.run.id}" }) now to confirm the tasks actually started before doing anything else.\nAfter that, completion will notify you — if you have no other work, end your turn instead of waiting.\nOther tools: subagent_result / reply_subagent / steer_subagent / resume_subagent / subagent_cancel.`,
 					},
 				],
 				details,
@@ -259,11 +324,11 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof RunIdParam, { run?: RunSnapshot }>({
+	defineTool<typeof RunIdParam, { run?: RunSnapshot }>({
 		name: "subagent_status",
 		label: "Subagent Status",
 		description:
-			"Live per-task status of a subagent run (non-blocking), incl. each child's session file path (JSONL) to `tail -f` from outside. Call once right after spawning to verify children actually started.",
+			"Live per-task status of a subagent run (non-blocking), incl. each child's session file path to `tail -f`. Call once right after spawning to verify children actually started.",
 		promptSnippet: "Check progress of a subagent run; use right after spawn as a health check.",
 		parameters: RunIdParam,
 		async execute(_id, params) {
@@ -280,7 +345,7 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof ResultParam, { run?: RunSnapshot }>({
+	defineTool<typeof ResultParam, { run?: RunSnapshot }>({
 		name: "subagent_result",
 		label: "Subagent Result",
 		description: "Full result (finalText + usage) of a run or one task. Non-blocking.",
@@ -307,11 +372,11 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof AwaitParam, { run?: RunSnapshot }>({
+	defineTool<typeof AwaitParam, { run?: RunSnapshot }>({
 		name: "await_subagent",
 		label: "Await Subagent",
 		description:
-			"Block until a run finishes (or timeoutMs elapses). Only when you have your own work to sync — otherwise end your turn; completion notifies you. While parked, child→leader messages (asks, notifies, completions) wake the wait and arrive inside the result.",
+			"Block until a run finishes (or timeoutMs elapses). Only when you have your own work to sync; otherwise end your turn. Child messages that arrive while parked wake the wait and are returned.",
 		parameters: AwaitParam,
 		async execute(_id, params) {
 			const { runId, timeoutMs } = params as { runId: string; timeoutMs?: number };
@@ -329,7 +394,7 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof ReplyParam, { run?: RunSnapshot }>({
+	defineTool<typeof ReplyParam, { run?: RunSnapshot }>({
 		name: "reply_subagent",
 		label: "Reply Subagent",
 		description: "Answer a child's ask_parent question; resumes its run.",
@@ -350,7 +415,7 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof SteerParam, { steered?: string[] }>({
+	defineTool<typeof SteerParam, { steered?: string[] }>({
 		name: "steer_subagent",
 		label: "Steer Subagent",
 		description:
@@ -377,11 +442,11 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof ResumeParam, { run?: RunSnapshot }>({
+	defineTool<typeof ResumeParam, { run?: RunSnapshot }>({
 		name: "resume_subagent",
 		label: "Resume Subagent",
 		description:
-			"Revive a failed/aborted task in its original session (full context + worktree branch preserved). Optional `model` swaps provider (e.g. after a rate limit); optional `thinking` sets the effort — the stored level is clamped to what the target model accepts, so a resume never dies on an unsupported effort; optional `message` replaces the default 'recap and continue' prompt. Refuses tasks that never started — respawn those.",
+			"Revive a failed/aborted task in its original session (full context + worktree branch preserved). Optional `model` swaps provider after e.g. a rate limit; `thinking` is clamped to the target model; `message` replaces the default recap prompt. Refuses tasks that never started — respawn those.",
 		parameters: ResumeParam,
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const { runId, taskId, message, model, thinking } = params as {
@@ -398,7 +463,7 @@ export default function (pi: ExtensionAPI) {
 				content: [
 					{
 						type: "text",
-						text: `Resumed ${runId}/${taskId} (${res.task.agent})${model ? ` on ${model}` : ""} from ${res.task.sessionFile}${res.task.branch ? `, branch ${res.task.branch}` : ""}.${res.note ? ` Adjusted ${res.note}.` : ""}\nNext: subagent_status("${runId}") to confirm it is running; completion will notify you.`,
+						text: `Resumed ${runId}/${taskId} (${res.task.agent})${model ? ` on ${model}` : ""} from ${res.task.sessionFile}${res.task.branch ? `, branch ${res.task.branch}` : ""}.${res.note ? ` Adjusted ${res.note}.` : ""}\nNext: subagent_status({ runId: "${runId}" }) to confirm it is running; completion will notify you.`,
 					},
 				],
 				details: { run: run ? cloneRun(run) : undefined },
@@ -406,7 +471,7 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof RunIdParam, { aborted?: number }>({
+	defineTool<typeof RunIdParam, { aborted?: number }>({
 		name: "subagent_cancel",
 		label: "Subagent Cancel",
 		description: "Abort a running/queued subagent run. Children are killed; run becomes aborted.",
@@ -423,4 +488,6 @@ export default function (pi: ExtensionAPI) {
 			};
 		},
 	});
+
+	presentation.registerInitial();
 }

package/src/manager.ts

@@ -37,6 +37,7 @@ import {
 } from "./format.ts";
 import { applyUpstream, resolveNeeds, runWaveScheduler } from "./graph.ts";
 import { createMailbox, type Mailbox } from "./mailbox.ts";
+import { chooseModel, resolveChildModel } from "./models.ts";
 import type { SubagentParamsShape, TaskInput } from "./schemas.ts";
 import {
 	MAX_TASKS,
@@ -62,6 +63,9 @@ import {
 	type Worktree,
 } from "./worktree.ts";
 
+/** Legacy callers import the resolver from here; its owner is `models.ts`. */
+export { resolveChildModel };
+
 export const DEFAULT_CONCURRENCY = 3;
 export const MAX_CONCURRENCY = 8;
 const DEFAULT_RUNTIME_MS = 3_600_000;
@@ -174,27 +178,6 @@ export function clampResumeThinking(
 	return clampThinkingLevel(model, thinking) as ThinkingLevel;
 }
 
-export function resolveChildModel(ctx: ExtensionContext, explicit: string | undefined) {
-	if (!explicit?.trim()) return ctx.model;
-	const ref = explicit.trim();
-	if (!ctx.modelRegistry) return ctx.model;
-	const available = ctx.modelRegistry.getAvailable();
-	const sessionProvider = ctx.model?.provider;
-	if (sessionProvider && !ref.includes("/")) {
-		const own = available.filter((m) => m.provider === sessionProvider);
-		const hit = own.find((m) => m.id === ref) ?? own.find((m) => m.id.endsWith(`/${ref}`));
-		if (hit) return hit;
-	}
-
-	const byId = available.find((m) => m.id === ref);
-	if (byId) return byId;
-	for (let slash = ref.indexOf("/"); slash > 0; slash = ref.indexOf("/", slash + 1)) {
-		const model = ctx.modelRegistry.find(ref.slice(0, slash), ref.slice(slash + 1));
-		if (model) return model;
-	}
-	throw new Error(`Model not found: ${ref}`);
-}
-
 const PROBE_THINKING_LEVELS: ThinkingLevel[] = ["low", "minimal", "medium", "high", "xhigh", "max"];
 
 /**
@@ -816,7 +799,7 @@ export class SubagentManager {
 
 		let model: Model<Api> | undefined;
 		try {
-			model = resolveChildModel(ctx, file?.model ?? input.model);
+			model = resolveChildModel(ctx, chooseModel(file, input.model).requested);
 			validateThinking(model, thinking);
 
 			const checked = await ensureUsableModel(ctx, model, signal, thinking);
@@ -1207,12 +1190,12 @@ export class SubagentManager {
 			const input = inputs[i] as TaskInput;
 			const cwd = input.cwd ?? ctx.cwd;
 			const file = resolveAgentFile(input.agent, input.task, cwd, getAgentDir());
-			const requested = file?.model ?? input.model;
+			const choice = chooseModel(file, input.model);
 			try {
-				validateThinking(resolveChildModel(ctx, requested), input.thinking);
+				validateThinking(resolveChildModel(ctx, choice.requested), input.thinking);
 			} catch (err) {
-				const where = file?.model
-					? ` (from agent file ${file.path}, which overrides the requested model${input.model ? ` "${input.model}"` : ""})`
+				const where = choice.sourceFile
+					? ` (from agent file ${choice.sourceFile}, which overrides the requested model${input.model ? ` "${input.model}"` : ""})`
 					: "";
 				throw new Error(
 					`Task ${input.id ?? `task_${i + 1}`} (${input.agent}): ${err instanceof Error ? err.message : String(err)}${where}`,
@@ -1435,11 +1418,13 @@ export class SubagentManager {
 		const tools = task.tools?.filter((t) => !(CHILD_TALK_TOOLS as readonly string[]).includes(t));
 		const write = tools?.some((t) => WRITE_CAPABLE.includes(t)) ?? false;
 		// A resume may swap the model, so the level stored on the task can be one the new model
-		// rejects (a mode-clamped xhigh onto a model that only takes low|high|max). Clamp it, or take
-		// the caller's explicit level and clamp that.
+		// rejects (a mode-clamped xhigh onto a model that only takes low|high|max). Clamp it against
+		// the model runChild will actually use — including a matched agent file's, whose frontmatter
+		// overrides the inline model at spawn — or the clamp would validate a different model.
+		const file = resolveAgentFile(task.agent, task.task, task.cwd, getAgentDir());
 		let resumeModel: Model<Api> | undefined;
 		try {
-			resumeModel = resolveChildModel(ctx, opts.model ?? task.model);
+			resumeModel = resolveChildModel(ctx, chooseModel(file, opts.model ?? task.model).requested);
 		} catch {}
 		const requestedThinking = (opts.thinking ?? task.thinking) as ThinkingLevel | undefined;
 		const thinking = clampResumeThinking(resumeModel, requestedThinking);

package/src/modelconfig.ts

@@ -0,0 +1,131 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Optional user preferences for `subagent_models`. This filters and orders what the tool shows and
+ * nothing else: it never grants or blocks a model, because pi already owns what may run. A missing
+ * file, malformed JSON, or an unknown key degrades to no preferences, so a config typo cannot break
+ * delegation.
+ */
+export interface ModelPreferences {
+	/** Patterns to sort first, in declaration order. */
+	prefer: string[];
+	/** Patterns to omit from the listing. */
+	hide: string[];
+	/** Suggested model, surfaced but never applied as a substitute. */
+	default?: string;
+	/** Set when the file existed but could not be used, so the failure is reportable, not silent. */
+	error?: string;
+	/** The path that was read, or would be. */
+	path: string;
+}
+
+export const MODEL_CONFIG_FILENAME = "subagent-models.json";
+
+export const NO_PREFERENCES = (path: string): ModelPreferences => ({ prefer: [], hide: [], path });
+
+/**
+ * Match a model reference against a config pattern. `provider/id` is matched as a whole; a bare
+ * provider also matches everything from that provider, so `"openai-codex"` is shorthand for
+ * `"openai-codex/*"`. `*` matches any run of characters, other metacharacters are literal, and
+ * matching is case-insensitive.
+ */
+export function matchesPattern(reference: string, pattern: string): boolean {
+	const ref = reference.toLowerCase();
+	const pat = pattern.trim().toLowerCase();
+	if (!pat) return false;
+	if (!pat.includes("*")) return ref === pat || ref.startsWith(`${pat}/`);
+	const escaped = pat.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+	return new RegExp(`^${escaped}$`).test(ref);
+}
+
+function asStringArray(value: unknown, field: string, errors: string[]): string[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value)) {
+		errors.push(`${field} must be an array of strings`);
+		return [];
+	}
+	const out: string[] = [];
+	for (const item of value) {
+		if (typeof item !== "string" || !item.trim()) errors.push(`${field} contains a non-string entry`);
+		else out.push(item.trim());
+	}
+	return out;
+}
+
+/** Parse config text. Exported so the validation rules are testable without touching the filesystem. */
+export function parsePreferences(text: string, path = MODEL_CONFIG_FILENAME): ModelPreferences {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(text);
+	} catch (err) {
+		return {
+			prefer: [],
+			hide: [],
+			path,
+			error: `not valid JSON (${err instanceof Error ? err.message : String(err)})`,
+		};
+	}
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+		return { prefer: [], hide: [], path, error: "must be a JSON object" };
+	}
+	const obj = raw as Record<string, unknown>;
+	const errors: string[] = [];
+	const known = new Set(["prefer", "hide", "default"]);
+	const unknown = Object.keys(obj).filter((k) => !known.has(k));
+	if (unknown.length > 0) errors.push(`unknown key(s): ${unknown.join(", ")}`);
+
+	const prefer = asStringArray(obj.prefer, "prefer", errors);
+	const hide = asStringArray(obj.hide, "hide", errors);
+	let fallback: string | undefined;
+	if (obj.default !== undefined) {
+		if (typeof obj.default !== "string" || !obj.default.trim()) errors.push("default must be a non-empty string");
+		else fallback = obj.default.trim();
+	}
+	if (errors.length > 0) return { prefer: [], hide: [], path, error: errors.join("; ") };
+	return { prefer, hide, ...(fallback ? { default: fallback } : {}), path };
+}
+
+/** Read the preferences file if present. Never throws: an unusable file degrades to no preferences. */
+export function loadPreferences(agentDir: string): ModelPreferences {
+	const path = join(agentDir, MODEL_CONFIG_FILENAME);
+	if (!existsSync(path)) return NO_PREFERENCES(path);
+	try {
+		return parsePreferences(readFileSync(path, "utf8"), path);
+	} catch (err) {
+		return {
+			prefer: [],
+			hide: [],
+			path,
+			error: `could not be read (${err instanceof Error ? err.message : String(err)})`,
+		};
+	}
+}
+
+/**
+ * Hide first, then order: preferred matches by declaration order, the rest after, stable. Also
+ * reports patterns that matched nothing — an inert `hide` entry must not read as though it worked.
+ */
+export function applyPreferences<T extends { reference: string }>(
+	entries: T[],
+	prefs: ModelPreferences,
+): { entries: T[]; unusedPatterns: string[] } {
+	if (prefs.error) return { entries: [...entries], unusedPatterns: [] };
+	const used = new Set<string>();
+	const kept = entries.filter((entry) => {
+		const hit = prefs.hide.find((pattern) => matchesPattern(entry.reference, pattern));
+		if (hit) used.add(hit);
+		return !hit;
+	});
+	const unusedPatterns = prefs.hide.filter((pattern) => !used.has(pattern));
+	if (prefs.prefer.length === 0) return { entries: kept, unusedPatterns };
+
+	const ranked = kept.map((entry, index) => {
+		const pattern = prefs.prefer.find((candidate) => matchesPattern(entry.reference, candidate));
+		if (pattern) used.add(pattern);
+		return { entry, index, rank: pattern ? prefs.prefer.indexOf(pattern) : Number.MAX_SAFE_INTEGER };
+	});
+	for (const pattern of prefs.prefer) if (!used.has(pattern)) unusedPatterns.push(pattern);
+	ranked.sort((a, b) => a.rank - b.rank || a.index - b.index);
+	return { entries: ranked.map((r) => r.entry), unusedPatterns };
+}

package/src/models.ts

@@ -0,0 +1,184 @@
+import { type Api, getSupportedThinkingLevels, type Model, type ModelThinkingLevel } from "@earendil-works/pi-ai";
+import { type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { applyPreferences, loadPreferences, type ModelPreferences } from "./modelconfig.ts";
+import type { ModelCatalog, ModelPricing, SelectableModel } from "./types.ts";
+
+/**
+ * Resolve a task's `model` reference against the registry. An absent reference inherits the
+ * session model — delegation stays usable without naming one; naming one is a pin, not a
+ * requirement.
+ */
+export function resolveChildModel(ctx: ExtensionContext, explicit: string | undefined) {
+	if (!explicit?.trim()) return ctx.model;
+	const ref = explicit.trim();
+	if (!ctx.modelRegistry) return ctx.model;
+	const available = ctx.modelRegistry.getAvailable();
+	const sessionProvider = ctx.model?.provider;
+	if (sessionProvider && !ref.includes("/")) {
+		const own = available.filter((m) => m.provider === sessionProvider);
+		const hit = own.find((m) => m.id === ref) ?? own.find((m) => m.id.endsWith(`/${ref}`));
+		if (hit) return hit;
+	}
+
+	const byId = available.find((m) => m.id === ref);
+	if (byId) return byId;
+	for (let slash = ref.indexOf("/"); slash > 0; slash = ref.indexOf("/", slash + 1)) {
+		const model = ctx.modelRegistry.find(ref.slice(0, slash), ref.slice(slash + 1));
+		if (model) return model;
+	}
+	throw new Error(`Model not found: ${ref}`);
+}
+
+export interface ModelChoice {
+	/** The reference to resolve, or undefined when the caller named none (inherit the session model). */
+	requested: string | undefined;
+	/** Set when an agent file supplied the model, so errors can say where it came from. */
+	sourceFile?: string;
+}
+
+/**
+ * Single owner of the model-precedence rule: a matched agent file's `model` wins over the inline
+ * one. Spawn, pre-creation validation, and resume all resolve through this, so they cannot disagree
+ * about which model a task actually uses.
+ */
+export function chooseModel(
+	file: { model?: string; path?: string } | undefined,
+	inline: string | undefined,
+): ModelChoice {
+	const fromFile = file?.model?.trim();
+	return fromFile ? { requested: fromFile, sourceFile: file?.path } : { requested: inline };
+}
+
+/**
+ * The thinking levels a model honors at runtime, from pi's own resolver, so the catalog cannot
+ * promise a level the runtime would silently clamp: `xhigh`/`max` count only when explicitly
+ * mapped. An accepted input can still be clamped; the catalog lists only honored levels.
+ */
+export function supportedThinkingLevels(model: Model<Api> | undefined): ModelThinkingLevel[] {
+	if (!model) return [];
+	return [...getSupportedThinkingLevels(model)];
+}
+
+/** Keep only finite, non-negative per-Mtok rates; a partial or absent cost is unavailable, not free. */
+export function normalizeCost(cost: unknown): ModelPricing | undefined {
+	if (!cost || typeof cost !== "object") return undefined;
+	const raw = cost as Partial<Record<keyof ModelPricing, unknown>>;
+	const rate = (value: unknown): number | undefined =>
+		typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+	const input = rate(raw.input);
+	const output = rate(raw.output);
+	if (input === undefined || output === undefined) return undefined;
+	const cacheRead = rate(raw.cacheRead);
+	const cacheWrite = rate(raw.cacheWrite);
+	return {
+		input,
+		output,
+		...(cacheRead !== undefined ? { cacheRead } : {}),
+		...(cacheWrite !== undefined ? { cacheWrite } : {}),
+	};
+}
+
+/**
+ * Models a subagent task may name, scoped the way pi scopes them.
+ *
+ * `ctx.scopedModels` is pi's own resolution of `enabledModels` and `--models` — the set
+ * `/scoped-models` shows. When no scoping is configured pi reports an empty list, and only then
+ * does this fall back to the full available catalogue; `scope` tells the caller which case applies.
+ *
+ * A reference is listed only when it resolves back to the model it describes. Resolution is not a
+ * pure `provider/id` split (a model whose bare id contains a slash can shadow another provider's
+ * `provider/id`), so building the string naively could advertise a reference that silently selects
+ * a different model. Anything ambiguous is reported as such, and a registry fault is reported
+ * separately because the caller's fix differs.
+ */
+export function listSelectableModels(ctx: ExtensionContext, preferences?: ModelPreferences): ModelCatalog {
+	if (!ctx.modelRegistry) {
+		return { models: [], scope: "all", unavailable: "this context exposes no model registry" };
+	}
+	const scoped = ctx.scopedModels ?? [];
+	const scope: ModelCatalog["scope"] = scoped.length > 0 ? "session" : "all";
+
+	let candidate: Model<Api>[];
+	try {
+		candidate = scoped.length > 0 ? scoped.map((entry) => entry.model) : (ctx.modelRegistry.getAvailable() ?? []);
+	} catch (err) {
+		return { models: [], scope, unavailable: err instanceof Error ? err.message : String(err) };
+	}
+
+	const seen = new Set<string>();
+	const models: SelectableModel[] = [];
+	const ambiguous: string[] = [];
+	const unresolved: string[] = [];
+	for (const model of candidate) {
+		const reference = `${model.provider}/${model.id}`;
+		if (seen.has(reference)) continue;
+		seen.add(reference);
+
+		let resolved: Model<Api> | undefined;
+		let lookupError: string | undefined;
+		try {
+			resolved = resolveChildModel(ctx, reference);
+		} catch (err) {
+			lookupError = err instanceof Error ? err.message : String(err);
+		}
+		if (!resolved) {
+			unresolved.push(lookupError ? `${reference} (${lookupError})` : reference);
+			continue;
+		}
+		if (resolved.provider !== model.provider || resolved.id !== model.id) {
+			ambiguous.push(reference);
+			continue;
+		}
+		models.push({
+			reference,
+			provider: model.provider,
+			id: model.id,
+			name: typeof model.name === "string" && model.name.trim() ? model.name : model.id,
+			reasoning: Boolean(model.reasoning),
+			thinkingLevels: supportedThinkingLevels(model),
+			contextWindow:
+				typeof model.contextWindow === "number" && Number.isFinite(model.contextWindow) && model.contextWindow > 0
+					? model.contextWindow
+					: 0,
+			cost: normalizeCost((model as { cost?: unknown }).cost),
+		});
+	}
+
+	// Preferences filter and order only. `preferences` is injectable so the file-to-catalog wiring
+	// is testable without touching the user's real config.
+	const prefs = preferences ?? loadPreferences(getAgentDir());
+	const { entries: shown, unusedPatterns } = applyPreferences(models, prefs);
+	const hiddenCount = models.length - shown.length;
+	const suggested = prefs.error ? undefined : prefs.default;
+	const listedDefault = suggested && shown.some((entry) => entry.reference === suggested);
+	return {
+		models: shown,
+		scope,
+		...(listedDefault ? { preferredDefault: suggested } : {}),
+		...(suggested && !listedDefault ? { unlistedDefault: suggested } : {}),
+		...(prefs.error ? { configError: `${prefs.path}: ${prefs.error}` } : {}),
+		...(hiddenCount > 0 ? { hidden: hiddenCount } : {}),
+		...(unusedPatterns.length > 0 ? { unusedPatterns } : {}),
+		...(ambiguous.length > 0
+			? {
+					ambiguous,
+					reason: `another model's bare id would win resolution for ${ambiguous.join(", ")}`,
+				}
+			: {}),
+		...(unresolved.length > 0
+			? { unresolved, unresolvedReason: `the registry could not resolve these entries: ${unresolved.join(", ")}` }
+			: {}),
+		...(shown.length === 0
+			? {
+					unavailable:
+						models.length > 0
+							? `every listed model is hidden by ${prefs.path} — unhide one or remove \`hide\``
+							: unresolved.length > 0
+								? `the registry could not resolve any of its available models: ${unresolved.join("; ")}`
+								: scope === "session"
+									? "the session's enabled models could not be resolved"
+									: "no model has usable credentials",
+				}
+			: {}),
+	};
+}

package/src/presentation.ts

@@ -0,0 +1,209 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ToolDefinition,
+	ToolExposure,
+	ToolLoadout,
+	ToolLoadoutChanges,
+	ToolNamespace,
+} from "@earendil-works/pi-coding-agent";
+
+/**
+ * Presentation preference for the subagent toolset.
+ * - auto: native codemode presentation when the codemode tool is active, direct otherwise.
+ * - direct: subagent tools are declared to the model (model-only exposure).
+ * - codemode: subagent tools are callable from codemode scripts but not declared or listed.
+ */
+export type SubagentMode = "auto" | "direct" | "codemode";
+export type EffectiveMode = "direct" | "codemode";
+
+/** Branch-scoped custom entry holding the preference, so resume/tree keep it. */
+export const MODE_ENTRY_TYPE = "subagent-mode";
+export const CODEMODE_TOOL_NAME = "codemode";
+
+export const SUBAGENT_NAMESPACE: ToolNamespace = {
+	name: "subagents",
+	description: "Isolated background subagents with a dependency-graph scheduler, git-worktree isolation and intercom.",
+	instructions: `Isolated subagents with their own context, session and optional git worktree. Delegate independent review, testing, research or parallel analysis.
+
+## Modes
+- auto (default): codemode presentation while the \`codemode\` tool is active, direct otherwise.
+- direct: subagent tools are declared to the model (model-only, not callable from scripts).
+- codemode: active tools are callable from scripts but not declared; inactive tools stay model-only and are not callable at all.
+Switch with \`/subagents mode auto|direct|codemode\`. The preference is stored on the session branch and restored on reload, resume and tree navigation.
+
+## Operations
+Object arguments, exactly as validated when issued by the model:
+- \`subagent({ agent, task, prompt?, write?, tools?, model?, thinking?, cwd?, maxRuntimeMs?, autoAwait?, notifyPerTask? })\` runs one agent; \`tasks: [...]\`, \`chain: [...]\` with \`{previous}\` and \`needs\` edges gate tasks and prepend upstream output.
+- \`subagent_models()\` lists the models a task may name: the exact \`model\` value to pass, the thinking levels the runtime honors, the context window and pi catalog price per million tokens. The list follows this session's scoped models when scoping is configured, else every usable model; the output states which case applies, and references that would resolve to another model are called out as ambiguous.
+- \`subagent_status({ runId })\` returns live per-task status and session file paths; call once right after spawning.
+- \`subagent_result({ runId, taskId? })\` returns final text, usage and the worktree branch/diff summary.
+- \`await_subagent({ runId, timeoutMs? })\` blocks only when this turn must consume the result.
+- \`reply_subagent({ runId, taskId, message })\` answers a child \`ask_parent\` question and resumes it.
+- \`steer_subagent({ runId, taskId?, message })\` injects a message into running tasks.
+- \`resume_subagent({ runId, taskId, message?, model?, thinking? })\` revives a failed/aborted task with its context and branch.
+- \`subagent_cancel({ runId })\` aborts the run and kills its children.
+
+## Agents
+- Define each agent inline: invented name, focused system prompt. Agent files (\`.agents/agents\`, \`.claude/agents\`, \`.pi/agents\`; project dirs, then home) are matched by \`description\` against the goal, never by name. A match is authoritative: its body is the system prompt, its \`model\` frontmatter wins over the inline value, and its \`tools\` apply — only the per-call \`tools\` and \`write\` override them.
+- Agents are read-only by default; \`write: true\` gives an isolated git worktree branch. Review the diff and merge with \`git merge --no-ff <branch>\`.
+- \`model\` is optional: omit it to inherit the session model, or name one from \`subagent_models\` to pin the run.
+
+## Rules
+- Batch every sub-task in ONE call with \`tasks\`/\`needs\`; do not split parallel work into separate calls.
+- After spawning, call \`subagent_status({ runId })\` once to confirm the tasks started; fix or respawn a task that died on spawn.
+- A task that failed mid-work keeps its session file and branch: \`resume_subagent({ runId, taskId })\`, model swap included, revives it; respawn only a task that never started.
+- Completion and failures notify you: end the turn when you have no work left; use \`autoAwait\` only when the same turn must consume the result.
+- End each task with a runnable check, e.g. 'Verify: bun test'. A subagent's claim of success is not evidence.
+
+## Codemode
+When codemode is active these tools are not declared. Call an active operation as \`tools.<name>(args)\`; spawning uses \`await tools.subagent(args)\`. If its signature is unknown, inspect only \`text(await describeTool('subagent'))\` once and reuse it. For another operation, inspect only its exact name when needed. Broad search and tool-list dumps are unnecessary for these known names; this namespace is the optional full reference. Inactive tools remain unavailable. Arguments are validated exactly like model-issued calls.`,
+};
+
+/** Adds the script-call path to the upfront rules, but only in the codemode profile. */
+export const CODEMODE_DISCOVERY_GUIDELINE =
+	"Codemode subagents: call active tools as tools.<name>(args); spawn with await tools.subagent(args). If its signature is unknown, inspect only text(await describeTool('subagent')) once, then reuse it. Other helpers: describeTool(exactName) only when needed. No broad search or tool-list dump required; describeNamespace('subagents') is optional full reference.";
+
+/** The full-reference pointer only resolves while codemode scripts can reach `describeNamespace`. */
+const NAMESPACE_REFERENCE = / Full reference: `describeNamespace\('subagents'\)`\./;
+
+export function isSubagentMode(value: unknown): value is SubagentMode {
+	return value === "auto" || value === "direct" || value === "codemode";
+}
+
+export type AnyToolDefinition = ToolDefinition<any, any, any>;
+
+export interface Presentation {
+	readonly preference: SubagentMode;
+	/** The profile currently registered, or undefined before the first registration. */
+	readonly applied: EffectiveMode | undefined;
+	/** Effective mode for the given active set, defaulting to the session's live active tools. */
+	effective(active?: readonly string[]): EffectiveMode;
+	/** Report preference, effective mode and codemode availability. */
+	describe(): string;
+	setPreference(mode: SubagentMode): void;
+	/** Restore the latest preference stored on the session branch. */
+	restore(ctx: ExtensionContext): void;
+	/** Register the tools for the current effective mode; no-op when already applied. */
+	sync(): boolean;
+	/** Initial registration during extension load, before any session state exists. */
+	registerInitial(): void;
+}
+
+/**
+ * Owns the subagent exposure profile. Tools stay registered while only their exposure changes, so
+ * the active selection (and the running manager) is preserved across mode switches.
+ */
+export function createPresentation(pi: ExtensionAPI, definitions: readonly AnyToolDefinition[]): Presentation {
+	const ownNames = (): string[] => definitions.map((definition) => definition.name);
+	let preference: SubagentMode = "auto";
+	let applied: EffectiveMode | undefined;
+	let appliedOwn = new Set<string>();
+
+	const codemodeActive = (active: readonly string[]): boolean => active.includes(CODEMODE_TOOL_NAME);
+	const effectiveFrom = (active: readonly string[]): EffectiveMode =>
+		preference !== "direct" && codemodeActive(active) ? "codemode" : "direct";
+	const sameSet = (a: ReadonlySet<string>, b: ReadonlySet<string>): boolean =>
+		a.size === b.size && [...a].every((name) => b.has(name));
+
+	// Hides only the declarations of active subagent tools; other tools keep their loadout. Runs on
+	// every loadout recompute, so it follows the registered profile: a preference that is only
+	// pending (mid-stream) must not rewrite a live loadout.
+	const hideDeclarations = (loadout: ToolLoadout): ToolLoadoutChanges | undefined => {
+		if (applied !== "codemode") return undefined;
+		const active = new Set(loadout.declared.map((tool) => tool.name));
+		const hidden = definitions.map((definition) => definition.name).filter((name) => active.has(name));
+		return hidden.length > 0 ? { hiddenDeclarations: hidden } : undefined;
+	};
+
+	// Register the profile for the given effective mode. Only own tools that are really active stay
+	// script-callable (`deferred`); inactive own tools are `model-only` and never callable. Re-registering
+	// must not reactivate a tool the user deactivated, so `defaultActive: false` replaces the native
+	// default once the initial registration has made the tools available by default.
+	const register = (mode: EffectiveMode, ownActive: ReadonlySet<string>, initial = false): void => {
+		const own = new Set(ownNames());
+		applied = mode;
+		for (const definition of definitions) {
+			const scriptCallable = mode === "codemode" && ownActive.has(definition.name);
+			const exposure: ToolExposure = scriptCallable ? "deferred" : "model-only";
+			const promptGuidelines = [...(definition.promptGuidelines ?? [])];
+			if (scriptCallable && !promptGuidelines.includes(CODEMODE_DISCOVERY_GUIDELINE))
+				promptGuidelines.push(CODEMODE_DISCOVERY_GUIDELINE);
+			// In the direct profile there is no script path, so the pointer would be unreachable.
+			const description =
+				mode === "direct" ? definition.description.replace(NAMESPACE_REFERENCE, "") : definition.description;
+			pi.registerTool({
+				...definition,
+				description,
+				exposure,
+				namespace: SUBAGENT_NAMESPACE,
+				promptGuidelines,
+				prepareLoadout: hideDeclarations,
+				...(initial ? {} : { defaultActive: false }),
+			} as AnyToolDefinition);
+		}
+		// With an explicit --tools/defaultTools allowlist the SDK force-activates every registered
+		// declarable tool it names, ignoring `defaultActive`. Restore exactly the own-name membership
+		// that was asked for; every unrelated name, including a newly registered one, is preserved.
+		if (!initial) {
+			const active = pi.getActiveTools();
+			if (active.some((name) => own.has(name) && !ownActive.has(name)))
+				pi.setActiveTools(active.filter((name) => !own.has(name) || ownActive.has(name)));
+		}
+		appliedOwn = new Set(ownActive);
+	};
+
+	return {
+		get preference() {
+			return preference;
+		},
+		get applied() {
+			return applied;
+		},
+		effective: (active = pi.getActiveTools()) => effectiveFrom(active),
+		describe() {
+			const active = pi.getActiveTools();
+			const target = effectiveFrom(active);
+			const shown = applied ?? target;
+			const available = codemodeActive(active);
+			const availability = available ? "codemode is active" : "codemode is not active";
+			const fallback = !available && preference === "codemode" ? "; using direct fallback" : "";
+			const pending = target !== shown ? `; pending ${target} at the next request boundary` : "";
+			return `Subagent exposure: mode ${preference} → effective ${shown} (${availability}${fallback}${pending}). Use /subagents mode auto|direct|codemode.`;
+		},
+		setPreference(mode) {
+			preference = mode;
+			pi.appendEntry(MODE_ENTRY_TYPE, { mode });
+		},
+		restore(ctx) {
+			let restored: SubagentMode | undefined;
+			for (const entry of ctx.sessionManager.getBranch()) {
+				const candidate = entry as { type?: string; customType?: string; data?: { mode?: unknown } };
+				if (
+					candidate.type === "custom" &&
+					candidate.customType === MODE_ENTRY_TYPE &&
+					isSubagentMode(candidate.data?.mode)
+				)
+					restored = candidate.data.mode;
+			}
+			// Branch-sensitive state: a branch without an entry uses the package default again.
+			preference = restored ?? "auto";
+		},
+		sync() {
+			const own = new Set(ownNames());
+			const active = pi.getActiveTools();
+			const next = effectiveFrom(active);
+			const ownActive = new Set(active.filter((name) => own.has(name)));
+			// Members inside a profile are part of the registration: a helper activated or deactivated
+			// natively must change its exposure (deferred vs model-only) at the next boundary.
+			if (next === applied && sameSet(ownActive, appliedOwn)) return false;
+			register(next, ownActive);
+			return true;
+		},
+		registerInitial() {
+			// Before the session runtime exists `pi.getActiveTools()` is not bound; the optimistic
+			// all-active set is corrected by `sync()` once the session starts.
+			register("direct", new Set(ownNames()), true);
+		},
+	};
+}

package/src/schemas.ts

@@ -1,8 +1,17 @@
-import { StringEnum } from "@earendil-works/pi-ai";
+import { type ModelThinkingLevel, StringEnum } from "@earendil-works/pi-ai";
 import { type Static, Type } from "typebox";
 import { DEFAULT_CONCURRENCY, MAX_CONCURRENCY } from "./manager.ts";
 
-const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+/** Schema vocabulary; per-model supported levels come from pi-ai. */
+const THINKING_LEVELS = [
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
+] as const satisfies readonly ModelThinkingLevel[];
 const TaskItem = Type.Object({
 	id: Type.Optional(Type.String({ description: "Optional stable task id" })),
 	agent: Type.String({ minLength: 1, description: "Agent name you invent (defined inline via `prompt`)" }),
@@ -10,10 +19,16 @@ const TaskItem = Type.Object({
 	prompt: Type.Optional(Type.String({ description: "System prompt defining this agent's behavior" })),
 	write: Type.Optional(
 		Type.Boolean({
-			description: "true = write toolset (adds bash, edit, write); default false = read-only (read, grep, find, ls)",
+			description:
+				"true = write toolset (adds bash, edit, write); default false = read-only (read, grep, find, ls, codemode)",
+		}),
+	),
+	model: Type.Optional(
+		Type.String({
+			description:
+				"Model override (provider/model-id). Omit to inherit the session model; call subagent_models for the exact references this session accepts.",
 		}),
 	),
-	model: Type.Optional(Type.String({ description: "Model override (provider/model-id)" })),
 	thinking: Type.Optional(StringEnum(THINKING_LEVELS, { description: "Thinking level override" })),
 	cwd: Type.Optional(Type.String({ description: "Working directory (default: current project)" })),
 	tools: Type.Optional(Type.Array(Type.String(), { description: "Explicit tool allowlist (overrides the toolset)" })),
@@ -35,7 +50,12 @@ export const SubagentParams = Type.Object({
 	),
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "Parallel tasks" })),
 	chain: Type.Optional(Type.Array(TaskItem, { description: "Sequential tasks; {previous} = prior output" })),
-	model: Type.Optional(Type.String({ description: "Model override (single mode)" })),
+	model: Type.Optional(
+		Type.String({
+			description:
+				"Model override (single mode). Omit to inherit the session model; call subagent_models for the exact references this session accepts.",
+		}),
+	),
 	thinking: Type.Optional(StringEnum(THINKING_LEVELS, { description: "Thinking level override (single mode)" })),
 	cwd: Type.Optional(Type.String({ description: "Working directory (single mode). Default: current project." })),
 	concurrency: Type.Optional(
@@ -64,6 +84,7 @@ export type TaskInput = Static<typeof TaskItem>;
 export type SubagentParamsShape = Static<typeof SubagentParams>;
 
 export const RunIdParam = Type.Object({ runId: Type.String({ description: "Run id from subagent()" }) });
+export const ModelsParam = Type.Object({});
 export const ResultParam = Type.Object({
 	runId: Type.String(),
 	taskId: Type.Optional(Type.String({ description: "Specific task id; defaults to all" })),

package/src/types.ts

@@ -71,3 +71,55 @@ export interface RunDetails {
 export interface PendingReply {
 	resolve: (message: string) => void;
 }
+
+/** Per-million-token USD rates, as pi reports them. */
+export interface ModelPricing {
+	input: number;
+	output: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+}
+
+/** One selectable model, as the agent needs it to choose: what to pass, what it supports, what it costs. */
+export interface SelectableModel {
+	/** The value to pass as `model` ("provider/id"). */
+	reference: string;
+	provider: string;
+	id: string;
+	name: string;
+	reasoning: boolean;
+	/** Levels the runtime honors without clamping. */
+	thinkingLevels: string[];
+	/** 0 when the provider did not report one. */
+	contextWindow: number;
+	/** pi's catalog rates, or undefined when the provider reported none — distinct from free. */
+	cost?: ModelPricing;
+}
+
+export interface ModelCatalog {
+	models: SelectableModel[];
+	/**
+	 * What the list was scoped to. pi resolves `enabledModels` (and `--models`) into scoped models,
+	 * so this is normally the session's own enabled set rather than every model with credentials.
+	 */
+	scope: "session" | "all";
+	/** The config's suggested model, surfaced for the caller to weigh. Never applied automatically. */
+	preferredDefault?: string;
+	unlistedDefault?: string;
+	/** Set when the preferences file existed but was unusable, so a typo is reported, not silent. */
+	configError?: string;
+	/** How many models the config hid, so a surprising absence is explained. */
+	hidden?: number;
+	/** Preferred/hidden patterns that matched no listed model — inert config, reported not hidden. */
+	unusedPatterns?: string[];
+	/** References that are NOT safe to pass because another model's bare id would win resolution. */
+	ambiguous?: string[];
+	/** Why the ambiguous references are unsafe, in full, so the agent can act instead of retrying blindly. */
+	reason?: string;
+	/** Entries the registry itself could not resolve — a registry fault, distinct from a name collision. */
+	unresolved?: string[];
+	/** Why those entries failed, so a registry fault is never mistaken for a collision. */
+	unresolvedReason?: string;
+	/** Set when the catalog is empty, so the caller knows it is not looking at a legitimate empty list. */
+	unavailable?: string;
+}