cc-safe-setup 29.7.0 → 30.0.4

package/examples/exploration-budget-guard.sh

@@ -0,0 +1,89 @@
+#!/bin/bash
+# exploration-budget-guard.sh — Stop excessive exploration from draining tokens
+#
+# Solves: #51054 — Claude wastes 20% of weekly allowance exploring files
+#         on a simple task instead of acting. Read/Glob/Grep loops with
+#         no Edit/Write progress.
+#
+# Tracks read-only tool calls (Read, Glob, Grep) per session. After 25
+# consecutive reads without a write, warns. After 40, blocks.
+# Resets when an Edit/Write/Bash(write) occurs.
+#
+# TRIGGER: PreToolUse  MATCHER: "Read|Glob|Grep|Edit|Write"
+
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-exploration-budget-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [exploration-budget-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+STATE_DIR="/tmp/.cc-exploration-budget"
+mkdir -p "$STATE_DIR"
+
+# Session-scoped state file (keyed by parent PID)
+STATE_FILE="$STATE_DIR/session-$$"
+# Fall back to a shared file if $$ changes between hook calls
+STATE_FILE="$STATE_DIR/exploration-count"
+
+NOW=$(date +%s)
+
+case "$TOOL" in
+  Edit|Write)
+    # Write operation = progress. Reset exploration counter.
+    echo "0 $NOW" > "$STATE_FILE"
+    exit 0
+    ;;
+  Read|Glob|Grep)
+    # Read operation = exploration. Increment counter.
+    ;;
+  *)
+    exit 0
+    ;;
+esac
+
+# Read current count
+COUNT=0
+LAST_TIME=0
+if [ -f "$STATE_FILE" ]; then
+    read -r COUNT LAST_TIME < "$STATE_FILE" 2>/dev/null || true
+    # Reset if more than 10 minutes since last call (new task)
+    ELAPSED=$(( NOW - LAST_TIME ))
+    if [ "$ELAPSED" -gt 600 ]; then
+        COUNT=0
+    fi
+fi
+
+COUNT=$(( COUNT + 1 ))
+echo "$COUNT $NOW" > "$STATE_FILE"
+
+WARN_THRESHOLD=25
+BLOCK_THRESHOLD=40
+
+if [ "$COUNT" -ge "$BLOCK_THRESHOLD" ]; then
+    echo "BLOCKED: $COUNT consecutive read operations without writing anything." >&2
+    echo "  You're stuck in an exploration loop — this wastes tokens." >&2
+    echo "  Take action NOW:" >&2
+    echo "  1. Write your solution based on what you've already read" >&2
+    echo "  2. If unsure, make a small change and test it" >&2
+    echo "  3. Ask the user for clarification instead of reading more files" >&2
+    echo "" >&2
+    echo "  Exploration budget: $COUNT/$BLOCK_THRESHOLD (EXCEEDED)" >&2
+    exit 2
+fi
+
+if [ "$COUNT" -ge "$WARN_THRESHOLD" ]; then
+    echo "WARNING: $COUNT consecutive reads without any write." >&2
+    echo "  You may be over-exploring. Consider acting on what you know." >&2
+    echo "  Budget: $COUNT/$BLOCK_THRESHOLD reads before block." >&2
+fi
+
+exit 0

package/examples/expo-eject-guard.sh

@@ -1,5 +1,18 @@
+#!/bin/bash
 #
 # TRIGGER: PreToolUse  MATCHER: "Bash"
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-expo-eject-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [expo-eject-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [[ -z "$COMMAND" ]] && exit 0

package/examples/extended-thinking-loop-guard.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+# extended-thinking-loop-guard.sh — Hard-block a Cluster 13A resume when the
+#   session is running under an autonomous-loop / headless-resume harness.
+#
+# Solves: the LMS927369 amplification reported in #63147 on 2026-05-29. The
+#   well-known 13A wedge (transcript persists thinking blocks with
+#   `thinking: ""` + retained `signature`, then resume re-sends them and the
+#   API returns 400) is normally a one-time failure under interactive use.
+#   Under `/loop`-style autonomous resume, the failure is instead an
+#   *unrecoverable infinite loop*: the loop queues another continuation,
+#   the latest assistant message is unchanged on disk, the next request
+#   hits the same 400, and the loop never bails because the wedged turn
+#   never gets past the API.
+#
+# Why a second hook (in addition to PR #445's advisory): the existing
+#   extended-thinking-resume-warning.sh always exits 0 — it surfaces the
+#   precursor to the operator's terminal but does not block the session
+#   start. Under `/loop`, nobody is watching stderr in the moment, so a
+#   non-blocking advisory does not break the loop. This hook is the
+#   opt-in BLOCKING complement: when the operator declares "I am running
+#   under an autonomous resume harness" via CC_LOOP_GUARD_ENABLED=1, the
+#   hook scans the transcript on the disk and exits 2 with a decision
+#   block if the 13A precursor is present. The blocking exit propagates
+#   into the loop layer and breaks the retry cycle.
+#
+# Issue addressed: #63147 (central case), amplification reported by
+#   LMS927369 (https://github.com/anthropics/claude-code/issues/63147#issuecomment-4571317923).
+#   Field guide: https://gist.github.com/yurukusa/8c6be069f602399238356a9c9b719a45
+#
+# Default behavior: SILENT NO-OP. The hook exits 0 immediately unless
+#   CC_LOOP_GUARD_ENABLED=1 is explicitly set. This makes it safe to drop
+#   into a settings.json template that gets applied broadly — interactive
+#   operators who do not set the env var see no change in behavior. Only
+#   harnesses that opt in get the blocking semantics.
+#
+# Environment variables:
+#   CC_LOOP_GUARD_ENABLED=1                — REQUIRED to arm the guard
+#   CC_LOOP_GUARD_DISABLE=1                — kill switch (wins over enable)
+#   CC_LOOP_GUARD_TRANSCRIPT=<path>        — override transcript path (test)
+#   CC_LOOP_GUARD_FORCE=1                  — fire regardless of source (test)
+#   CC_LOOP_GUARD_THRESHOLD=<N>            — minimum precursor blocks to
+#                                            trigger (default 1)
+#
+# TRIGGER: SessionStart
+# MATCHER: "" (filters event internally)
+#
+# Exit codes:
+#   0 — safe to proceed (env disabled, no precursor, or non-resume source)
+#   2 — BLOCK (precursor detected under armed guard); decision JSON on stderr
+
+set -uo pipefail
+
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-extended-thinking-loop-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [extended-thinking-loop-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+
+# Kill switch wins.
+[ "${CC_LOOP_GUARD_DISABLE:-0}" = "1" ] && exit 0
+
+# Default behavior: not armed → silent no-op. This is the key safety
+# property: dropping the hook into settings.json without setting the env
+# var must not change behavior for interactive operators.
+[ "${CC_LOOP_GUARD_ENABLED:-0}" = "1" ] || exit 0
+
+EVENT=$(printf '%s' "$INPUT" | jq -r '.event // .hook_event_name // empty' 2>/dev/null)
+case "$EVENT" in
+    session_start|SessionStart|sessionstart) ;;
+    *) exit 0 ;;
+esac
+
+# Only fire on resume/continue. A fresh `startup` cannot carry a stale
+# precursor (no transcript yet). Unknown source defaults to scanning so
+# new client versions that introduce new source labels stay covered.
+SOURCE=$(printf '%s' "$INPUT" | jq -r '.source // empty' 2>/dev/null)
+if [ "${CC_LOOP_GUARD_FORCE:-0}" != "1" ]; then
+    case "$SOURCE" in
+        resume|continue|"") ;;
+        startup|fresh|new) exit 0 ;;
+        *) ;;
+    esac
+fi
+
+# Locate the transcript file. Same heuristic as PR #445 — recompute the
+# Claude Code project slug from CC_PROJECT_DIR or PWD; if it doesn't
+# resolve, fail open rather than blocking blindly.
+LATEST="${CC_LOOP_GUARD_TRANSCRIPT:-}"
+if [ -z "$LATEST" ]; then
+    PROJ_DIR="${CC_PROJECT_DIR:-$PWD}"
+    SLUG=$(printf '%s' "$PROJ_DIR" | sed 's|/|-|g')
+    TRANSCRIPT_DIR="${HOME}/.claude/projects/${SLUG}"
+    [ -d "$TRANSCRIPT_DIR" ] || exit 0
+    LATEST=$(ls -t "$TRANSCRIPT_DIR"/*.jsonl 2>/dev/null | head -1)
+fi
+[ -n "$LATEST" ] || exit 0
+[ -r "$LATEST" ] || exit 0
+
+# Scan for empty-thinking + non-empty-signature blocks. Same shape as the
+# PR #445 detector; the difference is what we do with the result.
+SCAN=$(jq -rR 'fromjson? | select(.type == "assistant") | .message.content[]? | select(.type == "thinking" and ((.thinking // "") | length) == 0 and ((.signature // "") | length) > 0) | (.signature | length)' "$LATEST" 2>/dev/null || true)
+
+if [ -z "$SCAN" ]; then
+    exit 0
+fi
+
+COUNT=$(printf '%s\n' "$SCAN" | grep -c .)
+THRESHOLD="${CC_LOOP_GUARD_THRESHOLD:-1}"
+
+if [ "$COUNT" -lt "$THRESHOLD" ]; then
+    exit 0
+fi
+
+# Block. Emit decision JSON on stderr and exit 2. The decision payload is
+# what Claude Code surfaces to the operator (and what an enclosing harness
+# can grep for to identify the bail reason).
+REASON="Cluster 13A precursor detected on disk (${COUNT} empty-text-signed thinking block(s) in ${LATEST}). Under autonomous loop, resuming this transcript would re-send the corrupted blocks, hit API 400 (\`thinking\` blocks cannot be modified), and the loop would replay indefinitely. Stopping the resume to break the loop. Recover by: (1) backing up the .jsonl, (2) stripping thinking/redacted_thinking blocks from assistant content arrays in-place (leave uuid/parentUuid chains intact), (3) clearing CC_LOOP_GUARD_ENABLED or setting CC_LOOP_GUARD_DISABLE=1 for the recovery session, then resuming. Reference: https://github.com/anthropics/claude-code/issues/63147 — Field guide: https://gist.github.com/yurukusa/8c6be069f602399238356a9c9b719a45"
+
+# JSON-escape the reason field for the decision payload. Use jq for the
+# escape so embedded backticks, quotes, slashes, etc. don't break the JSON.
+DECISION=$(jq -nc --arg r "$REASON" '{decision:"block", reason:$r}' 2>/dev/null)
+
+if [ -n "$DECISION" ]; then
+    printf '%s\n' "$DECISION" >&2
+else
+    # jq unavailable for the escape — fall back to a plain-text reason.
+    # Operators get the message; harness grep on "decision" may miss it.
+    printf '[extended-thinking-loop-guard] BLOCK: %s\n' "$REASON" >&2
+fi
+
+exit 2

package/examples/extended-thinking-resume-warning.sh

@@ -0,0 +1,119 @@
+#!/bin/bash
+# extended-thinking-resume-warning.sh — Warn before resuming a session whose
+#                                        transcript carries the 13A precursor.
+#
+# Solves: Cluster 13 Axis A — the resume serialization corruption that wedges
+#         extended-thinking sessions on a permanent API 400. Claude Code
+#         persists thinking blocks to the session transcript with the
+#         `thinking` field emptied to "" but the `signature` field retained
+#         from the original response. When the session is resumed, the client
+#         sends `{"thinking": "", "signature": "<original>"}` to the API; the
+#         signature was computed over the original non-empty thinking text,
+#         so validation fails and the session is permanently wedged.
+#
+# Issue addressed: #63147 (central case, 33 reactions). Field guide:
+#         https://gist.github.com/yurukusa/8c6be069f602399238356a9c9b719a45
+#
+# How it works: SessionStart hook. When the session source indicates a resume
+#   or continue, finds the transcript directory for the current project
+#   (~/.claude/projects/<slug>/) and reads the most recent .jsonl file. Scans
+#   the file for assistant thinking blocks where `thinking` is empty but
+#   `signature` is non-empty — the on-disk shape that becomes the 13A wedge
+#   on the next API request.
+#
+#   If the pattern is present, the hook emits a stderr advisory naming
+#   sub-pattern 13A, pointing at the field guide, and listing the recommended
+#   actions (save state, start fresh). The hook NEVER blocks — exit 0 always.
+#
+# Heuristic notes:
+#   - Claude Code's project slug is the absolute project dir with leading
+#     slash stripped and remaining `/` replaced with `-` (e.g.
+#     `/home/u/proj` → `home-u-proj`). The hook recomputes this from
+#     CC_PROJECT_DIR or PWD; if the layout differs in a future client
+#     version the hook fails open rather than emitting a stale warning.
+#   - Trailing thinking blocks in healthy sessions are *also* frequently
+#     stored empty-but-signed (per #63147 evidence), so the hook fires on
+#     a SHAPE that is common, not a SHAPE that is uniquely broken. The
+#     advisory is calibrated to match: it warns the operator that resume
+#     may hit the 400, not that it definitely will.
+#
+# Environment variables:
+#   CC_EXTENDED_THINKING_RESUME_DISABLE=1   — disable advisory entirely
+#   CC_EXTENDED_THINKING_RESUME_VERBOSE=1   — include per-block sizes
+#   CC_EXTENDED_THINKING_RESUME_TRANSCRIPT  — override transcript path (test)
+#   CC_EXTENDED_THINKING_RESUME_FORCE=1     — fire regardless of source (test)
+#
+# TRIGGER: SessionStart
+# MATCHER: "" (filters event internally)
+
+set -uo pipefail
+
+INPUT=$(cat)
+[ "${CC_EXTENDED_THINKING_RESUME_DISABLE:-0}" = "1" ] && exit 0
+
+EVENT=$(printf '%s' "$INPUT" | jq -r '.event // .hook_event_name // empty' 2>/dev/null)
+case "$EVENT" in
+    session_start|SessionStart|sessionstart) ;;
+    *) exit 0 ;;
+esac
+
+# Only fire on resume/continue. Some clients send `source: "resume"`,
+# others `source: "continue"`, others omit it. Fail-open: when the source
+# field is missing or unknown, default to scanning (the cost is one
+# advisory if the transcript happens to carry the precursor shape).
+SOURCE=$(printf '%s' "$INPUT" | jq -r '.source // empty' 2>/dev/null)
+if [ "${CC_EXTENDED_THINKING_RESUME_FORCE:-0}" != "1" ]; then
+    case "$SOURCE" in
+        resume|continue|"") ;;
+        startup|fresh|new) exit 0 ;;
+        *) ;;  # unknown source — scan anyway
+    esac
+fi
+
+# Locate the transcript file.
+LATEST="${CC_EXTENDED_THINKING_RESUME_TRANSCRIPT:-}"
+if [ -z "$LATEST" ]; then
+    PROJ_DIR="${CC_PROJECT_DIR:-$PWD}"
+    SLUG=$(printf '%s' "$PROJ_DIR" | sed 's|/|-|g')
+    TRANSCRIPT_DIR="${HOME}/.claude/projects/${SLUG}"
+    [ -d "$TRANSCRIPT_DIR" ] || exit 0
+    LATEST=$(ls -t "$TRANSCRIPT_DIR"/*.jsonl 2>/dev/null | head -1)
+fi
+[ -n "$LATEST" ] || exit 0
+[ -r "$LATEST" ] || exit 0
+
+# Scan for empty-thinking + non-empty-signature blocks. Read each line as
+# raw text and use fromjson? so malformed lines are silently skipped rather
+# than aborting the scan.
+SCAN=$(jq -rR 'fromjson? | select(.type == "assistant") | .message.content[]? | select(.type == "thinking" and ((.thinking // "") | length) == 0 and ((.signature // "") | length) > 0) | (.signature | length)' "$LATEST" 2>/dev/null || true)
+[ -z "$SCAN" ] && exit 0
+
+COUNT=$(printf '%s\n' "$SCAN" | grep -c .)
+SIG_LENGTHS=$(printf '%s' "$SCAN" | tr '\n' ' ')
+
+{
+    echo "[extended-thinking-resume-warning] Cluster 13A precursor detected."
+    echo ""
+    echo "  Transcript: $LATEST"
+    echo "  Empty-text signed thinking block(s): ${COUNT}"
+    echo ""
+    echo "Resuming this session may hit the persistent API 400:"
+    echo "    \`thinking\` blocks in the latest assistant message cannot be modified."
+    echo ""
+    echo "Once it fires, the wedge persists for the life of the transcript —"
+    echo "every subsequent turn re-sends the same corrupted message and re-fails."
+    echo ""
+    echo "Recommended actions:"
+    echo "  - If resume is critical, save state from the running process now."
+    echo "  - Otherwise start a fresh session; the wedge cannot be cleared in-session."
+    echo "  - Disable extended thinking via /model if your next task allows."
+    echo ""
+    echo "Reference: https://github.com/anthropics/claude-code/issues/63147"
+    echo "Field guide: https://gist.github.com/yurukusa/8c6be069f602399238356a9c9b719a45"
+    if [ "${CC_EXTENDED_THINKING_RESUME_VERBOSE:-0}" = "1" ]; then
+        echo ""
+        echo "(per-block signature lengths: ${SIG_LENGTHS})"
+    fi
+} >&2
+
+exit 0

package/examples/extended-thinking-tool-use-mismatch-detector.sh

@@ -0,0 +1,212 @@
+#!/bin/bash
+# ================================================================
+# extended-thinking-tool-use-mismatch-detector.sh — Warn when the
+#   structural 12B pattern is detected in the trailing transcript:
+#   assistant turns with stop_reason="tool_use" but no parseable
+#   tool_use block in content (only thinking and/or text blocks).
+# ================================================================
+# PURPOSE:
+#   Issue #62467 documents that when Opus 4.7's extended thinking
+#   is active, the assistant turn can carry stop_reason="tool_use"
+#   yet emit only a thinking block — no tool_use block reaches the
+#   harness parser. The harness then surfaces a "malformed and
+#   could not be parsed" notice and retries; in the reporter's
+#   sessions ~20 retry prompts accumulated across 6 sessions with
+#   no recovery. Output size and special characters are ruled out;
+#   the common factor is Opus 4.7 + extended thinking.
+#
+#   The companion sub-pattern 12A
+#   (long-session-malformed-tool-call-detector.sh, PR #406) keys
+#   off the literal "malformed and could not be parsed" string in
+#   the transcript text. That text marker fires for any cause of
+#   the same surface symptom. The 12B detector here keys off the
+#   structural mismatch directly — stop_reason vs. content-block
+#   absence — so the operator gets sub-pattern-specific naming
+#   even when 12A's text marker has not appeared yet (the harness
+#   may suppress the parser notice in some configurations) or when
+#   it fires together with 12A's marker (both advisories then name
+#   the cluster, with 12B specifically calling out the
+#   extended-thinking factor and pointing to the workaround at the
+#   model layer rather than at the session layer).
+#
+# TRIGGER: PostToolUse  MATCHER: ""
+# CLUSTER: 12 (Tool Call Parsing failures in Opus 4.7)
+# SUB-PATTERN: 12B (extended-thinking serialization defect)
+#
+# BEHAVIOR:
+#   - Read transcript_path from PostToolUse hook input.
+#   - Scan the trailing LOOKBACK lines for assistant turns.
+#   - For each assistant turn, check if .stop_reason == "tool_use"
+#     and the .content array contains no element with
+#     .type == "tool_use". Count each such mismatch.
+#   - If at or above the threshold, emit a one-screen stderr
+#     advisory naming sub-pattern 12B and pointing to the
+#     model-layer workaround (switch to a variant without
+#     extended thinking).
+#   - Rate-limit advisory emission per session via a counter
+#     file so the warning does not repeat on every PostToolUse
+#     after the first detection.
+#   - Always exits 0 (advisory only; never blocks tool execution).
+#
+# CONFIGURATION (env vars):
+#   CC_THINKING_MISMATCH_DISABLE     Set to "1" to silence.
+#   CC_THINKING_MISMATCH_LOOKBACK    How many recent transcript
+#                                    lines to scan. Default 150.
+#   CC_THINKING_MISMATCH_THRESHOLD   Minimum mismatches in
+#                                    LOOKBACK to fire. Default 2.
+#                                    (Single mismatches are rare
+#                                    but can occur from unrelated
+#                                    serialization edge cases;
+#                                    requiring 2 keys off the
+#                                    repeated-failure shape
+#                                    #62467 actually documents.)
+#   CC_THINKING_MISMATCH_COOLDOWN    Minimum tool calls between
+#                                    repeat advisories per
+#                                    session. Default 30.
+#   CC_THINKING_MISMATCH_TRANSCRIPT  Override transcript path
+#                                    (used by tests).
+#   CC_THINKING_MISMATCH_STATE_DIR   Override state directory
+#                                    (used by tests). Default
+#                                    /tmp/cc-thinking-mismatch.
+#
+# UPSTREAM REFERENCES:
+#   #62467 (central case: stop_reason="tool_use" with only a
+#           thinking block, ~20 retry prompts across 6 sessions,
+#           Opus 4.7 + extended thinking)
+#   #62123 (broader "retry also failed" central case, 21 reactions)
+#   #62344 (in-context few-shot poisoning, sub-pattern 12A)
+#   #62700 (spurious malformed notice, sub-pattern 12C)
+#
+# RECOVERY ON A HIT:
+#   The advisory does not recover the session. The known
+#   workaround for sub-pattern 12B is at the model layer:
+#     - Switch to a Claude Sonnet variant for the task at hand.
+#     - Disable extended thinking via the /model command when
+#       Opus's standard mode is sufficient.
+#   /clear (the 12A recovery) does not fix 12B because the
+#   serialization defect re-fires on the next extended-thinking
+#   turn even in a fresh session. The advisory's value is in
+#   pointing the operator at the correct workaround layer.
+# ================================================================
+
+set -u
+
+if [ "${CC_THINKING_MISMATCH_DISABLE:-0}" = "1" ]; then
+    exit 0
+fi
+
+LOOKBACK="${CC_THINKING_MISMATCH_LOOKBACK:-150}"
+THRESHOLD="${CC_THINKING_MISMATCH_THRESHOLD:-2}"
+COOLDOWN="${CC_THINKING_MISMATCH_COOLDOWN:-30}"
+STATE_DIR="${CC_THINKING_MISMATCH_STATE_DIR:-/tmp/cc-thinking-mismatch}"
+
+INPUT=$(cat 2>/dev/null || true)
+
+TRANSCRIPT_PATH="${CC_THINKING_MISMATCH_TRANSCRIPT:-}"
+if [ -z "$TRANSCRIPT_PATH" ]; then
+    TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+fi
+
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+    exit 0
+fi
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // "default"' 2>/dev/null)
+[ -z "$SESSION_ID" ] && SESSION_ID="default"
+
+SAFE_SESSION=$(printf '%s' "$SESSION_ID" | tr -c 'A-Za-z0-9._-' '_' | head -c 80)
+[ -z "$SAFE_SESSION" ] && SAFE_SESSION="default"
+
+mkdir -p "$STATE_DIR" 2>/dev/null
+
+COUNTER_FILE="$STATE_DIR/${SAFE_SESSION}.count"
+LASTFIRED_FILE="$STATE_DIR/${SAFE_SESSION}.lastfired"
+
+COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo 0)
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+
+# Count structural 12B mismatches in the trailing window.
+# A mismatch is an assistant turn line where:
+#   - stop_reason equals "tool_use" (checked at .stop_reason and
+#     .message.stop_reason to handle both common transcript shapes)
+#   - the matching content array contains no element with
+#     type == "tool_use"
+# Each line is parsed independently; lines that fail to parse as
+# JSON are silently skipped.
+MISMATCHES=$(tail -n "$LOOKBACK" "$TRANSCRIPT_PATH" 2>/dev/null | jq -R -r '
+    try (fromjson) catch null | select(. != null) | . as $obj |
+    (
+        (($obj.stop_reason // $obj.message.stop_reason) == "tool_use")
+        and
+        (
+            (($obj.content // $obj.message.content // []) | type) == "array"
+        )
+        and
+        (
+            (($obj.content // $obj.message.content // []) | map(select(.type == "tool_use")) | length) == 0
+        )
+    ) | select(. == true) | "1"
+' 2>/dev/null | wc -l | tr -d ' ')
+
+MISMATCHES="${MISMATCHES:-0}"
+
+if [ "$MISMATCHES" -lt "$THRESHOLD" ]; then
+    exit 0
+fi
+
+LASTFIRED=$(cat "$LASTFIRED_FILE" 2>/dev/null || echo 0)
+SINCE=$((COUNT - LASTFIRED))
+
+if [ "$LASTFIRED" -gt 0 ] && [ "$SINCE" -lt "$COOLDOWN" ]; then
+    exit 0
+fi
+
+echo "$COUNT" > "$LASTFIRED_FILE"
+
+cat >&2 <<EOF
+
+⚠️  Detected ${MISMATCHES} assistant turn(s) with stop_reason="tool_use"
+    but no parseable tool_use block in content, in the trailing
+    ${LOOKBACK} transcript lines.
+
+This is the structural signal for sub-pattern 12B
+(extended-thinking serialization defect), the case filed in #62467.
+When Opus 4.7's extended thinking is active, the assistant turn can
+carry stop_reason="tool_use" yet emit only a thinking block — the
+tool_use block never reaches the harness parser. The reporter
+observed ~20 retry prompts accumulated across 6 sessions before
+giving up; output size and special characters were ruled out, and
+the common factor was Opus 4.7 + extended thinking.
+
+Sub-pattern 12B is distinct from 12A (in-context few-shot
+poisoning, #62344, recovered by \`/clear\`). 12B is at the model
+serialization layer, so a fresh session does not recover — the
+defect re-fires on the next extended-thinking turn.
+
+Known workarounds (operator-side, at the model layer):
+  - Switch to a Claude Sonnet variant for the affected task.
+  - Disable extended thinking via the \`/model\` command when
+    Opus's standard mode is sufficient for the work.
+  - Break the work into smaller sub-tasks that complete without
+    the model entering extended thinking.
+
+If a single mismatch in the window is informational, sub-pattern
+12B's actual signal is the repeated-failure shape #62467 documents
+(the default threshold of 2 keys off that). If you are seeing
+mismatches reliably above the threshold, the model layer is in the
+state #62467 describes and operator-side hooks cannot recover.
+
+References: #62467 (the extended-thinking-serialization central
+case), #62123 (the broader "retry also failed" case, 21 reactions),
+Cluster 12 in the cc-safe-setup tracker:
+https://yurukusa.github.io/cc-safe-setup/cluster-tracker.html#cluster-tool-call-parsing
+
+Silence: set CC_THINKING_MISMATCH_DISABLE=1.
+Tune sensitivity: CC_THINKING_MISMATCH_THRESHOLD (default 2),
+                  CC_THINKING_MISMATCH_LOOKBACK (default 150 lines),
+                  CC_THINKING_MISMATCH_COOLDOWN (default 30 tool calls).
+
+EOF
+
+exit 0