cc-safe-setup 29.6.32 → 29.6.33

package/examples/ci-workflow-guard.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# ci-workflow-guard.sh — Prevent dangerous CI/CD workflow modifications
+#
+# Solves: Claude modifying CI workflows to add `--no-verify`, skip tests,
+#         disable security scanning, or add overly broad permissions.
+#         A compromised workflow can exfiltrate secrets or deploy malicious code.
+#
+# How it works: PostToolUse hook on Edit/Write that checks workflow files
+#   for dangerous patterns after modification.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "Edit|Write"
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+case "$TOOL" in Edit|Write) ;; *) exit 0 ;; esac
+
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+
+# Only check CI workflow files
+case "$FILE" in
+    .github/workflows/*.yml|.github/workflows/*.yaml) ;;
+    .gitlab-ci.yml|.circleci/config.yml|Jenkinsfile) ;;
+    */.github/workflows/*.yml) ;;
+    *) exit 0 ;;
+esac
+
+[ -f "$FILE" ] || exit 0
+
+WARNINGS=""
+
+# Check for dangerous patterns
+if grep -qE 'permissions:\s*write-all|permissions:\s*\{[^}]*contents:\s*write' "$FILE" 2>/dev/null; then
+    WARNINGS="${WARNINGS}  - Broad write permissions detected\n"
+fi
+
+if grep -qE '--no-verify|--skip-tests|--no-check|SKIP_CI|skip ci|\[ci skip\]' "$FILE" 2>/dev/null; then
+    WARNINGS="${WARNINGS}  - Test/verification skip detected\n"
+fi
+
+if grep -qE 'curl.*\|.*sh|wget.*\|.*bash|bash\s*<\(curl' "$FILE" 2>/dev/null; then
+    WARNINGS="${WARNINGS}  - Remote script execution (curl|sh) detected\n"
+fi
+
+if grep -qE 'dangerously-skip-permissions|--force|--no-verify' "$FILE" 2>/dev/null; then
+    WARNINGS="${WARNINGS}  - Safety bypass flags detected\n"
+fi
+
+if [ -n "$WARNINGS" ]; then
+    echo "WARNING: Potentially dangerous CI workflow changes:" >&2
+    echo "  File: $FILE" >&2
+    echo -e "$WARNINGS" >&2
+    echo "  Review these changes carefully before committing." >&2
+fi
+
+exit 0

package/examples/classifier-fallback-allow.sh

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

package/examples/claude-cache-gc.sh

@@ -0,0 +1,15 @@
+CLAUDE_DIR="$HOME/.claude"
+MAX_AGE_DAYS="${CC_GC_MAX_AGE:-30}"
+MAX_SIZE_MB="${CC_GC_MAX_SIZE:-500}"
+DRY_RUN="${CC_GC_DRY_RUN:-0}"
+find "$CLAUDE_DIR/projects" -name "*.jsonl" -mtime +"$MAX_AGE_DAYS" -type f 2>/dev/null | while read f; do
+    [ "$DRY_RUN" = "1" ] && echo "  [dry-run] would delete: $f" >&2 && continue
+    rm "$f"
+done
+find "$CLAUDE_DIR/projects" -maxdepth 1 -type d -empty -delete 2>/dev/null
+find "$CLAUDE_DIR" -path "*/tool-results/*" -mtime +"$MAX_AGE_DAYS" -type f -delete 2>/dev/null
+TOTAL_MB=$(du -sm "$CLAUDE_DIR" 2>/dev/null | cut -f1)
+if [ "$TOTAL_MB" -gt "$MAX_SIZE_MB" ] 2>/dev/null; then
+    echo "~/.claude is ${TOTAL_MB}MB (cap: ${MAX_SIZE_MB}MB)" >&2
+fi
+exit 0

package/examples/claudeignore-enforce-guard.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# claudeignore-enforce-guard.sh — Enforce .claudeignore at the tool level
+#
+# Solves: .claudeignore patterns not blocking Read/Edit/Grep tool calls (#16704).
+#         Claude can directly access files listed in .claudeignore via tool calls.
+#         This hook enforces ignore rules that the built-in system misses.
+#
+# How it works: PreToolUse hook on Read/Edit/Write/Grep that checks if the
+#   target file matches any pattern in .claudeignore. Uses glob-style matching.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Read|Edit|Write|Grep|Glob"
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+# Extract file path based on tool type
+case "$TOOL" in
+  Read|Edit|Write)
+    FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+    ;;
+  Grep|Glob)
+    FILE=$(echo "$INPUT" | jq -r '.tool_input.path // empty' 2>/dev/null)
+    ;;
+  *) exit 0 ;;
+esac
+
+[ -z "$FILE" ] && exit 0
+
+# Find .claudeignore in project root or current directory
+IGNORE_FILE=""
+for candidate in ".claudeignore" "../.claudeignore" "../../.claudeignore"; do
+  if [ -f "$candidate" ]; then
+    IGNORE_FILE="$candidate"
+    break
+  fi
+done
+
+[ -z "$IGNORE_FILE" ] && exit 0
+
+# Check each pattern in .claudeignore
+while IFS= read -r pattern || [ -n "$pattern" ]; do
+  # Skip empty lines and comments
+  [[ -z "$pattern" || "$pattern" == \#* ]] && continue
+  # Strip trailing whitespace
+  pattern=$(echo "$pattern" | sed 's/[[:space:]]*$//')
+  [ -z "$pattern" ] && continue
+
+  # Match: exact path, basename, or glob
+  BASENAME=$(basename "$FILE")
+  if [[ "$FILE" == $pattern ]] || [[ "$BASENAME" == $pattern ]] || [[ "$FILE" == */$pattern ]]; then
+    echo "BLOCKED: File '$FILE' matches .claudeignore pattern '$pattern'." >&2
+    echo "This file is excluded from Claude Code access." >&2
+    exit 2
+  fi
+done < "$IGNORE_FILE"
+
+exit 0

package/examples/claudemd-enforcer.sh

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

package/examples/commit-message-check.sh

@@ -24,6 +24,8 @@
 #
 # The "if" field (v2.1.85+) skips this hook for non-commit commands.
 # Without "if", the hook still works — it checks internally and exits early.
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

package/examples/compact-blocker.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# ================================================================
+# compact-blocker.sh — Block auto-compaction entirely
+# ================================================================
+# PURPOSE:
+#   Power users who manage context manually (file-backed plans,
+#   checkpoint scripts) lose nuanced context when auto-compaction
+#   fires. This hook blocks compaction via exit code 2.
+#
+#   For conditional blocking (e.g., only during plan mode), modify
+#   the guard condition below.
+#
+# TRIGGER: PreCompact
+# MATCHER: (none — PreCompact has no matcher)
+#
+# DECISION: exit 2 = block compaction
+#
+# See: https://github.com/anthropics/claude-code/issues/6689
+# ================================================================
+
+# Unconditional block — compaction never fires
+# To make it conditional, add logic here:
+#   e.g., [ -f /tmp/allow-compact ] && exit 0
+echo '{"decision":"block","reason":"auto-compaction disabled by compact-blocker hook"}' >&2
+exit 2

package/examples/composer-guard.sh

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

package/examples/compound-command-allow.sh

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

package/examples/consecutive-failure-circuit-breaker.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# consecutive-failure-circuit-breaker.sh — Stop after repeated failures
+#
+# Solves: Claude escalating to destructive actions after repeated failures (#31946).
+#         Without this, Claude retries failing commands dozens of times,
+#         eventually trying increasingly dangerous alternatives.
+#
+# How it works: PostToolUse hook on Bash that tracks consecutive non-zero
+#   exit codes. After CC_MAX_CONSECUTIVE_FAILURES (default 3), blocks
+#   further Bash calls until a success resets the counter.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "Bash"
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ "$TOOL" != "Bash" ] && exit 0
+
+EXIT_CODE=$(echo "$INPUT" | jq -r '.tool_result.exitCode // "0"' 2>/dev/null)
+MAX_FAILURES="${CC_MAX_CONSECUTIVE_FAILURES:-3}"
+COUNTER_FILE="/tmp/claude-consecutive-failures-${PPID:-0}"
+
+if [ "$EXIT_CODE" = "0" ]; then
+  # Success — reset counter
+  echo "0" > "$COUNTER_FILE"
+  exit 0
+fi
+
+# Failure — increment counter
+COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo 0)
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+
+if [ "$COUNT" -ge "$MAX_FAILURES" ]; then
+  echo "CIRCUIT BREAKER: $COUNT consecutive Bash failures detected." >&2
+  echo "" >&2
+  echo "Stop and reassess your approach. Repeated failures often lead to" >&2
+  echo "increasingly risky workarounds. Consider:" >&2
+  echo "  1. Read the error messages carefully" >&2
+  echo "  2. Check your assumptions" >&2
+  echo "  3. Try a completely different approach" >&2
+  echo "  4. Ask the user for help" >&2
+  # Don't block (exit 0) — just warn strongly via stderr
+  # PostToolUse can't block, but the warning enters context
+fi
+
+exit 0

package/examples/console-log-count.sh

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

package/examples/context-compact-advisor.sh

@@ -0,0 +1,16 @@
+INPUT=$(cat)
+COUNTER="/tmp/cc-tool-count-$$"
+COUNT=$(cat "$COUNTER" 2>/dev/null || echo 0)
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER"
+THRESHOLD="${CC_COMPACT_THRESHOLD:-50}"
+if [ "$((COUNT % THRESHOLD))" -eq 0 ]; then
+    TRANSCRIPT=$(ls -t ~/.claude/projects/*/sessions/*/transcript.jsonl 2>/dev/null | head -1)
+    if [ -f "$TRANSCRIPT" ]; then
+        SIZE_KB=$(($(wc -c < "$TRANSCRIPT") / 1024))
+        if [ "$SIZE_KB" -gt 200 ]; then
+            echo "Context ~${SIZE_KB}KB ($COUNT calls). Consider /compact." >&2
+        fi
+    fi
+fi
+exit 0

package/examples/cors-star-warn.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0
 # PostToolUse matcher: Edit|Write

package/examples/credential-exfil-guard.sh

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

package/examples/credential-file-cat-guard.sh

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

package/examples/cron-modification-guard.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# cron-modification-guard.sh — Block unreviewed cron job modifications
+#
+# Solves: Claude creating cron jobs that sabotage live services (#40421).
+#         A cron job that polls 200 content IDs against a single-connection
+#         proxy caused stream resets every 10 minutes for days.
+#
+# Why this matters:
+#   Cron jobs are persistent, invisible, and run unattended. A bad cron
+#   can cause sustained damage long after the session ends. This hook
+#   blocks crontab edits, /etc/cron.d writes, and systemd timer creation.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Detect cron/timer modifications
+if echo "$COMMAND" | grep -qEi '(crontab\s+-[elr]|crontab\s+[^-]|systemctl\s+(enable|start|restart)\s+.*\.timer|(^|\s|;|&&|\|)at\s+)'; then
+  echo "BLOCKED: Cron/timer modification requires manual review." >&2
+  echo "" >&2
+  echo "Command: $COMMAND" >&2
+  echo "" >&2
+  echo "Cron jobs are persistent and run unattended. Before creating one:" >&2
+  echo "  1. Will this interfere with live services?" >&2
+  echo "  2. Does it access shared resources (DB, API, proxy)?" >&2
+  echo "  3. What happens if it fails silently?" >&2
+  exit 2
+fi
+
+# Also catch writing to cron directories
+if echo "$COMMAND" | grep -qE '>\s*/etc/cron\.|tee\s+/etc/cron\.'; then
+  echo "BLOCKED: Direct write to cron directory." >&2
+  echo "Command: $COMMAND" >&2
+  exit 2
+fi
+
+exit 0

package/examples/cwd-project-boundary-guard.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# cwd-project-boundary-guard.sh — Warn when cd leaves the project directory
+#
+# Solves: Claude navigating to system directories or other projects
+#         and making changes outside the intended scope. Especially
+#         dangerous with auto-approve, where writes to /etc or
+#         other projects go unchallenged.
+#
+# How it works: CwdChanged hook that tracks the project root and warns
+#   when the working directory moves outside it.
+#
+# CONFIG:
+#   CC_PROJECT_ROOT (auto-detected if not set)
+#
+# TRIGGER: CwdChanged
+# MATCHER: "" (CwdChanged has no matcher support)
+
+set -euo pipefail
+
+INPUT=$(cat)
+NEW_CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
+[ -z "$NEW_CWD" ] && exit 0
+
+# Determine project root
+PROJECT_ROOT="${CC_PROJECT_ROOT:-}"
+if [ -z "$PROJECT_ROOT" ]; then
+    # Auto-detect: find nearest .git directory
+    PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+fi
+[ -z "$PROJECT_ROOT" ] && exit 0
+
+# Normalize paths
+PROJECT_ROOT=$(realpath "$PROJECT_ROOT" 2>/dev/null || echo "$PROJECT_ROOT")
+NEW_CWD=$(realpath "$NEW_CWD" 2>/dev/null || echo "$NEW_CWD")
+
+# Check if new cwd is inside project
+case "$NEW_CWD" in
+    "$PROJECT_ROOT"|"$PROJECT_ROOT"/*)
+        # Inside project — OK
+        exit 0
+        ;;
+    *)
+        echo "WARNING: Working directory left project boundary." >&2
+        echo "  Project: $PROJECT_ROOT" >&2
+        echo "  New cwd: $NEW_CWD" >&2
+        echo "  Changes outside the project may affect other systems." >&2
+        ;;
+esac
+
+exit 0

package/examples/denied-action-retry-guard.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# denied-action-retry-guard.sh — Block re-attempts of denied tool calls
+#
+# Solves: Model retries the same operation after user explicitly denied it (#40156).
+#         Claude asks "shall I git push?", user says no, Claude tries git push anyway.
+#
+# How it works: PreToolUse hook that tracks denied operations via a state file.
+#   When a tool call is blocked (exit 2 from any hook), the command signature
+#   is recorded. If the same signature appears again, it's auto-blocked.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash|Edit|Write"
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+COMMAND=""
+
+case "$TOOL" in
+  Bash) COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null) ;;
+  Edit|Write) COMMAND=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null) ;;
+  *) exit 0 ;;
+esac
+
+[ -z "$COMMAND" ] && exit 0
+
+DENY_FILE="/tmp/claude-denied-actions-${PPID:-0}"
+
+# Check if this action was previously denied
+if [ -f "$DENY_FILE" ]; then
+  # Normalize: take first 80 chars as signature
+  SIG=$(echo "$COMMAND" | head -c 80 | md5sum | cut -d' ' -f1)
+  if grep -q "$SIG" "$DENY_FILE" 2>/dev/null; then
+    echo "BLOCKED: This action was previously denied in this session." >&2
+    echo "Do not retry denied actions. Try a different approach." >&2
+    exit 2
+  fi
+fi
+
+exit 0

package/examples/dependency-install-guard.sh

@@ -16,6 +16,8 @@
 # - Packages in ALLOWLIST (customize below)
 #
 # Usage: Add to settings.json as a PreToolUse hook on "Bash"
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

package/examples/deploy-guard.sh

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

package/examples/deploy-path-verify-guard.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# deploy-path-verify-guard.sh — Verify deployment target path before writes
+#
+# Solves: Writing files to wrong filesystem path in Docker setups (#40421).
+#         Claude wrote to host /srv/ instead of Docker mount /opt/acestream/public/
+#         three times, each time claiming deployment was successful.
+#
+# How it works: Before writing to paths matching CC_DEPLOY_PATHS pattern,
+#   verifies the target is actually mounted/accessible. Catches host-vs-container
+#   path confusion.
+#
+# CONFIG:
+#   CC_DEPLOY_PATHS="/srv:/opt/acestream/public:/var/www"
+#   CC_DEPLOY_VERIFY_CMD="docker inspect --format '{{.Mounts}}' mycontainer"
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash|Write"
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+DEPLOY_PATHS="${CC_DEPLOY_PATHS:-/srv:/var/www:/opt}"
+
+# For Write tool, check file_path
+if [ "$TOOL" = "Write" ]; then
+  FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+  [ -z "$FILE" ] && exit 0
+
+  IFS=':' read -ra PATHS <<< "$DEPLOY_PATHS"
+  for dp in "${PATHS[@]}"; do
+    if [[ "$FILE" == "$dp"* ]]; then
+      echo "WARNING: Writing to deployment path $dp." >&2
+      echo "File: $FILE" >&2
+      echo "" >&2
+      echo "Verify this is the correct target:" >&2
+      echo "  - Is this inside a Docker container or on the host?" >&2
+      echo "  - Run 'docker inspect' to check bind mounts first." >&2
+      # Warning only (exit 0), not blocking — change to exit 2 to block
+      exit 0
+    fi
+  done
+fi
+
+# For Bash tool, check commands that write to deploy paths
+if [ "$TOOL" = "Bash" ]; then
+  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+  [ -z "$COMMAND" ] && exit 0
+
+  IFS=':' read -ra PATHS <<< "$DEPLOY_PATHS"
+  for dp in "${PATHS[@]}"; do
+    if echo "$COMMAND" | grep -qE "(cp|mv|tee|cat.*>|echo.*>).*${dp}"; then
+      echo "WARNING: Bash command targets deployment path $dp." >&2
+      echo "Command: $COMMAND" >&2
+      echo "Verify the target path is correct (host vs container)." >&2
+      exit 0
+    fi
+  done
+fi
+
+exit 0

package/examples/django-migrate-guard.sh

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

package/examples/docker-volume-guard.sh

@@ -1,4 +1,6 @@
 #!/bin/bash
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
 COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0
 if echo "$COMMAND" | grep -qE '\bdocker\s+volume\s+(rm|prune)\b'; then

package/examples/dockerfile-latest-guard.sh

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

package/examples/dotenv-commit-guard.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# dotenv-commit-guard.sh — Prevent committing .env files with secrets
+#
+# Solves: Claude adding .env files to git staging and committing them.
+#         Even with .gitignore, Claude can `git add -f .env` to force-add.
+#
+# How it works: PreToolUse hook on Bash that detects git add/commit
+#   commands including .env files and blocks them.
+#
+# 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
+
+# Check for git add with .env files
+# Allow .env.example, .env.sample, .env.template
+if echo "$COMMAND" | grep -qE 'git\s+add\s+.*\.env\.(example|sample|template)'; then
+    exit 0
+fi
+if echo "$COMMAND" | grep -qE 'git\s+add\s+.*\.env'; then
+    echo "BLOCKED: Adding .env file to git staging." >&2
+    echo "  .env files contain secrets and should not be committed." >&2
+    echo "  Use .env.example with placeholder values instead." >&2
+    exit 2
+fi
+
+# Check for git add -A/-f that might include .env
+if echo "$COMMAND" | grep -qE 'git\s+add\s+(-A|--all|-f|--force)\b'; then
+    # Check if .env exists in the working directory
+    if [ -f ".env" ] || [ -f ".env.local" ] || [ -f ".env.production" ]; then
+        # Check if .gitignore excludes it
+        if ! git check-ignore -q .env 2>/dev/null; then
+            echo "WARNING: 'git add -A' with .env file not in .gitignore." >&2
+            echo "  Add .env to .gitignore before staging all files." >&2
+            # Warning only for git add -A
+        fi
+    fi
+fi
+
+exit 0

package/examples/dotenv-example-sync.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# ================================================================
+# dotenv-example-sync.sh — Warn when .env changes but .env.example doesn't
+# ================================================================
+# PURPOSE:
+#   When Claude edits .env (adding/removing variables), .env.example
+#   should be updated to match. This hook warns if .env was modified
+#   but .env.example still has different keys, preventing deployment
+#   failures when team members don't have the new variables.
+#
+# TRIGGER: PostToolUse
+# MATCHER: "Edit|Write"
+#
+# DECISION: Advisory only (exit 0). Warns via stderr.
+# ================================================================
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+
+# Only trigger when .env is edited (not .env.example itself)
+case "$(basename "$FILE")" in
+    .env|.env.local|.env.development|.env.production) ;;
+    *) exit 0 ;;
+esac
+
+# Find corresponding .env.example
+DIR=$(dirname "$FILE")
+EXAMPLE=""
+for candidate in "$DIR/.env.example" "$DIR/.env.sample" "$DIR/.env.template"; do
+    if [ -f "$candidate" ]; then
+        EXAMPLE="$candidate"
+        break
+    fi
+done
+
+[ -z "$EXAMPLE" ] && exit 0
+[ ! -f "$FILE" ] && exit 0
+
+# Extract variable names (lines with KEY=)
+ENV_KEYS=$(grep -oE '^[A-Z_][A-Z0-9_]*=' "$FILE" 2>/dev/null | sort -u)
+EXAMPLE_KEYS=$(grep -oE '^[A-Z_][A-Z0-9_]*=' "$EXAMPLE" 2>/dev/null | sort -u)
+
+# Find keys in .env but not in .env.example
+MISSING=$(comm -23 <(echo "$ENV_KEYS") <(echo "$EXAMPLE_KEYS"))
+
+if [ -n "$MISSING" ]; then
+    echo "⚠ .env has variables not in $(basename "$EXAMPLE"):" >&2
+    echo "$MISSING" | sed 's/=$//' | while read key; do
+        echo "  + $key" >&2
+    done
+    echo "  Update $(basename "$EXAMPLE") so teammates have the full variable list." >&2
+fi
+
+exit 0

package/examples/dotnet-build-on-edit.sh

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