cc-safe-setup 29.7.0 → 30.0.4

package/examples/quoted-flag-approver.sh

@@ -10,7 +10,7 @@
 # trigger a confirmation prompt even when they match allowlist patterns.
 #
 # This PermissionRequest hook auto-approves these prompts when:
-# 1. The base command is in a safe list
+# 1. Every command position is in a safe list
 # 2. The only "issue" is quoted characters in flag values
 #
 # TRIGGER: PermissionRequest
@@ -25,6 +25,25 @@
 #     }]
 #   }
 # }
+#
+# Fixed 2026-08-03. The safe list held bare command *words* — `git`, `curl`,
+# `chmod`, `sed`, `node`, `python3`, `npx` — and a word says nothing about what
+# the command does. `git commit -m "fix"` and `git push --force origin main`
+# have the same first word.
+#
+# Measured against the shipped copy, over 20 destructive or credential-reading
+# commands with no separator in them at all: **15 were approved**, among them
+# `git push --force`, `git reset --hard`, `git clean -fdx`, `chmod -R 777 /`,
+# `curl … | sh`, `node -e '…rmSync…'` and `cat ~/.aws/credentials`.
+#
+# This is a different defect from the first-command-position one repaired in
+# #937/#940/#941/#942/#943/#947, and mixing the two would produce a number that
+# looks right and is not: nothing here was hiding past a separator. The
+# granularity of the list was the problem. (The first-position defect was here
+# too, and is fixed in the same pass.)
+#
+# Known limit: quotes are not parsed when splitting, so a separator inside a
+# quoted string ends a segment early. That errs toward fewer approvals.
 
 INPUT=$(cat)
 
@@ -36,16 +55,86 @@ echo "$MESSAGE" | grep -qi "quoted characters in flag" || exit 0
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0
 
-# Safe base commands — customize for your project
-SAFE_COMMANDS="git|npm|npx|bun|yarn|pnpm|docker|make|cargo|go|pip|python3|node|tsc|eslint|prettier|jest|vitest|pytest|curl|wget|rsync|tar|zip|unzip|cp|mv|mkdir|cat|echo|grep|find|ls|chmod|sed|awk"
+# A substitution or backtick carries a command no string-level read can see.
+# This hook is about quoted flag values, not substitution, so it refuses them.
+case "$COMMAND" in
+    *'$('*|*'`'*) exit 0 ;;
+esac
+
+# Command words that carry no destructive form of their own. Anything that
+# takes code as an argument (`node -e`, `python3 -c`, `npx`) or fetches and runs
+# (`curl`, `wget`) is deliberately absent: for those the word says nothing.
+cc_base_ok() {
+    case "$1" in
+        cat|head|tail|less|more|wc|file|stat|du|df|ls|tree|\
+        which|whereis|type|realpath|readlink|basename|dirname|\
+        grep|rg|ag|ack|sort|uniq|tr|cut|column|nl|rev|awk|\
+        echo|printf|true|false|pwd|date|uname|hostname|whoami|id|\
+        jq|yq|cd|\
+        tsc|eslint|prettier|jest|vitest|pytest)
+            return 0 ;;
+    esac
+    return 1
+}
+
+# Build tool subcommands that neither destroy history nor run fetched code.
+# One line on purpose: inside single quotes a trailing backslash is a literal
+# backslash-newline, not a continuation, and the pattern silently stops matching.
+CC_SUBCMD_RE='^[[:space:]]*(git[[:space:]]+(status|log|diff|show|add|commit|branch|remote|describe|rev-parse|blame|shortlog|ls-files|ls-tree|fetch|stash[[:space:]]+(list|push|save))|npm[[:space:]]+(test|run|ci|ls|view|outdated)|yarn[[:space:]]+(test|run|info|why)|pnpm[[:space:]]+(test|run|list|why)|bun[[:space:]]+(test|run)|cargo[[:space:]]+(build|test|check|fmt|clippy|tree)|go[[:space:]]+(build|test|vet|fmt|list)|docker[[:space:]]+(ps|images|logs|inspect|version|info)|make[[:space:]]+[A-Za-z0-9_.-]+|pip[[:space:]]+(list|show|freeze)|python3[[:space:]]+-m[[:space:]]+(pytest|unittest|pip[[:space:]]+(list|show|freeze)))([[:space:]]|$)'
+
+cc_subcommand_ok() {
+    printf '%s' "$1" | grep -qE "$CC_SUBCMD_RE"
+}
+
+cc_segment_base() {
+    printf '%s' "$1" \
+        | sed -E 's/^[[:space:]]+//; s/^([A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+)*//' \
+        | awk '{print $1}' \
+        | sed 's|.*/||'
+}
+
+# `git branch` reads; `git branch -D main` deletes one. Same first two words.
+CC_GIT_DESTRUCTIVE_RE='^[[:space:]]*git[[:space:]]+(branch|tag)[[:space:]]+-([dDmM]|-delete|-move)([[:space:]]|$)'
+
+cc_segment_ok() {
+    local seg="$1" base
+    base=$(cc_segment_base "$seg")
+    [ -z "$base" ] && return 1
+
+    if [ "$base" = "find" ]; then
+        printf '%s' "$seg" \
+            | grep -qE '(^|[[:space:]])-(delete|exec|execdir|ok|okdir|fprintf?|fls|fprint0)([[:space:]]|$)' \
+            && return 1
+        return 0
+    fi
+    if [ "$base" = "sed" ]; then
+        printf '%s' "$seg" | grep -qE '(^|[[:space:]])-[a-zA-Z]*i' && return 1
+        return 0
+    fi
+
+    cc_base_ok "$base" && return 0
+    printf '%s' "$seg" | grep -qE "$CC_GIT_DESTRUCTIVE_RE" && return 1
+    cc_subcommand_ok "$seg" && return 0
+    return 1
+}
+
+# A redirection writes a file, whatever the command word says.
+case "$COMMAND" in
+    *'>'*) exit 0 ;;
+esac
 
-# Extract base command (first word, ignoring env vars and path)
-BASE_CMD=$(echo "$COMMAND" | sed 's/^[A-Z_]*=[^ ]* //' | awk '{print $1}' | sed 's|.*/||')
+IDX=0
+while IFS= read -r SEG; do
+    SEG="${SEG#"${SEG%%[![:space:]]*}"}"
+    SEG="${SEG%"${SEG##*[![:space:]]}"}"
+    [ -z "$SEG" ] && continue
+    cc_segment_ok "$SEG" || exit 0
+    IDX=$((IDX + 1))
+done <<EOF
+$(printf '%s' "$COMMAND" | tr ';&|' '\n\n\n')
+EOF
 
-if echo "$BASE_CMD" | grep -qE "^($SAFE_COMMANDS)$"; then
-  echo '{"permissionDecision":"allow"}'
-  exit 0
-fi
+[ "$IDX" -eq 0 ] && exit 0
 
-# Unknown command — let the prompt through
+echo '{"permissionDecision":"allow"}'
 exit 0

package/examples/rails-migration-guard.sh

@@ -19,6 +19,18 @@
 #
 # 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-rails-migration-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [rails-migration-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)
 

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