@link-assistant/hive-mind 2.3.0 → 2.4.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @link-assistant/hive-mind
 
+## 2.4.1
+
+### Patch Changes
+
+- c412790: Improve model capacity fallback handling (Issue #2037): when the requested model is temporarily unavailable, every tool now retries the originally-requested model up to 5 times with exponential backoff before switching, then walks a fallback chain ordered by intelligence/size tier (e.g. `gpt-5.6-sol → gpt-5.6-terra → gpt-5.5 → gpt-5.4 → gpt-5.2`, skipping the smaller `gpt-5.6-luna` variant), keeps the mismatch warning informative rather than alarming, retries quickly after a capacity-driven model switch, and reports the fallback model's share of output tokens. Includes a case study reconstructing the timeline and root causes.
+
+## 2.4.0
+
+### Minor Changes
+
+- dc28004: Fix `--think` validation asymmetry between `solve` and `hive` (Issue #2041). After the #2038 vocabulary refactor, `solve.config` only validated `--think` in the CLI `parseArguments()` path, so consumers that parse solve options directly through the yargs config — most notably the Telegram bot — silently accepted invalid `--think` values (a CI false-negative that failed `test-telegram-options-before-url`). `createYargsConfig` now runs the same `normalizeAndValidateThink` `.check()` that `hive.config` already used, and `parseArguments` propagates that validation error verbatim instead of swallowing it. Invalid `--think` values are now rejected consistently on the CLI and Telegram paths.
+- d92c772: `--think` now accepts a richer, provider-neutral vocabulary (Issue #2038): the off synonyms `off`/`disable`/`disabled`/`no`/`none` all mean disabled (or the closest safe equivalent when a model cannot truly disable thinking), a new `minimal` tier below `low` (Codex `minimal` reasoning; Claude lowest effort with a ~4000-token budget), a first-class `adaptive` mode that requests provider-managed adaptive thinking and fails fast for `solve`/`hive` on models/tools that do not support it (only adaptive-only Claude models: Opus 4.7+, Fable 5, Mythos 5, Sonnet 5), and numeric intensities for precision — percentages `0%`..`100%`, fractions `0.0`..`1.0`, and the integers `0` (off) and `1` (max). Normalization is applied consistently for both `solve` and `hive`.
+
 ## 2.3.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/agent.lib.mjs

@@ -24,7 +24,7 @@ import semver from 'semver';
 import { agentModels, defaultModels, freeToBaseModelMap } from './models/index.mjs';
 import { checkPlaywrightMcpPackageAvailability, getAgentPlaywrightMcpDisableEnv } from './playwright-mcp.lib.mjs';
 import { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage } from './agent-token-usage.lib.mjs';
-import { classifyRetryableError, getRetryDelayMs, maybeSwitchToFallbackModel, waitWithCountdown } from './tool-retry.lib.mjs';
+import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { attachStreamingInput, finalizeBidirectionalHandler, setupBidirectionalHandler } from './bidirectional-interactive.lib.mjs';
 
 export { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage };
@@ -898,15 +898,22 @@ export const executeAgentCommand = async params => {
           const isRequestTimeoutRetry = retryableError.label === 'Request timeout';
           const maxRetries = isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
           if (retryCount < maxRetries) {
-            const delay = getRetryDelayMs({
+            if (sessionId && !argv.resume) argv.resume = sessionId;
+            // Issue #2037: retry the same model on capacity errors before falling back;
+            // after a capacity-driven model switch, retry quickly instead of waiting the
+            // full transient backoff — the new model may be available now.
+            const retryPlan = await prepareRetryAfterError({
+              tool: 'agent',
+              argv,
+              log,
+              errorMessage: retryableError.message,
               retryCount,
               initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
               maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
             });
+            const delay = retryPlan.delay;
             const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
             await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel}${sessionId ? ' (session preserved)' : ''}...`, { level: 'warning' });
-            if (sessionId && !argv.resume) argv.resume = sessionId;
-            await maybeSwitchToFallbackModel({ tool: 'agent', argv, log, errorMessage: retryableError.message });
             await finalizeAgentBidirectionalHandler();
             await waitForRetryDelay(delay, log);
             await log('\n🔄 Retrying now...');

package/src/claude.lib.mjs

@@ -26,7 +26,7 @@ import { buildMcpConfigWithoutPlaywright, ensureClaudePlaywrightMcpServer } from
 import { resolveClaudeSessionToolFlags } from './useless-tools.lib.mjs';
 import { ensureClaudeQuietConfig } from './claude-quiet-config.lib.mjs';
 import { fetchModelInfo } from './model-info.lib.mjs';
-import { classifyRetryableError, logExecutionContext, maybeSwitchToFallbackModel, waitWithCountdown } from './tool-retry.lib.mjs';
+import { classifyRetryableError, logExecutionContext, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { resolveSubSessionSize } from './sub-session-size.lib.mjs'; // Issue #1706
 import { withAgentsMdAsClaudeMd } from './agents-md-claude-support.lib.mjs';
 import { deployHandoffSkill } from './handoff-skill.lib.mjs'; // Issue #1877
@@ -206,7 +206,9 @@ export const resolveThinkingSettings = async (argv, log) => {
   let thinkLevel = argv.think;
   let translation = null;
   if (isNewVersion) {
-    if (thinkLevel !== undefined && thinkingBudget === undefined) {
+    // Issue #2038: `adaptive` is provider-managed and has no explicit token
+    // budget; skip the budget translation and let the model manage thinking.
+    if (thinkLevel !== undefined && thinkLevel !== 'adaptive' && thinkingBudget === undefined) {
       thinkingBudget = thinkingLevelToTokens[thinkLevel];
       translation = `--think ${thinkLevel} → --thinking-budget ${thinkingBudget}`;
       if (argv.verbose) {
@@ -1210,7 +1212,11 @@ export const executeClaudeCommand = async params => {
           };
         }
         if (retryCount < maxRetries) {
-          const delay = Math.min(initialDelay * Math.pow(retryLimits.retryBackoffMultiplier, retryCount), maxDelay);
+          // Activity timeout preserves session (work was started), startup timeout does not (no session created)
+          if (!isStartupTimeout && sessionId && !argv.resume) argv.resume = sessionId;
+          // Issue #2037: retry same model on capacity errors before falling back; a switch retries fast.
+          const retryPlan = await prepareRetryAfterError({ tool: 'claude', argv, log, errorMessage: retryableLastError.message || lastMessage, retryCount, initialDelayMs: initialDelay, maxDelayMs: maxDelay });
+          const delay = retryPlan.delay;
           const errorLabel = isStartupTimeout ? 'Stream startup timeout (Issue #1472/#1475)' : isActivityTimeout ? 'Stream activity timeout (Issue #1472)' : isRequestTimeout ? 'Request timeout' : retryableLastError.label || (isOverloadError || (lastMessage.includes('API Error: 500') && lastMessage.includes('Overloaded')) || (lastMessage.includes('API Error: 529') && lastMessage.includes('Overloaded')) ? `API overload (${lastMessage.includes('529') ? '529' : '500'})` : isInternalServerError || lastMessage.includes('Internal server error') ? 'Internal server error (500)' : isRateLimitError ? 'Server rate limited (429)' : '503 network error');
           const notRetryableHint = apiMarkedNotRetryable ? ' (API says not retryable — will stop early if no progress)' : '';
           const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
@@ -1230,9 +1236,6 @@ export const executeClaudeCommand = async params => {
               await log(`   Warning: Could not post force-kill comment to PR: ${commentError.message}`, { verbose: true });
             }
           }
-          // Activity timeout preserves session (work was started), startup timeout does not (no session created)
-          if (!isStartupTimeout && sessionId && !argv.resume) argv.resume = sessionId;
-          await maybeSwitchToFallbackModel({ tool: 'claude', argv, log, errorMessage: retryableLastError.message || lastMessage });
           await waitWithCountdown(delay, log);
           await log('\n🔄 Retrying now...');
           retryCount++;
@@ -1387,11 +1390,13 @@ export const executeClaudeCommand = async params => {
         const initialDelay = isTimeoutException ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs;
         const maxDelay = isTimeoutException ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs;
         if (retryCount < maxRetries) {
-          const delay = Math.min(initialDelay * Math.pow(retryLimits.retryBackoffMultiplier, retryCount), maxDelay);
-          const errorLabel = isTimeoutException ? 'Request timeout' : retryableException.label || (errorStr.includes('Overloaded') ? `API overload (${errorStr.includes('529') ? '529' : '500'})` : errorStr.includes('Internal server error') ? 'Internal server error (500)' : '503 network error');
-          await log(`\n⚠️ ${errorLabel} in exception. Retry ${retryCount + 1}/${maxRetries} in ${Math.round(delay / 60000)} min (session preserved)...`, { level: 'warning' });
           if (sessionId && !argv.resume) argv.resume = sessionId;
-          await maybeSwitchToFallbackModel({ tool: 'claude', argv, log, errorMessage: errorStr });
+          // Issue #2037: retry same model on capacity errors before falling back; a switch retries fast.
+          const retryPlan = await prepareRetryAfterError({ tool: 'claude', argv, log, errorMessage: errorStr, retryCount, initialDelayMs: initialDelay, maxDelayMs: maxDelay });
+          const delay = retryPlan.delay;
+          const errorLabel = isTimeoutException ? 'Request timeout' : retryableException.label || (errorStr.includes('Overloaded') ? `API overload (${errorStr.includes('529') ? '529' : '500'})` : errorStr.includes('Internal server error') ? 'Internal server error (500)' : '503 network error');
+          const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
+          await log(`\n⚠️ ${errorLabel} in exception. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel} (session preserved)...`, { level: 'warning' });
           await waitWithCountdown(delay, log);
           await log('\n🔄 Retrying now...');
           retryCount++;

package/src/codex.lib.mjs

@@ -31,7 +31,7 @@ import { initProgressMonitoring } from './solve.progress-monitoring.lib.mjs';
 import { ensureCodexPlaywrightMcpServer, getCodexPlaywrightMcpDisableConfigArgs } from './playwright-mcp.lib.mjs';
 import { fetchModelInfo } from './model-info.lib.mjs';
 import { defaultModels } from './models/index.mjs';
-import { classifyRetryableError, getRetryDelayMs, maybeSwitchToFallbackModel, waitWithCountdown } from './tool-retry.lib.mjs';
+import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { parseSubSessionSize, buildCodexSubSessionSizeConfigArgs, buildCodexDisable1mContextConfigArgs } from './sub-session-size.lib.mjs'; // Issue #1706
 import { getCumulativeContextInputTokens } from './context-fill.lib.mjs';
 import { deployHandoffSkill } from './handoff-skill.lib.mjs'; // Issue #1877
@@ -1175,15 +1175,13 @@ export const executeCodexCommand = async params => {
           const isRequestTimeoutRetry = retryableError.label === 'Request timeout';
           const maxRetries = isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
           if (retryCount < maxRetries) {
-            const delay = getRetryDelayMs({
-              retryCount,
-              initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
-              maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
-            });
+            if (sessionId && !argv.resume) argv.resume = sessionId;
+            // Issue #2037: retry same model on capacity errors before falling back; a
+            // capacity-driven switch retries fast, other transient errors use standard backoff.
+            const retryPlan = await prepareRetryAfterError({ tool: 'codex', argv, log, errorMessage: retryableError.message, retryCount, initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs, maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs });
+            const delay = retryPlan.delay;
             const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
             await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel}${sessionId ? ' (session preserved)' : ''}...`, { level: 'warning' });
-            if (sessionId && !argv.resume) argv.resume = sessionId;
-            await maybeSwitchToFallbackModel({ tool: 'codex', argv, log, errorMessage: retryableError.message });
             await waitForRetryDelay(delay, log);
             await log('\n🔄 Retrying now...');
             retryCount++;
@@ -1222,15 +1220,13 @@ export const executeCodexCommand = async params => {
           const isRequestTimeoutRetry = retryableError.label === 'Request timeout';
           const maxRetries = isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
           if (retryCount < maxRetries) {
-            const delay = getRetryDelayMs({
-              retryCount,
-              initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
-              maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
-            });
+            if (sessionId && !argv.resume) argv.resume = sessionId;
+            // Issue #2037: retry same model on capacity errors before falling back; a
+            // capacity-driven switch retries fast, other transient errors use standard backoff.
+            const retryPlan = await prepareRetryAfterError({ tool: 'codex', argv, log, errorMessage: retryableError.message, retryCount, initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs, maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs });
+            const delay = retryPlan.delay;
             const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
             await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel}${sessionId ? ' (session preserved)' : ''}...`, { level: 'warning' });
-            if (sessionId && !argv.resume) argv.resume = sessionId;
-            await maybeSwitchToFallbackModel({ tool: 'codex', argv, log, errorMessage: retryableError.message });
             await waitForRetryDelay(delay, log);
             await log('\n🔄 Retrying now...');
             retryCount++;

package/src/codex.options.lib.mjs

@@ -14,6 +14,8 @@ export const mapModelToId = model => codexModels[model] || model;
 // deepest single-agent effort. `off` disables reasoning (`none`). See docs/case-studies/issue-2027.
 const THINK_LEVEL_TO_CODEX_REASONING = {
   off: 'none',
+  // Issue #2038: Codex/GPT-5.x natively exposes a `minimal` reasoning effort below `low`.
+  minimal: 'minimal',
   low: 'low',
   medium: 'medium',
   high: 'high',

package/src/config.lib.mjs

@@ -127,6 +127,18 @@ export const retryLimits = {
   maxTransientErrorRetries: parseIntWithDefault('HIVE_MIND_MAX_TRANSIENT_ERROR_RETRIES', 10),
   initialTransientErrorDelayMs: parseIntWithDefault('HIVE_MIND_INITIAL_TRANSIENT_ERROR_DELAY_MS', 2 * 60 * 1000), // 2 minutes
   maxTransientErrorDelayMs: parseIntWithDefault('HIVE_MIND_MAX_TRANSIENT_ERROR_DELAY_MS', 30 * 60 * 1000), // 30 minutes
+  // Issue #2037: When a "model is at capacity" error triggers a switch to a *different*
+  // fallback model, the long transient backoff is wasteful — the different model is
+  // available now, so retry almost immediately instead of stalling for minutes.
+  modelSwitchRetryDelayMs: parseIntWithDefault('HIVE_MIND_MODEL_SWITCH_RETRY_DELAY_MS', 5 * 1000), // 5 seconds
+  // Issue #2037 (review): On a "model is at capacity" error, retry the *originally
+  // requested* model a few times with exponential backoff before falling back to a
+  // different (less-preferred) model. Capacity errors are often short-lived, so giving
+  // the preferred model several chances keeps the run on the model the user asked for.
+  // Only once these retries are exhausted do we step to the next-closest fallback model.
+  capacityRetriesBeforeFallback: parseIntWithDefault('HIVE_MIND_CAPACITY_RETRIES_BEFORE_FALLBACK', 5),
+  initialCapacityRetryDelayMs: parseIntWithDefault('HIVE_MIND_INITIAL_CAPACITY_RETRY_DELAY_MS', 15 * 1000), // 15 seconds
+  maxCapacityRetryDelayMs: parseIntWithDefault('HIVE_MIND_MAX_CAPACITY_RETRY_DELAY_MS', 4 * 60 * 1000), // 4 minutes
   // Request timeout retry configuration (Issue #1353)
   // Network timeouts need longer waits than API errors — Claude CLI already exhausted its own retries
   maxRequestTimeoutRetries: parseIntWithDefault('HIVE_MIND_MAX_REQUEST_TIMEOUT_RETRIES', 10),
@@ -341,6 +353,20 @@ export const supportsEffortLevel = model => {
   return isFable5OrMythos5(model) || isMythosPreview(model) || isOpus47OrLater(model) || isOpus46(model) || isSonnet46OrLater(model) || isOpus45(model);
 };
 
+/**
+ * Issue #2038: Check whether a model uses provider-managed adaptive thinking.
+ * Adaptive-only Claude models (Opus 4.7+, Fable 5, Mythos 5, Sonnet 5) manage
+ * their own thinking depth and accept an unset effort/budget as "adaptive".
+ * These are exactly the models for which `--think adaptive` is meaningful; all
+ * other Claude models and non-Claude tools do not expose an adaptive mode.
+ * @param {string} model - The model name or ID
+ * @returns {boolean} True if the model supports adaptive thinking
+ */
+export const supportsAdaptiveThinking = model => {
+  if (!model) return false;
+  return isOpus47OrLater(model) || isFable5OrMythos5(model) || isSonnet5(model);
+};
+
 /**
  * Check if a model supports the xhigh effort level.
  * Official docs list xhigh for Claude Fable 5, Claude Mythos 5, Claude Opus 4.7,
@@ -393,6 +419,7 @@ export const getDefaultMaxThinkingBudgetForModel = model => {
  */
 export const getThinkingLevelToTokens = (maxBudget = DEFAULT_MAX_THINKING_BUDGET) => ({
   off: 0,
+  minimal: Math.floor(maxBudget / 8), // ~4000 for default 31999 (Issue #2038: below `low`)
   low: Math.floor(maxBudget / 4), // ~8000 for default 31999
   medium: Math.floor(maxBudget / 2), // ~16000 for default 31999
   high: Math.floor((maxBudget * 3) / 4), // ~24000 for default 31999
@@ -413,12 +440,14 @@ export const thinkingLevelToTokens = getThinkingLevelToTokens(DEFAULT_MAX_THINKI
 export const getTokensToThinkingLevel = (maxBudget = DEFAULT_MAX_THINKING_BUDGET) => {
   const levels = getThinkingLevelToTokens(maxBudget);
   // Calculate midpoints between levels for range determination
+  const minimalLowMidpoint = Math.floor((levels.minimal + levels.low) / 2);
   const lowMediumMidpoint = Math.floor((levels.low + levels.medium) / 2);
   const mediumHighMidpoint = Math.floor((levels.medium + levels.high) / 2);
   const highMaxMidpoint = Math.floor((levels.high + levels.max) / 2);
 
   return tokens => {
     if (tokens === 0) return 'off';
+    if (tokens <= minimalLowMidpoint) return 'minimal'; // Issue #2038
     if (tokens <= lowMediumMidpoint) return 'low';
     if (tokens <= mediumHighMidpoint) return 'medium';
     if (tokens <= highMaxMidpoint) return 'high';
@@ -505,6 +534,15 @@ export const thinkLevelToEffortLevel = (thinkLevel, options = {}) => {
   const supportsMax = options.supportsMax ?? true;
 
   switch (thinkLevel) {
+    case 'adaptive':
+      // Issue #2038: adaptive requests provider-managed thinking. Claude Code has
+      // no explicit `adaptive` effort value; leaving the effort unset lets the
+      // model manage its own thinking depth (its native adaptive behaviour).
+      return undefined;
+    case 'minimal':
+      // Issue #2038: Claude effort levels start at `low`; `minimal` maps to the
+      // lowest real effort so it stays strictly below `low` in intent but valid.
+      return 'low';
     case 'low':
       return 'low';
     case 'medium':

package/src/gemini.lib.mjs

@@ -19,7 +19,7 @@ const __geminiBuildSolveResumeCmd = (argv, sessionId, tempDir) => (sessionId &&
 import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import { defaultModels, geminiModels } from './models/index.mjs';
 import { checkPlaywrightMcpPackageAvailability } from './playwright-mcp.lib.mjs';
-import { classifyRetryableError, getRetryDelayMs, maybeSwitchToFallbackModel, waitWithCountdown } from './tool-retry.lib.mjs';
+import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { getCumulativeContextInputTokens, toTokenCount } from './context-fill.lib.mjs';
 import { getTerminalEventCompletionHealth } from './tool-run-health.lib.mjs'; // Issue #1990
 
@@ -522,14 +522,21 @@ export const executeGeminiCommand = async params => {
           const isRequestTimeoutRetry = retryableError.label === 'Request timeout';
           const maxRetries = isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
           if (retryCount < maxRetries) {
-            const delay = getRetryDelayMs({
+            // Issue #2037: retry the same model on capacity errors before falling back;
+            // after a capacity-driven model switch, retry quickly instead of waiting the
+            // full transient backoff — the new model may be available now.
+            const retryPlan = await prepareRetryAfterError({
+              tool: 'gemini',
+              argv,
+              log,
+              errorMessage: retryableError.message,
               retryCount,
               initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
               maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
             });
+            const delay = retryPlan.delay;
             const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
             await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel}${sessionId ? ' (session preserved)' : ''}...`, { level: 'warning' });
-            await maybeSwitchToFallbackModel({ tool: 'gemini', argv, log, errorMessage: retryableError.message });
             await waitForRetryDelay(delay, log);
             await log('\n🔄 Retrying now...');
             retryCount++;

package/src/github.lib.mjs

@@ -388,6 +388,9 @@ export async function attachLogToGitHub(options) {
     }
     let totalCostUSD = publicPricingEstimate; // Issue #1225: token usage + actual model IDs
     let actualModelIds = null;
+    // Issue #2037 (review): per-model output-token map, used to report the share of
+    // output tokens produced by the fallback model in the "Models used:" section.
+    let modelUsageForComment = null;
     if (totalCostUSD === null && sessionId && tempDir && !errorMessage) {
       try {
         const { calculateSessionTokens } = await import('./claude.lib.mjs');
@@ -399,6 +402,7 @@ export async function attachLogToGitHub(options) {
           }
           if (tokenUsage.modelUsage && Object.keys(tokenUsage.modelUsage).length > 0) {
             actualModelIds = Object.keys(tokenUsage.modelUsage);
+            modelUsageForComment = tokenUsage.modelUsage;
             if (verbose) await log(`  🤖 Actual models used: ${actualModelIds.join(', ')}`, { verbose: true });
           }
         }
@@ -412,6 +416,7 @@ export async function attachLogToGitHub(options) {
       if (ids.length > 0 && (!actualModelIds || ids.length > actualModelIds.length)) {
         ids.sort((a, b) => (resultModelUsage[b]?.costUSD ?? 0) - (resultModelUsage[a]?.costUSD ?? 0));
         actualModelIds = ids;
+        if (!modelUsageForComment) modelUsageForComment = resultModelUsage;
         if (verbose) await log(`  🤖 Using result JSON modelUsage (${ids.length} models): ${ids.join(', ')}`, { verbose: true });
       }
     }
@@ -431,7 +436,7 @@ export async function attachLogToGitHub(options) {
         // Issue #1949: prefer an explicit thinkingInfo, otherwise derive it from argv
         // (e.g. "high (~24000 tokens)"). null when the run used the tool's default.
         const resolvedThinkingInfo = thinkingInfo ?? describeRequestedThinking(argv);
-        modelInfoString = await getModelInfoForComment({ requestedModel, tool, pricingInfo, actualModelIds, thinkingInfo: resolvedThinkingInfo });
+        modelInfoString = await getModelInfoForComment({ requestedModel, tool, pricingInfo, actualModelIds, thinkingInfo: resolvedThinkingInfo, fallbackModel: argv?.fallbackModel ?? null, modelUsage: modelUsageForComment });
         if (verbose && modelInfoString) {
           await log('  🤖 Model info fetched for comment', { verbose: true });
         }

package/src/hive.config.lib.mjs

@@ -3,7 +3,7 @@
 // when only the yargs configuration is needed (e.g., in telegram-bot.mjs)
 // This module has no heavy dependencies to allow fast loading for --help
 
-import { SOLVE_OPTION_DEFINITIONS } from './solve.config.lib.mjs';
+import { SOLVE_OPTION_DEFINITIONS, normalizeAndValidateThink } from './solve.config.lib.mjs';
 import { buildModelOptionDescription, defaultModels } from './models/index.mjs';
 
 // Hive-only options that are NOT solve options (hive-specific functionality).
@@ -224,6 +224,12 @@ export const createYargsConfig = yargsInstance => {
       'strip-aliased': false,
       'populate--': false,
     })
+    // Issue #2038: normalize/validate --think identically to solve (off synonyms,
+    // minimal, adaptive, percentages/fractions/0|1; fail fast on unsupported adaptive).
+    .check(argv => {
+      normalizeAndValidateThink(argv);
+      return true;
+    })
     .showHelpOnFail(false) // Don't show help on validation failures
     .strict()
     .help('h')

package/src/locales/en.lino

@@ -578,7 +578,7 @@ en
         branch
           option "• `--base-branch <branch>` or `-b` - Target branch for PR (default: repo default branch)"
       think
-        option "• `--think <level>` - Thinking level (off/low/medium/high/xhigh/ultra/max) | `--thinking-budget <num>` - Token budget (0-63999)"
+        option "• `--think <level>` - Thinking level (off/minimal/low/medium/high/xhigh/ultra/max/adaptive) | `--thinking-budget <num>` - Token budget (0-63999)"
       verbose
         option "• `--verbose` or `-v` - Verbose output | `--attach-logs` - Attach logs to PR"
       show

package/src/locales/hi.lino

@@ -578,7 +578,7 @@ hi
         branch
           option "• `--base-branch <branch>` या `-b` - PR के लिए target branch (default: repo default branch)"
       think
-        option "• `--think <level>` - thinking level (off/low/medium/high/xhigh/ultra/max) | `--thinking-budget <num>` - token budget (0-63999)"
+        option "• `--think <level>` - thinking level (off/minimal/low/medium/high/xhigh/ultra/max/adaptive) | `--thinking-budget <num>` - token budget (0-63999)"
       verbose
         option "• `--verbose` या `-v` - verbose output | `--attach-logs` - logs को PR से attach करें"
       show

package/src/locales/ru.lino

@@ -578,7 +578,7 @@ ru
         branch
           option "• `--base-branch <branch>` или `-b` - Целевая ветка для PR (по умолчанию ветка репозитория)"
       think
-        option "• `--think <level>` - уровень размышления (off/low/medium/high/xhigh/ultra/max) | `--thinking-budget <num>` - бюджет токенов (0-63999)"
+        option "• `--think <level>` - уровень размышления (off/minimal/low/medium/high/xhigh/ultra/max/adaptive) | `--thinking-budget <num>` - бюджет токенов (0-63999)"
       verbose
         option "• `--verbose` или `-v` - подробный вывод | `--attach-logs` - прикрепить логи к PR"
       show

package/src/locales/zh.lino

@@ -578,7 +578,7 @@ zh
         branch
           option "• `--base-branch <branch>` 或 `-b` - PR 目标分支（默认：仓库默认分支）"
       think
-        option "• `--think <level>` - 思考级别（off/low/medium/high/xhigh/ultra/max）| `--thinking-budget <num>` - token 预算（0-63999）"
+        option "• `--think <level>` - 思考级别（off/minimal/low/medium/high/xhigh/ultra/max/adaptive）| `--thinking-budget <num>` - token 预算（0-63999）"
       verbose
         option "• `--verbose` 或 `-v` - 详细输出 | `--attach-logs` - 将日志附加到 PR"
       show

package/src/models/index.mjs

@@ -367,9 +367,11 @@ export const getDefaultModelForTool = tool => {
 
 let cachedInstalledCodexModelsPromise = null;
 // Issue #2027: With gpt-5.6-sol as the preferred default, the fallback chain is only
-// consulted when Sol is absent from the local catalog. Prefer the previous stable
-// default (gpt-5.5) first, then the remaining GPT-5.6 preview tiers, then older models.
-const CODEX_DEFAULT_FALLBACK_CHAIN = ['gpt-5.5', 'openai.gpt-5.5', 'gpt-5.6-terra', 'gpt-5.6-luna', 'openai.gpt-5.6-sol', 'openai.gpt-5.6-terra', 'openai.gpt-5.6-luna', 'gpt-5.4', 'openai.gpt-5.4', 'gpt-5.5-mini', 'gpt-5.4-mini', 'gpt-5.3-codex', 'gpt-5.3-codex-spark', 'gpt-5.2', 'gpt-5.2-codex', 'gpt-5.5-nano', 'gpt-5.4-nano'];
+// consulted when Sol is absent from the local catalog. Issue #2037 (review): order by
+// intelligence / size tier (closest first), not by generation — the flagship sibling
+// `gpt-5.6-terra` is closer to Sol than the previous-generation `gpt-5.5`, which in turn
+// is a larger, more capable model than the smaller GPT-5.6 `luna` tier.
+const CODEX_DEFAULT_FALLBACK_CHAIN = ['gpt-5.6-terra', 'openai.gpt-5.6-terra', 'gpt-5.5', 'openai.gpt-5.5', 'gpt-5.4', 'openai.gpt-5.4', 'gpt-5.2', 'gpt-5.6-luna', 'openai.gpt-5.6-luna', 'openai.gpt-5.6-sol', 'gpt-5.5-mini', 'gpt-5.4-mini', 'gpt-5.3-codex', 'gpt-5.3-codex-spark', 'gpt-5.2-codex', 'gpt-5.5-nano', 'gpt-5.4-nano'];
 
 export const getInstalledCodexModels = async () => {
   if (!cachedInstalledCodexModelsPromise) {
@@ -1047,7 +1049,30 @@ const doesRequestedMatchActual = (requestedModel, actualModelId, tool) => {
  * @param {Array<{modelId: string, modelInfo: Object|null}>|null} options.modelsUsed - Actual models used from CLI JSON output
  * @returns {string} Formatted markdown string for model info section
  */
-export const buildModelInfoString = ({ requestedModel = null, tool = null, pricingInfo = null, modelInfo = null, modelsUsed = null, thinkingInfo = null } = {}) => {
+/**
+ * Compute the share (0-100) of total output tokens that a given model produced.
+ * Used to report how much of the run actually ran on the fallback model, so the
+ * PR/issue comment can manage expectations precisely (Issue #2037 review).
+ * @param {Object|null} modelUsage - map of modelId -> { outputTokens } (or output_tokens)
+ * @param {string} modelId - the model whose share to compute
+ * @returns {number|null} integer percentage, or null when no output-token data
+ */
+const computeOutputTokenSharePercent = (modelUsage, modelId) => {
+  if (!modelUsage || typeof modelUsage !== 'object' || !modelId) return null;
+  const target = normalizeForComparison(modelId);
+  let total = 0;
+  let matched = 0;
+  for (const [id, usage] of Object.entries(modelUsage)) {
+    const out = Number(usage?.outputTokens ?? usage?.output_tokens ?? 0) || 0;
+    if (out <= 0) continue;
+    total += out;
+    if (normalizeForComparison(id) === target) matched += out;
+  }
+  if (total <= 0) return null;
+  return Math.round((matched / total) * 100);
+};
+
+export const buildModelInfoString = ({ requestedModel = null, tool = null, pricingInfo = null, modelInfo = null, modelsUsed = null, thinkingInfo = null, fallbackModel = null, modelUsage = null } = {}) => {
   const hasRequested = requestedModel !== null && requestedModel !== undefined;
   const hasModelsUsed = Array.isArray(modelsUsed) && modelsUsed.length > 0;
   const hasModelInfo = modelInfo !== null;
@@ -1090,12 +1115,30 @@ export const buildModelInfoString = ({ requestedModel = null, tool = null, prici
     const mainModelName = mainModelMeta?.name || mainModelId;
     const modelLabel = supportingEntries.length > 0 ? 'Main model' : 'Model';
 
+    // Issue #2037: A mismatch between the requested model and the model that
+    // actually ran happens when the run was downgraded to the configured fallback
+    // model (e.g. Codex reported the requested `gpt-5.6-sol` was "at capacity", so
+    // the retry loop switched to `gpt-5.6-terra`). Even though the fallback did its
+    // job, the user did *not* get the model they asked for in full detail, so this
+    // is still surfaced as a \u26A0\uFE0F warning (Issue #2037 review) \u2014 but a
+    // clearer one that explains it was an automatic capacity fallback rather than an
+    // unexplained mismatch. When output-token data is available we also report the
+    // share of output tokens produced by the fallback model, so expectations are set
+    // precisely.
+    const matchesFallback = hasRequested && !mainMatches && fallbackModel ? doesRequestedMatchActual(fallbackModel, mainModelId, tool) : false;
+
     if (mainMatches) {
       info += `\n- **${modelLabel}: ${mainModelName}** (\`${mainModelId}\`)`;
     } else {
       info += `\n- **${modelLabel}: ${mainModelName}** (\`${mainModelId}\`)`;
       if (hasRequested) {
-        info += `\n- \u26A0\uFE0F **Warning**: Main model \`${mainModelId}\` does not match requested model \`${requestedModel}\``;
+        const sharePercent = computeOutputTokenSharePercent(modelUsage, mainModelId);
+        const shareSuffix = sharePercent !== null ? ` (fallback model produced ${sharePercent}% of output tokens)` : '';
+        if (matchesFallback) {
+          info += `\n- \u26A0\uFE0F **Warning**: Requested model \`${requestedModel}\` was unavailable (at capacity); automatically fell back to \`${mainModelId}\`${shareSuffix}`;
+        } else {
+          info += `\n- \u26A0\uFE0F **Warning**: Main model \`${mainModelId}\` does not match requested model \`${requestedModel}\`${shareSuffix}`;
+        }
       }
     }
 
@@ -1159,14 +1202,25 @@ export const defaultFallbackModels = {
     'claude-sonnet-5': 'sonnet-4-6',
   },
   codex: {
-    'gpt-5.6-sol': 'gpt-5.5',
+    // Issue #2037 (review): order fallbacks by *intelligence / size tier*, not by
+    // generation. Within GPT-5.6, `sol` is the flagship and `terra` is the next tier
+    // down; `luna` is a smaller/cheaper variant. When `gpt-5.6-sol` is at capacity the
+    // closest replacement is `gpt-5.6-terra`, and the next-closest to `gpt-5.6-terra`
+    // is the previous generation's flagship `gpt-5.5` (a larger, more capable model
+    // than the smaller `gpt-5.6-luna`), then `gpt-5.5 -> gpt-5.4 -> gpt-5.2`, and so
+    // on. So the flagship chain walks sol -> terra -> gpt-5.5 -> gpt-5.4 -> gpt-5.2
+    // and never detours through the smaller `luna` tier. The smaller `luna` variant,
+    // if requested directly, steps down to the previous full generation as well.
+    'gpt-5.6-sol': 'gpt-5.6-terra',
     'gpt-5.6-terra': 'gpt-5.5',
     'gpt-5.6-luna': 'gpt-5.5',
-    'openai.gpt-5.6-sol': 'openai.gpt-5.5',
+    'openai.gpt-5.6-sol': 'openai.gpt-5.6-terra',
     'openai.gpt-5.6-terra': 'openai.gpt-5.5',
     'openai.gpt-5.6-luna': 'openai.gpt-5.5',
     'openai.gpt-5.5': 'openai.gpt-5.4',
+    'openai.gpt-5.4': 'openai.gpt-5.2',
     'gpt-5.5': 'gpt-5.4',
+    'gpt-5.4': 'gpt-5.2',
   },
 };
 
@@ -1189,7 +1243,7 @@ export const resolveDefaultFallbackModel = (tool, model) => {
  * @param {Array<string>|null} options.actualModelIds - Actual model IDs from CLI JSON output
  * @returns {Promise<string>} Formatted markdown model info section
  */
-export const getModelInfoForComment = async ({ requestedModel = null, tool = null, pricingInfo = null, actualModelIds = null, thinkingInfo = null } = {}) => {
+export const getModelInfoForComment = async ({ requestedModel = null, tool = null, pricingInfo = null, actualModelIds = null, thinkingInfo = null, fallbackModel = null, modelUsage = null } = {}) => {
   let modelIds = [];
 
   if (Array.isArray(actualModelIds) && actualModelIds.length > 0) {
@@ -1221,5 +1275,7 @@ export const getModelInfoForComment = async ({ requestedModel = null, tool = nul
     modelInfo: modelsUsed.length === 0 ? firstModelInfo : null,
     modelsUsed: modelsUsed.length > 0 ? modelsUsed : null,
     thinkingInfo,
+    fallbackModel,
+    modelUsage,
   });
 };

package/src/opencode.lib.mjs

@@ -23,7 +23,7 @@ import { opencodeModels, defaultModels } from './models/index.mjs';
 import { checkPlaywrightMcpPackageAvailability, getOpenCodePlaywrightMcpDisableEnv } from './playwright-mcp.lib.mjs';
 import { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage as parseOpenCodeTokenUsage } from './agent-token-usage.lib.mjs';
 import { calculateAgentPricing } from './agent.lib.mjs';
-import { classifyRetryableError, getRetryDelayMs, maybeSwitchToFallbackModel, waitWithCountdown } from './tool-retry.lib.mjs';
+import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 
 export { parseOpenCodeTokenUsage };
 
@@ -483,15 +483,22 @@ export const executeOpenCodeCommand = async params => {
           const isRequestTimeoutRetry = retryableError.label === 'Request timeout';
           const maxRetries = isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
           if (retryCount < maxRetries) {
-            const delay = getRetryDelayMs({
+            if (sessionId && !argv.resume) argv.resume = sessionId;
+            // Issue #2037: retry the same model on capacity errors before falling back;
+            // after a capacity-driven model switch, retry quickly instead of waiting the
+            // full transient backoff — the new model may be available now.
+            const retryPlan = await prepareRetryAfterError({
+              tool: 'opencode',
+              argv,
+              log,
+              errorMessage: retryableError.message,
               retryCount,
               initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
               maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
             });
+            const delay = retryPlan.delay;
             const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
             await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel}${sessionId ? ' (session preserved)' : ''}...`, { level: 'warning' });
-            if (sessionId && !argv.resume) argv.resume = sessionId;
-            await maybeSwitchToFallbackModel({ tool: 'opencode', argv, log, errorMessage: retryableError.message });
             await waitForRetryDelay(delay, log);
             await log('\n🔄 Retrying now...');
             retryCount++;

package/src/qwen.lib.mjs

@@ -20,7 +20,7 @@ import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.lib.mjs
 import { sanitizeObjectStrings } from './unicode-sanitization.lib.mjs';
 import { qwenModels, defaultModels } from './models/index.mjs';
 import { checkPlaywrightMcpPackageAvailability } from './playwright-mcp.lib.mjs';
-import { classifyRetryableError, getRetryDelayMs, maybeSwitchToFallbackModel, waitWithCountdown } from './tool-retry.lib.mjs';
+import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { getCumulativeContextInputTokens, getRestoredContextInputTokens, toTokenCount } from './context-fill.lib.mjs';
 import { getTerminalEventCompletionHealth } from './tool-run-health.lib.mjs'; // Issue #1990
 
@@ -599,15 +599,22 @@ export const executeQwenCommand = async params => {
             const isRequestTimeoutRetry = retryableError.label === 'Request timeout';
             const maxRetries = isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutRetries : retryLimits.maxTransientErrorRetries;
             if (retryCount < maxRetries) {
-              const delay = getRetryDelayMs({
+              if (sessionId && !argv.resume) argv.resume = sessionId;
+              // Issue #2037: retry the same model on capacity errors before falling back;
+              // after a capacity-driven model switch, retry quickly instead of waiting the
+              // full transient backoff — the new model may be available now.
+              const retryPlan = await prepareRetryAfterError({
+                tool: 'qwen',
+                argv,
+                log,
+                errorMessage: retryableError.message,
                 retryCount,
                 initialDelayMs: isRequestTimeoutRetry ? retryLimits.initialRequestTimeoutDelayMs : retryLimits.initialTransientErrorDelayMs,
                 maxDelayMs: isRequestTimeoutRetry ? retryLimits.maxRequestTimeoutDelayMs : retryLimits.maxTransientErrorDelayMs,
               });
+              const delay = retryPlan.delay;
               const delayLabel = delay >= 60000 ? `${Math.round(delay / 60000)} min` : `${Math.round(delay / 1000)}s`;
               await log(`\n⚠️ ${retryableError.label} detected. Retry ${retryCount + 1}/${maxRetries} in ${delayLabel}${sessionId ? ' (session preserved)' : ''}...`, { level: 'warning' });
-              if (sessionId && !argv.resume) argv.resume = sessionId;
-              await maybeSwitchToFallbackModel({ tool: 'qwen', argv, log, errorMessage: retryableError.message });
               await waitForRetryDelay(delay, log);
               await log('\n🔄 Retrying now...');
               retryCount++;

package/src/solve.config.lib.mjs

@@ -12,6 +12,9 @@ import { defaultModels, buildModelOptionDescription, resolveDefaultFallbackModel
 import { validateBranchName } from './solve.branch.lib.mjs';
 import { resolveEscalationConfig, isEscalateEnabled, DEFAULT_ESCALATE_RANGE } from './solve.escalate.lib.mjs';
 import { getLinoYargsFactory, hideBin, normalizeCliArgs, parseCliArgumentsWithLino } from './cli-arguments.lib.mjs';
+import { normalizeThinkLevel, ADAPTIVE_THINK_LEVEL } from './think-level.lib.mjs';
+import { supportsAdaptiveThinking } from './config.lib.mjs';
+import { resolvePromptModelForTool } from './thinking-prompt.lib.mjs';
 
 // Re-export for use by telegram-bot.mjs (avoids extra import lines there)
 export { detectMalformedFlags };
@@ -299,8 +302,14 @@ export const SOLVE_OPTION_DEFINITIONS = {
   },
   think: {
     type: 'string',
-    description: 'Thinking level hint. For Claude, translated to --thinking-budget for Claude Code >= 2.1.12 (off=0, low=~8000, medium=~16000, high=~24000, xhigh/ultra/max=31999) and to CLAUDE_CODE_EFFORT_LEVEL when supported. Adaptive-only models that cannot disable thinking use their lowest effort for off. Fable 5/Mythos 5/Sonnet 5/Opus 4.8/4.7 support xhigh and max; Opus 4.6/Sonnet 4.6/Mythos Preview support max; Opus 4.5 uses high for xhigh/max. `ultra` maps to the highest supported Claude effort (Claude "ultracode"-class reasoning). For Codex (GPT-5.6 Sol), mapped 1:1 to reasoning effort (off=none, low=low, medium=medium, high=high, xhigh=xhigh, ultra=ultra, max=max); GPT-5.6 keeps xhigh and adds max above it, and ultra runs the multi-agent mode paired with a rollout token budget cap. Default: off.',
-    choices: ['off', 'low', 'medium', 'high', 'xhigh', 'ultra', 'max'],
+    description:
+      'Thinking level hint. Levels (ascending): off, minimal, low, medium, high, xhigh, ultra, max, plus the special `adaptive` mode. ' +
+      'Off synonyms (all mean disabled, or the closest safe equivalent): off/disable/disabled/no/none. An omitted --think means off. ' +
+      'Numeric intensities are accepted for precision: percentages 0%..100%, fractions 0.0..1.0, and the integers 0 (off) and 1 (max). ' +
+      '`adaptive` requests provider-managed adaptive thinking and fails immediately for models/tools that do not support it (only adaptive-only Claude models: Opus 4.7+, Fable 5, Mythos 5, Sonnet 5). ' +
+      'For Claude, levels translate to --thinking-budget for Claude Code >= 2.1.12 (off=0, minimal=~4000, low=~8000, medium=~16000, high=~24000, xhigh/ultra/max=31999) and to CLAUDE_CODE_EFFORT_LEVEL when supported (minimal→low). Adaptive-only models that cannot disable thinking use their lowest effort for off. ' +
+      '`ultra` maps to the highest supported Claude effort (Claude "ultracode"-class reasoning). ' +
+      'For Codex (GPT-5.6 Sol), mapped 1:1 to reasoning effort (off=none, minimal=minimal, low=low, medium=medium, high=high, xhigh=xhigh, ultra=ultra, max=max); ultra runs the multi-agent mode paired with a rollout token budget cap. Default: off.',
     default: 'off',
   },
   'thinking-budget': {
@@ -335,7 +344,7 @@ export const SOLVE_OPTION_DEFINITIONS = {
   },
   'fallback-model': {
     type: 'string',
-    description: 'Fallback model to switch to on model capacity/overload errors (and, for Fable 5, on safety-classifier refusals). When supported, retries resume the same session with this model. Defaults: claude fable/claude-fable-5 -> opus (Opus 4.8); claude mythos-5/claude-mythos-5 -> fable; claude opus/opus-4-8 -> opus-4-7; claude opus-4-7 -> opus-4-6; codex gpt-5.6-sol/gpt-5.6-terra/gpt-5.6-luna -> gpt-5.5; codex gpt-5.5 -> gpt-5.4; all others unset.',
+    description: 'Fallback model to switch to on model capacity/overload errors (and, for Fable 5, on safety-classifier refusals). When supported, retries resume the same session with this model. An explicit value is pinned exactly; the built-in defaults form a chain that steps to the next-closest model on repeated capacity errors. Defaults: claude fable/claude-fable-5 -> opus (Opus 4.8); claude mythos-5/claude-mythos-5 -> fable; claude opus/opus-4-8 -> opus-4-7; claude opus-4-7 -> opus-4-6; codex gpt-5.6-sol -> gpt-5.6-terra -> gpt-5.6-luna -> gpt-5.5 -> gpt-5.4; all others unset.',
     default: undefined,
   },
   'sub-agent-model': {
@@ -736,6 +745,14 @@ export const createYargsConfig = yargsInstance => {
     .parserConfiguration({
       'boolean-negation': true,
     })
+    // Issue #2038 + #2041: normalize/validate --think during parsing (off synonyms,
+    // minimal, adaptive, percentages/fractions/0|1; fail fast on unsupported adaptive)
+    // so callers that parse via yargs directly (e.g. the Telegram bot) reject invalid
+    // --think values instead of silently accepting them. Mirrors hive.config.
+    .check(argv => {
+      normalizeAndValidateThink(argv);
+      return true;
+    })
     // Use yargs built-in strict mode to reject unrecognized options
     // This prevents issues like #453 and #482 where unknown options are silently ignored
     .strict()
@@ -745,6 +762,42 @@ export const createYargsConfig = yargsInstance => {
   return config;
 };
 
+/**
+ * Issue #2038: Normalize the parsed `--think` value into a single canonical
+ * vocabulary and validate the special `adaptive` mode. Mutates `argv.think` in
+ * place and throws (with `_enhanced` set so the error message is shown verbatim)
+ * for invalid values or unsupported adaptive requests. Shared by solve and hive
+ * so both commands fail fast identically.
+ * @param {Object} argv - Parsed CLI arguments (reads/writes `think`, reads `tool`/`model`)
+ */
+export const normalizeAndValidateThink = argv => {
+  if (!argv) return;
+
+  if (argv.think !== undefined) {
+    try {
+      argv.think = normalizeThinkLevel(argv.think);
+    } catch (thinkError) {
+      const err = new Error(thinkError.message);
+      err._enhanced = true;
+      throw err;
+    }
+  }
+
+  // `--think adaptive` requests provider-managed adaptive thinking and must fail
+  // immediately when the selected tool/model does not support it. Only
+  // adaptive-only Claude models expose an adaptive mode.
+  if (argv.think === ADAPTIVE_THINK_LEVEL) {
+    const tool = argv.tool || 'claude';
+    const resolvedModel = resolvePromptModelForTool(tool, argv.model);
+    const adaptiveSupported = tool === 'claude' && supportsAdaptiveThinking(resolvedModel);
+    if (!adaptiveSupported) {
+      const err = new Error(`--think adaptive is not supported by ${tool}${resolvedModel ? ` model "${resolvedModel}"` : ''}. ` + 'Adaptive thinking is only available on adaptive-only Claude models (Opus 4.7+, Fable 5, Mythos 5, Sonnet 5). ' + 'Use an explicit level instead (off, minimal, low, medium, high, xhigh, ultra, max).');
+      err._enhanced = true;
+      throw err;
+    }
+  }
+};
+
 // Parse command line arguments - now needs yargs and hideBin passed in
 export const parseArguments = async (yargs = getLinoYargsFactory(), hideBinFn = hideBin) => {
   const rawArgs = normalizeCliArgs(hideBinFn(process.argv));
@@ -804,6 +857,14 @@ export const parseArguments = async (yargs = getLinoYargsFactory(), hideBinFn =
       }
     }
   } catch (error) {
+    // Issue #2041: the yargs `.check()` for --think (added to createYargsConfig so
+    // non-CLI consumers like the Telegram bot reject invalid values) throws an
+    // already-enhanced error. Propagate it verbatim instead of swallowing it into
+    // `error.argv`, otherwise the CLI would silently drop the invalid --think and
+    // crash later during normalization.
+    if (error && error._enhanced && !(error.message && /Unknown argument/.test(error.message))) {
+      throw error;
+    }
     // Yargs throws errors for validation issues
     // If the error is about unknown arguments (strict mode), enhance it with suggestions
     // Check if this error has already been enhanced to avoid re-processing
@@ -852,6 +913,12 @@ export const parseArguments = async (yargs = getLinoYargsFactory(), hideBinFn =
     argv.think = undefined;
   }
 
+  // Issue #2038: normalize the --think value into a single canonical vocabulary
+  // (off synonyms, minimal, adaptive, percentages/fractions/0|1) and fail fast on
+  // an unsupported `adaptive` request. Shared by solve and hive so both commands
+  // behave identically.
+  normalizeAndValidateThink(argv);
+
   // --plan flag expansion (Issue #1223)
   // When --plan is set, it acts as a shortcut for --plan-model opus --worker-model sonnet
   // Explicit --plan-model and --model/--worker-model values take precedence
@@ -995,6 +1062,11 @@ export const parseArguments = async (yargs = getLinoYargsFactory(), hideBinFn =
     const defaultFallbackModel = resolveDefaultFallbackModel(argv.tool, argv.model);
     argv.fallbackModel = defaultFallbackModel || undefined;
   }
+  // Issue #2037 (review): remember whether the fallback model was pinned by the user.
+  // An explicit --fallback-model is honoured exactly and never walked past; an
+  // implicit (default) fallback is allowed to step down the full default chain on
+  // repeated capacity errors. See resolveConfiguredFallbackModel().
+  argv._fallbackModelExplicit = fallbackModelExplicitlyProvided;
 
   // Validate mutual exclusivity of --claude-file and --gitkeep-file
   // Check if both are explicitly enabled (user passed both --claude-file and --gitkeep-file)

package/src/think-level.lib.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+/**
+ * Issue #2038: Canonical normalization of the `--think` option.
+ *
+ * The `--think` flag historically accepted only a small fixed set of keyword
+ * levels (off/low/medium/high/xhigh/ultra/max). Issue #2038 requires a much
+ * richer and more forgiving surface, mapped consistently across Claude and
+ * Codex:
+ *
+ *   1. A family of synonyms that all mean "off" (thinking disabled, or the
+ *      closest safe equivalent when a model cannot truly disable thinking):
+ *      `off`, `disable`, `disabled`, `no`, `none`, `false`.
+ *   2. A `minimal` level (below `low`) mapped to the lowest real reasoning
+ *      effort each tool supports (Codex `minimal`, Claude lowest effort).
+ *   3. An explicit `adaptive` level that requests provider-managed adaptive
+ *      thinking and MUST fail fast for models/tools that do not support it.
+ *   4. Numeric intensities so users can dial precision:
+ *        - percentages `0%` .. `100%`
+ *        - fractions   `0.0` .. `1.0`
+ *        - the integers `0` and `1`
+ *      `0`/`0%`/`0.0` == off and `1`/`100%`/`1.0` == max.
+ *
+ * `normalizeThinkLevel()` folds every accepted spelling into one canonical
+ * level so the rest of the codebase keeps operating on a single vocabulary.
+ */
+
+// Canonical think levels in ascending intensity order. `adaptive` is a distinct
+// mode (provider-managed), not a point on the numeric intensity scale, so it is
+// listed separately and never produced by numeric coercion.
+export const CANONICAL_THINK_LEVELS = Object.freeze(['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'ultra', 'max']);
+
+export const ADAPTIVE_THINK_LEVEL = 'adaptive';
+
+// Keyword synonyms → canonical level. All the "off" spellings are synonyms per
+// the issue title, and an omitted `--think` is treated as `off` elsewhere.
+const THINK_LEVEL_SYNONYMS = Object.freeze({
+  off: 'off',
+  disable: 'off',
+  disabled: 'off',
+  no: 'off',
+  none: 'off',
+  false: 'off',
+  min: 'minimal',
+  minimal: 'minimal',
+  low: 'low',
+  medium: 'medium',
+  med: 'medium',
+  high: 'high',
+  xhigh: 'xhigh',
+  'x-high': 'xhigh',
+  ultra: 'ultra',
+  max: 'max',
+  maximum: 'max',
+  full: 'max',
+  adaptive: 'adaptive',
+  auto: 'adaptive',
+});
+
+/**
+ * Map a fraction in [0, 1] to a canonical intensity level.
+ * 0 → off, 1 → max, with evenly spaced bands in between. Never returns the
+ * out-of-band `ultra` (multi-agent) or `adaptive` modes.
+ * @param {number} fraction
+ * @returns {string}
+ */
+export const fractionToThinkLevel = fraction => {
+  if (!Number.isFinite(fraction) || fraction <= 0) return 'off';
+  if (fraction < 0.2) return 'minimal';
+  if (fraction < 0.4) return 'low';
+  if (fraction < 0.6) return 'medium';
+  if (fraction < 0.8) return 'high';
+  if (fraction < 1) return 'xhigh';
+  return 'max';
+};
+
+/**
+ * Parse a numeric think value (percentage, fraction, or 0/1 integer) into a
+ * fraction in [0, 1], or return null when the value is not numeric.
+ * @param {string} raw
+ * @returns {number|null}
+ */
+export const parseNumericThinkValue = raw => {
+  const text = String(raw).trim();
+  const percentMatch = /^([0-9]+(?:\.[0-9]+)?)\s*%$/.exec(text);
+  if (percentMatch) {
+    return Math.min(1, Math.max(0, Number(percentMatch[1]) / 100));
+  }
+  if (/^[0-9]+(?:\.[0-9]+)?$/.exec(text)) {
+    const num = Number(text);
+    // Bare integers greater than 1 are treated as a 0..100 style percentage so
+    // `--think 50` behaves like `--think 50%`; 0 and 1 stay canonical fraction
+    // endpoints (off and max).
+    if (num > 1) return Math.min(1, num / 100);
+    return Math.min(1, Math.max(0, num));
+  }
+  return null;
+};
+
+/**
+ * Normalize any accepted `--think` spelling into a canonical level.
+ * @param {string|number|undefined|null} raw
+ * @returns {string|undefined} canonical level, ADAPTIVE_THINK_LEVEL, or
+ *   undefined when input is empty. Throws for unrecognized values.
+ */
+export const normalizeThinkLevel = raw => {
+  if (raw === undefined || raw === null || raw === '') return undefined;
+
+  // Already-canonical (e.g. re-normalization) short circuit.
+  if (typeof raw === 'string') {
+    const lowered = raw.trim().toLowerCase();
+    if (lowered === '') return undefined;
+
+    if (Object.prototype.hasOwnProperty.call(THINK_LEVEL_SYNONYMS, lowered)) {
+      return THINK_LEVEL_SYNONYMS[lowered];
+    }
+
+    const fraction = parseNumericThinkValue(lowered);
+    if (fraction !== null) {
+      return fractionToThinkLevel(fraction);
+    }
+
+    throw new Error(`Invalid --think value: "${raw}". Use a level (${CANONICAL_THINK_LEVELS.join(', ')}, adaptive), ` + `an off synonym (off/disable/disabled/no/none), a percentage (0%..100%), or a fraction (0.0..1.0).`);
+  }
+
+  if (typeof raw === 'number') {
+    const fraction = raw > 1 ? Math.min(1, raw / 100) : Math.min(1, Math.max(0, raw));
+    return fractionToThinkLevel(fraction);
+  }
+
+  throw new Error(`Invalid --think value: "${raw}".`);
+};
+
+export default {
+  CANONICAL_THINK_LEVELS,
+  ADAPTIVE_THINK_LEVEL,
+  normalizeThinkLevel,
+  fractionToThinkLevel,
+  parseNumericThinkValue,
+};

package/src/thinking-prompt.lib.mjs

@@ -4,6 +4,7 @@ import { supportsEffortLevel, supportsThinkingBudget } from './config.lib.mjs';
 import { defaultModels, mapModelForTool } from './models/index.mjs';
 
 export const THINK_PROMPT_MESSAGES = Object.freeze({
+  minimal: 'Think.',
   low: 'Think.',
   medium: 'Think hard.',
   high: 'Think harder.',

package/src/tool-retry.lib.mjs

@@ -199,8 +199,30 @@ export const waitWithCountdown = async (delayMs, log) => {
   clearInterval(timer);
 };
 
-export const resolveConfiguredFallbackModel = ({ tool, currentModel, configuredFallbackModel = undefined } = {}) => {
-  if (configuredFallbackModel) return configuredFallbackModel;
+// Issue #2037 (review): Support a *multi-level* fallback chain (e.g.
+// gpt-5.6-sol -> gpt-5.6-terra -> gpt-5.6-luna -> gpt-5.5 -> gpt-5.4) so repeated
+// capacity errors keep stepping to the next-closest model instead of getting stuck
+// on the first fallback. `configuredFallbackModel` (from --fallback-model, or the
+// default resolved once at config time) is honoured only while it still differs from
+// the current model; once the run has already switched onto it, we resolve the next
+// hop from the default chain of the *current* model. An explicitly user-pinned
+// fallback (`explicit: true`) is never walked past — the user chose that model on
+// purpose, so it stays put.
+export const resolveConfiguredFallbackModel = ({ tool, currentModel, configuredFallbackModel = undefined, explicit = false } = {}) => {
+  // A user-pinned fallback (--fallback-model) is honoured as-is and never walked
+  // past: the user chose that exact model on purpose. Return it while it still
+  // differs from the current model; once the run is already on it, stop switching.
+  if (explicit && configuredFallbackModel) {
+    const current = normalizeModelKey(resolveModelId(currentModel, tool));
+    const configured = normalizeModelKey(resolveModelId(configuredFallbackModel, tool));
+    if (configured && configured !== current) return configuredFallbackModel;
+    return null;
+  }
+  // Otherwise resolve the next hop from the default chain of the *current* model,
+  // so repeated capacity errors walk the whole chain
+  // (e.g. gpt-5.6-sol -> gpt-5.6-terra -> gpt-5.6-luna -> gpt-5.5 -> gpt-5.4).
+  // The auto-set argv.fallbackModel is intentionally ignored here — it only ever
+  // holds the first default hop and would otherwise pin the chain to one step.
   return resolveDefaultFallbackModel(tool, currentModel);
 };
 
@@ -237,6 +259,7 @@ export const maybeSwitchToFallbackModel = async ({ tool, argv, log, errorMessage
     tool,
     currentModel: argv?.model,
     configuredFallbackModel: argv?.fallbackModel,
+    explicit: argv?._fallbackModelExplicit === true,
   });
 
   const classification = classifyRetryableError(errorMessage);
@@ -262,7 +285,12 @@ export const maybeSwitchToFallbackModel = async ({ tool, argv, log, errorMessage
 
   const previousModel = argv.model;
   argv.model = fallbackModel;
-  if (!argv.fallbackModel) argv.fallbackModel = fallbackModel;
+  // Issue #2037 (review): record the model we actually switched to as the current
+  // fallback target. For a multi-hop chain (sol -> terra -> luna -> ...) this keeps
+  // argv.fallbackModel pointing at the model that is now running, so the PR comment
+  // correctly reports it as the automatic capacity fallback. An explicit user pin
+  // already equals `fallbackModel` here, so this is a no-op in that case.
+  argv.fallbackModel = fallbackModel;
 
   if (typeof log === 'function') {
     // Issue #1949: show the resolved full model IDs so the switch is unambiguous,
@@ -278,12 +306,51 @@ export const maybeSwitchToFallbackModel = async ({ tool, argv, log, errorMessage
   };
 };
 
+// Issue #2037 (review): Unified retry planner shared by every tool's retry loop.
+// On a genuine "model is at capacity" error it first retries the *originally
+// requested* model up to `capacityRetriesBeforeFallback` times with exponential
+// backoff — capacity errors are often short-lived, so the preferred model gets
+// several chances before we downgrade. Only once those same-model retries are
+// exhausted does it switch to the next-closest fallback model (fast 5s retry).
+// Non-capacity transient errors keep the current model and use the caller's
+// standard backoff, exactly as before.
+//
+// The same-model capacity retry count is stored on `argv._capacityRetryCount` so it
+// survives the recursive executeWithRetry calls without each tool tracking extra
+// state. It resets to 0 whenever we actually switch models, so every model in the
+// fallback chain gets its own batch of same-model retries before stepping down.
+export const prepareRetryAfterError = async ({ tool, argv, log, errorMessage, retryCount, initialDelayMs, maxDelayMs } = {}) => {
+  const classification = classifyRetryableError(errorMessage);
+  const isCapacity = classification.isCapacity === true && !!argv?.model;
+  const capacityRetryCount = argv?._capacityRetryCount || 0;
+
+  if (isCapacity && capacityRetryCount < retryLimits.capacityRetriesBeforeFallback) {
+    if (argv) argv._capacityRetryCount = capacityRetryCount + 1;
+    const delay = getRetryDelayMs({
+      retryCount: capacityRetryCount,
+      initialDelayMs: retryLimits.initialCapacityRetryDelayMs,
+      maxDelayMs: retryLimits.maxCapacityRetryDelayMs,
+    });
+    if (typeof log === 'function') {
+      await log(`   Model ${formatModelWithResolvedId(argv.model, tool)} at capacity — retrying same model (attempt ${capacityRetryCount + 1}/${retryLimits.capacityRetriesBeforeFallback}) before falling back`, { level: 'warning' });
+    }
+    return { delay, switched: false };
+  }
+
+  const switchResult = await maybeSwitchToFallbackModel({ tool, argv, log, errorMessage });
+  // A model switch starts a fresh batch of same-model retries for the new model.
+  if (switchResult?.switched && argv) argv._capacityRetryCount = 0;
+  const delay = switchResult?.switched ? retryLimits.modelSwitchRetryDelayMs : getRetryDelayMs({ retryCount, initialDelayMs, maxDelayMs });
+  return { delay, switched: switchResult?.switched === true };
+};
+
 export default {
   classifyRetryableError,
   getRetryDelayMs,
   waitWithCountdown,
   resolveConfiguredFallbackModel,
   maybeSwitchToFallbackModel,
+  prepareRetryAfterError,
   formatModelWithResolvedId,
   logExecutionContext,
 };