ai-consultants 3.1.1 → 3.3.0

package/.env.example

@@ -144,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

package/CLAUDE.md

@@ -6,7 +6,7 @@ AI Consultants is a multi-model coverage system that queries up to 11 AI consult
 
 **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.1.1
+**Version**: 3.3.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 |
@@ -613,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) |
@@ -786,6 +787,19 @@ curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/s
 
 ## Changelog
 
+### v3.3.0
+- **Grok and Kimi compatibility is now established from capabilities, not inferred from an installed binary or its version string.** `grok_cli_supports_required_interface` validates the complete headless parser surface inside the same isolated HOME/CWD boundary used for dispatch, while `grok_cli_exposes_requested_model` verifies both usable authentication and the exact `GROK_MODEL` in the CLI inventory (`scripts/query_grok.sh:85-154`). Kimi similarly checks prompt mode, `stream-json`, the provider inventory, and `KIMI_MODEL` before any request (`scripts/query_kimi.sh:45-79`). Compatible future and vendor-custom versions therefore continue to work without a release-specific allowlist; an interface that cannot enforce the adapter's contract fails before a model call.
+- **The observed CLI version is provenance only.** Successful Grok and Kimi responses add `metadata.cli_version` and `metadata.cli_compatibility="capability-probed"`; the shared schema documents both fields without making either required for other transports (`scripts/query_grok.sh:319-336`, `scripts/query_kimi.sh:126-138`, `scripts/lib/schema.json:169-180`). This deliberately does not introduce a blessed-version range: the version is useful for diagnosis, while compatibility is decided by the exercised command, output, and model surfaces.
+- **Optional capabilities remain optional.** Grok's `--no-auto-update` is used when the help surface advertises it, but its absence does not reject an otherwise compatible CLI. The capability probe itself uses `--help` and model/provider inventory commands; it does not send a consultation. Grok preserves its existing narrowly classified API fallback when the required CLI route is unavailable, while Kimi continues to fail closed because it has no API transport.
+- **Regression coverage pins the compatibility contract rather than today's binaries.** Grok's suite accepts an alternate compatible version, rejects an incomplete interface before dispatch, checks requested-model availability, and preserves the post-launch/API-fallback boundary (32 checks). Kimi's suite covers an alternate compatible version, an incomplete interface, and a missing requested model (8 checks). Full release gate: 17/17 suites; core suite: 299/299; ShellCheck green. Installed Grok 0.2.114 and Kimi 0.27.0 also passed no-model-call probes.
+
+### 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.
 

package/README.md

@@ -1,8 +1,8 @@
-# AI Consultants v3.1.1
+# AI Consultants v3.3.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.1.1-blue.svg)](https://github.com/matteoscurati/ai-consultants)
+[![Version](https://img.shields.io/badge/version-3.3.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)
@@ -388,7 +388,10 @@ 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.
+CLI/API switchable. Grok and Kimi compatibility is capability-probed before
+dispatch: the requested model, headless arguments, and structured-output
+surface must be available. Any CLI version is accepted when those checks pass;
+the observed version is response provenance only.
 
 ### API-Only Consultants
 
@@ -444,7 +447,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 |
@@ -546,7 +549,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
@@ -563,6 +572,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.1.1
+  version: 3.3.0
 ---
 
-# AI Consultants v3.1.1 - AI Expert Panel
+# AI Consultants v3.3.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.
 
@@ -45,6 +45,11 @@ Configuration (presets, strategies, features, personas, API keys) can be managed
 
 **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.
 
+Grok and Kimi are compatible by capability rather than by CLI version. Before
+dispatch, their adapters verify the required headless arguments, requested
+model, and structured-output surface. Compatible version changes are accepted;
+the observed version is recorded only as response provenance.
+
 **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.
 
 ## Requirements

package/docs/COST_RATES.md

@@ -1,4 +1,4 @@
-# Cost Rates - AI Consultants v3.1.1
+# Cost Rates - AI Consultants v3.3.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/JSON_SCHEMA.md

@@ -37,6 +37,8 @@ The schema is defined in `scripts/lib/schema.json` following JSON Schema Draft-0
     "tokens_output": 300,
     "latency_ms": 2345,
     "model_version": "gemini-3.1-pro-preview",
+    "cli_version": "0.27.0",
+    "cli_compatibility": "capability-probed",
     "timestamp": "2024-01-14T12:34:56Z"
   }
 }
@@ -209,6 +211,8 @@ Present only if Multi-Agent Debate is enabled (round >= 2):
 | `tokens_output` | integer | Completion tokens, when the provider reported them (API mode only) |
 | `latency_ms` | integer | Response time in ms |
 | `model_version` | string | Exact model version |
+| `cli_version` | string | Observed CLI version for provenance; never a compatibility gate |
+| `cli_compatibility` | string | Capability-probe result: `capability-probed` or `incompatible` |
 | `timestamp` | string | ISO 8601 timestamp |
 
 ## Enum Values

package/docs/cost_rates.json

@@ -1,10 +1,10 @@
 {
-  "version": "3.1.1",
-  "updated": "2026-07-16",
+  "version": "3.3.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.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/docs/releases/v3.3.0.md

@@ -0,0 +1,80 @@
+# Release v3.3.0
+
+**Date:** 2026-07-29
+**Type:** Minor — capability-based Grok and Kimi CLI compatibility
+**Previous:** v3.2.0
+
+## Highlights
+
+- Grok and Kimi now prove CLI compatibility from the interface they actually need, not from a version string.
+- Compatible future and vendor-custom CLI versions are accepted without a release-specific allowlist.
+- Incomplete interfaces and missing requested models are rejected before a model request begins.
+- Responses expose the observed CLI version as provenance alongside the capability-probe result.
+
+## What's New
+
+### Capability-based CLI compatibility
+
+Before dispatch, the Grok adapter validates its complete headless argument
+surface, strict sandbox controls, structured output, authentication state, and
+the requested model. The probe runs inside an isolated environment and does not
+send a consultation.
+
+Kimi now validates prompt mode, `stream-json`, provider inventory, and the exact
+configured model before dispatch. A CLI with a different version number remains
+compatible when these capabilities are present; a CLI that cannot satisfy the
+contract fails before a model call.
+
+Grok's `--no-auto-update` flag remains optional. It is enabled when the installed
+CLI advertises it and omitted otherwise, so a useful automation control does not
+become an accidental version constraint.
+
+### Diagnostic provenance
+
+Successful Grok and Kimi CLI responses now include:
+
+| Field | Meaning |
+|---|---|
+| `metadata.cli_version` | The version reported by the CLI, retained for diagnosis and provenance |
+| `metadata.cli_compatibility` | `capability-probed` when the required interface passed |
+
+These fields are additive. Existing response consumers and non-CLI transports
+do not need to provide them.
+
+### Verification
+
+- Full repository gate: 17/17 suites
+- Core suite: 299/299 checks
+- Grok adapter suite: 32/32 checks
+- Kimi adapter suite: 8/8 checks
+- ShellCheck: green
+- Installed Grok 0.2.114 and Kimi 0.27.0: no-model-call capability probes passed
+
+## Breaking Changes
+
+None — this release is backwards-compatible. No configuration changes are
+required.
+
+An installed Grok or Kimi CLI that lacks the adapter's required command,
+structured-output, or requested-model surface will now be rejected before
+dispatch instead of failing later during a consultation.
+
+## Upgrade Guide
+
+```bash
+# npx (no install)
+npx ai-consultants@latest "your question"
+
+# git clone install
+cd ~/.claude/skills/ai-consultants && git pull
+
+# curl | bash install
+curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/scripts/install.sh | bash
+```
+
+No configuration changes are required. If an adapter reports an incompatible
+CLI, update that CLI and run `ai-consultants doctor` before retrying.
+
+## Commits
+
+- `c7bad95` Harden CLI capability checks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-consultants",
-  "version": "3.1.1",
+  "version": "3.3.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.
@@ -235,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
@@ -246,16 +252,26 @@ 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.
+Set `GROK_USE_API=true` only to force the API path. The adapter accepts any CLI
+version that exposes the complete required headless interface and requested
+model; `metadata.cli_version` is provenance, not a version pin.
 
 `KIMI_MODEL` is passed directly to `kimi --model`, so `kimi-code/k3` overrides
-any older default stored in the user's Kimi CLI configuration.
+any older default stored in the user's Kimi CLI configuration. Kimi CLI
+compatibility is also capability-probed: prompt mode, `stream-json`, provider
+inventory, and the requested model must be present. No numeric CLI version is
+used as a gate.
 
 ## Model Quality Tiers (v2.5)
 

package/scripts/config.sh

@@ -271,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}"
 
@@ -581,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" ;;
@@ -778,4 +779,4 @@ EOF
 # VERSION
 # =============================================================================
 
-AI_CONSULTANTS_VERSION="3.1.1"
+AI_CONSULTANTS_VERSION="3.3.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")
@@ -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
 }
@@ -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/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)

package/scripts/lib/common.sh

@@ -902,6 +902,7 @@ resolve_response_tokens() {
 
 # Build metadata JSON for responses
 # Usage: build_response_metadata <latency_ms> <model> [error_msg] [tokens] [source]
+#        [tokens_input] [tokens_output] [provider_cost_usd]
 #
 # tokens_used was hardcoded to 0 until v2.25, which made every session's cost
 # report read $0.00 regardless of what was actually spent (calculate_session_cost
@@ -915,6 +916,7 @@ build_response_metadata() {
     local source="${5:-unknown}"
     local tokens_in="${6:-}"
     local tokens_out="${7:-}"
+    local provider_cost="${8:-}"
 
     jq -n \
         --argjson latency "$latency" \
@@ -925,9 +927,11 @@ build_response_metadata() {
         --arg source "$source" \
         --arg t_in "$tokens_in" \
         --arg t_out "$tokens_out" \
+        --arg provider_cost "$provider_cost" \
         '{tokens_used: $tokens, tokens_source: $source, latency_ms: $latency, model_version: $model, timestamp: $timestamp}
          + (if $t_in  != "" then {tokens_input:  ($t_in  | tonumber)} else {} end)
          + (if $t_out != "" then {tokens_output: ($t_out | tonumber)} else {} end)
+         + (if $provider_cost != "" then {provider_cost_usd: ($provider_cost | tonumber)} else {} end)
          + (if $error != "" then {error: $error} else {} end)'
 }
 
@@ -943,15 +947,14 @@ build_structured_response() {
     local tokens_source="${7:-unknown}"
     local tokens_in="${8:-}"
     local tokens_out="${9:-}"
-    local tokens_in="${8:-}"
-    local tokens_out="${9:-}"
+    local provider_cost="${10:-}"
 
     jq -n \
         --arg consultant "$consultant" \
         --arg model "$model" \
         --arg persona "$persona" \
         --argjson inner "$inner_json" \
-        --argjson metadata "$(build_response_metadata "$latency" "$model" "" "$tokens" "$tokens_source" "$tokens_in" "$tokens_out")" \
+        --argjson metadata "$(build_response_metadata "$latency" "$model" "" "$tokens" "$tokens_source" "$tokens_in" "$tokens_out" "$provider_cost")" \
         '{consultant: $consultant, model: $model, persona: $persona, response: $inner.response, confidence: $inner.confidence, metadata: $metadata}'
 }
 
@@ -967,13 +970,14 @@ build_fallback_response() {
     local tokens_source="${7:-unknown}"
     local tokens_in="${8:-}"
     local tokens_out="${9:-}"
+    local provider_cost="${10:-}"
 
     jq -n \
         --arg consultant "$consultant" \
         --arg model "$model" \
         --arg persona "$persona" \
         --arg response "$response_text" \
-        --argjson metadata "$(build_response_metadata "$latency" "$model" "" "$tokens" "$tokens_source" "$tokens_in" "$tokens_out")" \
+        --argjson metadata "$(build_response_metadata "$latency" "$model" "" "$tokens" "$tokens_source" "$tokens_in" "$tokens_out" "$provider_cost")" \
         '{consultant: $consultant, model: $model, persona: $persona,
           response: {summary: "Unstructured response - see detailed", detailed: $response, approach: "unknown", pros: [], cons: [], caveats: ["Unstructured output from consultant"]},
           confidence: {score: 5, reasoning: "Confidence not provided by consultant", uncertainty_factors: ["Non-standard response format"]},

package/scripts/lib/costs.sh

@@ -306,11 +306,8 @@ _billable_response_files() {
 # Calculate total session cost from responses
 # Usage: calculate_session_cost <responses_dir>
 #
-# Prefers the provider's own prompt/completion split when it was recorded
-# (API mode). The 60/40 guess is a last resort for CLI mode, which has no
-# split to record: consultations are large-context/short-reply, so applying it
-# to a measured total materially overstates cost when output rates exceed
-# input rates.
+# Prefers an exact provider cost when recorded (Claude CLI), then the provider's
+# prompt/completion split (API mode), and only then the legacy 60/40 guess.
 calculate_session_cost() {
     local responses_dir="$1"
     local total_cost=0
@@ -318,6 +315,13 @@ calculate_session_cost() {
 
     while IFS= read -r f; do
         [[ -n "$f" ]] || continue
+        local provider_cost
+        provider_cost=$(jq -r '.metadata.provider_cost_usd // empty' "$f" 2>/dev/null)
+        if [[ "$provider_cost" =~ ^[0-9]+([.][0-9]+)?$ ]]; then
+            total_cost=$(echo "scale=6; $total_cost + $provider_cost" | bc)
+            continue
+        fi
+
         local model input_tokens output_tokens
         model=$(jq -r '.model // "default"' "$f" 2>/dev/null)
         input_tokens=$(jq -r '.metadata.tokens_input // empty' "$f" 2>/dev/null)
@@ -338,6 +342,11 @@ calculate_session_cost() {
         total_cost=$(echo "scale=6; $total_cost + $cost" | bc)
     done < <(_billable_response_files "$responses_dir")
 
+    # Provider-reported costs may carry fewer decimal places than locally
+    # estimated values. Normalize the public result to the existing 6-place
+    # contract without changing its numeric value.
+    total_cost=$(echo "scale=6; $total_cost / 1" | bc)
+
     # bc drops the leading zero on sub-1 values (".115000"); restore it as
     # estimate_query_cost does, so callers can compare numerically.
     [[ "$total_cost" == .* ]] && total_cost="0$total_cost"
@@ -351,8 +360,9 @@ calculate_session_cost() {
 #
 # Two things can make the number less than it looks:
 #   - credit-billed models contribute 0 because they have no per-token price;
-#   - CLI-mode consultants have no provider token count, so their share is a
-#     4-chars-per-token approximation (metadata.tokens_source = "estimated").
+#   - CLI-mode consultants without provider usage have a 4-chars-per-token
+#     approximation (metadata.tokens_source = "estimated"). Claude CLI is the
+#     exception: its JSON envelope supplies measured usage and exact cost.
 # Both are stated rather than folded silently into a confident-looking total.
 #
 # Rescans the directory rather than reading state left by

package/scripts/lib/schema.json

@@ -167,6 +167,15 @@
           "type": "string",
           "description": "Exact model version string"
         },
+        "cli_version": {
+          "type": "string",
+          "description": "Observed consultant CLI version for provenance only; compatibility is not decided from this string."
+        },
+        "cli_compatibility": {
+          "type": "string",
+          "enum": ["capability-probed", "incompatible"],
+          "description": "Result of checking the CLI's required command, model, and structured-output capabilities before dispatch."
+        },
         "timestamp": {
           "type": "string",
           "format": "date-time",

package/scripts/query_claude.sh

@@ -4,9 +4,10 @@
 # Usage: ./query_claude.sh "question" [context_file] [output_file]
 #
 # Environment variables:
-#   CLAUDE_MODEL - Model to use (default: claude-opus-4-8)
+#   CLAUDE_MODEL - Model to use (default: claude-opus-5)
 #   CLAUDE_TIMEOUT - Timeout in seconds (default: 240)
 #   CLAUDE_USE_API - Use API mode instead of CLI (default: false)
+#   CLAUDE_API_MAX_TOKENS - API thinking + visible-output budget (default: 16384)
 #   ANTHROPIC_API_KEY - API key for API mode
 #   ENABLE_PERSONA - Enable "The Synthesizer" persona (default: true)
 
@@ -25,7 +26,7 @@ OUTPUT_FILE="${3:-/tmp/claude_response.json}"
 ENABLE_PERSONA="${ENABLE_PERSONA:-true}"
 CONSULTANT_NAME="Claude"
 CLAUDE_CMD="${CLAUDE_CMD:-claude}"
-MODEL_USED="${CLAUDE_MODEL:-claude-opus-4-8}"
+MODEL_USED="${CLAUDE_MODEL:-claude-opus-5}"
 
 # --- Build query ---
 FULL_QUERY=$(build_full_query "$QUERY" "$CONTEXT_FILE")
@@ -69,12 +70,13 @@ else
     log_api_mode_status "claude"
     check_command "$CLAUDE_CMD" "Claude CLI" "Visit https://docs.anthropic.com/en/docs/claude-code" || exit 1
 
-    # Claude CLI uses --print for non-interactive mode
+    # JSON output exposes provider-measured usage and cost. In particular,
+    # output_tokens includes adaptive thinking that is absent from .result.
     echo "$FULL_QUERY" | run_query \
         "Claude" \
         "$TEMP_OUTPUT" \
         "$CLAUDE_TIMEOUT_SECONDS" \
-        "$CLAUDE_CMD" --print --model "$MODEL_USED"
+        "$CLAUDE_CMD" --print --model "$MODEL_USED" --output-format json
 
     exit_code=$?
 fi
@@ -88,16 +90,45 @@ PERSONA_NAME=$(get_persona_name "$CONSULTANT_NAME")
 
 # --- Post-processing: wrap in full schema using shared helpers ---
 if [[ $exit_code -eq 0 && -f "$TEMP_OUTPUT" && -s "$TEMP_OUTPUT" ]]; then
-    RAW_RESPONSE=$(cat "$TEMP_OUTPUT")
-    read -r _TOK _TOK_SRC _TOK_IN _TOK_OUT <<< "$(resolve_response_tokens "$FULL_QUERY" "$RAW_RESPONSE")"
+    PROVIDER_COST=""
+    if ! is_api_mode "claude"; then
+        CLI_ENVELOPE=$(cat "$TEMP_OUTPUT")
+        if ! echo "$CLI_ENVELOPE" | jq -e \
+                '.type == "result" and (.result | type == "string")' >/dev/null 2>&1; then
+            rm -f "$TEMP_OUTPUT"
+            build_error_response "$CONSULTANT_NAME" "$MODEL_USED" "$PERSONA_NAME" \
+                "Claude CLI returned an invalid JSON result envelope" "$LATENCY_MS" > "$OUTPUT_FILE"
+            cat "$OUTPUT_FILE"
+            exit 1
+        fi
+        RAW_RESPONSE=$(echo "$CLI_ENVELOPE" | jq -r '.result')
+        _TOK_IN=$(echo "$CLI_ENVELOPE" | jq -r \
+            '([.modelUsage[]?
+                | (.inputTokens // 0)
+                  + (.cacheCreationInputTokens // 0)
+                  + (.cacheReadInputTokens // 0)] | add)
+             // ((.usage.input_tokens // 0)
+                 + (.usage.cache_creation_input_tokens // 0)
+                 + (.usage.cache_read_input_tokens // 0))')
+        _TOK_OUT=$(echo "$CLI_ENVELOPE" | jq -r \
+            '([.modelUsage[]? | (.outputTokens // 0)] | add)
+             // (.usage.output_tokens // 0)')
+        _TOK=$((_TOK_IN + _TOK_OUT))
+        _TOK_SRC="measured"
+        PROVIDER_COST=$(echo "$CLI_ENVELOPE" | jq -r \
+            '[.modelUsage[]?.costUSD | numbers] | add // empty')
+    else
+        RAW_RESPONSE=$(cat "$TEMP_OUTPUT")
+        read -r _TOK _TOK_SRC _TOK_IN _TOK_OUT <<< "$(resolve_response_tokens "$FULL_QUERY" "$RAW_RESPONSE")"
+    fi
     clear_api_token_split
     rm -f "$TEMP_OUTPUT"
 
     # Try to parse as structured JSON
     if echo "$RAW_RESPONSE" | jq -e '.response.summary' > /dev/null 2>&1; then
-        build_structured_response "$CONSULTANT_NAME" "$MODEL_USED" "$PERSONA_NAME" "$RAW_RESPONSE" "$LATENCY_MS" "$_TOK" "$_TOK_SRC" "$_TOK_IN" "$_TOK_OUT" > "$OUTPUT_FILE"
+        build_structured_response "$CONSULTANT_NAME" "$MODEL_USED" "$PERSONA_NAME" "$RAW_RESPONSE" "$LATENCY_MS" "$_TOK" "$_TOK_SRC" "$_TOK_IN" "$_TOK_OUT" "$PROVIDER_COST" > "$OUTPUT_FILE"
     else
-        build_fallback_response "$CONSULTANT_NAME" "$MODEL_USED" "$PERSONA_NAME" "$RAW_RESPONSE" "$LATENCY_MS" "$_TOK" "$_TOK_SRC" "$_TOK_IN" "$_TOK_OUT" > "$OUTPUT_FILE"
+        build_fallback_response "$CONSULTANT_NAME" "$MODEL_USED" "$PERSONA_NAME" "$RAW_RESPONSE" "$LATENCY_MS" "$_TOK" "$_TOK_SRC" "$_TOK_IN" "$_TOK_OUT" "$PROVIDER_COST" > "$OUTPUT_FILE"
     fi
 else
     rm -f "$TEMP_OUTPUT"

package/scripts/query_grok.sh

@@ -36,6 +36,9 @@ START_TIME=$(get_timestamp_ms)
 TEMP_OUTPUT=$(mktemp)
 GROK_RUNTIME_DIR=""
 TRANSPORT="cli"
+GROK_CLI_VERSION=""
+GROK_CLI_COMPATIBILITY=""
+GROK_SUPPORTS_NO_AUTO_UPDATE=false
 exit_code=1
 
 cleanup() {
@@ -67,6 +70,93 @@ run_grok_api() {
     fi
 }
 
+observe_grok_cli_version() {
+    local version
+    version=$("$GROK_CMD" --version 2>/dev/null | head -1 || true)
+    if [[ "$version" =~ ^grok[[:space:]]+([^[:space:]]+) ]]; then
+        printf '%s\n' "${BASH_REMATCH[1]}"
+    elif [[ -n "$version" ]]; then
+        printf '%s\n' "$version"
+    else
+        printf 'unknown\n'
+    fi
+}
+
+grok_cli_supports_required_interface() {
+    local probe_home="$1"
+    local probe_grok_home="$2"
+    local probe_workspace="$3"
+    local help flag
+
+    help=$(env HOME="$probe_home" GROK_HOME="$probe_grok_home" \
+        "$GROK_CMD" --help 2>&1 || true)
+    for flag in \
+        --prompt-file --model --cwd --output-format --no-plan --no-subagents \
+        --no-memory --disable-web-search --max-turns --permission-mode \
+        --sandbox --tools --deny --verbatim; do
+        grep -q -- "$flag" <<< "$help" || return 1
+    done
+    grep -Eq '^[[:space:]]+models([[:space:]]|$)' <<< "$help" || return 1
+
+    # Exercise the complete headless argument surface under --help. This checks
+    # parser compatibility without starting a session or sending a prompt.
+    env HOME="$probe_home" GROK_HOME="$probe_grok_home" \
+        "$GROK_CMD" \
+        --prompt-file /dev/null \
+        -m "$GROK_MODEL" \
+        --cwd "$probe_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 \
+        --help >/dev/null 2>&1 || return 1
+
+    if grep -q -- '--no-auto-update' <<< "$help"; then
+        GROK_SUPPORTS_NO_AUTO_UPDATE=true
+    else
+        GROK_SUPPORTS_NO_AUTO_UPDATE=false
+    fi
+    GROK_CLI_COMPATIBILITY="capability-probed"
+}
+
+grok_cli_exposes_requested_model() {
+    local isolated_home="$1"
+    local isolated_grok_home="$2"
+    local models
+
+    if ! models=$(env HOME="$isolated_home" GROK_HOME="$isolated_grok_home" \
+            "$GROK_CMD" models 2>&1); then
+        printf '%s\n' "$models"
+        return 1
+    fi
+    grep -Fq "You are logged in with grok.com." <<< "$models" || {
+        printf '%s\n' "$models"
+        return 1
+    }
+    awk -v requested="$GROK_MODEL" '
+        {
+            line = $0
+            sub(/^[[:space:]*]+/, "", line)
+            split(line, fields, /[[:space:]]+/)
+            if (fields[1] == requested) found = 1
+        }
+        END { exit(found ? 0 : 1) }
+    ' <<< "$models"
+}
+
 grok_cli_is_unavailable() {
     local cli_exit_code="$1"
     local error_file="$2"
@@ -85,7 +175,7 @@ grok_cli_is_unavailable() {
     # 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)' \
+        '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)|lacks the required capabilities|does not expose the requested model' \
         "$error_file"
 }
 
@@ -128,51 +218,66 @@ else
             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
+        GROK_CLI_VERSION=$(observe_grok_cli_version)
+        if ! grok_cli_supports_required_interface \
+                "$isolated_home" "$isolated_grok_home" "$isolated_workspace"; then
+            GROK_CLI_COMPATIBILITY="incompatible"
+            printf 'Grok Build CLI lacks the required capabilities\n' > "${TEMP_OUTPUT}.err"
+            log_warn "[$CONSULTANT_NAME] Grok Build CLI is capability-incompatible (reported version: $GROK_CLI_VERSION)"
+            exit_code=69
+        elif ! grok_cli_exposes_requested_model \
+                "$isolated_home" "$isolated_grok_home" > "${TEMP_OUTPUT}.err"; then
+            printf 'Grok Build CLI does not expose the requested model %s\n' \
+                "$GROK_MODEL" >> "${TEMP_OUTPUT}.err"
+            log_warn "[$CONSULTANT_NAME] Grok Build CLI does not expose $GROK_MODEL"
+            exit_code=69
         else
-            exit_code=$?
+            # 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
+            )
+
+            # --no-auto-update is a useful optional capability, not a version
+            # requirement. Compatible older or vendor-custom builds may omit it.
+            if [[ "$GROK_SUPPORTS_NO_AUTO_UPDATE" == "true" ]]; 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
         fi
     else
         log_warn "[$CONSULTANT_NAME] Grok Build CLI not found: $GROK_CMD"
@@ -214,7 +319,17 @@ 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' \
+    if jq --arg transport "$TRANSPORT" \
+            --arg cli_version "$GROK_CLI_VERSION" \
+            --arg cli_compatibility "$GROK_CLI_COMPATIBILITY" '
+            .metadata.transport = $transport |
+            if $transport == "cli" and $cli_version != "" then
+                .metadata.cli_version = $cli_version |
+                .metadata.cli_compatibility = $cli_compatibility
+            else
+                .
+            end
+        ' \
             "$OUTPUT_FILE" > "$response_tmp"; then
         mv "$response_tmp" "$OUTPUT_FILE"
     else

package/scripts/query_kimi.sh

@@ -40,9 +40,43 @@ START_TIME=$(get_timestamp_ms)
 
 # --- Execution ---
 TEMP_OUTPUT=$(mktemp)
+KIMI_CLI_VERSION=""
+
+observe_kimi_cli_version() {
+    local version
+    version=$("$KIMI_CMD" --version 2>/dev/null | head -1 || true)
+    printf '%s\n' "${version:-unknown}"
+}
+
+kimi_cli_supports_required_interface() {
+    local help providers flag
+
+    help=$("$KIMI_CMD" --help 2>&1 || true)
+    for flag in --model --prompt --output-format; do
+        grep -q -- "$flag" <<< "$help" || return 1
+    done
+    grep -Eq '^[[:space:]]+provider([[:space:]]|$)' <<< "$help" || return 1
+
+    # Check the complete prompt-mode parser without running a model request.
+    "$KIMI_CMD" \
+        --model "$KIMI_MODEL" \
+        --prompt "" \
+        --output-format stream-json \
+        --help >/dev/null 2>&1 || return 1
+
+    providers=$("$KIMI_CMD" provider list --json 2>/dev/null || true)
+    jq -e --arg model "$KIMI_MODEL" '
+        .models[$model] != null
+    ' <<< "$providers" >/dev/null 2>&1
+}
 
 # Check CLI prerequisite
 check_command "$KIMI_CMD" "Kimi CLI" "curl -L code.kimi.com/install.sh | bash" || exit 1
+KIMI_CLI_VERSION=$(observe_kimi_cli_version)
+kimi_cli_supports_required_interface || {
+    log_error "[Kimi] Kimi CLI lacks the required capabilities for model $KIMI_MODEL (reported version: $KIMI_CLI_VERSION)"
+    exit 1
+}
 
 # Kimi takes the prompt as the -p argument (it does NOT read stdin). The old
 # `--quiet --input-format text` were NOT real flags on kimi 0.23.6 — commander
@@ -89,5 +123,17 @@ PERSONA_NAME=$(get_persona_name "$CONSULTANT_NAME")
 process_consultant_response "$CONSULTANT_NAME" "$MODEL_USED" "$PERSONA_NAME" \
     "$TEMP_OUTPUT" "$OUTPUT_FILE" "$exit_code" "$LATENCY_MS" "" "$FULL_QUERY"
 
+if [[ -s "$OUTPUT_FILE" ]]; then
+    response_tmp=$(mktemp)
+    if jq --arg cli_version "$KIMI_CLI_VERSION" '
+            .metadata.cli_version = $cli_version |
+            .metadata.cli_compatibility = "capability-probed"
+        ' "$OUTPUT_FILE" > "$response_tmp"; then
+        mv "$response_tmp" "$OUTPUT_FILE"
+    else
+        rm -f "$response_tmp"
+    fi
+fi
+
 cat "$OUTPUT_FILE"
 exit $exit_code