ai-consultants 5.1.2 → 5.2.0

package/.claude/commands/ai-consultants:consult.md

@@ -15,7 +15,7 @@ Query multiple AI models for expert opinions on a coding question.
 1. If no question provided in $ARGUMENTS, ask the user what they want to consult about.
 
    Separate supported consultation options from the question before running the
-   panel. In particular, preserve `--preset <name>` and `--strategy <name>` as
+   panel. In particular, preserve `--mode <name>`, `--preset <name>` and `--strategy <name>` as
    CLI arguments placed before the question; they are not part of the question
    text. Reject an incomplete option instead of guessing its value.
 
@@ -39,15 +39,30 @@ Query multiple AI models for expert opinions on a coding question.
    - Shell-quote every context-file path as one argument.
    - Install a shell trap that removes only the exact query file when the Bash
      invocation exits; question text must not persist in the temp directory.
+     Some harnesses (Codex) reject `rm -f`; `unlink "<file>"` removes it too.
    - Capture `caller_root="$PWD"` before changing directories. Pass it through
      `--context-root` so regular files from the user's project are staged under
      a private temp directory without widening the runtime filesystem allowlist.
 
    ```bash
-   caller_root="$PWD"; cd "${AI_CONSULTANTS_DIR:-$HOME/.claude/skills/ai-consultants}" && INVOKING_AGENT=claude ./scripts/consult_all.sh [--preset <name>] [--strategy <name>] --context-root "$caller_root" --query-file "<private-question-file>" "<file1[@TAG]>" "<file2[@TAG]>" ...
+   caller_root="$PWD"; cd "${AI_CONSULTANTS_DIR:-$HOME/.claude/skills/ai-consultants}" && INVOKING_AGENT=claude ./scripts/consult_all.sh [--mode <name> | --preset <name>] [--strategy <name>] --context-root "$caller_root" --query-file "<private-question-file>" "<file1[@TAG]>" "<file2[@TAG]>" ...
    ```
    - Each `<fileN>` is a file path, optionally suffixed with `@PRIMARY` or `@CONTEXT`.
-   - **Capture the last line of stdout** — it contains the output directory path (e.g., `/tmp/ai_consultations/20260315_143022_12345/`).
+   - **Capture the last line of stdout** — it contains the output directory path (e.g., `~/.cache/ai-consultants/consultations/20260315_143022_12345`).
+   - **No time limit by default.** Reasoning models can take several minutes.
+     If your shell tool can run a command in the background and read its output
+     while it runs, do so; otherwise use the longest timeout your tool allows.
+   - While waiting, the run logs `Output: <output_dir>` near the start and
+     `Still waiting after Ns for: <consultants>` every 30 seconds. You decide
+     when to stop waiting:
+     - `touch "<output_dir>/.proceed"` continues with the answers already
+       received: consultants still running are stopped, then synthesis runs.
+       Sent during synthesis, it skips the synthesis.
+     - `touch "<output_dir>/.abort"` ends the run and keeps the partial output.
+     Stopping does not cancel what a provider already generated and billed, so
+     keep waiting unless the user wants results now or a consultant looks stuck
+     (for example, far slower than the rest of the panel). Never stop the run
+     with SIGKILL: it would leave consultant CLIs running. Use `.abort` or SIGTERM.
    - Keep `INVOKING_AGENT=claude` exactly as shown. Never invoke
      `query_claude.sh` directly and never remove self-exclusion to increase the
      panel count.
@@ -56,7 +71,7 @@ Query multiple AI models for expert opinions on a coding question.
    - Read `<output_dir>/report.md` using the **Read** tool
    - Read `<output_dir>/synthesis.json` using the **Read** tool (may not exist if synthesis was skipped or failed)
    - If neither exists, use the **Glob** tool with pattern `<output_dir>/*.json` to discover individual consultant response files, then read each one
-   - `claude.json` must not exist and `.synthesis_provider` must not be
+   - `claude.json` must not exist and the `synthesis_provider` field of `synthesis.json` must not be
      `claude`. If either appears, report a self-exclusion failure instead of
      presenting the run as valid.
 
@@ -89,7 +104,8 @@ Query multiple AI models for expert opinions on a coding question.
      ```bash
      cd "${AI_CONSULTANTS_DIR:-$HOME/.claude/skills/ai-consultants}" && ./scripts/doctor.sh
      ```
-   - **Exit code 124** (timeout): Suggest `--preset fast` for quicker results or increasing the timeout (e.g., `GEMINI_TIMEOUT=300`)
+   - **Consultant timeouts** (`Timeout after …s` in the output): a hard limit was set with `<NAME>_TIMEOUT`. Suggest `0` (no limit, the default) or `--mode fast-check` for quicker results
+   - **Stopped consultants** (`Stopped by the host`): present the answers received and name the consultants that were stopped before answering
    - **Partial failures** (some consultants responded, others didn't): Present the successful results normally and note which consultants failed at the end
    - **Empty output directory** (no JSON files produced): Suggest running `doctor.sh` to verify CLI installations and API keys
 

package/.env.example

@@ -1,14 +1,16 @@
 # =============================================================================
 # AI Consultants - Environment Variables
 # =============================================================================
-# Copy this file to .env and customize as needed.
-# All variables have sensible defaults - only override what you need.
+# Template for the private user configuration, normally
+# ~/.config/ai-consultants/.env (created by `ai-consultants init`, or written
+# with detected values by `ai-consultants configure`). Another private
+# directory can be selected with AI_CONSULTANTS_CONFIG_DIR; a project .env is
+# never read automatically. Keep the file at mode 600: it may hold API keys.
+# All variables have sensible defaults - only override what you need, and
+# exported environment variables take precedence over this file.
 #
 # IMPORTANT: At least 2 consultants must be enabled for the system to work.
 #
-# Export variables before running, or source this file:
-#   source .env && ./scripts/consult_all.sh "Your question"
-#
 # For detailed setup instructions, see: docs/SETUP.md
 
 # =============================================================================
@@ -18,7 +20,7 @@
 # or use the CLI's built-in auth flow.
 
 # Google Gemini API key (only needed for API mode; the agy CLI uses OAuth)
-# Get yours at: https://makersuite.google.com/app/apikey
+# Get yours at: https://aistudio.google.com/apikey
 # CLI mode uses the Antigravity CLI (agy); sign in by running `agy` once.
 # GEMINI_API_KEY=your-google-api-key
 
@@ -77,9 +79,12 @@ ENABLE_GROK=true
 ENABLE_MINIMAX=true
 ENABLE_CLAUDE=true
 
-# API-only consultants (default: disabled - require API keys)
-ENABLE_GLM=false
-ENABLE_DEEPSEEK=false
+# API-only consultants (default: disabled - require API keys).
+# Left commented on purpose: an explicit "false" is a durable opt-out that
+# presets (including max_quality) will never override, even once a key is
+# added. Uncomment with "true" after setting the key, or run `configure`.
+# ENABLE_GLM=true
+# ENABLE_DEEPSEEK=true
 
 # =============================================================================
 # CLI/API MODE SWITCHING (v2.6+)
@@ -112,29 +117,33 @@ ENABLE_DEEPSEEK=false
 #   https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
 
 # =============================================================================
-# MODEL CONFIGURATION (August 2026 premium defaults)
+# MODEL CONFIGURATION (October 2026 premium defaults)
 # =============================================================================
 
 # Gemini - The Architect (CLI mode via Antigravity CLI: agy)
-GEMINI_MODEL="Gemini 3.8 Flash (High)"
-GEMINI_TIMEOUT=180
+GEMINI_MODEL="Gemini 4 Argon (High)"
+GEMINI_TIMEOUT=0
 GEMINI_CMD=agy
-# API-mode model ID (only used when GEMINI_USE_API=true)
-GEMINI_API_MODEL=gemini-3.1-pro-preview
-# Gemini 3.1 Pro and 3.6 Flash remain valid CLI pins. API mode stays on the
-# separately verified 3.1 Pro ID; gemini-3.8-flash is an API-only opt-in until
-# that transport completes its own authenticated smoke.
+# API-mode model ID (only used when GEMINI_USE_API=true). Gemini 4 Argon needs
+# a paid-tier key: Google excludes it from the Free tier and the AI Pro plan.
+GEMINI_API_MODEL=gemini-4-argon
+# Argon's thinking tokens count toward this output budget (API only).
+GEMINI_API_MAX_TOKENS=32768
+# Pin "Gemini 3.8 Flash (High)" or gemini-3.1-pro-preview to keep the previous
+# targets; Gemini 3.1 Pro and 3.6 Flash remain valid CLI pins. gemini-3.8-flash
+# is an API-only opt-in until that transport completes its own authenticated smoke.
 # Reasoning effort for the agy CLI, passed as --effort <value>. Current agy
-# advertises low|medium|high|max globally, but named Gemini 3.8 High/Medium/Low
-# variants reject --effort: leave GEMINI_REASONING_EFFORT unset for those CLI
-# targets and choose the level with GEMINI_MODEL. Native Gemini 3.7/3.8 Flash
-# API thinking supports low|medium|high through this setting.
+# advertises low|medium|high|max globally, but named Gemini 4 Argon and 3.8
+# High/Medium/Low variants reject --effort: leave GEMINI_REASONING_EFFORT unset
+# for those CLI targets and choose the level with GEMINI_MODEL. Native Gemini
+# 3.7/3.8 Flash and 4 Argon API thinking supports low|medium|high through this
+# setting; Argon defaults to high, matching its CLI target.
 # GEMINI_REASONING_EFFORT=
 
 # Codex - The Pragmatist
-CODEX_MODEL=gpt-6-astra
+CODEX_MODEL=gpt-6.1-sol
 CODEX_API_MAX_TOKENS=16384
-CODEX_TIMEOUT=180
+CODEX_TIMEOUT=0
 CODEX_CMD=codex
 # Reasoning effort for the codex CLI (and API mode). Passed as
 # -c model_reasoning_effort=<value>. The provider owns the accepted enum;
@@ -142,28 +151,29 @@ CODEX_CMD=codex
 # CODEX_REASONING_EFFORT=
 
 # Mistral Vibe - The Devil's Advocate
-# API model ID. Vibe uses the separate CLI alias below. Mistral Medium 3.5,
-# Large 3, and Small 4 API IDs are documented opt-ins until an API smoke passes.
-MISTRAL_MODEL=mistral-large-3
+# API model ID (MISTRAL_USE_API=true only). Vibe uses the separate CLI alias
+# below. Mistral Large 4 is a public preview and is absent from GET /v1/models
+# even when the key can call it. Pin mistral-large-3 to keep the previous target.
+MISTRAL_MODEL=mistral-large-4
 MISTRAL_CLI_MODEL=mistral-medium-3.5
-MISTRAL_API_MAX_TOKENS=4096
+MISTRAL_API_MAX_TOKENS=16384
 # Official API opt-ins: use mistral-medium-3-5, mistral-large-2512, or
 # mistral-small-2603 for MISTRAL_MODEL after an authenticated API smoke.
-MISTRAL_TIMEOUT=180
+MISTRAL_TIMEOUT=0
 MISTRAL_CMD=vibe
 MISTRAL_MAX_TURNS=4
 
 # Kimi - The Eastern Sage (K3 via Kimi Code CLI)
 KIMI_MODEL=kimi-code/k3
 # max_quality selects the inventory-probed kimi-code/k3-256k target.
-KIMI_TIMEOUT=180
+KIMI_TIMEOUT=0
 KIMI_CMD=kimi
 
 # Claude - The Synthesizer
 CLAUDE_MODEL=claude-fable-5-1 # ai-consultants:default
 # For the lower-cost standard/medium Claude tier, set CLAUDE_MODEL to
 # claude-opus-5-5 (or apply_model_tier standard for a single run).
-CLAUDE_TIMEOUT=240
+CLAUDE_TIMEOUT=0
 CLAUDE_CMD=claude
 CLAUDE_API_MAX_TOKENS=16384
 # Reasoning effort for the claude CLI (and API mode). Passed as --effort <value>.
@@ -172,14 +182,14 @@ CLAUDE_API_MAX_TOKENS=16384
 # CLAUDE_REASONING_EFFORT=
 
 # Qwen3 - The Analyst (CLI/API switchable v2.7)
-QWEN3_MODEL=qwen3.7-max
-QWEN3_TIMEOUT=180
-QWEN3_MAX_QUALITY_TIMEOUT=600
+QWEN3_MODEL=qwen3.8-max
+QWEN3_TIMEOUT=0
+QWEN3_MAX_QUALITY_TIMEOUT=0
 QWEN3_API_MAX_TOKENS=16384
 QWEN3_CMD=qwen
 # Reasoning effort. API mode ONLY - the qwen CLI has no effort flag, so in CLI
-# mode this is ignored (with a warning); set model.reasoningEffort in
-# ~/.qwen/settings.json instead. Accepted: none|minimal|low|medium|high|xhigh|max
+# mode this is ignored (with a warning); configure the effort in
+# ~/.qwen/settings.json instead (see docs/RECIPES.md). Accepted: none|minimal|low|medium|high|xhigh|max
 # (the provider's own enum). The valid subset depends on the model:
 # qwen3.8-max takes all of them EXCEPT 'none' - thinking cannot be
 # disabled on it - and defaults to xhigh. An unsupported combination is
@@ -201,7 +211,7 @@ QWEN3_CMD=qwen
 
 # GLM - The Methodologist
 GLM_MODEL=glm-5.3-flash
-GLM_TIMEOUT=180
+GLM_TIMEOUT=0
 GLM_API_MAX_TOKENS=16384
 GLM_API_URL=https://api.z.ai/api/coding/paas/v4/chat/completions
 # GLM_REASONING_EFFORT=  # max_quality sets max
@@ -209,7 +219,7 @@ GLM_API_URL=https://api.z.ai/api/coding/paas/v4/chat/completions
 # Grok Build CLI + xAI API fallback - The Provocateur
 GROK_CMD=grok
 GROK_MODEL=grok-4.7
-GROK_TIMEOUT=180
+GROK_TIMEOUT=0
 GROK_MAX_TURNS=4
 GROK_OAUTH_MODE=shared
 GROK_API_MAX_TOKENS=4096
@@ -218,8 +228,8 @@ GROK_API_URL=https://api.x.ai/v1/chat/completions
 
 # DeepSeek - The Code Specialist
 DEEPSEEK_MODEL=deepseek-flash
-DEEPSEEK_TIMEOUT=180
-DEEPSEEK_MAX_QUALITY_TIMEOUT=600
+DEEPSEEK_TIMEOUT=0
+DEEPSEEK_MAX_QUALITY_TIMEOUT=0
 DEEPSEEK_API_MAX_TOKENS=16384
 DEEPSEEK_API_URL=https://api.deepseek.com/v1/chat/completions
 # DEEPSEEK_REASONING_EFFORT= # max_quality sets max
@@ -228,7 +238,7 @@ DEEPSEEK_API_URL=https://api.deepseek.com/v1/chat/completions
 MINIMAX_CMD=mmx
 MINIMAX_MODEL=MiniMax-M2.7
 # max_quality selects the smoke-tested MiniMax-M3 target.
-MINIMAX_TIMEOUT=180
+MINIMAX_TIMEOUT=0
 MINIMAX_API_MAX_TOKENS=4096
 MINIMAX_MAX_TOKENS=4096
 MINIMAX_MAX_QUALITY_TOKENS=16384
@@ -269,8 +279,8 @@ SYNTHESIS_MODEL=
 SYNTHESIS_EXTRACT_FIELDS=true
 SYNTH_MAX=10
 SYNTH_DETAIL_MAX_CHARS=4000
-SYNTHESIS_TIMEOUT=240
-SYNTHESIS_TOTAL_TIMEOUT=480
+SYNTHESIS_TIMEOUT=0
+SYNTHESIS_TOTAL_TIMEOUT=0
 
 # Health gate and quorum: validate the live panel before spending on a full run
 ENABLE_HEALTH_GATE=false       # Adds one small ping per selected consultant
@@ -291,7 +301,8 @@ API_BASE_BACKOFF=2
 API_MAX_BACKOFF=60
 API_RATE_LIMIT=30
 
-# Optional response limits by question category
+# Deprecated no-op, kept for configuration compatibility: no adapter applies
+# these per-category limits. Use the *_API_MAX_TOKENS settings instead.
 ENABLE_RESPONSE_LIMITS=false
 MAX_RESPONSE_TOKENS_BY_CATEGORY=QUICK_SYNTAX:200,CODE_REVIEW:800,BUG_DEBUG:800,ARCHITECTURE:1000,SECURITY:1000,DATABASE:600,GENERAL:500
 
@@ -310,6 +321,9 @@ MAX_SESSION_COST=1.00
 # Question classification (required for smart routing)
 ENABLE_CLASSIFICATION=true
 CLASSIFICATION_MODE=pattern  # pattern (fast) or llm (accurate)
+# llm mode asks the Claude CLI (economy model, stateless, tool-free) and is
+# skipped when Claude is the invoking host. Bounded by this timeout (seconds).
+# CLASSIFICATION_TIMEOUT=30
 
 # Smart routing: select consultants based on question category
 ENABLE_SMART_ROUTING=false
@@ -359,6 +373,30 @@ MAX_RETRIES=2                # Max retry attempts on failure
 RETRY_DELAY_SECONDS=5        # Pause between retries
 LAUNCH_STAGGER_MAX_SECONDS=2
 
+# Every *_TIMEOUT for consultants and synthesis defaults to 0: no time limit.
+# A timed-out call is usually still billed while its answer is lost, so the
+# invoking host decides when to stop waiting. While consult_all.sh waits it
+# logs progress every WAIT_HEARTBEAT_SECONDS (0 = silent) and accepts:
+#   touch <output dir>/.proceed   continue with the answers received
+#                                 (also: kill -USR1 <pid>, or a first Ctrl-C)
+#   touch <output dir>/.abort     end the run (also: SIGTERM, or a second Ctrl-C)
+# A positive *_TIMEOUT restores a hard limit for that consultant.
+WAIT_HEARTBEAT_SECONDS=30
+# agy can print its whole answer and then never exit. When its output is one
+# complete JSON object unchanged for this many seconds, the run ends agy and
+# keeps the answer (0 = always wait for agy to exit).
+AGY_EXIT_GRACE_SECONDS=60
+
+# Agentic consultant CLIs (agy, qwen, kimi) run from a private empty working
+# directory so they cannot load project instructions or read files beyond the
+# built context. Set to false to run them from the current directory.
+# CLI_WORKSPACE_ISOLATION=true
+
+# agy, vibe and kimi accept the prompt only as a command-line argument, which
+# is visible in the process list and size-limited (128 KiB per argument on
+# Linux). Larger prompts fail before dispatch; override the computed limit here.
+# ARGV_PROMPT_MAX_BYTES=
+
 # Output directory base
 # DEFAULT_OUTPUT_DIR_BASE=/custom/cache/consultations
 

package/CLAUDE.md

@@ -6,7 +6,7 @@ AI Consultants is a multi-model coverage system that queries up to 10 AI consult
 
 **Self-Exclusion**: The invoking agent is automatically excluded from both the panel and synthesis. Claude Code won't query or synthesize with Claude, Codex CLI won't query or synthesize with Codex, etc.
 
-**Version**: 5.1.2
+**Version**: 5.2.0
 
 ## Distribution
 
@@ -33,7 +33,6 @@ ai-consultants/
 ├── bin/
 │   └── ai-consultants          # npm/npx entry point (bash wrapper)
 ├── package.json                # npm distribution metadata (zero dependencies)
-├── .npmignore                  # Excludes dev artifacts from npm package
 ├── scripts/
 │   ├── consult_all.sh          # Main orchestrator - entry point
 │   ├── config.sh               # Centralized configuration
@@ -52,9 +51,13 @@ ai-consultants/
 │       ├── schema.json         # JSON output schema
 │       ├── routing.sh          # Smart routing (category affinity) + cost-aware routing
 │       ├── session.sh          # Session management
-│       ├── costs.sh            # Cost tracking + response limits
+│       ├── costs.sh            # Cost tracking + budget enforcement
 │       ├── cache.sh            # Semantic caching (v2.3)
 │       ├── api_query.sh        # API mode query execution (v2.6)
+│       ├── response_canonicalize.jq   # Consultant answer repairs before validation
+│       ├── synthesis_canonicalize.jq  # synthesis.json contract
+│       ├── json_schema_check.jq       # jq-only schema validator used by tests
+│       ├── agy_exit_guard.sh   # Keeps a complete agy answer when agy never exits
 │       └── progress.sh         # Progress bars
 ├── references/
 │   ├── configuration.md      # Full configuration reference
@@ -67,7 +70,7 @@ ai-consultants/
 │   ├── SMART_ROUTING.md      # Affinity matrix
 │   └── JSON_SCHEMA.md        # Output schema
 └── templates/
-    └── synthesis_prompt.md     # Synthesis prompt
+    └── synthesis_prompt.md     # Reference copy only; the runtime prompt is inline in synthesize.sh
 ```
 
 ## Claude Skills Compliance
@@ -235,9 +238,9 @@ curl -L code.kimi.com/install.sh | bash
 ```
 
 **Environment Variables:**
-- `ENABLE_KIMI` - Enable Kimi consultant (default: false)
+- `ENABLE_KIMI` - Enable Kimi consultant (default: true)
 - `KIMI_CMD` - CLI command (default: kimi)
-- `KIMI_TIMEOUT` - Timeout in seconds (default: 180)
+- `KIMI_TIMEOUT` - Timeout in seconds (default: 0, no limit)
 - `KIMI_MODEL` - Kimi CLI model alias (default: kimi-code/k3; passed explicitly with `--model`)
 
 **Persona:** The Eastern Sage - Focuses on holistic understanding, balance of perspectives, and wisdom from diverse viewpoints.
@@ -349,8 +352,8 @@ Three normal tiers plus a `maximum` tier are configurable via `apply_model_tier(
 
 | Tier | Description | Example Models |
 |------|-------------|----------------|
-| **premium** | Latest flagship models | claude-fable-5-1, Gemini 3.8 Flash (High), gpt-6-astra |
-| **maximum** | All 10 consultants; maximum targets and highest provider effort | claude-fable-5-1, K3-256k, Qwen3.8-Max, MiniMax M3; Grok xhigh, GLM/DeepSeek max |
+| **premium** | Latest flagship models | claude-fable-5-1, Gemini 4 Argon (High), gpt-6.1-sol |
+| **maximum** | All 10 consultants; maximum targets and highest provider effort | claude-fable-5-1, Gemini 4 Argon (High), K3-256k, Qwen3.8-Max, MiniMax M3; Grok xhigh, GLM/DeepSeek max |
 | **standard** | Good quality at reasonable cost | claude-opus-5-5, Gemini 3.8 Flash (High), gpt-5.6-terra |
 | **economy** | Optimized for speed and low cost | claude-haiku-4-5, Gemini 3.8 Flash (Low), gpt-5.6-luna |
 
@@ -365,7 +368,7 @@ apply_model_tier "standard"  # Set all consultants to standard models
 apply_model_tier "economy"   # Set all consultants to economy models
 
 # Get model for a specific consultant and tier (v2.8.1)
-get_model_for_tier "gemini" "premium"   # → Gemini 3.8 Flash (High) on agy
+get_model_for_tier "gemini" "premium"   # → Gemini 4 Argon (High) on agy
 get_model_for_tier "claude" "economy"   # → claude-haiku-4-5
 ```
 
@@ -389,13 +392,13 @@ All consultants now use premium models by default:
 | Consultant | Default Model |
 |------------|---------------|
 | Claude | claude-fable-5-1 |
-| Gemini | Gemini 3.8 Flash (High) (via agy CLI); API: gemini-3.1-pro-preview |
-| Codex | gpt-6-astra |
-| Mistral | CLI: mistral-medium-3.5; API: mistral-large-3 |
+| Gemini | Gemini 4 Argon (High) (via agy CLI); API: gemini-4-argon |
+| Codex | gpt-6.1-sol (max_quality: gpt-6-astra) |
+| Mistral | CLI: mistral-medium-3.5; API: mistral-large-4 (preview) |
 | DeepSeek | deepseek-flash (DeepSeek-V4.1-Flash) |
 | GLM | glm-5.3-flash |
 | Grok | grok-4.7 |
-| Qwen3 | qwen3.7-max |
+| Qwen3 | qwen3.8-max (standard/economy: qwen3.8-flash) |
 | Kimi | kimi-code/k3 |
 | MiniMax | MiniMax-M2.7 |
 
@@ -412,10 +415,10 @@ is surfaced and never silently rerouted to the API.
 
 The live full-panel smoke defines the `max_quality` runtime envelope, not just
 the model names. Mistral and Grok receive four bounded advisory turns plus an
-explicit no-tools/workspace instruction. Qwen3.8-Max gets a 600-second Token
-Plan timeout; DeepSeek V4 Pro/max gets 600 seconds and 16,384 completion tokens;
-GLM gets 16,384; MiniMax M3 gets 16,384 plus a compact Markdown contract in
-mmx's native system channel. OpenAI-compatible
+explicit no-tools/workspace instruction. Qwen3.8-Max and DeepSeek get
+`QWEN3_MAX_QUALITY_TIMEOUT`/`DEEPSEEK_MAX_QUALITY_TIMEOUT` (default 0, no limit);
+DeepSeek gets 16,384 completion tokens; GLM gets 16,384; MiniMax M3 gets 16,384
+plus the shared JSON response contract in mmx's native system channel. OpenAI-compatible
 `finish_reason=length` is an error. Every
 response records `metadata.response_quality=structured|fallback|error`:
 malformed JSON-looking output fails closed, while real markdown/prose is kept
@@ -463,18 +466,20 @@ Reduces redundant API calls by caching responses based on query + context finger
 # Configuration in config.sh
 ENABLE_SEMANTIC_CACHE=true      # Enable caching (default: true)
 CACHE_TTL_HOURS=24              # Cache expiration
-CACHE_DIR=/tmp/ai_consultants_cache
+CACHE_DIR=~/.cache/ai-consultants/cache   # XDG default
 ```
 
 Functions in `lib/cache.sh`:
-- `generate_fingerprint()` - Creates hash from query + category + context
+- `generate_fingerprint()` - Creates hash from query + category + context + consultant identity (`cache_identity()`: model, transport, effort, persona)
 - `check_cache()` - Returns cached response if valid
 - `store_cache()` - Stores response with metadata
 - `cleanup_cache()` - Removes expired entries
 - `get_cache_stats()` - Returns cache statistics as JSON
 
-### Response Length Limits (Opt-in)
-Limits output tokens by question category to reduce costs.
+### Response Length Limits (deprecated no-op)
+**Never applied by any adapter** (most consultant CLIs expose no output cap);
+the settings are accepted for configuration compatibility only. Use the
+`*_API_MAX_TOKENS` settings to bound API responses.
 
 ```bash
 ENABLE_RESPONSE_LIMITS=false    # Default: false (opt-in per quality review)
@@ -496,7 +501,7 @@ COMPLEXITY_THRESHOLD_MEDIUM=6   # Score 4-6 = medium, 7-10 = complex
 ```
 
 Functions in `lib/routing.sh`:
-- `select_consultants_cost_aware()` - Selects consultants based on complexity
+- `select_consultants_cost_aware()` - Selects consultants based on complexity (used by the smart-routing path)
 - `get_cost_aware_model()` - Returns economic model for simple queries
 - `calculate_query_complexity()` - Scores query 1-10
 
@@ -505,7 +510,12 @@ Functions in `lib/costs.sh`:
 - `get_model_tier()` - Returns economy/standard/premium
 
 ### Fallback Escalation
-Automatically re-queries with premium models if confidence is too low.
+Active only with `ENABLE_COST_AWARE_ROUTING=true`. Re-queries a **structured**
+response whose confidence is below the threshold on the consultant's premium
+model for its active transport (`model_env_var_for`). Error and fallback
+envelopes are never escalated, the same model is never re-asked, a
+maximum-tier target is never "escalated" to premium, and each re-query passes
+`enforce_budget` first.
 
 ```bash
 FALLBACK_CONFIDENCE_THRESHOLD=7  # Escalate if confidence < 7
@@ -586,17 +596,18 @@ 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-fable-5-1 | Claude model (use claude-opus-5 for lower-cost standard) |
+| `CLAUDE_MODEL` | claude-fable-5-1 | Claude model (use claude-opus-5-5 for lower-cost standard) |
 | `CLAUDE_API_MAX_TOKENS` | 16384 | Claude API thinking + visible-output budget |
-| `GEMINI_MODEL` | Gemini 3.8 Flash (High) | Gemini agy CLI model |
-| `GEMINI_API_MODEL` | gemini-3.1-pro-preview | Gemini API-mode model ID (v2.15) |
-| `CODEX_MODEL` | gpt-6-astra | Codex model (v2.5) |
-| `MISTRAL_MODEL` | mistral-large-3 | Mistral model (v2.5) |
+| `GEMINI_MODEL` | Gemini 4 Argon (High) | Gemini agy CLI model |
+| `GEMINI_API_MODEL` | gemini-4-argon | Gemini API-mode model ID (v2.15) |
+| `GEMINI_API_MAX_TOKENS` | 32768 | Gemini API thinking + visible-output budget |
+| `CODEX_MODEL` | gpt-6.1-sol | Codex model (max_quality: gpt-6-astra) |
+| `MISTRAL_MODEL` | mistral-large-4 | Mistral API model (Vibe uses `MISTRAL_CLI_MODEL`) |
 | `MISTRAL_CLI_MODEL` | mistral-medium-3.5 | Vibe CLI model alias |
 | `SYNTHESIS_STRATEGY` | coverage | Synthesis strategy (coverage=union of distinct points) |
 | `ENABLE_SEMANTIC_CACHE` | true | Semantic response caching (v2.3) |
 | `CACHE_TTL_HOURS` | 24 | Cache expiration in hours (v2.3) |
-| `ENABLE_RESPONSE_LIMITS` | false | Response token limits (v2.3, opt-in) |
+| `ENABLE_RESPONSE_LIMITS` | false | Deprecated no-op (never applied) |
 | `ENABLE_COST_AWARE_ROUTING` | false | Cost-based model routing (v2.3) |
 | `ENABLE_COMPACT_REPORT` | true | Compact report format (v2.3) |
 | `ENABLE_BUDGET_LIMIT` | false | Budget enforcement (v2.4, opt-in) |
@@ -629,17 +640,18 @@ The system handles errors with:
 
 - **Automatic retry**: `MAX_RETRIES` attempts (default: 2)
 - **Delay between retries**: `RETRY_DELAY_SECONDS` (default: 5s)
-- **Cross-platform timeout**: Supports Linux (`timeout`), macOS (`gtimeout`), and POSIX fallback
-- **Exit codes**: 0 = success, 1 = error, 124 = timeout
+- **Cross-platform timeout** (only when a positive `*_TIMEOUT` is set): Linux (`timeout`), macOS (`gtimeout`), and POSIX fallback
+- **Exit codes**: 0 = success, 1 = error, 124 = timeout; a host abort exits 130 (`.abort`, second Ctrl-C), 143 (SIGTERM) or 129 (SIGHUP)
 
 ```bash
 # Retry configuration
 MAX_RETRIES=3
 RETRY_DELAY_SECONDS=10
 
-# Per-consultant timeout
-GEMINI_TIMEOUT=240
-CODEX_TIMEOUT=180
+# Per-consultant timeout: 0 (default) = no limit; the invoking host decides
+# when to stop waiting (touch <output dir>/.proceed or .abort)
+GEMINI_TIMEOUT=0
+CODEX_TIMEOUT=0
 ```
 
 ## Extended Documentation
@@ -760,6 +772,27 @@ curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/s
 
 ## Changelog
 
+### v5.2.0 (2026-10-19)
+
+- **Host context described the wrong project.** Hosts `cd` into the skill root, and `build_context.sh` reported `pwd`/`find .` from there. `consult_all.sh` now runs it from `--context-root` (staged files are absolute temp paths, still admitted by `_is_temp_path`).
+- **API-only consultants never received the response contract.** `run_api_consultant` (GLM, DeepSeek, MiniMax API, custom agents) skipped `build_query_with_persona`, so every answer was prose -> fallback -> never attributable coverage, and `max_quality` could not reach `coverage_integrity=MET`. MiniMax CLI now gets the contract through `--system`. The live GLM smoke then exposed a nested/one-brace-short `confidence`; `normalize_consultant_response_text` lifts/repairs only that exact shape. Rejected payloads keep `metadata.raw_excerpt` so the next failure is diagnosable without a billed re-run.
+- **Cache key ignored the model.** `cache_identity()` (model/API/CLI model, transport, effort, format, URL, budgets, persona) is part of every fingerprint; `CACHE_KEY_VERSION` invalidates old entries once.
+- **Synthesis extraction** used a sed line range that ends at the first `}` line; now `strip_json_fence` then first-`{`..last-`}`. The synthesis call is estimated into `synthesis.json.synthesis_metadata` and billed by `calculate_session_cost` (`_synthesis_estimated_cost`).
+- **Follow-up** history stores the full query, `get_session_by_id` returns the current-session shape, whole-panel follow-ups run with `AI_CONSULTANTS_SKIP_SESSION_SAVE=true` inside the follow-up directory and are recorded on the original session.
+- **Transport privacy/limits.** Questions reach classify/build_context/synthesize via stdin (`-`); the request builders (`lib/api.sh`, `query_minimax.sh`) read the prompt with `jq --rawfile prompt /dev/stdin`, and curl gets headers and body through process substitution (`-H @<(...)`, `--data-binary @<(...)`), so neither the key nor the prompt is in argv or in a temp file a stopped query would leave behind. Process substitution does not survive the POSIX `run_with_timeout` fallback (the background job loses `/dev/fd/63`), so `doctor` bounds its probe with curl's own `-m`. `guard_argv_prompt_size` fails fast for argv-only CLIs (agy/vibe/kimi) and synthesis skips agy above the limit; agy/qwen/kimi run from `make_cli_workspace` directories. The POSIX timeout fallback never reads a TTY.
+- **Test gate hermeticity** now lives in `test_all.sh` (empty `AI_CONSULTANTS_CONFIG_DIR`, documented keys and `_AI_CONSULTANTS_*` markers unset), fixing the root cause of the release-gate leaks recorded in v2.23.0/v2.25.1/v3.0.0. `npm run lint` is the single lint invocation for CI and publish.
+- **JSON contracts.** `lib/response_canonicalize.jq` (consultant answers) and `lib/synthesis_canonicalize.jq` (synthesis.json) apply only deterministic, content-preserving repairs; `summary` is never derived from `detailed` (detailed text is deliberately not atomized) and a string `response` stays fallback prose. `lib/schema.json` v3 describes the real envelopes plus `synthesis_artifact`; `lib/json_schema_check.jq` + `assert_schema_valid` make it executable in tests. Estimates use `model_env_var_for` (tier + transport).
+- **Codex model policy.** `gpt-6.1-sol` is the default/premium Codex target and `gpt-6-astra` stays the maximum target (`get_model_for_tier`, `docs/cost_rates.json` premium tier and fallback). `_codex_frontier_model` in `lib/api.sh` gives both the implicit `high` effort and the none/minimal rejection (provider docs: low|medium|high|xhigh|max, default medium). `configure` migrates unpinned `gpt-6-astra` too and keeps the earliest `migrated-from`. One authorized CLI smoke passed (structured, measured usage, requested-only identity).
+- **Qwen/GLM policy.** `qwen3.8-max` is default/premium/maximum on all Qwen transports (the Token Plan-only gate in `apply_model_tier` is gone; `xhigh` is set only on the OpenAI-compatible wire, `QWEN3_MAX_QUALITY_TIMEOUT` everywhere, default 0); `qwen3.8-flash` serves standard/economy. GLM maximum is `glm-5.3`. Live checks passed for all four. 401/403 failures now carry the provider reason (`provider_error_summary`): a renewed Token Plan issues a new plan key, and DashScope without purchase returns `AccessDenied.Unpurchased`.
+- **Mistral API policy.** `mistral-large-4` (public preview, 2026-10-06) is `MISTRAL_MODEL` and every API tier; `configure` migrates unpinned `mistral-large-3`. Rates use the list price ($1.36/$4.18 per 1M), not the 50% preview price, so budgets fail safe. Evidence: one authorized 1-token chat call (2026-10-15) returned HTTP 200, provider-reported model `mistral-large-4`, `service_tier: standard`. `GET /v1/models` omits the preview (and every Large model) for that key, so listing is not an access check. A first `query_mistral.sh` smoke (same day, HTTP 200, 244 in / 3833 out tokens, ~44 s) failed closed because `message.content` was a chunk array (`thinking` + `text`); `parse_openai_response` now joins only `text` chunks (test in `test_api_transport.sh`). `MISTRAL_API_MAX_TOKENS` default 4096 -> 16384: that smoke spent 3833 of 4096 tokens, mostly thinking. A second authorized smoke after both fixes passed: `response_quality=structured`, provider-reported `mistral-large-4`, Devil's Advocate persona, confidence 9, 244 in / 3296 out measured tokens, ~44 s, schema-valid envelope. Vibe economy moved from the retired `devstral-small-2` to `mistral-medium-3.5`. Vibe stays on `mistral-medium-3.5`.
+- **Gemini policy.** Gemini 4 Argon (GA 2026-10-13; API ID `gemini-4-argon`, generateContent supported) serves maximum and premium/default: `Gemini 4 Argon (High)` on `agy`, `gemini-4-argon` on the API. Standard/economy keep `Gemini 3.8 Flash (High/Low)` on the CLI and `gemini-3.1-pro-preview` on the API (no shutdown announced; `gemini-3.8-flash` API stays opt-in until its own smoke). `configure` migrates unpinned `Gemini 3.8 Flash (High)` (plus the older Pro 3.1 / Flash 3.7 High values) and unpinned `gemini-3.1-pro-preview`. Rates use the list price ($4/$20 per 1M), not the introductory $2/$10 through 2026-11-30. API wire: `GEMINI_API_MAX_TOKENS` (default 32768, Google's minimum advice and per-request non-streaming cap) replaces the fixed 4096 because thinking counts toward `maxOutputTokens`; Argon accepts low|medium|high and defaults to `high` like its CLI target; no sampling parameters are sent (Argon ignores them); `parse_google_ai_response` joins visible text parts and skips `thought` parts. Evidence: `agy models` 1.3.6 lists Argon Low/Medium/High; one authorized `query_gemini.sh` CLI smoke on 2026-10-16 returned `response_quality=structured`, confidence 9, capability-probed identity, ~49 s, schema-valid (agy reports no usage, so tokens are estimated). No authenticated Gemini API smoke was run, so the API transport is offline-tested only. Google excludes Argon from the Free tier and the AI Pro plan. `GEMINI_TIMEOUT` defaults to 0 (no limit, see the timeout policy below), in line with Google's advice to use long client timeouts for hard prompts.
+- **Timeout policy.** Generation has no wall-clock limit by default: every consultant `*_TIMEOUT`, `QWEN3/DEEPSEEK_MAX_QUALITY_TIMEOUT` and `SYNTHESIS_TIMEOUT`/`SYNTHESIS_TOTAL_TIMEOUT` default to 0 (`run_with_timeout 0` runs the command directly; `run_api_query` omits curl `-m`; `format_timeout_label` logs "none"). Reason: a client timeout usually still bills the provider call and loses the answer, and Argon/Large 4 approach the old 180 s limit. The user explicitly rejected a safety ceiling. Instead the host decides: `consult_all.sh` polls children once per second (Bash 3.2 has no `wait -n`), logs a heartbeat every `WAIT_HEARTBEAT_SECONDS` (30), and honors *proceed* (`<dir>/.proceed`, SIGUSR1, first Ctrl-C: stop the current phase, continue with received answers; during synthesis, skip it) and *abort* (`<dir>/.abort`, SIGTERM 143, SIGHUP 129, second Ctrl-C 130). Stopped consultants become `NAME:STOPPED`: partial JSON deleted, counted against quorum, not recorded as a reliability failure, excluded from cost with a billing caveat. `lib/common.sh::kill_process_tree` freezes, terminates and finally kills the whole descendant tree (walked with portable `ps -A -o pid= -o ppid=`), with stderr silenced so Bash job-termination notices stay out of logs. Escalation and synthesis run in the background under `_wait_child_under_host_control`; traps are restored after synthesis. SIGKILL on `consult_all.sh` cannot clean up and would orphan CLIs (documented). Probe limits stay: agy inventory 10-12 s, auth 8-12 s, health gate 30 s, doctor live 45 s, LLM classifier 30 s (falls back to pattern). `configure` migrates unpinned generated 180/240/480/600 values to `0 # ai-consultants:default`; pins and custom values stay limits. Tests: `test_common.sh` Test 15, `test_api_transport.sh` (curl args), `test_configure.sh` (migration), `test_e2e.sh` Tests 6-8 (proceed via file, abort via file, SIGUSR1 during synthesis; all assert no surviving stub process).
+- **Review fixes (`/code-review max` on this branch).** `normalize_consultant_response_text` took its JSON-like probe from `sed`/`cut -c1`, which work line by line, so a pretty-printed truncated answer became a successful fallback instead of failing closed; it now reads the first non-blank character of the whole text, and a canonical result with several JSON values fails closed (it used to reach `build_structured_response --argjson` and leave an empty envelope). `run_api_query` wrote the key-bearing headers to a mktemp file that a stopped or killed query left on disk (reproduced with `kill_process_tree`); headers and body now go through process substitution, and the builders read the prompt from stdin (a 1.2 MB prompt previously produced an empty body via E2BIG). A host proceed during escalation ends the phase (`break`, it used to start the next billed re-query), and `_discard_late_proceed` keeps a request that lands after a phase finished from skipping the next one. The pattern classifier strips dependency/constructor/field/fault injection before the SECURITY check; `build_context.sh` never lists `$HOME` or `/` as the project tree; `provider_error_summary` reads string `error` fields (xAI); `json_schema_check.jq` reports an unknown definition or `$ref`; `kill_process_tree` re-lists the frozen tree until it is stable, from one `ps` snapshot per listing. Regression tests: `test_common.sh` Tests 8, 12, 13, 16; `test_api_transport.sh` (on-disk check, large prompts, xAI reason); `test_context_optimization.sh` Test 18; each failed on the pre-fix tree.
+- **Live verification after the review (2026-10-19).** Default models, `MAX_RETRIES=1`, cache off. `balanced` (Gemini Argon High agy, Sol CLI, Large 4 API): 3/3 structured, 181 s, reported $0.22 incl. synthesis. Every consultant enabled (`DEFAULT_PRESET=` override): 9/10 structured in 172 s, reported $0.59; synthesis represented 83/83 IDs, schema-valid. Kimi failed on an expired Kimi Code OAuth grant (`OAuthUnauthorizedError` in the CLI's session wire; nothing reached the model) and passed a separate single call after `kimi login`. The adapter surfaced only the first stderr line, a `max_retries_per_step` config deprecation warning, as the reason: `run_query` reports the first line, not the first error line (open). No host stop was needed, so `.proceed`/`.abort` remain offline-tested only. The pre-run INFO estimate used to be the generic 4-consultant default-rate figure ($0.063 for both runs); it now logs the refined per-panel estimate.
+- **Host harness check (2026-10-19).** Static: Codex 0.163 has no custom prompts/commands (skills only, from `~/.codex/skills` and `~/.agents/skills`); the Gemini CLI 0.64 `FileCommandLoader` globs `**/*.toml`, so `.gemini/commands/*.md` never registers (and the CLI is Homebrew-deprecated and no longer serves personal OAuth accounts); agy 1.4.2 reads `<workspace>/.agents/skills/<name>/` and `~/.gemini/config/skills/<name>/` (from its built-in instructions); the Gemini CLI shell tool kills a command after 300 s without output (the 30 s heartbeat covers it). `.codex/commands`/`.gemini/commands` stay as host-specific reference text (`test_install.sh` checks them) but are not slash commands. Live, one headless run each against this branch (temporary `~/.agents/skills` symlink and `~/.claude/commands` copies, restored afterwards): Claude Code ran the command in the foreground with a 600 s Bash timeout (it auto-backgrounds past that) and read `.synthesis_provider` as a file name, hence the clearer wording; Codex's first launch was rejected by Codex itself ("rm -f style commands are not permitted"), hence the `unlink` hint, and its memories led it to disable synthesis; agy followed the contract exactly, ran the command async (`WaitMsBeforeAsync` 10 s) and waits at most 30 min for background tasks in print mode. Claude Code host cost $0.59 (Opus 5.5).
+- **Live host control and harnesses (2026-10-19, second pass).** Every stop path ran live (`.proceed`, USR1, `.abort`, SIGTERM, SIGHUP) with no process left. A real terminal Ctrl-C (SIGINT to the whole group) exposed a bug: under `set -e` the interrupted poll `sleep` ended the run with 130 and orphaned the consultant CLIs (they ignore SIGINT as background jobs); fixed with an async poll pause, a Round 1 poll loop without errexit (an interrupted `date`/`jq` would end the run too), `trap '' INT` in every consultant/escalation/synthesis job (Bash 5.2 in CI did not ignore SIGINT in them, so the adapter died and orphaned its CLI; Bash 3.2 does), host-request checks before collecting (a CLI that Ctrl-C ended is `stopped`) and an EXIT safety net; `test_e2e.sh` Tests 9-10 send SIGINT to the process group. agy 1.4.2 printed a complete synthesis and never exited (its log stops after "Stream goroutine exited", without "Language server shutting down"), so the no-timeout run hung for 16 min: `scripts/lib/agy_exit_guard.sh` (`AGY_EXIT_GRACE_SECONDS`). Hosts: Claude Code proceeds on request; agy finds `~/.gemini/config/skills` and aborts on request; Codex `workspace-write` without approvals gets 0/3 (network), and its auto-reviewer refuses the escalation (code to external providers), so the approval must come from the user; the Gemini CLI is rejected for individual accounts (`UNSUPPORTED_CLIENT`). Failure reasons were then fixed against network-denied reproductions (`sandbox-exec` with `(deny network*)`, nothing billed): `pick_error_line` (shared by `run_query` and `get_consultant_error_reason`) skips warnings and stack frames, `describe_curl_exit` names API network failures, agy inventory failures carry agy's message, and `diagnosed_failures_network_hint` flags an all-network failure (sandbox). The user's `~/.kimi-code/config.toml` `max_retries_per_step` was renamed to `max_attempts_per_step` (same value; `kimi doctor` valid).
+- Release 5.2.0 bumps the version surfaces and adds `docs/releases/v5.2.0.md`; the showcase site syncs after npm serves 5.2.0. Frozen benchmark inputs are unchanged. Residual: a non-improving escalation re-query is still not billed (its file is deleted). `history.json` now stores every full question and is never pruned.
+
 ### v5.1.2 (2026-09-28)
 
 - **Model selection remains transport-specific.** Grok 4.7 replaces the premium/maximum default, Opus 5.5 replaces standard Claude, and Gemini 3.8 High/Low replace the respective CLI targets. Fable and API Pro 3.1 remain separate defaults. Native Gemini 3.8 API thinking accepts low/medium/high and rejects incompatible explicit values before dispatch.