create-merlin-brain 4.2.0 → 5.0.1

package/files/rules/duo-routing.md

@@ -0,0 +1,203 @@
+# Duo Mode — Routing Rules
+
+This document is the single source of truth for duo mode. Do not duplicate routing logic elsewhere — cross-reference this file instead.
+
+## What duo is
+
+Duo mode runs two brains on the same task: Claude and Codex. Tasks that produce independent artifacts (plans, reports, markdown, test files) run in **parallel** — both brains work simultaneously and an arbiter merges outputs. Tasks that write or modify source files run **sequentially** — one author at a time, followed by a Claude reviewer and a structured gate decision. This eliminates file-conflict risk while still getting two perspectives on every code change.
+
+---
+
+## Activation
+
+**State file:** `~/.claude/merlin-state/duo-mode.json`
+
+**Schema:**
+```json
+{"enabled": bool, "sinceISO": "ISO8601 | null", "lastToggleReason": "string | null"}
+```
+
+**Default (first install):**
+```json
+{"enabled": false, "sinceISO": null, "lastToggleReason": null}
+```
+
+**Auto-expire:** If `sinceISO` is more than 24 hours old at read time, treat as disabled. The file is NOT rewritten on read — expiry is a read-time interpretation. Approximately session-sticky.
+
+**Toggle:** `Skill("merlin:duo", args="on|off|status|unsuppress")` or natural language (see `merlin-routing.md` for intent triggers).
+
+**Install gate:** Run `~/.claude/scripts/duo-installed.sh` before any duo activation. If gate returns non-zero:
+- Silently fall back to solo routing for this task
+- Do NOT write `enabled: true` to the state file
+- Do NOT mention duo, Codex, or the gate failure to the user
+- Proceed as if duo was never considered
+
+---
+
+## Precedence
+
+When multiple modes are enabled simultaneously:
+
+1. **Duo active** (enabled=true, within 24h, gate passes) → duo rules in this file win
+2. **Codex-mode active** (enabled=true, within 24h, codex gate passes) → `codex-routing.md` rules apply
+3. **Neither** → solo routing (existing `merlin-routing.md` + `codex-routing.md` rules)
+
+Note: duo does NOT require `codex-mode.json` to be enabled. Duo manages its own state independently.
+
+---
+
+## Badge contract (UNMISSABLE)
+
+Compute the badge via `~/.claude/scripts/duo-badge.sh` before every action prefix.
+
+| Condition | Badge |
+|---|---|
+| Duo enabled + within 24h + gate passes | `⟡🔮↔🔮 MERLIN·DUO ›` |
+| Any other state | `⟡🔮 MERLIN ›` |
+
+**Text-only fallback:** If env `MERLIN_BADGE_TEXTONLY=1`, `duo-badge.sh` returns `[DUO] MERLIN ›` or `MERLIN ›` for terminals that mangle `↔` or emoji.
+
+Every Merlin action MUST prefix with the computed badge. If the badge is missing, the action is non-compliant. See badge audit: `.planning/duo/BADGE-AUDIT.md`.
+
+Special case — `duo off` when codex-mode is still active:
+```
+⟡🔮 MERLIN › Duo off. (codex-mode is still active.)
+```
+
+---
+
+## Routing Matrix — PARALLEL execution
+
+Both brains run independently on the same task. Results are routed to the arbiter for merging or deduplication. **Parallel tasks ONLY produce reports, plans, markdown, or test files — never edits to existing source code.** Source edits are always sequential (see below).
+
+| Task | Brain A | Brain B | Decider |
+|---|---|---|---|
+| Planning (feature-dev / refactor / product-dev) | `merlin-planner` | `codex-planner` | `challenger-arbiter` |
+| Documentation | `docs-keeper` (Claude) | `docs-keeper` via `codex-as.sh` | `challenger-arbiter` |
+| Code review | `code-review` | `codex-code-review` | merge + dedupe (in arbiter) |
+| Testing | `tests-qa` (Claude) | `tests-qa` via `codex-as.sh` | merge + dedupe (in arbiter) |
+
+**UX during parallel runs:**
+```
+⟡🔮↔🔮 MERLIN·DUO › Planning ×2 (claude + codex)…
+⟡🔮↔🔮 MERLIN·DUO › Arbiter merging plans…
+⟡🔮↔🔮 MERLIN·DUO › Plan ready.
+```
+
+---
+
+## Routing Matrix — SEQUENTIAL execution
+
+One author at a time to prevent file conflicts. Sequential only for tasks that write or modify source files.
+
+| Task | Author | Reviewer | Decider |
+|---|---|---|---|
+| Code write (new files) | `codex-implementer` | `code-review` (Claude) | `reviewer-decider` (Claude) |
+| Code modification | `codex-implementer` | `code-review` (Claude) | `reviewer-decider` (Claude) |
+
+**Sequential decision flow:**
+
+1. Author (`codex-implementer`) writes diff
+2. Reviewer (`code-review`, Claude) reviews diff
+3. `reviewer-decider` returns `{decision: approve|revise|reject, reasoning, required_changes?}`
+4. **On `approve`:** proceed to verification
+5. **On `revise`:** author iterates ONCE with `required_changes`. Re-review. If revise again → escalate to reject.
+6. **On `reject`** OR second revise without resolution: Claude reviewer takes over and writes the fix directly
+
+Maximum iterations per task: 2 (one initial pass + one revise loop). `reviewer-decider` enforces `iteration_count` ≤ 2.
+
+**UX during sequential runs:**
+```
+⟡🔮↔🔮 MERLIN·DUO › [1/3] Codex writing diff…
+⟡🔮↔🔮 MERLIN·DUO › [2/3] Claude reviewing…
+⟡🔮↔🔮 MERLIN·DUO › [3/3] Decision: approve · proceeding to verify
+```
+
+If decider returns `revise`:
+```
+⟡🔮↔🔮 MERLIN·DUO › Iteration 2/2: codex revising…
+```
+
+---
+
+## reviewer-decider is Claude-only (P0 safety)
+
+`reviewer-decider` MUST NOT be invoked via `codex-as.sh`. Codex impersonating the gate that checks Codex's own output destroys the sequential safety story. The curated specialists list in `codex-routing.md` explicitly excludes `reviewer-decider` — this exclusion is permanent and must not be removed.
+
+See also: `codex-routing.md` § "Curated specialists exclusion".
+
+---
+
+## Auto-offer for risky tasks
+
+When duo is OFF, Merlin runs a pre-route hook at the start of every routing decision:
+
+1. Call `~/.claude/scripts/duo-pre-route.sh --task "..." [--workflow X] [--files a,b] [--loc N]`
+2. Hook reads `duo-mode.json`, calls `duo-installed.sh`, calls `duo-risk-detect.sh`, checks `duo-suppress.json`
+3. Hook outputs exactly one of:
+   - `mode=duo` → proceed with duo routing (duo was already on)
+   - `mode=offer` → invoke `Skill("merlin:duo", args="offer")` first; user response determines mode
+   - `mode=solo` → fall through to existing solo/codex-mode rules
+
+**Risk threshold:** `duo-risk-detect.sh` scores the task 0–100. `suggest_duo: true` when score ≥ 50. Threshold tunable via env `MERLIN_DUO_OFFER_THRESHOLD`.
+
+**Offer fires only when ALL of the following are true:**
+- `duo-installed.sh` exits 0 (Codex installed)
+- Duo is currently OFF (or auto-expired)
+- Risk score ≥ threshold
+- Not suppressed (no `session_skip`, task hash not in `task_hashes_declined`, intent not in `never_for_intents`)
+
+**Offer is one-shot per task.** Never offer mid-flight. If `duo-pre-route.sh` errors or times out (>500ms), skip the offer silently and log to `duo-decisions.log`.
+
+**Suppression memory:** `~/.claude/merlin-state/duo-suppress.json`. Reset via `Skill("merlin:duo", args="unsuppress")`. `never_for_intents` entries auto-expire after 7 days. `session_skip` clears when file mtime is > 12h old.
+
+---
+
+## Codex-broken-runtime fallback (P0)
+
+`duo-installed.sh` only checks PATH presence. If Codex is on PATH but fails at runtime:
+
+1. Wrap all Codex invocations with a 60s timeout:
+   - With coreutils: `gtimeout 60s codex …`
+   - Without coreutils: `perl -e 'alarm 60; exec @ARGV' codex …`
+2. On Codex error or timeout: log to `~/.claude/merlin-state/duo-decisions.log` with severity `codex_runtime_failure`. Fall back to Claude for that step:
+   - Parallel branch: drop the codex result; arbiter receives one input
+   - Sequential branch: Claude takes the author role
+3. After 3 consecutive Codex failures in a session: surface the following message, write `enabled: false` to `duo-mode.json` with `lastToggleReason: "codex runtime failures"`, and revert to solo:
+
+```
+⟡🔮 MERLIN › Codex appears unhealthy. Reverting to solo for this session. Run 'codex doctor' to diagnose.
+```
+
+---
+
+## Verification authority (UNCHANGED)
+
+Claude ALWAYS runs `merlin_run_verification()` after a duo flow completes, regardless of who wrote the code. This is the brain/hands principle — Codex (or any specialist) may execute, but Claude certifies.
+
+---
+
+## Workflow integration
+
+| Workflow | When duo ON | When duo OFF |
+|---|---|---|
+| `feature-dev` | Parallel planning + sequential coding | Existing codex-mode dual-plan or solo |
+| `refactor` | Parallel planning + sequential coding | Existing codex-mode dual-plan or solo |
+| `product-dev` | Parallel planning + sequential coding | Solo |
+| `bug-fix` | Solo by default; opt-in via "duo this" | Solo |
+| `quick` | Solo by default; opt-in via "duo this" | Solo |
+| Code review intent | Parallel review pair | `code-review` or `codex-code-review` (codex-routing rules) |
+| Tests intent | Parallel test generation pair | Solo |
+| Docs intent | Parallel docs pair | Solo |
+
+---
+
+## Cross-references
+
+- Codex execution layer: `~/.claude/rules/codex-routing.md`
+- Intent triggers (toggle phrases, workflow routing): `~/.claude/rules/merlin-routing.md`
+- Skill prompts: `~/.claude/skills/merlin/duo/` (SKILL.md, on.md, off.md, status.md, offer.md)
+- Reviewer-decider agent: `~/.claude/agents/reviewer-decider.md`
+- Badge audit: `.planning/duo/BADGE-AUDIT.md`
+- State files: `~/.claude/merlin-state/duo-mode.json`, `~/.claude/merlin-state/duo-suppress.json`
+- Decision audit log: `~/.claude/merlin-state/duo-decisions.log` (JSONL, append-only)

package/files/rules/merlin-routing.md

@@ -58,6 +58,10 @@ Call `merlin_smart_route(task="...")` FIRST (searches 500+ community agents). Th
 | "remind me" / "add a todo" | `Skill("merlin:add-todo")` |
 | "check todos" / "pending items" | `Skill("merlin:check-todos")` |
 | New project, no PROJECT.md | `Skill("merlin:map-codebase")` then `Skill("merlin:new-project")` |
+| "duo on" / "enable duo" / "go duo" | `Skill("merlin:duo", args="on")` |
+| "duo off" / "disable duo" / "back to solo" | `Skill("merlin:duo", args="off")` |
+| "duo status" / "am I in duo" / "is duo on" | `Skill("merlin:duo", args="status")` |
+| "stop duo for this kind of task" / "never duo for X" | `Skill("merlin:duo", args="unsuppress")` |
 
 ## Planning Intents
 
@@ -124,3 +128,5 @@ See `~/.claude/rules/codex-routing.md` for full details.
 
 - `feature-dev` and `refactor` workflows: If Codex installed, use dual-plan flow (merlin-planner + codex-planner → challenger-arbiter → codex-implementer execution)
 - `bug-fix` and `quick`: No dual-plan — normal flow, but failed-fix escalation to codex-escalator is available
+
+> When duo mode is active, `feature-dev`, `refactor`, and `product-dev` workflows automatically use parallel planning + sequential coding. See `duo-routing.md`.

package/files/scripts/duo-badge.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# duo-badge.sh — outputs the Merlin badge string to stdout
+# Usage: duo-badge.sh [step-phrase]
+# Env: MERLIN_BADGE_TEXTONLY=1 for ASCII-only output
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+STEP_PHRASE="${1:-}"
+
+# Determine if duo is active: gate passes AND mode is enabled
+DUO_ACTIVE=false
+if "${SCRIPT_DIR}/duo-installed.sh" 2>/dev/null; then
+    if [[ "$("${SCRIPT_DIR}/duo-mode-read.sh" 2>/dev/null)" == "enabled" ]]; then
+        DUO_ACTIVE=true
+    fi
+fi
+
+# Build badge
+if [[ "${MERLIN_BADGE_TEXTONLY:-0}" == "1" ]]; then
+    if [[ "$DUO_ACTIVE" == "true" ]]; then
+        BADGE="[DUO] MERLIN ›"
+    else
+        BADGE="MERLIN ›"
+    fi
+else
+    if [[ "$DUO_ACTIVE" == "true" ]]; then
+        BADGE="⟡🔮↔🔮 MERLIN·DUO ›"
+    else
+        BADGE="⟡🔮 MERLIN ›"
+    fi
+fi
+
+# Append optional step phrase
+if [[ -n "$STEP_PHRASE" ]]; then
+    printf '%s %s\n' "$BADGE" "$STEP_PHRASE"
+else
+    printf '%s\n' "$BADGE"
+fi

package/files/scripts/duo-codex-call.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# duo-codex-call.sh — timeout-wrapped codex invocation with 3-strike fallback
+# Usage: duo-codex-call.sh <codex-command> [args...]
+# Exit 0: success (stdout/stderr forwarded)
+# Exit 75 (TEMPFAIL): codex failed or timed out — caller should fall back to Claude
+# Always exits — never hangs beyond 60s
+
+set -euo pipefail
+
+FAILURES_FILE="${HOME}/.claude/merlin-state/.duo-codex-failures"
+DECISIONS_LOG="${HOME}/.claude/merlin-state/duo-decisions.log"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# --- Counter helpers ---
+_read_counter() {
+    # Reset counter if file is > 6h old (session boundary)
+    if [[ -f "$FAILURES_FILE" ]]; then
+        AGE=$(python3 -c "import os,time; print(int(time.time() - os.path.getmtime('$FAILURES_FILE')))" 2>/dev/null || echo "99999")
+        if [[ "$AGE" -gt 21600 ]]; then
+            rm -f "$FAILURES_FILE"
+            echo 0; return
+        fi
+        cat "$FAILURES_FILE" 2>/dev/null || echo 0
+    else
+        echo 0
+    fi
+}
+
+_write_counter() {
+    echo "$1" > "$FAILURES_FILE"
+}
+
+_log_failure() {
+    local exit_code="$1"
+    local ts
+    ts=$(python3 -c "from datetime import datetime,timezone; print(datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'))" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ")
+    # Mask command to avoid leaking sensitive args (show only first token)
+    local masked_cmd
+    masked_cmd=$(echo "${*:2}" | awk '{print $1}')
+    printf '{"ts":"%s","event":"codex_runtime_failure","exit_code":%d,"command":"%s"}\n' \
+        "$ts" "$exit_code" "$masked_cmd" >> "$DECISIONS_LOG" 2>/dev/null || true
+}
+
+_auto_disable_duo() {
+    "${SCRIPT_DIR}/duo-mode-write.sh" off "codex runtime failures (3 in session)" 2>/dev/null || true
+    echo "⟡🔮 MERLIN › Codex appears unhealthy. Reverting to solo for this session. Run 'codex doctor' to diagnose." >&2
+    _write_counter 0
+}
+
+# --- Build timeout command ---
+_TIMEOUT=""
+if command -v gtimeout >/dev/null 2>&1; then
+    _TIMEOUT="gtimeout 60"
+elif timeout --version >/dev/null 2>&1; then
+    _TIMEOUT="timeout 60"
+fi
+
+# --- Execute (capture exit code without triggering set -e) ---
+EXIT_CODE=0
+if [[ -n "$_TIMEOUT" ]]; then
+    $_TIMEOUT "$@" || EXIT_CODE=$?
+else
+    # perl alarm fallback for macOS without coreutils
+    perl -e 'alarm 60; exec @ARGV or exit 127' -- "$@" || EXIT_CODE=$?
+fi
+
+if [[ $EXIT_CODE -eq 0 ]]; then
+    # Success — reset failure counter
+    _write_counter 0
+    exit 0
+fi
+
+# Failure path
+_log_failure "$EXIT_CODE" "$@"
+
+COUNT=$(( $(_read_counter) + 1 ))
+_write_counter "$COUNT"
+
+if [[ $COUNT -ge 3 ]]; then
+    _auto_disable_duo
+fi
+
+exit 75

package/files/scripts/duo-installed.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# duo-installed.sh — composite install gate for duo mode
+# Returns 0 only if codex-installed.sh (sibling) returns 0
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+"${SCRIPT_DIR}/codex-installed.sh"

package/files/scripts/duo-mode-read.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# duo-mode-read.sh — reads duo-mode.json, applies 24h auto-expire (read-time only, never modifies file)
+# Prints exactly "enabled" or "disabled" to stdout
+
+set -euo pipefail
+
+STATE_FILE="${HOME}/.claude/merlin-state/duo-mode.json"
+
+# If state file missing, default to disabled
+if [[ ! -f "$STATE_FILE" ]]; then
+    echo "disabled"
+    exit 0
+fi
+
+python3 - "$STATE_FILE" <<'PYEOF'
+import sys
+import json
+from datetime import datetime, timezone, timedelta
+
+state_path = sys.argv[1]
+
+try:
+    with open(state_path, "r") as f:
+        data = json.load(f)
+except (json.JSONDecodeError, OSError):
+    print("disabled")
+    sys.exit(0)
+
+enabled = data.get("enabled", False)
+since_iso = data.get("sinceISO")
+
+if not enabled or since_iso is None:
+    print("disabled")
+    sys.exit(0)
+
+# Parse sinceISO and apply 24h auto-expire (read-time interpretation, no file write)
+try:
+    # Handle both Z suffix and +00:00 format
+    since_str = since_iso.replace("Z", "+00:00")
+    since_dt = datetime.fromisoformat(since_str)
+    now_dt = datetime.now(timezone.utc)
+    if (now_dt - since_dt) > timedelta(hours=24):
+        print("disabled")
+        sys.exit(0)
+except (ValueError, TypeError):
+    # Unparseable timestamp — treat as expired
+    print("disabled")
+    sys.exit(0)
+
+print("enabled")
+PYEOF

package/files/scripts/duo-mode-write.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# duo-mode-write.sh — atomic write to duo-mode.json
+# Usage: duo-mode-write.sh on "<reason>" | off "<reason>"
+
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+    echo "Usage: duo-mode-write.sh on|off \"<reason>\"" >&2
+    exit 1
+fi
+
+ACTION="$1"
+REASON="$2"
+STATE_FILE="${HOME}/.claude/merlin-state/duo-mode.json"
+STATE_DIR="$(dirname "$STATE_FILE")"
+
+# Ensure state directory exists
+mkdir -p "$STATE_DIR"
+
+case "$ACTION" in
+    on)
+        ENABLED="true"
+        ;;
+    off)
+        ENABLED="false"
+        ;;
+    *)
+        echo "Error: first argument must be 'on' or 'off', got: $ACTION" >&2
+        exit 1
+        ;;
+esac
+
+# Use python3 for JSON serialization and atomic write via mktemp + mv (same FS = atomic)
+python3 - "$STATE_FILE" "$ENABLED" "$REASON" <<'PYEOF'
+import sys
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+
+state_path = sys.argv[1]
+enabled = sys.argv[2] == "true"
+reason = sys.argv[3]
+
+now_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") if enabled else None
+
+data = {
+    "enabled": enabled,
+    "sinceISO": now_iso,
+    "lastToggleReason": reason,
+}
+
+state_dir = os.path.dirname(state_path)
+fd, tmp_path = tempfile.mkstemp(dir=state_dir, suffix=".tmp")
+try:
+    with os.fdopen(fd, "w") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+    os.replace(tmp_path, state_path)
+except Exception:
+    try:
+        os.unlink(tmp_path)
+    except OSError:
+        pass
+    raise
+PYEOF

package/files/scripts/duo-pre-route.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# duo-pre-route.sh — pre-routing hook for workflow dispatch
+# Usage: duo-pre-route.sh --task "<text>" [--workflow <name>] [--files <comma-list>] [--loc <int>]
+# Outputs one of: mode=duo | mode=offer | mode=solo
+# Always exits 0 — never blocks routing
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+TASK=""
+WORKFLOW=""
+FILES=""
+LOC=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --task)     TASK="${2:-}";     shift 2 ;;
+        --workflow) WORKFLOW="${2:-}"; shift 2 ;;
+        --files)    FILES="${2:-}";    shift 2 ;;
+        --loc)      LOC="${2:-}";      shift 2 ;;
+        *)          shift ;;
+    esac
+done
+
+# Branch 1: duo explicitly enabled by user (and not expired)
+DUO_STATE=$("${SCRIPT_DIR}/duo-mode-read.sh" 2>/dev/null || echo "disabled")
+if [[ "$DUO_STATE" == "enabled" ]]; then
+    echo "mode=duo"
+    exit 0
+fi
+
+# Branch 2: Codex absent — stay solo silently (never mention duo)
+if ! "${SCRIPT_DIR}/duo-installed.sh" 2>/dev/null; then
+    echo "mode=solo"
+    exit 0
+fi
+
+# Branch 3: risk-detect suggestion
+RISK_DETECT="${SCRIPT_DIR}/duo-risk-detect.sh"
+if [[ ! -x "$RISK_DETECT" ]]; then
+    echo "mode=solo"
+    exit 0
+fi
+
+# Run risk detector — it handles its own 500ms timeout internally
+RISK_JSON=$("$RISK_DETECT" --task "$TASK" --workflow "$WORKFLOW" --files "$FILES" --loc "$LOC" 2>/dev/null \
+    || echo '{"score":0,"reasons":[],"suggest_duo":false}')
+
+# Parse suggest_duo from JSON (python3, no jq dep)
+SUGGEST_DUO=$(python3 -c "
+import json, sys
+try:
+    d = json.loads(sys.argv[1])
+    print('true' if d.get('suggest_duo', False) else 'false')
+except Exception:
+    print('false')
+" "$RISK_JSON" 2>/dev/null || echo "false")
+
+if [[ "$SUGGEST_DUO" != "true" ]]; then
+    echo "mode=solo"
+    exit 0
+fi
+
+# Branch 3a: suppression check — use a temp python script to avoid heredoc-in-subshell issues
+REASONS_JSON=$(python3 -c "
+import json, sys
+try:
+    d = json.loads(sys.argv[1])
+    print(json.dumps(d.get('reasons', [])))
+except Exception:
+    print('[]')
+" "$RISK_JSON" 2>/dev/null || echo "[]")
+
+SUPPRESS_SCRIPT=$(mktemp /tmp/duo-suppress-check.XXXXXX.py)
+trap 'rm -f "$SUPPRESS_SCRIPT"' EXIT
+
+cat > "$SUPPRESS_SCRIPT" << 'PYEOF'
+import sys, json, os, time, hashlib, re
+
+task      = os.environ.get("_DUO_TASK", "")
+workflow  = os.environ.get("_DUO_WORKFLOW", "")
+reasons   = json.loads(os.environ.get("_DUO_REASONS", "[]"))
+
+path = os.path.expanduser("~/.claude/merlin-state/duo-suppress.json")
+try:
+    d = json.load(open(path))
+except Exception:
+    d = {}
+
+# session_skip: check file mtime < 12h
+mtime = os.path.getmtime(path) if os.path.exists(path) else 0
+if d.get("session_skip") and (time.time() - mtime) < 43200:
+    print("true"); sys.exit(0)
+
+# task_hash check
+normalized = re.sub(r'[\s\'"`]+', ' ', task.lower()).strip()[:120]
+task_hash  = hashlib.sha1(f"{workflow}:{normalized}".encode()).hexdigest()
+if task_hash in d.get("task_hashes_declined", []):
+    print("true"); sys.exit(0)
+
+# intent fingerprint check (7d expiry)
+top3 = sorted(reasons[:3])
+intent_fp = hashlib.sha1(f"{workflow}:{':'.join(top3)}".encode()).hexdigest()
+now = time.time()
+for entry in d.get("never_for_intents", []):
+    if isinstance(entry, dict):
+        if entry.get("fp") == intent_fp and (now - entry.get("ts", 0)) < 604800:
+            print("true"); sys.exit(0)
+
+print("false")
+PYEOF
+
+IS_SUPPRESSED=$(export _DUO_TASK="$TASK" _DUO_WORKFLOW="$WORKFLOW" _DUO_REASONS="$REASONS_JSON"; \
+    python3 "$SUPPRESS_SCRIPT" 2>/dev/null || echo "false")
+
+if [[ "$IS_SUPPRESSED" == "true" ]]; then
+    echo "mode=solo"
+    exit 0
+fi
+
+# Risk fires, not suppressed — ask user
+echo "mode=offer"
+exit 0