#21556: fix(agents): graceful fallback when spawned model is not in allowlist
agents
size: S
Cluster:
Model Management Enhancements
## Summary
When `sessions_spawn` is called with a `model` that is not in the agent's model allowlist, the current behavior hard-fails with `status: "error"`, making callers uncertain whether the task started. This leads to accidental duplicate spawns.
## Changes
- **Graceful fallback**: when `sessions.patch` rejects the model with "model not allowed" or "invalid model", the spawn continues with the default model instead of returning an error
- **Clear warning**: the response includes `warning: "model not allowed: ... — task will run with the default model instead"` so callers know what happened without re-spawning
- **Type update**: added `warning?: string` to `SpawnSubagentResult` to make the field part of the public contract
- **Tests**: added test coverage for the allowlist fallback path (status="accepted", modelApplied=false, warning present) and the hard-fail path (non-allowlist errors still return status="error")
## Behavior
| Scenario | Before | After |
|---|---|---|
| Model not in allowlist | `status: "error"` (task not started) | `status: "accepted"`, `modelApplied: false`, `warning: "..."` |
| Invalid model name | `status: "error"` | `status: "error"` (unchanged) |
| Model in allowlist | `status: "accepted"`, `modelApplied: true` | unchanged |
## Notes
- This aligns the git source with the behavior already shipped in the 2026.2.17 release build, adding the missing `warning` type field and improving the warning message clarity
- Callers should check `modelApplied` to confirm the requested model was applied; `warning` is present when it wasn't
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Implements graceful fallback when `sessions_spawn` is called with a model that's not in the allowlist. Previously, such calls would hard-fail with `status: "error"`, causing uncertainty about whether the task started and leading to duplicate spawns. Now, when the gateway rejects a model with "model not allowed" or "invalid model" errors, the spawn continues with the default model and returns `status: "accepted"` with `modelApplied: false` and a clear warning message.
- Added `warning?: string` field to `SpawnSubagentResult` type (src/agents/subagent-spawn.ts:52)
- Modified error handling in `spawnSubagentDirect` to detect allowlist-related errors and fall back gracefully (src/agents/subagent-spawn.ts:205-214)
- Updated tests to distinguish between allowlist errors (graceful fallback) and other errors (hard fail)
- Added comprehensive test coverage for both "model not allowed" and "invalid model" fallback scenarios
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with no identified risks
- The implementation is straightforward, well-tested, and follows existing patterns in the codebase. The string matching for error detection (`includes("model not allowed")` and `includes("invalid model")`) correctly aligns with the canonical error messages from `model-selection.ts`. The type change is additive and backwards-compatible. Test coverage is comprehensive, covering both fallback paths and the unchanged hard-fail path for non-allowlist errors.
- No files require special attention
<sub>Last reviewed commit: 29cca80</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#21088: fix: sessions_sspawn model override ignored for sub-agents
by Slats24 · 2026-02-19
84.7%
#9583: fix(models): allow models in agents.defaults.models even if not in ...
by hotzen100 · 2026-02-05
84.6%
#20712: fix(subagents): prioritize agent runtime default model over global ...
by sourcesavant · 2026-02-19
84.1%
#10608: fix(agents): honor spawn model override in gateway and session spaw...
by 1kuna · 2026-02-06
83.9%
#13376: fix: pass model directly to agent for sub-agent runs
by jrbobbyhansen-pixel · 2026-02-10
82.1%
#6603: fix: use allowAny flag instead of size check for model override val...
by gavinbmoore · 2026-02-01
81.7%
#11349: fix(agents): do not filter fallback models by models allowlist
by liuxiaopai-ai · 2026-02-07
81.7%
#11107: fix(models): auto-allow selected model on sessions.patch
by Mokoby · 2026-02-07
81.2%
#6673: fix: preserve allowAny flag in createModelSelectionState for custom...
by tenor0 · 2026-02-01
80.6%
#16838: fix: include configured fallbacks in model allowlist
by taw0002 · 2026-02-15
80.4%