fix: respect explicit model selection after Flash quota exhaustion (#26759)

[cocosheng-g]

Summary

Fixes issue #26759 where explicit model selection (e.g., Pro) was being ignored once the Flash quota was exhausted. This ensures that the CLI correctly honors user intent and provides high availability by falling back between capable models in the same family.

Details

• Surgical Prefix Normalization: Introduced normalizeModelId utility to strip the models/ prefix from model IDs. ModelAvailabilityService now normalizes all incoming model IDs, ensuring robust identification and health tracking without modifying sensitive config files.
• Gemini 3 Family-Based Policy Wrapping: Updated policyHelpers.ts to enable wrapsAround: true for all Gemini 3 family models. This allows the availability service to automatically resolve a fallback to Pro if Flash is exhausted (and vice-versa), even when a concrete model was requested by a tool or subagent.
• Proactive Router Guardrails: Updated ClassifierStrategy and NumericalClassifierStrategy to check model availability before returning a routing decision. If a strategy selects a model that is currently exhausted, it will now return null (bypass), allowing the router to fall back to the user's default/active model.

Related Issues

Fixes #26759

How to Validate

1. Run the core tests: npm test -w @google/gemini-cli-core
2. Comprehensive unit tests are integrated into:
   • packages/core/src/availability/modelAvailabilityService.test.ts (Prefix normalization verification)
   • packages/core/src/availability/policyHelpers.test.ts
   • packages/core/src/routing/strategies/classifierStrategy.test.ts
   • packages/core/src/routing/strategies/numericalClassifierStrategy.test.ts
   • packages/core/src/utils/modelUtils.test.ts
3. Manually verify by setting a model to Pro and simulating a Flash quota error.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed) - Integrated comprehensive test cases.
• Noted breaking changes (if any) - None.
• Validated on required platforms/methods:
  • MacOS
    • npm run

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses issue #26759, where explicit model selections were being ignored or failing during periods of quota exhaustion. By implementing family-based policy wrapping and adding proactive availability checks to the routing strategies, the CLI now gracefully falls back to available models within the same family, improving overall system reliability and honoring user intent.

Highlights

• Family-Based Policy Wrapping: Modified resolvePolicyChain to enable wrapsAround: true for all Gemini family models, ensuring automatic fallback between models (e.g., Pro to Flash and vice-versa) even when a specific model is requested.
• Proactive Router Guardrails: Updated ClassifierStrategy and NumericalClassifierStrategy to verify model availability before finalizing routing decisions, bypassing exhausted models to allow for fallback.
• Regression Testing: Added a comprehensive regression test suite (modelAvailability_issue_26759.regression.test.ts) and design documentation to validate fallback behavior under various quota exhaustion scenarios.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

Size Change: +1.25 kB (0%)

Total Size: 34.1 MB

Filename	Size	Change
./bundle/chunk-3EMWKGQ6.js	0 B	-2.78 MB (removed)	🏆
./bundle/chunk-6TTDYQ6W.js	0 B	-3.8 kB (removed)	🏆
./bundle/chunk-H2XGOH7V.js	0 B	-49.2 kB (removed)	🏆
./bundle/chunk-OSQ5NGGX.js	0 B	-658 kB (removed)	🏆
./bundle/chunk-PYOR3ITL.js	0 B	-19.5 kB (removed)	🏆
./bundle/chunk-QTB23IKC.js	0 B	-1.97 MB (removed)	🏆
./bundle/chunk-T5X2XNZY.js	0 B	-3.43 kB (removed)	🏆
./bundle/chunk-VO52C4HA.js	0 B	-12.5 kB (removed)	🏆
./bundle/chunk-WQRAKLLK.js	0 B	-14.8 MB (removed)	🏆
./bundle/core-7TZM6XMY.js	0 B	-49.2 kB (removed)	🏆
./bundle/devtoolsService-3VTHYNYX.js	0 B	-28 kB (removed)	🏆
./bundle/gemini-RZXVHWHV.js	0 B	-587 kB (removed)	🏆
./bundle/interactiveCli-CF6M6CS7.js	0 B	-1.3 MB (removed)	🏆
./bundle/liteRtServerManager-5VB3YUVB.js	0 B	-2.11 kB (removed)	🏆
./bundle/oauth2-provider-BUQWNQ2B.js	0 B	-9.16 kB (removed)	🏆
./bundle/chunk-6NNHMYAM.js	1.97 MB	+1.97 MB (new file)	🆕
./bundle/chunk-EIHEEWLJ.js	14.8 MB	+14.8 MB (new file)	🆕
./bundle/chunk-HLQQPXML.js	49.2 kB	+49.2 kB (new file)	🆕
./bundle/chunk-JPHWXDFW.js	3.8 kB	+3.8 kB (new file)	🆕
./bundle/chunk-N3C6AHKG.js	12.5 kB	+12.5 kB (new file)	🆕
./bundle/chunk-ONNY5KPS.js	658 kB	+658 kB (new file)	🆕
./bundle/chunk-RUA4FLDM.js	3.43 kB	+3.43 kB (new file)	🆕
./bundle/chunk-TQJW2L7L.js	2.78 MB	+2.78 MB (new file)	🆕
./bundle/chunk-ZXXBDUH2.js	19.5 kB	+19.5 kB (new file)	🆕
./bundle/core-EESGKC4H.js	49.2 kB	+49.2 kB (new file)	🆕
./bundle/devtoolsService-DFMUHAPN.js	28 kB	+28 kB (new file)	🆕
./bundle/gemini-MEQWHONP.js	587 kB	+587 kB (new file)	🆕
./bundle/interactiveCli-EIAXR7VM.js	1.3 MB	+1.3 MB (new file)	🆕
./bundle/liteRtServerManager-257XAHUG.js	2.11 kB	+2.11 kB (new file)	🆕
./bundle/oauth2-provider-KMJ3HLHP.js	9.16 kB	+9.16 kB (new file)	🆕

ℹ️ View Unchanged

Filename	Size	Change
./bundle/bundled/third_party/index.js	8 MB	0 B
./bundle/chunk-34MYV7JD.js	2.45 kB	0 B
./bundle/chunk-5AUYMPVF.js	858 B	0 B
./bundle/chunk-5PS3AYFU.js	1.18 kB	0 B
./bundle/chunk-664ZODQF.js	124 kB	0 B
./bundle/chunk-DAHVX5MI.js	206 kB	0 B
./bundle/chunk-IUUIT4SU.js	56.5 kB	0 B
./bundle/chunk-RJTRUG2J.js	39.8 kB	0 B
./bundle/cleanup-SMM2TVVK.js	0 B	-932 B (removed)	🏆
./bundle/devtools-36NN55EP.js	696 kB	0 B
./bundle/dist-T73EYRDX.js	356 B	0 B
./bundle/events-XB7DADIJ.js	418 B	0 B
./bundle/examples/hooks/scripts/on-start.js	188 B	0 B
./bundle/examples/mcp-server/example.js	1.43 kB	0 B
./bundle/gemini.js	5.1 kB	0 B
./bundle/getMachineId-bsd-TXG52NKR.js	1.55 kB	0 B
./bundle/getMachineId-darwin-7OE4DDZ6.js	1.55 kB	0 B
./bundle/getMachineId-linux-SHIFKOOX.js	1.34 kB	0 B
./bundle/getMachineId-unsupported-5U5DOEYY.js	1.06 kB	0 B
./bundle/getMachineId-win-6KLLGOI4.js	1.72 kB	0 B
./bundle/memoryDiscovery-PTF4YLMR.js	0 B	-980 B (removed)	🏆
./bundle/multipart-parser-KPBZEGQU.js	11.7 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	222 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	229 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	13.4 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B	0 B
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B
./bundle/sandbox-macos-strict-open.sb	4.82 kB	0 B
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB	0 B
./bundle/src-QVCVGIUX.js	47 kB	0 B
./bundle/start-7ZGAOCEP.js	0 B	-652 B (removed)	🏆
./bundle/tree-sitter-7U6MW5PS.js	274 kB	0 B
./bundle/tree-sitter-bash-34ZGLXVX.js	1.84 MB	0 B
./bundle/cleanup-NVNG5YGS.js	932 B	+932 B (new file)	🆕
./bundle/memoryDiscovery-QGLPGQCK.js	980 B	+980 B (new file)	🆕
./bundle/start-A5LIOBVK.js	652 B	+652 B (new file)	🆕

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive regression testing strategy and implementation for model availability and routing robustness. Key changes include the addition of a regression design document and a new test suite covering exhaustion scenarios, such as ensuring explicit model selections are honored and tools correctly fall back within a model family. The core logic in resolvePolicyChain was updated to ensure family-based fallback is always active for Gemini 2 and 3 models. Furthermore, both ClassifierStrategy and NumericalClassifierStrategy now proactively verify model availability, bypassing selection if a model is marked as exhausted. I have no feedback to provide as there were no review comments to assess.

[cocosheng-g]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces model ID normalization by stripping the 'models/' prefix to ensure consistent behavior across the availability service and routing strategies. It also implements mandatory wrap-around logic for Gemini 3 models to improve fallback availability. Feedback focused on ensuring that model IDs are normalized within policyHelpers.ts before being passed to family checks and slicing functions to prevent potential identification failures.

[cocosheng-g]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces model ID normalization by stripping the 'models/' prefix across core availability and routing services to ensure consistent internal logic. The changes include a new utility function, updates to the ModelAvailabilityService, and integration into the classifier strategies. The review feedback correctly identifies high-severity issues where normalization might break existing strict equality checks against hardcoded values in the policy catalog, specifically within functions like isGemini3Model and applyDynamicSlicing. These inconsistencies could lead to failed model lookups and disabled fallback logic.

[cocosheng-g]

/gemini review

[gemini-code-assist]

Code Review

This pull request implements model ID normalization by stripping the "models/" prefix across the availability and routing services to ensure consistent internal logic. Changes include a new normalizeModelId utility, its application in ModelAvailabilityService and classifier strategies, and updated wrap-around logic for Gemini 3 models. A review comment identifies that the normalization in resolvePolicyChain is incomplete and suggests centralizing the normalization of model IDs at the start of the function to avoid fragile comparisons and repetitive calls.

[cocosheng-g]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a normalizeModelId utility to strip the models/ prefix from model identifiers, ensuring consistent behavior across availability checks, policy resolution, and routing. The ModelAvailabilityService and policyHelpers were updated to use this normalization, and routing strategies now verify model availability before selection. Review feedback identifies two instances in the classifier strategies where the input model ID should be normalized before being passed to resolveClassifierModel to prevent failures in internal equality checks.

[cocosheng-g]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces model ID normalization across the core package to consistently handle the "models/" prefix, ensuring internal logic like family matching and availability checks work correctly regardless of the input format. Key changes include the addition of a normalizeModelId utility, updates to ModelAvailabilityService and resolvePolicyChain to use normalized IDs, and a new availability check in routing strategies to bypass unavailable models selected by classifiers. Additionally, Gemini 3 model chains now default to wrapping around for improved fallback availability. I have no feedback to provide.