cc-safe-setup 29.6.33 → 29.6.37

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dw/cc-safe-setup)](https://www.npmjs.com/package/cc-safe-setup)
 [![tests](https://github.com/yurukusa/cc-safe-setup/actions/workflows/test.yml/badge.svg)](https://github.com/yurukusa/cc-safe-setup/actions/workflows/test.yml)
 
-**One command to make Claude Code safe for autonomous operation.** 611 example hooks · 10,411 tests · 1,000+ installs/day · [日本語](docs/README.ja.md)
+**One command to make Claude Code safe for autonomous operation.** 634 example hooks · 13,835 tests · 1,000+ installs/day · [日本語](docs/README.ja.md)
 
 ```bash
 npx cc-safe-setup

package/examples/claudemd-violation-detector.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# claudemd-violation-detector.sh — Remind critical CLAUDE.md rules after tool use
+#
+# Solves: Claude ignores CLAUDE.md instructions, especially after
+#         context compaction or in long sessions (#40930).
+#
+# How it works: After each tool use, extracts and prints
+#   critical rules (ABSOLUTE/MUST NEVER/NEVER/禁止) from CLAUDE.md
+#   as a reminder. Runs every N tool calls to avoid noise.
+#
+# TRIGGER: PostToolUse
+# MATCHER: ""
+
+set -euo pipefail
+
+# Rate limit: only remind every 20 tool calls
+COUNTER_FILE="/tmp/claudemd-reminder-counter"
+COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+[ $((COUNT % 20)) -ne 0 ] && exit 0
+
+# Find CLAUDE.md
+CLAUDEMD=""
+for candidate in "CLAUDE.md" ".claude/CLAUDE.md" "../CLAUDE.md"; do
+  [ -f "$candidate" ] && CLAUDEMD="$candidate" && break
+done
+[ -z "$CLAUDEMD" ] && exit 0
+
+# Extract critical rules
+RULES=$(grep -iE '(ABSOLUTE|MUST NEVER|NEVER DO|禁止|絶対)' "$CLAUDEMD" 2>/dev/null | head -5 || true)
+[ -z "$RULES" ] && exit 0
+
+echo "📋 CLAUDE.md critical rules reminder:" >&2
+echo "$RULES" >&2
+exit 0

package/examples/clear-command-confirm-guard.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# clear-command-confirm-guard.sh — Block accidental /clear command
+#
+# Solves: /clear destroys all conversation context with zero
+#         confirmation. Prefix matching means /c + Enter can
+#         accidentally trigger /clear instead of /commit or /compact (#40931).
+#
+# How it works: Blocks /clear entirely. Use /compact to reduce
+#   context without losing it.
+#
+# TRIGGER: UserPromptSubmit
+# MATCHER: "^/clear$"
+
+INPUT=$(cat)
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null)
+
+if echo "$PROMPT" | grep -qE '^/clear$'; then
+  echo "BLOCKED: /clear permanently destroys all context. Use /compact instead to reduce context safely." >&2
+  exit 2
+fi
+exit 0

package/examples/core-file-protect-guard.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+# ================================================================
+# core-file-protect-guard.sh — Block edits to core/config/rules files
+# ================================================================
+# PURPOSE:
+#   Claude Code sometimes makes unprompted architectural changes to
+#   game rules, configuration files, and core logic files. This hook
+#   blocks modifications to files matching configurable glob patterns.
+#
+# Protects files matching CC_PROTECTED_FILES patterns (colon-separated).
+# Default: "*rules*:*config*:*core*"
+#
+# Catches:
+#   - Edit/Write tool targeting protected files
+#   - Bash commands using sed -i or awk -i on protected files
+#
+# See: https://github.com/anthropics/claude-code/issues/40788
+#
+# TRIGGER: PreToolUse  MATCHER: "Edit|Write|Bash"
+#
+# Configuration:
+#   CC_PROTECTED_FILES — colon-separated glob patterns
+#   Default: "*rules*:*config*:*core*"
+# ================================================================
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+# Configurable protected file patterns (colon-separated globs)
+PROTECTED="${CC_PROTECTED_FILES:-*rules*:*config*:*core*}"
+
+# Convert colon-separated globs to a function that checks a filename
+matches_protected() {
+    local filepath="$1"
+    local basename
+    basename=$(basename "$filepath")
+
+    IFS=':' read -ra PATTERNS <<< "$PROTECTED"
+    for pattern in "${PATTERNS[@]}"; do
+        # Use bash glob matching (case-insensitive via shopt)
+        if [[ "$basename" == $pattern ]] || [[ "$filepath" == *$pattern* ]]; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+# Handle Edit/Write tools
+if [[ "$TOOL" == "Edit" || "$TOOL" == "Write" ]]; then
+    FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+    [ -z "$FILE" ] && exit 0
+
+    if matches_protected "$FILE"; then
+        echo "BLOCKED: Cannot modify protected file: $FILE" >&2
+        echo "" >&2
+        echo "Protected patterns: $PROTECTED" >&2
+        echo "Configure with CC_PROTECTED_FILES env var." >&2
+        echo "" >&2
+        echo "See: https://github.com/anthropics/claude-code/issues/40788" >&2
+        exit 2
+    fi
+    exit 0
+fi
+
+# Handle Bash tool — check for sed -i / awk -i targeting protected files
+if [[ "$TOOL" == "Bash" ]]; then
+    COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+    [ -z "$COMMAND" ] && exit 0
+
+    # Skip echo/printf
+    echo "$COMMAND" | grep -qE '^\s*(echo|printf)\s' && exit 0
+
+    # Check for sed -i or awk -i inplace targeting protected files
+    if echo "$COMMAND" | grep -qE '(sed\s+-i|awk\s+-i\s+inplace)'; then
+        # Extract potential file arguments from the command
+        IFS=':' read -ra PATTERNS <<< "$PROTECTED"
+        for pattern in "${PATTERNS[@]}"; do
+            if echo "$COMMAND" | grep -qE "$pattern"; then
+                echo "BLOCKED: In-place edit targets protected file pattern: $pattern" >&2
+                echo "" >&2
+                echo "Command: $COMMAND" >&2
+                echo "Protected patterns: $PROTECTED" >&2
+                echo "" >&2
+                echo "See: https://github.com/anthropics/claude-code/issues/40788" >&2
+                exit 2
+            fi
+        done
+    fi
+fi
+
+exit 0

package/examples/cwd-drift-detector.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# cwd-drift-detector.sh — Warn when destructive commands run outside project root
+#
+# Solves: Claude frequently loses track of which directory
+#         it is in, risking destructive commands in the wrong
+#         location (#1669). git reset --hard in the wrong
+#         directory can destroy unrelated work.
+#
+# How it works: For destructive commands (git reset, rm -rf,
+#   git clean, git checkout -- .), checks if the current
+#   directory looks like a project root (has .git, package.json,
+#   etc). Warns if it doesn't.
+#
+# 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
+if ! echo "$COMMAND" | grep -qE '(git\s+(reset|clean|checkout\s+--|push\s+--force)|rm\s+-rf|DROP\s+TABLE|DROP\s+DATABASE)'; then
+  exit 0
+fi
+
+# Check if we're in a project root
+CWD=$(pwd)
+IS_PROJECT=false
+
+for marker in .git package.json Cargo.toml go.mod pyproject.toml Makefile; do
+  if [ -e "$CWD/$marker" ]; then
+    IS_PROJECT=true
+    break
+  fi
+done
+
+if [ "$IS_PROJECT" = false ]; then
+  echo "WARNING: Destructive command detected outside project root." >&2
+  echo "  CWD: $CWD" >&2
+  echo "  Command: $(echo "$COMMAND" | head -c 100)" >&2
+  echo "  No project markers (.git, package.json, etc) found." >&2
+  echo "  Verify you are in the correct directory." >&2
+fi
+
+exit 0

package/examples/deployment-verify-guard.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# ================================================================
+# deployment-verify-guard.sh — Warn if committing without post-deploy verification
+# ================================================================
+# PURPOSE:
+#   Claude Code sometimes reports "deployment successful" without
+#   actually verifying the deployment works. This hook tracks deploy
+#   commands and checks that functional verification was performed
+#   before the next git commit.
+#
+# How it works:
+#   1. When a deploy command is detected, logs timestamp to a marker file
+#   2. When verification commands (test, curl, log grep) run, clears the marker
+#   3. When git commit is attempted after a deploy without verification,
+#      emits a warning (non-blocking, exit 0)
+#
+# See: https://github.com/anthropics/claude-code/issues/40861
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
+#
+# Configuration:
+#   CC_DEPLOY_COMMANDS — regex pattern for deploy commands
+#   Default: "systemctl restart|docker restart|docker-compose up|deploy|kubectl apply|terraform apply|heroku push"
+#
+#   CC_VERIFY_COMMANDS — regex pattern for verification commands
+#   Default: "curl|wget|test |pytest|npm test|jest|mocha|rspec|go test|cargo test|make test|grep.*log|tail.*log|journalctl|docker logs|health"
+# ================================================================
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+[ -z "$COMMAND" ] && exit 0
+
+MARKER="/tmp/cc-deploy-pending-$$"
+
+# Configurable deploy command patterns
+DEPLOY_PATTERN="${CC_DEPLOY_COMMANDS:-systemctl\s+restart|docker\s+restart|docker-compose\s+up|docker\s+compose\s+up|\bdeploy\b|kubectl\s+apply|terraform\s+apply|heroku\s+.*push|fly\s+deploy}"
+
+# Configurable verify command patterns
+VERIFY_PATTERN="${CC_VERIFY_COMMANDS:-\bcurl\b|\bwget\b|\btest\s|\bpytest\b|npm\s+test|\bjest\b|\bmocha\b|\brspec\b|go\s+test|cargo\s+test|make\s+test|grep.*log|tail.*log|\bjournalctl\b|docker\s+logs|\bhealth}"
+
+# Skip echo/printf
+echo "$COMMAND" | grep -qE '^\s*(echo|printf)\s' && exit 0
+
+# Check if this is a deploy command
+if echo "$COMMAND" | grep -qiE "$DEPLOY_PATTERN"; then
+    date +%s > "$MARKER"
+    echo "Deploy detected. Verification will be required before commit." >&2
+    exit 0
+fi
+
+# Check if this is a verification command — clear the deploy marker
+if echo "$COMMAND" | grep -qiE "$VERIFY_PATTERN"; then
+    if [ -f "$MARKER" ]; then
+        rm -f "$MARKER"
+    fi
+    exit 0
+fi
+
+# Check if this is a git commit after an unverified deploy
+if echo "$COMMAND" | grep -qE '\bgit\s+commit\b'; then
+    if [ -f "$MARKER" ]; then
+        DEPLOY_TIME=$(cat "$MARKER" 2>/dev/null || echo "unknown")
+        echo "WARNING: Committing after deployment without verification." >&2
+        echo "" >&2
+        echo "A deploy command was run (at timestamp $DEPLOY_TIME) but no" >&2
+        echo "verification command was detected since then." >&2
+        echo "" >&2
+        echo "Recommended verifications:" >&2
+        echo "  curl http://localhost:<port>/health" >&2
+        echo "  npm test / pytest / go test" >&2
+        echo "  docker logs <container> | tail" >&2
+        echo "  journalctl -u <service> --since '5 min ago'" >&2
+        echo "" >&2
+        echo "See: https://github.com/anthropics/claude-code/issues/40861" >&2
+        # Non-blocking — just warn
+        rm -f "$MARKER"
+    fi
+fi
+
+exit 0

package/examples/edit-old-string-validator.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# edit-old-string-validator.sh — Pre-validate Edit tool old_string exists
+#
+# Solves: Parallel Edit tool calls cascade-fail when one Edit's
+#         old_string doesn't match the file content (#22264).
+#         By catching mismatches before execution, sibling
+#         edits in the same batch can proceed normally.
+#
+# How it works: Reads the Edit tool input, checks if old_string
+#   exists in the target file. If not found, blocks with exit 2
+#   and a descriptive error message.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Edit"
+
+set -euo pipefail
+INPUT=$(cat)
+
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+OLD_STRING=$(echo "$INPUT" | jq -r '.tool_input.old_string // empty' 2>/dev/null)
+
+# Skip if no file or old_string
+[ -z "$FILE" ] && exit 0
+[ -z "$OLD_STRING" ] && exit 0
+
+# Skip if file doesn't exist (Edit tool will handle that error)
+[ ! -f "$FILE" ] && exit 0
+
+# Check if old_string exists in the file
+if ! grep -qF "$OLD_STRING" "$FILE" 2>/dev/null; then
+  echo "BLOCKED: old_string not found in $FILE." >&2
+  echo "The file may have been modified by a prior edit in this batch." >&2
+  echo "Re-read the file to get the current content before retrying." >&2
+  exit 2
+fi
+
+exit 0

package/examples/encoding-preserve-guard.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# ================================================================
+# encoding-preserve-guard.sh — Warn when file encoding changes
+# ================================================================
+# PURPOSE:
+#   Claude's Write tool always outputs UTF-8. When editing files
+#   that use different encodings (UTF-8 BOM, Latin-1, Shift-JIS),
+#   the encoding silently changes, potentially corrupting content.
+#   Common in legacy codebases, .csv exports, Windows batch files.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Write|Edit"
+# ================================================================
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+[[ "$TOOL" != "Write" && "$TOOL" != "Edit" ]] && exit 0
+[ -z "$FILE" ] || [ ! -f "$FILE" ] && exit 0
+
+# Check for BOM (Byte Order Mark)
+if head -c 3 "$FILE" 2>/dev/null | od -An -tx1 | grep -q "ef bb bf"; then
+    echo "WARNING: $FILE has UTF-8 BOM. Write tool may strip the BOM." >&2
+fi
+
+# Check for non-UTF-8 encoding using file command
+ENCODING=$(file -bi "$FILE" 2>/dev/null | grep -oP 'charset=\K\S+')
+if [ -n "$ENCODING" ] && [ "$ENCODING" != "utf-8" ] && [ "$ENCODING" != "us-ascii" ]; then
+    echo "WARNING: $FILE uses $ENCODING encoding. Write tool outputs UTF-8." >&2
+    echo "  This may corrupt non-ASCII characters in the file." >&2
+fi
+
+exit 0

package/examples/git-crypt-worktree-guard.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# git-crypt-worktree-guard.sh — Block worktree creation in git-crypt repos
+#
+# Solves: When Claude creates a worktree in a git-crypt repo,
+#         the smudge filter fails because git-crypt hasn't been
+#         unlocked in the new worktree. This produces destructive
+#         commits that delete all encrypted files (#38538).
+#
+# How it works: Before git worktree add, checks if the repo
+#   uses git-crypt (.gitattributes contains filter=git-crypt).
+#   If yes, blocks the worktree creation with a warning.
+#
+# 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 git worktree add
+if ! echo "$COMMAND" | grep -qE 'git\s+worktree\s+add'; then
+  exit 0
+fi
+
+# Check if repo uses git-crypt
+if [ -f ".gitattributes" ] && grep -q "filter=git-crypt" .gitattributes 2>/dev/null; then
+  echo "BLOCKED: Cannot create worktree in a git-crypt repo." >&2
+  echo "git-crypt is not automatically unlocked in new worktrees." >&2
+  echo "This would produce destructive commits that delete all encrypted files." >&2
+  echo "Work in the main repo instead, or manually run 'git-crypt unlock' in the worktree first." >&2
+  exit 2
+fi
+
+exit 0

package/examples/git-operations-require-approval.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# ================================================================
+# git-operations-require-approval.sh — Block git write operations
+# ================================================================
+# PURPOSE:
+#   Claude Code sometimes ignores CLAUDE.md rules about git commit,
+#   push, and branch creation — performing these operations without
+#   user approval. This hook enforces the restriction at process level.
+#
+# Blocks:
+#   git commit, git push (including --force), git checkout -b,
+#   git switch -c, git branch <name>
+#
+# Does NOT block:
+#   git status, git log, git diff, git show, git branch (list),
+#   git fetch, git stash, git add
+#
+# Handles compound commands (&&, ;, ||) by checking each segment.
+#
+# See: https://github.com/anthropics/claude-code/issues/40695
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
+# ================================================================
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+[ -z "$COMMAND" ] && exit 0
+
+# Skip if the command is inside echo/printf (not actual execution)
+echo "$COMMAND" | grep -qE '^\s*(echo|printf)\s' && exit 0
+
+# Check each segment of compound commands
+check_segment() {
+    local seg="$1"
+    # Trim whitespace
+    seg=$(echo "$seg" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+    [ -z "$seg" ] && return 0
+
+    # git commit
+    if echo "$seg" | grep -qE '\bgit\s+commit\b'; then
+        echo "BLOCKED: git commit requires explicit user approval." >&2
+        echo "Command: $seg" >&2
+        echo "" >&2
+        echo "See: https://github.com/anthropics/claude-code/issues/40695" >&2
+        return 1
+    fi
+
+    # git push (including force variants)
+    if echo "$seg" | grep -qE '\bgit\s+push\b'; then
+        echo "BLOCKED: git push requires explicit user approval." >&2
+        echo "Command: $seg" >&2
+        echo "" >&2
+        echo "See: https://github.com/anthropics/claude-code/issues/40695" >&2
+        return 1
+    fi
+
+    # git checkout -b (branch creation)
+    if echo "$seg" | grep -qE '\bgit\s+checkout\s+(-b|--branch)\b'; then
+        echo "BLOCKED: git branch creation requires explicit user approval." >&2
+        echo "Command: $seg" >&2
+        return 1
+    fi
+
+    # git switch -c / --create (branch creation)
+    if echo "$seg" | grep -qE '\bgit\s+switch\s+(-c|--create)\b'; then
+        echo "BLOCKED: git branch creation requires explicit user approval." >&2
+        echo "Command: $seg" >&2
+        return 1
+    fi
+
+    # git branch <name> (creation, not listing)
+    # git branch without flags or with only -a/-r/-l/--list is listing
+    if echo "$seg" | grep -qE '\bgit\s+branch\s'; then
+        # Allow listing flags
+        if echo "$seg" | grep -qE '\bgit\s+branch\s+(-[arl]|--list|--merged|--no-merged|--contains|-v|--verbose|-d|--delete|-D)\b'; then
+            return 0
+        fi
+        # If it has a name argument after "git branch", it's creation
+        local args
+        args=$(echo "$seg" | sed 's/.*\bgit\s\+branch\s\+//')
+        if [ -n "$args" ] && ! echo "$args" | grep -qE '^\s*$'; then
+            echo "BLOCKED: git branch creation requires explicit user approval." >&2
+            echo "Command: $seg" >&2
+            return 1
+        fi
+    fi
+
+    return 0
+}
+
+# Split on && ; || and check each part
+while IFS= read -r segment; do
+    if ! check_segment "$segment"; then
+        exit 2
+    fi
+done < <(echo "$COMMAND" | sed 's/&&/\n/g; s/;/\n/g; s/||/\n/g')
+
+exit 0

package/examples/line-ending-guard.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# ================================================================
+# line-ending-guard.sh — Warn on CRLF/LF mismatch
+# ================================================================
+# PURPOSE:
+#   Claude Code outputs LF line endings. On Windows/WSL, files may
+#   use CRLF. Editing a CRLF file with LF content creates mixed
+#   line endings, causing test failures, script errors, and git
+#   noise. Especially common in .bat, .cmd, .ps1 files.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Write|Edit"
+# ================================================================
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+[[ "$TOOL" != "Write" && "$TOOL" != "Edit" ]] && exit 0
+[ -z "$FILE" ] || [ ! -f "$FILE" ] && exit 0
+
+# Check if existing file uses CRLF
+if head -c 1000 "$FILE" 2>/dev/null | od -c | grep -q '\\r\\n'; then
+    echo "WARNING: $FILE uses CRLF line endings. Claude outputs LF." >&2
+    echo "  This may create mixed line endings. Consider:" >&2
+    echo "  - Setting .gitattributes: *.bat text eol=crlf" >&2
+    echo "  - Running: unix2dos $FILE (after edit)" >&2
+fi
+
+exit 0

package/examples/permission-pattern-auto-allow.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# permission-pattern-auto-allow.sh — Auto-allow commands matching user-defined patterns
+#
+# Solves: Claude repeatedly asks for permission to run commands
+#         even after "Always Allow" — because the settings use
+#         exact argument matching, not pattern matching (#819).
+#
+# How it works: Maintains a list of regex patterns in an env var
+#   or config file. If the Bash command matches any pattern,
+#   returns allow decision. Bypasses the broken exact-match
+#   permission system entirely.
+#
+# Config: Set ALLOWED_PATTERNS env var or create ~/.claude/allowed-patterns.txt
+#   Example patterns (one per line):
+#     ^npm (test|run|install|ci)
+#     ^git (status|log|diff|add|commit|push|pull|fetch|branch|checkout)
+#     ^(ls|cat|pwd|echo|head|tail|wc|grep|find|which|env)
+#     ^python[23]?\s
+#     ^cargo (build|test|run|check)
+#
+# 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
+
+# Load patterns from file or env
+PATTERN_FILE="${HOME}/.claude/allowed-patterns.txt"
+if [ -f "$PATTERN_FILE" ]; then
+  while IFS= read -r pattern || [ -n "$pattern" ]; do
+    # Skip empty lines and comments
+    [[ -z "$pattern" || "$pattern" == \#* ]] && continue
+    if echo "$COMMAND" | grep -qE "$pattern" 2>/dev/null; then
+      exit 0
+    fi
+  done < "$PATTERN_FILE"
+elif [ -n "${ALLOWED_PATTERNS:-}" ]; then
+  # Fallback: pipe-separated patterns in env var
+  echo "$ALLOWED_PATTERNS" | tr '|' '\n' | while IFS= read -r pattern; do
+    [ -z "$pattern" ] && continue
+    if echo "$COMMAND" | grep -qE "$pattern" 2>/dev/null; then
+      exit 0
+    fi
+  done
+fi
+
+exit 0

package/examples/read-audit-log.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# ================================================================
+# read-audit-log.sh — Log all file read operations for forensics
+# ================================================================
+# PURPOSE:
+#   Creates a searchable audit trail of every file Claude reads.
+#   Useful for:
+#   - Post-incident forensics ("what did Claude access?")
+#   - Detecting prompt injection (tracking reads of untrusted files)
+#   - Understanding context consumption (which files cost tokens)
+#
+# TRIGGER: PostToolUse
+# MATCHER: "Read"
+#
+# OUTPUT: ~/.claude/read-audit.jsonl (append-only)
+# ================================================================
+
+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
+
+AUDIT_FILE="${CC_READ_AUDIT:-$HOME/.claude/read-audit.jsonl}"
+mkdir -p "$(dirname "$AUDIT_FILE")"
+
+# Get file metadata
+SIZE=$(stat -c%s "$FILE" 2>/dev/null || stat -f%z "$FILE" 2>/dev/null || echo 0)
+LINES=$(wc -l < "$FILE" 2>/dev/null || echo 0)
+
+echo "{\"time\":\"$(date -Iseconds)\",\"file\":\"$FILE\",\"size\":$SIZE,\"lines\":$LINES,\"cwd\":\"$(pwd)\"}" >> "$AUDIT_FILE"
+
+exit 0

package/examples/session-duration-guard.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# ================================================================
+# session-duration-guard.sh — Warn on long-running sessions
+# ================================================================
+# PURPOSE:
+#   Model quality degrades in very long sessions due to context
+#   accumulation, compaction artifacts, and attention dilution.
+#   This hook warns at configurable thresholds and suggests
+#   saving state + starting fresh.
+#
+#   Based on 700+ hours of autonomous operation experience.
+#
+# TRIGGER: PostToolUse
+# MATCHER: ""  (all tools)
+#
+# CONFIG:
+#   CC_SESSION_WARN_HOURS=2  (warn after 2 hours, default)
+#   CC_SESSION_CRITICAL_HOURS=4  (critical after 4 hours, default)
+# ================================================================
+
+MARKER="/tmp/cc-session-start-$$"
+WARN_HOURS="${CC_SESSION_WARN_HOURS:-2}"
+CRITICAL_HOURS="${CC_SESSION_CRITICAL_HOURS:-4}"
+
+# Create marker on first run
+if [ ! -f "$MARKER" ]; then
+    date +%s > "$MARKER"
+    exit 0
+fi
+
+# Check every 50 tool calls (not every call)
+COUNTER="/tmp/cc-duration-counter-$$"
+COUNT=$(cat "$COUNTER" 2>/dev/null || echo 0)
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER"
+[ $((COUNT % 50)) -ne 0 ] && exit 0
+
+START=$(cat "$MARKER" 2>/dev/null || echo 0)
+NOW=$(date +%s)
+ELAPSED=$(( (NOW - START) / 3600 ))
+ELAPSED_MIN=$(( (NOW - START) / 60 ))
+
+if [ "$ELAPSED" -ge "$CRITICAL_HOURS" ]; then
+    echo "⚠ CRITICAL: Session running for ${ELAPSED_MIN} minutes (${ELAPSED}+ hours)." >&2
+    echo "  Model quality typically degrades after ${CRITICAL_HOURS} hours." >&2
+    echo "  Save your state and start a new session: /compact then resume later." >&2
+elif [ "$ELAPSED" -ge "$WARN_HOURS" ]; then
+    echo "NOTE: Session running for ${ELAPSED_MIN} minutes. Consider saving state." >&2
+fi
+
+exit 0