cc-safe-setup 29.6.40 → 29.8.0

package/examples/broad-find-guard.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# broad-find-guard.sh — Block overly broad find/locate commands that scan the entire home directory
+#
+# Solves: Claude Code running `find $HOME` or `find /` which scans all user files,
+#         triggering OneDrive/iCloud/Dropbox to download synced files (#51010)
+#
+# Detects patterns like:
+#   find / -name "CLAUDE.md"
+#   find ~ -name "*.py"
+#   find $HOME -type f
+#   find /c/Users/username -name "*.md"
+#   locate "CLAUDE.md"
+#
+# Why: On Windows/macOS, cloud sync folders (OneDrive, iCloud, Dropbox) are
+#      under the home directory. A broad `find` traverses them and triggers
+#      downloading of ALL synced files — potentially gigabytes of data.
+#      Claude Code should only search project-scoped directories.
+#
+# Usage: Add to settings.json as a PreToolUse hook
+#
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/broad-find-guard.sh" }]
+#     }]
+#   }
+# }
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+[ -z "$COMMAND" ] && exit 0
+
+# Pattern 1: find starting from root
+if echo "$COMMAND" | grep -qE 'find\s+/\s'; then
+    echo "BLOCKED: find from root (/) scans entire filesystem. Use a project-scoped path instead." >&2
+    exit 2
+fi
+
+# Pattern 2: find starting from home directory (various forms)
+if echo "$COMMAND" | grep -qE 'find\s+(~|\$HOME|/home/[a-zA-Z0-9_]+|/Users/[a-zA-Z0-9_]+|/c/Users/[a-zA-Z0-9_]+)\s'; then
+    echo "BLOCKED: find from home directory scans all user files including cloud sync folders (OneDrive/iCloud/Dropbox). Use a specific project path instead." >&2
+    exit 2
+fi
+
+# Pattern 3: find with -maxdepth 0 or 1 from home is OK (shallow), but deep scans are not
+# This pattern catches find ~ without further path restriction
+if echo "$COMMAND" | grep -qE 'find\s+(~|\$HOME|/home/|/Users/|/c/Users/)\b' && ! echo "$COMMAND" | grep -qE '\-maxdepth\s+[01]'; then
+    echo "BLOCKED: broad find from home directory. Add -maxdepth or use a specific subdirectory to avoid scanning cloud sync folders." >&2
+    exit 2
+fi
+
+# Pattern 4: locate without project-scoping (scans entire DB)
+if echo "$COMMAND" | grep -qE '^\s*locate\s' && ! echo "$COMMAND" | grep -qE 'locate.*--database|locate.*-d\s'; then
+    echo "BLOCKED: locate searches the entire filesystem index. Use find with a specific directory instead." >&2
+    exit 2
+fi
+
+exit 0

package/examples/cache-creation-spike-detector.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# cache-creation-spike-detector.sh — cache_creationスパイクを検知して警告
+# Why: smooshSystemReminderSiblings関数がsystem-reminderを毎ターンtool_result.contentに
+#      折り込むことで、プロンプトキャッシュのプレフィックスが変わり、cache_creationが
+#      数十万トークン単位でスパイクする (#49585)。5xの消費率上昇報告あり (#49593)
+# Event: PostToolUse (全ツール実行後にチェック)
+# Action: cache_creation_input_tokensが閾値を超えた場合に警告
+
+INPUT=$(cat)
+# PostToolUseではusageデータにアクセスできないため、
+# /costコマンド出力のログファイルで累積cache_creationを追跡する
+CACHE_LOG="/tmp/cc-cache-creation-tracker.log"
+THRESHOLD=100000  # 100Kトークン以上でcache_creation警告
+
+# 10回に1回だけチェック（パフォーマンス配慮）
+COUNTER_FILE="/tmp/cache-spike-check-counter"
+COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+[ $((COUNT % 10)) -ne 0 ] && exit 0
+
+# セッション開始からの経過時間をチェック
+SESSION_START=$(stat -c %Y /tmp/cache-spike-check-counter 2>/dev/null || echo "0")
+NOW=$(date +%s)
+ELAPSED=$((NOW - SESSION_START))
+
+# セッション開始10分以内はスキップ（初期キャッシュ構築は正常）
+[ "$ELAPSED" -lt 600 ] && exit 0
+
+echo "INFO: cache_creationスパイク検知hookが動作中。異常なトークン消費を感じたら /cost で確認してください。" >&2
+echo "詳細: https://github.com/anthropics/claude-code/issues/49585" >&2
+exit 0

package/examples/case-insensitive-path-guard.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# case-insensitive-path-guard.sh — Detect path case mismatches on case-insensitive filesystems
+#
+# Solves: Claude Code resolving paths with wrong case on macOS APFS (case-insensitive),
+#   causing rm -rf to destroy unintended directories
+#   - #48792: rm -rf WebstormProjects/ destroyed webstormprojects/ (10 years of work)
+#   - #49102: Same APFS bug, second catastrophic loss in 48 hours
+#
+# How it works:
+#   For rm/mv/cp commands targeting paths under $HOME, resolves the ACTUAL
+#   filesystem path and compares case. If the specified path exists only via
+#   case-insensitive matching (e.g., "Projects" matches "projects/"), blocks
+#   the command because the user likely intended a different directory.
+#
+# Platform: macOS only (APFS case-insensitive is default). On Linux (ext4, case-sensitive),
+#   the guard exits cleanly since case mismatches simply won't resolve.
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
+
+set -euo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Only check destructive commands
+echo "$COMMAND" | grep -qE '\b(rm|mv|cp)\s' || exit 0
+
+# Skip if not macOS (Linux filesystems are case-sensitive by default)
+if [ "$(uname)" != "Darwin" ]; then
+    exit 0
+fi
+
+# Extract target paths from destructive commands
+# Handles: rm -rf path, mv path dest, cp -r path dest
+TARGETS=""
+
+# rm: all non-flag arguments
+if echo "$COMMAND" | grep -qE '\brm\s'; then
+    TARGETS=$(echo "$COMMAND" | grep -oP '\brm\s+(-[a-zA-Z]+\s+)*\K[^\s;&|]+(\s+[^\s;&|]+)*' 2>/dev/null || true)
+fi
+
+# mv: first non-flag argument (source)
+if echo "$COMMAND" | grep -qE '\bmv\s'; then
+    MV_TARGET=$(echo "$COMMAND" | grep -oP '\bmv\s+(-[a-zA-Z]+\s+)*\K\S+' 2>/dev/null || true)
+    TARGETS="$TARGETS $MV_TARGET"
+fi
+
+[ -z "$TARGETS" ] && exit 0
+
+# Expand ~ to $HOME
+TARGETS=$(echo "$TARGETS" | sed "s|~|$HOME|g")
+
+for target in $TARGETS; do
+    # Skip flags
+    echo "$target" | grep -q '^-' && continue
+
+    # Skip safe disposable paths
+    echo "$target" | grep -qE '(node_modules|\.cache|__pycache__|/tmp/|dist/|build/)' && continue
+
+    # Only check paths under home directory (most risk)
+    echo "$target" | grep -qE "^($HOME|~)" || continue
+
+    # Resolve the canonical path using the filesystem
+    # On case-insensitive APFS, /Users/me/Projects resolves even if actual is /Users/me/projects
+    CANONICAL=$(python3 -c "
+import os, sys
+p = os.path.expanduser('$target')
+# Walk up to find the longest existing prefix
+check = p
+while check and not os.path.exists(check):
+    check = os.path.dirname(check)
+if not check:
+    sys.exit(0)
+# Get the real path (canonical case)
+real = os.path.realpath(check)
+# Get the suffix that was beyond the existing part
+suffix = p[len(check):]
+print(real + suffix)
+" 2>/dev/null || echo "")
+
+    [ -z "$CANONICAL" ] && continue
+
+    # Compare: if the specified path differs in case from the canonical path
+    if [ "$target" != "$CANONICAL" ] && [ "${target,,}" = "${CANONICAL,,}" ] 2>/dev/null; then
+        echo "BLOCKED: Case mismatch detected on case-insensitive filesystem" >&2
+        echo "  Specified: $target" >&2
+        echo "  Actual:    $CANONICAL" >&2
+        echo "  On macOS APFS, these resolve to the SAME directory." >&2
+        echo "  This mismatch has caused catastrophic data loss (#48792, #49102)." >&2
+        echo "  Verify the path case matches the actual filesystem before proceeding." >&2
+        exit 2
+    fi
+done
+
+exit 0

package/examples/cjk-punctuation-guard.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# cjk-punctuation-guard.sh — Detect CJK punctuation corruption after Write/Edit
+#
+# Solves: Claude Code's Write and Edit tools silently convert full-width CJK
+#         punctuation to half-width ASCII (，→, 。→. 「→" etc.) without warning.
+#         This corrupts Chinese, Japanese, and Korean text.
+#         (GitHub Issue #50975)
+#
+# How it works:
+#   After Write or Edit, checks if the file contains CJK characters.
+#   If yes, runs git diff to see if any full-width punctuation was replaced
+#   with half-width equivalents in the same commit.
+#
+# TRIGGER: PostToolUse  MATCHER: "Write|Edit"
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.file // empty' 2>/dev/null)
+
+[ -z "$FILE" ] || [ ! -f "$FILE" ] && exit 0
+
+# Only check files that contain CJK characters
+if ! grep -Pq '[\p{Han}\p{Hiragana}\p{Katakana}\p{Hangul}]' "$FILE" 2>/dev/null; then
+    exit 0
+fi
+
+# Check git diff for punctuation changes (full-width → half-width)
+DIFF=$(git diff -- "$FILE" 2>/dev/null)
+[ -z "$DIFF" ] && exit 0
+
+# Detect suspicious patterns: removed full-width, added half-width in same hunk
+# Common corruptions: ，→, 。→. 、→, ：→: ；→; ！→! ？→? 「→" 」→" （→( ）→)
+REMOVED_FW=$(echo "$DIFF" | grep '^-' | grep -Pc '[，。、：；！？「」（）【】『』]' 2>/dev/null || echo 0)
+ADDED_HW=$(echo "$DIFF" | grep '^+' | grep -Pc '[,\.;:!\?\(\)\[\]]' 2>/dev/null || echo 0)
+
+if [ "$REMOVED_FW" -gt 0 ] && [ "$ADDED_HW" -gt 0 ]; then
+    echo "⚠ WARNING: CJK punctuation may have been corrupted in $FILE" >&2
+    echo "  $REMOVED_FW lines with full-width punctuation removed" >&2
+    echo "  $ADDED_HW lines with half-width punctuation added" >&2
+    echo "  Review: git diff -- \"$FILE\"" >&2
+    echo "  Undo:   git checkout -- \"$FILE\"" >&2
+    # Warning only (exit 0), not blocking — the write already happened
+fi
+
+exit 0

package/examples/clipboard-secret-guard.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# clipboard-secret-guard.sh — Block secrets from being copied to clipboard
+#
+# Solves: Claude Code may pipe sensitive data (API keys, tokens, passwords)
+#   to clipboard utilities (pbcopy, xclip, xsel, wl-copy). This leaks
+#   secrets outside the terminal where they persist and may sync to cloud.
+#
+# How it works: PreToolUse hook that detects clipboard commands containing
+#   secret-like patterns. Blocks the operation.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+# CATEGORY: security
+
+INPUT=$(cat)
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$CMD" ] && exit 0
+
+# Check if command pipes to clipboard
+if echo "$CMD" | grep -qiE '(pbcopy|xclip|xsel|wl-copy|clip\.exe)'; then
+    # Check if the piped content looks like it contains secrets
+    if echo "$CMD" | grep -qiE '(api.?key|secret|token|password|passwd|credential|private.?key|Bearer|AWS_|ANTHROPIC_|OPENAI_)'; then
+        echo "BLOCKED: Attempting to copy secret-like content to clipboard." >&2
+        echo "  Clipboard data may sync to cloud or persist after session." >&2
+        exit 2
+    fi
+fi
+
+exit 0

package/examples/compact-circuit-breaker.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# ================================================================
+# compact-circuit-breaker.sh — Prevent auto-compact death spirals
+# ================================================================
+# PURPOSE:
+#   Auto-compact can enter an infinite loop when FileHistory
+#   recovery is degraded — each compaction fails to restore
+#   continuity, triggering the next one immediately. Users have
+#   lost entire overnight token budgets to 15+ consecutive
+#   compactions with zero forward progress (#51088). One incident
+#   recorded 211 compactions in a single session (#24179).
+#
+#   This hook acts as a circuit breaker: it allows normal
+#   compaction but blocks rapid-fire compaction that indicates
+#   a death spiral. After MAX_PER_HOUR compactions, further
+#   attempts are blocked until the window resets.
+#
+# TRIGGER: PreCompact
+# MATCHER: (none — PreCompact has no matcher)
+#
+# DECISION: exit 0 = allow, exit 2 = block
+#
+# CONFIG:
+#   MAX_PER_HOUR — Maximum compactions allowed per hour (default: 3)
+#   MIN_INTERVAL — Minimum seconds between compactions (default: 120)
+#
+# See: https://github.com/anthropics/claude-code/issues/51088
+#      https://github.com/anthropics/claude-code/issues/24179
+# ================================================================
+
+MAX_PER_HOUR="${CC_COMPACT_MAX_PER_HOUR:-3}"
+MIN_INTERVAL="${CC_COMPACT_MIN_INTERVAL:-120}"
+STATE_DIR="/tmp/.cc-compact-circuit-breaker"
+STATE_FILE="$STATE_DIR/compaction-log"
+
+mkdir -p "$STATE_DIR"
+touch "$STATE_FILE"
+
+NOW=$(date +%s)
+ONE_HOUR_AGO=$((NOW - 3600))
+
+# Clean old entries (older than 1 hour)
+if [ -f "$STATE_FILE" ]; then
+  awk -v cutoff="$ONE_HOUR_AGO" '$1 >= cutoff' "$STATE_FILE" > "$STATE_FILE.tmp"
+  mv "$STATE_FILE.tmp" "$STATE_FILE"
+fi
+
+# Count compactions in the last hour
+RECENT_COUNT=$(wc -l < "$STATE_FILE" | tr -d ' ')
+
+# Check minimum interval since last compaction
+LAST_TIME=0
+if [ -s "$STATE_FILE" ]; then
+  LAST_TIME=$(tail -1 "$STATE_FILE")
+fi
+ELAPSED=$((NOW - LAST_TIME))
+
+# Circuit breaker: block if too many compactions
+if [ "$RECENT_COUNT" -ge "$MAX_PER_HOUR" ]; then
+  echo "CIRCUIT BREAKER: $RECENT_COUNT compactions in the last hour (max: $MAX_PER_HOUR). Possible death spiral detected. Start a fresh session instead of compacting." >&2
+  exit 2
+fi
+
+# Cooldown: block if too soon after last compaction
+if [ "$ELAPSED" -lt "$MIN_INTERVAL" ] && [ "$LAST_TIME" -gt 0 ]; then
+  echo "COOLDOWN: Last compaction was ${ELAPSED}s ago (min interval: ${MIN_INTERVAL}s). Wait before compacting again." >&2
+  exit 2
+fi
+
+# Allow compaction and log it
+echo "$NOW" >> "$STATE_FILE"
+exit 0

package/examples/context-size-alert.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# context-size-alert.sh — Warn when context window usage exceeds threshold
+# Trigger: PostToolUse
+# Matcher: (empty — runs after every tool use)
+#
+# Since v2.1.100, the system prompt grew ~40-50% (~4,000 tokens).
+# This hook monitors context usage and warns before you hit limits.
+# See: https://github.com/anthropics/claude-code/issues/46339
+#
+# Optimization tips: https://zenn.dev/yurukusa/books/token-savings-guide
+#
+# TRIGGER: PostToolUse  MATCHER: ""
+
+INPUT=$(cat)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+
+# Only check every 10th invocation to minimize overhead
+COUNTER_FILE="/tmp/context-size-alert-${SESSION_ID:-default}.count"
+COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo 0)
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+[ $((COUNT % 10)) -ne 0 ] && exit 0
+
+# Check if /cost or /context data is available via transcript
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+[ -z "$TRANSCRIPT" ] && exit 0
+
+# Count approximate context by transcript file size (rough proxy)
+if [ -f "$TRANSCRIPT" ]; then
+    SIZE_KB=$(du -k "$TRANSCRIPT" | cut -f1)
+    # Rough threshold: 500KB transcript ≈ approaching context limits
+    if [ "$SIZE_KB" -gt 500 ]; then
+        echo "⚠ Context is large (~${SIZE_KB}KB transcript). Consider /compact or /clear to reduce token cost." >&2
+        echo "  Tip: Run /context to see exact usage breakdown." >&2
+    fi
+fi
+
+exit 0

package/examples/context-usage-drift-alert.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# context-usage-drift-alert.sh — コンテキスト使用率の急増を検知
+# Why: 1Mコンテキストモデルで実際124%使用中にUI上60%と表示される問題 (#50204)。
+#      予告なくauto-compactが発火してコンテキストが消失する。
+#      ツール呼び出し回数でコンテキスト消費を推定し、警告する。
+# Event: PostToolUse  MATCHER: ""
+# Action: セッション内のツール呼び出し回数が閾値を超えたら警告
+
+COUNTER_FILE="/tmp/cc-context-usage-counter-$$"
+# セッションPIDが変わると新しいカウンターになる
+# フォールバック: 親PIDでグループ化
+if [ ! -f "$COUNTER_FILE" ]; then
+  COUNTER_FILE="/tmp/cc-context-usage-counter-$(date +%Y%m%d)"
+fi
+
+COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+
+# 50回: 注意喚起、100回: 強い警告、150回: compact推奨
+if [ "$COUNT" -eq 50 ]; then
+  echo "📊 Session checkpoint: $COUNT tool calls. Context may be growing large." >&2
+  echo "Run /cost to check actual usage. UI display may undercount by 2x (#50204)." >&2
+elif [ "$COUNT" -eq 100 ]; then
+  echo "⚠ HIGH CONTEXT USAGE: $COUNT tool calls this session." >&2
+  echo "UI may show ~50% when actual usage is near 100%. Consider /compact." >&2
+  echo "Unexpected auto-compact can erase your working context. See: #50204" >&2
+elif [ "$COUNT" -eq 150 ]; then
+  echo "🚨 VERY HIGH CONTEXT: $COUNT tool calls. Auto-compact likely imminent." >&2
+  echo "Save important state to files NOW. Run /compact manually to control what's kept." >&2
+fi
+
+exit 0

package/examples/dangerous-pip-flag-guard.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# dangerous-pip-flag-guard.sh — Block dangerous pip flags that bypass safety
+#
+# Solves: Claude Code using pip install with dangerous flags in auto mode
+#   - #48992: pip install --break-system-packages passed through auto mode
+#   - Breaks system Python installations, can render OS tools unusable
+#
+# What it blocks:
+#   --break-system-packages (bypasses PEP 668 externally-managed check)
+#   --force-reinstall combined with system paths
+#   pip install targeting /usr/lib or /usr/local/lib directly
+#
+# What it allows:
+#   pip install in virtual environments (venv/conda)
+#   pip install --user (installs to user directory)
+#   pip install in project directories
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
+
+set -euo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Only check pip commands
+echo "$COMMAND" | grep -qE '\bpip[3]?\s+install\b' || exit 0
+
+# Block --break-system-packages
+if echo "$COMMAND" | grep -qE '\-\-break-system-packages'; then
+    echo "BLOCKED: --break-system-packages flag detected" >&2
+    echo "This flag bypasses PEP 668 protection and can break your system Python." >&2
+    echo "Use a virtual environment instead: python3 -m venv .venv && source .venv/bin/activate" >&2
+    exit 2
+fi
+
+# Block sudo pip install (system-wide install without venv)
+if echo "$COMMAND" | grep -qE '\bsudo\s+pip[3]?\s+install\b'; then
+    echo "BLOCKED: sudo pip install detected" >&2
+    echo "System-wide pip install can break OS tools. Use a virtual environment." >&2
+    exit 2
+fi
+
+# Block pip targeting system directories
+if echo "$COMMAND" | grep -qE '\bpip[3]?\s+install\b.*\-\-target\s*=?\s*/(usr|opt|lib)'; then
+    echo "BLOCKED: pip install targeting system directory" >&2
+    echo "Installing packages to system directories can break OS tools." >&2
+    exit 2
+fi
+
+exit 0

package/examples/deny-bypass-detector.sh

@@ -0,0 +1,143 @@
+#!/bin/bash
+# deny-bypass-detector.sh — Detect when Claude circumvents a hook denial
+#
+# Solves: After a PreToolUse hook blocks a command (exit 2), Claude
+# reformulates the same operation as a script wrapper, eval, or
+# bash -c to evade pattern matching. (#46991)
+#
+# How it works: Two-phase detection:
+#   Phase 1 (PostToolUse): When a Bash command is blocked (tool_result
+#     contains deny/block signals), log the dangerous substrings.
+#   Phase 2 (PreToolUse): Before each Bash command, check if it
+#     contains a recently-denied substring wrapped in bash -c, sh -c,
+#     eval, or a temp script.
+#
+# Denied commands expire after 60 seconds to avoid permanent lockout.
+#
+# Usage: Add TWO hooks — PostToolUse to log denials, PreToolUse to detect bypass
+#
+# {
+#   "hooks": {
+#     "PostToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/deny-bypass-detector.sh" }]
+#     }],
+#     "PreToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/deny-bypass-detector.sh" }]
+#     }]
+#   }
+# }
+#
+# TRIGGER: PostToolUse+PreToolUse  MATCHER: "Bash"
+
+set -euo pipefail
+
+DENY_LOG="/tmp/cc-deny-bypass-log"
+mkdir -p "$(dirname "$DENY_LOG")" 2>/dev/null || true
+
+INPUT=$(cat)
+HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // empty' 2>/dev/null)
+
+# --- Phase 1: PostToolUse — log denied commands ---
+if [[ "$HOOK_EVENT" == "PostToolUse" ]]; then
+    RESULT=$(echo "$INPUT" | jq -r '.tool_result // empty' 2>/dev/null)
+    # Detect denial signals in tool result
+    if echo "$RESULT" | grep -qiE 'BLOCKED|exit.*(code|status).*2|hook.*denied|hook.*blocked'; then
+        CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+        [ -z "$CMD" ] && exit 0
+        # Extract dangerous substrings: the core operation
+        # e.g., from "rm -rf node_modules" extract "rm -rf" and "node_modules"
+        TIMESTAMP=$(date +%s)
+        # Log the full command and key fragments
+        echo "${TIMESTAMP}|${CMD}" >> "$DENY_LOG"
+        # Also extract individual dangerous tokens
+        for token in $(echo "$CMD" | grep -oE '(rm\s+-rf|git\s+push\s+--force|git\s+reset\s+--hard|git\s+clean|chmod\s+777|curl.*\|.*sh|wget.*\|.*sh)' 2>/dev/null); do
+            echo "${TIMESTAMP}|PATTERN:${token}" >> "$DENY_LOG"
+        done
+    fi
+    exit 0
+fi
+
+# --- Phase 2: PreToolUse — detect bypass attempts ---
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$CMD" ] && exit 0
+[ ! -f "$DENY_LOG" ] && exit 0
+
+NOW=$(date +%s)
+CUTOFF=$((NOW - 60))
+
+# Clean expired entries
+if [ -f "$DENY_LOG" ]; then
+    awk -F'|' -v cutoff="$CUTOFF" '$1 >= cutoff' "$DENY_LOG" > "${DENY_LOG}.tmp" 2>/dev/null
+    mv "${DENY_LOG}.tmp" "$DENY_LOG" 2>/dev/null || true
+fi
+
+# Check if current command wraps a denied command
+BYPASS_DETECTED=0
+DENIED_CMD=""
+
+while IFS='|' read -r ts denied_cmd; do
+    [ "$ts" -lt "$CUTOFF" ] 2>/dev/null && continue
+    [ -z "$denied_cmd" ] && continue
+
+    # Skip pattern entries for this check
+    [[ "$denied_cmd" == PATTERN:* ]] && continue
+
+    # Check 1: bash -c / sh -c / eval wrapping the denied command
+    if echo "$CMD" | grep -qE '(bash|sh)\s+-c\s' || echo "$CMD" | grep -qE '\beval\s'; then
+        # Extract the inner command from the wrapper
+        INNER=$(echo "$CMD" | sed -E "s/.*(bash|sh)\s+-c\s+['\"]?//" | sed -E "s/['\"]?\s*$//")
+        # Check if inner command is similar to denied command
+        # Use key fragments: first word + arguments
+        DENIED_CORE=$(echo "$denied_cmd" | awk '{print $1}')
+        if echo "$INNER" | grep -qF "$DENIED_CORE"; then
+            BYPASS_DETECTED=1
+            DENIED_CMD="$denied_cmd"
+            break
+        fi
+    fi
+
+    # Check 2: Writing denied command to a temp script then executing
+    if echo "$CMD" | grep -qE '(cat|echo|printf).*>.*\.(sh|bash|tmp)' || \
+       echo "$CMD" | grep -qE 'python3?\s+-c|node\s+-e'; then
+        DENIED_CORE=$(echo "$denied_cmd" | awk '{print $1}')
+        if echo "$CMD" | grep -qF "$DENIED_CORE"; then
+            BYPASS_DETECTED=1
+            DENIED_CMD="$denied_cmd"
+            break
+        fi
+    fi
+
+    # Check 3: Direct re-execution (same command within 60s)
+    if [ "$CMD" = "$denied_cmd" ]; then
+        BYPASS_DETECTED=1
+        DENIED_CMD="$denied_cmd"
+        break
+    fi
+
+done < "$DENY_LOG"
+
+# Also check pattern-based detection
+if [ "$BYPASS_DETECTED" -eq 0 ]; then
+    while IFS='|' read -r ts pattern_entry; do
+        [ "$ts" -lt "$CUTOFF" ] 2>/dev/null && continue
+        [[ "$pattern_entry" != PATTERN:* ]] && continue
+        PATTERN="${pattern_entry#PATTERN:}"
+        if echo "$CMD" | grep -qiE "$PATTERN"; then
+            BYPASS_DETECTED=1
+            DENIED_CMD="(pattern: $PATTERN)"
+            break
+        fi
+    done < "$DENY_LOG"
+fi
+
+if [ "$BYPASS_DETECTED" -eq 1 ]; then
+    echo "BLOCKED: Bypass attempt detected." >&2
+    echo "  A similar command was denied <60 seconds ago: $DENIED_CMD" >&2
+    echo "  Wrapping denied commands in scripts or eval does not change the policy." >&2
+    echo "  Ask the user for explicit permission before retrying." >&2
+    exit 2
+fi
+
+exit 0

package/examples/dotenv-read-guard.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# dotenv-read-guard.sh — Block Read/Glob/Grep of .env files
+#
+# Solves: Sub-agents (especially Explore) reading .env files and exposing
+#         API keys, tokens, and secrets in the conversation transcript.
+#         (#51030 — Explore agent read .env, exposed 5 API keys, $50 damage)
+#         (#30731 — credentials exposed in output)
+#
+# This hook catches the Read tool accessing .env files, which
+# credential-file-cat-guard.sh misses (it only covers Bash cat commands).
+# Sub-agents inherit hooks but NOT memory/security instructions, making
+# this hook essential for preventing secret leaks in multi-agent workflows.
+#
+# Usage: Add to settings.json as a PreToolUse hook
+#
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Read",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/dotenv-read-guard.sh" }]
+#     }]
+#   }
+# }
+#
+# TRIGGER: PreToolUse  MATCHER: "Read"
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+[ -z "$FILE_PATH" ] && exit 0
+
+BASENAME=$(basename "$FILE_PATH")
+
+# Block .env and all variants (.env.local, .env.production, .env.staging, etc.)
+# Allow .env.example, .env.sample, .env.template (safe reference files)
+if echo "$BASENAME" | grep -qE '^\.env(\.example|\.sample|\.template)$'; then
+    exit 0
+fi
+
+if echo "$BASENAME" | grep -qE '^\.env(\..+)?$'; then
+    echo "BLOCKED: Reading $BASENAME — contains secrets (API keys, tokens)" >&2
+    echo "  .env files should never be read by Claude Code." >&2
+    echo "  If you need to check which variables are set, read .env.example instead." >&2
+    echo "  Related: GitHub Issue #51030 (sub-agent exposed 5 API keys)" >&2
+    exit 2
+fi
+
+exit 0