ai-consultants 3.0.0 → 3.2.0

package/.env.example

@@ -38,7 +38,7 @@
 # =============================================================================
 # API-BASED CONSULTANT KEYS
 # =============================================================================
-# These are required for the API-based consultants (Qwen3, GLM, Grok, DeepSeek)
+# These are required for API transports and API-only consultants.
 
 # Qwen3 (Alibaba DashScope) - The Analyst
 # Get yours at: https://dashscope.console.aliyun.com/
@@ -48,7 +48,8 @@
 # Get yours at: https://open.z.ai/
 # GLM_API_KEY=your_zhipu_api_key
 
-# Grok (xAI) - The Provocateur
+# Grok API fallback (the Grok Build CLI normally uses its own login)
+# Official docs call this XAI_API_KEY; GROK_API_KEY remains the project setting.
 # Get yours at: https://console.x.ai/
 # GROK_API_KEY=your_xai_api_key
 
@@ -73,18 +74,18 @@ ENABLE_MISTRAL=true
 ENABLE_CURSOR=true
 ENABLE_KIMI=true
 ENABLE_QWEN3=true
+ENABLE_GROK=true
 ENABLE_MINIMAX=true
 ENABLE_CLAUDE=true
 
 # API-only consultants (default: disabled - require API keys)
 ENABLE_GLM=false
-ENABLE_GROK=false
 ENABLE_DEEPSEEK=false
 
 # =============================================================================
 # CLI/API MODE SWITCHING (v2.6+)
 # =============================================================================
-# 6 agents support switching: Gemini, Codex, Claude, Mistral, Qwen3, MiniMax
+# 7 agents support switching: Gemini, Codex, Claude, Mistral, Qwen3, Grok, MiniMax
 # When API mode is enabled, CLI mode is automatically disabled.
 
 # GEMINI_USE_API is auto-resolved when left UNSET (v2.15.1): API mode if
@@ -143,9 +144,10 @@ KIMI_TIMEOUT=180
 KIMI_CMD=kimi
 
 # Claude - The Synthesizer
-CLAUDE_MODEL=claude-opus-4-8
+CLAUDE_MODEL=claude-opus-5 # ai-consultants:default
 CLAUDE_TIMEOUT=240
 CLAUDE_CMD=claude
+CLAUDE_API_MAX_TOKENS=16384
 
 # Qwen3 - The Analyst (CLI/API switchable v2.7)
 QWEN3_MODEL=qwen3.7-max
@@ -160,8 +162,13 @@ QWEN3_CMD=qwen
 # rejected by the provider with a 400, not silently ignored.
 # QWEN3_REASONING_EFFORT=
 
+# GROK_USE_API is auto-resolved CLI-first: Grok Build is used whenever `grok`
+# is installed; the xAI API is selected when the CLI is unavailable and a key
+# exists. A failed CLI launch also falls back to the API at runtime.
+# GROK_USE_API=false
+
 # =============================================================================
-# API-BASED CONSULTANT CONFIGURATION
+# API-ONLY AND FALLBACK CONFIGURATION
 # =============================================================================
 
 # GLM - The Methodologist
@@ -169,7 +176,8 @@ GLM_MODEL=glm-5.2
 GLM_TIMEOUT=180
 GLM_API_URL=https://api.z.ai/api/coding/paas/v4/chat/completions
 
-# Grok - The Provocateur
+# Grok Build CLI + xAI API fallback - The Provocateur
+GROK_CMD=grok
 GROK_MODEL=grok-4.5
 GROK_TIMEOUT=180
 GROK_API_URL=https://api.x.ai/v1/chat/completions

package/CLAUDE.md

@@ -2,11 +2,11 @@
 
 ## Project Overview
 
-AI Consultants is a multi-model AI deliberation system that queries up to 11 AI consultants (Gemini, Codex, Mistral, Cursor, Kimi, Claude, Qwen3, GLM, Grok, DeepSeek, MiniMax) to obtain diverse perspectives on coding problems.
+AI Consultants is a multi-model coverage system that queries up to 11 AI consultants (Gemini, Codex, Mistral, Cursor, Kimi, Claude, Qwen3, GLM, Grok, DeepSeek, MiniMax) to obtain diverse perspectives on coding problems.
 
 **Self-Exclusion**: The invoking agent is automatically excluded from the panel to prevent self-consultation. Claude Code won't query Claude, Codex CLI won't query Codex, etc.
 
-**Version**: 3.0.0
+**Version**: 3.2.0
 
 ## Distribution
 
@@ -368,7 +368,7 @@ Three tiers of models are available for each consultant, configurable via `apply
 
 | Tier | Description | Example Models |
 |------|-------------|----------------|
-| **premium** | Latest flagship models | claude-opus-4-8, Gemini 3.1 Pro (High), gpt-5.5 |
+| **premium** | Latest flagship models | claude-opus-5, Gemini 3.1 Pro (High), gpt-5.5 |
 | **standard** | Good quality at reasonable cost | claude-sonnet-4-6, Gemini 3.5 Flash (High), gpt-5.4 |
 | **economy** | Optimized for speed and low cost | claude-haiku-4-5, Gemini 3.5 Flash (Low), gpt-5.4-nano |
 
@@ -400,12 +400,12 @@ Three new presets leverage the model tiers:
 ./scripts/consult_all.sh --preset fast "quick syntax question"
 ```
 
-### Premium Model Defaults (June 2026)
+### Premium Model Defaults (July 2026)
 All consultants now use premium models by default:
 
 | Consultant | Default Model |
 |------------|---------------|
-| Claude | claude-opus-4-8 |
+| Claude | claude-opus-5 |
 | Gemini | Gemini 3.1 Pro (High) (via agy CLI) |
 | Codex | gpt-5.5 |
 | Mistral | mistral-large-3 |
@@ -419,6 +419,15 @@ All consultants now use premium models by default:
 
 Override with environment variables: `CLAUDE_MODEL`, `GEMINI_MODEL`, `CODEX_MODEL`, `KIMI_MODEL`, etc.
 
+Grok is CLI-first through the official Grok Build `grok` command, with
+`grok-4.5` passed explicitly in headless mode. The prompt is delivered with
+`--prompt-file`; HOME and CWD are isolated, built-in/MCP tools are denied, and
+the strict sandbox prevents user or project extensions from joining the
+consultation. The xAI Chat Completions path is retained only when the CLI is
+missing, cannot launch, or lacks usable authentication and `GROK_API_KEY` is
+available. A timeout, model error, empty response, or other post-launch failure
+is surfaced and never silently rerouted to the API.
+
 ## v2.4 Features
 
 ### Budget Enforcement (Opt-in)
@@ -604,7 +613,8 @@ for f in scripts/*.sh scripts/lib/*.sh; do bash -n "$f" && echo "OK: $f"; done
 | `ENABLE_SMART_ROUTING` | false | Intelligent routing by category |
 | `ENABLE_COST_TRACKING` | true | Track costs |
 | `MAX_SESSION_COST` | 1.00 | Max budget ($) |
-| `CLAUDE_MODEL` | claude-opus-4-8 | Claude model (v2.5) |
+| `CLAUDE_MODEL` | claude-opus-5 | Claude model (v2.5) |
+| `CLAUDE_API_MAX_TOKENS` | 16384 | Claude API thinking + visible-output budget |
 | `GEMINI_MODEL` | Gemini 3.1 Pro (High) | Gemini agy CLI model (v2.15) |
 | `GEMINI_API_MODEL` | gemini-3.1-pro-preview | Gemini API-mode model ID (v2.15) |
 | `CODEX_MODEL` | gpt-5.5 | Codex model (v2.5) |
@@ -777,6 +787,23 @@ curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/s
 
 ## Changelog
 
+### v3.2.0
+- **Claude premium upgraded from Opus 4.8 to Opus 5.** The default `CLAUDE_MODEL`, premium/max/best tier, standalone adapter fallback, configuration examples, model table, and cost catalog now resolve to the canonical `claude-opus-5` ID (`scripts/config.sh:274`, `scripts/query_claude.sh:29`). Pricing remains $5/$25 per million tokens; `claude-opus-4-8` stays in the legacy catalog for historical responses and intentional pins.
+- **Opus 5 adaptive thinking is accounted for end to end.** Claude CLI mode now requests the JSON result envelope, extracts visible `.result`, aggregates provider usage across `modelUsage`, and persists the provider's exact `costUSD` (`scripts/query_claude.sh:72-126`, `scripts/lib/common.sh:904-980`, `scripts/lib/costs.sh:307-354`). This fixes the review finding that pricing only the visible answer undercounted hidden thinking and cache charges. The implementation deliberately prefers provider cost over reconstructing cache pricing from token totals.
+- **Anthropic API responses no longer disappear when thinking precedes text.** `parse_anthropic_response` selects every `type=text` block rather than assuming `.content[0].text` (`scripts/lib/api.sh:325-343`). The API token budget is now the configurable `CLAUDE_API_MAX_TOKENS=16384`, shared by adaptive thinking and visible output; `stop_reason=max_tokens` fails closed instead of admitting a partial answer into synthesis (`scripts/lib/api_query.sh:94-153`).
+- **Historical generated defaults migrate with provenance.** Before this release, `init` copied `CLAUDE_MODEL=claude-opus-4-8` without distinguishing a generated default from a user pin, so the new runtime fallback was unreachable for existing installations. `configure` now upgrades that exact historical value to Opus 5 and writes `# ai-consultants:default`; model values supplied by environment, interactive input, or `--set` receive `# ai-consultants:pin` and survive later rewrites (`scripts/configure.sh:183-291`, `scripts/configure.sh:357-420`). An intentionally retained 4.8 value should be reasserted once with `--set CLAUDE_MODEL=claude-opus-4-8`.
+- **Verification expanded around all four review findings.** `test_query_claude.sh` exercises CLI JSON extraction, measured usage, provider cost persistence, and session billing. `test_api_transport.sh` covers thinking-before-text, the 16,384-token request default, invalid budgets, and truncation rejection; `test_configure.sh` covers managed migration and persistent pins. Full gate: 17/17 suites; core suite: 299/299; shellcheck green. The real maintainer config was not rewritten during implementation and remained on 4.8 until the release installation step.
+
+### v3.1.1
+- **`doctor` no longer aborts at the first missing enabled consultant.** The v3.1.0 tag workflow exposed the pre-existing `set -e` interaction when Grok became CLI-first and the clean Ubuntu runner had no `grok` binary: the main JSON diagnostic exited before emitting output. Missing CLI/API configuration checks now add their issue and continue to the final summary, which still exits unhealthy. `test_doctor.sh` stubs the complete CLI roster, rejects empty JSON output, and includes a dedicated missing-Grok regression. Full gate: 16/16 suites; shellcheck green.
+
+### v3.1.0
+- **Grok is now a first-class CLI/API-switchable consultant on `grok-4.5`.** `scripts/query_grok.sh` uses the official Grok Build headless interface, `scripts/config.sh` resolves CLI-first while preserving API-only installations, and configure/doctor/update-clis/docs all classify Grok with the other switchable consultants. `XAI_API_KEY` is accepted as the official alias for the historical `GROK_API_KEY` contract. The route that actually answered is recorded as `metadata.transport = cli|api|api_fallback`.
+- **The CLI boundary is enforced rather than documented.** The first implementation disabled plan/subagents/memory/web but still inherited the current checkout and the maintainer's Grok environment; `grok inspect --json` showed 1 MCP server, 13 plugins, 11 hooks, 79 skills, and 3 project instructions available to an advisory consultation. Each run now creates an ephemeral mode-700 HOME/CWD, copies only a regular non-symlink `auth.json` at mode 600, supplies `--tools ""`, `--permission-mode dontAsk`, `--sandbox strict`, and explicit deny rules, then validates the temp-prefix before recursive cleanup. A live Grok 4.5 smoke succeeded through this isolated path.
+- **Prompts use `--prompt-file`, not argv.** `FULL_QUERY` includes context files; passing it through `-p "$FULL_QUERY"` exposed the prompt in the process list and failed before Grok launched once the combined context crossed `ARG_MAX`. Reproduced locally with a 1.1 MiB context (`timeout: Argument list too long`). The private prompt file removes both failure modes, and the regression suite drives the same 1.1 MiB case.
+- **API fallback means transport unavailable, not "any non-zero".** The initial adapter sent every CLI error to the API when a key existed — including timeouts, model errors, empty responses, and a generic tested `exit 42` — which hid CLI regressions and could add an unexpected API charge. `grok_cli_is_unavailable` now recognizes missing/unexecutable binaries and authentication/startup failures only; post-launch failures remain `transport=cli` and surface as errors. Missing-command and authentication fallback paths are tested separately.
+- **Regression and release coverage.** New `test_query_grok.sh` carries 26 assertions across headless flags/model pinning, HOME/CWD/auth isolation, tool denial, transport metadata, API fallback boundaries, and large contexts. The master runner discovers it automatically, taking `npm test` to 16 suites; the v3.1.0 release gate and shellcheck pass. README, SKILL, setup/recipes/configuration references, changelog, and the showcase roster are synchronized.
+
 ### v3.0.0
 - **Phase 2 of the panel-premise investigation: the deliberation/consensus machinery is removed and the default is now the coverage union.** Two independent reviews (Codex `gpt-5.6-sol`, then Fable-5) had judged the panel premise weak — voting/consensus measure *agreement*, not correctness, and no held-out comparison against one strong model existed. A held-out A/W/C coverage experiment (maintainer instrumentation on the `experiment/coverage-metric` branch, not shipped) resolved it: **task-dependent.** On convergent single-answer defect-finding a single strong model (Gemini 3.1 Pro) caught **19/19** hard bugs (repo-internal + external CVEs/concurrency incl. the Rust `Arc` bug found by RustBelt formal verification) → the panel has no coverage headroom. On **breadth/enumeration** (deep 60-point rubrics across JWT/webhook/cache), rubric coverage was **A 51% · self-consistency C 70% · panel W 93%, W>C>A on every item** → diversity, not volume, and specifically the raw **union** (deliberation OFF). The durable value is the diverse fan-out + union; the averaging machinery adds nothing measurable. Directional (n=3 breadth, hand-validated; n=19 defect).
 - **Removed end to end** (six test-green commits on `refactor/remove-deliberation`, merged via PR #6): `lib/voting.sh` (voted recommendation, 1-10 score, consensus score, dissenters), `lib/orchestration.sh` (shape planner + convergence loop) + `debate_round.sh`, `lib/stance.sh`, `peer_review.sh`, and the capability-calibration cluster `roster_audit.sh`/`roster_calibrate.sh`/`run_calibration.sh`/`taste_elo.sh` + `references/calibration_benchmark.json` + the `capabilities`/`category_axis` blocks in `affinity.json`. Panic functions cut from `common.sh`; capability functions (`get_capability`/`get_category_axis`) and the `ENABLE_CAPABILITY_ROUTING` branch cut from `routing.sh`. Config: `ENABLE_DEBATE`/`DEBATE_ROUNDS`, `ORCHESTRATION_MODE`/`CONVERGENCE_*`, `ENABLE_DEBATE_OPTIMIZATION`/`DEBATE_*`, `ENABLE_PANIC_MODE`/`PANIC_*`, `ENABLE_ADVERSARIAL_VERIFY`, `ENABLE_PEER_REVIEW`/`PEER_REVIEW_MIN`, `ENABLE_CAPABILITY_*`/`CAPABILITY_*`, `ENABLE_STANCE_CONSENSUS`/`STANCE_*`. Presets no longer force debate/peer-review. The `debate` and `roster-audit` slash commands are gone (installers prune them). 19 files deleted, ~-4600 lines. 6 test suites removed.

package/README.md

@@ -1,8 +1,8 @@
-# AI Consultants v3.0.0
+# AI Consultants v3.2.0
 
 > **Coverage, not a single guess.** A panel of up to 11 frontier models from different vendors fans out on your question in parallel and hands you the *union* of what they collectively see — the risks, edge cases, and approaches a single model misses.
 
-[![Version](https://img.shields.io/badge/version-3.0.0-blue.svg)](https://github.com/matteoscurati/ai-consultants)
+[![Version](https://img.shields.io/badge/version-3.2.0-blue.svg)](https://github.com/matteoscurati/ai-consultants)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-orange.svg)](https://docs.anthropic.com/en/docs/claude-code/skills)
 [![GitHub stars](https://img.shields.io/github/stars/matteoscurati/ai-consultants?style=social)](https://github.com/matteoscurati/ai-consultants)
@@ -379,17 +379,22 @@ INVOKING_AGENT=codex ./scripts/consult_all.sh "Question"    # Codex excluded
 | **Kimi K3** | `kimi` | The Eastern Sage | Holistic, balanced perspectives |
 | **Claude** | `claude` | The Synthesizer | Big picture, synthesis, connecting ideas |
 | **Qwen3** | `qwen` | The Analyst | Data-driven analysis |
+| **Grok** | `grok` | The Provocateur | Challenge conventions |
 | **MiniMax** | `mmx` | The Pragmatic Optimizer | Performance, efficiency, pragmatism |
 
-Qwen3 and MiniMax can switch from their CLI to API transport. Gemini, Codex,
-Claude, and Mistral are also CLI/API switchable.
+Grok uses Grok Build with `grok-4.5` in an isolated, tool-free sandbox. Prompts
+are passed through a private file rather than process arguments. It falls back
+to the xAI API only when the CLI is missing, cannot launch, or has no usable
+authentication and `GROK_API_KEY` is configured; post-launch request failures
+are surfaced without a silent API charge. Qwen3 and MiniMax can also switch
+from their CLI to API transport. Gemini, Codex, Claude, and Mistral are
+CLI/API switchable.
 
 ### API-Only Consultants
 
 | Consultant | Default Model | Persona | Focus |
 |------------|---------------|---------|-------|
 | **GLM** | glm-5.2 | The Methodologist | Structured approaches |
-| **Grok** | grok-4.5 | The Provocateur | Challenge conventions |
 | **DeepSeek** | deepseek-v4-pro | The Code Specialist | Algorithms, code generation |
 
 ### Installing Consultant CLIs
@@ -405,6 +410,7 @@ curl https://cursor.com/install -fsS | bash  # Cursor
 # Optional CLI-based consultants
 curl -L code.kimi.com/install.sh | bash            # Kimi K3
 npm install -g @qwen-code/qwen-code@latest  # Qwen (alternative to API)
+curl -fsSL https://x.ai/cli/install.sh | bash # Grok Build (grok-4.5)
 npm install -g mmx-cli                       # MiniMax
 
 ```
@@ -438,7 +444,7 @@ parallel and returns the coverage union.
 
 | Consultant | Premium | Standard | Economy |
 |------------|---------|----------|---------|
-| Claude | claude-opus-4-8 | claude-sonnet-4-6 | claude-haiku-4-5 |
+| Claude | claude-opus-5 | claude-sonnet-4-6 | claude-haiku-4-5 |
 | Gemini | Gemini 3.1 Pro (High) | Gemini 3.5 Flash (High) | Gemini 3.5 Flash (Low) |
 | Codex | gpt-5.5 | gpt-5.4 | gpt-5.4-nano |
 | Mistral | mistral-large-3 | mistral-medium-latest | devstral-small-2 |
@@ -540,7 +546,13 @@ with `--set`). Rewrites create a private timestamped backup. Use `--advanced` to
 review every parameter or `--dry-run` to preview a redacted result.
 Auto-selected `*_USE_API` values are marked `# ai-consultants:auto`, allowing a
 later run to adapt when a CLI or credential changes. Environment variables,
-`--set`, and unmarked values remain explicit user choices.
+`--set`, and unmarked values remain explicit user choices, except for the exact
+historical generated Claude default described below.
+Managed model defaults use `# ai-consultants:default`; `configure` upgrades the
+historical unmarked `CLAUDE_MODEL=claude-opus-4-8` default to Opus 5. To keep
+4.8 intentionally, run
+`ai-consultants configure --set CLAUDE_MODEL=claude-opus-4-8`; explicit model
+overrides are stored with `# ai-consultants:pin`.
 
 Enter credentials through `--interactive`/`--advanced` or export them before the
 run; avoid passing API keys through `--set`, where the shell may retain them in
@@ -557,6 +569,7 @@ DEFAULT_STRATEGY=coverage    # coverage | compare_only | majority | risk_averse
 ENABLE_SMART_ROUTING=true    # Auto-select consultants by question category
 MAX_SESSION_COST=1.00        # USD budget cap (paired with ENABLE_BUDGET_LIMIT=true to enforce)
 KIMI_MODEL=kimi-code/k3      # Pin the Kimi consultant to K3
+CLAUDE_API_MAX_TOKENS=16384  # Shared thinking + visible-output budget in API mode
 ```
 
 Full reference: [`references/configuration.md`](references/configuration.md). Copy-paste workflows: [`docs/RECIPES.md`](docs/RECIPES.md). For category-aware preset suggestions: `ai-consultants doctor --suggest-preset --question "..."`.

package/SKILL.md

@@ -5,10 +5,10 @@ license: MIT
 compatibility: Requires bash, jq, and at least 2 AI CLI tools (agy, codex, vibe, etc.). macOS and Linux.
 metadata:
   author: matteoscurati
-  version: 3.0.0
+  version: 3.2.0
 ---
 
-# AI Consultants v3.0.0 - AI Expert Panel
+# AI Consultants v3.2.0 - AI Expert Panel
 
 **Coverage, not a single guess.** Convene a panel of AI "consultants" from different vendors for coding questions: they fan out in parallel and you get the *union* of what they collectively see — the risks, edge cases, and approaches a single model misses. Each consultant has a **configurable persona** that decorrelates its analysis.
 
@@ -38,11 +38,12 @@ Configuration (presets, strategies, features, personas, API keys) can be managed
 | **Kimi K3** | `kimi` | The Eastern Sage | Holistic, balanced perspectives |
 | **Claude** | `claude` | The Synthesizer | Big picture, synthesis |
 | **Qwen** | `qwen` | The Analyst | Data-driven, metrics |
+| **Grok** | `grok` | The Provocateur | Challenge conventions |
 | **MiniMax** | `mmx` | The Pragmatic Optimizer | Performance, efficiency, pragmatism |
 
-**API-only consultants**: GLM (The Methodologist), Grok (The Provocateur), DeepSeek (The Code Specialist)
+**API-only consultants**: GLM (The Methodologist), DeepSeek (The Code Specialist)
 
-**CLI/API Mode**: Gemini, Codex, Claude, Mistral, Qwen, and MiniMax can switch between CLI and API mode via `*_USE_API` environment variables. Gemini auto-selects API mode when `GEMINI_API_KEY` is set (no `agy` install needed) and the CLI otherwise.
+**CLI/API Mode**: Gemini, Codex, Claude, Mistral, Qwen, Grok, and MiniMax can switch between CLI and API mode via `*_USE_API` environment variables. Grok is CLI-first on Grok Build with `grok-4.5` and falls back to the xAI API when the CLI cannot run. Gemini auto-selects API mode when `GEMINI_API_KEY` is set (no `agy` install needed) and the CLI otherwise.
 
 **Self-Exclusion**: The invoking agent is automatically excluded from the panel. When invoked from Claude Code, Claude is excluded; when invoked from Codex CLI, Codex is excluded, etc.
 

package/docs/COST_RATES.md

@@ -1,4 +1,4 @@
-# Cost Rates - AI Consultants v3.0.0
+# Cost Rates - AI Consultants v3.2.0
 
 This page documents the per-token rates used by the cost tracking system.
 
@@ -26,7 +26,7 @@ Since v2.5, models are organized into three tiers. Use `apply_model_tier()` or `
 | gpt-5.5 | Premium | $0.005 | Codex |
 | gpt-5.4 | Standard | $0.0025 | Codex |
 | gpt-5.4-nano | Economy | $0.0002 | Codex |
-| claude-opus-4-8 | Premium | $0.005 | Claude |
+| claude-opus-5 | Premium | $0.005 | Claude |
 | claude-sonnet-4-6 | Standard | $0.003 | Claude |
 | claude-haiku-4-5 | Economy | $0.001 | Claude |
 | mistral-large-3 | Premium | $0.002 | Mistral |
@@ -59,7 +59,7 @@ Since v2.5, models are organized into three tiers. Use `apply_model_tier()` or `
 | gpt-5.5 | Premium | $0.030 | Codex |
 | gpt-5.4 | Standard | $0.015 | Codex |
 | gpt-5.4-nano | Economy | $0.00125 | Codex |
-| claude-opus-4-8 | Premium | $0.025 | Claude |
+| claude-opus-5 | Premium | $0.025 | Claude |
 | claude-sonnet-4-6 | Standard | $0.015 | Claude |
 | claude-haiku-4-5 | Economy | $0.005 | Claude |
 | mistral-large-3 | Premium | $0.006 | Mistral |

package/docs/RECIPES.md

@@ -124,10 +124,10 @@ CLAUDE_USE_API=false
 MISTRAL_USE_API=false
 QWEN3_USE_API=false
 MINIMAX_USE_API=false
+GROK_USE_API=false
 KIMI_MODEL=kimi-code/k3
 
 ENABLE_GLM=false
-ENABLE_GROK=false
 ENABLE_DEEPSEEK=false
 ```
 
@@ -140,8 +140,10 @@ even when `~/.kimi/config.toml` still names an older default model.
 
 ## 8. Hybrid CLI and API panel
 
-Enable API transport only where needed. Gemini and MiniMax automatically choose
-API mode when their API key is present unless `*_USE_API` is explicitly set.
+Enable API transport only where needed. Grok normally uses Grok Build and
+automatically falls back to the xAI API if the CLI cannot run. Gemini and
+MiniMax automatically choose API mode when their API key is present unless
+`*_USE_API` is explicitly set.
 
 ```dotenv
 CODEX_USE_API=false
@@ -151,6 +153,7 @@ QWEN3_USE_API=true
 QWEN3_API_KEY=your-dashscope-key
 
 ENABLE_GROK=true
+GROK_USE_API=false
 GROK_API_KEY=your-xai-key
 GROK_MODEL=grok-4.5
 

package/docs/SETUP.md

@@ -394,7 +394,7 @@ INVOKING_AGENT=codex ./scripts/consult_all.sh "Question"
 
 ## CLI/API Mode Switching (v2.6+)
 
-Six consultants can switch between CLI mode (using local CLI tools) and API mode (direct API calls): **Gemini, Codex, Claude, Mistral, Qwen3, and MiniMax**.
+Seven consultants can switch between CLI mode (using local CLI tools) and API mode (direct API calls): **Gemini, Codex, Claude, Mistral, Qwen3, Grok, and MiniMax**. Grok is CLI-first and runs in an isolated, tool-free strict sandbox. It falls back automatically only when Grok Build is missing, cannot launch, or lacks usable authentication and a key is available; request failures after launch are surfaced without an API fallback.
 
 ### Why Use API Mode?
 
@@ -418,6 +418,9 @@ export ANTHROPIC_API_KEY="sk-ant-..."
 export MISTRAL_USE_API=true
 export MISTRAL_API_KEY="your-mistral-key"
 
+export GROK_USE_API=true
+export GROK_API_KEY="your-xai-key"
+
 export QWEN3_USE_API=true   # Enable API mode for Qwen3
 export QWEN3_API_KEY="your-dashscope-key"
 ```
@@ -590,8 +593,8 @@ ENABLE_CLAUDE=false    # Auto-excluded when invoked from Claude Code
 ENABLE_MISTRAL=false
 ENABLE_CURSOR=false
 ENABLE_QWEN3=false     # v2.7: The Analyst (CLI/API)
+ENABLE_GROK=true       # Grok Build CLI; API fallback when unavailable
 ENABLE_GLM=false
-ENABLE_GROK=false
 ENABLE_DEEPSEEK=false
 ENABLE_KIMI=true
 ENABLE_MINIMAX=true
@@ -606,6 +609,7 @@ OPENAI_API_KEY=sk-your-key
 MISTRAL_API_KEY=your-key
 ANTHROPIC_API_KEY=sk-ant-your-key
 QWEN3_API_KEY=your-dashscope-key
+GROK_API_KEY=your-xai-key  # optional fallback; Grok Build normally uses login
 
 # CLI/API Mode Switching (v2.6+)
 # GEMINI_USE_API auto-resolves when unset (v2.15.1): API if GEMINI_API_KEY is

package/docs/cost_rates.json

@@ -1,10 +1,10 @@
 {
-  "version": "3.0.0",
-  "updated": "2026-07-16",
+  "version": "3.2.0",
+  "updated": "2026-07-25",
   "models": {
     "_comment_units": "All rates are USD per 1,000 tokens (per-1K). lib/costs.sh computes cost as (token_count / 1000) * rate, so every value here MUST be a per-1K rate = (provider $/1M price) / 1000. Do NOT paste $/MTok figures directly.",
-    "_comment_premium": "Premium tier models - Jun 2026 (v2.17.0)",
-    "claude-opus-4-8": {
+    "_comment_premium": "Premium tier models - Jul 2026",
+    "claude-opus-5": {
       "input": 0.005,
       "output": 0.025
     },
@@ -137,6 +137,10 @@
       "output": 0.001
     },
     "_comment_legacy": "Legacy models for backwards compatibility",
+    "claude-opus-4-8": {
+      "input": 0.005,
+      "output": 0.025
+    },
     "claude-opus-4-7": {
       "input": 0.005,
       "output": 0.025
@@ -331,8 +335,8 @@
     "qwen3.8-max-preview"
   ],
   "consultant_fallbacks": {
-    "_comment": "Premium defaults - Updated Jun 2026 (v2.17.0)",
-    "claude": "claude-opus-4-8",
+    "_comment": "Premium defaults - Updated Jul 2026",
+    "claude": "claude-opus-5",
     "gemini": "Gemini 3.1 Pro (High)",
     "codex": "gpt-5.5",
     "mistral": "mistral-large-3",
@@ -347,7 +351,7 @@
   "model_tiers": {
     "_comment": "Model tiers for apply_model_tier() function",
     "premium": {
-      "claude": "claude-opus-4-8",
+      "claude": "claude-opus-5",
       "gemini": "Gemini 3.1 Pro (High)",
       "codex": "gpt-5.5",
       "mistral": "mistral-large-3",

package/docs/releases/v3.1.0.md

@@ -0,0 +1,95 @@
+# Release v3.1.0
+
+**Date:** 2026-07-24
+**Type:** Minor — Grok 4.5 becomes a secure CLI-first consultant through Grok Build
+**Previous:** v3.0.0
+
+## Highlights
+
+- **Grok 4.5 now uses the official Grok Build CLI by default**, including OAuth/subscription authentication already available on the machine.
+- **Each Grok consultation runs in an isolated, tool-free environment** without importing local plugins, hooks, MCP servers, skills, memories, or project instructions.
+- **The xAI API remains available as a focused fallback** when Grok Build is missing, cannot launch, or is not authenticated.
+- **CLI request failures never silently become billable API requests.** Timeouts, model errors, and empty responses are returned as failures on the attempted CLI transport.
+- **Large contexts are safe from shell argument limits** because prompts are delivered through a private file instead of the process command line.
+
+## What's New
+
+### Grok Build CLI transport
+
+Grok joins the CLI-first consultant roster with `grok-4.5` pinned explicitly. Existing installations prefer the `grok` command; API-only installations continue to use the xAI Chat Completions transport when `GROK_API_KEY` or `XAI_API_KEY` is configured.
+
+Every response records the route that answered:
+
+| `metadata.transport` | Meaning |
+|---|---|
+| `cli` | Grok Build answered |
+| `api` | API mode was explicitly selected |
+| `api_fallback` | The CLI was unavailable and the xAI API answered |
+
+### Isolated advisory execution
+
+AI Consultants uses Grok as an advisory model, not as an editing agent. The adapter therefore starts Grok Build with:
+
+- an ephemeral HOME and empty working directory;
+- no built-in tools, MCP tools, subagents, memory, or web access;
+- fail-closed permissions and the strict sandbox;
+- only the existing Grok authentication material copied into the private runtime;
+- automatic cleanup after the response.
+
+The consultation receives only the prompt and context explicitly assembled by AI Consultants.
+
+### Narrow API fallback
+
+The API fallback is limited to transport availability:
+
+- Grok Build is not installed;
+- the command cannot execute or launch;
+- the CLI has no usable authentication.
+
+Failures after the CLI request starts—including timeouts, model errors, and empty output—are surfaced directly. This prevents a broken CLI request from silently producing a separate API charge.
+
+### Private prompt files
+
+The complete prompt is written to a mode-600 temporary file and passed with `--prompt-file`. This keeps prompt content out of process listings and supports contexts larger than the operating system's argument-vector limit.
+
+## Breaking Changes
+
+None — this release is backwards-compatible. `GROK_USE_API=true` still forces the API transport, and the existing `GROK_API_KEY` configuration remains supported.
+
+## 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"
+```
+
+Install and authenticate Grok Build to use the new default transport:
+
+```bash
+curl -fsSL https://x.ai/cli/install.sh | bash
+grok login
+```
+
+No configuration changes are required. Systems without a usable Grok Build CLI continue to use the configured xAI API fallback.
+
+## Verification
+
+- Live Grok 4.5 smoke through the isolated CLI runtime
+- Grok adapter regression suite: 26 checks
+- Full repository gate: 16/16 suites
+- Core suite: 295/295 checks
+- Shellcheck and release-surface validation
+
+## Commits
+
+- `ed84c8c` feat: integrate Grok 4.5 through Grok Build CLI
+
+## Contributors
+
+- Matteo Scurati

package/docs/releases/v3.1.1.md

@@ -0,0 +1,54 @@
+# Release v3.1.1
+
+**Date:** 2026-07-24
+**Type:** Patch — complete doctor diagnostics when a consultant is unavailable
+**Previous:** v3.1.0
+
+## Highlights
+
+- **`doctor` now reaches its final summary when an enabled CLI is missing.**
+- **JSON diagnostics always emit a complete object before returning unhealthy.**
+- **Missing API credentials follow the same accumulate-and-report behavior.**
+
+## What Was Fixed
+
+The diagnostic checks correctly recognized an enabled but unavailable consultant
+as unhealthy, but returned a non-zero status from inside the pipeline. Because
+`doctor.sh` runs with `set -e`, that return terminated the entire command before
+the human summary or JSON object could be produced.
+
+This became visible in the clean Linux release runner after Grok Build became the
+default Grok transport in v3.1.0: the runner had no `grok` executable, so
+`doctor --json` emitted nothing.
+
+CLI, switchable API-mode, and API-only checks now record the issue and continue.
+The command still exits 1 after the completed summary when any issue exists.
+
+## Verification
+
+- Dedicated missing-Grok JSON regression
+- Empty output is no longer accepted as valid JSON
+- Doctor suite: 43/43 checks
+- Full repository gate: 16/16 suites
+- Shellcheck passed
+
+## Breaking Changes
+
+None.
+
+## 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 doctor
+```
+
+## Contributors
+
+- Matteo Scurati