@link-assistant/hive-mind 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @link-assistant/hive-mind
 
+## 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.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/claude.lib.mjs

@@ -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) {

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

@@ -341,6 +341,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 +407,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 +428,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 +522,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/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/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': {
@@ -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

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.',