fix(cliproxy): centralize gemini compatibility and fallback hints

src/cliproxy/config/thinking-config.ts

@@ -65,7 +65,7 @@ export function detectTierFromModel(modelName: string): ModelTier {
  *
  * @param model - Base model name
  * @param thinkingValue - Level name (e.g., 'high') or numeric budget
- * @returns Model name with thinking suffix, e.g., "gemini-3-pro-preview(high)"
+ * @returns Model name with thinking suffix, e.g., "gemini-3.1-pro-preview(high)"
  */
 export function applyThinkingSuffix(model: string, thinkingValue: string | number): string {
   return applyThinkingSuffixForProvider(model, thinkingValue);

src/cliproxy/executor/index.ts

@@ -34,7 +34,13 @@ import { DEFAULT_BACKEND } from '../platform-detector';
 import { configureProviderModel, getCurrentModel } from '../model-config';
 import { reconcileCodexModelForActivePlan } from '../codex-plan-compatibility';
 import { resolveProxyConfig, PROXY_CLI_FLAGS } from '../proxy-config-resolver';
-import { supportsModelConfig, isModelBroken, getModelIssueUrl, findModel } from '../model-catalog';
+import {
+  supportsModelConfig,
+  isModelBroken,
+  getModelIssueUrl,
+  findModel,
+  getSuggestedReplacementModel,
+} from '../model-catalog';
 import { CodexReasoningProxy } from '../codex-reasoning-proxy';
 import { ToolSanitizationProxy } from '../tool-sanitization-proxy';
 import {
@@ -714,9 +720,14 @@ export async function execClaudeWithCLIProxy(
     if (currentModel && isModelBroken(provider, currentModel)) {
       const modelEntry = findModel(provider, currentModel);
       const issueUrl = getModelIssueUrl(provider, currentModel);
+      const replacementModel = getSuggestedReplacementModel(provider, currentModel);
       console.error('');
       console.error(warn(`${modelEntry?.name || currentModel} has known issues with Claude Code`));
-      console.error('    Tool calls will fail. Use "gemini-3.1-pro-preview" instead.');
+      if (replacementModel) {
+        console.error(`    Tool calls will fail. Use "${replacementModel}" instead.`);
+      } else {
+        console.error('    Tool calls will fail. Consider changing the model in config.yaml.');
+      }
       if (issueUrl) {
         console.error(`    Tracking: ${issueUrl}`);
       }

src/cliproxy/model-catalog.ts

@@ -12,13 +12,7 @@ import {
   normalizeModelIdForProvider,
 } from './model-id-normalizer';
 import { stripModelConfigurationSuffixes } from '../shared/extended-context-utils';
-
-const GEMINI_MINOR_VERSION_COMPATIBILITY_IDS = Object.freeze({
-  'gemini-3-pro-preview': 'gemini-3.1-pro-preview',
-  'gemini-3.1-pro-preview': 'gemini-3-pro-preview',
-  'gemini-3-flash-preview': 'gemini-3.1-flash-preview',
-  'gemini-3.1-flash-preview': 'gemini-3-flash-preview',
-});
+import { GEMINI_MINOR_VERSION_COMPATIBILITY_IDS } from '../shared/gemini-minor-version-compatibility';
 
 /**
  * Thinking support configuration for a model.
@@ -391,6 +385,26 @@ export function getProviderCatalog(provider: CLIProxyProvider): ProviderCatalog
   return MODEL_CATALOG[provider];
 }
 
+/**
+ * Suggest a supported replacement model from the provider catalog.
+ * Prefers the provider default unless it matches the excluded model or is itself broken.
+ */
+export function getSuggestedReplacementModel(
+  provider: CLIProxyProvider,
+  excludedModelId?: string
+): string | undefined {
+  const catalog = MODEL_CATALOG[provider];
+  if (!catalog) return undefined;
+
+  const excludedId = excludedModelId ? findModel(provider, excludedModelId)?.id : undefined;
+  const defaultModel = findModel(provider, catalog.defaultModel);
+  if (defaultModel && !defaultModel.broken && defaultModel.id !== excludedId) {
+    return defaultModel.id;
+  }
+
+  return catalog.models.find((model) => !model.broken && model.id !== excludedId)?.id;
+}
+
 /**
  * Find model entry by ID
  * Note: Model IDs are normalized to lowercase for case-insensitive comparison

src/shared/gemini-minor-version-compatibility.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared Gemini preview aliases for minor-version rollouts.
+ * Keep CLIProxy backend and dashboard model resolution on the same compatibility pairs.
+ */
+export const GEMINI_MINOR_VERSION_COMPATIBILITY_IDS = Object.freeze({
+  'gemini-3-pro-preview': 'gemini-3.1-pro-preview',
+  'gemini-3.1-pro-preview': 'gemini-3-pro-preview',
+  'gemini-3-flash-preview': 'gemini-3.1-flash-preview',
+  'gemini-3.1-flash-preview': 'gemini-3-flash-preview',
+});