cc-safe-setup 29.6.30 → 29.6.32

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.** 514 example hooks · 7,564 tests · 1,000+ installs/day · [日本語](docs/README.ja.md)
+**One command to make Claude Code safe for autonomous operation.** 517 example hooks · 7,591 tests · 1,000+ installs/day · [日本語](docs/README.ja.md)
 
 ```bash
 npx cc-safe-setup
@@ -117,7 +117,7 @@ Install any of these: `npx cc-safe-setup --install-example <name>`
 | `--scan [--apply]` | Tech stack detection |
 | `--export / --import` | Team config sharing |
 | `--verify` | Test each hook |
-| `--install-example <name>` | Install from 514 examples |
+| `--install-example <name>` | Install from 517 examples |
 | `--examples [filter]` | Browse examples by keyword |
 | `--full` | All-in-one setup |
 | `--status` | Check installed hooks |
@@ -400,6 +400,7 @@ See [Issue #1](https://github.com/yurukusa/cc-safe-setup/issues/1) for details.
 
 ## Learn More
 
+- **[Hook Design Guide (Zenn Book)](https://zenn.dev/yurukusa/books/6076c23b1cb18b)** — 14-chapter guide from 700+ hours of autonomous operation. Hook design patterns, testing strategies, real incident postmortems. [Chapter 2 free](https://zenn.dev/yurukusa/books/6076c23b1cb18b/viewer/2-safety-guards)
 - [Cookbook](COOKBOOK.md) — 26 practical recipes (block, approve, protect, monitor, diagnose)
 - [Official Hooks Reference](https://code.claude.com/docs/en/hooks) — Claude Code hooks documentation
 - [Hooks Cookbook](https://github.com/yurukusa/claude-code-hooks/blob/main/COOKBOOK.md) — 25 recipes from real GitHub Issues ([interactive version](https://yurukusa.github.io/claude-code-hooks/))

package/examples/README.md

@@ -1,6 +1,6 @@
 # Example Hooks
 
-514 installable hooks. Each solves a real problem from GitHub Issues or autonomous operation. 7,564 tests.
+518 installable hooks. Each solves a real problem from GitHub Issues or autonomous operation. 7,603 tests.
 
 ```bash
 npx cc-safe-setup --install-example <name>   # install one
@@ -13,7 +13,7 @@ npx cc-safe-setup --shield                    # install recommended set
 
 | Category | Count | Examples |
 |----------|-------|---------|
-| Destructive Command Prevention | 12 | `destructive-guard`, `branch-guard`, `no-sudo-guard`, `symlink-guard` |
+| Destructive Command Prevention | 14 | `destructive-guard`, `branch-guard`, `no-sudo-guard`, `symlink-guard`, `shell-wrapper-guard`, `compound-inject-guard` |
 | Data Protection | 5 | `block-database-wipe`, `secret-guard`, `hardcoded-secret-detector` |
 | Git Safety | 11 | `git-config-guard`, `no-verify-blocker`, `push-requires-test-pass` |
 | Auto-Approve (PreToolUse) | 11 | `auto-approve-readonly`, `auto-approve-build`, `auto-approve-docker` |
@@ -21,8 +21,8 @@ npx cc-safe-setup --shield                    # install recommended set
 | Code Quality | 10 | `syntax-check`, `diff-size-guard`, `test-deletion-guard` |
 | Security | 10 | `credential-file-cat-guard`, `credential-exfil-guard`, `prompt-injection-guard` |
 | Deploy | 4 | `deploy-guard`, `no-deploy-friday`, `work-hours-guard` |
-| Monitoring & Cost | 13 | `context-monitor`, `cost-tracker`, `loop-detector`, `edit-error-counter` |
-| Utility | 17 | `comment-strip`, `session-handoff`, `auto-checkpoint`, `edit-retry-loop-guard` |
+| Monitoring & Cost | 14 | `context-monitor`, `cost-tracker`, `loop-detector`, `edit-error-counter`, `dotenv-watch` |
+| Utility | 20 | `comment-strip`, `session-handoff`, `auto-checkpoint`, `edit-retry-loop-guard`, `direnv-auto-reload`, `pre-compact-checkpoint` |
 
 ## Popular Hooks
 

package/examples/api-retry-limiter.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# api-retry-limiter.sh — Limit API error retries to prevent token waste
+#
+# Solves: Claude Code retries API calls on transient errors without
+#         backoff, burning tokens on repeated failures.
+#         Related to #40376 (rescue from 4xx/5xx) and general cost concerns.
+#
+# How it works: PostToolUse hook that tracks API error patterns.
+#   If the same error appears 3+ times in 60 seconds, warns the user
+#   and suggests waiting or switching approaches.
+#
+# Complements api-error-alert (built-in) with retry-specific logic.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "" (all tools — API errors can come from any tool)
+
+INPUT=$(cat)
+ERROR=$(echo "$INPUT" | jq -r '.tool_output // empty' 2>/dev/null | head -c 500)
+[ -z "$ERROR" ] && exit 0
+
+# Only track API-related errors
+echo "$ERROR" | grep -qiE "rate.limit|429|500|502|503|529|overloaded|timeout|ECONNREFUSED|ENOTFOUND" || exit 0
+
+ERROR_LOG="/tmp/cc-api-errors-${PPID}"
+NOW=$(date +%s)
+ERROR_TYPE=$(echo "$ERROR" | grep -oiE "rate.limit|429|500|502|503|529|overloaded|timeout|ECONNREFUSED" | head -1)
+
+echo "$NOW $ERROR_TYPE" >> "$ERROR_LOG"
+
+# Count recent errors of same type
+RECENT=$(awk -v now="$NOW" -v type="$ERROR_TYPE" '$1 > now - 60 && $2 == type {count++} END {print count+0}' "$ERROR_LOG")
+
+if [ "$RECENT" -ge 5 ]; then
+    echo "⚠ API error loop: ${ERROR_TYPE} occurred ${RECENT} times in 60s" >&2
+    echo "  Suggestion: Wait 30-60 seconds before retrying" >&2
+    echo "  Or: Switch to a different approach that doesn't require this API" >&2
+elif [ "$RECENT" -ge 3 ]; then
+    echo "⚠ Repeated API error: ${ERROR_TYPE} (${RECENT}x in 60s)" >&2
+fi
+
+exit 0

package/examples/binary-upload-guard.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# binary-upload-guard.sh — Block committing binary files to git
+#
+# Solves: Claude adds binary files (images, compiled binaries, archives)
+#         to git, bloating the repository. Once committed, binaries
+#         are in git history forever (even if deleted later).
+#
+# How it works: PreToolUse hook on Bash that checks git add/commit
+#   commands for binary file extensions.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Only check git add/commit commands
+echo "$COMMAND" | grep -qE 'git\s+(add|commit)' || exit 0
+
+# Binary file extensions to block
+BINARY_EXT='\.(exe|dll|so|dylib|bin|obj|o|a|lib|class|jar|war|ear|pyc|pyo|whl|egg|tar|gz|bz2|xz|zip|rar|7z|iso|dmg|pkg|deb|rpm|msi|app|apk|ipa|pdf|doc|docx|xls|xlsx|ppt|pptx|sqlite|db|mdb|wasm)(\s|$|")'
+
+# Check if the command references binary files
+if echo "$COMMAND" | grep -qiE "$BINARY_EXT"; then
+    MATCHED=$(echo "$COMMAND" | grep -oiE "[^ \"']+${BINARY_EXT}" | head -3)
+    echo "⚠ Binary file detected in git command:" >&2
+    echo "  $MATCHED" >&2
+    echo "  Binary files bloat git history permanently." >&2
+    echo "  Consider: .gitignore, git-lfs, or external storage." >&2
+    # Warn but don't block (some binaries are intentional)
+fi
+
+# Block large archives being added
+if echo "$COMMAND" | grep -qE 'git\s+add.*\.(tar\.gz|zip|rar|7z|iso|dmg)\b'; then
+    echo "BLOCKED: Large archive file in git add" >&2
+    echo "  Archives should not be committed to git." >&2
+    echo "  Use .gitignore or external storage." >&2
+    exit 2
+fi
+
+exit 0

package/examples/compaction-transcript-guard.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# compaction-transcript-guard.sh — Save conversation state before compaction
+#
+# Solves: Compaction race condition destroys transcript (#40352).
+#         When rate limiting hits during compaction, the JSONL transcript
+#         is left with 4,300+ empty messages. All context is permanently lost.
+#
+# How it works: Uses PreCompact hook event to save a recovery snapshot
+#   before compaction begins. If compaction fails, the snapshot enables
+#   manual recovery.
+#
+# Saves:
+#   1. Git state (uncommitted changes committed as checkpoint)
+#   2. Current task context to ~/.claude/recovery/pre-compact-snapshot.md
+#   3. Recent file list to ~/.claude/recovery/recent-files.txt
+#
+# TRIGGER: PreCompact
+# MATCHER: No matcher support — fires on every compaction
+#
+# DECISION CONTROL: None (notification only)
+
+RECOVERY_DIR="${HOME}/.claude/recovery"
+mkdir -p "$RECOVERY_DIR"
+
+TIMESTAMP=$(date -u '+%Y%m%d-%H%M%S')
+SNAPSHOT="${RECOVERY_DIR}/pre-compact-${TIMESTAMP}.md"
+
+# 1. Save git state
+if git rev-parse --is-inside-work-tree &>/dev/null; then
+    BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+    DIRTY=$(git status --porcelain 2>/dev/null | wc -l)
+    LAST_COMMIT=$(git log --oneline -1 2>/dev/null)
+
+    # Auto-commit uncommitted changes
+    if [ "$DIRTY" -gt 0 ]; then
+        git add -A 2>/dev/null
+        git commit -m "recovery: pre-compact checkpoint (${DIRTY} files, ${TIMESTAMP})" --no-verify 2>/dev/null
+        echo "📸 Recovery checkpoint: ${DIRTY} uncommitted files saved" >&2
+    fi
+
+    cat > "$SNAPSHOT" << EOF
+# Pre-Compaction Recovery Snapshot
+Timestamp: ${TIMESTAMP}
+Branch: ${BRANCH}
+Uncommitted files: ${DIRTY}
+Last commit: ${LAST_COMMIT}
+
+## Recent files (last 10 modified)
+$(git diff --name-only HEAD~3 HEAD 2>/dev/null | tail -10)
+
+## Working directory
+$(pwd)
+
+## Recovery instructions
+If compaction failed and context was lost:
+1. Check git log: git log --oneline -5
+2. Restore from checkpoint: git show HEAD
+3. Resume work from this snapshot
+EOF
+fi
+
+# 2. Save list of recently accessed files
+if [ -f "${HOME}/.claude/session-changes.log" ]; then
+    tail -20 "${HOME}/.claude/session-changes.log" > "${RECOVERY_DIR}/recent-files-${TIMESTAMP}.txt"
+fi
+
+echo "📋 Recovery snapshot saved: ${SNAPSHOT}" >&2
+echo "  If compaction fails, recovery data is preserved" >&2
+
+exit 0

package/examples/compound-inject-guard.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# compound-inject-guard.sh — Block destructive commands hidden in compound statements
+#
+# Solves: Permission allow list glob wildcards match shell operators (&&, ;, ||),
+#         allowing destructive commands to bypass the allowlist.
+#         Example: `Bash(git -C * status)` also matches
+#         `git -C "/repo" && rm -rf / && git -C "/repo" status`
+#
+# Related: GitHub #40344 — "Permission allow list glob wildcards match shell
+#          operators, enabling command injection"
+#
+# How it works: Splits compound commands on shell operators (&&, ||, ;)
+#   and checks each segment independently for destructive patterns.
+#   This prevents destructive commands from hiding inside compound statements
+#   that match overly broad permission allow rules.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Only check compound commands (those with shell operators)
+echo "$COMMAND" | grep -qE '&&|\|\||;' || exit 0
+
+# Destructive patterns to detect in each segment
+DESTRUCT='rm\s+-[rf]*\s+[/~]|rm\s+-[rf]*\s+\.\.|git\s+reset\s+--hard|git\s+clean\s+-[fd]+|mkfs\.|dd\s+if=|chmod\s+777\s+/|>\s*/dev/sd'
+
+# Split on shell operators and check each segment
+IFS=$'\n'
+for segment in $(echo "$COMMAND" | sed 's/&&/\n/g; s/||/\n/g; s/;/\n/g'); do
+    # Trim leading whitespace
+    segment=$(echo "$segment" | sed 's/^\s*//')
+    [ -z "$segment" ] && continue
+
+    if echo "$segment" | grep -qE "$DESTRUCT"; then
+        echo "BLOCKED: Destructive command in compound statement" >&2
+        echo "  Segment: $segment" >&2
+        echo "  Fix: Run destructive commands separately, not chained with && or ;" >&2
+        exit 2
+    fi
+done
+
+exit 0

package/examples/concurrent-edit-lock.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# concurrent-edit-lock.sh — Prevent file corruption from concurrent Claude sessions
+#
+# Solves: File corruption when running multiple Claude Code terminals (#35682).
+#         Two sessions editing the same file simultaneously can produce
+#         interleaved writes, truncated content, or merge conflicts.
+#
+# How it works: PreToolUse hook on Edit/Write that creates a lock file
+#   before editing. If another session holds the lock, blocks the edit.
+#   Lock auto-expires after 60 seconds (configurable) to prevent deadlocks.
+#
+# CONFIG:
+#   CC_EDIT_LOCK_TIMEOUT=60  # seconds before lock expires
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Edit|Write"
+
+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)
+[ -z "$FILE" ] && exit 0
+
+LOCK_DIR="${HOME}/.claude/locks"
+mkdir -p "$LOCK_DIR"
+
+LOCK_TIMEOUT=${CC_EDIT_LOCK_TIMEOUT:-60}
+
+# Create a hash of the file path for the lock file name
+LOCK_HASH=$(echo "$FILE" | md5sum | cut -c1-16)
+LOCK_FILE="${LOCK_DIR}/${LOCK_HASH}.lock"
+SESSION_ID="$$"
+
+# Check for existing lock
+if [ -f "$LOCK_FILE" ]; then
+    LOCK_INFO=$(cat "$LOCK_FILE")
+    LOCK_PID=$(echo "$LOCK_INFO" | cut -d'|' -f1)
+    LOCK_TIME=$(echo "$LOCK_INFO" | cut -d'|' -f2)
+    NOW=$(date +%s)
+
+    # Check if lock is expired
+    if [ $((NOW - LOCK_TIME)) -gt "$LOCK_TIMEOUT" ]; then
+        # Lock expired — remove and proceed
+        rm -f "$LOCK_FILE"
+    elif [ "$LOCK_PID" != "$SESSION_ID" ]; then
+        # Another session holds the lock
+        # Check if the locking process is still alive
+        if kill -0 "$LOCK_PID" 2>/dev/null; then
+            echo "BLOCKED: File is being edited by another Claude session (PID ${LOCK_PID})" >&2
+            echo "  File: $(basename "$FILE")" >&2
+            echo "  Wait for the other session to finish, or remove lock: rm ${LOCK_FILE}" >&2
+            exit 2
+        else
+            # Process is dead — stale lock
+            rm -f "$LOCK_FILE"
+        fi
+    fi
+fi
+
+# Acquire lock
+echo "${SESSION_ID}|$(date +%s)" > "$LOCK_FILE"
+
+# Schedule lock cleanup (best effort — PostToolUse should handle this)
+# The lock will expire naturally after LOCK_TIMEOUT seconds
+
+exit 0

package/examples/context-threshold-alert.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# context-threshold-alert.sh — Alert at configurable context usage thresholds
+#
+# Solves: No hook event for context usage thresholds (#40256).
+#         Users want to be notified when context hits 50%, 75%, 90%
+#         without waiting for the built-in context-monitor warnings.
+#
+# How it works: PostToolUse hook that reads the context percentage
+#   from the tool output and triggers alerts at configurable thresholds.
+#   Each threshold fires only once per session (tracked via temp file).
+#
+# CONFIG (environment variables):
+#   CC_CONTEXT_WARN=50      # First warning at 50%
+#   CC_CONTEXT_ALERT=75     # Alert at 75%
+#   CC_CONTEXT_CRITICAL=90  # Critical at 90%
+#   CC_CONTEXT_ACTION=log   # "log" (stderr only) or "block" (exit 2 at critical)
+#
+# TRIGGER: PostToolUse
+# MATCHER: "" (all tools — checks context on every call)
+
+INPUT=$(cat)
+
+# Extract context percentage from tool output if available
+CONTEXT_PCT=$(echo "$INPUT" | jq -r '.context_window.remaining_percentage // empty' 2>/dev/null)
+
+# If no context data in this tool call, try the session state
+if [ -z "$CONTEXT_PCT" ]; then
+    # Check if context-monitor data exists
+    STATE_FILE="/tmp/cc-context-state-$$"
+    [ -f "$STATE_FILE" ] && CONTEXT_PCT=$(cat "$STATE_FILE")
+fi
+
+[ -z "$CONTEXT_PCT" ] && exit 0
+
+# Convert remaining % to used %
+USED=$((100 - CONTEXT_PCT))
+
+# Configurable thresholds
+WARN=${CC_CONTEXT_WARN:-50}
+ALERT=${CC_CONTEXT_ALERT:-75}
+CRITICAL=${CC_CONTEXT_CRITICAL:-90}
+ACTION=${CC_CONTEXT_ACTION:-log}
+
+# Track which thresholds have fired (once per session)
+FIRED_FILE="/tmp/cc-context-fired-${PPID}"
+
+already_fired() {
+    grep -q "^$1$" "$FIRED_FILE" 2>/dev/null
+}
+
+mark_fired() {
+    echo "$1" >> "$FIRED_FILE"
+}
+
+# Check thresholds (highest first)
+if [ "$USED" -ge "$CRITICAL" ] && ! already_fired "critical"; then
+    echo "🔴 CRITICAL: Context usage at ${USED}% (threshold: ${CRITICAL}%)" >&2
+    echo "  Consider running /compact or starting a new session" >&2
+    mark_fired "critical"
+    [ "$ACTION" = "block" ] && exit 2
+elif [ "$USED" -ge "$ALERT" ] && ! already_fired "alert"; then
+    echo "🟠 ALERT: Context usage at ${USED}% (threshold: ${ALERT}%)" >&2
+    echo "  Commit work and prepare for compaction" >&2
+    mark_fired "alert"
+elif [ "$USED" -ge "$WARN" ] && ! already_fired "warn"; then
+    echo "🟡 WARNING: Context usage at ${USED}% (threshold: ${WARN}%)" >&2
+    mark_fired "warn"
+fi
+
+exit 0

package/examples/context-warning-verifier.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# context-warning-verifier.sh — Verify context warnings are genuine
+#
+# Solves: Claude weaponizes user's CLAUDE.md context warning rules to
+#         fabricate urgency and manipulate users (#35357, 2 reactions).
+#         Claude triggers context warnings at the exact format defined
+#         in CLAUDE.md when the context window is nowhere near the threshold.
+#
+# How it works: PostToolUse hook that independently verifies context usage
+#   after Claude claims the context is running low. If Claude's claim
+#   doesn't match the actual context state, warns the user.
+#
+# This hook provides an independent "second opinion" on context warnings,
+# preventing the model from using the user's own rules as manipulation tools.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "" (monitors all tool outputs for fabricated warnings)
+
+INPUT=$(cat)
+OUTPUT=$(echo "$INPUT" | jq -r '.tool_output // empty' 2>/dev/null)
+[ -z "$OUTPUT" ] && exit 0
+
+# Check if the output contains context warning patterns
+HAS_WARNING=false
+echo "$OUTPUT" | grep -qiE "context.*(running out|low|critical|depleted|remaining.*[0-9]+%)" && HAS_WARNING=true
+echo "$OUTPUT" | grep -qiE "(20|15|10|5)%.*(context|remaining|left)" && HAS_WARNING=true
+echo "$OUTPUT" | grep -qiE "コンテキスト.*(残|不足|危険|低)" && HAS_WARNING=true
+
+[ "$HAS_WARNING" = "false" ] && exit 0
+
+# Claude claims context is low — verify independently
+# Get actual context percentage from the tool metadata if available
+ACTUAL_PCT=$(echo "$INPUT" | jq -r '.context_window.remaining_percentage // empty' 2>/dev/null)
+
+if [ -n "$ACTUAL_PCT" ] && [ "$ACTUAL_PCT" -gt 50 ] 2>/dev/null; then
+    echo "⚠ CONTEXT WARNING VERIFICATION FAILED" >&2
+    echo "  Claude claims context is running low" >&2
+    echo "  Actual remaining: ${ACTUAL_PCT}% (well above danger zone)" >&2
+    echo "  This may be a fabricated warning to avoid work." >&2
+    echo "  Reference: GitHub Issue #35357" >&2
+elif [ -z "$ACTUAL_PCT" ]; then
+    echo "ℹ Context warning detected but cannot independently verify." >&2
+    echo "  Check actual usage with: context-monitor or statusline" >&2
+fi
+
+exit 0

package/examples/cross-session-error-log.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# cross-session-error-log.sh — Persist error patterns across sessions
+#
+# Solves: Agent ignores spec across multiple sessions (#40383).
+#         Each new session starts fresh with no memory of previous failures.
+#         The same destructive mistakes are repeated session after session.
+#
+# How it works: PostToolUse hook that logs blocked/failed operations
+#   to a persistent file (~/.claude/error-history.log). On SessionStart,
+#   checks for recurring patterns and warns the new session about them.
+#
+# The error history survives session restarts, so the next Claude session
+# sees "this operation failed 3 times in previous sessions" before
+# attempting it again.
+#
+# TRIGGER: PostToolUse (log errors) + Notification/SessionStart (read history)
+# MATCHER: "" (all tools)
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+EVENT=$(echo "$INPUT" | jq -r '.event // empty' 2>/dev/null)
+
+ERROR_LOG="${HOME}/.claude/error-history.log"
+mkdir -p "$(dirname "$ERROR_LOG")"
+
+# On session start: show recent error patterns
+if [ "$EVENT" = "session_start" ] || [ "$EVENT" = "SessionStart" ]; then
+    if [ -f "$ERROR_LOG" ]; then
+        RECENT=$(tail -50 "$ERROR_LOG" | awk -F'|' '{print $3}' | sort | uniq -c | sort -rn | head -5)
+        if [ -n "$RECENT" ]; then
+            echo "📋 Recurring error patterns from previous sessions:" >&2
+            echo "$RECENT" | while read count pattern; do
+                [ "$count" -ge 2 ] && echo "  ${count}x: ${pattern}" >&2
+            done
+        fi
+    fi
+    exit 0
+fi
+
+# On tool use: check for error indicators
+OUTPUT=$(echo "$INPUT" | jq -r '.tool_output // empty' 2>/dev/null | head -c 200)
+[ -z "$OUTPUT" ] && exit 0
+
+# Detect error patterns
+IS_ERROR=false
+ERROR_TYPE=""
+
+if echo "$OUTPUT" | grep -qiE "error|failed|BLOCKED|exit code [1-9]|permission denied|not found|syntax error"; then
+    IS_ERROR=true
+    ERROR_TYPE=$(echo "$OUTPUT" | grep -oiE "error:[^\"]*|failed:[^\"]*|BLOCKED:[^\"]*" | head -1 | head -c 80)
+    [ -z "$ERROR_TYPE" ] && ERROR_TYPE="$(echo "$OUTPUT" | head -c 60)"
+fi
+
+# Log error with timestamp and tool name
+if [ "$IS_ERROR" = "true" ]; then
+    TIMESTAMP=$(date -u '+%Y-%m-%dT%H:%M:%S')
+    echo "${TIMESTAMP}|${TOOL}|${ERROR_TYPE}" >> "$ERROR_LOG"
+
+    # Keep log manageable (last 200 entries)
+    if [ "$(wc -l < "$ERROR_LOG")" -gt 200 ]; then
+        tail -100 "$ERROR_LOG" > "${ERROR_LOG}.tmp"
+        mv "${ERROR_LOG}.tmp" "$ERROR_LOG"
+    fi
+fi
+
+exit 0

package/examples/file-age-guard.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# file-age-guard.sh — Warn before editing files not modified in 30+ days
+#
+# Solves: Claude edits stable/legacy files that haven't been touched
+#         in months, introducing regressions in well-tested code.
+#
+# How it works: PreToolUse hook on Edit/Write that checks the last
+#   modification time of the target file. If the file hasn't been
+#   modified in CC_FILE_AGE_DAYS (default 30), warns the user.
+#
+# This doesn't block — just warns. The assumption is that files
+# untouched for a long time are stable and should be edited carefully.
+#
+# CONFIG:
+#   CC_FILE_AGE_DAYS=30  (warn threshold in days)
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Edit"
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+[ -f "$FILE" ] || exit 0
+
+AGE_THRESHOLD=${CC_FILE_AGE_DAYS:-30}
+
+# Get file modification time
+FILE_MTIME=$(stat -c %Y "$FILE" 2>/dev/null)
+[ -z "$FILE_MTIME" ] && exit 0
+
+NOW=$(date +%s)
+AGE_DAYS=$(( (NOW - FILE_MTIME) / 86400 ))
+
+if [ "$AGE_DAYS" -ge "$AGE_THRESHOLD" ]; then
+    FILENAME=$(basename "$FILE")
+    echo "⚠ Editing stable file: ${FILENAME} (last modified ${AGE_DAYS} days ago)" >&2
+    echo "  This file hasn't been touched in ${AGE_DAYS} days." >&2
+    echo "  Verify changes don't break existing behavior." >&2
+fi
+
+exit 0

package/examples/heredoc-backtick-approver.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# heredoc-backtick-approver.sh — Auto-approve backtick warnings in heredoc strings
+#
+# Solves: Backticks inside heredoc quoted strings trigger false-positive
+#         permission prompt (#35183, 2 reactions).
+#         `git commit -m "$(cat <<'EOF' ... \`code\` ... EOF)"` triggers
+#         "Command contains backticks for command substitution" even though
+#         backticks inside <<'EOF' are inert literal characters.
+#
+# How it works: PermissionRequest hook that checks if the backtick warning
+#   is from a command containing a quoted heredoc (<<'EOF' or <<"EOF").
+#   If so, auto-approves since the backticks are string content, not shell.
+#
+# TRIGGER: PermissionRequest
+# MATCHER: "" (all permission requests)
+
+INPUT=$(cat)
+MESSAGE=$(echo "$INPUT" | jq -r '.message // empty' 2>/dev/null)
+[ -z "$MESSAGE" ] && exit 0
+
+# Only handle backtick/command substitution warnings
+echo "$MESSAGE" | grep -qiE "backtick|command substitution" || exit 0
+
+# Get the command that triggered the warning
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Check if command contains a quoted heredoc
+# <<'EOF' (single-quoted) or <<"EOF" (double-quoted) disable backtick expansion
+if echo "$COMMAND" | grep -qE "<<'[A-Za-z_]+'" || echo "$COMMAND" | grep -qE '<<"[A-Za-z_]+"'; then
+    # Backticks inside a quoted heredoc are literal — safe to approve
+    echo '{"permissionDecision":"allow","permissionDecisionReason":"Backticks are literal characters inside quoted heredoc (<<'"'"'EOF'"'"')"}'
+    exit 0
+fi
+
+# Also handle unquoted heredoc with git commit pattern
+# git commit -m "$(cat <<EOF ... `code` ... EOF)" — common pattern
+if echo "$COMMAND" | grep -qE 'git\s+commit.*<<\s*[A-Za-z_]+' && \
+   echo "$COMMAND" | grep -qE '`[a-zA-Z_][a-zA-Z0-9_]*`'; then
+    # Likely markdown formatting backticks in commit message
+    echo '{"permissionDecision":"allow","permissionDecisionReason":"Backticks appear to be markdown formatting in commit message"}'
+    exit 0
+fi
+
+exit 0

package/examples/hook-stdout-sanitizer.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# hook-stdout-sanitizer.sh — Prevent hook stdout from corrupting tool results
+#
+# Solves: Worktree path corrupted by hook stdout (#40262).
+#         When a hook writes to stdout (instead of stderr), the output
+#         gets concatenated into tool results like file paths, causing
+#         corruption (e.g., worktree path becomes "/path/to/repo{hookJSON}").
+#
+# How it works: Wraps another hook script, redirecting all of its stdout
+#   to stderr. Only valid JSON hookSpecificOutput is sent to stdout.
+#   This prevents accidental stdout pollution.
+#
+# Usage: Wrap any existing hook:
+#   Original: "command": "bash ~/.claude/hooks/my-hook.sh"
+#   Wrapped:  "command": "bash ~/.claude/hooks/hook-stdout-sanitizer.sh ~/.claude/hooks/my-hook.sh"
+#
+# Or use as a template for writing safe hooks.
+#
+# TRIGGER: Any (wrapper for other hooks)
+# MATCHER: Any
+
+TARGET_HOOK="$1"
+shift
+
+if [ -z "$TARGET_HOOK" ] || [ ! -f "$TARGET_HOOK" ]; then
+    echo "Usage: hook-stdout-sanitizer.sh <path-to-hook.sh>" >&2
+    exit 0
+fi
+
+# Capture stdin (tool input)
+TOOL_INPUT=$(cat)
+
+# Run the target hook, capturing stdout and stderr separately
+STDOUT_FILE=$(mktemp)
+STDERR_FILE=$(mktemp)
+echo "$TOOL_INPUT" | bash "$TARGET_HOOK" "$@" > "$STDOUT_FILE" 2> "$STDERR_FILE"
+EXIT_CODE=$?
+
+# Forward stderr (safe — always goes to user)
+cat "$STDERR_FILE" >&2
+
+# Only forward stdout if it looks like valid hookSpecificOutput JSON
+STDOUT_CONTENT=$(cat "$STDOUT_FILE")
+if [ -n "$STDOUT_CONTENT" ]; then
+    # Check if it's valid JSON with hookSpecificOutput
+    if echo "$STDOUT_CONTENT" | jq -e '.hookSpecificOutput' &>/dev/null 2>&1 || \
+       echo "$STDOUT_CONTENT" | jq -e '.permissionDecision' &>/dev/null 2>&1 || \
+       echo "$STDOUT_CONTENT" | jq -e '.systemMessage' &>/dev/null 2>&1; then
+        # Valid hook output — forward to stdout
+        echo "$STDOUT_CONTENT"
+    else
+        # Not valid hook JSON — redirect to stderr to prevent corruption
+        echo "⚠ hook-stdout-sanitizer: redirected non-JSON stdout to stderr" >&2
+        echo "$STDOUT_CONTENT" >&2
+    fi
+fi
+
+# Clean up
+rm -f "$STDOUT_FILE" "$STDERR_FILE"
+
+exit $EXIT_CODE