cc-safe-setup 29.8.0 → 30.0.4

package/examples/read-budget-guard.sh

@@ -25,6 +25,18 @@
 #   CC_READ_BUDGET=100    — max unique files per session (default: 100)
 #   CC_READ_WARN=50       — warn threshold (default: 50)
 
+# 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-read-budget-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [read-budget-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

package/examples/read-loop-detector.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# ================================================================
+# read-loop-detector.sh — Surface same-file Read loops within a session
+# ================================================================
+# PURPOSE:
+#   When Claude Code decides to write a memory file (or any output)
+#   it sometimes re-reads source files it already read earlier in the
+#   same session, looping 10+ times before finally writing. The
+#   "File unchanged since last read" cache hint logs through the
+#   harness but does not short-circuit the model's decision, so the
+#   loop bills tokens for round-trips that return identical content.
+#
+#   This hook surfaces the loop while it's happening so the user can
+#   interrupt with `escape` and prompt the model to write directly.
+#
+#   Reference: https://github.com/anthropics/claude-code/issues/53578
+#              https://github.com/anthropics/claude-code/issues/40123
+#
+# TRIGGER: PostToolUse  MATCHER: "Read"
+#
+# CONFIG:
+#   CC_READ_LOOP_THRESHOLD=3              (warn at this many reads of same path)
+#   CC_READ_LOOP_LOG_DIR=/tmp             (per-session counter log location)
+#   CC_READ_LOOP_DISABLE=                 (set to 1 to disable)
+# ================================================================
+
+[ "${CC_READ_LOOP_DISABLE:-}" = "1" ] && exit 0
+
+INPUT=$(cat)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null)
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+[ "$TOOL_NAME" != "Read" ] && exit 0
+[ -z "$FILE_PATH" ] && exit 0
+
+THRESHOLD="${CC_READ_LOOP_THRESHOLD:-3}"
+LOG_DIR="${CC_READ_LOOP_LOG_DIR:-/tmp}"
+LOG_FILE="$LOG_DIR/cc-read-loop-${SESSION_ID}.log"
+
+# Defensive: ensure threshold is a positive integer
+case "$THRESHOLD" in
+    ''|*[!0-9]*) THRESHOLD=3 ;;
+esac
+
+# Append this read; one path per line for grep -c
+printf '%s\n' "$FILE_PATH" >> "$LOG_FILE" 2>/dev/null || exit 0
+
+# Count occurrences of this exact path (literal string, not regex)
+COUNT=$(grep -cFx "$FILE_PATH" "$LOG_FILE" 2>/dev/null || echo 0)
+
+if [ "$COUNT" -ge "$THRESHOLD" ]; then
+    echo "NOTE: Read on $FILE_PATH has fired $COUNT times this session." >&2
+    echo "If the agent is preparing to write a memory or summary file, the model may be re-verifying context it already has." >&2
+    echo "To break the loop: escape and prompt 'Stop reading. Write the file now using existing context.'" >&2
+    echo "Disable this hint: export CC_READ_LOOP_DISABLE=1" >&2
+fi
+
+exit 0

package/examples/read-once-guard.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# read-once-guard.sh — Warn when Claude re-reads a file already in context
+#
+# Inspired by the token waste pattern where Claude reads the same file
+# multiple times in a session, consuming tokens without gaining new info.
+# Studies show this can waste 30%+ of session tokens.
+#
+# HOW IT WORKS:
+#   Tracks which files have been read in the current session.
+#   If a file is read again and hasn't been modified since the last read,
+#   warns the user (but allows the read to proceed).
+#
+# TRIGGER: PreToolUse  MATCHER: "Read"
+#
+# CONFIGURATION:
+#   CC_READ_ONCE_ACTION=warn|block  (default: warn)
+#   CC_READ_ONCE_MAX=3              (warn/block after N re-reads of same file)
+
+# 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-read-once-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [read-once-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+[[ -z "$FILE_PATH" ]] && exit 0
+
+# Normalize path
+FILE_PATH=$(realpath "$FILE_PATH" 2>/dev/null || echo "$FILE_PATH")
+
+STATE_DIR="/tmp/cc-read-once"
+mkdir -p "$STATE_DIR"
+
+ACTION="${CC_READ_ONCE_ACTION:-warn}"
+MAX_READS="${CC_READ_ONCE_MAX:-3}"
+
+# Session ID based on parent process
+SESSION_ID="${CC_SESSION_ID:-$$}"
+STATE_FILE="$STATE_DIR/reads-${SESSION_ID}.log"
+
+# Get current file mtime
+CURRENT_MTIME=$(stat -c %Y "$FILE_PATH" 2>/dev/null || echo "0")
+
+# Check if this file was already read
+READ_COUNT=0
+LAST_MTIME="0"
+if [[ -f "$STATE_FILE" ]]; then
+  while IFS=$'\t' read -r path mtime count; do
+    if [[ "$path" == "$FILE_PATH" ]]; then
+      READ_COUNT=$count
+      LAST_MTIME=$mtime
+      break
+    fi
+  done < "$STATE_FILE"
+fi
+
+# If file was modified since last read, reset counter
+if [[ "$CURRENT_MTIME" != "$LAST_MTIME" && "$LAST_MTIME" != "0" ]]; then
+  READ_COUNT=0
+fi
+
+# Increment read count
+READ_COUNT=$((READ_COUNT + 1))
+
+# Update state file (use tab as delimiter to avoid path conflicts)
+ESCAPED_PATH=$(printf '%s' "$FILE_PATH" | sed 's/[&/\]/\\&/g')
+if grep -q "^${ESCAPED_PATH}	" "$STATE_FILE" 2>/dev/null; then
+  # Replace the line for this file
+  grep -v "^${ESCAPED_PATH}	" "$STATE_FILE" > "${STATE_FILE}.tmp"
+  echo -e "${FILE_PATH}\t${CURRENT_MTIME}\t${READ_COUNT}" >> "${STATE_FILE}.tmp"
+  mv "${STATE_FILE}.tmp" "$STATE_FILE"
+else
+  echo -e "${FILE_PATH}\t${CURRENT_MTIME}\t${READ_COUNT}" >> "$STATE_FILE"
+fi
+
+# Check threshold
+if [[ "$READ_COUNT" -gt "$MAX_READS" ]]; then
+  if [[ "$ACTION" == "block" ]]; then
+    echo "⚠️  BLOCKED: ${FILE_PATH} has been read ${READ_COUNT} times without changes." >&2
+    echo "   The file content is already in your context. Use what you already know." >&2
+    exit 2
+  else
+    echo "⚠️  NOTE: Re-reading ${FILE_PATH} (${READ_COUNT}x). File hasn't changed since last read." >&2
+    echo "   Consider using the content already in your context to save tokens." >&2
+  fi
+fi
+
+exit 0

package/examples/read-only-mode.sh

@@ -33,6 +33,18 @@
 # TRIGGER: PreToolUse  MATCHER: "Write|Edit|NotebookEdit|Bash"
 
 # Only active when CLAUDE_READONLY=1
+# 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-read-only-mode-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [read-only-mode]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 [[ "${CLAUDE_READONLY:-}" != "1" ]] && exit 0
 
 INPUT=$(cat)

package/examples/record-read-coverage.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# ================================================================
+# record-read-coverage.sh — Record how much of each file was read
+# ================================================================
+# PURPOSE:
+#   Two shipped hooks need to know whether a file was read before it
+#   is written, and neither could work without this recorder:
+#
+#     read-before-edit.sh      — documents "Requires companion PostToolUse
+#                                hook to record Read events" and no such
+#                                hook shipped, so its NOTE fired on every
+#                                single Edit (a warning that always fires
+#                                carries no information)
+#     write-overwrite-confirm.sh — could only compare sizes, so an overwrite
+#                                that keeps the line count was invisible
+#
+# WHY COVERAGE AND NOT JUST THE PATH:
+#   Issue #78273: the agent read FIVE lines of a hand-built file, confirmed
+#   it had content, then overwrote the whole file with its own analysis.
+#   The original was not in git and was unrecoverable. A path-only record
+#   would have said "this file was read" and the write would have passed.
+#   What matters is whether the part being destroyed was ever seen.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "Read"
+#
+# RECORD FORMAT (tab separated, appended):
+#   <absolute path>\t<offset>\t<limit>\t<total lines when read>
+#
+#   offset/limit are 0 when the Read carried no such argument, which the
+#   Read tool treats as "from the top, up to its own default cap".
+# ================================================================
+
+set -uo pipefail
+
+READ_LOG="${CC_READ_LOG:-/tmp/cc-read-files}"
+
+INPUT=$(cat)
+
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || true)
+[ "$TOOL" = "Read" ] || exit 0
+
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)
+[ -n "$FILE" ] || exit 0
+
+# Only real files can be covered. A path that is gone by the time the
+# PostToolUse hook runs tells us nothing useful, so record nothing.
+[ -f "$FILE" ] || exit 0
+
+OFFSET=$(printf '%s' "$INPUT" | jq -r '.tool_input.offset // 0' 2>/dev/null || echo 0)
+LIMIT=$(printf '%s' "$INPUT" | jq -r '.tool_input.limit // 0' 2>/dev/null || echo 0)
+case "$OFFSET" in ''|*[!0-9]*) OFFSET=0 ;; esac
+case "$LIMIT"  in ''|*[!0-9]*) LIMIT=0  ;; esac
+
+TOTAL=$(wc -l < "$FILE" 2>/dev/null || echo 0)
+case "$TOTAL" in ''|*[!0-9]*) TOTAL=0 ;; esac
+
+# The log is advisory state shared between separate hook processes, so a
+# failed write must never break the user's Read. Everything here is best effort.
+printf '%s\t%s\t%s\t%s\n' "$FILE" "$OFFSET" "$LIMIT" "$TOTAL" >> "$READ_LOG" 2>/dev/null || true
+
+# Keep the log from growing without bound across a long session. 2000 lines is
+# far more than any single session needs and costs nothing to carry.
+if [ -f "$READ_LOG" ]; then
+  LINES=$(wc -l < "$READ_LOG" 2>/dev/null || echo 0)
+  case "$LINES" in ''|*[!0-9]*) LINES=0 ;; esac
+  if [ "$LINES" -gt 2000 ]; then
+    tail -n 1000 "$READ_LOG" > "$READ_LOG.trim" 2>/dev/null &&
+      mv "$READ_LOG.trim" "$READ_LOG" 2>/dev/null || true
+  fi
+fi
+
+exit 0

package/examples/redirect-fragment-warner.sh

@@ -0,0 +1,149 @@
+#!/bin/bash
+# redirect-fragment-warner.sh — Warn / block Bash commands using `2>&1`
+# (Cluster 25 candidate, axis 25C — permission-engine `&` fragmentation hang)
+#
+# Background:
+#   A Bash tool command containing `2>&1` triggers a multi-minute spinner
+#   hang in the permission-evaluation layer. Token usage increments
+#   continuously during the hang — implying a model-reinvocation loop
+#   rather than an idle wait. The command itself eventually executes
+#   correctly; the hang is purely in the permission step.
+#
+#   Hypothesised root cause: the permission engine splits Bash commands on
+#   shell operators including `&`. The `&` inside `2>&1` fragments the
+#   command into segments that are validated independently. That
+#   fragmentation drops the command into a re-validation loop where each
+#   fragment is re-checked, and the loop re-invokes the model on each
+#   iteration — which is the source of the climbing token usage during
+#   the visible hang.
+#
+#   Anchor case:
+#     #64334 — Bash command with 2>&1 causes ~12min spinner hang with
+#              token usage climbing during the stall
+#
+#   Cluster 25 sub-axes (4 + 1 overlap):
+#     25A — late/empty tool-result delivery (substrate)
+#     25B — echo-probe spam compensation (PR #556 shipped)
+#     25C — 2>&1 permission-engine fragmentation hang (this hook)
+#     25D — compounding cost (downstream of 25B/25C)
+#     25E — empty-result triggered fabrication (Cluster 22 overlap)
+#
+#   This hook is a PreToolUse hook on Bash that:
+#     - Matches `2>&1` in the command string (the trigger pattern)
+#     - Warns with a rewrite suggestion (default) — `CC_BLOCK_2_REDIRECT=1`
+#       to block by default for users who have been bitten once
+#     - Allows operator override via `# ACCEPT 2>&1` marker in the command
+#
+#   The cost-impact justification (12-min hang with token billing climbing)
+#   supports defaulting to warn rather than silent allow, and supports the
+#   easy-toggle to block-by-default for users who have hit this.
+#
+# When this hook does NOT warn / block:
+#   - CC_REDIRECT_FRAGMENT_DISABLE=1     — never warn or block
+#   - CC_REDIRECT_FRAGMENT_QUIET=1       — silent (no stderr output)
+#   - The command does not contain `2>&1`
+#   - The command contains `# ACCEPT 2>&1` marker (operator override)
+#
+# When this hook BLOCKS (exit 2):
+#   - CC_BLOCK_2_REDIRECT=1 is set
+#   - the command contains `2>&1`
+#   - the command does not contain the `# ACCEPT 2>&1` override marker
+#
+# Hook config (settings.json):
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/redirect-fragment-warner.sh" }]
+#     }]
+#   }
+# }
+#
+# Env vars:
+#   CC_REDIRECT_FRAGMENT_DISABLE=1  — never warn or block
+#   CC_REDIRECT_FRAGMENT_QUIET=1    — silent (process but never write stderr)
+#   CC_BLOCK_2_REDIRECT=1           — block (exit 2) instead of warn
+
+set -u
+
+if [ "${CC_REDIRECT_FRAGMENT_DISABLE:-}" = "1" ]; then
+    exit 0
+fi
+
+INPUT=$(cat 2>/dev/null || true)
+CMD=""
+if command -v jq >/dev/null 2>&1 && [ -n "$INPUT" ]; then
+    CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+fi
+
+if [ -z "$CMD" ]; then
+    exit 0
+fi
+
+# Detect `2>&1` in the command (the trigger pattern)
+if ! printf '%s\n' "$CMD" | grep -q '2>&1'; then
+    exit 0
+fi
+
+# Operator override: `# ACCEPT 2>&1` marker disables the warning for this call
+if printf '%s\n' "$CMD" | grep -Eq '#[[:space:]]*ACCEPT[[:space:]]+2>&1'; then
+    exit 0
+fi
+
+# Build the rewrite suggestion: strip `2>&1` and keep the rest of the command
+# (best-effort — the operator should review)
+SUGGESTED=$(printf '%s\n' "$CMD" | sed 's/[[:space:]]*2>&1//g')
+
+if [ "${CC_REDIRECT_FRAGMENT_QUIET:-}" = "1" ]; then
+    if [ "${CC_BLOCK_2_REDIRECT:-}" = "1" ]; then
+        exit 2
+    fi
+    exit 0
+fi
+
+if [ "${CC_BLOCK_2_REDIRECT:-}" = "1" ]; then
+    cat >&2 <<EOF
+
+BLOCKED: Bash command contains \`2>&1\`.
+
+Pattern detected: the permission engine splits Bash commands on shell
+operators including \`&\`. The \`&\` inside \`2>&1\` fragments the command
+into segments that are validated independently, dropping the command
+into a re-validation loop where each fragment is re-checked and the
+loop re-invokes the model on each iteration. This produces the
+multi-minute spinner hang with token usage climbing observed in #64334
+(Cluster 25 axis 25C).
+
+What to do instead:
+  bad:  ${CMD}
+  good: ${SUGGESTED}
+
+If you genuinely need stderr captured, redirect it explicitly to a file
+or to a separate stream the model reads separately.
+
+Background: gist.github.com/yurukusa/5881286479969d5bac0323511dc33ab2
+Anchor issue: github.com/anthropics/claude-code/issues/64334
+
+To override once: include "# ACCEPT 2>&1" in the command.
+To disable: export CC_REDIRECT_FRAGMENT_DISABLE=1
+To downgrade to warn-only: unset CC_BLOCK_2_REDIRECT
+
+EOF
+    exit 2
+fi
+
+cat >&2 <<EOF
+
+NOTICE: Bash command contains \`2>&1\`, which can trigger a multi-minute
+permission-engine hang with token billing climbing during the stall
+(Cluster 25 axis 25C, anchor #64334).
+
+Suggested rewrite:
+  ${SUGGESTED}
+
+To block this pattern by default: export CC_BLOCK_2_REDIRECT=1
+To override per-call: include "# ACCEPT 2>&1" in the command.
+
+EOF
+
+exit 0

package/examples/redis-flushall-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-redis-flushall-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [redis-flushall-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/redundant-read-blocker.sh

@@ -0,0 +1,132 @@
+#!/bin/bash
+# redundant-read-blocker.sh — Prevent the model from re-reading files it has
+# already read recently in the same session.
+#
+# Solves: #60283 — "Excessive token consumption — task halted mid-execution
+# with zero output (macOS)" — where Claude re-read in-context files 10+ times
+# before being interrupted, with zero deliverable. Confirmed at scale by
+# yurukusa/quota-leakage-audit.sh — across multiple sessions on a single
+# operator, individual files were observed Read 3-5 times even when their
+# content had not changed.
+#
+# Background:
+#   https://gist.github.com/yurukusa/303431f8e32fed5081b6b2b89712c991 (cluster)
+#   https://gist.github.com/yurukusa/0dbe97df416c53c43dd699b72f439060 (audit)
+#
+# How it works:
+#   Maintains a per-session set of recently-read files at
+#   $STATE_DIR/<session>/reads.log. On each PreToolUse for Read, checks if
+#   the file was already read within the configured window of tool calls.
+#   If so, emits a system reminder advising the model to use what's already
+#   in context, and (in strict mode) refuses the call.
+#
+#   The hook respects mtime: if the file has been modified since the previous
+#   read, it is NOT considered redundant and the new read passes.
+#
+# TRIGGER: PreToolUse
+# MATCHER: Read
+#
+# CONFIGURATION:
+#   CC_REDUNDANT_READ_WINDOW=20    # how many recent reads to keep tracking
+#   CC_REDUNDANT_READ_THRESHOLD=1  # warn after N prior reads (default 1 = the first re-read of an unchanged file fires)
+#   CC_REDUNDANT_READ_STRICT=0     # 1 = exit 2 (hard block), 0 = stderr warning (default)
+#   CC_REDUNDANT_READ_STATE_DIR    # default /tmp/cc-redundant-read
+#
+# Usage in settings.json:
+#   {
+#     "hooks": {
+#       "PreToolUse": [{
+#         "matcher": "Read",
+#         "hooks": [{
+#           "type": "command",
+#           "command": "~/.claude/hooks/redundant-read-blocker.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-redundant-read-blocker-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [redundant-read-blocker]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat 2>/dev/null || true)
+[ -z "$INPUT" ] && exit 0
+
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ "$TOOL" != "Read" ] && exit 0
+
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // "default"' 2>/dev/null)
+[ -z "$FILE_PATH" ] && exit 0
+
+WINDOW="${CC_REDUNDANT_READ_WINDOW:-20}"
+THRESHOLD="${CC_REDUNDANT_READ_THRESHOLD:-1}"
+STRICT="${CC_REDUNDANT_READ_STRICT:-0}"
+STATE_DIR="${CC_REDUNDANT_READ_STATE_DIR:-/tmp/cc-redundant-read}/$SESSION_ID"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+READS_LOG="$STATE_DIR/reads.log"
+
+# Get current mtime of the target file (may not exist yet, that's fine)
+CUR_MTIME=$(stat -c '%Y' "$FILE_PATH" 2>/dev/null || echo "0")
+
+# Count how many times this path has been read within the window, accounting
+# for mtime: an entry only counts as a "previous read" if the file has NOT
+# been modified since.
+PREVIOUS=0
+LAST_MTIME=""
+if [ -f "$READS_LOG" ]; then
+    # Tail the last N lines, then filter for matching paths
+    while IFS=$'\t' read -r p m; do
+        if [ "$p" = "$FILE_PATH" ]; then
+            # If the recorded mtime equals the current mtime, the file is unchanged
+            if [ "$m" = "$CUR_MTIME" ]; then
+                PREVIOUS=$((PREVIOUS + 1))
+            fi
+        fi
+    done < <(tail -n "$WINDOW" "$READS_LOG" 2>/dev/null)
+fi
+
+# Append this read to the log (always — even on block, since the model may
+# choose to override and we want to track that)
+printf '%s\t%s\n' "$FILE_PATH" "$CUR_MTIME" >> "$READS_LOG"
+
+# Trim log to the window
+tail -n "$WINDOW" "$READS_LOG" > "$READS_LOG.tmp" && mv "$READS_LOG.tmp" "$READS_LOG"
+
+# Decide based on threshold
+if [ "$PREVIOUS" -ge "$THRESHOLD" ]; then
+    cat >&2 <<EOF
+<system-reminder>
+REDUNDANT READ — $FILE_PATH has already been read $PREVIOUS time(s) in this
+session without modification since the last read. The file content is already
+in the conversation context.
+
+If you genuinely need to verify the content, use Grep with a specific pattern
+rather than re-reading the entire file. If you are reading to refresh memory,
+use what is already in context — re-reading consumes input tokens for content
+the model already has.
+
+Background: #60283 (excessive token consumption with re-reads of in-context
+files). Audit: https://gist.github.com/yurukusa/0dbe97df416c53c43dd699b72f439060
+
+To disable this gate: set CC_REDUNDANT_READ_STRICT=0 and CC_REDUNDANT_READ_THRESHOLD
+higher, or remove the hook from settings.json.
+</system-reminder>
+EOF
+    if [ "$STRICT" = "1" ]; then
+        exit 2
+    fi
+fi
+
+exit 0