ai-consultants 3.0.0 → 3.1.1

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
@@ -160,8 +161,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 +175,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.1.1
 
 ## Distribution
 
@@ -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)
@@ -777,6 +786,16 @@ curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/s
 
 ## Changelog
 
+### 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.1.1
 
 > **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.1.1-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
 
 ```

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.1.1
 ---
 
-# AI Consultants v3.0.0 - AI Expert Panel
+# AI Consultants v3.1.1 - 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.1.1
 
 This page documents the per-token rates used by the cost tracking system.
 

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,5 +1,5 @@
 {
-  "version": "3.0.0",
+  "version": "3.1.1",
   "updated": "2026-07-16",
   "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.",

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-consultants",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "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

@@ -182,7 +182,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 +193,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 +208,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 +221,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
 ```
 
@@ -245,6 +246,14 @@ DEEPSEEK_MODEL=deepseek-v4-pro
 MINIMAX_MODEL=MiniMax-M2.7
 ```
 
+`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)
@@ -265,10 +285,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 +303,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}"
 
 # =============================================================================
@@ -758,4 +778,4 @@ EOF
 # VERSION
 # =============================================================================
 
-AI_CONSULTANTS_VERSION="3.0.0"
+AI_CONSULTANTS_VERSION="3.1.1"

package/scripts/configure.sh

@@ -307,9 +307,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
 }
 
@@ -346,7 +346,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 +359,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)

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/common.sh

@@ -274,8 +274,8 @@ to_title() {
 
 # Central list of known/predefined agents (to distinguish from custom ones)
 # This list is used by discovery functions to identify custom agents
-KNOWN_CLI_AGENTS="GEMINI CODEX MISTRAL CURSOR KIMI CLAUDE QWEN3 MINIMAX"
-KNOWN_API_AGENTS="GLM GROK DEEPSEEK"
+KNOWN_CLI_AGENTS="GEMINI CODEX MISTRAL CURSOR KIMI CLAUDE QWEN3 GROK MINIMAX"
+KNOWN_API_AGENTS="GLM DEEPSEEK"
 
 # Every non-consultant ENABLE_* flag declared in config.sh. This is a denylist
 # guarding _discover_custom_api_agents (consult_all.sh): that function walks
@@ -351,6 +351,8 @@ validate_api_mode() {
         CLAUDE)     api_key_var="ANTHROPIC_API_KEY" ;;
         MISTRAL)    api_key_var="MISTRAL_API_KEY" ;;
         QWEN3)      api_key_var="QWEN3_API_KEY" ;;
+        GROK)       api_key_var="GROK_API_KEY" ;;
+        MINIMAX)    api_key_var="MINIMAX_API_KEY" ;;
         *)
             log_error "Unknown agent for API mode: $agent"
             return 1
@@ -465,11 +467,9 @@ get_api_format() {
 # Warn when a reasoning-effort setting cannot be delivered on the CLI transport.
 # Usage: warn_effort_ignored_in_cli <agent_name>
 #
-# api_query.sh reads ${AGENT}_REASONING_EFFORT generically, so six consultants
-# accept the variable in API mode. CLI is the mandatory default transport and no
-# CLI exposes an effort flag, so every one of them needs the same diagnostic -
-# it lived in query_qwen3.sh alone, leaving the other five with the silent
-# no-op this feature exists to avoid.
+# api_query.sh reads ${AGENT}_REASONING_EFFORT generically for API transports,
+# accept the variable in API mode. CLI adapters that cannot express the setting
+# use this diagnostic instead of silently ignoring it.
 warn_effort_ignored_in_cli() {
     local agent="$1"
     local agent_upper
@@ -1210,7 +1210,7 @@ is_consultant_enabled() {
     # Get default based on consultant type
     local default="true"
     case "$name_upper" in
-        GLM|GROK|DEEPSEEK)
+        GLM|DEEPSEEK)
             default="false"
             ;;
     esac

package/scripts/query_grok.sh

@@ -1,17 +1,226 @@
 #!/bin/bash
-# query_grok.sh - Query Grok (xAI) via HTTP API (v2.0 with Persona and Confidence)
+# query_grok.sh - Query Grok Build CLI, with xAI API fallback
 #
 # Usage: ./query_grok.sh "question" [context_file] [output_file]
 #
 # Environment variables:
-#   GROK_API_KEY    - API key for xAI (required)
-#   GROK_MODEL      - Model to use (default: grok-4.20-0309-reasoning)
+#   GROK_CMD        - Grok Build command (default: grok)
+#   GROK_MODEL      - Model to use in both transports (default: grok-4.5)
 #   GROK_TIMEOUT    - Timeout in seconds (default: 180)
+#   GROK_USE_API    - Force the API path when true (default: CLI-first auto)
+#   GROK_API_KEY    - xAI API key used by the fallback
+#   XAI_API_KEY     - Official xAI key name; accepted as a GROK_API_KEY alias
 #   ENABLE_PERSONA  - Enable "The Provocateur" persona (default: true)
 
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/lib/api_query.sh"
+source "$SCRIPT_DIR/lib/common.sh"
+source "$SCRIPT_DIR/lib/personas.sh"
 
-run_api_consultant "Grok" "$@"
+QUERY="${1:-}"
+CONTEXT_FILE="${2:-}"
+OUTPUT_FILE="${3:-/tmp/grok_response.json}"
+
+ENABLE_PERSONA="${ENABLE_PERSONA:-true}"
+CONSULTANT_NAME="Grok"
+
+FULL_QUERY=$(build_full_query "$QUERY" "$CONTEXT_FILE")
+validate_query "$FULL_QUERY" "$CONSULTANT_NAME" || exit 1
+
+if [[ "$ENABLE_PERSONA" == "true" ]]; then
+    FULL_QUERY=$(build_query_with_persona "$CONSULTANT_NAME" "$FULL_QUERY")
+fi
+
+START_TIME=$(get_timestamp_ms)
+TEMP_OUTPUT=$(mktemp)
+GROK_RUNTIME_DIR=""
+TRANSPORT="cli"
+exit_code=1
+
+cleanup() {
+    rm -f "$TEMP_OUTPUT" "${TEMP_OUTPUT}.err"
+
+    # GROK_RUNTIME_DIR is always created by this script under the system temp
+    # directory. Validate the prefix before recursive cleanup so an unexpected
+    # empty or overridden value can never widen the deletion target.
+    local temp_prefix="${TMPDIR:-/tmp}"
+    temp_prefix="${temp_prefix%/}/ai-consultants-grok."
+    if [[ -n "$GROK_RUNTIME_DIR" && "$GROK_RUNTIME_DIR" == "$temp_prefix"* ]]; then
+        rm -rf -- "$GROK_RUNTIME_DIR"
+    fi
+}
+trap cleanup EXIT
+
+run_grok_api() {
+    source "$SCRIPT_DIR/lib/api_query.sh"
+    : > "$TEMP_OUTPUT"
+    if run_api_mode_query \
+            "$CONSULTANT_NAME" \
+            "$GROK_MODEL" \
+            "$FULL_QUERY" \
+            "$TEMP_OUTPUT" \
+            "$GROK_TIMEOUT_SECONDS"; then
+        return 0
+    else
+        return $?
+    fi
+}
+
+grok_cli_is_unavailable() {
+    local cli_exit_code="$1"
+    local error_file="$2"
+
+    # A missing command is detected before execution. 126/127 cover a binary
+    # that was resolved but cannot be executed (bad interpreter, permissions,
+    # or a race with an uninstall).
+    case "$cli_exit_code" in
+        126|127) return 0 ;;
+    esac
+
+    [[ -s "$error_file" ]] || return 1
+
+    # Authentication is part of CLI availability: without a usable Grok Build
+    # login the subscription transport cannot start a request. Do not classify
+    # model errors, timeouts, empty output, or other post-launch failures here;
+    # those must surface instead of silently creating a billable API request.
+    grep -Eiq \
+        'not authenticated|authentication( is)? required|authentication failed|unauthorized|run .?grok login|please .*log ?in|no (valid )?(credentials|access token)|missing .*credential|token.*expired|(^|[^0-9])401([^0-9]|$)|permission denied|cannot execute|exec format error|no such file or directory|failed to (start|launch|spawn)|could not (start|launch|spawn)' \
+        "$error_file"
+}
+
+if is_api_mode "grok"; then
+    log_api_mode_status "grok"
+    TRANSPORT="api"
+    if run_grok_api; then
+        exit_code=0
+    else
+        exit_code=$?
+    fi
+else
+    log_api_mode_status "grok"
+
+    if command -v "$GROK_CMD" >/dev/null 2>&1; then
+        runtime_base="${TMPDIR:-/tmp}"
+        runtime_base="${runtime_base%/}"
+        GROK_RUNTIME_DIR=$(mktemp -d "$runtime_base/ai-consultants-grok.XXXXXX")
+        chmod 700 "$GROK_RUNTIME_DIR"
+
+        isolated_home="$GROK_RUNTIME_DIR/home"
+        isolated_grok_home="$isolated_home/.grok"
+        isolated_workspace="$GROK_RUNTIME_DIR/workspace"
+        prompt_file="$GROK_RUNTIME_DIR/prompt.txt"
+        mkdir -p "$isolated_grok_home" "$isolated_workspace"
+        chmod 700 "$isolated_home" "$isolated_grok_home" "$isolated_workspace"
+        printf '%s' "$FULL_QUERY" > "$prompt_file"
+        chmod 600 "$prompt_file"
+
+        # Preserve only the credential needed to use the installed CLI. All
+        # config, plugins, hooks, MCP servers, skills, memories, and project
+        # instructions stay outside the isolated HOME/CWD.
+        source_grok_home=$(printenv GROK_HOME 2>/dev/null || true)
+        [[ -n "$source_grok_home" ]] || source_grok_home="${HOME}/.grok"
+        if [[ -f "$source_grok_home/auth.json" && ! -L "$source_grok_home/auth.json" ]]; then
+            if cp "$source_grok_home/auth.json" "$isolated_grok_home/auth.json"; then
+                chmod 600 "$isolated_grok_home/auth.json"
+            else
+                log_warn "[$CONSULTANT_NAME] Could not copy the Grok CLI credential into the isolated runtime"
+            fi
+        fi
+
+        # Official Grok Build headless contract:
+        #   --prompt-file avoids argv size/process-list exposure, -m pins the
+        #   model, and plain output contains the final assistant text.
+        #   dontAsk + strict sandbox make every unapproved tool fail closed.
+        GROK_ARGS=(
+            env
+            HOME="$isolated_home"
+            GROK_HOME="$isolated_grok_home"
+            "$GROK_CMD"
+            --prompt-file "$prompt_file"
+            -m "$GROK_MODEL"
+            --cwd "$isolated_workspace"
+            --output-format plain
+            --no-plan
+            --no-subagents
+            --no-memory
+            --disable-web-search
+            --max-turns 1
+            --permission-mode dontAsk
+            --sandbox strict
+            --tools ""
+            --deny Bash
+            --deny Edit
+            --deny Read
+            --deny Grep
+            --deny MCPTool
+            --deny WebFetch
+            --deny WebSearch
+            --verbatim
+        )
+
+        # Newer Grok Build releases document --no-auto-update for automation;
+        # keep compatibility with older installed builds that do not expose it.
+        if "$GROK_CMD" --help 2>&1 | grep -q -- '--no-auto-update'; then
+            GROK_ARGS+=("--no-auto-update")
+        fi
+
+        if run_query \
+                "$CONSULTANT_NAME" \
+                "$TEMP_OUTPUT" \
+                "$GROK_TIMEOUT_SECONDS" \
+                "${GROK_ARGS[@]}" </dev/null; then
+            exit_code=0
+        else
+            exit_code=$?
+        fi
+    else
+        log_warn "[$CONSULTANT_NAME] Grok Build CLI not found: $GROK_CMD"
+        exit_code=127
+    fi
+
+    # Fall back only when the CLI transport is genuinely unavailable. A timeout,
+    # model error, empty reply, or other post-launch failure is returned as-is so
+    # it cannot silently turn into a separately billed API request.
+    if [[ $exit_code -ne 0 ]] \
+            && grok_cli_is_unavailable "$exit_code" "${TEMP_OUTPUT}.err" \
+            && [[ -n "${GROK_API_KEY:-}" ]]; then
+        log_warn "[$CONSULTANT_NAME] Grok Build CLI unavailable (exit $exit_code); falling back to the xAI API"
+        TRANSPORT="api_fallback"
+        if run_grok_api; then
+            exit_code=0
+        else
+            exit_code=$?
+        fi
+    elif [[ $exit_code -ne 0 && -n "${GROK_API_KEY:-}" ]]; then
+        log_warn "[$CONSULTANT_NAME] Grok Build request failed after launch; API fallback suppressed"
+    fi
+fi
+
+END_TIME=$(get_timestamp_ms)
+LATENCY_MS=$((END_TIME - START_TIME))
+PERSONA_NAME=$(get_persona_name "$CONSULTANT_NAME")
+
+# The response builder intentionally returns the consultant exit code. Keep it
+# inside a conditional so `set -e` cannot skip transport metadata and cleanup
+# on the failure path.
+if process_consultant_response "$CONSULTANT_NAME" "$GROK_MODEL" "$PERSONA_NAME" \
+        "$TEMP_OUTPUT" "$OUTPUT_FILE" "$exit_code" "$LATENCY_MS" "" "$FULL_QUERY"; then
+    :
+else
+    :
+fi
+
+# Preserve which route actually answered without changing the shared schema.
+if [[ -s "$OUTPUT_FILE" ]]; then
+    response_tmp=$(mktemp)
+    if jq --arg transport "$TRANSPORT" '.metadata.transport = $transport' \
+            "$OUTPUT_FILE" > "$response_tmp"; then
+        mv "$response_tmp" "$OUTPUT_FILE"
+    else
+        rm -f "$response_tmp"
+    fi
+fi
+
+cat "$OUTPUT_FILE"
+exit $exit_code

package/scripts/update_clis.sh

@@ -18,7 +18,7 @@
 # With no flags it updates every installed supported CLI, best-effort: a failure
 # on one CLI is reported and the rest still run. Some updates run the CLI's
 # official installer (curl | bash) -- use --dry-run first to see what will run.
-# API-only consultants (GLM, Grok, DeepSeek) have no CLI and are not listed here.
+# API-only consultants (GLM, DeepSeek) have no CLI and are not listed here.
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -39,6 +39,7 @@ _CLI_ENTRIES=(
     "Kimi|KIMI_CMD|kimi"
     "Claude|CLAUDE_CMD|claude"
     "Qwen3|QWEN3_CMD|qwen"
+    "Grok|GROK_CMD|grok"
     "MiniMax|MINIMAX_CMD|mmx"
 )
 
@@ -66,6 +67,7 @@ _cli_meta() {
         kimi)     SELF_SUB="upgrade"; INSTALLER="curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash" ;;
         claude)   BREW_CASK="claude-code@latest"; NPM_PKG="@anthropic-ai/claude-code"; SELF_SUB="update" ;;
         qwen)     NPM_PKG="@qwen-code/qwen-code" ;;
+        grok)     SELF_SUB="update"; INSTALLER="curl -fsSL https://x.ai/cli/install.sh | bash" ;;
         mmx)      NPM_PKG="mmx-cli"; SELF_SUB="update" ;;
     esac
 }