cc-safe-setup 29.8.0 → 30.0.4

package/examples/memory-write-guard.sh

@@ -1,40 +1,122 @@
 #!/bin/bash
 # ================================================================
-# memory-write-guard.sh — Log writes to ~/.claude/ directory
+# memory-write-guard.sh — See, approve, or block silent memory writes
 # ================================================================
 # PURPOSE:
-#   Claude auto-writes to ~/.claude/projects/*/memory/ without
-#   user visibility. This hook logs all writes to ~/.claude/ paths
-#   so users know what's being stored.
+#   Claude Code writes to its memory without asking: it edits CLAUDE.md
+#   and silently creates/updates/deletes files under
+#   ~/.claude/projects/*/memory/. Users report having to re-check those
+#   files after every session to find changes they never approved.
 #
-# TRIGGER: PreToolUse  MATCHER: "Write|Edit"
+#   This hook gives the operator control over those writes. By default it
+#   only makes them VISIBLE (logs + a stderr note), which is non-intrusive
+#   and safe for automated runs. Opt in to an approval prompt — or a hard
+#   block — when you want every memory change to pass through you first.
 #
-# Born from: https://github.com/anthropics/claude-code/issues/38040
-#   "No way to enforce approval on all file modifications"
+# WHAT COUNTS AS A "MEMORY" WRITE (Write/Edit/MultiEdit on):
+#   - any CLAUDE.md / CLAUDE.local.md (project or user memory)
+#   - anything under a .claude/ directory, which includes the auto-memory
+#     store ~/.claude/projects/*/memory/ and ~/.claude/settings.json
+#
+# MODE (env var CC_MEMORY_WRITE_APPROVAL):
+#   off   (default) — log + warn, never interrupt   (backward compatible)
+#   ask            — require interactive approval for each memory write
+#   block          — refuse all memory writes
+#
+# WHY OPT-IN: existing installs and headless/CI runs must keep working
+#   unchanged, so the prompt is never on unless the operator asks for it.
+#
+# VERSION NOTE (measured 2026-08-13 on 2.1.228, corrects an earlier note here):
+#   #77212 reported that under bypassPermissions an "ask" decision is silently
+#   auto-approved and does not gate the write. This comment used to repeat that
+#   as current behaviour. It does not reproduce on 2.1.228: run interactively in
+#   an isolated HOME, the confirmation appears both under
+#   --dangerously-skip-permissions and under --permission-mode auto, carrying
+#   this hook's permissionDecisionReason. Control: with the hook removed, both
+#   modes ran the same command with no prompt at all, so the permissive mode was
+#   genuinely in effect. Non-interactively (claude -p) the call is refused
+#   rather than approved. Older builds may still match the report — verify on
+#   your own version with `--version` before relying on either behaviour.
+#   Independent of all this: an "ask" needs somebody present to answer, so for
+#   fully unattended runs use CC_MEMORY_WRITE_APPROVAL=block (exit 2), which is
+#   enforced regardless of permission mode.
+#
+# TRIGGER: PreToolUse  MATCHER: "Write|Edit|MultiEdit"
+#
+# Born from:
+#   https://github.com/anthropics/claude-code/issues/38040
+#     "No way to enforce approval on all file modifications"
+#   https://github.com/anthropics/claude-code/issues/65064
+#     "claude code writes memory without asking for permission"
 # ================================================================
 
+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-memory-write-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [memory-write-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
 [ -z "$FILE" ] && exit 0
 
-# Check if targeting ~/.claude/
+# Is this a memory file? Match the auto-memory/.claude store and CLAUDE.md
+# files anywhere (project ./CLAUDE.md as well as ~/.claude/CLAUDE.md).
+BASENAME=$(basename "$FILE")
+IS_MEMORY=0
 case "$FILE" in
-    */.claude/*|~/.claude/*)
-        # Log the write
-        LOG="$HOME/.claude/memory-writes.log"
-        echo "[$(date -Iseconds)] Write to: $FILE" >> "$LOG" 2>/dev/null
+    */.claude/*|~/.claude/*) IS_MEMORY=1 ;;
+esac
+case "$BASENAME" in
+    CLAUDE.md|CLAUDE.local.md) IS_MEMORY=1 ;;
+esac
+[ "$IS_MEMORY" -eq 0 ] && exit 0
+
+# Record every memory write so the operator can audit what was stored.
+LOG="$HOME/.claude/memory-writes.log"
+echo "[$(date -Iseconds)] Write to: $FILE" >> "$LOG" 2>/dev/null
 
-        # Only warn (don't block) — memory writes are usually intentional
-        echo "NOTE: Writing to Claude config directory: $FILE" >&2
+MODE="${CC_MEMORY_WRITE_APPROVAL:-off}"
 
-        # Block writes to settings.json unless explicitly allowed
+case "$MODE" in
+    ask)
+        # Emit a PreToolUse permission decision. In an interactive session
+        # this surfaces an approve/deny prompt — including under
+        # bypassPermissions and auto mode, measured on 2.1.228 (see the
+        # VERSION NOTE at the top; #77212 reported otherwise on older builds).
+        # Use =block when nobody is present to answer the prompt.
+        jq -n --arg f "$FILE" '{
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "ask",
+                permissionDecisionReason: ("Approve write to memory file: " + $f)
+            }
+        }'
+        exit 0
+        ;;
+    block)
+        echo "BLOCKED: memory write refused by memory-write-guard." >&2
+        echo "File: $FILE" >&2
+        echo "Set CC_MEMORY_WRITE_APPROVAL=ask to approve per-write, or =off to only log." >&2
+        exit 2
+        ;;
+    *)
+        # off (default): only make the write visible.
+        echo "NOTE: Writing to Claude memory: $FILE" >&2
         case "$FILE" in
             */settings.json|*/settings.local.json)
                 echo "WARNING: Modifying Claude Code settings file." >&2
                 echo "Verify this change is intentional." >&2
                 ;;
         esac
+        exit 0
         ;;
 esac
-
-exit 0

package/examples/migration-verify-guard.sh

@@ -14,6 +14,18 @@
 
 set -euo 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-migration-verify-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [migration-verify-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/model-swap-suggester.sh

@@ -0,0 +1,177 @@
+#!/bin/bash
+# model-swap-suggester.sh — Evidence-driven swap recommendation for the AUP false-positive cluster
+#
+# Background:
+#   Cluster 9 (Usage Policy classifier over-trigger) accumulated 25+ open GitHub issues
+#   between 2026-05-18 and 2026-05-27, with Opus 4.7 / 4.6 / 1M variants over-triggering
+#   on benign Claude Code prompts (English, Russian, Polish, Spanish; kernel security,
+#   biomedical, FPGA, plain greetings — context-independent). Sonnet variants are reported
+#   unaffected.
+#
+#   Two defense hooks ship today:
+#     - aup-false-positive-helper.sh   (SessionStart, opt-in, generic awareness)
+#     - aup-block-pattern-logger.sh    (PostToolUse, on-by-default, records each block)
+#
+#   The gap they leave: the operator who is actively being blocked needs an evidence-driven
+#   recommendation at the right moment — "you have been blocked N times in the last hour
+#   on Opus, here is the exact swap command." The helper hook is generic and fires on every
+#   Opus session; the logger collects evidence but does not act on it.
+#
+#   This hook closes that loop. On SessionStart, it reads the block log written by the
+#   logger, counts Opus blocks in a recent time window, and emits a concrete swap-to-Sonnet
+#   advisory only when the count crosses a threshold. Silent otherwise.
+#
+#   Reference: https://gist.github.com/yurukusa/4fa4751044be45bd83345601ee79c2db
+#
+# What this hook does:
+#   On SessionStart, if ANTHROPIC_MODEL is pinned to an Opus variant AND the AUP block log
+#   shows N or more blocks on any Opus model in the last M minutes, emit a one-time advisory
+#   with the exact swap command for the current session. Silent in every other case.
+#
+# When this hook does NOT emit anything:
+#   - CC_MODEL_SWAP_SUGGESTER_DISABLE=1
+#   - CC_MODEL_SWAP_SUGGESTER_QUIET=1
+#   - ANTHROPIC_MODEL unset                                  (default routing)
+#   - ANTHROPIC_MODEL pinned to a non-Opus variant           (Sonnet / Haiku unaffected)
+#   - aup-block log missing, empty, or unreadable
+#   - Opus blocks in the configured window < threshold
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "SessionStart": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/model-swap-suggester.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_MODEL_SWAP_SUGGESTER_DISABLE=1        — never emit
+#   CC_MODEL_SWAP_SUGGESTER_QUIET=1          — silent (post-acknowledgment)
+#   CC_MODEL_SWAP_SUGGESTER_THRESHOLD=<n>    — Opus block count threshold (default 3)
+#   CC_MODEL_SWAP_SUGGESTER_WINDOW_MIN=<n>   — lookback window in minutes (default 60)
+#   CC_MODEL_SWAP_SUGGESTER_TARGET=<model>   — target Sonnet model (default claude-sonnet-4-7)
+#   CC_AUP_BLOCK_LOG_PATH=<path>             — log path (shared with logger; default ~/.claude/aup-block-history.log)
+#
+# Design notes:
+#   - Evidence-driven, not opt-in. The advisory only fires when real blocks have happened,
+#     so it never adds noise for users who haven't been affected.
+#   - Counts Opus blocks across all Opus variants in the log (not just the currently pinned
+#     model), because the cluster signature is Opus-family-wide. If you swapped from
+#     opus-4-7 to opus-4-6 mid-day and both blocked, both count toward the threshold.
+#   - Window is timestamp-based, not last-N-lines, so a quiet session with stale entries
+#     does not trigger the advisory.
+#   - Never blocks. All failure paths exit 0 so a corrupt log or missing date utility
+#     cannot break the session.
+
+set -u
+
+# Disable path
+if [ "${CC_MODEL_SWAP_SUGGESTER_DISABLE:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Quiet path
+if [ "${CC_MODEL_SWAP_SUGGESTER_QUIET:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Model unset → default routing, no specific advisory
+if [ -z "${ANTHROPIC_MODEL:-}" ]; then
+  exit 0
+fi
+
+# Non-Opus model → unaffected by the cluster
+case "$ANTHROPIC_MODEL" in
+  *opus*|*Opus*|*OPUS*) : ;;
+  *) exit 0 ;;
+esac
+
+LOG_PATH="${CC_AUP_BLOCK_LOG_PATH:-$HOME/.claude/aup-block-history.log}"
+[ -f "$LOG_PATH" ] || exit 0
+[ -r "$LOG_PATH" ] || exit 0
+[ -s "$LOG_PATH" ] || exit 0
+
+THRESHOLD="${CC_MODEL_SWAP_SUGGESTER_THRESHOLD:-3}"
+WINDOW_MIN="${CC_MODEL_SWAP_SUGGESTER_WINDOW_MIN:-60}"
+TARGET="${CC_MODEL_SWAP_SUGGESTER_TARGET:-claude-sonnet-4-7}"
+
+# Validate numeric env vars; fall back to defaults on garbage input.
+case "$THRESHOLD" in
+  ''|*[!0-9]*) THRESHOLD=3 ;;
+esac
+case "$WINDOW_MIN" in
+  ''|*[!0-9]*) WINDOW_MIN=60 ;;
+esac
+
+# Compute cutoff epoch (now - window_min * 60). Use GNU date first, then BSD date.
+NOW=$(date -u '+%s' 2>/dev/null) || exit 0
+CUTOFF=$((NOW - WINDOW_MIN * 60))
+
+ts_to_epoch() {
+  local ts="$1"
+  date -u -d "$ts" '+%s' 2>/dev/null \
+    || date -j -u -f '%Y-%m-%dT%H:%M:%SZ' "$ts" '+%s' 2>/dev/null
+}
+
+# Count Opus blocks in the window. The log schema is:
+#   ISO8601_UTC | MODEL | TOOL | PATTERN_KIND | EXCERPT
+# We only count rows whose model field matches an Opus variant and whose timestamp falls
+# inside the cutoff window. Rows with unparseable timestamps are skipped silently.
+COUNT=0
+while IFS='|' read -r LOG_TS LOG_MODEL _LOG_TOOL _LOG_KIND _LOG_EXCERPT; do
+  [ -z "$LOG_TS" ] && continue
+  [ -z "$LOG_MODEL" ] && continue
+  case "$LOG_MODEL" in
+    *opus*|*Opus*|*OPUS*) : ;;
+    *) continue ;;
+  esac
+  LOG_EPOCH=$(ts_to_epoch "$LOG_TS")
+  [ -z "$LOG_EPOCH" ] && continue
+  case "$LOG_EPOCH" in
+    *[!0-9]*) continue ;;
+  esac
+  if [ "$LOG_EPOCH" -ge "$CUTOFF" ] 2>/dev/null; then
+    COUNT=$((COUNT + 1))
+  fi
+done < "$LOG_PATH"
+
+if [ "$COUNT" -lt "$THRESHOLD" ] 2>/dev/null; then
+  exit 0
+fi
+
+# Threshold crossed → emit one-time advisory. The advisory is deliberately concrete:
+# exact swap command, exact env-var suppression command, and pointers to the partner hooks
+# the operator can lean on after swapping.
+cat >&2 <<EOF
+[model-swap-suggester] $COUNT Usage Policy block(s) recorded on Opus models in the last $WINDOW_MIN minutes.
+
+Current model: $ANTHROPIC_MODEL
+Log file:      $LOG_PATH
+
+The Anthropic Usage Policy classifier has been over-triggering on benign prompts on Opus
+variants since 2026-05-18. Sonnet variants are reportedly unaffected. Recommended swap
+for this session:
+
+  export ANTHROPIC_MODEL=$TARGET
+
+After swapping, the false-positive helper will go silent automatically (Sonnet is treated
+as unaffected). Re-pin Opus once the upstream classifier stabilises.
+
+Related hooks (already shipped):
+  aup-false-positive-helper.sh — generic awareness advisory (opt-in via CC_AUP_FALSE_POSITIVE_HELPER_REMIND=1)
+  aup-block-pattern-logger.sh  — records each block to $LOG_PATH
+
+To silence this advisory permanently for the current session, even when blocks continue:
+  export CC_MODEL_SWAP_SUGGESTER_QUIET=1
+
+To raise the threshold instead of silencing:
+  export CC_MODEL_SWAP_SUGGESTER_THRESHOLD=10   # only suggest after 10 blocks in $WINDOW_MIN min
+
+GitHub tracker (25+ independent reports, 2026-05-18 through 2026-05-27):
+  https://github.com/anthropics/claude-code/issues/60366
+  https://github.com/anthropics/claude-code/issues/62190
+EOF
+
+exit 0

package/examples/model-version-alert.sh

@@ -1,3 +1,4 @@
+#!/bin/bash
 INPUT=$(cat)
 COUNTER_FILE="/tmp/.cc-model-check-counter"
 COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo 0)
@@ -6,7 +7,10 @@ echo "$COUNT" > "$COUNTER_FILE"
 if [ $((COUNT % 50)) -ne 0 ]; then
     exit 0
 fi
-SESSION_FILE=$(ls -t ~/.claude/projects/*/session.jsonl 2>/dev/null | head -1)
+# 記録の場所を推測しない（旧: projects/*/session.jsonl は実在せず、
+# glob が空のまま黙って一度も警告しなかった）。
+SESSION_FILE=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+[ -f "$SESSION_FILE" ] || SESSION_FILE=$(ls -t "$HOME"/.claude/projects/*/*.jsonl 2>/dev/null | head -1)
 if [ -n "$SESSION_FILE" ]; then
     MODEL=$(grep -o '"model":"[^"]*"' "$SESSION_FILE" 2>/dev/null | tail -1 | cut -d'"' -f4)
     if echo "$MODEL" | grep -qi "opus-4-7\|opus-4.7"; then

package/examples/model-version-lock.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# model-version-lock.sh — silent mid-session downgrade detector (Incident 4)
+# Why: Opus 4.7 sessions sometimes migrate mid-session to a different model
+#      (for example the 1M-context automatic switch, #49541) with no client-
+#      visible announcement. The downgrade silently changes token accounting,
+#      context window, and quality. This hook writes a lock file containing
+#      the model id seen on the first turn of the session and emits a stderr
+#      banner whenever a later turn reports a different model id.
+# Event: PostToolUse  MATCHER: "*"
+# Action: First per-session call creates
+#         ~/.claude/logs/model-locks/<session-id>.model. Subsequent calls read
+#         the lock and compare. Mismatch → banner. /model is the expected
+#         user path for intentional switches, so the banner says so.
+#
+# To reset: rm -rf ~/.claude/logs/model-locks/   (between sessions that
+# deliberately switch models, otherwise locks accumulate)
+
+set -u
+
+LOG_DIR="${HOME}/.claude/logs"
+LOCK_DIR="${LOG_DIR}/model-locks"
+mkdir -p "$LOCK_DIR" 2>/dev/null
+
+INPUT=$(cat)
+
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null)
+[ "$SESSION_ID" = "unknown" ] && exit 0
+
+# Resolve the current model. PostToolUse payload rarely has it directly, so
+# read the last assistant turn from the transcript for its "model" field.
+MODEL=""
+TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+if [ -n "$TRANSCRIPT" ] && [ -r "$TRANSCRIPT" ]; then
+  MODEL=$(tac "$TRANSCRIPT" 2>/dev/null \
+          | grep -m1 '"model"' \
+          | jq -r '.message.model // .model // empty' 2>/dev/null)
+fi
+
+# Fallback: environment variable (used by some wrappers and tests).
+if [ -z "$MODEL" ] && [ -n "${CLAUDE_MODEL:-}" ]; then
+  MODEL="$CLAUDE_MODEL"
+fi
+
+# If we still do not know the model, do nothing — no false positives.
+[ -z "$MODEL" ] && exit 0
+
+LOCK_FILE="${LOCK_DIR}/${SESSION_ID}.model"
+
+if [ ! -s "$LOCK_FILE" ]; then
+  printf '%s\n' "$MODEL" > "$LOCK_FILE"
+  exit 0
+fi
+
+LOCKED=$(cat "$LOCK_FILE" 2>/dev/null)
+if [ -n "$LOCKED" ] && [ "$LOCKED" != "$MODEL" ]; then
+  echo "⚠ model-version-lock: $LOCKED → $MODEL (session $SESSION_ID)" >&2
+  echo "  Use /model to switch intentionally. Silent migrations (#49541) change token accounting and quality." >&2
+  # Update the lock so we do not emit again for the same transition this
+  # session. Users who want to see every transition can remove this line.
+  printf '%s\n' "$MODEL" > "$LOCK_FILE"
+fi
+
+exit 0

package/examples/move-delete-sequence-guard.sh

@@ -20,6 +20,18 @@
 
 set -euo 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-move-delete-sequence-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [move-delete-sequence-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
@@ -33,10 +45,29 @@ fi
 # Pattern: mv <src> <dst> [&&;||] rm [-rf] <target>
 # We check if the rm target is a parent of, or the same as, the mv source
 
+# The extraction below used grep -oP, which is GNU-only. BSD grep (macOS)
+# rejects -P outright, so both variables came back empty, and the two [ -z ]
+# checks under this block read that as "nothing to compare" and exited 0 —
+# the guard was off on macOS with no sign of it. Keep the GNU path exactly as
+# it was and add an equivalent for platforms without PCRE.
+if echo x | grep -qP x 2>/dev/null; then HAS_PCRE=1; else HAS_PCRE=0; fi
+
+# Reads a command line on stdin, prints the first argument after $1 and its flags.
+# \b and \K have no POSIX equivalent, so the fallback matches the command word
+# with its leading boundary and strips that prefix afterwards.
+extract_operand() {
+    if [ "$HAS_PCRE" = 1 ]; then
+        grep -oP "\\b$1\\s+(-[a-zA-Z]+\\s+)*\\K\\S+" 2>/dev/null || true
+    else
+        grep -oE "(^|[^a-zA-Z])$1[[:space:]]+(-[a-zA-Z]+[[:space:]]+)*[^[:space:]]+" 2>/dev/null \
+            | sed -E "s/^[^a-zA-Z]?$1[[:space:]]+(-[a-zA-Z]+[[:space:]]+)*//" || true
+    fi
+}
+
 # Get all mv source paths (first arg after mv and optional flags)
-MV_SOURCES=$(echo "$COMMAND" | grep -oP '\bmv\s+(-[a-zA-Z]+\s+)*\K\S+' 2>/dev/null || true)
+MV_SOURCES=$(echo "$COMMAND" | extract_operand mv)
 # Get all rm targets
-RM_TARGETS=$(echo "$COMMAND" | grep -oP '\brm\s+(-[a-zA-Z]+\s+)*\K\S+' 2>/dev/null || true)
+RM_TARGETS=$(echo "$COMMAND" | extract_operand rm)
 
 [ -z "$MV_SOURCES" ] && exit 0
 [ -z "$RM_TARGETS" ] && exit 0

package/examples/multi-file-plan-routing-gate.sh

@@ -0,0 +1,192 @@
+#!/bin/bash
+# multi-file-plan-routing-gate.sh — Refuse Write/Edit when the current session
+# has touched N or more distinct files without a written plan, route the
+# work through plan-mode before further writes land.
+#
+# Solves: #60506 — supplier-side recommendation #7 in the model's first-person
+# self-report:
+#
+#   "Automatic routing of three-or-more-file changes into a plan-mode path.
+#    Currently I can sprawl across the codebase without writing a plan first.
+#    The hook should refuse the third file-touching Write until a plan exists,
+#    and then enforce the plan as the contract for the remaining touches."
+#
+# This is the seventh and final operator-side implementation of the seven
+# recommendations Semih extracted from claude-opus-4-7's self-report. The
+# preceding six are shipped or in PR:
+#
+#   1. Chain templates as architectural rules → CLAUDE.md hook frameworks
+#   2. Drift detector (3-correction repeat)   → same-correction-arrest.sh
+#   3. Failure-mode re-injection at Write     → claude-md-reinjector.sh
+#   4. Closure-word verification gate         → closure-word-verify-gate.sh
+#   5. Evidence requirements for "tested"     → evidence-claim-gate.sh (PR #256)
+#   6. Apology weighting at training time     → supplier-only
+#   7. THIS HOOK — plan-mode routing for 3+ file changes
+#
+# HOW IT WORKS:
+#   1. Tracks distinct file_path values per session in a small state file.
+#   2. On each PreToolUse Write/Edit/MultiEdit, adds the file_path to the
+#      session's set.
+#   3. When the count reaches CC_PLAN_GATE_THRESHOLD (default 3), checks
+#      for the presence of a plan file at $PLAN_DIR/<session>.md.
+#   4. If no plan file exists, refuses the Write with exit 2 + system reminder
+#      asking the assistant to write the plan first.
+#   5. Once the plan file appears, subsequent writes pass through silently.
+#   6. Stale session state (older than 7 days) is purged automatically.
+#
+# DESIGN PRINCIPLE: don't block the work, route it. The hook does not
+# prevent multi-file changes; it requires that they be planned before being
+# executed. The plan file is the contract; the writes are the contract's
+# fulfillment. The arrest happens at the *third* file (configurable), not
+# the first — single-file and two-file changes are common and not the
+# failure mode #60506 is describing.
+#
+# Related Issues:
+#   #60506 (@zean89,   2026-05-19) — original report, recommendation 7
+#   #60226 (@suwayama, 2026-05-18) — recognition-without-arrest framework
+#   #60177 (@mike-prokhorov)       — twelve days, fifty-one commits, no plan
+#
+# TRIGGER: PreToolUse
+# MATCHER: Write|Edit|MultiEdit
+#
+# CONFIGURATION (environment variables):
+#   CC_PLAN_GATE_THRESHOLD     default 3 — file count that triggers the gate
+#   CC_PLAN_GATE_STATE_DIR     default /tmp/cc-plan-gate
+#   CC_PLAN_GATE_PLAN_DIR      default .claude/plans
+#   CC_PLAN_GATE_DISABLE       set to "1" to disable the gate entirely
+#   CC_PLAN_GATE_STATE_TTL     default 7 (days) — stale state cleanup window
+#
+# USAGE (settings.json):
+#   {
+#     "hooks": {
+#       "PreToolUse": [{
+#         "matcher": "Write|Edit|MultiEdit",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/multi-file-plan-routing-gate.sh"
+#         }]
+#       }]
+#     }
+#   }
+
+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-multi-file-plan-routing-gate-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [multi-file-plan-routing-gate]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+[ "${CC_PLAN_GATE_DISABLE:-0}" = "1" ] && exit 0
+
+# OPT-IN: this gate BLOCKS the 3rd+ file Write/Edit in a session when no plan
+# file exists. Ordinary multi-file work (refactors, features touching 3+ files)
+# would be arrested by default, so it is off unless explicitly enabled.
+# Set CC_PLAN_GATE_ENABLE=1 to turn it on.
+[ "${CC_PLAN_GATE_ENABLE:-0}" = "1" ] || exit 0
+
+INPUT=$(cat 2>/dev/null || true)
+[ -z "$INPUT" ] && exit 0
+
+THRESHOLD="${CC_PLAN_GATE_THRESHOLD:-3}"
+STATE_DIR="${CC_PLAN_GATE_STATE_DIR:-/tmp/cc-plan-gate}"
+PLAN_DIR="${CC_PLAN_GATE_PLAN_DIR:-.claude/plans}"
+TTL_DAYS="${CC_PLAN_GATE_STATE_TTL:-7}"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+
+# Stale state cleanup. Purge session files older than TTL_DAYS.
+find "$STATE_DIR" -type f -mtime "+${TTL_DAYS}" -delete 2>/dev/null || true
+
+# Extract session_id and file_path from input.
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '
+    .session_id //
+    .stop_input.session_id //
+    .transcript[-1].session_id //
+    "default"
+' 2>/dev/null)
+[ -z "$SESSION_ID" ] && SESSION_ID="default"
+
+# Sanitize session_id for filename use
+SAFE_SESSION=$(printf '%s' "$SESSION_ID" | tr -c '[:alnum:]_-' '_' | head -c 64)
+
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '
+    .tool_input.file_path //
+    empty
+' 2>/dev/null)
+
+# No file_path → nothing to track (e.g. MultiEdit without path, fall back
+# to tool_input.file as a fallback)
+[ -z "$FILE_PATH" ] && FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file // empty' 2>/dev/null)
+[ -z "$FILE_PATH" ] && exit 0
+
+STATE_FILE="$STATE_DIR/${SAFE_SESSION}.files"
+
+# Add file_path to the session's set (deduplicated).
+touch "$STATE_FILE"
+if ! grep -Fxq "$FILE_PATH" "$STATE_FILE" 2>/dev/null; then
+    echo "$FILE_PATH" >> "$STATE_FILE"
+fi
+
+# Count distinct files touched this session.
+FILE_COUNT=$(wc -l < "$STATE_FILE" 2>/dev/null | tr -d ' ')
+FILE_COUNT="${FILE_COUNT:-0}"
+
+# Below threshold → nothing to gate.
+if [ "$FILE_COUNT" -lt "$THRESHOLD" ]; then
+    exit 0
+fi
+
+# At-or-above threshold. Is there a plan file for this session?
+PLAN_FILE="$PLAN_DIR/${SAFE_SESSION}.md"
+PLAN_FILE_ALT="$PLAN_DIR/plan-${SAFE_SESSION}.md"
+PLAN_FILE_GENERIC="$PLAN_DIR/plan.md"
+
+if [ -f "$PLAN_FILE" ] || [ -f "$PLAN_FILE_ALT" ] || [ -f "$PLAN_FILE_GENERIC" ]; then
+    # Plan exists — work has been routed, allow.
+    exit 0
+fi
+
+# No plan. Refuse the Write/Edit and ask the assistant to write a plan.
+cat >&2 <<EOF
+<system-reminder>
+MULTI-FILE CHANGE WITHOUT A PLAN — this session has now touched $FILE_COUNT
+distinct files via Write/Edit/MultiEdit, and no plan file exists at
+$PLAN_FILE.
+
+This is the failure mode documented in #60506 (recommendation 7): the model
+sprawls across the codebase without writing a plan first, and the resulting
+changes are scattered, partially-wired, or contradict each other. The cost
+of an unplanned multi-file change lands on the operator at review time.
+
+The files touched so far in this session:
+$(sed 's/^/  - /' "$STATE_FILE" 2>/dev/null | head -20)
+
+Before the next Write/Edit lands, do one of the following:
+
+  1. Write a plan to $PLAN_FILE that lists the goal, the files involved,
+     the order of changes, and the verification step for each file. Once
+     the plan file exists, this gate auto-clears and writes proceed silently.
+
+  2. If the changes are unrelated and a unified plan is not appropriate,
+     split the work across separate sessions — one task per session, gate
+     resets at session end (TTL 7 days).
+
+  3. If this is a refactor where multi-file scope was inherent from the
+     start, the plan can be one or two paragraphs — the gate's purpose
+     is to require explicit forethought, not extensive documentation.
+
+To disable this gate for design discussions, retrospectives, or sessions
+where multi-file scope is not the failure mode you are guarding against,
+set CC_PLAN_GATE_DISABLE=1 in your environment. The threshold can be
+raised via CC_PLAN_GATE_THRESHOLD (default 3).
+</system-reminder>
+EOF
+
+exit 2