ai-consultants 3.2.0 → 3.4.0

package/package.json

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

@@ -239,7 +239,7 @@ 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
+CODEX_MODEL=gpt-5.6-sol
 CLAUDE_MODEL=claude-opus-5
 CLAUDE_API_MAX_TOKENS=16384  # API only: adaptive thinking + visible output
 MISTRAL_MODEL=mistral-large-3
@@ -263,10 +263,15 @@ 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

@@ -144,8 +144,8 @@ export GEMINI_USE_API
 # CODEX CONFIGURATION - The Pragmatist
 # =============================================================================
 
-# Model: "gpt-5.5" (default), "gpt-5.4", "gpt-5.4-nano", "gpt-5.3-codex", etc.
-CODEX_MODEL="${CODEX_MODEL:-gpt-5.5}"
+# Model: "gpt-5.6-sol" (default), "gpt-5.6-terra", "gpt-5.6-luna", etc.
+CODEX_MODEL="${CODEX_MODEL:-gpt-5.6-sol}"
 CODEX_TIMEOUT_SECONDS="${CODEX_TIMEOUT:-180}"
 CODEX_CMD="${CODEX_CMD:-codex}"
 
@@ -584,7 +584,7 @@ get_model_for_tier() {
             case "$consultant" in
                 claude)   echo "claude-opus-5" ;;
                 gemini)   echo "Gemini 3.1 Pro (High)" ;;
-                codex)    echo "gpt-5.5" ;;
+                codex)    echo "gpt-5.6-sol" ;;
                 mistral)  echo "mistral-large-3" ;;
                 cursor)   echo "composer-2.5" ;;
                 deepseek) echo "deepseek-v4-pro" ;;
@@ -598,9 +598,9 @@ get_model_for_tier() {
             ;;
         standard|medium|balanced)
             case "$consultant" in
-                claude)   echo "claude-sonnet-4-6" ;;
-                gemini)   echo "Gemini 3.5 Flash (High)" ;;
-                codex)    echo "gpt-5.4" ;;
+                claude)   echo "claude-sonnet-5" ;;
+                gemini)   echo "Gemini 3.6 Flash (High)" ;;
+                codex)    echo "gpt-5.6-terra" ;;
                 mistral)  echo "mistral-medium-latest" ;;
                 cursor)   echo "composer-2" ;;
                 deepseek) echo "deepseek-v4-flash" ;;
@@ -615,8 +615,8 @@ get_model_for_tier() {
         economy|fast|quick)
             case "$consultant" in
                 claude)   echo "claude-haiku-4-5" ;;
-                gemini)   echo "Gemini 3.5 Flash (Low)" ;;
-                codex)    echo "gpt-5.4-nano" ;;
+                gemini)   echo "Gemini 3.6 Flash (Low)" ;;
+                codex)    echo "gpt-5.6-luna" ;;
                 mistral)  echo "devstral-small-2" ;;
                 cursor)   echo "gemini-3-flash" ;;
                 deepseek) echo "deepseek-v4-flash" ;;
@@ -779,4 +779,4 @@ EOF
 # VERSION
 # =============================================================================
 
-AI_CONSULTANTS_VERSION="3.2.0"
+AI_CONSULTANTS_VERSION="3.4.0"

package/scripts/configure.sh

@@ -285,6 +285,15 @@ if [[ "$(read_value "$WORK_FILE" CLAUDE_MODEL 2>/dev/null || true)" == "claude-o
     echo "Migrated managed Claude default: claude-opus-4-8 -> claude-opus-5" >&2
 fi
 
+# Same shape for Codex: `init` once wrote gpt-5.5 as an unmarked value, so
+# configure treated it as a deliberate pin and never reached gpt-5.6-sol. A
+# real pin is preserved by `--set CODEX_MODEL=gpt-5.5`.
+if [[ "$(read_value "$WORK_FILE" CODEX_MODEL 2>/dev/null || true)" == "gpt-5.5" ]] \
+    && ! has_value_marker "$WORK_FILE" CODEX_MODEL "$PIN_MARKER"; then
+    set_value CODEX_MODEL "gpt-5.6-sol $DEFAULT_MARKER"
+    echo "Migrated managed Codex default: gpt-5.5 -> gpt-5.6-sol" >&2
+fi
+
 configure_cli_only() {
     local enable_key="$1" cmd_key="$2" cmd enabled=false
     cmd=$(effective_input_value "$cmd_key")

package/scripts/doctor.sh

@@ -242,9 +242,15 @@ check_cli_consultant() {
         return 0
     fi
 
-    # Get version (--version is standard and fast, no timeout needed)
+    # Get version (--version is standard and fast, no timeout needed).
+    # Gemini/agy must run under agy_env so an SSH session still reaches the
+    # Keychain credential store (see agy_env in lib/common.sh).
     local version
-    version=$("$cmd" --version 2>/dev/null | head -1 || echo "")
+    if [[ "$name" == "Gemini" ]]; then
+        version=$(agy_env "$cmd" --version 2>/dev/null | head -1 || echo "")
+    else
+        version=$("$cmd" --version 2>/dev/null | head -1 || echo "")
+    fi
 
     if [[ -n "$version" ]]; then
         _print "  ✓ $name: $version"

package/scripts/lib/api.sh

@@ -188,7 +188,7 @@ build_qwen_request() {
 #   'reasoning_effort' must be one of: 'none', 'minimal', 'low', 'medium',
 #   'high', 'xhigh', 'max'
 # Note this is WIDER than the low|high|xhigh that the public write-ups for
-# qwen3.8-max-preview all reported — 'minimal', 'medium' and 'max' are accepted
+# qwen3.8-max all reported — 'minimal', 'medium' and 'max' are accepted
 # by the model too. Taken from the API rather than from documentation for
 # exactly that reason.
 #
@@ -196,7 +196,7 @@ build_qwen_request() {
 # facts in shell is what produced the stale-model bugs this release also fixes,
 # and the same builder serves GLM/Grok/DeepSeek/MiniMax. An unsupported
 # combination is rejected by the provider with a 400 that run_api_query
-# surfaces without retrying — e.g. 'none' on qwen3.8-max-preview returns "The
+# surfaces without retrying — e.g. 'none' on qwen3.8-max returns "The
 # value of the enable_thinking parameter is restricted to True", which is a
 # model fact, not a syntax error.
 validate_reasoning_effort() {
@@ -248,7 +248,7 @@ build_openai_request() {
 # Usage: build_anthropic_request <prompt> <model> [max_tokens]
 build_anthropic_request() {
     local prompt="$1"
-    local model="${2:-claude-sonnet-4-6}"
+    local model="${2:-claude-sonnet-5}"
     local max_tokens="${3:-16384}"
 
     jq -n \

package/scripts/lib/common.sh

@@ -140,6 +140,29 @@ check_command() {
     return 0
 }
 
+# Run a command with SSH session markers stripped from the environment.
+#
+# WHY (do not "simplify" this away): the Antigravity CLI (`agy`, our Gemini
+# transport) picks its credential store from the environment. When it sees any
+# of SSH_CLIENT, SSH_CONNECTION, or SSH_TTY it switches to a file-based token
+# store and never consults the macOS Keychain. A user who signed in locally has
+# credentials only in the Keychain, so every `agy` call from an SSH session
+# fails auth — and re-signing-in does not help, because the new login also lands
+# in the Keychain the CLI has already decided to ignore. Clearing the three
+# markers for the `agy` process restores Keychain lookup. On a local (non-SSH)
+# session they are already unset, so this is a pure no-op there. It grants no
+# extra tools or filesystem access; it only changes which credential store the
+# CLI consults.
+#
+# AGY_ENV_PREFIX is the exec-safe form (external `env` binary) for use under
+# run_with_timeout / GNU timeout, which cannot invoke shell functions. agy_env
+# is the same-shell convenience wrapper. Keep both in lockstep via this array.
+#
+# Usage (same shell):  agy_env <command> [args...]
+# Usage (under timeout / command arrays):  "${AGY_ENV_PREFIX[@]}" <command> [args...]
+AGY_ENV_PREFIX=(env -u SSH_CLIENT -u SSH_CONNECTION -u SSH_TTY)
+agy_env() { "${AGY_ENV_PREFIX[@]}" "$@"; }
+
 # =============================================================================
 # MAIN QUERY EXECUTION FUNCTION
 # =============================================================================
@@ -149,8 +172,9 @@ check_command() {
 # Usage: run_query <consultant_name> <output_file> <timeout_sec> <command...>
 #
 # The query is passed via stdin to the command.
+# Use the exec-safe array form under run_query (agy_env is same-shell only).
 # Example:
-#   echo "$QUERY" | run_query "Gemini" "/tmp/out.json" 120 agy -p - --model "Gemini 3.1 Pro (High)"
+#   echo "$QUERY" | run_query "Gemini" "/tmp/out.json" 120 "${AGY_ENV_PREFIX[@]}" agy -p "..." --model "Gemini 3.1 Pro (High)"
 #
 run_query() {
     local consultant_name="$1"
@@ -485,7 +509,7 @@ warn_effort_ignored_in_cli() {
     if is_api_mode "$agent"; then
         return 0
     fi
-    log_warn "[$agent] $var is ignored in CLI mode - no consultant CLI exposes a reasoning-effort flag. Set it in the CLI's own configuration, or switch this consultant to API mode."
+    log_warn "[$agent] $var is ignored in CLI mode - this consultant's CLI does not expose a reasoning-effort flag. Set it in the CLI's own configuration, or switch this consultant to API mode."
 }
 
 # Log API mode status for debugging
@@ -1311,7 +1335,8 @@ build_synthesis_args() {
             # stdin and "-" is not a stdin sentinel. A prior `-p -` made agy answer
             # a literal "-" with a generic greeting -> unparseable synthesis ->
             # manual_review. Pass the prompt directly, mirroring query_gemini.sh.
-            SYNTHESIS_ARGS=("${GEMINI_CMD:-agy}" "-p" "$prompt")
+            # AGY_ENV_PREFIX is exec-safe under timeout (see agy_env above).
+            SYNTHESIS_ARGS=("${AGY_ENV_PREFIX[@]}" "${GEMINI_CMD:-agy}" "-p" "$prompt")
             local model="${SYNTHESIS_MODEL:-${GEMINI_MODEL:-}}"
             [[ -n "$model" ]] && SYNTHESIS_ARGS+=("--model" "$model")
             ;;

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

@@ -9,6 +9,7 @@
 #   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
+#   CLAUDE_REASONING_EFFORT - Optional CLI/API reasoning effort
 #   ENABLE_PERSONA - Enable "The Synthesizer" persona (default: true)
 
 set -euo pipefail
@@ -64,21 +65,41 @@ if is_api_mode "claude"; then
     else
         exit_code=$?
     fi
-warn_effort_ignored_in_cli "Claude"
 else
     # --- CLI Mode ---
     log_api_mode_status "claude"
     check_command "$CLAUDE_CMD" "Claude CLI" "Visit https://docs.anthropic.com/en/docs/claude-code" || exit 1
 
-    # 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" --output-format json
+    # Optional CLI effort control. Unset leaves the CLI's own default alone;
+    # when set, pass --effort through after the shared validation gate. Do not
+    # invent a local allowlist — the provider rejects what it does not accept.
+    CLAUDE_ARGS=("$CLAUDE_CMD" --print --model "$MODEL_USED" --output-format json)
+    effort_ok=true
+    if [[ -n "${CLAUDE_REASONING_EFFORT:-}" ]]; then
+        source "$SCRIPT_DIR/lib/api.sh"
+        if ! cli_effort=$(validate_reasoning_effort "$CLAUDE_REASONING_EFFORT" "$CONSULTANT_NAME"); then
+            effort_ok=false
+            exit_code=1
+        else
+            CLAUDE_ARGS+=(--effort "$cli_effort")
+        fi
+    fi
 
-    exit_code=$?
+    if [[ "$effort_ok" == "true" ]]; then
+        # JSON output exposes provider-measured usage and cost. In particular,
+        # output_tokens includes adaptive thinking that is absent from .result.
+        # Keep failures inside an explicit conditional so `set -e` cannot skip
+        # exit_code assignment (same guard as the API branch).
+        if echo "$FULL_QUERY" | run_query \
+                "Claude" \
+                "$TEMP_OUTPUT" \
+                "$CLAUDE_TIMEOUT_SECONDS" \
+                "${CLAUDE_ARGS[@]}"; then
+            exit_code=0
+        else
+            exit_code=$?
+        fi
+    fi
 fi
 
 # --- Calculate latency ---

package/scripts/query_codex.sh

@@ -1,13 +1,14 @@
 #!/bin/bash
-# query_codex.sh - Query OpenAI Codex CLI or API (v2.6 with API mode support)
+# query_codex.sh - Query OpenAI Codex CLI or API (isolated CLI runtime)
 #
 # Usage: ./query_codex.sh "question" [context_file] [output_file]
 #
 # Environment variables:
-#   CODEX_MODEL - Model to use (default: gpt-5.3-codex)
+#   CODEX_MODEL - Model to use (default: gpt-5.6-sol)
 #   CODEX_TIMEOUT - Timeout in seconds (default: 180)
 #   CODEX_USE_API - Use API mode instead of CLI (default: false)
 #   OPENAI_API_KEY - API key for API mode
+#   CODEX_REASONING_EFFORT - Optional CLI/API reasoning effort
 #   ENABLE_PERSONA - Enable "The Pragmatist" persona (default: true)
 
 set -euo pipefail
@@ -39,6 +40,22 @@ START_TIME=$(get_timestamp_ms)
 
 # --- Execution (CLI or API mode) ---
 TEMP_OUTPUT=$(mktemp)
+CODEX_RUNTIME_DIR=""
+exit_code=1
+
+cleanup() {
+    rm -f "$TEMP_OUTPUT" "${TEMP_OUTPUT}.err"
+
+    # CODEX_RUNTIME_DIR is always created by this script under the system temp
+    # directory. Validate the prefix before recursive cleanup so an unexpected
+    # empty or overridden value can never widen the deletion target.
+    local temp_prefix="${TMPDIR:-/tmp}"
+    temp_prefix="${temp_prefix%/}/ai-consultants-codex."
+    if [[ -n "$CODEX_RUNTIME_DIR" && "$CODEX_RUNTIME_DIR" == "$temp_prefix"* ]]; then
+        rm -rf -- "$CODEX_RUNTIME_DIR"
+    fi
+}
+trap cleanup EXIT
 
 if is_api_mode "codex"; then
     # --- API Mode ---
@@ -61,26 +78,104 @@ if is_api_mode "codex"; then
     else
         exit_code=$?
     fi
-warn_effort_ignored_in_cli "Codex"
 else
-    # --- CLI Mode ---
+    # --- CLI Mode (isolated HOME/CWD; auth via real CODEX_HOME) ---
     log_api_mode_status "codex"
     check_command "$CODEX_CMD" "Codex CLI" "npm install -g @openai/codex" || exit 1
 
-    # Build command
-    CMD_ARGS=("$CODEX_CMD" "exec" "--skip-git-repo-check")
-    if [[ -n "$CODEX_MODEL" ]]; then
-        CMD_ARGS+=("-m" "$CODEX_MODEL")
+    # Resolve the real Codex home BEFORE overriding HOME. --ignore-user-config
+    # skips config.toml but auth still resolves through CODEX_HOME; repointing
+    # it at the isolated home would break authentication.
+    real_codex_home="${CODEX_HOME:-${HOME}/.codex}"
+
+    runtime_base="${TMPDIR:-/tmp}"
+    runtime_base="${runtime_base%/}"
+    CODEX_RUNTIME_DIR=$(mktemp -d "$runtime_base/ai-consultants-codex.XXXXXX")
+    chmod 700 "$CODEX_RUNTIME_DIR"
+
+    isolated_home="$CODEX_RUNTIME_DIR/home"
+    isolated_cwd="$CODEX_RUNTIME_DIR/workspace"
+    prompt_file="$CODEX_RUNTIME_DIR/prompt.txt"
+    payload_file="$CODEX_RUNTIME_DIR/payload.txt"
+    mkdir -p "$isolated_home" "$isolated_cwd"
+    chmod 700 "$isolated_home" "$isolated_cwd"
+    printf '%s' "$FULL_QUERY" > "$prompt_file"
+    : > "$payload_file"
+    chmod 600 "$prompt_file" "$payload_file"
+
+    cli_effort=""
+    effort_ok=true
+    if [[ -n "${CODEX_REASONING_EFFORT:-}" ]]; then
+        # Keep the existing validate_reasoning_effort gate; pass the value
+        # through and let the CLI reject what it does not accept.
+        source "$SCRIPT_DIR/lib/api.sh"
+        if ! cli_effort=$(validate_reasoning_effort "$CODEX_REASONING_EFFORT" "$CONSULTANT_NAME"); then
+            effort_ok=false
+            exit_code=1
+        fi
     fi
 
-    # Codex uses query as the last argument, not from stdin
-    run_query \
-        "Codex" \
-        "$TEMP_OUTPUT" \
-        "$CODEX_TIMEOUT_SECONDS" \
-        "${CMD_ARGS[@]}" "$FULL_QUERY" < /dev/null
-
-    exit_code=$?
+    if [[ "$effort_ok" == "true" ]]; then
+        # Isolated Codex headless contract (verified against codex-cli 0.146.0):
+        #   HOME is ephemeral so ambient ~/.codex config, hooks, MCP, and
+        #   project instructions stay outside the consultation.
+        #   CODEX_HOME stays on the real auth store.
+        #   --ignore-user-config is safe here only because we pin the model with
+        #   -m. It also makes Codex ignore any -p <profile>, which is why we
+        #   must not add -p.
+        #   -s read-only: the consultant answers; it never edits.
+        #   -C points at an empty temp dir so the host repo's AGENTS.md stays out
+        #   (build_context.sh already inlined the relevant files into FULL_QUERY).
+        #   trailing - reads the prompt from stdin (no ARG_MAX / process-list).
+        #   -o writes the final agent message to a private payload file.
+        CMD_ARGS=(
+            env
+            HOME="$isolated_home"
+            CODEX_HOME="$real_codex_home"
+            "$CODEX_CMD"
+            exec
+            --ephemeral
+            --ignore-user-config
+            --ignore-rules
+            --skip-git-repo-check
+            -m "$CODEX_MODEL"
+            -s read-only
+            -C "$isolated_cwd"
+            -o "$payload_file"
+        )
+
+        if [[ -n "$cli_effort" ]]; then
+            CMD_ARGS+=("-c" "model_reasoning_effort=${cli_effort}")
+        fi
+
+        CMD_ARGS+=("-")
+
+        # run_query buffers stdin once and replays it on each retry.
+        if run_query \
+                "Codex" \
+                "$TEMP_OUTPUT" \
+                "$CODEX_TIMEOUT_SECONDS" \
+                "${CMD_ARGS[@]}" < "$prompt_file"; then
+            exit_code=0
+        else
+            exit_code=$?
+        fi
+
+        # Prefer the -o payload over stdout only when the run succeeded.
+        # A non-empty payload must never rewrite a timeout, auth error, or
+        # exhausted-retry into success — a partial answer would enter synthesis
+        # as a healthy consultation. Exit 0 with an empty payload remains a
+        # diagnosed failure.
+        if [[ $exit_code -eq 0 ]]; then
+            if [[ -s "$payload_file" ]]; then
+                cp "$payload_file" "$TEMP_OUTPUT"
+            else
+                exit_code=1
+                log_warn "[$CONSULTANT_NAME] Codex wrote an empty last-message payload"
+                printf 'Codex wrote an empty last-message payload\n' > "${TEMP_OUTPUT}.err"
+            fi
+        fi
+    fi
 fi
 
 # --- Calculate latency ---
@@ -88,12 +183,15 @@ END_TIME=$(get_timestamp_ms)
 LATENCY_MS=$((END_TIME - START_TIME))
 
 # --- Configuration for response building ---
-MODEL_USED="${CODEX_MODEL:-gpt-5.5}"
+MODEL_USED="${CODEX_MODEL:-gpt-5.6-sol}"
 PERSONA_NAME=$(get_persona_name "$CONSULTANT_NAME")
 
 # --- Post-processing: use shared helper ---
+# process_consultant_response returns the consultant exit code. Guard the call
+# so a non-zero return does not abort under set -e before we cat the output
+# file and exit with that code.
 process_consultant_response "$CONSULTANT_NAME" "$MODEL_USED" "$PERSONA_NAME" \
-    "$TEMP_OUTPUT" "$OUTPUT_FILE" "$exit_code" "$LATENCY_MS" "" "$FULL_QUERY"
+    "$TEMP_OUTPUT" "$OUTPUT_FILE" "$exit_code" "$LATENCY_MS" "" "$FULL_QUERY" || true
 
 cat "$OUTPUT_FILE"
 exit $exit_code

package/scripts/query_gemini.sh

@@ -13,6 +13,7 @@
 #   GEMINI_USE_API - Use Google AI API mode instead of the agy CLI (default: false)
 #   GEMINI_API_MODEL - API model ID for API mode (default: gemini-3.1-pro-preview)
 #   GEMINI_API_KEY - API key for API mode
+#   GEMINI_REASONING_EFFORT - Optional CLI reasoning effort
 #   ENABLE_PERSONA - Enable "The Architect" persona (default: true)
 
 set -euo pipefail
@@ -68,7 +69,6 @@ if is_api_mode "gemini"; then
     else
         exit_code=$?
     fi
-warn_effort_ignored_in_cli "Gemini"
 else
     # --- CLI Mode (Antigravity CLI: agy) ---
     log_api_mode_status "gemini"
@@ -85,13 +85,38 @@ else
     # -p argument. agy has --model (no -m alias) and no read-from-file flag, so a
     # very large FULL_QUERY goes through argv (ARG_MAX-bounded; fine for normal
     # contexts). stdin is /dev/null (agy ignores it; run_query's cat needs an EOF).
-    run_query \
-        "Gemini" \
-        "$TEMP_OUTPUT" \
-        "$GEMINI_TIMEOUT_SECONDS" \
-        "$GEMINI_CMD" -p "$FULL_QUERY" --model "$GEMINI_MODEL" </dev/null
+    # Strip SSH_* markers so agy consults the macOS Keychain (see agy_env /
+    # AGY_ENV_PREFIX in lib/common.sh). Use the exec-safe prefix array — not the
+    # agy_env function — because run_query dispatches through GNU timeout.
+    #
+    # Optional CLI effort: when GEMINI_REASONING_EFFORT is set, pass --effort.
+    # agy accepts only a subset (e.g. low|medium|high); unsupported values fail
+    # at the provider and surface as diagnosed errors — no local allowlist.
+    GEMINI_ARGS=("${AGY_ENV_PREFIX[@]}" "$GEMINI_CMD" -p "$FULL_QUERY" --model "$GEMINI_MODEL")
+    effort_ok=true
+    if [[ -n "${GEMINI_REASONING_EFFORT:-}" ]]; then
+        source "$SCRIPT_DIR/lib/api.sh"
+        if ! cli_effort=$(validate_reasoning_effort "$GEMINI_REASONING_EFFORT" "$CONSULTANT_NAME"); then
+            effort_ok=false
+            exit_code=1
+        else
+            GEMINI_ARGS+=(--effort "$cli_effort")
+        fi
+    fi
 
-    exit_code=$?
+    if [[ "$effort_ok" == "true" ]]; then
+        # Keep failures inside an explicit conditional so `set -e` cannot skip
+        # exit_code assignment (same guard as the API branch).
+        if run_query \
+                "Gemini" \
+                "$TEMP_OUTPUT" \
+                "$GEMINI_TIMEOUT_SECONDS" \
+                "${GEMINI_ARGS[@]}" </dev/null; then
+            exit_code=0
+        else
+            exit_code=$?
+        fi
+    fi
 fi
 
 # --- Calculate latency ---