ai-consultants 3.0.0 → 3.2.0

package/docs/releases/v3.2.0.md

@@ -0,0 +1,96 @@
+# Release v3.2.0
+
+**Date:** 2026-07-25
+**Type:** Minor — Claude moves to Opus 5 with adaptive-thinking-safe transports and billing
+**Previous:** v3.1.1
+
+## Highlights
+
+- **Claude now uses `claude-opus-5` as its premium default** across direct configuration, model tiers, documentation, and cost tracking.
+- **Claude CLI costs now come directly from the provider**, including adaptive thinking and cache charges that are absent from the visible answer.
+- **Anthropic API thinking blocks are handled correctly**, and responses truncated by the shared thinking/output budget are rejected instead of synthesized as complete.
+- **Existing generated Opus 4.8 defaults migrate to Opus 5**, while explicit model pins are recorded and preserved.
+- **Opus 4.8 remains supported** for historical responses and intentional overrides.
+
+## What's New
+
+### Opus 5 premium default
+
+The Claude consultant, premium/max/best quality tier, standalone adapter fallback, examples, and cost catalog now use the canonical `claude-opus-5` model ID. Standard and economy tiers remain on Claude Sonnet 4.6 and Haiku 4.5.
+
+Opus 5 retains the previous $5 per million input tokens and $25 per million output tokens. The legacy Opus 4.8 rates remain available so historical sessions and pinned installations continue to be priced correctly.
+
+### Exact Claude CLI usage and cost
+
+Claude CLI mode now requests its JSON result envelope. AI Consultants extracts:
+
+- the visible answer from `.result`;
+- measured input, cache, and output usage from `modelUsage`;
+- the provider-reported `costUSD`.
+
+The exact provider cost takes precedence over local token-rate reconstruction. This includes adaptive-thinking and cache charges even though those tokens do not appear in the visible answer.
+
+### Adaptive-thinking-safe API mode
+
+Anthropic responses may place a thinking block before one or more visible text blocks. The parser now collects every visible `type=text` block instead of assuming the first content block contains the answer.
+
+The new `CLAUDE_API_MAX_TOKENS` setting defaults to 16,384 tokens. Anthropic counts adaptive thinking and visible output against this shared budget. If the provider returns `stop_reason=max_tokens`, the consultation fails as truncated rather than entering synthesis as a complete response.
+
+### Managed configuration migration
+
+Older `ai-consultants init` templates wrote the then-current Opus 4.8 default as an ordinary value. Running `ai-consultants configure` now recognizes that exact historical generated default, upgrades it to Opus 5, and records managed provenance.
+
+Explicit model choices are written with an `# ai-consultants:pin` marker and survive subsequent configuration refreshes.
+
+## Breaking Changes
+
+None — this release is backwards-compatible. Opus 4.8 remains selectable and priced.
+
+If `CLAUDE_MODEL=claude-opus-4-8` was an intentional unmarked override rather than the generated default, reassert it once after upgrading:
+
+```bash
+ai-consultants configure --set CLAUDE_MODEL=claude-opus-4-8
+```
+
+## Upgrade Guide
+
+```bash
+# If installed via git clone
+cd ~/.claude/skills/ai-consultants && git pull
+
+# If installed via curl | bash
+curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/scripts/install.sh | bash
+
+# If used through npx
+npx ai-consultants@latest "your question"
+```
+
+Refresh persistent configuration so a historical generated Opus 4.8 value migrates:
+
+```bash
+ai-consultants configure
+ai-consultants doctor
+```
+
+API users may override the shared thinking/output budget if needed:
+
+```bash
+ai-consultants configure --set CLAUDE_API_MAX_TOKENS=32768
+```
+
+## Verification
+
+- Full repository gate: 17/17 suites
+- Core suite: 299/299 checks
+- Claude CLI JSON/cost regression suite: 6/6 checks
+- Anthropic transport regression suite: 48/48 checks
+- Shellcheck and release-surface validation
+- Live local Claude CLI JSON envelope verified with `claude-opus-5`
+
+## Commits
+
+- `3963c3c` feat: upgrade Claude consultant to Opus 5
+
+## Contributors
+
+- Matteo Scurati

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-consultants",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "A harness for every question - a panel of up to 11 AI models that picks its own deliberation strategy per question (convergence, adversarial verification, tournament) and checks its work before answering",
   "bin": {
     "ai-consultants": "bin/ai-consultants"

package/references/configuration.md

@@ -54,6 +54,11 @@ ai-consultants configure --dry-run
 Use the hidden interactive credential prompts (or exported environment variables)
 for API keys; command-line arguments may be visible in shell history and process
 inspection.
+Model defaults carry an `# ai-consultants:default` marker. On rewrite,
+`configure` upgrades the historical unmarked
+`CLAUDE_MODEL=claude-opus-4-8` generated default to Opus 5. An explicit model
+override supplied with `--set` is stored with `# ai-consultants:pin`, so
+`--set CLAUDE_MODEL=claude-opus-4-8` keeps the legacy model intentionally.
 The exhaustive parameter contract is [`.env.example`](../.env.example); the
 configurator derives its accepted keys from that template, while
 [`scripts/config.sh`](../scripts/config.sh) remains the runtime source of truth.
@@ -182,7 +187,7 @@ override it.
 
 ## CLI/API Mode Switching (v2.6+)
 
-Six consultants support switching between CLI and API mode. **The default is the CLI** for every consultant that has one — API mode is opt-in (for CLI-less models or an explicit choice). When API mode is enabled, the CLI is not used.
+Seven consultants support switching between CLI and API mode. **The default is the CLI** for every consultant that has one. Grok additionally falls back to the xAI API after a failed CLI launch when a key is available. When API mode is explicitly enabled, the CLI is not used.
 
 **Gemini auto-resolution (v2.15.1):** leave `GEMINI_USE_API` unset and the mode is chosen for you — API mode when `GEMINI_API_KEY` is present (no `agy` install or OAuth needed; ideal for `npx`), CLI mode (`agy`) otherwise. Set `GEMINI_USE_API` explicitly only to force a mode (an explicit value disables auto-detection).
 
@@ -193,6 +198,7 @@ CODEX_USE_API=false          # Use OpenAI API instead of codex CLI
 CLAUDE_USE_API=false         # Use Anthropic API instead of claude CLI
 MISTRAL_USE_API=false        # Use Mistral API instead of vibe CLI
 QWEN3_USE_API=false          # Use qwen CLI (default) or DashScope API
+GROK_USE_API=false           # Use Grok Build (default); API is fallback
 MINIMAX_USE_API=false        # Use mmx CLI (default) or MiniMax API
 ```
 
@@ -207,7 +213,7 @@ MINIMAX_USE_API=false        # Use mmx CLI (default) or MiniMax API
 | Qwen3 | `QWEN3_API_KEY` | DashScope API key |
 | MiniMax | `MINIMAX_API_KEY` | MiniMax API key (API mode only; the mmx CLI uses OAuth) |
 | GLM | `GLM_API_KEY` | Required when `ENABLE_GLM=true` |
-| Grok | `GROK_API_KEY` | Required when `ENABLE_GROK=true` |
+| Grok | `GROK_API_KEY` | xAI API fallback key; Grok Build CLI uses its own login |
 | DeepSeek | `DEEPSEEK_API_KEY` | Required when `ENABLE_DEEPSEEK=true` |
 
 ## Consultant Toggles and Models
@@ -220,12 +226,12 @@ ENABLE_MISTRAL=true
 ENABLE_CURSOR=true
 ENABLE_KIMI=true             # Kimi CLI - The Eastern Sage
 ENABLE_QWEN3=true            # Qwen CLI/API - The Analyst
+ENABLE_GROK=true             # Grok Build CLI/API fallback - The Provocateur
 ENABLE_MINIMAX=true          # MiniMax CLI/API (mmx) - The Pragmatic Optimizer
 ENABLE_CLAUDE=true           # Claude CLI - The Synthesizer (auto-excluded under Claude Code)
 
 # API-only consultants (off by default - require API keys)
 ENABLE_GLM=false
-ENABLE_GROK=false
 ENABLE_DEEPSEEK=false
 ```
 
@@ -234,7 +240,8 @@ ENABLE_DEEPSEEK=false
 ```bash
 GEMINI_MODEL=Gemini 3.1 Pro (High)   # agy CLI display name; API mode uses GEMINI_API_MODEL
 CODEX_MODEL=gpt-5.5
-CLAUDE_MODEL=claude-opus-4-8
+CLAUDE_MODEL=claude-opus-5
+CLAUDE_API_MAX_TOKENS=16384  # API only: adaptive thinking + visible output
 MISTRAL_MODEL=mistral-large-3
 CURSOR_MODEL=composer-2.5
 KIMI_MODEL=kimi-code/k3
@@ -245,6 +252,19 @@ DEEPSEEK_MODEL=deepseek-v4-pro
 MINIMAX_MODEL=MiniMax-M2.7
 ```
 
+Anthropic counts adaptive thinking and visible response tokens against the same
+`CLAUDE_API_MAX_TOKENS` limit. The default is 16,384; a response that reaches
+that limit is rejected as truncated instead of entering synthesis as a complete
+answer.
+
+`GROK_MODEL` is passed explicitly to `grok -m`. The default transport is the
+headless Grok Build CLI using a private `--prompt-file` inside an isolated,
+tool-free strict sandbox. If the CLI is missing, cannot execute, or has no
+usable authentication, the same query and model fall back to `GROK_API_URL`
+when `GROK_API_KEY` is set. Failures after a request launches (including
+timeouts, model errors, and empty output) are returned without API fallback.
+Set `GROK_USE_API=true` only to force the API path.
+
 `KIMI_MODEL` is passed directly to `kimi --model`, so `kimi-code/k3` overrides
 any older default stored in the user's Kimi CLI configuration.
 

package/scripts/config.sh

@@ -64,12 +64,12 @@ DEFAULT_OUTPUT_DIR_BASE="${DEFAULT_OUTPUT_DIR_BASE:-${_AI_CONSULTANTS_XDG_CACHE}
 # =============================================================================
 # For agents that support both CLI and API mode, set USE_API=true to use API mode.
 # When API mode is enabled, CLI mode is automatically disabled (mutual exclusivity).
-# 6 agents support switching: Gemini, Codex, Claude, Mistral, Qwen3, MiniMax
+# 7 agents support switching: Gemini, Codex, Claude, Mistral, Qwen3, Grok, MiniMax
 
 # Mode switching (true = API, false = CLI). DEFAULT IS CLI — when a consultant
 # has a CLI, the tool uses it; the CLIs are the primary transport (OAuth /
 # subscription, no API key needed). API mode is opt-in only: for CLI-less models
-# (GLM/Grok/DeepSeek are API-only anyway) or an explicit per-run user
+# (GLM/DeepSeek are API-only) or an explicit per-run user
 # choice. Set a switch to true (with its API key) to force API for that agent.
 # GEMINI_USE_API is intentionally NOT defaulted here: it is auto-resolved in the
 # Gemini configuration section below (needs GEMINI_API_KEY / GEMINI_CMD), so an
@@ -78,6 +78,8 @@ CODEX_USE_API="${CODEX_USE_API:-false}"
 CLAUDE_USE_API="${CLAUDE_USE_API:-false}"
 MISTRAL_USE_API="${MISTRAL_USE_API:-false}"
 QWEN3_USE_API="${QWEN3_USE_API:-false}"  # Default false to use qwen CLI
+# GROK_USE_API is intentionally resolved in the Grok section: it is CLI-first,
+# but must preserve an API-only installation when Grok Build is unavailable.
 # MINIMAX_USE_API is intentionally NOT defaulted here: it is auto-resolved in the
 # MiniMax configuration section below (needs MINIMAX_API_KEY), so an explicit
 # unset stays distinguishable from an explicit "false" (back-compat for pre-v2.21
@@ -186,14 +188,32 @@ GLM_FORMAT="${GLM_FORMAT:-openai}"
 # API key: Set GLM_API_KEY environment variable
 
 # =============================================================================
-# GROK CONFIGURATION - The Provocateur (API-based)
+# GROK CONFIGURATION - The Provocateur (Grok Build CLI + API fallback)
 # =============================================================================
 
+GROK_CMD="${GROK_CMD:-grok}"
 GROK_MODEL="${GROK_MODEL:-grok-4.5}"
 GROK_TIMEOUT_SECONDS="${GROK_TIMEOUT:-180}"
 GROK_API_URL="${GROK_API_URL:-https://api.x.ai/v1/chat/completions}"
 GROK_FORMAT="${GROK_FORMAT:-openai}"
-# API key: Set GROK_API_KEY environment variable
+# Grok Build's official credential name is XAI_API_KEY. Keep the historical
+# GROK_API_KEY public contract and accept XAI_API_KEY as its fallback alias.
+GROK_API_KEY="${GROK_API_KEY:-${XAI_API_KEY:-}}"
+export GROK_API_KEY
+
+# CLI-first auto-resolution. Existing users can still pin GROK_USE_API=true,
+# while an unpinned setup uses the CLI whenever it is installed and falls back
+# to the API when only a key is available.
+if [[ -z "${GROK_USE_API+x}" ]]; then
+    if command -v "$GROK_CMD" >/dev/null 2>&1; then
+        GROK_USE_API=false
+    elif [[ -n "$GROK_API_KEY" ]]; then
+        GROK_USE_API=true
+    else
+        GROK_USE_API=false
+    fi
+fi
+export GROK_USE_API
 
 # =============================================================================
 # DEEPSEEK CONFIGURATION - The Methodologist (API-based)
@@ -251,7 +271,8 @@ KIMI_CMD="${KIMI_CMD:-kimi}"
 # CLAUDE CONFIGURATION - The Synthesizer (v2.2)
 # =============================================================================
 
-CLAUDE_MODEL="${CLAUDE_MODEL:-claude-opus-4-8}"
+CLAUDE_MODEL="${CLAUDE_MODEL:-claude-opus-5}"
+CLAUDE_API_MAX_TOKENS="${CLAUDE_API_MAX_TOKENS:-16384}"
 CLAUDE_TIMEOUT_SECONDS="${CLAUDE_TIMEOUT:-240}"
 CLAUDE_CMD="${CLAUDE_CMD:-claude}"
 
@@ -265,10 +286,10 @@ CLAUDE_CMD="${CLAUDE_CMD:-claude}"
 ALL_CONSULTANTS=("Gemini" "Codex" "Mistral" "Cursor" "Kimi" "Claude" "Qwen3" "GLM" "Grok" "DeepSeek" "MiniMax")
 
 # CLI-based consultants (use CLI tools, some support CLI/API switching)
-CLI_CONSULTANTS=("Gemini" "Codex" "Mistral" "Cursor" "Kimi" "Claude" "Qwen3" "MiniMax")
+CLI_CONSULTANTS=("Gemini" "Codex" "Mistral" "Cursor" "Kimi" "Claude" "Qwen3" "Grok" "MiniMax")
 
 # API-only consultants (use HTTP API directly, no CLI available)
-API_CONSULTANTS=("GLM" "Grok" "DeepSeek")
+API_CONSULTANTS=("GLM" "DeepSeek")
 
 # =============================================================================
 # ENABLED CONSULTANTS
@@ -283,11 +304,11 @@ ENABLE_CURSOR="${ENABLE_CURSOR:-true}"
 ENABLE_KIMI="${ENABLE_KIMI:-true}"       # Kimi Code (v2.9)
 ENABLE_CLAUDE="${ENABLE_CLAUDE:-true}"   # Auto-disabled when invoked by Claude Code
 ENABLE_QWEN3="${ENABLE_QWEN3:-true}"     # qwen-code CLI (v2.7); API opt-in
+ENABLE_GROK="${ENABLE_GROK:-true}"       # Grok Build CLI; API fallback
 ENABLE_MINIMAX="${ENABLE_MINIMAX:-true}" # mmx CLI (v2.21); API opt-in
 
 # API-only consultants (disabled by default - require API keys)
 ENABLE_GLM="${ENABLE_GLM:-false}"
-ENABLE_GROK="${ENABLE_GROK:-false}"
 ENABLE_DEEPSEEK="${ENABLE_DEEPSEEK:-false}"
 
 # =============================================================================
@@ -561,7 +582,7 @@ get_model_for_tier() {
     case "$tier" in
         premium|max|best)
             case "$consultant" in
-                claude)   echo "claude-opus-4-8" ;;
+                claude)   echo "claude-opus-5" ;;
                 gemini)   echo "Gemini 3.1 Pro (High)" ;;
                 codex)    echo "gpt-5.5" ;;
                 mistral)  echo "mistral-large-3" ;;
@@ -758,4 +779,4 @@ EOF
 # VERSION
 # =============================================================================
 
-AI_CONSULTANTS_VERSION="3.0.0"
+AI_CONSULTANTS_VERSION="3.2.0"

package/scripts/configure.sh

@@ -181,6 +181,25 @@ set_value() {
 }
 
 AUTO_MARKER="# ai-consultants:auto"
+DEFAULT_MARKER="# ai-consultants:default"
+PIN_MARKER="# ai-consultants:pin"
+
+has_value_marker() {
+    local file="$1" key="$2" marker="$3" line normalized
+    [[ -r "$file" ]] || return 1
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        line="${line%$'\r'}"
+        [[ "$line" =~ ^[[:space:]]*# ]] && continue
+        normalized="${line#"${line%%[![:space:]]*}"}"
+        if [[ "$normalized" =~ ^export[[:space:]]+ ]]; then
+            normalized="${normalized#export}"
+            normalized="${normalized#"${normalized%%[![:space:]]*}"}"
+        fi
+        [[ "$normalized" == "$key="* ]] || continue
+        [[ "$normalized" == *"$marker"* ]] && return 0
+    done < "$file"
+    return 1
+}
 
 is_auto_managed_value() {
     local file="$1" key="$2" line normalized raw="" seen=false
@@ -239,13 +258,33 @@ set_auto_value() {
 # Merge existing persistent values first, then current environment overrides.
 while IFS= read -r key; do
     if [[ -f "$OUTPUT_FILE" ]] && value=$(read_value "$OUTPUT_FILE" "$key"); then
-        set_value "$key" "$value"
+        if has_value_marker "$OUTPUT_FILE" "$key" "$DEFAULT_MARKER"; then
+            set_value "$key" "$value $DEFAULT_MARKER"
+        elif has_value_marker "$OUTPUT_FILE" "$key" "$PIN_MARKER"; then
+            set_value "$key" "$value $PIN_MARKER"
+        else
+            set_value "$key" "$value"
+        fi
     fi
     if [[ -n "${!key+x}" ]]; then
-        set_value "$key" "${!key}"
+        if [[ "$key" == *_MODEL ]]; then
+            set_value "$key" "${!key} $PIN_MARKER"
+        else
+            set_value "$key" "${!key}"
+        fi
     fi
 done < <(list_parameters)
 
+# Before model defaults had provenance markers, `init` copied the then-current
+# Claude default as an ordinary-looking value. Refresh that exact historical
+# default when configure rewrites the file. A real legacy pin is preserved by
+# `--set CLAUDE_MODEL=claude-opus-4-8`, which records the pin marker.
+if [[ "$(read_value "$WORK_FILE" CLAUDE_MODEL 2>/dev/null || true)" == "claude-opus-4-8" ]] \
+    && ! has_value_marker "$WORK_FILE" CLAUDE_MODEL "$PIN_MARKER"; then
+    set_value CLAUDE_MODEL "claude-opus-5 $DEFAULT_MARKER"
+    echo "Migrated managed Claude default: claude-opus-4-8 -> claude-opus-5" >&2
+fi
+
 configure_cli_only() {
     local enable_key="$1" cmd_key="$2" cmd enabled=false
     cmd=$(effective_input_value "$cmd_key")
@@ -307,9 +346,9 @@ run_auto_detection() {
     configure_cli_only ENABLE_KIMI KIMI_CMD
     configure_switchable ENABLE_CLAUDE CLAUDE_CMD CLAUDE_USE_API ANTHROPIC_API_KEY
     configure_switchable ENABLE_QWEN3 QWEN3_CMD QWEN3_USE_API QWEN3_API_KEY
+    configure_switchable ENABLE_GROK GROK_CMD GROK_USE_API GROK_API_KEY
     configure_switchable ENABLE_MINIMAX MINIMAX_CMD MINIMAX_USE_API MINIMAX_API_KEY
     configure_api_only ENABLE_GLM GLM_API_KEY
-    configure_api_only ENABLE_GROK GROK_API_KEY
     configure_api_only ENABLE_DEEPSEEK DEEPSEEK_API_KEY
 }
 
@@ -327,7 +366,11 @@ prompt_value() {
     else
         read -r -p "$key [$current]: " reply
         if [[ -n "$reply" ]]; then
-            set_value "$key" "$reply"
+            if [[ "$key" == *_MODEL ]]; then
+                set_value "$key" "$reply $PIN_MARKER"
+            else
+                set_value "$key" "$reply"
+            fi
         fi
     fi
 }
@@ -346,7 +389,7 @@ if [[ "$MODE" == "interactive" ]]; then
     for key in ENABLE_GEMINI ENABLE_CODEX ENABLE_MISTRAL ENABLE_CURSOR ENABLE_KIMI ENABLE_CLAUDE ENABLE_QWEN3 ENABLE_GLM ENABLE_GROK ENABLE_DEEPSEEK ENABLE_MINIMAX; do
         prompt_value "$key"
     done
-    for key in GEMINI_USE_API CODEX_USE_API MISTRAL_USE_API CLAUDE_USE_API QWEN3_USE_API MINIMAX_USE_API; do
+    for key in GEMINI_USE_API CODEX_USE_API MISTRAL_USE_API CLAUDE_USE_API QWEN3_USE_API GROK_USE_API MINIMAX_USE_API; do
         prompt_value "$key"
     done
 
@@ -359,7 +402,7 @@ if [[ "$MODE" == "interactive" ]]; then
         # parameter name as the user's answer instead.
         while IFS= read -r key <&3; do
             case "$key" in
-                ENABLE_GEMINI|ENABLE_CODEX|ENABLE_MISTRAL|ENABLE_CURSOR|ENABLE_KIMI|ENABLE_CLAUDE|ENABLE_QWEN3|ENABLE_GLM|ENABLE_GROK|ENABLE_DEEPSEEK|ENABLE_MINIMAX|GEMINI_USE_API|CODEX_USE_API|MISTRAL_USE_API|CLAUDE_USE_API|QWEN3_USE_API|MINIMAX_USE_API|GEMINI_API_KEY|OPENAI_API_KEY|MISTRAL_API_KEY|ANTHROPIC_API_KEY|QWEN3_API_KEY|MINIMAX_API_KEY|GLM_API_KEY|GROK_API_KEY|DEEPSEEK_API_KEY) continue ;;
+                ENABLE_GEMINI|ENABLE_CODEX|ENABLE_MISTRAL|ENABLE_CURSOR|ENABLE_KIMI|ENABLE_CLAUDE|ENABLE_QWEN3|ENABLE_GLM|ENABLE_GROK|ENABLE_DEEPSEEK|ENABLE_MINIMAX|GEMINI_USE_API|CODEX_USE_API|MISTRAL_USE_API|CLAUDE_USE_API|QWEN3_USE_API|GROK_USE_API|MINIMAX_USE_API|GEMINI_API_KEY|OPENAI_API_KEY|MISTRAL_API_KEY|ANTHROPIC_API_KEY|QWEN3_API_KEY|MINIMAX_API_KEY|GLM_API_KEY|GROK_API_KEY|DEEPSEEK_API_KEY) continue ;;
             esac
             prompt_value "$key"
         done 3< <(list_parameters)
@@ -368,7 +411,11 @@ fi
 
 # Explicit command-line overrides have final precedence.
 for ((i=0; i<${#SET_KEYS[@]}; i++)); do
-    set_value "${SET_KEYS[$i]}" "${SET_VALUES[$i]}"
+    if [[ "${SET_KEYS[$i]}" == *_MODEL ]]; then
+        set_value "${SET_KEYS[$i]}" "${SET_VALUES[$i]} $PIN_MARKER"
+    else
+        set_value "${SET_KEYS[$i]}" "${SET_VALUES[$i]}"
+    fi
 done
 
 enabled_count=0

package/scripts/doctor.sh

@@ -219,10 +219,9 @@ check_cli_consultant() {
         return 0
     fi
 
-    # Skip the CLI install check when the consultant runs in API mode. For the
-    # 6 switchable agents (Gemini, Codex, Claude, Mistral, Qwen3, MiniMax) a missing CLI
-    # is irrelevant once API mode is on -- the API key is validated separately
-    # by check_api_mode. This matters most for Gemini, which auto-resolves to
+    # Switchable agents skip the CLI requirement while explicitly in API mode;
+    # the API key is validated separately by check_api_mode. This matters most
+    # for Gemini, which auto-resolves to
     # API mode whenever GEMINI_API_KEY is set (the npm-friendly path).
     local use_api_var="${env_var}_USE_API"
     if [[ "${!use_api_var:-false}" == "true" ]]; then
@@ -238,7 +237,9 @@ check_cli_consultant() {
         fi
         add_issue "consultant" "$name CLI not found" "$install_cmd"
         check_fail
-        return 1
+        # A failed health check is data for the final diagnosis, not a reason
+        # to abort the diagnostic pipeline under `set -e`.
+        return 0
     fi
 
     # Get version (--version is standard and fast, no timeout needed)
@@ -265,6 +266,7 @@ check_cli_consultants() {
     check_cli_consultant "Kimi" "$KIMI_CMD" "curl -L code.kimi.com/install.sh | bash" "KIMI"
     check_cli_consultant "Claude" "$CLAUDE_CMD" "See https://docs.anthropic.com/claude-code" "CLAUDE"
     check_cli_consultant "Qwen" "$QWEN3_CMD" "npm install -g @qwen-code/qwen-code@latest" "QWEN3"
+    check_cli_consultant "Grok Build" "$GROK_CMD" "curl -fsSL https://x.ai/cli/install.sh | bash" "GROK"
     check_cli_consultant "MiniMax" "$MINIMAX_CMD" "npm install -g mmx-cli" "MINIMAX"
 }
 
@@ -291,7 +293,7 @@ check_api_mode() {
             _print "  ✗ $name: API mode enabled but $api_key_var not set"
             add_issue "api_mode" "$name API mode enabled but API key missing" "export ${api_key_var}='your-api-key'"
             check_fail
-            return 1
+            return 0
         else
             local masked_key="${api_key:0:4}...${api_key: -4}"
             _print "  ✓ $name: API mode (key: $masked_key)"
@@ -308,7 +310,7 @@ check_api_mode_switching() {
     local has_api_mode=false
 
     # Check switchable consultants
-    for agent in GEMINI CODEX CLAUDE MISTRAL QWEN3 MINIMAX; do
+    for agent in GEMINI CODEX CLAUDE MISTRAL QWEN3 GROK MINIMAX; do
         local enabled_var="ENABLE_${agent}"
         local use_api_var="${agent}_USE_API"
         local is_enabled="${!enabled_var:-false}"
@@ -326,6 +328,7 @@ check_api_mode_switching() {
         check_api_mode "Claude" "CLAUDE_USE_API" "ANTHROPIC_API_KEY" "ENABLE_CLAUDE"
         check_api_mode "Mistral" "MISTRAL_USE_API" "MISTRAL_API_KEY" "ENABLE_MISTRAL"
         check_api_mode "Qwen3" "QWEN3_USE_API" "QWEN3_API_KEY" "ENABLE_QWEN3"
+        check_api_mode "Grok" "GROK_USE_API" "GROK_API_KEY" "ENABLE_GROK"
         check_api_mode "MiniMax" "MINIMAX_USE_API" "MINIMAX_API_KEY" "ENABLE_MINIMAX"
     else
         _print "  ○ All switchable consultants using CLI mode"
@@ -357,7 +360,7 @@ check_api_consultant() {
         _print "  ✗ $name: API key not set"
         add_issue "api" "$name API key not configured" "export ${api_key_var}='your-api-key'"
         check_fail
-        return 1
+        return 0
     fi
 
     # Mask API key for display
@@ -383,7 +386,6 @@ check_api_consultants() {
     print_section "Checking API-only Consultants"
 
     check_api_consultant "GLM" "GLM_API_KEY" "GLM_API_URL" "ENABLE_GLM"
-    check_api_consultant "Grok" "GROK_API_KEY" "GROK_API_URL" "ENABLE_GROK"
     check_api_consultant "DeepSeek" "DEEPSEEK_API_KEY" "DEEPSEEK_API_URL" "ENABLE_DEEPSEEK"
 }
 
@@ -773,6 +775,7 @@ suggest_configuration() {
         "ENABLE_KIMI:${KIMI_CMD:-kimi}"
         "ENABLE_CLAUDE:${CLAUDE_CMD:-claude}"
         "ENABLE_QWEN3:${QWEN3_CMD:-qwen}"
+        "ENABLE_GROK:${GROK_CMD:-grok}"
         "ENABLE_MINIMAX:${MINIMAX_CMD:-mmx}"
     )
 
@@ -781,7 +784,8 @@ suggest_configuration() {
     for entry in "${consultant_clis[@]}"; do
         local flag="${entry%%:*}"
         local cmd="${entry##*:}"
-        if command -v "$cmd" >/dev/null 2>&1; then
+        if command -v "$cmd" >/dev/null 2>&1 || \
+           [[ "$flag" == "ENABLE_GROK" && -n "${GROK_API_KEY:-}" ]]; then
             lines+=("${flag}=true")
             ((available_count++)) || true
         else
@@ -792,7 +796,6 @@ suggest_configuration() {
     # API-only consultants: enable if API key is set
     local api_consultants=(
         "ENABLE_GLM:GLM_API_KEY"
-        "ENABLE_GROK:GROK_API_KEY"
         "ENABLE_DEEPSEEK:DEEPSEEK_API_KEY"
     )
     for entry in "${api_consultants[@]}"; do
@@ -856,13 +859,15 @@ _count_available_consultants() {
         "KIMI|ENABLE_KIMI|${KIMI_CMD:-kimi}"
         "CLAUDE|ENABLE_CLAUDE|${CLAUDE_CMD:-claude}"
         "QWEN3|ENABLE_QWEN3|${QWEN3_CMD:-qwen}"
+        "GROK|ENABLE_GROK|${GROK_CMD:-grok}"
         "MINIMAX|ENABLE_MINIMAX|${MINIMAX_CMD:-mmx}"
     )
     for entry in "${entries[@]}"; do
         IFS='|' read -r name flag cmd <<<"$entry"
         local enabled="${!flag:-false}"
         [[ "$enabled" != "true" ]] && continue
-        if command -v "$cmd" >/dev/null 2>&1; then
+        if command -v "$cmd" >/dev/null 2>&1 || \
+           [[ "$name" == "GROK" && -n "${GROK_API_KEY:-}" ]]; then
             [[ "$name" == "$invoker_consultant" ]] && continue
             ((count++)) || true
         fi
@@ -871,7 +876,6 @@ _count_available_consultants() {
     # API-only consultants: enabled flag + API key both required
     local api_entries=(
         "GLM|ENABLE_GLM|GLM_API_KEY"
-        "GROK|ENABLE_GROK|GROK_API_KEY"
         "DEEPSEEK|ENABLE_DEEPSEEK|DEEPSEEK_API_KEY"
     )
     for entry in "${api_entries[@]}"; do

package/scripts/lib/api.sh

@@ -249,7 +249,7 @@ build_openai_request() {
 build_anthropic_request() {
     local prompt="$1"
     local model="${2:-claude-sonnet-4-6}"
-    local max_tokens="${3:-4096}"
+    local max_tokens="${3:-16384}"
 
     jq -n \
         --arg model "$model" \
@@ -327,7 +327,11 @@ parse_anthropic_response() {
     local response="$1"
 
     local content
-    content=$(echo "$response" | jq -r '.content[0].text // empty' 2>/dev/null)
+    # Opus 5 may put a thinking block before the visible text block. Select
+    # every text block instead of assuming content[0] is user-visible output.
+    content=$(echo "$response" | jq -r \
+        '[.content[]? | select(.type == "text") | (.text // "")] | join("\n")' \
+        2>/dev/null)
 
     if [[ -n "$content" && "$content" != "null" ]]; then
         echo "$content"

package/scripts/lib/api_query.sh

@@ -94,7 +94,14 @@ run_api_mode_query() {
             if [[ -n "$effort" ]]; then
                 log_warn "[$consultant_name] $effort_var is not supported on the 'anthropic' wire format and is ignored."
             fi
-            request_body=$(build_anthropic_request "$query" "$model")
+            local max_tokens_var api_max_tokens
+            max_tokens_var="$(to_upper "$consultant_name")_API_MAX_TOKENS"
+            api_max_tokens="${!max_tokens_var:-16384}"
+            if ! [[ "$api_max_tokens" =~ ^[1-9][0-9]*$ ]]; then
+                log_error "[$consultant_name] $max_tokens_var must be a positive integer (got: $api_max_tokens)"
+                return 1
+            fi
+            request_body=$(build_anthropic_request "$query" "$model" "$api_max_tokens")
             auth_style="anthropic"
             ;;
         qwen)
@@ -134,6 +141,16 @@ run_api_mode_query() {
     local raw_response
     raw_response=$(cat "$temp_response")
 
+    # Anthropic counts adaptive thinking and visible output against the same
+    # max_tokens budget. A max_tokens stop is therefore an incomplete answer,
+    # not a successful partial response suitable for synthesis.
+    if [[ "$api_format" == "anthropic" ]] \
+        && [[ "$(jq -r '.stop_reason // empty' <<<"$raw_response" 2>/dev/null)" == "max_tokens" ]]; then
+        log_error "[$consultant_name] API response was truncated at ${api_max_tokens:-the configured} max tokens"
+        rm -f "$temp_response"
+        return 1
+    fi
+
     local parsed_content
     case "$api_format" in
         google_ai)