cc-safe-setup 3.1.0 → 3.2.0

package/README.md

@@ -220,6 +220,10 @@ Or browse all available examples in [`examples/`](examples/):
 
 **[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.

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/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;
 
@@ -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.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": {