cc-safe-setup 28.4.9 → 28.6.0

package/COOKBOOK.md

@@ -0,0 +1,153 @@
+# Cookbook — cc-safe-setup Recipes
+
+Real-world recipes for common safety scenarios. Each recipe is a single command.
+
+## Getting Started
+
+| I want to... | Command |
+|---|---|
+| Install basic safety | `npx cc-safe-setup` |
+| Maximum protection | `npx cc-safe-setup --shield` |
+| Check my setup | `npx cc-safe-setup --doctor` |
+| See my safety score | `npx cc-safe-setup --audit` |
+
+## Blocking Dangerous Commands
+
+### Block rm -rf on home/root
+Already included in the default install. To verify:
+```bash
+npx cc-safe-setup --simulate "rm -rf ~"
+# Expected: BLOCKED
+```
+
+### Block database wipes
+```bash
+npx cc-safe-setup --install-example block-database-wipe
+```
+Blocks: `prisma migrate reset`, `rails db:drop`, `DROP TABLE`, etc.
+
+### Block npm publish accidents
+```bash
+npx cc-safe-setup --install-example npm-publish-guard
+```
+
+## Auto-Approving Safe Commands
+
+### Approve read-only commands (cat, ls, grep)
+```bash
+npx cc-safe-setup --install-example auto-approve-readonly
+```
+
+### Approve test runners
+```bash
+npx cc-safe-setup --install-example auto-approve-test
+```
+Covers: `npm test`, `pytest`, `go test`, `cargo test`, `jest`, `vitest`
+
+### Approve git read commands (status, log, diff)
+```bash
+npx cc-safe-setup --install-example auto-approve-git-read
+```
+
+## File Protection
+
+### Protect .env files from edits
+```bash
+npx cc-safe-setup --protect .env
+```
+
+### Protect CLAUDE.md from unauthorized changes
+```bash
+npx cc-safe-setup --install-example protect-claudemd
+```
+
+### Protect dotfiles (~/.bashrc, ~/.aws/)
+```bash
+npx cc-safe-setup --install-example protect-dotfiles
+```
+
+## YAML Rules (No Coding)
+
+Write rules in YAML, compile to hooks:
+
+```yaml
+# rules.yaml
+- block: "rm -rf on root"
+  pattern: "rm\s+-rf\s+(\/$|~)"
+
+- approve: "read-only commands"
+  commands: [cat, ls, grep, head, tail]
+
+- protect: ".env"
+```
+
+```bash
+npx cc-safe-setup --rules rules.yaml
+```
+
+## Monitoring & Recovery
+
+### Auto-save checkpoint before compaction
+```bash
+npx cc-safe-setup --install-example auto-compact-prep
+```
+
+### Track context window usage
+```bash
+npx cc-safe-setup --install-example compact-reminder
+```
+
+### Fix hook permissions on Windows/plugins
+```bash
+npx cc-safe-setup --install-example hook-permission-fixer
+```
+
+### Prevent tool call loops
+```bash
+npx cc-safe-setup --install-example response-budget-guard
+```
+
+## Diagnosing Problems
+
+### Why isn't my hook working?
+```bash
+npx cc-safe-setup --doctor
+```
+Checks: jq, settings.json, file existence, permissions, shebangs, exit codes.
+
+### Test a specific hook
+```bash
+npx cc-safe-setup --test-hook destructive-guard
+```
+
+### Preview how hooks react to a command
+```bash
+npx cc-safe-setup --simulate "git push --force origin main"
+```
+
+## Web Tools
+
+All browser-based, nothing leaves your machine:
+
+- [Safety Hub](https://yurukusa.github.io/cc-safe-setup/hub.html) — All 23 tools
+- [Validator](https://yurukusa.github.io/cc-safe-setup/validator.html) — Paste settings.json, get score
+- [Permission Checker](https://yurukusa.github.io/cc-safe-setup/permission-checker.html) — Find broken paths
+- [Playground](https://yurukusa.github.io/cc-safe-setup/playground.html) — Write and test hooks
+- [Hook Builder](https://yurukusa.github.io/cc-safe-setup/builder.html) — Generate hooks from English
+
+## 27. Bypass Protected Directory Prompts (PermissionRequest)
+
+PreToolUse hooks can't bypass built-in protected-directory checks — they run *before* those checks. Use PermissionRequest instead:
+
+```bash
+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.
+
+## Further Reading
+
+- [Getting Started](https://yurukusa.github.io/cc-safe-setup/getting-started.html)
+- [Common Mistakes](https://yurukusa.github.io/cc-safe-setup/common-mistakes.html)
+- [Troubleshooting](TROUBLESHOOTING.md)
+- [Settings Reference](SETTINGS_REFERENCE.md)

package/README.md

@@ -87,7 +87,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 316 examples |
+| `--install-example <name>` | Install from 331 examples |
 | `--examples [filter]` | Browse examples by keyword |
 | `--full` | All-in-one setup |
 | `--status` | Check installed hooks |
@@ -356,6 +356,7 @@ 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
 - [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) — この記事の日本語解説

package/TROUBLESHOOTING.md

@@ -132,6 +132,34 @@ jq -n '...'
 
 Auto-approve JSON must go to stdout.
 
+## "PreToolUse allow doesn't bypass protected directory prompts"
+
+This is expected behavior, not a bug.
+
+**Execution order:**
+1. PreToolUse hooks run
+2. Built-in protected-directory checks run (`.claude/`, `.git/`, etc.)
+3. PermissionRequest hooks run
+
+PreToolUse's `permissionDecision: "allow"` gets overridden by the built-in checks in step 2. To bypass protected directory prompts, use **PermissionRequest** hooks instead:
+
+```bash
+#!/bin/bash
+# Save as: ~/.claude/hooks/allow-protected-dir.sh
+# Trigger: PermissionRequest (not PreToolUse)
+INPUT=$(cat)
+PATH_TARGET=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.command // empty')
+
+# Allow writes to a specific protected directory
+if echo "$PATH_TARGET" | grep -q '/my-project/.git/hooks'; then
+  jq -n '{hookSpecificOutput: {hookEventName: "PermissionRequest", permissionDecision: "allow", permissionDecisionReason: "Allowed: git hooks directory"}}'
+  exit 0
+fi
+exit 0
+```
+
+**Rule of thumb:** PreToolUse = block dangerous actions. PermissionRequest = allow trusted actions that trigger built-in prompts.
+
 ## "Permission prompts still appear for compound commands"
 
 This is a known Claude Code limitation, not a hook issue. `Bash(git:*)` doesn't match `cd /path && git log`.

package/examples/allow-git-hooks-dir.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# allow-git-hooks-dir.sh — PermissionRequest hook
+# Trigger: PermissionRequest
+# Matcher: Edit|Write
+#
+# Bypasses the built-in protected-directory prompt for .git/hooks/.
+# PreToolUse hooks can't do this — they run before built-in checks.
+# PermissionRequest runs after, so it can override the prompt.
+#
+# WARNING: Only allow specific subdirectories you trust.
+# Never blanket-allow all of .git/ — that exposes HEAD, config, etc.
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE_PATH" ] && exit 0
+
+# Only allow .git/hooks/ writes (e.g., pre-commit, pre-push)
+if echo "$FILE_PATH" | grep -qE '\.git/hooks/[^/]+$'; then
+  jq -n '{
+    hookSpecificOutput: {
+      hookEventName: "PermissionRequest",
+      permissionDecision: "allow",
+      permissionDecisionReason: "Allowed: git hooks directory"
+    }
+  }'
+  exit 0
+fi
+
+exit 0

package/index.mjs

@@ -601,9 +601,12 @@ async function installExample(name) {
   let matcher = 'Bash';
 
   // Detect trigger from header comments
-  if (content.includes('PostToolUse')) trigger = 'PostToolUse';
-  if (content.includes('Notification')) trigger = 'Notification';
-  if (content.includes('Stop')) trigger = 'Stop';
+  if (content.includes('TRIGGER: PostToolUse') || content.includes('PostToolUse')) trigger = 'PostToolUse';
+  if (content.includes('TRIGGER: Notification') || content.includes('Notification')) trigger = 'Notification';
+  if (content.includes('TRIGGER: Stop') || content.includes('Stop')) trigger = 'Stop';
+  if (content.includes('TRIGGER: SessionStart') || content.includes('SessionStart')) trigger = 'SessionStart';
+  if (content.includes('TRIGGER: PreCompact') || content.includes('PreCompact')) trigger = 'PreCompact';
+  if (content.includes('TRIGGER: SessionEnd') || content.includes('SessionEnd')) trigger = 'SessionEnd';
 
   // Detect matcher from header
   const matcherMatch = content.match(/"matcher":\s*"([^"]*)"/);
@@ -5350,7 +5353,7 @@ async function main() {
   console.log('  ' + c.blue + '  --simulate "cmd"' + c.reset + '    Test how hooks react');
   console.log('  ' + c.blue + '  --shield' + c.reset + '            Maximum safety (recommended)');
   console.log();
-  console.log('  ' + c.dim + '22 web tools: https://yurukusa.github.io/cc-safe-setup/hub.html' + c.reset);
+  console.log('  ' + c.dim + '23 web tools: https://yurukusa.github.io/cc-safe-setup/hub.html' + c.reset);
   console.log();
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cc-safe-setup",
-  "version": "28.4.9",
-  "description": "One command to make Claude Code safe. 336 hooks (8 built-in + 330 examples). 49 CLI commands. 988 tests. 5 languages.",
+  "version": "28.6.0",
+  "description": "One command to make Claude Code safe. 337 hooks (8 built-in + 331 examples). 49 CLI commands. 996 tests. 5 languages.",
   "main": "index.mjs",
   "bin": {
     "cc-safe-setup": "index.mjs"