cc-safe-setup 29.6.32 → 29.6.33

package/examples/pre-compact-knowledge-save.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# pre-compact-knowledge-save.sh — Save critical context before compaction
+#
+# Solves: Context compaction losing important decisions, file locations,
+#         and progress state. After /compact, Claude forgets what it was
+#         doing and repeats work or contradicts earlier decisions.
+#
+# How it works: PreCompact hook that saves the current session state
+#   to a checkpoint file that survives compaction. The model can read
+#   this file after compaction to restore context.
+#
+# The checkpoint includes: current task, recent decisions, modified files.
+#
+# TRIGGER: PreCompact
+# MATCHER: ""
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+CHECKPOINT="${CC_COMPACT_CHECKPOINT:-.claude/pre-compact-checkpoint.md}"
+mkdir -p "$(dirname "$CHECKPOINT")"
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Gather session state
+GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
+MODIFIED=$(git diff --name-only 2>/dev/null | head -10 || echo "none")
+STAGED=$(git diff --cached --name-only 2>/dev/null | head -10 || echo "none")
+RECENT_COMMITS=$(git log --oneline -3 2>/dev/null || echo "none")
+
+cat > "$CHECKPOINT" << CHECKPOINT_EOF
+# Pre-Compact Checkpoint
+Generated: ${TIMESTAMP}
+Branch: ${GIT_BRANCH}
+
+## Modified files (not staged)
+${MODIFIED}
+
+## Staged files
+${STAGED}
+
+## Recent commits
+${RECENT_COMMITS}
+
+## Notes
+Read this file after compaction to restore context.
+Check tasks/todo.md for current task progress.
+CHECKPOINT_EOF
+
+echo "Pre-compact checkpoint saved to $CHECKPOINT" >&2
+
+exit 0

package/examples/pre-compact-transcript-export.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# ================================================================
+# pre-compact-transcript-export.sh — Export conversation before compaction
+# ================================================================
+# PURPOSE:
+#   After compaction, the pre-compaction conversation is inaccessible
+#   in the TUI. This hook exports the conversation to a human-readable
+#   markdown file before compaction happens, so you can review it later.
+#
+#   Reads transcript.jsonl and extracts:
+#   - User messages (prompts)
+#   - Assistant messages (responses)
+#   - Tool calls and results (summarized)
+#
+# TRIGGER: PreCompact
+# MATCHER: (none — PreCompact has no matcher)
+#
+# OUTPUT: .claude/conversation-snapshots/TIMESTAMP.md
+#
+# See: https://github.com/anthropics/claude-code/issues/27242
+# ================================================================
+
+# Find the current session transcript
+SESSION_DIR="${HOME}/.claude/projects"
+TRANSCRIPT=""
+
+# Try to find transcript from input
+INPUT=$(cat)
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
+
+# Fallback: find most recent transcript.jsonl
+if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
+    TRANSCRIPT=$(find "$SESSION_DIR" -name "transcript.jsonl" -newer /tmp/.claude-session-start 2>/dev/null | head -1)
+fi
+
+# If still not found, try the current working directory
+if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
+    TRANSCRIPT=$(find "$SESSION_DIR" -name "transcript.jsonl" -mmin -60 2>/dev/null | sort -t/ -k1 | tail -1)
+fi
+
+[ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ] && exit 0
+
+# Create snapshot directory
+SNAPSHOT_DIR="${HOME}/.claude/conversation-snapshots"
+mkdir -p "$SNAPSHOT_DIR"
+TIMESTAMP=$(date -u +"%Y%m%d-%H%M%S")
+OUTPUT="$SNAPSHOT_DIR/${TIMESTAMP}.md"
+
+# Extract human-readable conversation
+{
+    echo "# Conversation Snapshot"
+    echo "Exported: $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
+    echo "Source: $TRANSCRIPT"
+    echo ""
+    echo "---"
+    echo ""
+
+    # Parse JSONL and extract messages
+    while IFS= read -r line; do
+        ROLE=$(echo "$line" | jq -r '.message.role // empty' 2>/dev/null)
+        case "$ROLE" in
+            user)
+                CONTENT=$(echo "$line" | jq -r '.message.content // empty' 2>/dev/null)
+                if [ -n "$CONTENT" ] && [ "$CONTENT" != "null" ]; then
+                    echo "## User"
+                    echo "$CONTENT" | head -20
+                    echo ""
+                fi
+                ;;
+            assistant)
+                TEXT=$(echo "$line" | jq -r '[.message.content[]? | select(.type=="text") | .text] | join("\n")' 2>/dev/null)
+                if [ -n "$TEXT" ] && [ "$TEXT" != "null" ]; then
+                    echo "## Assistant"
+                    echo "$TEXT" | head -50
+                    echo ""
+                fi
+                ;;
+        esac
+    done < "$TRANSCRIPT"
+} > "$OUTPUT" 2>/dev/null
+
+LINES=$(wc -l < "$OUTPUT" 2>/dev/null || echo 0)
+echo "Conversation snapshot saved: $OUTPUT ($LINES lines)" >&2
+
+exit 0

package/examples/prefer-builtin-tools.sh

@@ -6,6 +6,8 @@
 # Claude Code has built-in Read, Edit, Grep, Glob tools that are faster and safer
 # than bash equivalents. But Claude often reaches for sed, grep, cat instead.
 # This hook denies those commands with a pointer to the correct built-in tool.
+#
+# TRIGGER: PermissionRequest  MATCHER: ""
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

package/examples/prefer-const.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+#
+# TRIGGER: PreToolUse  MATCHER: "Edit|Write"
 CONTENT=$(cat | jq -r '.tool_input.new_string // .tool_input.content // empty' 2>/dev/null)
 [ -z "$CONTENT" ] && exit 0
 echo "$CONTENT" | grep -qE "^\s*let\s+\w+\s*=" && echo "NOTE: Consider const if not reassigned" >&2

package/examples/prefer-dedicated-tools.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# prefer-dedicated-tools.sh — Force use of dedicated tools instead of Bash equivalents
+#
+# Solves: Claude uses Bash cat/grep/head/tail instead of dedicated Read/Grep
+#         tools, wasting tokens on shell overhead and losing structured output
+#         (#39979). The system prompt says to use dedicated tools, but the
+#         model ignores it.
+#
+# How it works: PreToolUse hook on Bash that detects file-reading commands
+#   and blocks them with a suggestion to use the dedicated tool instead.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+#
+# Usage:
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/prefer-dedicated-tools.sh" }]
+#     }]
+#   }
+# }
+
+INPUT=$(cat)
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$CMD" ] && exit 0
+
+# Detect cat used for reading files (not piped)
+if echo "$CMD" | grep -qE '^\s*cat\s+[^|]+$'; then
+    echo "BLOCKED: Use the Read tool instead of 'cat' for reading files." >&2
+    exit 2
+fi
+
+# Detect head/tail used for reading files
+if echo "$CMD" | grep -qE '^\s*(head|tail)\s+(-[0-9]+\s+)?[^|]+$'; then
+    echo "BLOCKED: Use the Read tool (with offset/limit) instead of head/tail." >&2
+    exit 2
+fi
+
+# Detect grep used for searching (not piped)
+if echo "$CMD" | grep -qE '^\s*grep\s+(-[a-zA-Z]*\s+)*[^|]+$' && ! echo "$CMD" | grep -qE '\|'; then
+    echo "BLOCKED: Use the Grep tool instead of 'grep' for searching files." >&2
+    exit 2
+fi
+
+# Detect find used for file discovery
+if echo "$CMD" | grep -qE '^\s*find\s+\S+\s+-name\s'; then
+    echo "BLOCKED: Use the Glob tool instead of 'find' for file discovery." >&2
+    exit 2
+fi
+
+# Allow piped commands (cat file | grep pattern is a valid use case)
+# Allow other legitimate bash usage
+exit 0

package/examples/prefer-optional-chaining.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+#
+# TRIGGER: PreToolUse  MATCHER: "Edit|Write"
 CONTENT=$(cat | jq -r '.tool_input.new_string // .tool_input.content // empty' 2>/dev/null)
 [ -z "$CONTENT" ] && exit 0
 echo "$CONTENT" | grep -qE "\w+\s*&&\s*\w+\.\w+" && echo "NOTE: Consider optional chaining (?.) instead" >&2

package/examples/prisma-migrate-guard.sh

@@ -16,6 +16,8 @@
 #   }
 # }
 # ================================================================
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

package/examples/prompt-injection-detector.sh

@@ -8,6 +8,8 @@
 # (API, shared sessions, automated pipelines).
 #
 # See: https://github.com/anthropics/claude-code/issues/34895
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null)

package/examples/prompt-length-guard.sh

@@ -6,6 +6,8 @@
 # Warns when a user prompt exceeds a character threshold.
 # Very long prompts can consume excessive context and tokens.
 # Adjust THRESHOLD to match your comfort level.
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null)

package/examples/protect-dotfiles.sh

@@ -16,6 +16,8 @@
 #     }]
 #   }
 # }
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)

package/examples/public-repo-push-guard.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# public-repo-push-guard.sh — Block pushing proprietary code to public repos
+#
+# Solves: Accidental exposure of private code to public repositories (#29225).
+#         Claude pushes code containing internal paths, strategy files, or
+#         proprietary patterns to a public GitHub repo.
+#
+# How it works: PreToolUse hook on Bash that detects git push commands,
+#   checks if the remote repo is public via gh API, then scans staged
+#   files against a configurable blocklist.
+#
+# Configuration: CC_PRIVATE_PATTERNS (colon-separated glob patterns)
+#   Default: "internal/:strategies/:*.secret.*:*.private.*"
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+
+set -uo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Only check git push
+if ! echo "$COMMAND" | grep -qE '^\s*git\s+push\b'; then
+  exit 0
+fi
+
+# Get remote URL
+REMOTE=$(git remote get-url origin 2>/dev/null || echo "")
+[ -z "$REMOTE" ] && exit 0
+
+# Extract owner/repo from URL
+REPO=$(echo "$REMOTE" | sed -E 's|.*github\.com[:/]||; s|\.git$||')
+[ -z "$REPO" ] && exit 0
+
+# Check visibility (requires gh CLI)
+if command -v gh &>/dev/null; then
+  VISIBILITY=$(gh repo view "$REPO" --json visibility --jq '.visibility' 2>/dev/null || echo "UNKNOWN")
+  if [ "$VISIBILITY" = "PUBLIC" ]; then
+    # Check staged files against private patterns
+    PATTERNS="${CC_PRIVATE_PATTERNS:-internal/:strategies/:*.secret.*:*.private.*}"
+    STAGED=$(git diff --cached --name-only 2>/dev/null || echo "")
+
+    IFS=':' read -ra PATS <<< "$PATTERNS"
+    for pat in "${PATS[@]}"; do
+      MATCH=$(echo "$STAGED" | grep -E "$pat" | head -1)
+      if [ -n "$MATCH" ]; then
+        echo "BLOCKED: Pushing to PUBLIC repo '$REPO' with private file pattern." >&2
+        echo "File: $MATCH matches pattern: $pat" >&2
+        echo "Remove private files from staging or push to a private repo." >&2
+        exit 2
+      fi
+    done
+  fi
+fi
+
+exit 0

package/examples/push-requires-test-pass-record.sh

@@ -5,6 +5,8 @@
 # The PreToolUse companion then checks this record before allowing git push.
 #
 # Detected test commands: npm test, pytest, cargo test, go test, make test, etc.
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

package/examples/push-requires-test-pass.sh

@@ -24,6 +24,8 @@
 #     }]
 #   }
 # }
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

package/examples/rails-migration-guard.sh

@@ -16,6 +16,8 @@
 #   }
 # }
 # ================================================================
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

package/examples/rate-limit-guard.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty' 2>/dev/null)

package/examples/read-all-files-enforcer.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# read-all-files-enforcer.sh — Track which files have been read in a directory
+#
+# Solves: Agent skips files when told to "read every file" (#40389).
+#         Claude delegates to subagents, summarizes instead of reading,
+#         or substitutes its own judgment about what needs reading.
+#
+# How it works: PostToolUse hook on Read that logs read files.
+#   Paired with a manual check: after the user says "read all files in X",
+#   compare the log against actual directory contents.
+#
+# Usage: Set CC_READ_TRACK_DIR to the target directory.
+#   export CC_READ_TRACK_DIR="docs/"
+#   After the task, check: diff <(ls docs/) <(cat /tmp/claude-read-log-*)
+#
+# TRIGGER: PostToolUse
+# MATCHER: "Read"
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ "$TOOL" = "Read" ] || exit 0
+
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+
+TRACK_DIR="${CC_READ_TRACK_DIR:-}"
+[ -n "$TRACK_DIR" ] || exit 0
+
+# Check if the read file is in the tracked directory
+case "$FILE" in
+    ${TRACK_DIR}*)
+        # Log the read
+        LOG_FILE="/tmp/claude-read-track-${PPID:-0}"
+        echo "$FILE" >> "$LOG_FILE"
+
+        # Count total files in directory vs read files
+        TOTAL=$(find "$TRACK_DIR" -type f 2>/dev/null | wc -l)
+        READ_COUNT=$(sort -u "$LOG_FILE" 2>/dev/null | wc -l)
+
+        if [ "$READ_COUNT" -lt "$TOTAL" ]; then
+            REMAINING=$((TOTAL - READ_COUNT))
+            echo "Progress: $READ_COUNT/$TOTAL files read in $TRACK_DIR ($REMAINING remaining)" >&2
+        else
+            echo "All $TOTAL files in $TRACK_DIR have been read." >&2
+        fi
+        ;;
+esac
+
+exit 0

package/examples/readme-exists-check.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 CONTENT=$(cat | jq -r '.tool_input.new_string // .tool_input.content // empty' 2>/dev/null)
 [ -z "$CONTENT" ] && exit 0
 COMMAND=$(cat | jq -r ".tool_input.command // empty" 2>/dev/null); echo "$COMMAND" | grep -qE "git\s+commit" && [ ! -f "README.md" ] && echo "NOTE: No README.md in project" >&2

package/examples/redis-flushall-guard.sh

@@ -1,3 +1,5 @@
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [[ -z "$COMMAND" ]] && exit 0

package/examples/rm-safety-net.sh

@@ -30,6 +30,8 @@
 #
 # Note: This hook checks rm, find -delete, and shred. Do NOT add an "if" field
 # (v2.1.85) because "if" only supports one pattern and would miss the others.
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

package/examples/role-tool-guard.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# role-tool-guard.sh — Restrict tools based on current agent role
+#
+# Solves: Agent team workflows where PM writes code instead of delegating (#40425).
+#         When using structured team roles (PM → Architect → Developer),
+#         each role should only access tools appropriate to its function.
+#         CLAUDE.md rules are advisory and get ignored under context pressure.
+#
+# How it works: Reads current role from a scope file, then blocks tools
+#   that don't match the role's allowed tool set.
+#
+# Setup:
+#   echo "pm" > .claude/current-role.txt
+#   Roles: pm, architect, developer, reviewer (customizable)
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash|Edit|Write|NotebookEdit|Agent"
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ -z "$TOOL" ] && exit 0
+
+# Read current role
+ROLE_FILE=".claude/current-role.txt"
+[ -f "$ROLE_FILE" ] || exit 0
+
+ROLE=$(head -1 "$ROLE_FILE" | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')
+[ -z "$ROLE" ] && exit 0
+
+# Define allowed tools per role (customizable via env)
+case "$ROLE" in
+  pm|"product-manager"|"project-manager")
+    # PM can read, search, and delegate — not write code
+    BLOCKED_TOOLS="Edit|Write|Bash|NotebookEdit"
+    ROLE_DESC="PM (read/delegate only)"
+    ;;
+  architect|"system-architect")
+    # Architect can read and write docs, not execute
+    BLOCKED_TOOLS="Bash|NotebookEdit"
+    ROLE_DESC="Architect (design only, no execution)"
+    ;;
+  reviewer|"code-reviewer")
+    # Reviewer can read and comment, not modify
+    BLOCKED_TOOLS="Edit|Write|NotebookEdit"
+    ROLE_DESC="Reviewer (read-only)"
+    ;;
+  developer|"dev")
+    # Developer has full access
+    exit 0
+    ;;
+  *)
+    # Unknown role — allow by default
+    exit 0
+    ;;
+esac
+
+# Check if current tool is blocked for this role
+if echo "$TOOL" | grep -qE "^($BLOCKED_TOOLS)$"; then
+  echo "BLOCKED: Role '$ROLE' cannot use $TOOL." >&2
+  echo "Current role: $ROLE_DESC" >&2
+  echo "" >&2
+  echo "To change role: echo 'developer' > .claude/current-role.txt" >&2
+  echo "Or delegate this task to the appropriate agent." >&2
+  exit 2
+fi
+
+exit 0

package/examples/ruby-lint-on-edit.sh

@@ -17,6 +17,8 @@
 #   }
 # }
 # ================================================================
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)

package/examples/schema-migration-guard.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# schema-migration-guard.sh — Warn on database schema migrations without backup
+#
+# Solves: Claude running destructive schema migrations (DROP COLUMN,
+#         ALTER TABLE, DROP INDEX) without first creating a backup or
+#         generating a rollback migration.
+#
+# How it works: PreToolUse hook on Bash that detects migration commands
+#   (Rails, Django, Prisma, Flyway, Liquibase, raw SQL) and warns if
+#   they contain destructive operations.
+#
+# 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
+
+# Detect migration commands
+IS_MIGRATION=false
+case "$COMMAND" in
+    *"migrate"*|*"migration"*|*"db:migrate"*|*"prisma migrate"*|*"alembic"*|*"flyway"*|*"liquibase"*)
+        IS_MIGRATION=true ;;
+esac
+
+# Also check for raw SQL with destructive operations
+if echo "$COMMAND" | grep -qEi '(DROP\s+(TABLE|COLUMN|INDEX|DATABASE|SCHEMA)|ALTER\s+TABLE.*DROP|TRUNCATE\s+TABLE|DELETE\s+FROM.*WHERE\s+1)'; then
+    IS_MIGRATION=true
+fi
+
+$IS_MIGRATION || exit 0
+
+# Check for destructive patterns
+DESTRUCT=""
+if echo "$COMMAND" | grep -qEi 'DROP\s+(TABLE|COLUMN|INDEX|DATABASE)'; then
+    DESTRUCT="${DESTRUCT}DROP operation detected. "
+fi
+if echo "$COMMAND" | grep -qEi 'TRUNCATE'; then
+    DESTRUCT="${DESTRUCT}TRUNCATE detected. "
+fi
+if echo "$COMMAND" | grep -qEi -- '--force|--no-check|--skip-validation'; then
+    DESTRUCT="${DESTRUCT}Safety bypass flag detected. "
+fi
+
+if [ -n "$DESTRUCT" ]; then
+    echo "WARNING: Destructive database migration detected." >&2
+    echo "  Command: $COMMAND" >&2
+    echo "  Issues: $DESTRUCT" >&2
+    echo "  Before running:" >&2
+    echo "    1. Create a database backup" >&2
+    echo "    2. Generate a rollback migration" >&2
+    echo "    3. Test on staging first" >&2
+fi
+
+exit 0

package/examples/scope-guard.sh

@@ -14,6 +14,8 @@
 #     }]
 #   }
 # }
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)

package/examples/secret-file-read-guard.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# secret-file-read-guard.sh — Block Read/Grep of files containing secrets
+#
+# Solves: Sensitive data (API keys, credentials, PII) is sent to the
+#         LLM provider when Read/Grep tools access configuration files
+#         (#39882). This hook blocks reads of known-sensitive files.
+#
+# How it works: PreToolUse hook that checks if Read/Grep targets a
+#   file that commonly contains secrets (.env, credentials, keys, etc.)
+#   and blocks the operation before file contents enter the context.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Read|Grep"
+#
+# Usage:
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Read|Grep",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/secret-file-read-guard.sh" }]
+#     }]
+#   }
+# }
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+
+[[ "$TOOL" != "Read" && "$TOOL" != "Grep" ]] && exit 0
+[ -z "$FILE" ] && exit 0
+
+# Expand ~ to $HOME
+FILE=$(echo "$FILE" | sed "s|^~|$HOME|")
+
+# ============================================
+# BLOCKED FILE PATTERNS — customize as needed
+# ============================================
+BLOCKED_PATTERNS=(
+    '\.env$'
+    '\.env\.'
+    'credentials'
+    '\.pem$'
+    '\.key$'
+    '\.p12$'
+    '\.jks$'
+    '\.keystore$'
+    'id_rsa'
+    'id_ed25519'
+    '\.ssh/config$'
+    '\.aws/credentials$'
+    '\.aws/config$'
+    '\.npmrc$'
+    '\.pypirc$'
+    '\.docker/config\.json$'
+    '\.kube/config$'
+    'secrets\.ya?ml$'
+    'vault\.ya?ml$'
+    '\.htpasswd$'
+    'shadow$'
+    'master\.key$'
+    'service[-_]account.*\.json$'
+)
+
+BASENAME=$(basename "$FILE")
+for pattern in "${BLOCKED_PATTERNS[@]}"; do
+    if echo "$FILE" | grep -qE "$pattern" || echo "$BASENAME" | grep -qE "$pattern"; then
+        echo "BLOCKED: Cannot read file that may contain secrets: $FILE" >&2
+        echo "This file matches pattern: $pattern" >&2
+        echo "If you need this file's contents, describe what you need and the user can provide it." >&2
+        exit 2
+    fi
+done
+
+exit 0