pi-subagents 0.12.5 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-04-11
+
+### Added
+- Added native agent `fallbackModels` support. Agents can now declare ordered backup models, and single, chain, parallel, and async/background runs retry on provider/model-style failures such as quota, auth, timeout, or provider/model unavailability.
+
+### Fixed
+- Fallback attempts now preserve observability across sync and async execution: results, artifact metadata, async status, and run logs record attempted models and per-attempt outcomes instead of only the final pass.
+- Child subagent runs now pass model selections through `--model` instead of `--models`, so live execution pins the intended model correctly and end-to-end fallback behavior matches the validated test path.
+
 ## [0.12.5] - 2026-04-09
 
 ### Fixed

package/README.md

@@ -63,6 +63,7 @@ description: Fast codebase recon
 tools: read, grep, find, ls, bash, mcp:chrome-devtools  # mcp: requires pi-mcp-adapter
 extensions:                 # absent=all, empty=none, csv=allowlist
 model: claude-haiku-4-5
+fallbackModels: openai/gpt-5-mini, anthropic/claude-sonnet-4  # optional ordered fallbacks
 thinking: high               # off, minimal, low, medium, high, xhigh
 skill: safe-bash, chrome-devtools  # comma-separated skills to inject
 output: context.md           # writes to {chain_dir}/context.md
@@ -77,6 +78,12 @@ Your system prompt goes here (the markdown body after frontmatter).
 
 The `thinking` field sets a default extended thinking level for the agent. At runtime it's appended as a `:level` suffix to the model string (e.g., `claude-sonnet-4-5:high`). If the model already has a thinking suffix (from a chain-clarify override), the agent's default is not double-applied.
 
+`fallbackModels` is an optional ordered list of backup models to try when the primary model fails with a provider/model-style error such as quota, auth, timeout, or provider/model unavailable. In markdown frontmatter, declare it as a comma-separated string. In management `config` objects, you can pass either a comma-separated string or a string array.
+
+Fallback resolution follows the same conservative model lookup as normal execution. Explicit `provider/model` values are used as-is. Bare model IDs are only upgraded to a full `provider/model` when they map cleanly to a single registry entry. If a bare ID is ambiguous, it stays bare.
+
+Fallback is only used for provider/model availability failures. Ordinary task failures such as bad `bash` commands, missing files, or other tool/runtime errors do not trigger a model hop.
+
 **Extension sandboxing**
 
 Use `extensions` in frontmatter to control which extensions a subagent can access:
@@ -552,6 +559,7 @@ Agent definitions are not loaded into LLM context by default. Management actions
   scope: "user",
   systemPrompt: "You are a code scout...",
   model: "anthropic/claude-sonnet-4",
+  fallbackModels: ["openai/gpt-5-mini", "anthropic/claude-haiku-4-5"],
   tools: "read, bash, mcp:github/search_repositories",
   extensions: "", // empty = no extensions
   skills: "parallel-scout",
@@ -590,7 +598,7 @@ Agent definitions are not loaded into LLM context by default. Management actions
 Notes:
 - `create` uses `config.scope` (`"user"` or `"project"`), not `agentScope`.
 - `update`/`delete` use `agentScope` only for scope disambiguation when the same name exists in both scopes.
-- Agent config mapping: `reads -> defaultReads`, `progress -> defaultProgress`, `extensions` controls extension sandboxing, `maxSubagentDepth` maps directly to agent frontmatter, and `tools` supports `mcp:` entries that map to direct MCP tools.
+- Agent config mapping: `reads -> defaultReads`, `progress -> defaultProgress`, `extensions` controls extension sandboxing, `maxSubagentDepth` maps directly to agent frontmatter, `fallbackModels` maps directly to agent frontmatter, and `tools` supports `mcp:` entries that map to direct MCP tools.
 - To clear any optional field, set it to `false` or `""` (e.g., `{ model: false }` or `{ skills: "" }`). Both work for all string-typed fields.
 
 ## Parameters
@@ -601,10 +609,11 @@ Notes:
 | `task` | string | - | Task string (single mode) |
 | `action` | string | - | Management action: `list`, `get`, `create`, `update`, `delete` |
 | `chainName` | string | - | Chain name for management get/update/delete |
-| `config` | object | - | Agent or chain config for management create/update |
+| `config` | object | - | Agent or chain config for management create/update. Agent configs also accept `fallbackModels` (comma-separated string or string array). |
 | `output` | `string \| false` | agent default | Override output file for single agent (absolute path as-is, relative path resolved against cwd) |
 | `skill` | `string \| string[] \| false` | agent default | Override skills (comma-separated string, array, or false to disable) |
 | `model` | string | agent default | Override model for single agent |
+| `fallbackModels` | `string \| string[]` | agent default | Management/config-only field for ordered backup models. Markdown frontmatter uses a comma-separated string. |
 | `tasks` | `{agent, task, cwd?, count?, skill?}[]` | - | Parallel tasks. Foreground runs directly; background requests are converted to an equivalent chain. `count` repeats one task entry N times with the same settings. |
 | `worktree` | boolean | false | Create isolated git worktrees for each parallel task. Requires clean git state. Per-worktree diffs included in output. |
 | `chain` | ChainItem[] | - | Sequential steps with behavior overrides (see below) |
@@ -637,6 +646,8 @@ Notes:
 | `skill` | `string \| string[] \| false` | agent default | Override skills or disable all |
 | `model` | string | agent default | Override model for this step |
 
+Fallbacks are inherited from the selected agent for that step. There is no per-step `fallbackModels` override in v1.
+
 *Parallel step fields:*
 
 | Field | Type | Default | Description |
@@ -660,6 +671,8 @@ Notes:
 | `skill` | `string \| string[] \| false` | agent default | Override skills or disable all |
 | `model` | string | agent default | Override model for this task |
 
+Fallbacks are inherited from the selected agent for that task. There is no per-task `fallbackModels` override in v1.
+
 Status tool:
 
 | Tool | Description |
@@ -821,7 +834,9 @@ Files per task:
 - `{runId}_{agent}_input.md` - Task prompt
 - `{runId}_{agent}_output.md` - Full output (untruncated)
 - `{runId}_{agent}.jsonl` - Event stream (sync only)
-- `{runId}_{agent}_meta.json` - Timing, usage, exit code
+- `{runId}_{agent}_meta.json` - Timing, usage, exit code, final model, attempted models, and per-attempt outcomes
+
+When fallback is used, metadata records both the ordered `attemptedModels` list and `modelAttempts` entries with success/failure, exit code, error, and usage per attempt.
 
 ## Session Logs
 
@@ -904,6 +919,8 @@ Async runs write a dedicated observability folder:
 
 `status.json` is the source of truth for async progress and powers both the TUI widget and `/subagents-status`. Async status and result files are written atomically, so readers do not observe partial JSON during background updates.
 
+When fallback is used in async/background mode, `status.json` and the final result JSON include the final selected model, ordered attempted models, and per-attempt outcomes so background runs are as debuggable as sync runs.
+
 For programmatic access:
 
 ```typescript
@@ -934,7 +951,7 @@ Async events:
 ├── chain-serializer.ts           # Parse/serialize .chain.md files
 ├── async-execution.ts            # Async/background execution support
 ├── async-status.ts               # Async run discovery, listing, and formatting
-├── execution.ts                  # Core runSync, applyThinkingSuffix
+├── execution.ts                  # Core runSync and sync fallback handling
 ├── render.ts                     # TUI rendering (widget, tool result display)
 ├── subagents-status.ts           # Async status overlay component
 ├── artifacts.ts                  # Artifact management
@@ -942,6 +959,7 @@ Async events:
 ├── schemas.ts                    # TypeBox parameter schemas
 ├── utils.ts                      # Shared utility functions (mapConcurrent, readStatus, etc.)
 ├── types.ts                      # Shared types and constants
+├── model-fallback.ts             # Fallback candidate resolution and retry classification
 ├── subagent-runner.ts            # Async runner (detached process)
 ├── parallel-utils.ts             # Parallel execution utilities for async runner
 ├── worktree.ts                   # Git worktree isolation for parallel execution

package/agent-management.ts

@@ -130,6 +130,13 @@ function modelWarning(ctx: ManagementContext, model: string | undefined): string
 	return found ? undefined : `Warning: model '${model}' is not in the current model registry.`;
 }
 
+function fallbackModelsWarning(ctx: ManagementContext, fallbackModels: string[] | undefined): string | undefined {
+	if (!fallbackModels || fallbackModels.length === 0) return undefined;
+	const available = new Set(ctx.modelRegistry.getAvailable().flatMap((m) => [`${m.provider}/${m.id}`, m.id]));
+	const missing = fallbackModels.filter((model) => !available.has(model));
+	return missing.length ? `Warning: fallback models not in the current model registry: ${missing.join(", ")}.` : undefined;
+}
+
 function skillsWarning(cwd: string, skills: string[] | undefined): string | undefined {
 	if (!skills || skills.length === 0) return undefined;
 	const available = new Set(discoverAvailableSkills(cwd).map((s) => s.name));
@@ -198,6 +205,19 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		else if (typeof cfg.model === "string") target.model = cfg.model.trim() || undefined;
 		else return "config.model must be a string or false when provided.";
 	}
+	if (hasKey(cfg, "fallbackModels")) {
+		if (cfg.fallbackModels === false || cfg.fallbackModels === "") target.fallbackModels = undefined;
+		else if (typeof cfg.fallbackModels === "string") {
+			const models = parseCsv(cfg.fallbackModels);
+			target.fallbackModels = models.length ? models : undefined;
+		} else if (Array.isArray(cfg.fallbackModels)) {
+			const models = cfg.fallbackModels
+				.filter((value): value is string => typeof value === "string")
+				.map((value) => value.trim())
+				.filter(Boolean);
+			target.fallbackModels = models.length ? [...new Set(models)] : undefined;
+		} else return "config.fallbackModels must be a comma-separated string, string array, or false when provided.";
+	}
 	if (hasKey(cfg, "tools")) {
 		if (cfg.tools === false || cfg.tools === "") { target.tools = undefined; target.mcpDirectTools = undefined; }
 		else if (typeof cfg.tools === "string") { const parsed = parseTools(cfg.tools); target.tools = parsed.tools; target.mcpDirectTools = parsed.mcpDirectTools; }
@@ -292,6 +312,7 @@ export function formatAgentDetail(agent: AgentConfig): string {
 	const tools = [...(agent.tools ?? []), ...(agent.mcpDirectTools ?? []).map((t) => `mcp:${t}`)];
 	const lines: string[] = [`Agent: ${agent.name} (${agent.source})`, `Path: ${agent.filePath}`, `Description: ${agent.description}`];
 	if (agent.model) lines.push(`Model: ${agent.model}`);
+	if (agent.fallbackModels?.length) lines.push(`Fallback models: ${agent.fallbackModels.join(", ")}`);
 	if (tools.length) lines.push(`Tools: ${tools.join(", ")}`);
 	if (agent.skills?.length) lines.push(`Skills: ${agent.skills.join(", ")}`);
 	if (agent.extensions !== undefined) lines.push(`Extensions: ${agent.extensions.length ? agent.extensions.join(", ") : "(none)"}`);
@@ -395,6 +416,8 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	if (applyError) return result(applyError, true);
 	const mw = modelWarning(ctx, agent.model);
 	if (mw) warnings.push(mw);
+	const fmw = fallbackModelsWarning(ctx, agent.fallbackModels);
+	if (fmw) warnings.push(fmw);
 	const sw = skillsWarning(ctx.cwd, agent.skills);
 	if (sw) warnings.push(sw);
 	fs.writeFileSync(targetPath, serializeAgent(agent), "utf-8");
@@ -431,6 +454,10 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 			const mw = modelWarning(ctx, updated.model);
 			if (mw) warnings.push(mw);
 		}
+		if (hasKey(cfg, "fallbackModels")) {
+			const fmw = fallbackModelsWarning(ctx, updated.fallbackModels);
+			if (fmw) warnings.push(fmw);
+		}
 		if (hasKey(cfg, "skills")) {
 			const sw = skillsWarning(ctx.cwd, updated.skills);
 			if (sw) warnings.push(sw);

package/agent-manager-edit.ts

@@ -16,7 +16,7 @@ export interface EditState {
 export interface EditInputResult { action?: "save" | "discard"; nextScreen?: EditScreen; }
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
-const FIELD_ORDER = ["name", "description", "model", "thinking", "tools", "extensions", "skills", "output", "reads", "progress", "interactive", "prompt"] as const;
+const FIELD_ORDER = ["name", "description", "model", "fallbackModels", "thinking", "tools", "extensions", "skills", "output", "reads", "progress", "interactive", "prompt"] as const;
 type EditField = typeof FIELD_ORDER[number];
 type ThinkingLevel = typeof THINKING_LEVELS[number];
 const PROMPT_VIEWPORT_HEIGHT = 16;
@@ -29,7 +29,7 @@ function parseCommaList(value: string): string[] | undefined { const items = val
 
 export function createEditState(draft: AgentConfig, isNew: boolean, models: ModelInfo[], skills: SkillInfo[]): EditState {
 	return {
-		draft: { ...draft, tools: draft.tools ? [...draft.tools] : undefined, mcpDirectTools: draft.mcpDirectTools ? [...draft.mcpDirectTools] : undefined, skills: draft.skills ? [...draft.skills] : undefined, extensions: draft.extensions ? [...draft.extensions] : draft.extensions, defaultReads: draft.defaultReads ? [...draft.defaultReads] : undefined, extraFields: draft.extraFields ? { ...draft.extraFields } : undefined },
+		draft: { ...draft, tools: draft.tools ? [...draft.tools] : undefined, mcpDirectTools: draft.mcpDirectTools ? [...draft.mcpDirectTools] : undefined, skills: draft.skills ? [...draft.skills] : undefined, fallbackModels: draft.fallbackModels ? [...draft.fallbackModels] : undefined, extensions: draft.extensions ? [...draft.extensions] : draft.extensions, defaultReads: draft.defaultReads ? [...draft.defaultReads] : undefined, extraFields: draft.extraFields ? { ...draft.extraFields } : undefined },
 		isNew, fieldIndex: 0, fieldMode: null, fieldEditor: createEditorState(), promptEditor: createEditorState(draft.systemPrompt ?? ""),
 		modelSearchQuery: "", modelCursor: 0, filteredModels: [...models], thinkingCursor: 0, skillSearchQuery: "", skillCursor: 0, filteredSkills: [...skills], skillSelected: new Set(draft.skills ?? []),
 	};
@@ -41,6 +41,7 @@ function renderFieldValue(field: EditField, state: EditState): string {
 		case "name": return draft.name;
 		case "description": return draft.description;
 		case "model": return draft.model ?? "default";
+		case "fallbackModels": return draft.fallbackModels && draft.fallbackModels.length > 0 ? draft.fallbackModels.join(", ") : "";
 		case "thinking": return draft.thinking ?? "off";
 		case "tools": return formatTools(draft);
 		case "extensions": return draft.extensions !== undefined ? (draft.extensions.length > 0 ? draft.extensions.join(", ") : "") : "(all)";
@@ -59,6 +60,7 @@ function applyFieldValue(field: EditField, state: EditState, value: string): voi
 		case "name": draft.name = value.trim(); break;
 		case "description": draft.description = value.trim(); break;
 		case "model": draft.model = value.trim() || undefined; break;
+		case "fallbackModels": draft.fallbackModels = parseCommaList(value); break;
 		case "tools": { const parsed = parseTools(value); draft.tools = parsed.tools; draft.mcpDirectTools = parsed.mcp; break; }
 		case "extensions": { const trimmed = value.trim(); draft.extensions = trimmed === "(all)" ? undefined : parseCommaList(trimmed) ?? []; break; }
 		case "skills": draft.skills = parseCommaList(value); break;

package/agent-serializer.ts

@@ -6,6 +6,7 @@ export const KNOWN_FIELDS = new Set([
 	"description",
 	"tools",
 	"model",
+	"fallbackModels",
 	"thinking",
 	"skill",
 	"skills",
@@ -36,6 +37,8 @@ export function serializeAgent(config: AgentConfig): string {
 	if (toolsValue) lines.push(`tools: ${toolsValue}`);
 
 	if (config.model) lines.push(`model: ${config.model}`);
+	const fallbackModelsValue = joinComma(config.fallbackModels);
+	if (fallbackModelsValue) lines.push(`fallbackModels: ${fallbackModelsValue}`);
 	if (config.thinking && config.thinking !== "off") lines.push(`thinking: ${config.thinking}`);
 
 	const skillsValue = joinComma(config.skills);

package/agents.ts

@@ -21,6 +21,7 @@ export interface AgentConfig {
 	tools?: string[];
 	mcpDirectTools?: string[];
 	model?: string;
+	fallbackModels?: string[];
 	thinking?: string;
 	systemPrompt: string;
 	source: AgentSource;
@@ -121,6 +122,10 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			?.split(",")
 			.map((s) => s.trim())
 			.filter(Boolean);
+		const fallbackModels = frontmatter.fallbackModels
+			?.split(",")
+			.map((model) => model.trim())
+			.filter(Boolean);
 
 		let extensions: string[] | undefined;
 		if (frontmatter.extensions !== undefined) {
@@ -143,6 +148,7 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			tools: tools.length > 0 ? tools : undefined,
 			mcpDirectTools: mcpDirectTools.length > 0 ? mcpDirectTools : undefined,
 			model: frontmatter.model,
+			fallbackModels: fallbackModels && fallbackModels.length > 0 ? fallbackModels : undefined,
 			thinking: frontmatter.thinking,
 			systemPrompt: body,
 			source,

package/async-execution.ts

@@ -16,6 +16,7 @@ import { isParallelStep, resolveStepBehavior, type ChainStep, type SequentialSte
 import type { RunnerStep } from "./parallel-utils.ts";
 import { resolvePiPackageRoot } from "./pi-spawn.ts";
 import { buildSkillInjection, normalizeSkillInput, resolveSkills } from "./skills.ts";
+import { buildModelCandidates, resolveModelCandidate, type AvailableModelInfo } from "./model-fallback.ts";
 import {
 	type ArtifactConfig,
 	type Details,
@@ -58,6 +59,7 @@ export interface AsyncChainParams {
 	chain: ChainStep[];
 	agents: AgentConfig[];
 	ctx: AsyncExecutionContext;
+	availableModels?: AvailableModelInfo[];
 	cwd?: string;
 	maxOutput?: MaxOutputConfig;
 	artifactsDir?: string;
@@ -85,6 +87,8 @@ export interface AsyncSingleParams {
 	sessionFile?: string;
 	skills?: string[];
 	output?: string | false;
+	modelOverride?: string;
+	availableModels?: AvailableModelInfo[];
 	maxSubagentDepth: number;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
@@ -146,6 +150,7 @@ export function executeAsyncChain(
 		worktreeSetupHookTimeoutMs,
 	} = params;
 	const chainSkills = params.chainSkills ?? [];
+	const availableModels = params.availableModels;
 
 	// Validate all agents exist before building steps
 	for (const s of chain) {
@@ -195,11 +200,15 @@ export function executeAsyncChain(
 		const outputPath = resolveSingleOutputPath(s.output, ctx.cwd, s.cwd ?? cwd);
 		const task = injectSingleOutputInstruction(s.task ?? "{previous}", outputPath);
 
+		const primaryModel = resolveModelCandidate(s.model ?? a.model, availableModels);
 		return {
 			agent: s.agent,
 			task,
 			cwd: s.cwd,
-			model: applyThinkingSuffix(s.model ?? a.model, a.thinking),
+			model: applyThinkingSuffix(primaryModel, a.thinking),
+			modelCandidates: buildModelCandidates(s.model ?? a.model, a.fallbackModels, availableModels).map((candidate) =>
+				applyThinkingSuffix(candidate, a.thinking),
+			),
 			tools: a.tools,
 			extensions: a.extensions,
 			mcpDirectTools: a.mcpDirectTools,
@@ -319,6 +328,7 @@ export function executeAsyncSingle(
 		worktreeSetupHookTimeoutMs,
 	} = params;
 	const skillNames = params.skills ?? agentConfig.skills ?? [];
+	const availableModels = params.availableModels;
 	const { resolved: resolvedSkills } = resolveSkills(skillNames, ctx.cwd);
 	let systemPrompt = agentConfig.systemPrompt?.trim() || null;
 	if (resolvedSkills.length > 0) {
@@ -349,7 +359,10 @@ export function executeAsyncSingle(
 					agent,
 					task: taskWithOutputInstruction,
 					cwd,
-					model: applyThinkingSuffix(agentConfig.model, agentConfig.thinking),
+					model: applyThinkingSuffix(resolveModelCandidate(params.modelOverride ?? agentConfig.model, availableModels), agentConfig.thinking),
+					modelCandidates: buildModelCandidates(params.modelOverride ?? agentConfig.model, agentConfig.fallbackModels, availableModels).map((candidate) =>
+						applyThinkingSuffix(candidate, agentConfig.thinking),
+					),
 					tools: agentConfig.tools,
 					extensions: agentConfig.extensions,
 					mcpDirectTools: agentConfig.mcpDirectTools,

package/async-status.ts

@@ -11,6 +11,9 @@ export interface AsyncRunStepSummary {
 	durationMs?: number;
 	tokens?: TokenUsage;
 	skills?: string[];
+	model?: string;
+	attemptedModels?: string[];
+	error?: string;
 }
 
 export interface AsyncRunSummary {
@@ -81,6 +84,9 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 			...(step.durationMs !== undefined ? { durationMs: step.durationMs } : {}),
 			...(step.tokens ? { tokens: step.tokens } : {}),
 			...(step.skills ? { skills: step.skills } : {}),
+			...(step.model ? { model: step.model } : {}),
+			...(step.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
+			...(step.error ? { error: step.error } : {}),
 		})),
 		...(status.sessionDir ? { sessionDir: status.sessionDir } : {}),
 		...(status.outputFile ? { outputFile: status.outputFile } : {}),
@@ -147,6 +153,7 @@ export function listAsyncRunsForOverlay(asyncDirRoot: string, recentLimit = 5):
 
 function formatStepLine(step: AsyncRunStepSummary): string {
 	const parts = [`${step.index + 1}. ${step.agent}`, step.status];
+	if (step.model) parts.push(step.model);
 	if (step.durationMs !== undefined) parts.push(formatDuration(step.durationMs));
 	if (step.tokens) parts.push(`${formatTokens(step.tokens.total)} tok`);
 	return parts.join(" | ");

package/chain-execution.ts

@@ -48,23 +48,7 @@ import {
 	MAX_CONCURRENCY,
 	resolveChildMaxSubagentDepth,
 } from "./types.ts";
-
-/** Resolve a model name to its full provider/model format */
-function resolveModelFullId(modelName: string | undefined, availableModels: ModelInfo[]): string | undefined {
-	if (!modelName) return undefined;
-	if (modelName.includes("/")) return modelName;
-
-	const colonIdx = modelName.lastIndexOf(":");
-	const baseModel = colonIdx !== -1 ? modelName.substring(0, colonIdx) : modelName;
-	const thinkingSuffix = colonIdx !== -1 ? modelName.substring(colonIdx) : "";
-
-	const match = availableModels.find((m) => m.id === baseModel);
-	if (match) {
-		return thinkingSuffix ? `${match.fullId}${thinkingSuffix}` : match.fullId;
-	}
-
-	return modelName;
-}
+import { resolveModelCandidate } from "./model-fallback.ts";
 
 interface ChainExecutionDetailsInput {
 	results: SingleResult[];
@@ -191,8 +175,8 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 
 			const taskAgentConfig = input.agents.find((agent) => agent.name === task.agent);
 			const effectiveModel =
-				(task.model ? resolveModelFullId(task.model, input.availableModels) : null)
-				?? resolveModelFullId(taskAgentConfig?.model, input.availableModels);
+				(task.model ? resolveModelCandidate(task.model, input.availableModels) : null)
+				?? resolveModelCandidate(taskAgentConfig?.model, input.availableModels);
 			const maxSubagentDepth = resolveChildMaxSubagentDepth(input.maxSubagentDepth, taskAgentConfig?.maxSubagentDepth);
 
 			const taskCwd = input.worktreeSetup
@@ -216,6 +200,7 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				outputPath,
 				maxSubagentDepth,
 				modelOverride: effectiveModel,
+				availableModels: input.availableModels,
 				skills: behavior.skills === false ? [] : behavior.skills,
 				onUpdate: input.onUpdate
 					? (progressUpdate) => {
@@ -643,8 +628,8 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			// Resolve model: TUI override (already full format) or agent's model resolved to full format
 			const effectiveModel =
 				tuiOverride?.model
-				?? (seqStep.model ? resolveModelFullId(seqStep.model, availableModels) : null)
-				?? resolveModelFullId(agentConfig.model, availableModels);
+				?? (seqStep.model ? resolveModelCandidate(seqStep.model, availableModels) : null)
+				?? resolveModelCandidate(agentConfig.model, availableModels);
 
 			// Run step
 			const outputPath = typeof behavior.output === "string"
@@ -665,6 +650,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				outputPath,
 				maxSubagentDepth,
 				modelOverride: effectiveModel,
+				availableModels,
 				skills: behavior.skills === false ? [] : behavior.skills,
 				onUpdate: onUpdate
 					? (p) => {