@arhen/pi-core-subagent 1.3.61 → 1.3.62

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.62",
 	"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,
@@ -271,3 +273,76 @@ export function makeNotice(run: RunSnapshot, kind: string): string {
 	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,21 @@
 import type { ExtensionAPI, ExtensionContext } 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 {
+	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 {
 	AwaitParam,
+	ModelsParam,
 	ReplyParam,
 	ResultParam,
 	ResumeParam,
@@ -14,7 +24,7 @@ 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) {
@@ -124,6 +134,18 @@ export default function (pi: ExtensionAPI) {
 		manager.clearRuns();
 	});
 
+	pi.registerTool<typeof ModelsParam, ModelCatalog>({
+		name: "subagent_models",
+		label: "Subagent Models",
+		description:
+			"List the models a subagent task may name, each with the exact `model` value to pass. The list is scoped to this session's enabled models when scoping is configured (the same set `/scoped-models` shows); when no scoping is configured, every model with usable credentials is listed and the output says so. Each entry includes its context window and pi catalog price per million tokens, and the thinking levels the runtime honors — a level shown here is not silently clamped. References shown here are safe to pass; ambiguous ones are called out. Naming a model is optional: omit `model` to inherit the session model, or call this when choosing one.",
+		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));
+		},
+	});
+
 	pi.registerTool<typeof SubagentParams, RunDetails>({
 		name: "subagent",
 		label: "Subagent",
@@ -132,6 +154,7 @@ export default function (pi: ExtensionAPI) {
 			"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).",
 		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.",

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,
@@ -174,27 +175,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 +796,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 +1187,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 +1415,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/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`)" }),
@@ -13,7 +22,12 @@ const TaskItem = Type.Object({
 			description: "true = write toolset (adds bash, edit, write); default false = read-only (read, grep, find, ls)",
 		}),
 	),
-	model: Type.Optional(Type.String({ description: "Model override (provider/model-id)" })),
+	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.",
+		}),
+	),
 	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 +49,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 +83,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;
+}