cc-safe-setup 29.6.0 → 29.6.1

package/COOKBOOK.md

@@ -145,6 +145,76 @@ npx cc-safe-setup --install-example allow-git-hooks-dir
 
 Or manually: create a PermissionRequest hook that outputs `permissionDecision: "allow"`. See [Troubleshooting](TROUBLESHOOTING.md#pretooluse-allow-doesnt-bypass-protected-directory-prompts) for details.
 
+## Credential Protection
+
+Block credential hunting commands (env scanning, file searches for tokens):
+
+```bash
+npx cc-safe-setup --install-example credential-exfil-guard
+```
+
+Blocks: `env | grep -i token`, `find / -name *.pem`, `cat ~/.ssh/id_rsa`, `cat ~/.aws/credentials`.
+
+## Extra rm Protection
+
+Add a second layer of rm protection beyond destructive-guard:
+
+```bash
+npx cc-safe-setup --install-example rm-safety-net
+```
+
+Blocks rm -rf on any non-safe path (only allows node_modules, dist, build, /tmp, __pycache__).
+
+## Auto Mode False Positive Fix
+
+Stop the safety classifier from blocking read-only commands:
+
+```bash
+npx cc-safe-setup --install-example auto-mode-safe-commands
+```
+
+Auto-approves: cat, grep, git status, ls, find, jq, curl GET, echo.
+
+## Compound Command Auto-Approve
+
+Stop permission prompts for `cd /path && git log`:
+
+```bash
+npx cc-safe-setup --install-example compound-command-allow
+```
+
+Splits compound commands and checks each component. Approves when all are safe.
+
+## Secret Leak Prevention (Write/Edit)
+
+Block secrets from being written into source files:
+
+```bash
+npx cc-safe-setup --install-example write-secret-guard
+```
+
+Detects AWS, GitHub, OpenAI, Anthropic, Slack, Stripe, Google keys + PEM + database URLs. Allows .env.example and test files.
+
+## Permission Audit Log
+
+Log every tool call for debugging permission rules:
+
+```bash
+npx cc-safe-setup --install-example permission-audit-log
+```
+
+Writes JSONL to `~/.claude/tool-usage.jsonl`. Analyze with `cat ~/.claude/tool-usage.jsonl | jq -s 'group_by(.tool) | map({tool: .[0].tool, count: length})'`.
+
+## Classifier Fallback
+
+Auto-approve read-only commands when Auto Mode's classifier is unavailable:
+
+```bash
+npx cc-safe-setup --install-example classifier-fallback-allow
+```
+
+PermissionRequest hook that approves cat, ls, grep, git read-only when the classifier can't respond.
+
 ## Further Reading
 
 - [Getting Started](https://yurukusa.github.io/cc-safe-setup/getting-started.html)

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.** [日本語](docs/README.ja.md)
+**One command to make Claude Code safe for autonomous operation.** 1,000+ installs/day · [日本語](docs/README.ja.md)
 
 ```bash
 npx cc-safe-setup
@@ -66,6 +66,34 @@ Claude Code ships with no safety hooks by default. This tool fixes that.
 
 Each hook exists because a real incident happened without it.
 
+### v2.1.85: `if` Field Support
+
+Hooks now support an `if` field for conditional execution. The hook process only spawns when the command matches the pattern — `ls` won't trigger a git-only hook.
+
+```json
+{
+  "type": "command",
+  "if": "Bash(git push *)",
+  "command": "~/.claude/hooks/test-before-push.sh"
+}
+```
+
+All example hooks include `if` field documentation in their headers.
+
+## PermissionRequest Hooks (NEW)
+
+Override Claude Code's built-in confirmation prompts. These run **after** the built-in safety checks, so they can auto-approve prompts that `permissions.allow` cannot suppress.
+
+| Hook | What It Solves | Issue |
+|------|---------------|-------|
+| `quoted-flag-approver` | "Quoted characters in flag names" prompt on `git commit -m "msg"` | [#27957](https://github.com/anthropics/claude-code/issues/27957) |
+| `bash-heuristic-approver` | Safety heuristic prompts for `$()`, backticks, ANSI-C quoting | [#30435](https://github.com/anthropics/claude-code/issues/30435) |
+| `edit-always-allow` | Edit prompts in `.claude/skills/` despite `bypassPermissions` | [#36192](https://github.com/anthropics/claude-code/issues/36192) |
+| `allow-git-hooks-dir` | Edit prompts in `.git/hooks/` for pre-commit/pre-push setup | |
+| `allow-protected-dirs` | All protected directory prompts (CI/Docker environments) | [#36168](https://github.com/anthropics/claude-code/issues/36168) |
+
+Install any of these: `npx cc-safe-setup --install-example <name>`
+
 ## All 49 Commands
 
 | Command | What It Does |
@@ -89,7 +117,7 @@ Each hook exists because a real incident happened without it.
 | `--scan [--apply]` | Tech stack detection |
 | `--export / --import` | Team config sharing |
 | `--verify` | Test each hook |
-| `--install-example <name>` | Install from 335 examples |
+| `--install-example <name>` | Install from 369 examples |
 | `--examples [filter]` | Browse examples by keyword |
 | `--full` | All-in-one setup |
 | `--status` | Check installed hooks |
@@ -147,6 +175,16 @@ Each hook exists because a real incident happened without it.
 | Maximum protection mode | `npx cc-safe-setup --safe-mode` |
 | Migrate from Cursor/Windsurf | [Migration Guide](https://yurukusa.github.io/cc-safe-setup/migration-guide.html) |
 
+## Common Pain Points (from GitHub Issues)
+
+| Problem | Issue | Fix |
+|---|---|---|
+| Claude uses `cat`/`grep`/`sed` instead of built-in Read/Edit/Grep | [#19649](https://github.com/anthropics/claude-code/issues/19649) (48👍) | `npx cc-safe-setup --install-example prefer-builtin-tools` |
+| `cd /path && cmd` bypasses permission allowlist | [#28240](https://github.com/anthropics/claude-code/issues/28240) (88👍) | `npx cc-safe-setup --install-example compound-command-approver` |
+| Multiline commands skip pattern matching | [#11932](https://github.com/anthropics/claude-code/issues/11932) (47👍) | Use hooks instead of allowlist patterns for complex commands |
+| No notification when Claude asks a question | [#13024](https://github.com/anthropics/claude-code/issues/13024) (52👍) | `npx cc-safe-setup --install-example notify-waiting` |
+| `allow` overrides `ask` in permissions | [#6527](https://github.com/anthropics/claude-code/issues/6527) (17👍) | Use hooks to block dangerous commands instead of `ask` rules |
+
 ## How It Works
 
 1. Writes hook scripts to `~/.claude/hooks/`
@@ -215,7 +253,7 @@ npx cc-health-check
 
 cc-safe-setup gives you 8 essential hooks. Want to know what else your setup needs?
 
-Run `npx cc-health-check` (free, 20 checks) to see your current score. If it's below 80, the **[Claude Code Ops Kit](https://yurukusa.github.io/cc-ops-kit-landing/?utm_source=github&utm_medium=readme&utm_campaign=safe-setup)** fills the gaps — 16 hooks + 6 templates + 3 exclusive tools + install.sh. Pay What You Want.
+Run `npx cc-health-check` (free, 20 checks) to see your current score. If it's below 80, the **[Claude Code Ops Kit](https://yurukusa.github.io/cc-ops-kit-landing/?utm_source=github&utm_medium=readme&utm_campaign=safe-setup)** fills the gaps — 6 hooks + 5 templates + 9 scripts + install.sh. Pay What You Want ($0+).
 
 Or browse the free hooks: [claude-code-hooks](https://github.com/yurukusa/claude-code-hooks)
 
@@ -362,9 +400,10 @@ See [Issue #1](https://github.com/yurukusa/cc-safe-setup/issues/1) for details.
 ## Learn More
 
 - [Cookbook](COOKBOOK.md) — 26 practical recipes (block, approve, protect, monitor, diagnose)
-- [Official Hooks Reference](https://docs.anthropic.com/en/docs/claude-code/hooks) — Claude Code hooks documentation
+- [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/))
 - [Japanese guide (Qiita)](https://qiita.com/yurukusa/items/a9714b33f5d974e8f1e8) — この記事の日本語解説
+- [v2.1.85 `if` field guide (Qiita)](https://qiita.com/yurukusa/items/7079866e9dc239fcdd57) — Reduce hook overhead with conditional execution
 - [Hook Test Runner](https://github.com/yurukusa/cc-hook-test) — `npx cc-hook-test <hook.sh>` to auto-test any hook
 - [Hook Registry](https://github.com/yurukusa/cc-hook-registry) — `npx cc-hook-registry search database` ([browse online](https://yurukusa.github.io/cc-hook-registry/))
 - [Hooks Cheat Sheet](https://yurukusa.github.io/cc-safe-setup/cheatsheet.html) — printable A4 quick reference

package/TROUBLESHOOTING.md

@@ -261,6 +261,36 @@ npx cc-safe-setup --status  # See which hooks are active
 
 This should be fixed in a future Claude Code release.
 
+## "write-secret-guard blocks normal code"
+
+The write-secret-guard hook may false-positive on strings that look like API keys (20+ alphanumeric characters after specific prefixes). Fix:
+
+1. If the blocked file is a test file, rename it to include `test` in the path
+2. If it's a `.env.example`, the hook should already allow it — check the filename pattern
+3. For specific false positives, add an allowlist pattern to the hook
+
+## "credential-exfil-guard blocks my grep"
+
+The hook blocks `grep` commands that search for secret-related keywords. If you need to search for `token` or `key` in code:
+
+```bash
+# This is blocked:
+env | grep -i token
+
+# This is allowed (searching code, not environment):
+grep "token" src/auth.js
+```
+
+The hook only blocks `env/printenv/set` piped to grep with secret keywords, not general file searches.
+
+## "compound-command-allow doesn't approve my command"
+
+The hook has a strict whitelist. If a command isn't on the list, it passes through to the normal permission system. Common misses:
+
+- `docker` commands (not whitelisted — install `auto-approve-docker` instead)
+- `pip install` (not whitelisted — install `pip-venv-guard` instead)
+- Custom scripts (unknown to the whitelist)
+
 ## Still Stuck?
 
 1. Wrap the hook with debug wrapper: `npx cc-safe-setup --install-example hook-debug-wrapper`

package/examples/api-rate-limit-tracker.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# api-rate-limit-tracker.sh — Track API call frequency and warn on burst
+#
+# Prevents: Rate limit errors from rapid API calls.
+#           Claude sometimes runs curl/fetch in tight loops.
+#
+# Tracks: API calls per minute via a log file.
+# Warns at: 10 calls/min, blocks at 30 calls/min.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+#
+# Usage:
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "Bash",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/api-rate-limit-tracker.sh" }]
+#     }]
+#   }
+# }
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Only track API-calling commands
+echo "$COMMAND" | grep -qiE '(curl|wget|http|fetch)\s' || exit 0
+
+LOG="/tmp/cc-api-rate-$$"
+NOW=$(date +%s)
+
+# Append timestamp
+echo "$NOW" >> "$LOG"
+
+# Count calls in the last 60 seconds
+CUTOFF=$((NOW - 60))
+RECENT=$(awk -v cutoff="$CUTOFF" '$1 >= cutoff' "$LOG" 2>/dev/null | wc -l)
+
+if [ "$RECENT" -ge 30 ]; then
+  echo "BLOCKED: $RECENT API calls in the last minute. Rate limit risk." >&2
+  echo "  Add delays between calls or batch requests." >&2
+  exit 2
+elif [ "$RECENT" -ge 10 ]; then
+  echo "WARNING: $RECENT API calls in the last minute. Slow down." >&2
+fi
+
+# Cleanup old entries
+awk -v cutoff="$CUTOFF" '$1 >= cutoff' "$LOG" > "${LOG}.tmp" 2>/dev/null && mv "${LOG}.tmp" "$LOG"
+
+exit 0

package/examples/auto-answer-question.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# auto-answer-question.sh — Auto-answer AskUserQuestion for headless/autonomous mode
+#
+# NOTE: updatedInput schema (question/answer vs questions/answers array)
+# may vary. Verify with your Claude Code version before production use.
+#
+# TRIGGER: PreToolUse
+# MATCHER: AskUserQuestion
+#
+# v2.1.85+: PreToolUse hooks can satisfy AskUserQuestion by returning
+# updatedInput alongside permissionDecision: "allow".
+#
+# Usage:
+# {
+#   "hooks": {
+#     "PreToolUse": [{
+#       "matcher": "AskUserQuestion",
+#       "hooks": [{
+#         "type": "command",
+#         "command": "~/.claude/hooks/auto-answer-question.sh"
+#       }]
+#     }]
+#   }
+# }
+#
+# Dangerous operations → answer NO
+# Safe operations (test, build, lint) → answer YES
+# Unknown questions → pass through to human
+
+INPUT=$(cat)
+QUESTION=$(echo "$INPUT" | jq -r '.tool_input.question // empty' 2>/dev/null)
+[ -z "$QUESTION" ] && exit 0
+
+# Log all auto-answered questions for audit
+LOG_DIR="${HOME}/.claude/audit"
+mkdir -p "$LOG_DIR"
+echo "$(date -u '+%Y-%m-%dT%H:%M:%SZ') Q: $QUESTION" >> "$LOG_DIR/auto-answers.log"
+
+# Dangerous operations → always NO
+if echo "$QUESTION" | grep -qiE 'delete|削除|drop|truncate|destroy|remove.*all|wipe|reset.*hard|force.*push|rm -rf'; then
+    jq -n --arg q "$QUESTION" '{
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "allow",
+            updatedInput: { question: $q, answer: "No. This operation is too risky for unattended mode." }
+        }
+    }'
+    echo "$(date -u '+%Y-%m-%dT%H:%M:%SZ') A: NO (dangerous)" >> "$LOG_DIR/auto-answers.log"
+    exit 0
+fi
+
+# Safe operations → always YES
+if echo "$QUESTION" | grep -qiE 'test|テスト|build|ビルド|lint|format|check|確認|verify'; then
+    jq -n --arg q "$QUESTION" '{
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "allow",
+            updatedInput: { question: $q, answer: "Yes, proceed." }
+        }
+    }'
+    echo "$(date -u '+%Y-%m-%dT%H:%M:%SZ') A: YES (safe op)" >> "$LOG_DIR/auto-answers.log"
+    exit 0
+fi
+
+# Unknown → pass through to human
+echo "$(date -u '+%Y-%m-%dT%H:%M:%SZ') A: PASS (unknown)" >> "$LOG_DIR/auto-answers.log"
+exit 0

package/examples/auto-approve-readonly-tools.sh

@@ -0,0 +1,10 @@
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+case "$TOOL" in
+    Read|Glob|Grep)
+        jq -n --arg tool "$TOOL" \
+            '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","permissionDecision":"allow","permissionDecisionReason":($tool + " is read-only, auto-approved")}}'
+        exit 0
+        ;;
+esac
+exit 0

package/examples/aws-production-guard.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# aws-production-guard.sh — Block dangerous AWS CLI operations
+#
+# Prevents: Accidental deletion of production resources.
+#           Blocks: aws s3 rm --recursive, aws ec2 terminate-instances,
+#           aws rds delete-db-instance, aws cloudformation delete-stack
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Only check AWS CLI commands
+echo "$COMMAND" | grep -qE '^\s*aws\s' || exit 0
+
+# Block destructive operations
+BLOCKED_PATTERNS=(
+  "s3.*rm.*--recursive"
+  "s3.*rb\s"
+  "ec2.*terminate-instances"
+  "rds.*delete-db"
+  "cloudformation.*delete-stack"
+  "lambda.*delete-function"
+  "dynamodb.*delete-table"
+  "iam.*delete-user"
+  "iam.*delete-role"
+)
+
+for pattern in "${BLOCKED_PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qiE "aws\s+$pattern"; then
+    echo "BLOCKED: Destructive AWS operation detected." >&2
+    echo "  Pattern: $pattern" >&2
+    echo "  Use the AWS Console for destructive operations." >&2
+    exit 2
+  fi
+done
+
+exit 0

package/examples/banned-command-guard.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# banned-command-guard.sh — Block commands that are explicitly banned
+#
+# Solves: Claude using sed/awk/perl one-liners to edit files instead of
+#         the built-in Edit tool, even when CLAUDE.md says "never use sed."
+#         Real incident: #36413 — sed from wrong CWD emptied a key file,
+#         then git checkout -- discarded 400 lines of uncommitted work.
+#
+# Why this matters:
+#   CLAUDE.md bans are advisory. Claude can ignore them under context pressure.
+#   This hook enforces the ban at the process level.
+#
+# Default banned commands (configurable via CC_BANNED_COMMANDS):
+#   sed -i (in-place file editing — use Edit tool instead)
+#   awk -i inplace (same reason)
+#   perl -pi -e (same reason)
+#
+# TRIGGER: PreToolUse  MATCHER: "Bash"
+#
+# Configuration:
+#   CC_BANNED_COMMANDS — colon-separated list of regex patterns to block
+#   Default: "sed -i:awk -i inplace:perl -pi"
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+[ -z "$COMMAND" ] && exit 0
+
+# Configurable banned patterns (colon-separated)
+BANNED="${CC_BANNED_COMMANDS:-sed\s+-i:awk\s+-i\s+inplace:perl\s+-pi}"
+
+# Check each banned pattern
+IFS=':' read -ra PATTERNS <<< "$BANNED"
+for pattern in "${PATTERNS[@]}"; do
+    if echo "$COMMAND" | grep -qE "$pattern"; then
+        echo "BLOCKED: Command matches banned pattern." >&2
+        echo "" >&2
+        echo "Command: $COMMAND" >&2
+        echo "Pattern: $pattern" >&2
+        echo "" >&2
+        echo "Use the built-in Edit tool instead of shell text processors." >&2
+        echo "Edit tool preserves file encoding, handles unicode correctly," >&2
+        echo "and shows diffs for review." >&2
+        exit 2
+    fi
+done
+
+exit 0

package/examples/bash-heuristic-approver.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# bash-heuristic-approver.sh — Auto-approve bash safety heuristic prompts
+#
+# Solves: Safety heuristic prompts cannot be suppressed (#30435, 30 reactions)
+#         Claude Code fires prompts for common patterns like:
+#         - $() command substitution
+#         - Backtick substitution
+#         - Newlines in commands (for loops, multi-step scripts)
+#         - Quote characters in comments
+#         - ANSI-C quoting
+#         These cannot be bypassed with permissions.allow or acceptEdits.
+#
+# This PermissionRequest hook detects heuristic-triggered prompts and
+# auto-approves them when the base command is in a safe list.
+#
+# TRIGGER: PermissionRequest
+# MATCHER: ""
+#
+# Usage:
+# {
+#   "hooks": {
+#     "PermissionRequest": [{
+#       "matcher": "",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/bash-heuristic-approver.sh" }]
+#     }]
+#   }
+# }
+
+INPUT=$(cat)
+
+# Detect safety heuristic prompts by their characteristic messages
+MESSAGE=$(echo "$INPUT" | jq -r '.message // empty' 2>/dev/null)
+[ -z "$MESSAGE" ] && exit 0
+
+# Match known heuristic warning patterns
+HEURISTIC_PATTERNS="command substitution|backtick|can desync quote|potential bypass|can hide characters|quoted characters|newline|ANSI.C quot"
+
+if ! echo "$MESSAGE" | grep -qiE "$HEURISTIC_PATTERNS"; then
+  # Not a heuristic prompt — pass through
+  exit 0
+fi
+
+# Extract the command
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Safe base commands — only auto-approve for known-safe tools
+SAFE_COMMANDS="git|npm|npx|bun|yarn|pnpm|docker|make|cargo|go|pip|python3|node|tsc|eslint|prettier|jest|vitest|pytest|gh|curl|wget|rsync|tar|zip|unzip|find|grep|sed|awk|cat|echo|ls|mkdir|cp|mv|chmod|wc|sort|head|tail|jq|python3"
+
+# Extract first meaningful command (skip env vars, cd, whitespace)
+BASE_CMD=$(echo "$COMMAND" | tr '\n' ' ' | sed 's/^[[:space:]]*//' | sed 's/^[A-Z_]*=[^ ]* //' | sed 's/^cd [^&;]* *[&;]* *//' | awk '{print $1}' | sed 's|.*/||')
+
+if echo "$BASE_CMD" | grep -qE "^($SAFE_COMMANDS)$"; then
+  echo '{"permissionDecision":"allow"}'
+  exit 0
+fi
+
+# Unknown base command — let the prompt through for safety
+exit 0

package/examples/block-database-wipe.sh

@@ -57,7 +57,7 @@ if echo "$COMMAND" | grep -qiE 'rake\s+db:(drop|reset)|rails\s+db:(drop|reset)';
 fi
 
 # Raw SQL destructive commands
-if echo "$COMMAND" | grep -qiE 'DROP\s+(DATABASE|TABLE|SCHEMA)|TRUNCATE\s+TABLE|DELETE\s+FROM\s+\w+\s*;?\s*$'; then
+if echo "$COMMAND" | grep -qiE 'DROP\s+(DATABASE|TABLE|SCHEMA)|TRUNCATE\s+TABLE|DELETE\s+FROM\s+\w+\s*(;|\s*$|WHERE\s+(1\s*=\s*1|true))'; then
     echo "BLOCKED: Destructive SQL command" >&2
     exit 2
 fi

package/examples/classifier-fallback-allow.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# classifier-fallback-allow.sh — Allow read-only commands when Auto Mode classifier is unavailable
+#
+# Solves: Auto Mode's safety classifier (Sonnet) sometimes goes down.
+#         When it does, ALL commands get blocked — even cat, ls, grep.
+#         (#39259, #38618, #38537)
+#
+# How it works: PermissionRequest hook that approves read-only commands
+#               regardless of classifier status. Only fires on PermissionRequest
+#               (the permission prompt), not on normal PreToolUse.
+#
+# Usage: Add to settings.json as a PermissionRequest hook
+#
+# {
+#   "hooks": {
+#     "PermissionRequest": [{
+#       "matcher": "Bash",
+#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/classifier-fallback-allow.sh" }]
+#     }]
+#   }
+# }
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+[ -z "$COMMAND" ] && exit 0
+
+# Extract the base command (first word, ignoring leading whitespace)
+BASE=$(echo "$COMMAND" | awk '{print $1}')
+
+# Read-only commands that are always safe
+case "$BASE" in
+    # File inspection
+    cat|head|tail|less|more|wc|file|stat|du|df|ls|tree|find|which|whereis|type|realpath|readlink|basename|dirname)
+        # find with -delete is NOT read-only
+        if echo "$COMMAND" | grep -qE '\s-delete'; then
+            exit 0  # Don't approve — let normal flow handle it
+        fi
+        jq -n '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","permissionDecision":"allow","permissionDecisionReason":"Read-only command (classifier fallback)"}}'
+        exit 0
+        ;;
+    # Text search
+    grep|rg|ag|ack)
+        jq -n '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","permissionDecision":"allow","permissionDecisionReason":"Text search (classifier fallback)"}}'
+        exit 0
+        ;;
+    # Git read-only
+    git)
+        SUBCMD=$(echo "$COMMAND" | awk '{print $2}')
+        case "$SUBCMD" in
+            status|log|diff|show|branch|tag|remote|describe|rev-parse|blame|shortlog|ls-files|ls-tree)
+                jq -n '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","permissionDecision":"allow","permissionDecisionReason":"Git read-only (classifier fallback)"}}'
+                exit 0
+                ;;
+        esac
+        ;;
+    # Shell builtins
+    echo|printf|true|false|pwd|env|printenv|date|uname|hostname|whoami|id)
+        jq -n '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","permissionDecision":"allow","permissionDecisionReason":"Shell builtin (classifier fallback)"}}'
+        exit 0
+        ;;
+    # JSON/YAML
+    jq|yq)
+        jq -n '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","permissionDecision":"allow","permissionDecisionReason":"Data processing (classifier fallback)"}}'
+        exit 0
+        ;;
+esac
+
+# Not a known read-only command — don't interfere
+exit 0

package/examples/commit-message-check.sh

@@ -13,10 +13,17 @@
 #   "hooks": {
 #     "PostToolUse": [{
 #       "matcher": "Bash",
-#       "hooks": [{ "type": "command", "command": "~/.claude/hooks/commit-message-check.sh" }]
+#       "hooks": [{
+#         "type": "command",
+#         "if": "Bash(git commit *)",
+#         "command": "~/.claude/hooks/commit-message-check.sh"
+#       }]
 #     }]
 #   }
 # }
+#
+# 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.
 
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

package/examples/commit-message-quality.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# commit-message-quality.sh — Warn about low-quality commit messages
+#
+# Prevents: "fix", "update", "wip", "asdf" commit messages.
+#           Claude sometimes generates vague messages.
+#
+# Checks: minimum length, conventional commit format suggestion
+#
+# 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 commit
+echo "$COMMAND" | grep -qE '^\s*git\s+commit' || exit 0
+
+# Extract commit message
+MSG=$(echo "$COMMAND" | grep -oP '(-m\s+["\x27])(.+?)(["\x27])' | sed "s/^-m\s*[\"']//" | sed "s/[\"']$//")
+[ -z "$MSG" ] && exit 0
+
+# Check message quality
+LEN=${#MSG}
+
+if [ "$LEN" -lt 10 ]; then
+  echo "WARNING: Commit message too short ($LEN chars). Be more descriptive." >&2
+fi
+
+# Check for vague messages
+if echo "$MSG" | grep -qiE '^(fix|update|change|wip|temp|test|asdf|todo|misc|stuff|things|more)$'; then
+  echo "WARNING: Vague commit message '$MSG'. Describe WHAT changed and WHY." >&2
+fi
+
+exit 0

package/examples/credential-exfil-guard.sh

@@ -70,4 +70,16 @@ if echo "$COMMAND" | grep -qE '^\s*(env|printenv|set)\s*$'; then
     exit 0
 fi
 
+# Pattern 8: curl/wget posting credential files
+if echo "$COMMAND" | grep -qiP 'curl\s.*-d\s+@[^\s]*(\.env|\.pem|\.key|credentials|\.ssh/id_)|wget\s.*--post-file[= ][^\s]*(\.env|\.pem|\.key|credentials|\.ssh/id_)'; then
+    echo "BLOCKED: Credential file exfiltration via HTTP upload" >&2
+    exit 2
+fi
+
+# Pattern 9: Piping credential files to curl/wget
+if echo "$COMMAND" | grep -qiP 'cat\s+[^\s]*(\.env|\.pem|\.key|credentials|\.ssh/id_)\S*\s*\|.*curl|cat\s+[^\s]*(\.env|\.pem|\.key|credentials|\.ssh/id_)\S*\s*\|.*wget'; then
+    echo "BLOCKED: Credential file piped to HTTP client" >&2
+    exit 2
+fi
+
 exit 0