cc-safe-setup 3.0.1 → 3.2.0

package/README.md

@@ -214,11 +214,16 @@ Or browse all available examples in [`examples/`](examples/):
 - **todo-check.sh** — Warn when committing files with TODO/FIXME/HACK markers
 - **path-traversal-guard.sh** — Block Edit/Write with `../../` path traversal and system directories
 - **case-sensitive-guard.sh** — Detect case-insensitive filesystems (exFAT, NTFS, HFS+) and block rm/mkdir that would collide due to case folding ([#37875](https://github.com/anthropics/claude-code/issues/37875))
+- **compound-command-approver.sh** — Auto-approve safe compound commands (`cd && git log`, `cd && npm test`) that the permission system can't match ([#30519](https://github.com/anthropics/claude-code/issues/30519) [#16561](https://github.com/anthropics/claude-code/issues/16561))
 
 ## Safety Checklist
 
 **[SAFETY_CHECKLIST.md](SAFETY_CHECKLIST.md)** — Copy-paste checklist for before/during/after autonomous sessions.
 
+## settings.json Reference
+
+**[SETTINGS_REFERENCE.md](SETTINGS_REFERENCE.md)** — Complete reference for permissions, hooks, modes, and common configurations. Includes known limitations and workarounds.
+
 ## Migration Guide
 
 **[MIGRATION.md](MIGRATION.md)** — Step-by-step guide for moving from permissions-only to permissions + hooks. Keep your existing config, add safety layers on top.
@@ -229,6 +234,7 @@ Or browse all available examples in [`examples/`](examples/):
 - [Hooks Cookbook](https://github.com/yurukusa/claude-code-hooks/blob/main/COOKBOOK.md) — 19 ready-to-use recipes from real GitHub Issues
 - [Japanese guide (Qiita)](https://qiita.com/yurukusa/items/a9714b33f5d974e8f1e8) — この記事の日本語解説
 - [Hook Test Runner](https://github.com/yurukusa/cc-hook-test) — `npx cc-hook-test <hook.sh>` to auto-test any hook
+- [Ecosystem Comparison](https://yurukusa.github.io/cc-safe-setup/ecosystem.html) — all Claude Code hook projects compared
 - [The incident that inspired this tool](https://github.com/anthropics/claude-code/issues/36339) — NTFS junction rm -rf
 
 ## FAQ

package/SETTINGS_REFERENCE.md

@@ -0,0 +1,282 @@
+# Claude Code settings.json Reference
+
+Everything you can put in `~/.claude/settings.json`, documented from real usage and GitHub Issues.
+
+## File Locations
+
+| File | Scope | Precedence |
+|------|-------|------------|
+| `~/.claude/settings.json` | All projects (user-level) | Lowest |
+| `.claude/settings.json` | Current project | Overrides user |
+| `.claude/settings.local.json` | Current project (gitignored) | Highest |
+
+## Permissions
+
+### allow
+
+Commands that auto-execute without prompting.
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(npm test:*)",
+      "Bash(npm run:*)",
+      "Read(*)",
+      "Edit(*)",
+      "Write(*)",
+      "Glob(*)",
+      "Grep(*)"
+    ]
+  }
+}
+```
+
+**Pattern syntax:**
+- `Tool(pattern)` — match tool name and argument pattern
+- `*` — wildcard (matches anything)
+- `:` — separator between command and arguments
+- `Bash(git:*)` — any command starting with `git`
+- `Bash(git status:*)` — `git status` with any args
+- `Bash(*)` — all bash commands (dangerous — use with hooks)
+
+**Known limitations (as of v2.1.81):**
+- Compound commands don't match: `Bash(git:*)` won't match `cd /path && git log` ([#30519](https://github.com/anthropics/claude-code/issues/30519), [#16561](https://github.com/anthropics/claude-code/issues/16561))
+- "Always Allow" saves exact strings, not patterns ([#6850](https://github.com/anthropics/claude-code/issues/6850))
+- User-level settings may not apply at project level ([#5140](https://github.com/anthropics/claude-code/issues/5140))
+- **Workaround:** Use `compound-command-approver` hook: `npx cc-safe-setup --install-example compound-command-approver`
+
+### deny
+
+Commands that are always blocked.
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(git push --force:*)",
+      "Bash(sudo:*)"
+    ]
+  }
+}
+```
+
+**Note:** Deny rules have the same compound-command limitation as allow rules. Hooks are more reliable for blocking.
+
+## Hooks
+
+### Structure
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/my-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Hook Events
+
+| Event | When | Use Case |
+|-------|------|----------|
+| `PreToolUse` | Before tool executes | Block/modify commands |
+| `PostToolUse` | After tool executes | Validate output, check syntax |
+| `Stop` | Session ends | Log data, notify |
+| `UserPromptSubmit` | User presses Enter | Validate prompts |
+| `Notification` | Claude shows notification | Custom alerts |
+| `PreCompact` | Before context compaction | Save state |
+| `SessionStart` | Session begins | Initialize |
+| `SessionEnd` | Session ends | Cleanup |
+
+### Matcher Values
+
+| Matcher | Matches |
+|---------|---------|
+| `"Bash"` | Bash tool only |
+| `"Edit\|Write"` | Edit or Write tool |
+| `"Read"` | Read tool only |
+| `""` (empty) | All tools |
+
+### Hook Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Allow (or no opinion) |
+| 2 | **Block** — tool call cancelled |
+| Other | Error (treated as allow) |
+
+### Hook Input (stdin JSON)
+
+**PreToolUse/PostToolUse:**
+```json
+{
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "git push origin main"
+  }
+}
+```
+
+**For Edit/Write:**
+```json
+{
+  "tool_name": "Edit",
+  "tool_input": {
+    "file_path": "/path/to/file.py",
+    "old_string": "...",
+    "new_string": "..."
+  }
+}
+```
+
+**Stop:**
+```json
+{
+  "stop_reason": "user",
+  "hook_event_name": "Stop"
+}
+```
+
+### Hook Output (stdout JSON)
+
+**Auto-approve:**
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "permissionDecisionReason": "auto-approved by hook"
+  }
+}
+```
+
+**Modify input:**
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "updatedInput": {
+      "command": "modified command here"
+    }
+  }
+}
+```
+
+## defaultMode
+
+```json
+{
+  "defaultMode": "default"
+}
+```
+
+| Mode | Behavior |
+|------|----------|
+| `"default"` | Prompt for unrecognized commands |
+| `"dontAsk"` | Auto-approve everything (hooks still run) |
+| `"bypassPermissions"` | Skip everything including hooks (dangerous) |
+
+**Recommendation:** Use `"dontAsk"` + hooks instead of `"bypassPermissions"`.
+
+## Common Configurations
+
+### Minimal Safe Setup
+
+```json
+{
+  "permissions": {
+    "allow": ["Read(*)", "Glob(*)", "Grep(*)"]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "~/.claude/hooks/destructive-guard.sh" },
+          { "type": "command", "command": "~/.claude/hooks/branch-guard.sh" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Autonomous Operation
+
+```json
+{
+  "defaultMode": "dontAsk",
+  "permissions": {
+    "allow": ["Bash(*)", "Read(*)", "Edit(*)", "Write(*)", "Glob(*)", "Grep(*)"]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "~/.claude/hooks/destructive-guard.sh" },
+          { "type": "command", "command": "~/.claude/hooks/branch-guard.sh" },
+          { "type": "command", "command": "~/.claude/hooks/secret-guard.sh" },
+          { "type": "command", "command": "~/.claude/hooks/compound-command-approver.sh" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          { "type": "command", "command": "~/.claude/hooks/syntax-check.sh" }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "~/.claude/hooks/context-monitor.sh" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Generate This Automatically
+
+```bash
+npx cc-safe-setup        # Install hooks
+npx cc-safe-setup --audit  # Check your score
+npx cc-safe-setup --doctor # Diagnose issues
+```
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Hooks don't fire | Not registered in settings.json | `npx cc-safe-setup` |
+| Hooks don't block | Wrong exit code (not 2) | Check `echo $?` after test |
+| "jq: command not found" | jq not installed | `brew install jq` / `apt install jq` |
+| Hook permission denied | Not executable | `chmod +x ~/.claude/hooks/*.sh` |
+| Compound commands prompt | Permission system limitation | Install `compound-command-approver` |
+| "Always Allow" doesn't stick | Saves exact string, not pattern | Use hooks instead |
+
+Run `npx cc-safe-setup --doctor` for automated diagnosis.
+
+## Resources
+
+- [Official Hooks Documentation](https://docs.anthropic.com/en/docs/claude-code/hooks)
+- [COOKBOOK.md](https://github.com/yurukusa/claude-code-hooks/blob/main/COOKBOOK.md) — 20 hook recipes
+- [Migration Guide](MIGRATION.md) — from permissions to hooks
+- [Ecosystem Comparison](https://yurukusa.github.io/cc-safe-setup/ecosystem.html) — all hook projects

package/audit-web/index.html

@@ -88,7 +88,7 @@ a { color: #58a6ff; text-decoration: none; }
 <div class="tab-content" id="tab-fix"></div>
 <div class="tab-content" id="tab-manual"></div>
 
-<p class="privacy">100% client-side. Your settings never leave this page. <a href="https://github.com/yurukusa/cc-safe-setup">Source</a> · <a href="https://www.npmjs.com/package/cc-safe-setup">npm</a></p>
+<p class="privacy">100% client-side. Your settings never leave this page. <a href="https://github.com/yurukusa/cc-safe-setup">Source</a> · <a href="https://www.npmjs.com/package/cc-safe-setup">npm</a> · <a href="ecosystem.html">Compare all hook projects</a></p>
 </div>
 
 <script>

package/docs/ecosystem.html

@@ -0,0 +1,223 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Claude Code Hooks Ecosystem</title>
+<meta name="description" content="Compare all Claude Code hook projects — features, language, stars, and installation methods.">
+<style>
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: #0d1117; color: #c9d1d9; min-height: 100vh; padding: 2rem; }
+.container { max-width: 900px; margin: 0 auto; }
+h1 { font-size: 1.5rem; margin-bottom: 0.5rem; color: #f0f6fc; }
+h2 { font-size: 1.2rem; margin: 2rem 0 1rem; color: #f0f6fc; }
+.subtitle { color: #8b949e; margin-bottom: 2rem; }
+a { color: #58a6ff; text-decoration: none; }
+a:hover { text-decoration: underline; }
+table { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: 0.85rem; }
+th { text-align: left; padding: 0.6rem 0.5rem; border-bottom: 2px solid #30363d; color: #f0f6fc; font-weight: 600; }
+td { padding: 0.5rem; border-bottom: 1px solid #21262d; vertical-align: top; }
+tr:hover td { background: #161b22; }
+.badge { display: inline-block; padding: 0.15rem 0.4rem; border-radius: 3px; font-size: 0.7rem; font-weight: bold; margin-right: 0.3rem; }
+.badge-bash { background: #1f6feb22; color: #58a6ff; border: 1px solid #1f6feb44; }
+.badge-js { background: #f0e68c22; color: #f0e68c; border: 1px solid #f0e68c44; }
+.badge-py { background: #3fb95022; color: #3fb950; border: 1px solid #3fb95044; }
+.badge-ts { background: #388bfd22; color: #388bfd; border: 1px solid #388bfd44; }
+.check { color: #3fb950; }
+.cross { color: #484f58; }
+.note { color: #8b949e; font-size: 0.8rem; margin-top: 2rem; }
+.footer { color: #484f58; font-size: 0.75rem; margin-top: 3rem; text-align: center; }
+</style>
+</head>
+<body>
+<div class="container">
+<h1>Claude Code Hooks Ecosystem</h1>
+<p class="subtitle">A neutral comparison of all major hook projects. Pick the one that fits your stack.</p>
+
+<h2>Projects at a Glance</h2>
+<table>
+<tr>
+  <th>Project</th>
+  <th>Language</th>
+  <th>Hooks</th>
+  <th>Install</th>
+  <th>Focus</th>
+</tr>
+<tr>
+  <td><a href="https://github.com/kenryu42/claude-code-safety-net">safety-net</a></td>
+  <td><span class="badge badge-ts">TS</span></td>
+  <td>5 rules</td>
+  <td>npx</td>
+  <td>Destructive command blocking with configurable severity</td>
+</tr>
+<tr>
+  <td><a href="https://github.com/yurukusa/cc-safe-setup">cc-safe-setup</a></td>
+  <td><span class="badge badge-bash">Bash</span></td>
+  <td>8 + 26 examples</td>
+  <td>npx</td>
+  <td>Full safety suite: block, audit, create, learn, watch, doctor</td>
+</tr>
+<tr>
+  <td><a href="https://github.com/karanb192/claude-code-hooks">karanb192/hooks</a></td>
+  <td><span class="badge badge-js">JS</span></td>
+  <td>5+</td>
+  <td>copy files</td>
+  <td>JS hooks with configurable safety levels and logging</td>
+</tr>
+<tr>
+  <td><a href="https://github.com/disler/claude-code-hooks-mastery">hooks-mastery</a></td>
+  <td><span class="badge badge-py">Python</span></td>
+  <td>12</td>
+  <td>copy files</td>
+  <td>Python hooks covering all hook events + LLM integration</td>
+</tr>
+<tr>
+  <td><a href="https://github.com/lasso-security/claude-hooks">lasso-security</a></td>
+  <td><span class="badge badge-py">Python</span></td>
+  <td>1 skill</td>
+  <td>install.sh</td>
+  <td>Prompt injection defense using YAML pattern matching</td>
+</tr>
+<tr>
+  <td><a href="https://github.com/johnlindquist/claude-hooks">johnlindquist</a></td>
+  <td><span class="badge badge-ts">TS</span></td>
+  <td>8</td>
+  <td>Bun</td>
+  <td>TypeScript hooks with Bun runtime, notification focus</td>
+</tr>
+<tr>
+  <td><a href="https://github.com/yurukusa/claude-code-hooks">claude-code-hooks</a></td>
+  <td><span class="badge badge-bash">Bash</span></td>
+  <td>16 + 5 templates</td>
+  <td>install.sh</td>
+  <td>Production hooks from 1000+ hours autonomous operation</td>
+</tr>
+</table>
+
+<h2>Feature Comparison</h2>
+<table>
+<tr>
+  <th>Feature</th>
+  <th>safety-net</th>
+  <th>cc-safe-setup</th>
+  <th>karanb192</th>
+  <th>mastery</th>
+  <th>lasso</th>
+</tr>
+<tr>
+  <td>rm -rf blocker</td>
+  <td class="check">&#10003;</td>
+  <td class="check">&#10003;</td>
+  <td class="check">&#10003;</td>
+  <td class="check">&#10003;</td>
+  <td class="cross">-</td>
+</tr>
+<tr>
+  <td>Branch push guard</td>
+  <td class="check">&#10003;</td>
+  <td class="check">&#10003;</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+</tr>
+<tr>
+  <td>Secret leak prevention</td>
+  <td class="cross">-</td>
+  <td class="check">&#10003;</td>
+  <td class="check">&#10003;</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+</tr>
+<tr>
+  <td>Syntax validation</td>
+  <td class="cross">-</td>
+  <td class="check">&#10003;</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+</tr>
+<tr>
+  <td>Context monitor</td>
+  <td class="cross">-</td>
+  <td class="check">&#10003;</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+</tr>
+<tr>
+  <td>Prompt injection defense</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+  <td class="check">&#10003;</td>
+</tr>
+<tr>
+  <td>Auto-approve safe cmds</td>
+  <td class="cross">-</td>
+  <td class="check">&#10003;</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+</tr>
+<tr>
+  <td>Database wipe guard</td>
+  <td class="cross">-</td>
+  <td class="check">&#10003;</td>
+  <td class="cross">-</td>
+  <td class="check">&#10003;</td>
+  <td class="cross">-</td>
+</tr>
+<tr>
+  <td>Safety audit/score</td>
+  <td class="cross">-</td>
+  <td class="check">&#10003;</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+</tr>
+<tr>
+  <td>Hook generator (NL)</td>
+  <td class="cross">-</td>
+  <td class="check">&#10003;</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+</tr>
+<tr>
+  <td>Zero dependencies</td>
+  <td class="cross">TS</td>
+  <td class="check">jq only</td>
+  <td class="check">Node</td>
+  <td class="cross">uv/pip</td>
+  <td class="cross">uv</td>
+</tr>
+<tr>
+  <td>GitHub Action</td>
+  <td class="cross">-</td>
+  <td class="check">&#10003;</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+  <td class="cross">-</td>
+</tr>
+</table>
+
+<p class="note">This page is maintained by the cc-safe-setup team but aims to be neutral. PRs welcome for corrections: <a href="https://github.com/yurukusa/cc-safe-setup">GitHub</a></p>
+
+<h2>Which Should I Use?</h2>
+<table>
+<tr><th>If you want...</th><th>Use this</th></tr>
+<tr><td>Quickest setup, bash-based</td><td><code>npx cc-safe-setup</code></td></tr>
+<tr><td>TypeScript hooks, configurable severity</td><td>safety-net</td></tr>
+<tr><td>Python hooks, all event types</td><td>hooks-mastery</td></tr>
+<tr><td>Prompt injection protection</td><td>lasso-security</td></tr>
+<tr><td>JS hooks with logging</td><td>karanb192</td></tr>
+<tr><td>Complete ops toolkit (hooks + templates)</td><td>claude-code-hooks</td></tr>
+</table>
+
+<div class="footer">
+  Last updated: March 2026 · <a href="https://yurukusa.github.io/cc-safe-setup/">Safety Audit Tool</a> · <a href="https://github.com/yurukusa/cc-safe-setup">Source</a>
+</div>
+</div>
+</body>
+</html>

package/docs/index.html

@@ -88,7 +88,7 @@ a { color: #58a6ff; text-decoration: none; }
 <div class="tab-content" id="tab-fix"></div>
 <div class="tab-content" id="tab-manual"></div>
 
-<p class="privacy">100% client-side. Your settings never leave this page. <a href="https://github.com/yurukusa/cc-safe-setup">Source</a> · <a href="https://www.npmjs.com/package/cc-safe-setup">npm</a></p>
+<p class="privacy">100% client-side. Your settings never leave this page. <a href="https://github.com/yurukusa/cc-safe-setup">Source</a> · <a href="https://www.npmjs.com/package/cc-safe-setup">npm</a> · <a href="ecosystem.html">Compare all hook projects</a></p>
 </div>
 
 <script>

package/examples/compound-command-approver.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+# ================================================================
+# compound-command-approver.sh — Auto-approve safe compound commands
+# ================================================================
+# PURPOSE:
+#   Claude Code's permission system doesn't match compound commands.
+#   `Bash(git:*)` doesn't match `cd /path && git log`.
+#   `Bash(npm:*)` doesn't match `cd project && npm test`.
+#
+#   This hook parses compound commands (&&, ||, ;) and auto-approves
+#   when ALL components are in the safe list.
+#
+#   Solves the #1 most-reacted permission issue:
+#   GitHub #30519 (53 reactions) — "Permissions matching is broken"
+#   GitHub #16561 (101 reactions) — "Parse compound Bash commands"
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash"
+#
+# HOW IT WORKS:
+#   1. Splits command on &&, ||, ;
+#   2. Checks each component against safe patterns
+#   3. If ALL components are safe → auto-approve
+#   4. If ANY component is unknown → pass through (no opinion)
+#
+# SAFE PATTERNS (configurable via CC_SAFE_COMMANDS):
+#   - cd, ls, pwd, echo, cat, head, tail, wc, sort, uniq, grep
+#   - git (read-only: status, log, diff, branch, show, rev-parse, tag)
+#   - npm/yarn/pnpm (read-only: test, run, list, outdated, audit)
+#   - python/python3 (test: pytest, -m pytest, -m py_compile)
+#   - cargo test, go test, make test
+#
+# WHAT IT DOES NOT APPROVE:
+#   - git push, git reset, git clean (handled by other guards)
+#   - rm, sudo, chmod (handled by destructive-guard)
+#   - Any command not in the safe list
+# ================================================================
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+if [[ -z "$COMMAND" ]]; then
+    exit 0
+fi
+
+# Only handle compound commands
+if ! echo "$COMMAND" | grep -qE '&&|\|\||;'; then
+    exit 0
+fi
+
+# Split on &&, ||, ; and trim each component
+IFS=$'\n' read -r -d '' -a PARTS < <(echo "$COMMAND" | sed 's/&&/\n/g; s/||/\n/g; s/;/\n/g' && printf '\0')
+
+# Safe command patterns
+SAFE_PATTERNS=(
+    # Navigation/info
+    '^\s*cd\s'
+    '^\s*ls(\s|$)'
+    '^\s*pwd\s*$'
+    '^\s*echo\s'
+    '^\s*cat\s'
+    '^\s*head\s'
+    '^\s*tail\s'
+    '^\s*wc\s'
+    '^\s*sort(\s|$)'
+    '^\s*uniq(\s|$)'
+    '^\s*grep\s'
+    '^\s*find\s.*-name'
+    '^\s*test\s'
+    '^\s*\[\s'
+    '^\s*true\s*$'
+    '^\s*false\s*$'
+    '^\s*mkdir\s+-p\s'
+    # Git read-only
+    '^\s*git\s+(status|log|diff|branch|show|rev-parse|tag|remote|stash\s+list|describe|name-rev|ls-files|ls-tree|shortlog|blame|reflog)(\s|$)'
+    '^\s*git\s+-C\s+\S+\s+(status|log|diff|branch|show|rev-parse)(\s|$)'
+    '^\s*git\s+add\s'
+    '^\s*git\s+commit\s'
+    # npm/yarn/pnpm read + test
+    '^\s*(npm|yarn|pnpm)\s+(test|run|list|outdated|audit|info|view|pack|version)(\s|$)'
+    '^\s*npx\s'
+    # Python
+    '^\s*(python3?|pytest)\s'
+    # Build/test tools
+    '^\s*(cargo|go|make|gradle|mvn)\s+(test|build|check|verify|compile)(\s|$)'
+    '^\s*(ruff|mypy|flake8|pylint|black|isort)\s'
+    '^\s*(eslint|prettier|tsc)\s'
+    # Docker read-only
+    '^\s*docker\s+(ps|images|logs|inspect|stats|version)(\s|$)'
+)
+
+ALL_SAFE=1
+for part in "${PARTS[@]}"; do
+    part=$(echo "$part" | sed 's/^\s*//; s/\s*$//')
+    [[ -z "$part" ]] && continue
+
+    PART_SAFE=0
+    for pattern in "${SAFE_PATTERNS[@]}"; do
+        if echo "$part" | grep -qE "$pattern"; then
+            PART_SAFE=1
+            break
+        fi
+    done
+
+    if (( PART_SAFE == 0 )); then
+        ALL_SAFE=0
+        break
+    fi
+done
+
+if (( ALL_SAFE == 1 )); then
+    jq -n '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"compound command auto-approved (all components safe)"}}'
+    exit 0
+fi
+
+# Unknown component — let normal permission flow handle it
+exit 0

package/index.mjs

@@ -79,6 +79,7 @@ const IMPORT_IDX = process.argv.findIndex(a => a === '--import');
 const IMPORT_FILE = IMPORT_IDX !== -1 ? process.argv[IMPORT_IDX + 1] : null;
 const STATS = process.argv.includes('--stats');
 const JSON_OUTPUT = process.argv.includes('--json');
+const LINT = process.argv.includes('--lint');
 const CREATE_IDX = process.argv.findIndex(a => a === '--create');
 const CREATE_DESC = CREATE_IDX !== -1 ? process.argv.slice(CREATE_IDX + 1).join(' ') : null;
 
@@ -92,7 +93,7 @@ if (HELP) {
     npx cc-safe-setup --verify     Test each hook with sample inputs
     npx cc-safe-setup --dry-run    Preview without installing
     npx cc-safe-setup --uninstall  Remove all installed hooks
-    npx cc-safe-setup --examples   List 25 example hooks (5 categories)
+    npx cc-safe-setup --examples   List 27 example hooks (5 categories)
     npx cc-safe-setup --install-example <name>  Install a specific example
     npx cc-safe-setup --full       Complete setup: hooks + scan + audit + badge
     npx cc-safe-setup --audit      Safety score (0-100) with fixes
@@ -100,6 +101,7 @@ if (HELP) {
     npx cc-safe-setup --audit --json  Machine-readable output for CI/CD
     npx cc-safe-setup --scan       Detect tech stack, recommend hooks
     npx cc-safe-setup --learn      Learn from your block history
+    npx cc-safe-setup --lint       Static analysis of hook configuration
     npx cc-safe-setup --doctor     Diagnose why hooks aren't working
     npx cc-safe-setup --watch      Live dashboard of blocked commands
     npx cc-safe-setup --create "<desc>"  Generate a custom hook from description
@@ -767,6 +769,148 @@ async function fullSetup() {
   console.log();
 }
 
+async function lint() {
+  console.log();
+  console.log(c.bold + '  cc-safe-setup --lint' + c.reset);
+  console.log(c.dim + '  Static analysis of hook configuration...' + c.reset);
+  console.log();
+
+  if (!existsSync(SETTINGS_PATH)) {
+    console.log(c.red + '  No settings.json found.' + c.reset);
+    process.exit(1);
+  }
+
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(SETTINGS_PATH, 'utf-8'));
+  } catch (e) {
+    console.log(c.red + '  settings.json parse error: ' + e.message + c.reset);
+    process.exit(1);
+  }
+
+  let warnings = 0;
+  let errors = 0;
+  const warn = (msg) => { console.log(c.yellow + '  WARN: ' + c.reset + msg); warnings++; };
+  const error = (msg) => { console.log(c.red + '  ERROR: ' + c.reset + msg); errors++; };
+  const info = (msg) => { console.log(c.green + '  OK: ' + c.reset + msg); };
+
+  const hooks = settings.hooks || {};
+
+  // 1. Check for duplicate hook commands within same trigger
+  for (const [trigger, entries] of Object.entries(hooks)) {
+    const commands = [];
+    for (const entry of entries) {
+      for (const h of (entry.hooks || [])) {
+        if (h.command) {
+          if (commands.includes(h.command)) {
+            warn(trigger + ': duplicate hook "' + h.command.split('/').pop() + '"');
+          }
+          commands.push(h.command);
+        }
+      }
+    }
+    if (commands.length > 0 && new Set(commands).size === commands.length) {
+      info(trigger + ': no duplicates (' + commands.length + ' hooks)');
+    }
+  }
+
+  // 2. Check for empty matcher on PreToolUse (runs on every tool = slow)
+  for (const entry of (hooks.PreToolUse || [])) {
+    if (!entry.matcher || entry.matcher === '') {
+      const hookNames = (entry.hooks || []).map(h => (h.command || '').split('/').pop()).join(', ');
+      warn('PreToolUse hook with empty matcher runs on EVERY tool call: ' + hookNames);
+    }
+  }
+
+  // 3. Check for empty matcher on PostToolUse with heavy scripts
+  for (const entry of (hooks.PostToolUse || [])) {
+    if (!entry.matcher || entry.matcher === '') {
+      const hookNames = (entry.hooks || []).map(h => (h.command || '').split('/').pop()).join(', ');
+      // Check if any of these scripts are large (>5KB = potentially slow)
+      for (const h of (entry.hooks || [])) {
+        if (h.command) {
+          const resolved = h.command.replace(/^(bash|sh|node)\s+/, '').split(/\s+/)[0].replace(/^~/, HOME);
+          try {
+            const { statSync } = await import('fs');
+            const size = statSync(resolved).size;
+            if (size > 5000) {
+              warn('PostToolUse empty matcher + large script (' + (size/1024).toFixed(1) + 'KB): ' + resolved.split('/').pop());
+            }
+          } catch {}
+        }
+      }
+    }
+  }
+
+  // 4. Check for hooks that exist in settings but script is missing
+  for (const [trigger, entries] of Object.entries(hooks)) {
+    for (const entry of entries) {
+      for (const h of (entry.hooks || [])) {
+        if (h.command) {
+          let scriptPath = h.command.replace(/^(bash|sh|node|python3?)\s+/, '').split(/\s+/)[0];
+          scriptPath = scriptPath.replace(/^~/, HOME);
+          if (!existsSync(scriptPath)) {
+            error(trigger + ': missing script "' + scriptPath.split('/').pop() + '"');
+          }
+        }
+      }
+    }
+  }
+
+  // 5. Check for overly broad allow rules combined with no hooks
+  const allows = settings.permissions?.allow || [];
+  if (allows.includes('Bash(*)') && (hooks.PreToolUse || []).length === 0) {
+    error('Bash(*) in allow list with no PreToolUse hooks = no safety net');
+  } else if (allows.includes('Bash(*)') && (hooks.PreToolUse || []).length > 0) {
+    info('Bash(*) with PreToolUse hooks = hooks provide safety');
+  }
+
+  // 6. Check for conflicting allow and deny
+  const denies = settings.permissions?.deny || [];
+  for (const d of denies) {
+    if (allows.includes(d)) {
+      warn('Same pattern in both allow and deny: ' + d);
+    }
+  }
+
+  // 7. Check total hook count and warn about performance
+  let totalHooks = 0;
+  for (const entries of Object.values(hooks)) {
+    for (const entry of entries) {
+      totalHooks += (entry.hooks || []).length;
+    }
+  }
+  if (totalHooks > 20) {
+    warn(totalHooks + ' total hooks registered — may slow down tool calls');
+  } else if (totalHooks > 0) {
+    info(totalHooks + ' hooks registered');
+  }
+
+  // 8. Check for hooks without type: "command"
+  for (const [trigger, entries] of Object.entries(hooks)) {
+    for (const entry of entries) {
+      for (const h of (entry.hooks || [])) {
+        if (h.type !== 'command') {
+          warn(trigger + ': hook with type "' + h.type + '" (only "command" is supported)');
+        }
+      }
+    }
+  }
+
+  // Summary
+  console.log();
+  if (errors === 0 && warnings === 0) {
+    console.log(c.bold + c.green + '  Clean. No issues found.' + c.reset);
+  } else if (errors === 0) {
+    console.log(c.bold + c.yellow + '  ' + warnings + ' warning(s). No errors.' + c.reset);
+  } else {
+    console.log(c.bold + c.red + '  ' + errors + ' error(s), ' + warnings + ' warning(s).' + c.reset);
+  }
+  console.log();
+
+  process.exit(errors > 0 ? 1 : 0);
+}
+
 async function createHook(description) {
   console.log();
   console.log(c.bold + '  cc-safe-setup --create' + c.reset);
@@ -1688,6 +1832,7 @@ async function main() {
   if (FULL) return fullSetup();
   if (DOCTOR) return doctor();
   if (WATCH) return watch();
+  if (LINT) return lint();
   if (CREATE_DESC) return createHook(CREATE_DESC);
   if (STATS) return stats();
   if (EXPORT) return exportConfig();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cc-safe-setup",
-  "version": "3.0.1",
-  "description": "One command to make Claude Code safe for autonomous operation. 8 built-in hooks + 26 installable examples. Destructive blocker, branch guard, database wipe protection, case-insensitive FS guard, and more.",
+  "version": "3.2.0",
+  "description": "One command to make Claude Code safe for autonomous operation. 8 built-in hooks + 27 installable examples. Destructive blocker, branch guard, compound command approver, database wipe protection, and more.",
   "main": "index.mjs",
   "bin": {
     "cc-safe-setup": "index.mjs"