pi-ui-extend 1.0.39 → 1.0.41

package/external/pi-tools-suite/src/async-subagents/core/config.ts

@@ -3,6 +3,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { applyEdits, modify, parse as parseJsonc } from "jsonc-parser";
+import { readAgentDefinitionsFromDir, readProjectAgentDefinitions, type AgentDefinition } from "./agents-dir.js";
 import { ensurePiToolsSuiteUserConfig, getPiToolsSuiteUserConfigPath } from "../../config.js";
 import type { AgentTask, RetryConfig } from "./types.js";
 
@@ -15,14 +16,24 @@ export interface ModelByParentEntry {
 
 export interface SubagentTypeConfig {
 	description?: string;
+	/**
+	 * Agent icon name resolved by UIs (pix TUI icon themes, Pix Desktop lucide
+	 * icons). Opaque pass-through here: unknown names render as the neutral
+	 * default agent icon.
+	 */
+	icon?: string;
+	/** Ranked candidates. The preset filters availability, never changes this order. */
+	models?: string[];
+	/** Legacy primary candidate; new profiles use models. */
 	model?: string;
-	/** Ordered model fallbacks used when the selected model hits quota/rate limits. */
+	/** Legacy candidates after model; new profiles use one ordered models list. */
 	fallbackModels?: string[];
 	/**
 	 * Parent-model-aware model selection. Keys are glob model refs (e.g. "zai/*")
 	 * matched against the current parent model; the first matching key wins.
 	 * Values may be a model ref string or { model, fallbackModels? }.
-	 * Resolved after explicit task.model / forcedModel, before preset/static model.
+	 * Ordinary roles: explicit task/forced model and preset models take priority.
+	 * Oracle alone keeps parent-aware selection ahead of presets.
 	 */
 	modelByParent?: Record<string, ModelByParentEntry>;
 	thinking?: string;
@@ -70,6 +81,9 @@ export interface SubagentVisionConfig {
 
 export interface SubagentPreset {
 	description?: string;
+	/** Available model pool. Agent candidate order wins; [] allows no models. */
+	models?: string[];
+	/** Legacy default model; prefer models for new presets. */
 	model?: string;
 	/** Ordered global model fallbacks used when this preset's selected model hits quota/rate limits. */
 	fallbackModels?: string[];
@@ -92,9 +106,10 @@ export interface SubagentPresetTypeOverride {
 }
 
 export interface SubagentConfig {
+	/** Ambiguous-task router hint and legacy resolver default; never a spawn error fallback. */
 	defaultType?: string;
 	types: Record<string, SubagentTypeConfig>;
-	/** LLM-based role routing for tasks that omit subagentType. */
+	/** Fallback LLM role selection for omitted types; explicit valid types bypass it. */
 	routing?: SubagentRoutingConfig;
 	/** Vision capability overrides for parent-model guidance. */
 	vision?: SubagentVisionConfig;
@@ -133,6 +148,13 @@ export interface ResolvedAgentTaskConfig {
 	timeoutMs?: number;
 }
 
+export class SubagentModelSelectionError extends Error {
+	constructor(taskId: string, message: string) {
+		super(`Task ${taskId}: ${message} No agents were launched. Configure a compatible model pool/candidate list or provide an explicit model override.`);
+		this.name = "SubagentModelSelectionError";
+	}
+}
+
 export interface ResolveAgentTaskOptions {
 	/** Default model for spawned sub-agents when task/profile do not specify one. */
 	model?: string;
@@ -166,7 +188,7 @@ export const DEFAULT_MAX_CONCURRENT = 5;
 /** Default lightweight LLM router used when subagentType is omitted. */
 export const DEFAULT_ROUTING_CONFIG: ResolvedSubagentRoutingConfig = {
 	enabled: true,
-	model: "zai/glm-4.5-air",
+	model: "zai/glm-5-turbo",
 	fallbackModels: ["openai-codex/gpt-5.6-luna"],
 	maxTaskChars: 1200,
 	maxTokens: 512,
@@ -175,98 +197,13 @@ export const DEFAULT_ROUTING_CONFIG: ResolvedSubagentRoutingConfig = {
 	debug: false,
 };
 
+const BUILTIN_AGENTS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "agents");
+
 const BUILTIN_CONFIG: SubagentConfig = {
+	defaultType: "research",
 	maxConcurrent: DEFAULT_MAX_CONCURRENT,
 	routing: { ...DEFAULT_ROUTING_CONFIG },
-	types: {
-		quick: {
-			description: "Use for tiny cheap tasks: answer a simple question, inspect one known file, or verify one fact. Not for broad repo search.",
-			model: "openai-codex/gpt-5.6-luna",
-			fallbackModels: ["zai/glm-4.5-air"],
-			thinking: "off",
-		},
-		scan: {
-			description: "Use for finding files, symbols, text, or inventory across a repo. Return paths/facts; do not judge code quality.",
-			model: "openai-codex/gpt-5.6-luna",
-			fallbackModels: ["zai/glm-4.5-air"],
-			thinking: "off",
-		},
-		research: {
-			description: "Use for multi-file codebase research: read several files and explain how something works. No edits.",
-			model: "openai-codex/gpt-5.6-terra",
-			fallbackModels: ["zai/glm-5-turbo"],
-			thinking: "low",
-		},
-		docs: {
-			description: "Use for documentation work: README/API docs review, docs gaps, changelog, migration notes, examples.",
-			model: "openai-codex/gpt-5.6-luna",
-			fallbackModels: ["zai/glm-4.5-air"],
-			thinking: "low",
-		},
-		frontend: {
-			description: "Use for frontend UI/UX visual work: styling, layout, typography, animation, responsive states, component polish, and accessibility. Avoid backend/business logic unless needed for UI behavior.",
-			thinking: "medium",
-			promptAppend: [
-				"Act as a frontend UI/UX engineer for visual and product-facing work.",
-				"Prioritize layout, typography, spacing, color, motion, responsive states, accessibility, and consistency with the existing design system.",
-				"Before editing, inspect nearby components/styles and infer the project's design language. Avoid backend/business-logic changes unless required for UI behavior.",
-				"When no mockup exists, choose a clear aesthetic direction and explain it briefly. Verify with targeted build/lint/tests or screenshot-relevant checks when possible.",
-			].join("\n"),
-		},
-		"browser-qa": {
-			description: "Use for browser-based visual QA: reproduce UI bugs and verify fixes with deterministic assertions, screenshots, video, and traces.",
-			model: "zai/glm-5.3-flash",
-			fallbackModels: ["openai-codex/gpt-5.6-luna"],
-			thinking: "low",
-			timeoutMs: 300_000,
-			tools: ["read", "grep", "bash"],
-			isolatedSkills: [getBrowserQaSkillPath()],
-		},
-		implement: {
-			description: "Use when the sub-agent should make or plan code changes for a feature, bug fix, or refactor.",
-			modelByParent: {
-				"openai-codex/gpt-5.6-luna*": { model: "openai-codex/gpt-5.6-terra", fallbackModels: ["zai/glm-5.3"] },
-				"openai-codex/gpt-5.6-sol*": { model: "openai-codex/gpt-5.6-terra", fallbackModels: ["zai/glm-5.3"] },
-			},
-			thinking: "high",
-		},
-		tests: {
-			description: "Use for tests: locate coverage, find gaps, run/check targeted test commands, diagnose failing tests.",
-			model: "openai-codex/gpt-5.6-terra",
-			fallbackModels: ["zai/glm-5-turbo"],
-			thinking: "medium",
-		},
-		review: {
-			description: "Use for review/audit of existing code or changes: correctness, security, performance, maintainability, API risks, quality. Do not implement new code.",
-			modelByParent: {
-				"openai-codex/gpt-5.6-luna*": { model: "openai-codex/gpt-5.6-sol", fallbackModels: ["zai/glm-5.3"] },
-				"openai-codex/gpt-5.6-terra*": { model: "openai-codex/gpt-5.6-sol", fallbackModels: ["zai/glm-5.3"] },
-			},
-			thinking: "high",
-		},
-		deep: {
-			description: "Use for broad hard reasoning: architecture, root-cause analysis, cross-module impact, complex debugging or tradeoffs.",
-			modelByParent: {
-				"openai-codex/gpt-5.6-luna*": { model: "openai-codex/gpt-5.6-sol", fallbackModels: ["zai/glm-5.3"] },
-				"openai-codex/gpt-5.6-terra*": { model: "openai-codex/gpt-5.6-sol", fallbackModels: ["zai/glm-5.3"] },
-			},
-			thinking: "high",
-		},
-		oracle: {
-			description: "Oracle: cross-provider flagship second opinion for hard or high-stakes uncertainty. Use sparingly to pressure-test architecture, plans, root-cause hypotheses, risk/security calls, or final recommendations when independent disagreement is valuable. Read-only; advise, do not edit.",
-			model: "openai-codex/gpt-5.6-sol",
-			fallbackModels: ["zai/glm-5.3"],
-			modelByParent: {
-				"zai/*": { model: "openai-codex/gpt-5.6-sol", fallbackModels: ["zai/glm-5.3"] },
-				"openai-codex/*": { model: "zai/glm-5.3", fallbackModels: ["openai-codex/gpt-5.6-sol"] },
-				"antigravity/*": { model: "zai/glm-5.3", fallbackModels: ["openai-codex/gpt-5.6-sol"] },
-				"anthropic/*": { model: "openai-codex/gpt-5.6-sol", fallbackModels: ["zai/glm-5.3"] },
-			},
-			thinking: "max",
-			tools: ["read", "grep", "bash"],
-			promptAppend: "You are an oracle: a flagship model from a different provider giving a second opinion to the parent agent. Give a concise, decisive recommendation with key tradeoffs and risks. Disagree when warranted; do not rubber-stamp. Do not edit unless explicitly asked.",
-		},
-	},
+	types: normalizeAgentDefinitions(readAgentDefinitionsFromDir(BUILTIN_AGENTS_DIR)),
 };
 
 export function loadSubagentConfig(cwd: string, env: NodeJS.ProcessEnv = process.env): SubagentConfig {
@@ -275,6 +212,10 @@ export function loadSubagentConfig(cwd: string, env: NodeJS.ProcessEnv = process
 		for (const file of piToolsSuiteConfigFiles(cwd, env)) {
 			mergeConfig(config, readPiToolsSuiteSubagentConfig(file));
 		}
+		// Project-local agent definitions (.pi/agents/*.md) win name collisions
+		// over user/project JSONC config; loaded fresh on every call so edits and
+		// /reload are respected without a restart.
+		mergeConfig(config, projectAgentTypes(cwd));
 	}
 	for (const file of configFiles(cwd, env)) {
 		mergeConfig(config, readConfigFile(file));
@@ -307,8 +248,8 @@ export function getSubagentConfigSamplePath(): string {
 	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "async-subagents.sample.jsonc");
 }
 
-export function getBrowserQaSkillPath(): string {
-	return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "private-skills", "browser-qa", "SKILL.md");
+export function getBuiltinSubagentDefinitionsDir(): string {
+	return BUILTIN_AGENTS_DIR;
 }
 
 export function getSubagentConfigInitTargetPath(cwd: string, env: NodeJS.ProcessEnv = process.env): string {
@@ -329,6 +270,22 @@ function piToolsSuiteConfigFiles(cwd: string, env: NodeJS.ProcessEnv): string[]
 	].filter((file): file is string => typeof file === "string" && fs.existsSync(file));
 }
 
+/** Normalize `.pi/agents/*.md` definitions through the shared type-profile path. */
+function projectAgentTypes(cwd: string): Partial<SubagentConfig> {
+	const definitions = readProjectAgentDefinitions(cwd);
+	const types = normalizeAgentDefinitions(definitions);
+	if (Object.keys(types).length === 0) return {};
+	return { types };
+}
+
+function normalizeAgentDefinitions(definitions: Record<string, AgentDefinition>): Record<string, SubagentTypeConfig> {
+	const types: Record<string, SubagentTypeConfig> = {};
+	for (const [name, definition] of Object.entries(definitions)) {
+		types[name] = normalizeSubagentTypeProfile(definition.raw, name, definition.file);
+	}
+	return types;
+}
+
 function findProjectPiToolsSuiteConfig(startDir: string): string | undefined {
 	let dir = path.resolve(startDir);
 	const root = path.parse(dir).root;
@@ -373,12 +330,19 @@ export function resolveAgentTaskConfig(
 	const selectedType = selectSubagentType(task, config);
 	const profile = selectedType ? config.types[selectedType] : undefined;
 	const preset = globalOptions.preset;
-	const presetType = selectedType ? preset?.types?.[selectedType] : undefined;
+	// A new pool preset has no per-role policy. Ignore any inherited legacy
+	// matrix/defaults so changing the pool cannot resurrect an expensive model.
+	const legacyPreset = preset?.models === undefined ? preset : undefined;
 	const explicitType = trimString(task.subagentType);
+	const requestedType = explicitType || trimString(config.defaultType);
+	// Legacy preset matrices still apply to an explicitly configured type with
+	// the same name. There are no implicit aliases between type names.
+	const presetType = (requestedType ? legacyPreset?.types?.[requestedType] : undefined)
+		?? (selectedType ? legacyPreset?.types?.[selectedType] : undefined);
 	const taskExtraArgs = arrayOfStrings(task.extraArgs) ?? [];
 	const profileExtraArgs = arrayOfStrings(profile?.extraArgs) ?? [];
 	const presetTypeExtraArgs = arrayOfStrings(presetType?.extraArgs) ?? [];
-	const presetExtraArgs = arrayOfStrings(preset?.extraArgs) ?? [];
+	const presetExtraArgs = arrayOfStrings(legacyPreset?.extraArgs) ?? [];
 	const globalExtraArgs = arrayOfStrings(globalOptions.extraArgs) ?? [];
 	const promptAppend = joinTextBlocks(profile?.promptAppend, task.promptAppend);
 	const forcedModel = trimString(globalOptions.forcedModel);
@@ -387,33 +351,60 @@ export function resolveAgentTaskConfig(
 	const parentMatchModel = trimString(parentMatch?.model);
 	const presetTypeModel = trimString(presetType?.model);
 	const globalModel = trimString(globalOptions.model);
-	const presetModel = trimString(preset?.model);
-	const profileModel = trimString(profile?.model);
-	const model = forcedModel || taskModel || parentMatchModel || presetTypeModel || globalModel || presetModel || profileModel;
-	const usedParentMatch = Boolean(parentMatchModel) && model === parentMatchModel;
-	const fallbackModels = forcedModel || taskModel
+	const presetModel = trimString(legacyPreset?.model);
+	const profileModels = profile?.models ?? modelList(profile?.model, profile?.fallbackModels) ?? [];
+	const profileModel = profileModels[0];
+	const usedParentMatch = Boolean(parentMatchModel) && !forcedModel && !taskModel
+		&& (selectedType === "oracle" || !(presetTypeModel || globalModel || presetModel));
+	const primaryModel = forcedModel || taskModel || (usedParentMatch ? parentMatchModel : undefined)
+		|| presetTypeModel || globalModel || presetModel || profileModel;
+	const configuredFallbacks = forcedModel || taskModel
 		? []
-		: usedParentMatch && parentMatch?.fallbackModels && parentMatch.fallbackModels.length > 0
+		: usedParentMatch && parentMatch?.fallbackModels !== undefined
 			? parentMatch.fallbackModels
-			: resolveFallbackModels({ model, presetType, preset, profile });
+			: resolveFallbackModels({ model: primaryModel, presetType, preset: legacyPreset, profileModels, profile });
 	const extraArgs = forcedModel
 		? stripModelArgs([...profileExtraArgs, ...presetTypeExtraArgs, ...taskExtraArgs, ...presetExtraArgs, ...globalExtraArgs])
 		: [...profileExtraArgs, ...presetTypeExtraArgs, ...taskExtraArgs, ...presetExtraArgs, ...globalExtraArgs];
-	const timeoutMs = task.timeoutMs ?? globalOptions.timeoutMs ?? presetType?.timeoutMs ?? preset?.timeoutMs ?? profile?.timeoutMs ?? config.timeoutMs;
+	const cliModel = modelFromArgs(extraArgs);
+	const explicitModel = forcedModel || cliModel || taskModel;
+	let candidates = modelList(explicitModel || primaryModel, explicitModel ? [] : configuredFallbacks) ?? [];
+	if (!explicitModel) {
+		if (selectedType === "oracle" && globalOptions.parentModel && !usedParentMatch
+			&& !presetTypeModel && !presetModel && !globalModel && !profile?.model) {
+			const parentProvider = globalOptions.parentModel.split("/")[0];
+			candidates = [
+				...candidates.filter((ref) => ref.split("/")[0] !== parentProvider),
+				...candidates.filter((ref) => ref.split("/")[0] === parentProvider),
+			];
+		}
+		if (preset?.models !== undefined) {
+			const available = new Set(preset.models);
+			candidates = candidates.filter((ref) => available.has(ref));
+			if (candidates.length === 0) {
+				throw new SubagentModelSelectionError(task.id, "No ranked candidate is in the active preset's models pool.");
+			}
+		}
+	}
+	if (candidates.length === 0) {
+		throw new SubagentModelSelectionError(task.id, "No model candidates are configured; set models on the agent profile.");
+	}
+	const [model, ...fallbackModels] = candidates;
+	const timeoutMs = task.timeoutMs ?? globalOptions.timeoutMs ?? presetType?.timeoutMs ?? legacyPreset?.timeoutMs ?? profile?.timeoutMs ?? config.timeoutMs;
 
 	return {
 		profile,
 		extraArgs,
-		isolatedSkills: resolveIsolatedSkills(selectedType, profile),
+		isolatedSkills: arrayOfStrings(profile?.isolatedSkills) ?? [],
 		fallbackModels,
 		retry: resolveRetryConfig(config.retry, profile?.retry),
 		maxResultBytes: profile?.maxResultBytes ?? config.maxResultBytes,
 		timeoutMs,
 		task: {
 			...task,
-			subagentType: explicitType || selectedType,
+			subagentType: selectedType,
 			model,
-			thinking: trimString(globalOptions.thinking) || trimString(task.thinking) || trimString(presetType?.thinking) || trimString(globalOptions.defaultThinking) || trimString(preset?.thinking) || trimString(profile?.thinking),
+			thinking: trimString(globalOptions.thinking) || trimString(task.thinking) || trimString(presetType?.thinking) || trimString(globalOptions.defaultThinking) || trimString(legacyPreset?.thinking) || trimString(profile?.thinking),
 			promptAppend,
 			promptOverride: trimString(task.promptOverride) || trimString(profile?.promptOverride),
 			tools: task.tools && task.tools.length > 0 ? task.tools : arrayOfStrings(profile?.tools),
@@ -422,18 +413,14 @@ export function resolveAgentTaskConfig(
 	};
 }
 
-function resolveIsolatedSkills(selectedType: string | undefined, profile: SubagentTypeConfig | undefined): string[] {
-	const configured = arrayOfStrings(profile?.isolatedSkills) ?? [];
-	if (selectedType !== "browser-qa") return configured;
-	return [...new Set([getBrowserQaSkillPath(), ...configured])];
-}
-
 export function resolveSubagentRoutingConfig(config: SubagentConfig): ResolvedSubagentRoutingConfig {
 	return { ...DEFAULT_ROUTING_CONFIG, ...(config.routing ?? {}) };
 }
 
 export function defaultSubagentType(config: SubagentConfig): string | undefined {
-	return trimString(config.defaultType) || Object.keys(config.types).find((name) => trimString(name));
+	const configured = trimString(config.defaultType);
+	if (configured) return Object.prototype.hasOwnProperty.call(config.types, configured) ? configured : undefined;
+	return Object.keys(config.types).find((name) => trimString(name));
 }
 
 /** Merge global and per-type retry partials into a fully resolved RetryConfig. Per-type wins. */
@@ -530,6 +517,7 @@ function normalizeConfig(value: Record<string, unknown>, file: string): Partial<
 			if (!isRecord(rawPreset)) throw new Error(`Subagent preset "${name}" must be an object: ${file}`);
 			presets[name] = {
 				description: trimString(rawPreset.description),
+				models: normalizeModels(rawPreset.models, `preset "${name}"`, file),
 				model: trimString(rawPreset.model),
 				fallbackModels: modelList(rawPreset.fallbackModels, rawPreset.fallbackModel),
 				thinking: trimString(rawPreset.thinking),
@@ -546,26 +534,42 @@ function normalizeConfig(value: Record<string, unknown>, file: string): Partial<
 	const types: Record<string, SubagentTypeConfig> = {};
 	for (const [name, rawProfile] of Object.entries(value.types)) {
 		if (!isRecord(rawProfile)) throw new Error(`Subagent type "${name}" must be an object: ${file}`);
-		types[name] = {
-			description: trimString(rawProfile.description),
-			model: trimString(rawProfile.model),
-			fallbackModels: modelList(rawProfile.fallbackModels, rawProfile.fallbackModel),
-			modelByParent: normalizeModelByParent(rawProfile.modelByParent, name, file),
-			thinking: trimString(rawProfile.thinking),
-			tools: arrayOfStrings(rawProfile.tools),
-			isolatedSkills: arrayOfStrings(rawProfile.isolatedSkills),
-			extraArgs: arrayOfStrings(rawProfile.extraArgs),
-			promptAppend: textBlock(rawProfile.promptAppend),
-			promptOverride: textBlock(rawProfile.promptOverride),
-			retry: isRecord(rawProfile.retry) ? normalizeRetryConfig(rawProfile.retry) : undefined,
-			maxResultBytes: finiteNumber(rawProfile.maxResultBytes) !== undefined ? Math.max(0, Math.round(finiteNumber(rawProfile.maxResultBytes)!)) : undefined,
-			timeoutMs: positiveMilliseconds(rawProfile.timeoutMs),
-		};
+		types[name] = normalizeSubagentTypeProfile(rawProfile, name, file);
 	}
 	output.types = types;
 	return output;
 }
 
+/**
+ * Normalize one raw sub-agent type profile (`SubagentTypeConfig` shape) from
+ * any source (JSONC config files or project agent definitions). Shared so all
+ * sources apply identical field validation and trimming.
+ */
+export function normalizeSubagentTypeProfile(
+	rawProfile: Record<string, unknown>,
+	name: string,
+	file: string,
+): SubagentTypeConfig {
+	const models = normalizeModels(rawProfile.models, `type "${name}"`, file);
+	return {
+		description: trimString(rawProfile.description),
+		icon: trimString(rawProfile.icon),
+		models,
+		model: models === undefined ? trimString(rawProfile.model) : undefined,
+		fallbackModels: models === undefined ? modelList(rawProfile.fallbackModels, rawProfile.fallbackModel) : undefined,
+		modelByParent: models === undefined ? normalizeModelByParent(rawProfile.modelByParent, name, file) : undefined,
+		thinking: trimString(rawProfile.thinking),
+		tools: arrayOfStrings(rawProfile.tools),
+		isolatedSkills: arrayOfStrings(rawProfile.isolatedSkills),
+		extraArgs: arrayOfStrings(rawProfile.extraArgs),
+		promptAppend: textBlock(rawProfile.promptAppend),
+		promptOverride: textBlock(rawProfile.promptOverride),
+		retry: isRecord(rawProfile.retry) ? normalizeRetryConfig(rawProfile.retry) : undefined,
+		maxResultBytes: finiteNumber(rawProfile.maxResultBytes) !== undefined ? Math.max(0, Math.round(finiteNumber(rawProfile.maxResultBytes)!)) : undefined,
+		timeoutMs: positiveMilliseconds(rawProfile.timeoutMs),
+	};
+}
+
 function mergeConfig(target: SubagentConfig, source: Partial<SubagentConfig>): void {
 	if (source.defaultType) target.defaultType = source.defaultType;
 	if (source.routing) target.routing = { ...(target.routing ?? {}), ...source.routing };
@@ -575,14 +579,45 @@ function mergeConfig(target: SubagentConfig, source: Partial<SubagentConfig>): v
 	if (source.timeoutMs !== undefined) target.timeoutMs = source.timeoutMs;
 	if (source.retry) target.retry = { ...(target.retry ?? {}), ...source.retry };
 	for (const [name, profile] of Object.entries(source.types ?? {})) {
-		target.types[name] = { ...(target.types[name] ?? {}), ...compactProfile(profile) };
+		target.types[name] = mergeTypeProfile(target.types[name] ?? {}, profile);
 	}
 	for (const [name, preset] of Object.entries(source.presets ?? {})) {
 		target.presets = target.presets ?? {};
-		target.presets[name] = { ...(target.presets[name] ?? {}), ...compactPreset(preset) };
+		const previous = target.presets[name] ?? {};
+		const merged = { ...previous, ...compactPreset(preset) };
+		// The explicit selector form in the later config wins in both directions.
+		if (preset.models !== undefined) {
+			delete merged.model;
+			delete merged.fallbackModels;
+			delete merged.types;
+			delete merged.thinking;
+			delete merged.extraArgs;
+			delete merged.timeoutMs;
+		} else if (preset.model || preset.fallbackModels !== undefined || preset.types) {
+			delete merged.models;
+		}
+		target.presets[name] = merged;
 	}
 }
 
+/** Preserve legacy field overrides without allowing inherited primary models
+ * to win over a newly supplied candidate list (or the reverse). */
+function mergeTypeProfile(base: SubagentTypeConfig, source: SubagentTypeConfig): SubagentTypeConfig {
+	const merged = { ...compactProfile(base), ...compactProfile(source) };
+	if (source.models !== undefined) {
+		merged.models = [...source.models];
+		delete merged.model;
+		delete merged.fallbackModels;
+		delete merged.modelByParent;
+	} else if (source.model || source.fallbackModels !== undefined) {
+		const previous = base.models ?? modelList(base.model, base.fallbackModels) ?? [];
+		delete merged.models;
+		merged.model = source.model ?? previous[0];
+		merged.fallbackModels = source.fallbackModels ?? base.fallbackModels ?? previous.slice(1);
+	}
+	return merged;
+}
+
 function normalizeRoutingConfig(value: Record<string, unknown>): SubagentRoutingConfig {
 	const routing: SubagentRoutingConfig = {};
 	if (typeof value.enabled === "boolean") routing.enabled = value.enabled;
@@ -625,8 +660,10 @@ function modelPatternRegExp(pattern: string): RegExp {
 function compactProfile(profile: SubagentTypeConfig): SubagentTypeConfig {
 	const compact: SubagentTypeConfig = {};
 	if (profile.description) compact.description = profile.description;
+	if (profile.icon) compact.icon = profile.icon;
+	if (profile.models !== undefined) compact.models = profile.models;
 	if (profile.model) compact.model = profile.model;
-	if (profile.fallbackModels && profile.fallbackModels.length > 0) compact.fallbackModels = profile.fallbackModels;
+	if (profile.fallbackModels) compact.fallbackModels = profile.fallbackModels;
 	if (profile.modelByParent) compact.modelByParent = profile.modelByParent;
 	if (profile.thinking) compact.thinking = profile.thinking;
 	if (profile.tools && profile.tools.length > 0) compact.tools = profile.tools;
@@ -643,8 +680,9 @@ function compactProfile(profile: SubagentTypeConfig): SubagentTypeConfig {
 function compactPreset(preset: SubagentPreset): SubagentPreset {
 	const compact: SubagentPreset = {};
 	if (preset.description) compact.description = preset.description;
+	if (preset.models !== undefined) compact.models = preset.models;
 	if (preset.model) compact.model = preset.model;
-	if (preset.fallbackModels && preset.fallbackModels.length > 0) compact.fallbackModels = preset.fallbackModels;
+	if (preset.fallbackModels) compact.fallbackModels = preset.fallbackModels;
 	if (preset.thinking) compact.thinking = preset.thinking;
 	if (preset.extraArgs && preset.extraArgs.length > 0) compact.extraArgs = preset.extraArgs;
 	if (preset.timeoutMs !== undefined) compact.timeoutMs = preset.timeoutMs;
@@ -671,7 +709,7 @@ function normalizePresetTypeOverrides(value: unknown, file: string, presetName:
 		const extraArgs = arrayOfStrings(rawOverride.extraArgs);
 		const timeoutMs = positiveMilliseconds(rawOverride.timeoutMs);
 		if (model) override.model = model;
-		if (fallbackModels && fallbackModels.length > 0) override.fallbackModels = fallbackModels;
+		if (fallbackModels) override.fallbackModels = fallbackModels;
 		if (thinking) override.thinking = thinking;
 		if (extraArgs && extraArgs.length > 0) override.extraArgs = extraArgs;
 		if (timeoutMs !== undefined) override.timeoutMs = timeoutMs;
@@ -680,6 +718,14 @@ function normalizePresetTypeOverrides(value: unknown, file: string, presetName:
 	return Object.keys(types).length > 0 ? types : undefined;
 }
 
+function normalizeModels(value: unknown, owner: string, file: string): string[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || value.some((ref) => typeof ref !== "string" || !/^[^\s/*]+\/[^\s*]+$/.test(ref.trim()))) {
+		throw new Error(`Subagent ${owner} models must be an array of provider/model references: ${file}`);
+	}
+	return [...new Set(value.map((ref: string) => ref.trim()))];
+}
+
 function normalizeModelByParent(value: unknown, typeName: string, file: string): Record<string, ModelByParentEntry> | undefined {
 	if (value === undefined || value === null) return undefined;
 	if (!isRecord(value)) throw new Error(`Subagent type "${typeName}" modelByParent must be an object: ${file}`);
@@ -716,13 +762,12 @@ function resolveFallbackModels(options: {
 	model?: string;
 	presetType?: SubagentPresetTypeOverride;
 	preset?: SubagentPreset;
+	profileModels: string[];
 	profile?: SubagentTypeConfig;
 }): string[] {
-	const fallbacks = [
-		...(options.presetType?.fallbackModels ?? []),
-		...(options.preset?.fallbackModels ?? []),
-		...(options.profile?.fallbackModels ?? []),
-	];
+	// A selected budget's fallback list is authoritative, including [] (none).
+	const fallbacks = options.presetType?.fallbackModels
+		?? options.preset?.fallbackModels ?? options.profile?.fallbackModels ?? options.profileModels.slice(1);
 	const seen = new Set<string>();
 	if (options.model) seen.add(options.model);
 	const result: string[] = [];
@@ -736,10 +781,12 @@ function resolveFallbackModels(options: {
 }
 
 function applyEnvModelOverrides(config: SubagentConfig, env: NodeJS.ProcessEnv): void {
-	for (const [name, profile] of Object.entries(config.types)) {
+	for (const name of Object.keys(config.types)) {
 		const key = typeEnvKey(name);
 		const model = trimString(env[`ASYNC_SUBAGENTS_${key}_MODEL`] || env[`PI_SUBAGENTS_${key}_MODEL`]);
-		if (model) profile.model = model;
+		if (model) {
+			config.types[name] = mergeTypeProfile(config.types[name] ?? {}, { model });
+		}
 	}
 }
 
@@ -849,7 +896,7 @@ function modelList(...values: unknown[]): string[] | undefined {
 			models.push(model);
 		}
 	}
-	return models.length > 0 ? models : undefined;
+	return models.length > 0 || values.some(Array.isArray) ? models : undefined;
 }
 
 function patternList(...values: unknown[]): string[] | undefined {
@@ -917,6 +964,16 @@ function stripModelArgs(args: string[]): string[] {
 	return output;
 }
 
+/** CLI overrides are explicit, too; retain the final flag's actual model. */
+function modelFromArgs(args: string[]): string | undefined {
+	let model: string | undefined;
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === "--model" || args[i] === "-m") model = trimString(args[++i]);
+		else if (args[i].startsWith("--model=")) model = trimString(args[i].slice("--model=".length));
+	}
+	return model;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }

package/external/pi-tools-suite/src/async-subagents/core/model-fallback.ts

@@ -104,7 +104,7 @@ function firstAvailableFallback(failedModel: string, fallbackModels: string[]):
 	return candidates.find((candidate) => modelProvider(candidate) !== failedProvider && !isSessionModelUnavailable(candidate));
 }
 
-function isSessionModelUnavailable(model: string): boolean {
+export function isSessionModelUnavailable(model: string): boolean {
 	return exhaustedModels.has(model) || exhaustedProviders.has(modelProvider(model));
 }
 

package/external/pi-tools-suite/src/async-subagents/core/model-selection.ts

@@ -0,0 +1,54 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { isBlindModelRef, SubagentModelSelectionError, type ResolvedAgentTaskConfig, type SubagentConfig } from "./config.js";
+import { isSessionModelUnavailable } from "./model-fallback.js";
+
+export interface SubagentModelRegistry {
+	find(provider: string, modelId: string): Model<Api> | undefined;
+	/** SDK snapshot excludes providers which are registered but not configured. */
+	getAvailable?(): Model<Api>[];
+	getApiKeyAndHeaders?(model: Model<Api>): Promise<{ ok?: boolean }>;
+}
+
+/** Rank was already determined by the profile/preset intersection. No LLM call. */
+export async function selectAvailableAgentModels(
+	resolved: ResolvedAgentTaskConfig,
+	config: SubagentConfig,
+	registry?: SubagentModelRegistry,
+	signal?: AbortSignal,
+): Promise<ResolvedAgentTaskConfig> {
+	if (signal?.aborted) throw new Error("Aborted");
+	const needsImages = Boolean(resolved.task.imagePaths?.length) || resolved.task.subagentType === "browser-qa";
+	if (!registry && !needsImages) return resolved; // Narrow offline/test callers.
+	const candidates = [resolved.task.model, ...resolved.fallbackModels].filter((ref): ref is string => Boolean(ref));
+	let registeredAvailable: Set<string> | undefined;
+	try {
+		if (registry?.getAvailable) {
+			registeredAvailable = new Set(registry.getAvailable().map((model) => `${model.provider}/${model.id}`));
+		}
+	} catch {
+		throw new SubagentModelSelectionError(resolved.task.id, "Model runtime availability could not be read.");
+	}
+	const available: string[] = [];
+	for (const ref of candidates) {
+		if (signal?.aborted) throw new Error("Aborted");
+		if (registeredAvailable && !registeredAvailable.has(ref)) continue;
+		if (isSessionModelUnavailable(ref)) continue;
+		const slash = ref.indexOf("/");
+		if (slash <= 0) continue;
+		try {
+			const model = registry?.find(ref.slice(0, slash), ref.slice(slash + 1));
+			if (!model) continue;
+			if (needsImages && (isBlindModelRef(ref, config) || !model.input?.includes("image"))) continue;
+			if (registry?.getApiKeyAndHeaders && (await registry.getApiKeyAndHeaders(model)).ok === false) continue;
+		} catch {
+			// Auth errors may contain sensitive provider details; never echo them.
+			continue;
+		}
+		available.push(ref);
+	}
+	if (signal?.aborted) throw new Error("Aborted");
+	const [model, ...fallbackModels] = available;
+	if (!model) throw new SubagentModelSelectionError(resolved.task.id,
+		`No configured candidate is available${needsImages ? " with confirmed image support" : ""} in the model runtime.`);
+	return { ...resolved, task: { ...resolved.task, model }, fallbackModels };
+}

package/external/pi-tools-suite/src/async-subagents/core/prompt.ts

@@ -23,18 +23,19 @@ Scope and constraints:
 - Do not spawn other agents or background jobs unless explicitly allowed.
 ${scopeLine}${imageLine}- Follow the parent task's constraints and repository instructions.
 - Keep output compact by default.
+- Stay within the assigned scope and preserve unrelated work. Do not re-plan the project.
+- Report concrete blockers and gathered evidence rather than widening the task or escalating models yourself.
+- Keep noisy intermediate output in artifacts; return only decision-relevant evidence to the parent.
 - If the task explicitly asks for verbatim/raw file contents, command output, logs, or exact text, output only that content exactly and do not summarize it.
 - If requested raw content is very large, include the requested relevant portion and clearly say what was omitted.
 
 Output format:
 - If the task explicitly requests a raw/verbatim/exact output format, follow that request instead and do not add the standard summary sections below.
 - Otherwise use:
-  1. Summary, max 5 bullets
-  2. Evidence / files inspected, paths first
-  3. Recommended changes or patch plan
-  4. Files changed, if any
-  5. Tests/commands run, with short results
-  6. Risks / open questions
+  1. Result: answer or completion status, briefly.
+  2. Evidence: relevant file:line references, changed files, check results and artifact paths.
+  3. Limits: blockers, unverified assumptions, risks or necessary next action; omit when empty.
+- Do not repeat the task or paste full logs/diffs unless requested. Preserve required QA artifact links.
 `;
 
 	return task.promptAppend