cc-safe-setup 3.1.0 → 3.2.1

package/README.md

@@ -215,11 +215,16 @@ Or browse all available examples in [`examples/`](examples/):
 - **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))
+- **tmp-cleanup.sh** — Clean up accumulated `/tmp/claude-*-cwd` files on session end ([#8856](https://github.com/anthropics/claude-code/issues/8856))
 
 ## 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.
@@ -230,6 +235,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
+- [Hooks Cheat Sheet](https://yurukusa.github.io/cc-safe-setup/cheatsheet.html) — printable A4 quick reference
 - [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
 

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/docs/cheatsheet.html

@@ -0,0 +1,187 @@
+<!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 Cheat Sheet</title>
+<style>
+@media print { body { padding: 0; background: #fff; color: #000; font-size: 9px; } .no-print { display: none; } h1 { font-size: 14px; } h2 { font-size: 11px; } pre { font-size: 8px; border: 1px solid #ccc; } .col { break-inside: avoid; } }
+@media screen { body { background: #0d1117; color: #c9d1d9; padding: 1rem; } pre { background: #161b22; border: 1px solid #30363d; } h1 { color: #f0f6fc; } h2 { color: #f0f6fc; } a { color: #58a6ff; } }
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', monospace; font-size: 11px; line-height: 1.4; }
+.container { max-width: 900px; margin: 0 auto; columns: 2; column-gap: 1.5rem; }
+h1 { font-size: 16px; margin-bottom: 0.3rem; text-align: center; column-span: all; }
+.subtitle { text-align: center; margin-bottom: 0.8rem; font-size: 10px; opacity: 0.7; column-span: all; }
+h2 { font-size: 12px; margin: 0.6rem 0 0.3rem; border-bottom: 1px solid #30363d; padding-bottom: 0.15rem; }
+pre { padding: 0.4rem; border-radius: 4px; overflow-x: auto; font-size: 9.5px; margin: 0.2rem 0 0.4rem; white-space: pre-wrap; word-break: break-all; }
+.col { break-inside: avoid; margin-bottom: 0.3rem; }
+table { width: 100%; border-collapse: collapse; font-size: 9.5px; margin: 0.2rem 0; }
+th, td { text-align: left; padding: 0.15rem 0.3rem; border-bottom: 1px solid #21262d; }
+th { font-weight: 600; }
+code { font-size: 9px; padding: 0.1rem 0.2rem; border-radius: 2px; }
+@media screen { code { background: #161b22; } }
+.footer { text-align: center; font-size: 8px; opacity: 0.5; margin-top: 0.5rem; column-span: all; }
+</style>
+</head>
+<body>
+<h1>Claude Code Hooks Cheat Sheet</h1>
+<p class="subtitle">Quick reference · Print this page (Ctrl+P) · <a href="https://github.com/yurukusa/cc-safe-setup" class="no-print">github.com/yurukusa/cc-safe-setup</a></p>
+
+<div class="container">
+
+<div class="col">
+<h2>Hook Lifecycle</h2>
+<pre>Prompt → PreToolUse → Tool Executes → PostToolUse → Stop
+         ↑ block here                  ↑ check here    ↑ log here</pre>
+</div>
+
+<div class="col">
+<h2>Exit Codes</h2>
+<table>
+<tr><th>Code</th><th>Meaning</th></tr>
+<tr><td><code>0</code></td><td>Allow (or no opinion)</td></tr>
+<tr><td><code>2</code></td><td><strong>Block</strong> — tool call cancelled</td></tr>
+<tr><td>other</td><td>Error (treated as allow)</td></tr>
+</table>
+</div>
+
+<div class="col">
+<h2>Hook Events</h2>
+<table>
+<tr><th>Event</th><th>Matcher</th><th>Use</th></tr>
+<tr><td>PreToolUse</td><td>Bash</td><td>Block commands</td></tr>
+<tr><td>PostToolUse</td><td>Edit|Write</td><td>Syntax check</td></tr>
+<tr><td>PostToolUse</td><td>(empty)</td><td>All tools</td></tr>
+<tr><td>Stop</td><td>(empty)</td><td>Session end</td></tr>
+<tr><td>UserPromptSubmit</td><td>—</td><td>Validate input</td></tr>
+</table>
+</div>
+
+<div class="col">
+<h2>settings.json Structure</h2>
+<pre>{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "~/.claude/hooks/guard.sh"
+      }]
+    }]
+  }
+}</pre>
+</div>
+
+<div class="col">
+<h2>Minimal Block Hook</h2>
+<pre>#!/bin/bash
+COMMAND=$(cat | jq -r '.tool_input.command // empty')
+[ -z "$COMMAND" ] && exit 0
+if echo "$COMMAND" | grep -qE 'PATTERN'; then
+    echo "BLOCKED: reason" >&2
+    exit 2
+fi
+exit 0</pre>
+</div>
+
+<div class="col">
+<h2>Auto-Approve Hook</h2>
+<pre>#!/bin/bash
+COMMAND=$(cat | jq -r '.tool_input.command // empty')
+[ -z "$COMMAND" ] && exit 0
+if echo "$COMMAND" | grep -qE '^\s*git\s+(status|log|diff)'; then
+    jq -n '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "allow"
+      }
+    }'
+fi
+exit 0</pre>
+</div>
+
+<div class="col">
+<h2>PostToolUse Syntax Check</h2>
+<pre>#!/bin/bash
+FILE=$(cat | jq -r '.tool_input.file_path // empty')
+[ -z "$FILE" ] || [ ! -f "$FILE" ] && exit 0
+case "${FILE##*.}" in
+  py) python3 -m py_compile "$FILE" 2>&1 ;;
+  sh) bash -n "$FILE" 2>&1 ;;
+  json) jq empty "$FILE" 2>&1 ;;
+  js) node --check "$FILE" 2>&1 ;;
+esac
+exit 0</pre>
+</div>
+
+<div class="col">
+<h2>Modify Input</h2>
+<pre>#!/bin/bash
+# Strip comments from bash commands
+COMMAND=$(cat | jq -r '.tool_input.command // empty')
+CLEAN=$(echo "$COMMAND" | sed '/^#/d; /^$/d')
+[ "$CLEAN" = "$COMMAND" ] && exit 0
+jq -n --arg cmd "$CLEAN" '{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "updatedInput": {"command": $cmd}
+  }
+}'</pre>
+</div>
+
+<div class="col">
+<h2>stdin JSON Reference</h2>
+<table>
+<tr><th>Event</th><th>Key Fields</th></tr>
+<tr><td>PreToolUse (Bash)</td><td><code>.tool_input.command</code></td></tr>
+<tr><td>PreToolUse (Edit)</td><td><code>.tool_input.file_path</code></td></tr>
+<tr><td>PostToolUse</td><td><code>.tool_input.file_path</code></td></tr>
+<tr><td>Stop</td><td><code>.stop_reason</code></td></tr>
+<tr><td>UserPromptSubmit</td><td><code>.prompt</code></td></tr>
+</table>
+</div>
+
+<div class="col">
+<h2>Test a Hook</h2>
+<pre># Manual test
+echo '{"tool_input":{"command":"rm -rf /"}}' \
+  | bash ~/.claude/hooks/guard.sh
+echo $?  # 2 = blocked
+
+# Auto-test
+npx cc-hook-test ~/.claude/hooks/guard.sh</pre>
+</div>
+
+<div class="col">
+<h2>Quick Setup Commands</h2>
+<table>
+<tr><td><code>npx cc-safe-setup</code></td><td>Install 8 hooks</td></tr>
+<tr><td><code>--create "desc"</code></td><td>Generate hook</td></tr>
+<tr><td><code>--audit</code></td><td>Safety score</td></tr>
+<tr><td><code>--lint</code></td><td>Config analysis</td></tr>
+<tr><td><code>--doctor</code></td><td>Diagnose issues</td></tr>
+<tr><td><code>--watch</code></td><td>Live dashboard</td></tr>
+<tr><td><code>--stats</code></td><td>Block statistics</td></tr>
+<tr><td><code>--verify</code></td><td>Test all hooks</td></tr>
+<tr><td><code>--export</code></td><td>Share with team</td></tr>
+</table>
+</div>
+
+<div class="col">
+<h2>Common Patterns</h2>
+<table>
+<tr><th>Block</th><th>Pattern</th></tr>
+<tr><td>rm -rf /</td><td><code>rm\s+(-[rf]+\s+)*/</code></td></tr>
+<tr><td>force push</td><td><code>git\s+push.*--force</code></td></tr>
+<tr><td>push main</td><td><code>git\s+push.*main</code></td></tr>
+<tr><td>.env commit</td><td><code>git\s+add.*\.env</code></td></tr>
+<tr><td>git reset</td><td><code>git\s+reset\s+--hard</code></td></tr>
+<tr><td>DB wipe</td><td><code>migrate:fresh|DROP\s+DB</code></td></tr>
+</table>
+</div>
+
+</div>
+
+<p class="footer">cc-safe-setup v3.2.0 · 20 recipes: <a href="https://github.com/yurukusa/claude-code-hooks/blob/main/COOKBOOK.md" class="no-print">COOKBOOK.md</a> · Full ref: <a href="https://github.com/yurukusa/cc-safe-setup/blob/main/SETTINGS_REFERENCE.md" class="no-print">SETTINGS_REFERENCE.md</a></p>
+</body>
+</html>

package/examples/tmp-cleanup.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# ================================================================
+# tmp-cleanup.sh — Clean up /tmp/claude-*-cwd temp files
+# ================================================================
+# PURPOSE:
+#   Claude Code creates /tmp/claude-{hex}-cwd files to track working
+#   directory changes but never deletes them. Over time, thousands
+#   accumulate.
+#
+#   This hook runs on session end and cleans up stale files.
+#
+#   GitHub #8856 (67 reactions, 102 comments) — the most reported
+#   resource leak in Claude Code.
+#
+# TRIGGER: Stop
+# MATCHER: ""
+#
+# WHAT IT CLEANS:
+#   - /tmp/claude-*-cwd (working directory tracking files, ~22 bytes each)
+#   - Only files older than 1 hour (to avoid cleaning active sessions)
+#
+# WHAT IT DOES NOT CLEAN:
+#   - /tmp/claude-* directories (may be in use by other sessions)
+#   - Any non-claude temp files
+# ================================================================
+
+# Clean up stale cwd tracking files (older than 60 minutes)
+find /tmp -maxdepth 1 -name 'claude-*-cwd' -type f -mmin +60 -delete 2>/dev/null
+
+# Count remaining (for logging)
+REMAINING=$(find /tmp -maxdepth 1 -name 'claude-*-cwd' -type f 2>/dev/null | wc -l)
+if [ "$REMAINING" -gt 100 ]; then
+    echo "NOTE: $REMAINING claude-*-cwd files remain in /tmp (active sessions)" >&2
+fi
+
+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 27 example hooks (5 categories)
+    npx cc-safe-setup --examples   List 28 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,6 +1,6 @@
 {
   "name": "cc-safe-setup",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "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": {