Summary

• Problem: /model and sessions.patch could reject an explicitly allowlisted model when that model was absent from the bundled catalog (stale catalog case), and models.list could surface stale entries.
• Why it matters: users with valid agents.defaults.models entries could still hit model not allowed and get inconsistent picker/runtime behavior.
• What changed: buildAllowedModelSet now always trusts parseable explicit allowlist refs and synthesizes missing catalog entries for those refs so picker output and runtime checks stay aligned.
• What did NOT change (scope boundary): no provider auth flow changes, no schema changes, no default allowlist policy changes.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Fixes [Bug]: Model switching via /model command rejected despite valid allowlist config #20291
• Related Model configuration inconsistency - config accepts models that session_status rejects #10425

User-visible / Behavior Changes

• Explicitly configured agents.defaults.models refs can now be selected via /model even when bundled catalog entries lag behind model releases.
• models.list now includes synthetic entries for allowlisted refs absent from bundled catalog data.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22 / pnpm / vitest
• Model/provider: anthropic + openai
• Integration/channel (if any): Gateway RPC (models.list, sessions.patch)
• Relevant config (redacted): agents.defaults.models contains explicit ref missing from bundled catalog

Steps

1. Configure agents.defaults.models with anthropic/claude-sonnet-4-6.
2. Provide a runtime catalog that only contains anthropic/claude-sonnet-4-5.
3. Call sessions.patch with model=anthropic/claude-sonnet-4-6 and call models.list.

Expected

• sessions.patch accepts explicit allowlisted ref.
• models.list includes the allowlisted ref.

Actual

• Verified with new regressions: behavior now matches expected.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Tests run:

• pnpm test src/agents/model-selection.test.ts src/gateway/sessions-patch.test.ts src/gateway/server.models-voicewake-misc.test.ts
• pnpm format

Human Verification (required)

• Verified scenarios: stale-catalog explicit allowlist acceptance for resolveAllowedModelRef and sessions.patch; synthetic allowlist entry surfacing in models.list.
• Edge cases checked: existing catalog allowlist behavior remains unchanged; explicit allowlist entries still control selection set.
• What you did not verify: live external provider calls.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert this PR.
• Files/config to restore: src/agents/model-selection.ts and related tests/changelog entry.
• Known bad symptoms reviewers should watch for: unexpected synthetic model entries in models.list when allowlist keys are malformed (guarded by parseability checks).

Risks and Mitigations

• Risk: synthetic entries may show model IDs as names when no catalog metadata exists.
  • Mitigation: this is intentional fallback behavior and preserves correct selectable IDs over stale catalog labels.

Greptile Summary

Updated buildAllowedModelSet to honor explicitly allowlisted model refs even when bundled catalog is stale. Previously, sessions.patch and /model selection could reject valid allowlisted models absent from the catalog. Now synthesizes missing catalog entries for allowlisted refs to keep picker output and runtime checks aligned.

• Simplified allowlist logic: removed conditional checks (CLI provider, catalog presence, configured provider) and now always trusts parseable explicit allowlist entries
• Added synthetic catalog entry generation for missing models (uses model ID for both id and name fields)
• Updated models.list test expectation: now returns synthetic entries instead of falling back to full catalog
• Comprehensive test coverage for stale catalog scenarios in model-selection.test.ts, sessions-patch.test.ts, and server.models-voicewake-misc.test.ts

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Clean logic simplification with comprehensive test coverage. The change removes overly restrictive conditions and properly guards against malformed refs via parseModelRef validation. All three test files verify the new behavior (unit tests for buildAllowedModelSet and resolveAllowedModelRef, integration tests for sessions.patch and models.list). The fallback to model ID for synthetic entry names is intentional and documented. No breaking changes to existing behavior when catalog entries exist.
• No files require special attention

_{Last reviewed commit: 83fee5d}