cc-safe-setup 29.8.0 → 30.0.5

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

package/examples/fabricated-command-detector.sh

@@ -0,0 +1,145 @@
+#!/bin/bash
+# fabricated-command-detector.sh — Detect command-shaped tokens in the final
+# assistant response that were never invoked as Bash tool calls in the session.
+#
+# Solves: substitution-by-default at the response layer (issue #60340).
+#   In #60340, a security-research reproduction shipped with `./exploit` as
+#   the command in the assistant's writeup, while the operator's actual
+#   reproduction command (`./chage_pwn root`) was established through dozens
+#   of Bash tool calls. The model never invoked `./exploit` — it generated
+#   a plausible-looking parallel command and substituted it into the response.
+#
+# How it works: Stop hook that reads the latest assistant turn from the
+#   session transcript, extracts command-shaped tokens (./xxx, git xxx,
+#   bash xxx, etc.) from inline code spans, and cross-references each one
+#   against the Bash tool calls that actually occurred in the session.
+#   Tokens that look like commands but were never invoked are flagged as
+#   possible fabrication.
+#
+# This hook is advisory by default — it warns to stderr and exits 0.
+# It does not block the response. Set CC_FABRICATED_CMD_BLOCK=1 to make
+# unverified tokens cause a non-zero exit (use for high-stakes contexts
+# like security reproductions).
+#
+# TRIGGER: Stop
+# MATCHER: ""
+#
+# Configuration:
+#   CC_FABRICATED_CMD_DISABLE=1    Disable the hook completely.
+#   CC_FABRICATED_CMD_BLOCK=1      Exit non-zero (exit 2) when fabricated
+#                                  tokens are detected. Default: advisory.
+#   CC_FABRICATED_CMD_ALLOW=regex  Pattern of tokens to ignore (e.g. for
+#                                  hypothetical example commands). Matched
+#                                  with `grep -E` against the token text.
+#   CC_FABRICATED_CMD_MAX=20       Maximum tokens to scan per response.
+#                                  Default 20. Cap protects performance on
+#                                  very long responses.
+
+set -u
+
+# 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-fabricated-command-detector-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [fabricated-command-detector]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+[ "${CC_FABRICATED_CMD_DISABLE:-0}" = "1" ] && exit 0
+
+INPUT=$(cat)
+
+TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+[ -z "$TRANSCRIPT" ] && exit 0
+[ ! -r "$TRANSCRIPT" ] && exit 0
+
+# Extract the LAST assistant message text content from the transcript.
+# Transcript is jsonl: one event per line. Look for the last assistant
+# message and concatenate its text content blocks.
+LAST_ASSISTANT=$(tac "$TRANSCRIPT" 2>/dev/null | grep -m1 '"role":"assistant"' || true)
+[ -z "$LAST_ASSISTANT" ] && exit 0
+
+# Try a few schemas for the assistant text. Newer transcripts wrap content
+# as an array of typed blocks; older ones may use a flat text field.
+RESPONSE_TEXT=$(printf '%s' "$LAST_ASSISTANT" | jq -r '
+  if .message.content then
+    (.message.content | if type == "array" then map(select(.type == "text") | .text) | join("\n") else . end)
+  elif .content then
+    (.content | if type == "array" then map(select(.type == "text") | .text) | join("\n") else . end)
+  else
+    empty
+  end
+' 2>/dev/null)
+
+[ -z "$RESPONSE_TEXT" ] && exit 0
+
+# Extract command-shaped tokens from backtick inline code in the response.
+# Patterns that look like operator commands the response is asserting were
+# (or are to be) run:
+#   - ./xxx and ./xxx_yyy and ./bin/xxx (relative executables)
+#   - git <subcommand> ... (git invocations)
+#   - bash <script>, sh <script> (shell-script invocations)
+#   - npm/pnpm/yarn run <task>
+#   - python <script>, node <script>
+MAX_TOKENS="${CC_FABRICATED_CMD_MAX:-20}"
+ALLOW_PATTERN="${CC_FABRICATED_CMD_ALLOW:-}"
+
+# Extract inline code spans (backtick-fenced single-line content)
+TOKENS=$(printf '%s\n' "$RESPONSE_TEXT" \
+  | grep -oE '`[^`]+`' 2>/dev/null \
+  | sed -e 's/^`//' -e 's/`$//' \
+  | grep -E '^(\./|git[[:space:]]+[a-z]+|bash[[:space:]]+[^[:space:]]|sh[[:space:]]+[^[:space:]]|npm[[:space:]]+run|pnpm[[:space:]]+run|yarn[[:space:]]+run|python[[:space:]]+[^[:space:]]+\.py|node[[:space:]]+[^[:space:]]+\.[mc]?js)' 2>/dev/null \
+  | sort -u \
+  | head -n "$MAX_TOKENS")
+
+[ -z "$TOKENS" ] && exit 0
+
+# Apply ALLOW filter if set
+if [ -n "$ALLOW_PATTERN" ]; then
+  TOKENS=$(printf '%s\n' "$TOKENS" | grep -Ev "$ALLOW_PATTERN" 2>/dev/null || true)
+fi
+
+[ -z "$TOKENS" ] && exit 0
+
+# Extract all Bash tool-call commands from the entire transcript.
+# Look at tool_use events with name=Bash and pull their command input.
+INVOKED_COMMANDS=$(grep -h '"name":"Bash"' "$TRANSCRIPT" 2>/dev/null \
+  | jq -r '
+    if .message.content then
+      (.message.content[]? | select(.type == "tool_use" and .name == "Bash") | .input.command // empty)
+    elif .content then
+      (.content[]? | select(.type == "tool_use" and .name == "Bash") | .input.command // empty)
+    else empty end
+  ' 2>/dev/null)
+
+# Compare each candidate token against the invoked commands.
+# A token is "verified" if its command-shaped form appears as a substring
+# of any invoked command (matches the literal sequence the operator ran).
+UNVERIFIED=""
+while IFS= read -r token; do
+  [ -z "$token" ] && continue
+  # Escape token for fixed-string match
+  if ! printf '%s' "$INVOKED_COMMANDS" | grep -Fq -- "$token" 2>/dev/null; then
+    UNVERIFIED="${UNVERIFIED}${UNVERIFIED:+$'\n'}${token}"
+  fi
+done <<< "$TOKENS"
+
+[ -z "$UNVERIFIED" ] && exit 0
+
+# Emit advisory listing unverified tokens.
+echo "⚠ fabricated-command-detector: command-shaped tokens in the response were not invoked as Bash tool calls in this session:" >&2
+printf '%s\n' "$UNVERIFIED" | while IFS= read -r line; do
+  [ -n "$line" ] && echo "  - $line" >&2
+done
+echo "  Verify each token before relying on the response as an operational record." >&2
+echo "  See issue #60340 for the failure shape (substitution-by-default at the response layer)." >&2
+
+if [ "${CC_FABRICATED_CMD_BLOCK:-0}" = "1" ]; then
+  exit 2
+fi
+
+exit 0