converse-mcp-server 3.4.0 → 3.5.0

package/README.md

@@ -267,7 +267,7 @@ Reasoning maps to `high` (enabled) or `none` (disabled) on Medium 3.5 and Small;
 - **deepseek-v4-pro** (default; aliases: `deepseek`, `deepseek-pro`): Flagship MoE model with thinking mode (1M context, 384K max output, text-only)
 - **deepseek-v4-flash** (alias: `deepseek-flash`): Faster, lower-cost V4 tier with thinking mode (1M context, 384K max output, text-only)
 
-Thinking mode maps `reasoning_effort` to `none` (off), `high` (enabled levels), or `max`.
+Thinking mode maps `reasoning_effort` to `none` (off), `high` (enabled levels up to `high`), or `max` (`xhigh` and `max`).
 
 ### OpenRouter Models
 

package/docs/API.md

@@ -84,8 +84,8 @@ MCP_TRANSPORT=stdio npm start
     },
     "reasoning_effort": {
       "type": "string",
-      "enum": ["none", "minimal", "low", "medium", "high", "max"],
-      "description": "Reasoning depth for thinking models. 'none' (fastest, GPT-5.1+ only), 'minimal', 'low', 'medium' (balanced), 'high', 'max'. Default: 'medium'."
+      "enum": ["none", "minimal", "low", "medium", "high", "xhigh", "max"],
+      "description": "Reasoning depth for thinking models, weakest to strongest. Passed through by name when the model accepts it, otherwise clamped to the nearest tier it does. Default: 'medium'."
     },
     "async": {
       "type": "boolean",
@@ -404,7 +404,7 @@ Provide models as plain name strings in the `models` array. Bare names and alias
 |-------|---------|---------|-------|
 | `grok-4.5` | `grok`, `grok-4.5-latest`, `grok-build-latest` | 500K | Flagship: image input, reasoning content, native web/X search via Agent Tools |
 
-`reasoning_effort` maps to Grok's `low`/`medium`/`high`; Grok 4.5 always reasons and cannot be disabled. Web search is attached automatically and the model decides whether to use it.
+`reasoning_effort` clamps into Grok's `low`/`medium`/`high` (`xhigh` and `max` become `high`); Grok 4.5 always reasons and cannot be disabled. Web search is attached automatically and the model decides whether to use it.
 
 ### Anthropic Models (API-based)
 
@@ -417,7 +417,7 @@ Provide models as plain name strings in the `models` array. Bare names and alias
 | `claude-sonnet-4-6` | `sonnet`, `sonnet-4.6` | 200K (1M beta) | 64K | Best speed/intelligence balance, adaptive thinking |
 | `claude-haiku-4-5-20251001` | `haiku`, `haiku-4.5` | 200K | 64K | Fast and intelligent |
 
-Models with adaptive thinking control depth via `reasoning_effort`, which maps to Anthropic's `effort` parameter. System prompts are automatically cached for 1 hour; cache stats appear in response metadata as `cache_creation_input_tokens` / `cache_read_input_tokens`.
+Models with adaptive thinking control depth via `reasoning_effort`, which is passed by name to Anthropic's `effort` parameter and clamped to what each model accepts: Fable 5, Opus 5, Opus 4.8, and Opus 4.7 take `low`–`max`; Opus 4.6 and Sonnet 4.6 lack `xhigh` (it becomes `max`); Opus 4.5 tops out at `high`. `none` and `minimal` become `low` everywhere. System prompts are automatically cached for 1 hour; cache stats appear in response metadata as `cache_creation_input_tokens` / `cache_read_input_tokens`.
 
 ### Mistral Models
 
@@ -436,7 +436,7 @@ Models with adaptive thinking control depth via `reasoning_effort`, which maps t
 | `deepseek-v4-pro` | `deepseek`, `deepseek-pro` | 1M | 384K | Flagship MoE, thinking mode, text-only |
 | `deepseek-v4-flash` | `deepseek-flash` | 1M | 384K | Faster, lower-cost V4 tier, text-only |
 
-`reasoning_effort`: `none` disables thinking; enabled levels use `high`; `max` uses `max`.
+`reasoning_effort`: `none` disables thinking; enabled levels up to `high` use `high`; `xhigh` and `max` use `max`.
 
 ### OpenRouter Models
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "converse-mcp-server",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Converse MCP Server - Converse with other LLMs with chat and consensus tools",
   "type": "module",
   "main": "src/index.js",

package/src/prompts/helpPrompt.js

@@ -295,11 +295,12 @@ function generateConfigurationTips(tools) {
     if (effortSchema.enum) {
       for (const value of effortSchema.enum) {
         const descriptions = {
-          none: 'No reasoning, fastest response (GPT-5.1+ only)',
+          none: 'Reasoning off, fastest response (where the model allows it)',
           minimal: 'Quick responses with minimal reasoning',
           low: 'Light analysis, simple problems',
           medium: 'Balanced reasoning (default)',
           high: 'Deep analysis, complex problems',
+          xhigh: 'Very deep analysis, one step below the ceiling',
           max: 'Maximum reasoning capability',
         };
         output += `- **${value}**: ${descriptions[value] || value}\n`;

package/src/providers/anthropic.js

@@ -10,6 +10,14 @@
 
 import { debugLog, debugError } from '../utils/console.js';
 import { ProviderError, ErrorCodes, StopReasons } from './interface.js';
+import { clampReasoningEffort } from '../utils/reasoningEffort.js';
+
+// Values each model accepts for the `effort` parameter. Anthropic cannot
+// switch reasoning off via effort, so 'none' and 'minimal' clamp up to 'low'.
+// Not every model that supports 'max' supports 'xhigh'.
+const EFFORT_TIERS_FULL = ['low', 'medium', 'high', 'xhigh', 'max'];
+const EFFORT_TIERS_NO_XHIGH = ['low', 'medium', 'high', 'max'];
+const EFFORT_TIERS_LEGACY = ['low', 'medium', 'high'];
 
 // Define supported Claude models with their capabilities
 const SUPPORTED_MODELS = {
@@ -26,6 +34,7 @@ const SUPPORTED_MODELS = {
     timeout: 1800000,
     supportsEffort: true,
     effortGA: true,
+    effortTiers: EFFORT_TIERS_FULL,
     supportsCompaction: true,
     description:
       'Claude Fable 5 - Most capable model for the most demanding reasoning and long-horizon agentic work',
@@ -51,6 +60,7 @@ const SUPPORTED_MODELS = {
     timeout: 1800000,
     supportsEffort: true,
     effortGA: true,
+    effortTiers: EFFORT_TIERS_FULL,
     supportsCompaction: true,
     description:
       'Claude Opus 5 - Most capable Opus for complex agentic coding and deep reasoning',
@@ -79,6 +89,7 @@ const SUPPORTED_MODELS = {
     timeout: 1800000,
     supportsEffort: true,
     effortGA: true,
+    effortTiers: EFFORT_TIERS_FULL,
     supports1MContext: true,
     supportsCompaction: true,
     description:
@@ -109,6 +120,7 @@ const SUPPORTED_MODELS = {
     timeout: 1800000,
     supportsEffort: true,
     effortGA: true,
+    effortTiers: EFFORT_TIERS_FULL,
     supports1MContext: true,
     supportsCompaction: true,
     description:
@@ -139,6 +151,7 @@ const SUPPORTED_MODELS = {
     timeout: 1800000,
     supportsEffort: true,
     effortGA: true,
+    effortTiers: EFFORT_TIERS_NO_XHIGH,
     supports1MContext: true,
     supportsCompaction: true,
     description:
@@ -167,6 +180,7 @@ const SUPPORTED_MODELS = {
     maxThinkingTokens: 64000,
     timeout: 900000,
     supportsEffort: true, // Opus 4.5 effort parameter (requires beta header)
+    effortTiers: EFFORT_TIERS_LEGACY,
     description:
       'Claude Opus 4.5 - Previous most intelligent model combining maximum capability with practical performance',
     aliases: [
@@ -223,6 +237,7 @@ const SUPPORTED_MODELS = {
     timeout: 900000,
     supportsEffort: true,
     effortGA: true, // Effort is generally available, no beta header required
+    effortTiers: EFFORT_TIERS_NO_XHIGH,
     supports1MContext: true, // Beta 1M context support
     supportsCompaction: true, // Beta server-side context compaction
     description:
@@ -311,22 +326,10 @@ const THINKING_BUDGETS = {
   low: 0.15, // 15% of max thinking tokens
   medium: 0.33, // 33% of max thinking tokens (default)
   high: 0.67, // 67% of max thinking tokens
+  xhigh: 0.85, // 85% of max thinking tokens
   max: 1.0, // 100% of max thinking tokens
 };
 
-/**
- * Effort parameter mapping for Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6, and Opus 4.5
- * Maps reasoning_effort values to Anthropic's effort parameter values
- */
-const EFFORT_MAP = {
-  none: 'low',
-  minimal: 'low',
-  low: 'medium',
-  medium: 'high',
-  high: 'xhigh',
-  max: 'max',
-};
-
 /**
  * Custom error class for Anthropic provider errors
  */
@@ -716,16 +719,17 @@ export const anthropicProvider = {
 
     // Add effort parameter for models that support it (uses output_config)
     if (modelConfig.supportsEffort && reasoning_effort) {
-      const effortValue = EFFORT_MAP[reasoning_effort];
-      if (effortValue) {
-        requestPayload.output_config = {
-          ...requestPayload.output_config,
-          effort: effortValue,
-        };
-        debugLog(
-          `[Anthropic] Effort parameter set to "${effortValue}" for ${resolvedModel} (from reasoning_effort: ${reasoning_effort})`,
-        );
-      }
+      const effortValue = clampReasoningEffort(
+        reasoning_effort,
+        modelConfig.effortTiers,
+      );
+      requestPayload.output_config = {
+        ...requestPayload.output_config,
+        effort: effortValue,
+      };
+      debugLog(
+        `[Anthropic] Effort parameter set to "${effortValue}" for ${resolvedModel} (from reasoning_effort: ${reasoning_effort})`,
+      );
     }
 
     // If streaming is requested and model doesn't support it, fall back to non-streaming

package/src/providers/codex.js

@@ -16,17 +16,10 @@
 import { debugLog, debugError } from '../utils/console.js';
 import { ProviderError, ErrorCodes, StopReasons } from './interface.js';
 import { normalizeExtendedPath } from '../utils/pathUtils.js';
-
-/**
- * Every Codex reasoning tier, weakest to strongest. Used to clamp a requested
- * tier onto the set a given backend model accepts.
- *
- * Codex also exposes 'ultra' above 'max', but that tier turns on automatic
- * sub-agent delegation — a change in how the run executes, not just how deep
- * it reasons — so nothing at the tool level maps to it and it is kept off the
- * ladder so the clamp can never select it.
- */
-const EFFORT_LADDER = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+import {
+  EFFORT_LADDER,
+  clampReasoningEffort,
+} from '../utils/reasoningEffort.js';
 
 /**
  * Backend models Codex can run, keyed by the slug passed to the CLI as
@@ -35,6 +28,11 @@ const EFFORT_LADDER = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max
  * are: 'low', 'medium', 'high', 'xhigh', and 'max'"). The SDK's
  * ModelReasoningEffort type is the union across models, so the backend is the
  * authority and requests are clamped per model.
+ *
+ * Codex also exposes 'ultra' above 'max', but that tier turns on automatic
+ * sub-agent delegation — a change in how the run executes, not just how deep
+ * it reasons — so it is deliberately absent from every supportedEfforts list
+ * and nothing at the tool level can select it.
  */
 const CODEX_BACKEND_MODELS = {
   'gpt-6-astra': {
@@ -307,50 +305,6 @@ async function getThreadIdFromContinuation(
   }
 }
 
-/**
- * Tool-level reasoning_effort values translated to their Codex equivalent.
- * Tool enum: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'max'
- */
-const EFFORT_ALIASES = {
-  none: 'none',
-  minimal: 'minimal',
-  low: 'low',
-  medium: 'medium',
-  high: 'high',
-  max: 'max',
-};
-
-/**
- * Map a tool-level reasoning_effort onto a tier the target model accepts.
- *
- * When the requested tier isn't in the model's supported set, the nearest
- * *stronger* tier wins: nudging 'minimal' up to 'low' keeps reasoning on,
- * where falling back to 'none' would silently switch it off.
- *
- * @param {string} effort - Tool-level reasoning_effort value
- * @param {string[]} [supported] - Tiers the model accepts
- * @returns {string} A tier from `supported`
- */
-export function mapReasoningEffort(effort, supported = EFFORT_LADDER) {
-  const desired = EFFORT_ALIASES[effort] || 'medium';
-  if (supported.includes(desired)) {
-    return desired;
-  }
-
-  const rank = EFFORT_LADDER.indexOf(desired);
-  const stronger = EFFORT_LADDER.slice(rank + 1).find((tier) =>
-    supported.includes(tier),
-  );
-  if (stronger) {
-    return stronger;
-  }
-
-  const weaker = EFFORT_LADDER.slice(0, rank)
-    .reverse()
-    .find((tier) => supported.includes(tier));
-  return weaker || 'medium';
-}
-
 /**
  * Resolve a user-facing model name to its entry in SUPPORTED_MODELS.
  * @param {string} modelName
@@ -500,9 +454,9 @@ export const codexProvider = {
       if (reasoning_effort) {
         const supportedEfforts =
           getBackendModelConfig(backendModel)?.supportedEfforts || EFFORT_LADDER;
-        const mappedEffort = mapReasoningEffort(reasoning_effort, supportedEfforts);
+        const mappedEffort = clampReasoningEffort(reasoning_effort, supportedEfforts);
         threadOptions.modelReasoningEffort = mappedEffort;
-        if (mappedEffort !== EFFORT_ALIASES[reasoning_effort]) {
+        if (mappedEffort !== reasoning_effort) {
           debugLog(
             `[Codex] reasoning_effort "${reasoning_effort}" not supported by ${backendModel} — using "${mappedEffort}"`,
           );

package/src/providers/copilot.js

@@ -17,6 +17,7 @@ import { delimiter, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { debugLog, debugError } from '../utils/console.js';
 import { ProviderError, ErrorCodes, StopReasons } from './interface.js';
+import { clampReasoningEffort } from '../utils/reasoningEffort.js';
 
 const SUPPORTED_MODELS = {
   copilot: {
@@ -517,20 +518,14 @@ function resolveSessionModel(requestModel, config) {
  * - session.error → { data: { errorType, message } }
  */
 /**
- * Map tool-level reasoning_effort values to Copilot SDK's ReasoningEffort.
- * Tool enum:  'none' | 'minimal' | 'low' | 'medium' | 'high' | 'max'
- * SDK enum:   'low' | 'medium' | 'high' | 'xhigh'
+ * Values the Copilot SDK's ReasoningEffort type accepts. The SDK tops out at
+ * 'xhigh' and cannot switch reasoning off, so 'max' clamps down and
+ * 'none'/'minimal' clamp up.
  */
+const COPILOT_EFFORT_TIERS = ['low', 'medium', 'high', 'xhigh'];
+
 function mapReasoningEffort(effort) {
-  const mapping = {
-    none: 'low',
-    minimal: 'low',
-    low: 'low',
-    medium: 'medium',
-    high: 'high',
-    max: 'xhigh',
-  };
-  return mapping[effort] || undefined;
+  return clampReasoningEffort(effort, COPILOT_EFFORT_TIERS);
 }
 
 /**

package/src/providers/deepseek.js

@@ -7,6 +7,7 @@
 
 import { createOpenAICompatibleProvider } from './openai-compatible.js';
 import { debugLog } from '../utils/console.js';
+import { clampReasoningEffort } from '../utils/reasoningEffort.js';
 
 // Define supported DeepSeek models with their capabilities.
 // V4 unified the catalog: both tiers share a 1M context window and a 384K output
@@ -65,13 +66,19 @@ function validateApiKey(apiKey) {
   return apiKey.length >= 32;
 }
 
+/**
+ * Values DeepSeek's `reasoning_effort` field accepts once thinking is on.
+ * There is no lower documented tier, so every enabled level below high clamps
+ * up to "high" (the default `medium` runs thinking-on rather than silently
+ * disabling it) and `xhigh` clamps up to "max".
+ */
+const DEEPSEEK_EFFORT_TIERS = ['high', 'max'];
+
 /**
  * Map a Converse reasoning_effort level to DeepSeek's thinking-mode request
- * fields. DeepSeek exposes only two independent controls: a `thinking` toggle
- * ({type:"enabled"|"disabled"}) and a `reasoning_effort` field that accepts
- * ONLY "high" or "max". Every enabled level below max maps to "high" (there is
- * no lower documented tier), preserving enabled-reasoning intent so the default
- * `medium` runs thinking-on rather than silently disabling it.
+ * fields. DeepSeek exposes two independent controls: a `thinking` toggle
+ * ({type:"enabled"|"disabled"}) and the `reasoning_effort` tier. Only `none`
+ * flips the toggle off.
  */
 function applyReasoning(requestPayload, reasoningEffort) {
   if (reasoningEffort === 'none') {
@@ -81,7 +88,10 @@ function applyReasoning(requestPayload, reasoningEffort) {
   }
 
   requestPayload.thinking = { type: 'enabled' };
-  requestPayload.reasoning_effort = reasoningEffort === 'max' ? 'max' : 'high';
+  requestPayload.reasoning_effort = clampReasoningEffort(
+    reasoningEffort,
+    DEEPSEEK_EFFORT_TIERS,
+  );
 }
 
 /**

package/src/providers/gemini-cli.js

@@ -31,6 +31,7 @@ import { join, delimiter } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { debugLog, debugError } from '../utils/console.js';
 import { ProviderError, ErrorCodes, StopReasons } from './interface.js';
+import { clampReasoningEffort } from '../utils/reasoningEffort.js';
 
 // Prompts at or below this length pass directly as the -p argv value (fast
 // path). Larger prompts are written to a file and -p carries a bootstrap
@@ -174,32 +175,25 @@ export function findAgyBinary() {
   return _cachedAgyPath;
 }
 
+// agy variant tiers per model base. Flash offers Low/Medium/High; Pro has no
+// Medium variant.
+const FLASH_EFFORT_TIERS = ['low', 'medium', 'high'];
+const PRO_EFFORT_TIERS = ['low', 'high'];
+
 /**
  * Map a reasoning_effort value to the agy parenthesized variant suffix.
- * Flash supports Low/Medium/High; Pro supports Low/High (no Medium).
+ * Unset effort selects High, agy's own default.
  * @param {string} base - agy model base ('Gemini 3.8 Flash' / 'Gemini 3.1 Pro')
  * @param {string} [reasoningEffort]
  * @returns {string} e.g. '(Low)', '(Medium)', '(High)'
  */
 function effortSuffix(base, reasoningEffort) {
-  const isPro = /pro/i.test(base);
-  const effort = (reasoningEffort || '').toLowerCase();
-
-  switch (effort) {
-  case 'none':
-  case 'minimal':
-  case 'low':
-    return '(Low)';
-  case 'medium':
-    // Pro has no Medium variant — fall back to High
-    return isPro ? '(High)' : '(Medium)';
-  case 'high':
-  case 'max':
-    return '(High)';
-  default:
-    // unset → High
+  if (!reasoningEffort) {
     return '(High)';
   }
+  const tiers = /pro/i.test(base) ? PRO_EFFORT_TIERS : FLASH_EFFORT_TIERS;
+  const tier = clampReasoningEffort(reasoningEffort.toLowerCase(), tiers);
+  return `(${tier[0].toUpperCase()}${tier.slice(1)})`;
 }
 
 /**

package/src/providers/google.js

@@ -7,6 +7,7 @@
 
 import { GoogleGenAI } from '@google/genai';
 import { debugLog, debugError } from '../utils/console.js';
+import { clampReasoningEffort } from '../utils/reasoningEffort.js';
 
 // Define supported Gemini models with their capabilities
 const SUPPORTED_MODELS = {
@@ -161,9 +162,14 @@ const THINKING_BUDGETS = {
   low: 0.08, // 8% of max - light reasoning tasks
   medium: 0.33, // 33% of max - balanced reasoning (default)
   high: 0.67, // 67% of max - complex analysis
+  xhigh: 0.85, // 85% of max - near-full budget
   max: 1.0, // 100% of max - full thinking budget
 };
 
+// thinkingLevel values for models without an explicit thinkingLevels list
+// (Gemini 3.0 Pro exposes only low/high).
+const BINARY_THINKING_LEVELS = ['low', 'high'];
+
 /**
  * Custom error class for Google provider errors
  */
@@ -527,37 +533,13 @@ export const googleProvider = {
     // Add thinking configuration for models that support it
     if (modelConfig.supportsThinking && reasoning_effort) {
       if (modelConfig.thinkingMode === 'level') {
-        let thinkingLevel;
-        if (modelConfig.thinkingLevels) {
-          // Model supports specific levels (e.g., Gemini 3.1 Pro: minimal/low/medium/high)
-          const levelMap = {
-            none: 'minimal',
-            minimal: 'minimal',
-            low: 'low',
-            medium: 'medium',
-            high: 'high',
-            max: 'high',
-          };
-          thinkingLevel = levelMap[reasoning_effort] || 'high';
-          if (!modelConfig.thinkingLevels.includes(thinkingLevel)) {
-            // Clamp to the nearest supported level: a request below the
-            // model's floor (e.g. minimal on 3.8 Flash) takes the lowest
-            // level, anything else the highest.
-            const rank = ['minimal', 'low', 'medium', 'high'];
-            const [lowest] = modelConfig.thinkingLevels;
-            thinkingLevel =
-              rank.indexOf(thinkingLevel) < rank.indexOf(lowest)
-                ? lowest
-                : modelConfig.thinkingLevels[
-                  modelConfig.thinkingLevels.length - 1
-                ];
-          }
-        } else {
-          // Binary levels only (Gemini 3.0 Pro: low/high)
-          thinkingLevel = ['minimal', 'low'].includes(reasoning_effort)
-            ? 'low'
-            : 'high';
-        }
+        // Gemini 3.x thinkingLevel names are tool-level tiers, so the request
+        // clamps straight onto the levels the model lists (none → minimal or
+        // the floor, xhigh/max → the ceiling).
+        const thinkingLevel = clampReasoningEffort(
+          reasoning_effort,
+          modelConfig.thinkingLevels || BINARY_THINKING_LEVELS,
+        );
         generationConfig.thinkingConfig = { thinkingLevel };
       } else {
         // Gemini 2.5: Use thinking budget (token count)

package/src/providers/mistral.js

@@ -7,6 +7,7 @@
 
 import { debugLog, debugError } from '../utils/console.js';
 import { ProviderError, ErrorCodes, StopReasons } from './interface.js';
+import { clampReasoningEffort } from '../utils/reasoningEffort.js';
 
 // Define supported Mistral models with their capabilities.
 // Reasoning (`reasoning_effort`) is supported only on Medium 3.5 and Small 4;
@@ -61,19 +62,22 @@ const SUPPORTED_MODELS = {
   },
 };
 
+/**
+ * Values Mistral documents for `reasoning_effort`. Every enabled level clamps
+ * to "high" so the default `medium` runs thinking-on; only `none` disables.
+ */
+const MISTRAL_EFFORT_TIERS = ['none', 'high'];
+
 /**
  * Map a Converse reasoning_effort level to Mistral's documented request value.
- * Mistral documents only "high" and "none". Every enabled level maps to "high"
- * to preserve enabled-reasoning intent (Converse's default `medium` runs
- * thinking-on); only `none` disables. Returns null when reasoning must not be
- * forwarded — i.e. the model does not support it (Large 3) or is an unknown
- * pass-through ID (capability-gated).
+ * Returns null when reasoning must not be forwarded — i.e. the model does not
+ * support it (Large 3) or is an unknown pass-through ID (capability-gated).
  */
 function resolveReasoningEffort(level, modelConfig) {
   if (!modelConfig?.supportsReasoning) {
     return null;
   }
-  return level === 'none' ? 'none' : 'high';
+  return clampReasoningEffort(level, MISTRAL_EFFORT_TIERS);
 }
 
 /**

package/src/providers/openai.js

@@ -7,6 +7,21 @@
 
 import OpenAI from 'openai';
 import { debugLog, debugError } from '../utils/console.js';
+import { clampReasoningEffort } from '../utils/reasoningEffort.js';
+
+// Values each family accepts for reasoning effort, per the model pages at
+// developers.openai.com/api/docs/models. GPT-5.6 is the only family with
+// 'max'; the GPT-5.4 tier stops at 'xhigh'; the original GPT-5 minis kept
+// 'minimal' but never gained 'xhigh'; the o-series predates both ends of the
+// ladder; GPT-5.4 Pro starts at 'medium'. Models without a list are passed
+// the requested value unchanged, except uncatalogued GPT-5 Pro snapshots,
+// which are only known to accept 'high'.
+const GPT_56_EFFORT_TIERS = ['none', 'low', 'medium', 'high', 'xhigh', 'max'];
+const GPT_54_EFFORT_TIERS = ['none', 'low', 'medium', 'high', 'xhigh'];
+const GPT_54_PRO_EFFORT_TIERS = ['medium', 'high', 'xhigh'];
+const GPT_5_EFFORT_TIERS = ['minimal', 'low', 'medium', 'high'];
+const O_SERIES_EFFORT_TIERS = ['low', 'medium', 'high'];
+const PRO_PASSTHROUGH_EFFORT_TIERS = ['high'];
 
 // Define supported models with their capabilities
 const SUPPORTED_MODELS = {
@@ -19,7 +34,7 @@ const SUPPORTED_MODELS = {
     supportsImages: true,
     supportsWebSearch: true,
     supportsResponsesAPI: true,
-    supportsNoneReasoningEffort: true,
+    supportedEfforts: GPT_56_EFFORT_TIERS,
     timeout: 10800000, // 3 hours
     description:
       'Flagship GPT-5.6 model (1M context, 128K output) - Frontier reasoning, coding, agentic workflows. Most token-efficient flagship',
@@ -44,7 +59,7 @@ const SUPPORTED_MODELS = {
     supportsImages: true,
     supportsWebSearch: true,
     supportsResponsesAPI: true,
-    supportsNoneReasoningEffort: true,
+    supportedEfforts: GPT_56_EFFORT_TIERS,
     timeout: 5400000, // 90 minutes
     description:
       'Lower-cost GPT-5.6 (400K context, 128K output) - Performance competitive with GPT-5.5 at half the flagship price',
@@ -59,7 +74,7 @@ const SUPPORTED_MODELS = {
     supportsImages: true,
     supportsWebSearch: true,
     supportsResponsesAPI: true,
-    supportsNoneReasoningEffort: true,
+    supportedEfforts: GPT_56_EFFORT_TIERS,
     timeout: 1800000, // 30 minutes
     description:
       'Fastest, most affordable GPT-5.6 (400K context, 128K output) - High-volume, latency-sensitive workloads',
@@ -74,7 +89,7 @@ const SUPPORTED_MODELS = {
     supportsImages: true,
     supportsWebSearch: true,
     supportsResponsesAPI: true,
-    supportsNoneReasoningEffort: true,
+    supportedEfforts: GPT_54_EFFORT_TIERS,
     timeout: 10800000, // 3 hours
     description:
       'Latest flagship model (1M context, 128K output) - Superior reasoning, coding, agentic workflows, computer use. Most token-efficient reasoning model',
@@ -92,6 +107,7 @@ const SUPPORTED_MODELS = {
     supportsImages: true,
     supportsWebSearch: true,
     supportsResponsesAPI: true,
+    supportedEfforts: GPT_5_EFFORT_TIERS,
     timeout: 5400000, // 90 minutes
     description:
       'Faster, cost-efficient GPT-5 (400K context, 128K output) - Well-defined tasks, precise prompts',
@@ -106,6 +122,7 @@ const SUPPORTED_MODELS = {
     supportsImages: true,
     supportsWebSearch: false, // GPT-5-nano doesn't support web search
     supportsResponsesAPI: true,
+    supportedEfforts: GPT_5_EFFORT_TIERS,
     timeout: 1800000, // 30 minutes
     description:
       'Fastest, most cost-efficient GPT-5 (400K context, 128K output) - Summarization, classification',
@@ -120,6 +137,7 @@ const SUPPORTED_MODELS = {
     supportsImages: true,
     supportsWebSearch: true,
     supportsResponsesAPI: true,
+    supportedEfforts: GPT_54_EFFORT_TIERS,
     timeout: 5400000, // 90 minutes
     description:
       'Fast, efficient GPT-5.4 (400K context, 128K output) - Coding, subagents, computer use, tool use. 2x faster than GPT-5 mini',
@@ -139,6 +157,7 @@ const SUPPORTED_MODELS = {
     supportsImages: true,
     supportsWebSearch: false,
     supportsResponsesAPI: true,
+    supportedEfforts: GPT_54_EFFORT_TIERS,
     timeout: 1800000, // 30 minutes
     description:
       'Smallest, cheapest GPT-5.4 (400K context, 128K output) - Classification, data extraction, ranking, coding subagents',
@@ -159,6 +178,7 @@ const SUPPORTED_MODELS = {
     supportsWebSearch: true,
     supportsResponsesAPI: true,
     supportsDeepResearch: false,
+    supportedEfforts: GPT_54_PRO_EFFORT_TIERS,
     timeout: 10800000, // 180 minutes
     description:
       'Maximum performance reasoning model (1M context, 272K output) - Most complex tasks, extended compute time (EXPENSIVE)',
@@ -179,6 +199,7 @@ const SUPPORTED_MODELS = {
     supportsImages: true,
     supportsWebSearch: true,
     supportsResponsesAPI: true,
+    supportedEfforts: O_SERIES_EFFORT_TIERS,
     timeout: 1800000, // 30 minutes
     description:
       'Strong reasoning (200K context) - Logical problems, code generation, systematic analysis',
@@ -193,6 +214,7 @@ const SUPPORTED_MODELS = {
     supportsImages: true,
     supportsWebSearch: true,
     supportsResponsesAPI: true,
+    supportedEfforts: O_SERIES_EFFORT_TIERS,
     timeout: 10800000, // 180 minutes
     description:
       'Professional-grade reasoning (200K context) - EXTREMELY EXPENSIVE: Only for the most complex problems',
@@ -207,6 +229,7 @@ const SUPPORTED_MODELS = {
     supportsImages: true,
     supportsWebSearch: true,
     supportsResponsesAPI: true,
+    supportedEfforts: O_SERIES_EFFORT_TIERS,
     timeout: 540000, // 9 minutes
     description:
       'Latest reasoning model (200K context) - Optimized for shorter contexts, rapid reasoning',
@@ -311,17 +334,32 @@ function resolveModelName(modelName) {
 }
 
 /**
- * Resolve the reasoning effort actually sent to the API for a given model.
- * GPT-5 Pro models only accept 'high'. GPT-5.6 models dropped 'minimal'
- * (supported efforts: none, low, medium, high, xhigh, max), so 'minimal'
- * maps to the closest supported value.
+ * Whether a request to this model should carry a reasoning effort at all.
+ * Catalogued models say so through their declared tiers; pass-through IDs
+ * fall back to the o-series / GPT-5 name heuristic.
  */
-function resolveReasoningEffort(resolvedModel, reasoningEffort) {
+function acceptsReasoningEffort(resolvedModel, modelConfig) {
+  if (modelConfig.supportedEfforts) {
+    return true;
+  }
+  return resolvedModel.startsWith('o3') || resolvedModel.startsWith('gpt-5');
+}
+
+/**
+ * Resolve the reasoning effort actually sent to the API. Catalogued models
+ * clamp onto their declared tiers. Pass-through IDs are matched by family
+ * where the tiers are known (GPT-5 Pro snapshots, GPT-5.6 snapshots) and
+ * otherwise keep the requested value.
+ */
+function resolveReasoningEffort(resolvedModel, modelConfig, reasoningEffort) {
+  if (modelConfig.supportedEfforts) {
+    return clampReasoningEffort(reasoningEffort, modelConfig.supportedEfforts);
+  }
   if (resolvedModel.endsWith('-pro') && resolvedModel.startsWith('gpt-5')) {
-    return 'high';
+    return clampReasoningEffort(reasoningEffort, PRO_PASSTHROUGH_EFFORT_TIERS);
   }
-  if (resolvedModel.startsWith('gpt-5.6') && reasoningEffort === 'minimal') {
-    return 'low';
+  if (resolvedModel.startsWith('gpt-5.6')) {
+    return clampReasoningEffort(reasoningEffort, GPT_56_EFFORT_TIERS);
   }
   return reasoningEffort;
 }
@@ -511,13 +549,13 @@ export const openaiProvider = {
         requestPayload.tools = [{ type: 'web_search_preview' }];
       }
 
-      // Add reasoning effort for thinking models (o3 series and GPT-5 family)
-      if (
-        (resolvedModel.startsWith('o3') || resolvedModel.startsWith('gpt-5')) &&
-        reasoning_effort
-      ) {
+      if (acceptsReasoningEffort(resolvedModel, modelConfig) && reasoning_effort) {
         requestPayload.reasoning = {
-          effort: resolveReasoningEffort(resolvedModel, reasoning_effort),
+          effort: resolveReasoningEffort(
+            resolvedModel,
+            modelConfig,
+            reasoning_effort,
+          ),
           summary: 'auto', // Enable reasoning summaries
         };
       }
@@ -531,13 +569,10 @@ export const openaiProvider = {
         ...cleanOptions,
       };
 
-      // Add reasoning effort for thinking models (o3 series and GPT-5 family)
-      if (
-        (resolvedModel.startsWith('o3') || resolvedModel.startsWith('gpt-5')) &&
-        reasoning_effort
-      ) {
+      if (acceptsReasoningEffort(resolvedModel, modelConfig) && reasoning_effort) {
         requestPayload.reasoning_effort = resolveReasoningEffort(
           resolvedModel,
+          modelConfig,
           reasoning_effort,
         );
       }

package/src/providers/openrouter.js

@@ -26,6 +26,7 @@ import {
   lookupOpenRouterModel,
   DiscoveryStatus,
 } from './openrouter-discovery.js';
+import { clampReasoningEffort } from '../utils/reasoningEffort.js';
 
 // Curated static catalog (verified live 2026-07-11). getSupportedModels() must
 // return exactly these 8 slugs even after a discovery call has run — dynamic
@@ -255,7 +256,7 @@ function extractReasoningText(details) {
  *   1. passthrough (openrouter/auto)  → null (router decides)
  *   2. mandatory (kimi-k2.7-code)     → { enabled: true } (cannot disable)
  *   3. effort-tiered (glm/deepseek)   → clamp into supported_efforts
- *                                       (max→xhigh, else→high; none→disabled)
+ *                                       (nearest stronger tier; none→disabled)
  *   4. enable/disable-only (qwen/kimi) → { enabled: false } for none, else true
  *   5. unavailable metadata           → null (omit conservatively)
  *
@@ -280,14 +281,9 @@ function buildOpenRouterReasoning(modelConfig, reasoningEffort) {
     reasoning.supported_efforts.length > 0
   ) {
     if (level === 'none') return { enabled: false };
-    const wanted = level === 'max' ? 'xhigh' : 'high';
-    const efforts = reasoning.supported_efforts;
-    const effort = efforts.includes(wanted)
-      ? wanted
-      : efforts.includes('high')
-        ? 'high'
-        : efforts[0];
-    return { effort };
+    return {
+      effort: clampReasoningEffort(level, reasoning.supported_efforts),
+    };
   }
 
   // Enable/disable-only.

package/src/providers/xai.js

@@ -14,6 +14,7 @@
 
 import OpenAI from 'openai';
 import { debugLog, debugError } from '../utils/console.js';
+import { clampReasoningEffort } from '../utils/reasoningEffort.js';
 
 // Curated catalog: grok-4.5 only (verified live 2026-07-11 against
 // GET https://api.x.ai/v1/models/grok-4.5 — id, aliases, 500k context).
@@ -85,27 +86,15 @@ function resolveModelName(modelName) {
 }
 
 /**
- * Map Converse reasoning_effort to a value grok-4.5 accepts.
- *
- * grok-4.5 supports ONLY low/medium/high (default high) and cannot disable
- * reasoning — there is no `none`/off value. Sending an unsupported value
- * (e.g. `none`/`minimal`/`max`) returns HTTP 400, so unsupported Converse
- * levels are clamped into {low, medium, high} rather than forwarded.
+ * Tiers grok-4.5 accepts (default high). It cannot disable reasoning — there
+ * is no `none`/off value — and sending an unsupported value (`none`,
+ * `minimal`, `xhigh`, `max`) returns HTTP 400, so requests are clamped into
+ * this set rather than forwarded.
  */
+const GROK_EFFORT_TIERS = ['low', 'medium', 'high'];
+
 function resolveReasoningEffort(reasoningEffort) {
-  switch (reasoningEffort) {
-  case 'none':
-  case 'minimal':
-  case 'low':
-    return 'low';
-  case 'medium':
-    return 'medium';
-  case 'high':
-  case 'max':
-    return 'high';
-  default:
-    return 'high';
-  }
+  return clampReasoningEffort(reasoningEffort, GROK_EFFORT_TIERS);
 }
 
 /**

package/src/tools/chat.js

@@ -27,6 +27,7 @@ import { applyTokenLimit, getTokenLimit } from '../utils/tokenLimiter.js';
 import { validateAllPaths } from '../utils/fileValidator.js';
 import { SummarizationService } from '../services/summarizationService.js';
 import { exportConversation } from '../utils/conversationExporter.js';
+import { EFFORT_LADDER } from '../utils/reasoningEffort.js';
 import {
   getDefaultModelForProvider,
   getProviderUnavailableMessage,
@@ -1187,9 +1188,9 @@ chatTool.inputSchema = {
     },
     reasoning_effort: {
       type: 'string',
-      enum: ['none', 'minimal', 'low', 'medium', 'high', 'max'],
+      enum: EFFORT_LADDER,
       description:
-        'Reasoning depth for thinking models. Examples: "none" (no reasoning, fastest - GPT-5.1+ only), "minimal", "low", "medium" (balanced), "high", "max". Default: "medium"',
+        'Reasoning depth for thinking models, weakest to strongest: "none" (reasoning off, where the model allows it), "minimal", "low", "medium" (balanced), "high", "xhigh", "max". Passed through by name when the model accepts it, otherwise clamped to the nearest tier it does. Default: "medium"',
     },
     async: {
       type: 'boolean',

package/src/utils/reasoningEffort.js

@@ -0,0 +1,75 @@
+/**
+ * Reasoning Effort Ladder
+ *
+ * The tool-level `reasoning_effort` vocabulary is the union of the tiers the
+ * providers expose, ordered weakest to strongest. Every provider declares the
+ * subset its model accepts and clamps the request onto it here, so the same
+ * word means the same tier everywhere and a provider never re-derives the
+ * ordering on its own.
+ */
+
+/**
+ * Every tool-level reasoning_effort value, weakest first. Doubles as the
+ * `enum` of the chat tool's `reasoning_effort` parameter.
+ * @type {string[]}
+ */
+export const EFFORT_LADDER = [
+  'none',
+  'minimal',
+  'low',
+  'medium',
+  'high',
+  'xhigh',
+  'max',
+];
+
+/**
+ * Effort applied when the caller leaves reasoning_effort unset or sends a
+ * value outside the ladder.
+ */
+export const DEFAULT_EFFORT = 'medium';
+
+/**
+ * Clamp a requested effort onto the tiers a model accepts.
+ *
+ * The requested tier wins when the model accepts it. Otherwise the nearest
+ * *stronger* accepted tier wins: nudging 'minimal' up to 'low' keeps reasoning
+ * on, where falling back to 'none' would silently switch it off. Only when
+ * nothing stronger exists does the nearest weaker tier apply (e.g. 'max' on a
+ * model that tops out at 'xhigh').
+ *
+ * Tiers in `supported` that are not on the ladder are ignored for ranking but
+ * the first of them is used as a last resort when nothing on the ladder
+ * matches, so a provider-declared list is never answered with a tier it
+ * doesn't contain. An empty list is invalid capability data and throws rather
+ * than inventing a tier the model may reject.
+ *
+ * @param {string|undefined} effort - Tool-level reasoning_effort value
+ * @param {string[]} supported - Tiers the model accepts (any order)
+ * @returns {string} A tier from `supported`
+ */
+export function clampReasoningEffort(effort, supported) {
+  if (!Array.isArray(supported) || supported.length === 0) {
+    throw new TypeError(
+      'clampReasoningEffort requires a non-empty list of supported tiers',
+    );
+  }
+
+  const desired = EFFORT_LADDER.includes(effort) ? effort : DEFAULT_EFFORT;
+  if (supported.includes(desired)) {
+    return desired;
+  }
+
+  const rank = EFFORT_LADDER.indexOf(desired);
+  const stronger = EFFORT_LADDER.slice(rank + 1).find((tier) =>
+    supported.includes(tier),
+  );
+  if (stronger) {
+    return stronger;
+  }
+
+  const weaker = EFFORT_LADDER.slice(0, rank)
+    .reverse()
+    .find((tier) => supported.includes(tier));
+  return weaker || supported[0];
+}