cc-safe-setup 29.6.31 → 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

package/examples/max-concurrent-agents.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# max-concurrent-agents.sh — Limit number of simultaneous subagents
+#
+# Solves: Uncontrolled agent spawning burns through rate limits and tokens.
+#         A single prompt like "research 10 topics" can spawn 10 agents,
+#         each consuming context and API calls simultaneously.
+#
+# How it works: PreToolUse hook on "Agent" that tracks active agents
+#   via a counter file. Blocks new agents when the limit is reached.
+#   Counter is decremented by a companion PostToolUse hook or timeout.
+#
+# CONFIG:
+#   CC_MAX_AGENTS=3  (default: 3 concurrent agents)
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Agent"
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ "$TOOL" != "Agent" ] && exit 0
+
+MAX_AGENTS=${CC_MAX_AGENTS:-3}
+COUNTER_FILE="/tmp/cc-agent-count-${PPID}"
+
+# Initialize counter
+[ -f "$COUNTER_FILE" ] || echo "0" > "$COUNTER_FILE"
+
+# Read current count
+CURRENT=$(cat "$COUNTER_FILE" 2>/dev/null || echo 0)
+
+# Clean up stale counts (reset if file is older than 10 minutes)
+if [ -f "$COUNTER_FILE" ]; then
+    AGE=$(( $(date +%s) - $(stat -c %Y "$COUNTER_FILE" 2>/dev/null || echo 0) ))
+    [ "$AGE" -gt 600 ] && echo "0" > "$COUNTER_FILE" && CURRENT=0
+fi
+
+if [ "$CURRENT" -ge "$MAX_AGENTS" ]; then
+    echo "BLOCKED: Maximum concurrent agents reached (${CURRENT}/${MAX_AGENTS})" >&2
+    echo "  Wait for existing agents to complete before spawning new ones." >&2
+    echo "  Set CC_MAX_AGENTS to increase the limit." >&2
+    exit 2
+fi
+
+# Increment counter
+echo $((CURRENT + 1)) > "$COUNTER_FILE"
+exit 0

package/examples/mcp-config-freeze.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# mcp-config-freeze.sh — Prevent MCP configuration changes during session
+#
+# Solves: Shadow MCP servers added mid-session (OWASP MCP09).
+#         An agent or prompt injection could modify .mcp.json or
+#         settings.json to add unauthorized MCP servers.
+#
+# How it works: On SessionStart, snapshots the current MCP config.
+#   On subsequent Edit/Write to config files, compares against snapshot.
+#   Blocks changes that add new MCP servers.
+#
+# Complements mcp-server-guard.sh (which blocks Bash-based server launches)
+# by also covering config file modification.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Edit|Write"
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+
+# Only check MCP-related config files
+FILENAME=$(basename "$FILE")
+case "$FILENAME" in
+    .mcp.json|mcp.json|mcp-config.json)
+        ;;
+    settings.json|settings.local.json)
+        # Check if the edit adds mcpServers
+        CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty' 2>/dev/null)
+        if echo "$CONTENT" | grep -qiE 'mcpServers|mcp_servers'; then
+            echo "BLOCKED: MCP server configuration change detected" >&2
+            echo "  File: $FILE" >&2
+            echo "  MCP server additions require manual approval." >&2
+            echo "  Edit the file manually or remove this hook temporarily." >&2
+            exit 2
+        fi
+        exit 0
+        ;;
+    *)
+        exit 0
+        ;;
+esac
+
+# For .mcp.json files, block all modifications
+echo "BLOCKED: MCP configuration file is frozen during this session" >&2
+echo "  File: $FILE" >&2
+echo "  To modify MCP config, edit the file manually outside Claude Code." >&2
+exit 2

package/examples/mcp-data-boundary.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# mcp-data-boundary.sh — Prevent MCP tools from accessing sensitive paths
+#
+# Solves: MCP tools can read/write files outside the intended scope.
+#         A rogue or misconfigured MCP server could exfiltrate credentials
+#         or modify system files. (OWASP MCP01 + MCP10)
+#
+# How it works: PostToolUse hook that checks MCP tool results for
+#   sensitive file path references. Warns if an MCP tool accessed
+#   paths outside the project directory.
+#
+# CONFIG:
+#   CC_MCP_ALLOWED_PATHS="/home/user/project"  (colon-separated)
+#
+# TRIGGER: PostToolUse
+# MATCHER: "" (monitors all tools, focuses on MCP tool outputs)
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+OUTPUT=$(echo "$INPUT" | jq -r '.tool_output // empty' 2>/dev/null | head -c 2000)
+[ -z "$OUTPUT" ] && exit 0
+
+# Only check MCP tool outputs (tool names starting with mcp__)
+echo "$TOOL" | grep -q '^mcp__' || exit 0
+
+# Check for sensitive path patterns in output
+SENSITIVE_PATHS='/etc/passwd|/etc/shadow|\.ssh/|\.aws/|\.env|credentials|\.npmrc|\.pypirc|\.netrc|\.gnupg|\.kube/config'
+
+if echo "$OUTPUT" | grep -qiE "$SENSITIVE_PATHS"; then
+    echo "⚠ MCP DATA BOUNDARY: MCP tool accessed sensitive path" >&2
+    echo "  Tool: $TOOL" >&2
+    echo "  Detected sensitive path reference in output." >&2
+    echo "  Review the MCP server's file access scope." >&2
+fi
+
+# Check for data that looks like secrets in output
+if echo "$OUTPUT" | grep -qE 'sk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{30,}|-----BEGIN.*KEY|AKIA[A-Z0-9]{16}'; then
+    echo "⚠ MCP DATA BOUNDARY: MCP tool output contains potential secrets" >&2
+    echo "  Tool: $TOOL" >&2
+    echo "  Review output for leaked credentials." >&2
+fi
+
+exit 0

package/examples/no-git-amend.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# no-git-amend.sh — Block git commit --amend to prevent overwriting previous commits
+#
+# Solves: Claude Code amending previous commits instead of creating new ones.
+#         When a pre-commit hook fails, the commit doesn't happen. If Claude
+#         then runs --amend to "fix" it, it modifies the PREVIOUS commit
+#         instead of creating a new one — potentially destroying prior work.
+#
+# This is explicitly recommended in Claude Code's own system prompt:
+#   "Always create NEW commits rather than amending"
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Block git commit --amend
+if echo "$COMMAND" | grep -qE 'git\s+commit\s+.*--amend|git\s+commit\s+--amend'; then
+    echo "BLOCKED: git commit --amend is not allowed" >&2
+    echo "  Create a new commit instead: git commit -m 'fix: ...'" >&2
+    echo "  Amending can overwrite the previous commit's changes." >&2
+    exit 2
+fi
+
+exit 0

package/examples/path-deny-bash-guard.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# path-deny-bash-guard.sh — Enforce path deny rules on Bash commands
+#
+# Solves: Bash tool bypasses settings.json path deny rules (#39987).
+#         Read/Glob/Grep respect deny rules, but Bash commands like
+#         `cat /denied/path/file.txt` or `grep pattern /denied/path/`
+#         bypass the restriction entirely.
+#
+# How it works: Reads denied paths from CC_DENIED_PATHS env var or
+#   a config file, then checks if any Bash command argument contains
+#   a denied path.
+#
+# CONFIG:
+#   CC_DENIED_PATHS="/path/one:/path/two:/path/three"
+#   Or create ~/.claude/denied-paths.txt (one path per line)
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Load denied paths
+DENIED_PATHS=""
+
+# Source 1: Environment variable (colon-separated)
+if [ -n "${CC_DENIED_PATHS:-}" ]; then
+    DENIED_PATHS="$CC_DENIED_PATHS"
+fi
+
+# Source 2: Config file (one path per line)
+DENY_FILE="${HOME}/.claude/denied-paths.txt"
+if [ -f "$DENY_FILE" ]; then
+    while IFS= read -r line; do
+        [ -z "$line" ] && continue
+        [[ "$line" =~ ^# ]] && continue
+        if [ -n "$DENIED_PATHS" ]; then
+            DENIED_PATHS="${DENIED_PATHS}:${line}"
+        else
+            DENIED_PATHS="$line"
+        fi
+    done < "$DENY_FILE"
+fi
+
+[ -z "$DENIED_PATHS" ] && exit 0
+
+# Check command against denied paths
+IFS=':'
+for denied_path in $DENIED_PATHS; do
+    [ -z "$denied_path" ] && continue
+    # Normalize: remove trailing slash
+    denied_path="${denied_path%/}"
+
+    if echo "$COMMAND" | grep -qF "$denied_path"; then
+        echo "BLOCKED: Bash command accesses denied path" >&2
+        echo "  Denied: $denied_path" >&2
+        echo "  Command: $(echo "$COMMAND" | head -c 100)" >&2
+        echo "  Note: This path is restricted in your deny rules." >&2
+        echo "        Use Read/Glob/Grep tools which respect deny rules," >&2
+        echo "        or remove the path from denied-paths.txt." >&2
+        exit 2
+    fi
+done
+
+exit 0

package/examples/permission-mode-drift-guard.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# permission-mode-drift-guard.sh — Detect permission mode changes mid-session
+#
+# Solves: Permission mode resets from 'Bypass permissions' to 'Edit automatically'
+#         mid-session without user interaction (#39057, 3 reactions).
+#
+# How it works: On SessionStart, records the initial permission mode.
+#   On each PermissionRequest, compares current behavior against expected.
+#   If permissions are being requested when bypass mode was set,
+#   warns the user that the mode may have drifted.
+#
+# Uses ConfigChange hook event (v2.1.83+) when available, falls back
+# to heuristic detection via unexpected permission prompts.
+#
+# TRIGGER: PermissionRequest (fallback detection)
+# MATCHER: "" (all permission requests)
+
+INPUT=$(cat)
+MESSAGE=$(echo "$INPUT" | jq -r '.message // empty' 2>/dev/null)
+
+STATE_FILE="/tmp/cc-permission-mode-${PPID}"
+
+# On first call, record that we're getting permission prompts
+if [ ! -f "$STATE_FILE" ]; then
+    echo "prompt_count=1" > "$STATE_FILE"
+    echo "first_prompt=$(date +%s)" >> "$STATE_FILE"
+    exit 0
+fi
+
+# Track prompt count
+. "$STATE_FILE"
+prompt_count=$((prompt_count + 1))
+echo "prompt_count=$prompt_count" > "$STATE_FILE"
+echo "first_prompt=$first_prompt" >> "$STATE_FILE"
+
+# If we're getting many permission prompts, something may be wrong
+if [ "$prompt_count" -eq 5 ]; then
+    echo "⚠ Permission mode drift detected: ${prompt_count} permission prompts this session" >&2
+    echo "  If you set 'Bypass permissions', it may have reset to 'Edit automatically'" >&2
+    echo "  Check: Ctrl+Shift+P → Claude Code: Set Permission Mode" >&2
+fi
+
+if [ "$prompt_count" -eq 20 ]; then
+    echo "⚠ ${prompt_count} permission prompts — consider re-enabling bypass mode" >&2
+fi
+
+exit 0

package/examples/plan-mode-strict-guard.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# plan-mode-strict-guard.sh — Hard-block all write operations during plan mode
+#
+# Solves: Plan mode doesn't hard-block write tools (#40324, 0 reactions).
+#         When Claude is in plan mode, it should only read and analyze.
+#         But the model can propose Edit/Write operations, and if the user
+#         clicks "approve", they execute — defeating the purpose of plan mode.
+#
+# How it works: Checks for plan mode indicators:
+#   1. CC_PLAN_MODE env var (set by some configurations)
+#   2. .claude/plan-mode.lock file (created by plan-mode-enforcer.sh)
+#   3. Plan-related keywords in the session context
+#
+# When plan mode is active, blocks Edit, Write, and dangerous Bash commands.
+# Read, Glob, Grep, and safe Bash commands are allowed.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Edit|Write|Bash"
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ -z "$TOOL" ] && exit 0
+
+# Check if plan mode is active
+PLAN_MODE=false
+
+# Method 1: Environment variable
+[ "${CC_PLAN_MODE:-}" = "true" ] && PLAN_MODE=true
+
+# Method 2: Lock file
+[ -f "${HOME}/.claude/plan-mode.lock" ] && PLAN_MODE=true
+
+# Method 3: Project-level plan lock
+[ -f ".claude/plan-mode.lock" ] && PLAN_MODE=true
+
+[ "$PLAN_MODE" = "false" ] && exit 0
+
+# Plan mode is active — enforce read-only
+case "$TOOL" in
+    Edit|Write)
+        echo "BLOCKED: Plan mode is active — write operations are not allowed" >&2
+        echo "  Exit plan mode first, then make changes" >&2
+        echo "  Remove ~/.claude/plan-mode.lock or unset CC_PLAN_MODE" >&2
+        exit 2
+        ;;
+    Bash)
+        CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+        [ -z "$CMD" ] && exit 0
+
+        # Allow read-only commands in plan mode
+        # Strip compound operators to get the first command
+        FIRST_PART=$(echo "$CMD" | sed 's/[;&|].*//' | sed 's/^\s*//')
+
+        # Single-word safe commands
+        FIRST_WORD=$(echo "$FIRST_PART" | awk '{print $1}')
+        SAFE_SINGLE="ls|cat|head|tail|grep|find|wc|diff|pwd|echo|date|which|type|file|tree|du|df|env|printenv"
+        if echo "$FIRST_WORD" | grep -qxE "$SAFE_SINGLE"; then
+            exit 0
+        fi
+
+        # Two-word safe commands (git, npm, etc.)
+        FIRST_TWO=$(echo "$FIRST_PART" | awk '{print $1, $2}')
+        SAFE_TWO="git status|git log|git diff|git branch|git show|git rev-parse|git tag|node -v|python3 -V|npm list|npm outdated|pip list|pip show"
+        if echo "$FIRST_TWO" | grep -qxE "$SAFE_TWO"; then
+            exit 0
+        fi
+
+        # Block write commands in plan mode
+        echo "BLOCKED: Plan mode is active — only read-only Bash commands allowed" >&2
+        echo "  Allowed: ls, cat, grep, git status/log/diff, etc." >&2
+        exit 2
+        ;;
+esac
+
+exit 0

package/examples/sandbox-write-verify.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# sandbox-write-verify.sh — Verify file existence before overwrite in sandbox mode
+#
+# Solves: Sandbox half-broken — writes hit real filesystem (#40321).
+#         When sandbox reads are isolated but writes pass through,
+#         Claude overwrites real files it can't see, destroying projects.
+#
+# How it works: Before Edit/Write operations, checks if the target file
+#   exists on the REAL filesystem (not sandboxed). If Claude is about to
+#   overwrite an existing file and can't read it (sandbox read isolation),
+#   blocks the write.
+#
+# Also detects bulk writes (>10 files in quick succession) which is
+# a sign of runaway overwrite behavior.
+#
+# 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
+
+# Track writes per session to detect bulk overwrite
+WRITE_LOG="/tmp/cc-sandbox-writes-${PPID}"
+echo "$(date +%s) $FILE" >> "$WRITE_LOG" 2>/dev/null
+
+# Check for bulk writes (>10 in last 60 seconds)
+if [ -f "$WRITE_LOG" ]; then
+    NOW=$(date +%s)
+    RECENT=$(awk -v now="$NOW" '$1 > now - 60 {count++} END {print count+0}' "$WRITE_LOG")
+    if [ "$RECENT" -gt 10 ]; then
+        echo "BLOCKED: Bulk write detected (${RECENT} files in 60s)" >&2
+        echo "  This may indicate a sandbox read/write mismatch." >&2
+        echo "  Verify sandbox state before continuing." >&2
+        exit 2
+    fi
+fi
+
+# Check if target file exists and is non-empty (potential overwrite)
+if [ -f "$FILE" ] && [ -s "$FILE" ]; then
+    # File exists. Check if it's in a project directory
+    DIR=$(dirname "$FILE")
+    # Count files in the same directory that were recently written
+    DIR_WRITES=$(grep -c "$DIR" "$WRITE_LOG" 2>/dev/null || echo 0)
+    if [ "$DIR_WRITES" -gt 5 ]; then
+        echo "WARNING: ${DIR_WRITES} writes to $(basename "$DIR")/ — verify sandbox state" >&2
+    fi
+fi
+
+exit 0

package/examples/session-resume-guard.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# session-resume-guard.sh — Verify context is loaded after session resume
+#
+# Solves: Session resume loads zero conversation history (#40319).
+#         When --continue resumes a long session, cache_read_input_tokens
+#         can drop from 434k to 0, silently losing all context.
+#
+# How it works: On SessionStart, checks if this is a resumed session
+#   (via CC_RESUME or --continue flag indicators). If so, verifies that
+#   key context files exist and warns if they might be stale.
+#
+# Also saves a "session handoff" file on Stop, so the next session
+# can detect if context was properly transferred.
+#
+# TRIGGER: Notification (SessionStart)
+# MATCHER: "" (fires on all notifications, filters for SessionStart internally)
+
+INPUT=$(cat)
+EVENT=$(echo "$INPUT" | jq -r '.event // empty' 2>/dev/null)
+
+HANDOFF_DIR="${HOME}/.claude/handoff"
+mkdir -p "$HANDOFF_DIR"
+HANDOFF_FILE="${HANDOFF_DIR}/last-session.md"
+
+case "$EVENT" in
+    session_start|SessionStart)
+        # Check if this is a resume (handoff file exists and is recent)
+        if [ -f "$HANDOFF_FILE" ]; then
+            AGE_SECONDS=$(( $(date +%s) - $(stat -c %Y "$HANDOFF_FILE" 2>/dev/null || echo 0) ))
+
+            if [ "$AGE_SECONDS" -lt 3600 ]; then
+                echo "📋 Resuming from previous session (handoff ${AGE_SECONDS}s ago)" >&2
+                echo "  Last session state:" >&2
+                head -5 "$HANDOFF_FILE" >&2
+            else
+                AGE_HOURS=$((AGE_SECONDS / 3600))
+                echo "⚠ Previous session handoff is ${AGE_HOURS}h old" >&2
+                echo "  Context may be stale. Consider starting fresh." >&2
+            fi
+        fi
+
+        # Check for recovery snapshots (from compaction-transcript-guard)
+        RECOVERY_DIR="${HOME}/.claude/recovery"
+        if [ -d "$RECOVERY_DIR" ]; then
+            LATEST=$(ls -t "$RECOVERY_DIR"/pre-compact-*.md 2>/dev/null | head -1)
+            if [ -n "$LATEST" ]; then
+                AGE=$(( $(date +%s) - $(stat -c %Y "$LATEST" 2>/dev/null || echo 0) ))
+                if [ "$AGE" -lt 7200 ]; then
+                    echo "📸 Recent compaction recovery snapshot found ($(( AGE / 60 ))m ago)" >&2
+                    echo "  Path: $LATEST" >&2
+                fi
+            fi
+        fi
+        ;;
+
+    session_end|Stop)
+        # Save handoff for next session
+        cat > "$HANDOFF_FILE" << EOF
+# Session Handoff
+Timestamp: $(date -u '+%Y-%m-%dT%H:%M:%SZ')
+Working directory: $(pwd)
+Branch: $(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'N/A')
+Uncommitted: $(git status --porcelain 2>/dev/null | wc -l) files
+Last commit: $(git log --oneline -1 2>/dev/null || echo 'N/A')
+EOF
+        echo "📋 Session handoff saved for next resume" >&2
+        ;;
+esac
+
+exit 0

package/examples/subagent-scope-validator.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# subagent-scope-validator.sh — Validate subagent task scope before launch
+#
+# Solves: Main agent's subagent delegation produces poor scoping (#40339).
+#         Subagents are launched with vague prompts, missing context,
+#         and no result verification criteria.
+#
+# How it works: PreToolUse hook on "Agent" that checks the prompt
+#   for minimum scope requirements:
+#   1. Prompt must be longer than 50 characters (not just "do X")
+#   2. Must contain file paths or specific identifiers
+#   3. Warns if no success criteria are mentioned
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Agent"
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ "$TOOL" != "Agent" ] && exit 0
+
+PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // empty' 2>/dev/null)
+[ -z "$PROMPT" ] && exit 0
+
+PROMPT_LEN=${#PROMPT}
+WARNINGS=""
+
+# Check 1: Minimum prompt length
+if [ "$PROMPT_LEN" -lt 50 ]; then
+    WARNINGS="${WARNINGS}\n  - Prompt is only ${PROMPT_LEN} chars. Subagents need detailed context (50+ chars recommended)"
+fi
+
+# Check 2: Contains specific identifiers (files, functions, paths)
+if ! echo "$PROMPT" | grep -qE '/[a-zA-Z]|\.ts|\.py|\.js|\.md|\.json|\.sh|function |class |def |const |let |var '; then
+    WARNINGS="${WARNINGS}\n  - No file paths or code identifiers found. Subagent may lack context"
+fi
+
+# Check 3: Success criteria
+if ! echo "$PROMPT" | grep -qiE 'verify|confirm|test|check|ensure|must|should|expect|return|report'; then
+    WARNINGS="${WARNINGS}\n  - No success criteria detected. Consider adding verification steps"
+fi
+
+# Output warnings (don't block — just inform)
+if [ -n "$WARNINGS" ]; then
+    echo "⚠ Subagent scope review:" >&2
+    echo -e "$WARNINGS" >&2
+    echo "  Prompt preview: $(echo "$PROMPT" | head -c 100)..." >&2
+fi
+
+exit 0

package/examples/windows-path-guard.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# windows-path-guard.sh — Prevent NTFS junction/symlink traversal destruction
+#
+# Solves: rm -rf following NTFS junctions to delete user directories (#36339).
+#         On Windows (WSL/Git Bash), `rm -rf` can traverse NTFS junctions
+#         and delete system directories like C:\Users.
+#
+# How it works: Before rm operations, checks if the target path is
+#   a symlink or junction that points outside the project directory.
+#   Blocks rm if it would traverse to a system-critical location.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Only check rm commands
+echo "$COMMAND" | grep -qE '^\s*rm\s|;\s*rm\s|&&\s*rm\s' || exit 0
+
+# Check the entire command for Windows system paths
+# This catches both direct paths and quoted paths with spaces
+WINDOWS_SYSTEM='/mnt/[a-z]/(Users|Windows|Program Files|Program)'
+if echo "$COMMAND" | grep -qiE "$WINDOWS_SYSTEM"; then
+    echo "BLOCKED: rm targets Windows system directory" >&2
+    echo "  Command contains a Windows system path reference." >&2
+    echo "  This could destroy system files via NTFS junction traversal." >&2
+    echo "  Reference: GitHub Issue #36339" >&2
+    exit 2
+fi
+
+# Check if any rm target is a symlink pointing to system directories
+for target in $(echo "$COMMAND" | grep -oE '/[^ ";\|&]+' | head -10); do
+    [ -L "$target" ] || [ -L "$(dirname "$target" 2>/dev/null)" ] || continue
+    LINK_TARGET=$(readlink -f "$target" 2>/dev/null)
+    [ -z "$LINK_TARGET" ] && continue
+    if echo "$LINK_TARGET" | grep -qiE "^/(mnt/[a-z]/(Users|Windows|Program)|home$|etc$|usr$|var$)"; then
+        echo "BLOCKED: rm would traverse symlink/junction to system directory" >&2
+        echo "  Target: $target → $LINK_TARGET" >&2
+        exit 2
+    fi
+done
+
+exit 0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cc-safe-setup",
-  "version": "29.6.31",
-  "description": "One command to make Claude Code safe. 517 example hooks + 8 built-in. 56 CLI commands. 7591 tests. Works with Auto Mode.",
+  "version": "29.6.32",
+  "description": "One command to make Claude Code safe. 539 example hooks + 8 built-in. 56 CLI commands. 7789 tests. Works with Auto Mode.",
   "main": "index.mjs",
   "bin": {
     "cc-safe-setup": "index.mjs"

package/test.sh.tmp

@@ -0,0 +1,12 @@
+echo "path-deny-bash-guard.sh:"
+test_ex path-deny-bash-guard.sh '{"tool_input":{"command":"cat /etc/passwd"}}' 0 "path-deny: no deny config"
+test_ex path-deny-bash-guard.sh '{}' 0 "path-deny: empty input"
+export CC_DENIED_PATHS="/secret/data:/private/keys"
+test_ex path-deny-bash-guard.sh '{"tool_input":{"command":"cat /secret/data/file.txt"}}' 2 "path-deny: cat denied path BLOCKED"
+test_ex path-deny-bash-guard.sh '{"tool_input":{"command":"grep pattern /secret/data/"}}' 2 "path-deny: grep denied path BLOCKED"
+test_ex path-deny-bash-guard.sh '{"tool_input":{"command":"head /private/keys/id_rsa"}}' 2 "path-deny: head denied path BLOCKED"
+test_ex path-deny-bash-guard.sh '{"tool_input":{"command":"ls /home/user/projects"}}' 0 "path-deny: safe path allowed"
+test_ex path-deny-bash-guard.sh '{"tool_input":{"command":"echo hello"}}' 0 "path-deny: no path in command"
+test_ex path-deny-bash-guard.sh '{"tool_input":{"command":"cat /secret/data/../../../etc/passwd"}}' 2 "path-deny: traversal still matches denied prefix"
+unset CC_DENIED_PATHS
+echo ""