ai-consultants 3.1.1 → 3.2.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.2.0
 
 ## Distribution
 
@@ -368,7 +368,7 @@ Three tiers of models are available for each consultant, configurable via `apply
 
 | Tier | Description | Example Models |
 |------|-------------|----------------|
-| **premium** | Latest flagship models | claude-opus-4-8, Gemini 3.1 Pro (High), gpt-5.5 |
+| **premium** | Latest flagship models | claude-opus-5, Gemini 3.1 Pro (High), gpt-5.5 |
 | **standard** | Good quality at reasonable cost | claude-sonnet-4-6, Gemini 3.5 Flash (High), gpt-5.4 |
 | **economy** | Optimized for speed and low cost | claude-haiku-4-5, Gemini 3.5 Flash (Low), gpt-5.4-nano |
 
@@ -400,12 +400,12 @@ Three new presets leverage the model tiers:
 ./scripts/consult_all.sh --preset fast "quick syntax question"
 ```
 
-### Premium Model Defaults (June 2026)
+### Premium Model Defaults (July 2026)
 All consultants now use premium models by default:
 
 | Consultant | Default Model |
 |------------|---------------|
-| Claude | claude-opus-4-8 |
+| Claude | claude-opus-5 |
 | Gemini | Gemini 3.1 Pro (High) (via agy CLI) |
 | Codex | gpt-5.5 |
 | Mistral | mistral-large-3 |
@@ -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,13 @@ curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/s
 
 ## Changelog
 
+### v3.2.0
+- **Claude premium upgraded from Opus 4.8 to Opus 5.** The default `CLAUDE_MODEL`, premium/max/best tier, standalone adapter fallback, configuration examples, model table, and cost catalog now resolve to the canonical `claude-opus-5` ID (`scripts/config.sh:274`, `scripts/query_claude.sh:29`). Pricing remains $5/$25 per million tokens; `claude-opus-4-8` stays in the legacy catalog for historical responses and intentional pins.
+- **Opus 5 adaptive thinking is accounted for end to end.** Claude CLI mode now requests the JSON result envelope, extracts visible `.result`, aggregates provider usage across `modelUsage`, and persists the provider's exact `costUSD` (`scripts/query_claude.sh:72-126`, `scripts/lib/common.sh:904-980`, `scripts/lib/costs.sh:307-354`). This fixes the review finding that pricing only the visible answer undercounted hidden thinking and cache charges. The implementation deliberately prefers provider cost over reconstructing cache pricing from token totals.
+- **Anthropic API responses no longer disappear when thinking precedes text.** `parse_anthropic_response` selects every `type=text` block rather than assuming `.content[0].text` (`scripts/lib/api.sh:325-343`). The API token budget is now the configurable `CLAUDE_API_MAX_TOKENS=16384`, shared by adaptive thinking and visible output; `stop_reason=max_tokens` fails closed instead of admitting a partial answer into synthesis (`scripts/lib/api_query.sh:94-153`).
+- **Historical generated defaults migrate with provenance.** Before this release, `init` copied `CLAUDE_MODEL=claude-opus-4-8` without distinguishing a generated default from a user pin, so the new runtime fallback was unreachable for existing installations. `configure` now upgrades that exact historical value to Opus 5 and writes `# ai-consultants:default`; model values supplied by environment, interactive input, or `--set` receive `# ai-consultants:pin` and survive later rewrites (`scripts/configure.sh:183-291`, `scripts/configure.sh:357-420`). An intentionally retained 4.8 value should be reasserted once with `--set CLAUDE_MODEL=claude-opus-4-8`.
+- **Verification expanded around all four review findings.** `test_query_claude.sh` exercises CLI JSON extraction, measured usage, provider cost persistence, and session billing. `test_api_transport.sh` covers thinking-before-text, the 16,384-token request default, invalid budgets, and truncation rejection; `test_configure.sh` covers managed migration and persistent pins. Full gate: 17/17 suites; core suite: 299/299; shellcheck green. The real maintainer config was not rewritten during implementation and remained on 4.8 until the release installation step.
+
 ### v3.1.1
 - **`doctor` no longer aborts at the first missing enabled consultant.** The v3.1.0 tag workflow exposed the pre-existing `set -e` interaction when Grok became CLI-first and the clean Ubuntu runner had no `grok` binary: the main JSON diagnostic exited before emitting output. Missing CLI/API configuration checks now add their issue and continue to the final summary, which still exits unhealthy. `test_doctor.sh` stubs the complete CLI roster, rejects empty JSON output, and includes a dedicated missing-Grok regression. Full gate: 16/16 suites; shellcheck green.
 

package/README.md

@@ -1,8 +1,8 @@
-# AI Consultants v3.1.1
+# AI Consultants v3.2.0
 
 > **Coverage, not a single guess.** A panel of up to 11 frontier models from different vendors fans out on your question in parallel and hands you the *union* of what they collectively see — the risks, edge cases, and approaches a single model misses.
 
-[![Version](https://img.shields.io/badge/version-3.1.1-blue.svg)](https://github.com/matteoscurati/ai-consultants)
+[![Version](https://img.shields.io/badge/version-3.2.0-blue.svg)](https://github.com/matteoscurati/ai-consultants)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-orange.svg)](https://docs.anthropic.com/en/docs/claude-code/skills)
 [![GitHub stars](https://img.shields.io/github/stars/matteoscurati/ai-consultants?style=social)](https://github.com/matteoscurati/ai-consultants)
@@ -444,7 +444,7 @@ parallel and returns the coverage union.
 
 | Consultant | Premium | Standard | Economy |
 |------------|---------|----------|---------|
-| Claude | claude-opus-4-8 | claude-sonnet-4-6 | claude-haiku-4-5 |
+| Claude | claude-opus-5 | claude-sonnet-4-6 | claude-haiku-4-5 |
 | Gemini | Gemini 3.1 Pro (High) | Gemini 3.5 Flash (High) | Gemini 3.5 Flash (Low) |
 | Codex | gpt-5.5 | gpt-5.4 | gpt-5.4-nano |
 | Mistral | mistral-large-3 | mistral-medium-latest | devstral-small-2 |
@@ -546,7 +546,13 @@ with `--set`). Rewrites create a private timestamped backup. Use `--advanced` to
 review every parameter or `--dry-run` to preview a redacted result.
 Auto-selected `*_USE_API` values are marked `# ai-consultants:auto`, allowing a
 later run to adapt when a CLI or credential changes. Environment variables,
-`--set`, and unmarked values remain explicit user choices.
+`--set`, and unmarked values remain explicit user choices, except for the exact
+historical generated Claude default described below.
+Managed model defaults use `# ai-consultants:default`; `configure` upgrades the
+historical unmarked `CLAUDE_MODEL=claude-opus-4-8` default to Opus 5. To keep
+4.8 intentionally, run
+`ai-consultants configure --set CLAUDE_MODEL=claude-opus-4-8`; explicit model
+overrides are stored with `# ai-consultants:pin`.
 
 Enter credentials through `--interactive`/`--advanced` or export them before the
 run; avoid passing API keys through `--set`, where the shell may retain them in
@@ -563,6 +569,7 @@ DEFAULT_STRATEGY=coverage    # coverage | compare_only | majority | risk_averse
 ENABLE_SMART_ROUTING=true    # Auto-select consultants by question category
 MAX_SESSION_COST=1.00        # USD budget cap (paired with ENABLE_BUDGET_LIMIT=true to enforce)
 KIMI_MODEL=kimi-code/k3      # Pin the Kimi consultant to K3
+CLAUDE_API_MAX_TOKENS=16384  # Shared thinking + visible-output budget in API mode
 ```
 
 Full reference: [`references/configuration.md`](references/configuration.md). Copy-paste workflows: [`docs/RECIPES.md`](docs/RECIPES.md). For category-aware preset suggestions: `ai-consultants doctor --suggest-preset --question "..."`.

package/SKILL.md

@@ -5,10 +5,10 @@ license: MIT
 compatibility: Requires bash, jq, and at least 2 AI CLI tools (agy, codex, vibe, etc.). macOS and Linux.
 metadata:
   author: matteoscurati
-  version: 3.1.1
+  version: 3.2.0
 ---
 
-# AI Consultants v3.1.1 - AI Expert Panel
+# AI Consultants v3.2.0 - AI Expert Panel
 
 **Coverage, not a single guess.** Convene a panel of AI "consultants" from different vendors for coding questions: they fan out in parallel and you get the *union* of what they collectively see — the risks, edge cases, and approaches a single model misses. Each consultant has a **configurable persona** that decorrelates its analysis.
 

package/docs/COST_RATES.md

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

package/docs/cost_rates.json

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

package/docs/releases/v3.2.0.md

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

package/package.json

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

package/references/configuration.md

@@ -54,6 +54,11 @@ ai-consultants configure --dry-run
 Use the hidden interactive credential prompts (or exported environment variables)
 for API keys; command-line arguments may be visible in shell history and process
 inspection.
+Model defaults carry an `# ai-consultants:default` marker. On rewrite,
+`configure` upgrades the historical unmarked
+`CLAUDE_MODEL=claude-opus-4-8` generated default to Opus 5. An explicit model
+override supplied with `--set` is stored with `# ai-consultants:pin`, so
+`--set CLAUDE_MODEL=claude-opus-4-8` keeps the legacy model intentionally.
 The exhaustive parameter contract is [`.env.example`](../.env.example); the
 configurator derives its accepted keys from that template, while
 [`scripts/config.sh`](../scripts/config.sh) remains the runtime source of truth.
@@ -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,6 +252,11 @@ 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

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.2.0"

package/scripts/configure.sh

@@ -181,6 +181,25 @@ set_value() {
 }
 
 AUTO_MARKER="# ai-consultants:auto"
+DEFAULT_MARKER="# ai-consultants:default"
+PIN_MARKER="# ai-consultants:pin"
+
+has_value_marker() {
+    local file="$1" key="$2" marker="$3" line normalized
+    [[ -r "$file" ]] || return 1
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        line="${line%$'\r'}"
+        [[ "$line" =~ ^[[:space:]]*# ]] && continue
+        normalized="${line#"${line%%[![:space:]]*}"}"
+        if [[ "$normalized" =~ ^export[[:space:]]+ ]]; then
+            normalized="${normalized#export}"
+            normalized="${normalized#"${normalized%%[![:space:]]*}"}"
+        fi
+        [[ "$normalized" == "$key="* ]] || continue
+        [[ "$normalized" == *"$marker"* ]] && return 0
+    done < "$file"
+    return 1
+}
 
 is_auto_managed_value() {
     local file="$1" key="$2" line normalized raw="" seen=false
@@ -239,13 +258,33 @@ set_auto_value() {
 # Merge existing persistent values first, then current environment overrides.
 while IFS= read -r key; do
     if [[ -f "$OUTPUT_FILE" ]] && value=$(read_value "$OUTPUT_FILE" "$key"); then
-        set_value "$key" "$value"
+        if has_value_marker "$OUTPUT_FILE" "$key" "$DEFAULT_MARKER"; then
+            set_value "$key" "$value $DEFAULT_MARKER"
+        elif has_value_marker "$OUTPUT_FILE" "$key" "$PIN_MARKER"; then
+            set_value "$key" "$value $PIN_MARKER"
+        else
+            set_value "$key" "$value"
+        fi
     fi
     if [[ -n "${!key+x}" ]]; then
-        set_value "$key" "${!key}"
+        if [[ "$key" == *_MODEL ]]; then
+            set_value "$key" "${!key} $PIN_MARKER"
+        else
+            set_value "$key" "${!key}"
+        fi
     fi
 done < <(list_parameters)
 
+# Before model defaults had provenance markers, `init` copied the then-current
+# Claude default as an ordinary-looking value. Refresh that exact historical
+# default when configure rewrites the file. A real legacy pin is preserved by
+# `--set CLAUDE_MODEL=claude-opus-4-8`, which records the pin marker.
+if [[ "$(read_value "$WORK_FILE" CLAUDE_MODEL 2>/dev/null || true)" == "claude-opus-4-8" ]] \
+    && ! has_value_marker "$WORK_FILE" CLAUDE_MODEL "$PIN_MARKER"; then
+    set_value CLAUDE_MODEL "claude-opus-5 $DEFAULT_MARKER"
+    echo "Migrated managed Claude default: claude-opus-4-8 -> claude-opus-5" >&2
+fi
+
 configure_cli_only() {
     local enable_key="$1" cmd_key="$2" cmd enabled=false
     cmd=$(effective_input_value "$cmd_key")
@@ -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/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"