cc-safe-setup 3.7.0 → 3.8.1

package/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to cc-safe-setup
+
+Thanks for considering a contribution. Here's how to add a new hook.
+
+## Adding an Example Hook
+
+1. Create `examples/your-hook-name.sh`
+2. Add the standard header comment:
+
+```bash
+#!/bin/bash
+# ================================================================
+# your-hook-name.sh — Short description
+# ================================================================
+# PURPOSE: What it does and why
+# TRIGGER: PreToolUse | PostToolUse | Stop
+# MATCHER: "Bash" | "Edit|Write" | ""
+# ================================================================
+```
+
+3. Handle empty input:
+
+```bash
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+```
+
+4. Use exit codes correctly:
+   - `exit 0` = allow
+   - `exit 2` = block
+   - Never use `exit 1` for blocking
+
+5. Add to `index.mjs` categories (search for `CATEGORIES`)
+6. Add to `README.md` examples list
+7. Run tests: `bash test.sh`
+
+## Testing Your Hook
+
+```bash
+# Manual test
+echo '{"tool_input":{"command":"your test command"}}' | bash examples/your-hook.sh
+echo $?
+
+# Auto-test
+npx cc-hook-test examples/your-hook.sh
+```
+
+## Hook Quality Checklist
+
+- [ ] Handles empty input (exits 0)
+- [ ] Uses `exit 2` for blocking (not `exit 1`)
+- [ ] Has descriptive stderr messages on block
+- [ ] Passes `bash -n` syntax check
+- [ ] Linked to a GitHub Issue if applicable
+- [ ] Added to README.md and index.mjs categories
+
+## Pull Request Process
+
+1. Fork and create a branch
+2. Add your hook + update README + update categories
+3. Run `bash test.sh` (all must pass)
+4. Submit PR with:
+   - What the hook does
+   - Which GitHub Issue inspired it (if any)
+   - Test evidence (manual or cc-hook-test output)
+
+## Code Style
+
+- Bash hooks (not Python/Node) for zero dependencies
+- `jq` for JSON parsing
+- Short variable names are fine (`CMD`, `FILE`, `INPUT`)
+- Comments explain *why*, not *what*

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.**
+**One command to make Claude Code safe for autonomous operation.** [日本語](docs/README.ja.md)
 
 8 built-in hooks + 32 installable examples. Audit, create, lint, diff, watch, and learn. [Cheat Sheet](https://yurukusa.github.io/cc-safe-setup/cheatsheet.html) · [Web Tool](https://yurukusa.github.io/cc-safe-setup/) · [Troubleshooting](TROUBLESHOOTING.md)
 
@@ -224,6 +224,8 @@ Or browse all available examples in [`examples/`](examples/):
 - **session-handoff.sh** — Auto-save git state and session info to `~/.claude/session-handoff.md` on session end
 - **diff-size-guard.sh** — Warn/block when committing too many files at once (default: warn at 10, block at 50)
 - **dependency-audit.sh** — Warn when installing packages not in manifest (npm/pip/cargo supply chain awareness)
+- **cost-tracker.sh** — Estimate session token cost and warn at thresholds ($1, $5)
+- **read-before-edit.sh** — Warn when editing files not recently read (prevents old_string mismatches)
 
 ## Safety Checklist
 
@@ -244,7 +246,7 @@ Or browse all available examples in [`examples/`](examples/):
 ## Learn More
 
 - [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) — 19 ready-to-use recipes from real GitHub Issues
+- [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) — この記事の日本語解説
 - [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

package/audit-web/index.html

@@ -88,6 +88,31 @@ a { color: #58a6ff; text-decoration: none; }
 <div class="tab-content" id="tab-fix"></div>
 <div class="tab-content" id="tab-manual"></div>
 
+<h2 style="margin-top:2rem">Hook Builder</h2>
+<p class="subtitle">Build a custom hook without writing code.</p>
+
+<div style="display:flex;gap:1rem;flex-wrap:wrap;margin:.5rem 0">
+  <div style="flex:1;min-width:200px">
+    <label style="color:#8b949e;font-size:.8rem">What should the hook do?</label>
+    <select id="hb-action" style="width:100%;padding:.5rem;background:#161b22;border:1px solid #30363d;border-radius:4px;color:#c9d1d9;margin-top:.25rem">
+      <option value="block">Block a command</option>
+      <option value="warn">Warn about a command</option>
+      <option value="approve">Auto-approve a command</option>
+    </select>
+  </div>
+  <div style="flex:2;min-width:300px">
+    <label style="color:#8b949e;font-size:.8rem">Command pattern (regex)</label>
+    <input id="hb-pattern" placeholder="e.g. rm\s+-rf, git push --force, npm publish" style="width:100%;padding:.5rem;background:#161b22;border:1px solid #30363d;border-radius:4px;color:#c9d1d9;margin-top:.25rem;font-family:monospace;font-size:.85rem">
+  </div>
+</div>
+<div style="margin:.5rem 0">
+  <label style="color:#8b949e;font-size:.8rem">Message shown to Claude</label>
+  <input id="hb-message" placeholder="e.g. Run tests before publishing" style="width:100%;padding:.5rem;background:#161b22;border:1px solid #30363d;border-radius:4px;color:#c9d1d9;margin-top:.25rem">
+</div>
+<button class="btn" onclick="buildHook()">Generate Hook</button>
+
+<div id="hb-result" style="margin-top:1rem"></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> · <a href="ecosystem.html">Compare all hook projects</a></p>
 </div>
 
@@ -599,6 +624,48 @@ exit 0`
   return scripts[id] || '#!/bin/bash\nexit 0';
 }
 
+function buildHook() {
+  const action = document.getElementById('hb-action').value;
+  const pattern = document.getElementById('hb-pattern').value.trim();
+  const message = document.getElementById('hb-message').value.trim() || 'Blocked by hook';
+  const el = document.getElementById('hb-result');
+
+  if (!pattern) { el.innerHTML = '<p style="color:#f85149">Enter a command pattern.</p>'; return; }
+
+  let script = '#!/bin/bash\n';
+  script += 'INPUT=$(cat)\n';
+  script += 'COMMAND=$(echo "$INPUT" | jq -r \'.tool_input.command // empty\' 2>/dev/null)\n';
+  script += '[ -z "$COMMAND" ] && exit 0\n\n';
+
+  if (action === 'block') {
+    script += 'if echo "$COMMAND" | grep -qE \'' + pattern.replace(/'/g, "'\\''") + '\'; then\n';
+    script += '    echo "BLOCKED: ' + message.replace(/"/g, '\\"') + '" >&2\n';
+    script += '    echo "Command: $COMMAND" >&2\n';
+    script += '    exit 2\n';
+    script += 'fi\n';
+  } else if (action === 'warn') {
+    script += 'if echo "$COMMAND" | grep -qE \'' + pattern.replace(/'/g, "'\\''") + '\'; then\n';
+    script += '    echo "WARNING: ' + message.replace(/"/g, '\\"') + '" >&2\n';
+    script += '    echo "Command: $COMMAND" >&2\n';
+    script += 'fi\n';
+  } else if (action === 'approve') {
+    script += 'if echo "$COMMAND" | grep -qE \'' + pattern.replace(/'/g, "'\\''") + '\'; then\n';
+    script += '    jq -n \'{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"' + message.replace(/"/g, '\\"') + '"}}\'\n';
+    script += 'fi\n';
+  }
+  script += 'exit 0';
+
+  const settings = {
+    hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: '~/.claude/hooks/custom-hook.sh' }] }] }
+  };
+
+  el.innerHTML = '<h3>Hook Script</h3>' +
+    '<div class="code-block"><button class="copy-btn" onclick="copyText(\'hb-script\')">Copy</button><pre id="hb-script">' + escHtml(script) + '</pre></div>' +
+    '<h3>settings.json entry</h3>' +
+    '<div class="code-block"><button class="copy-btn" onclick="copyText(\'hb-settings\')">Copy</button><pre id="hb-settings">' + escHtml(JSON.stringify(settings, null, 2)) + '</pre></div>' +
+    '<p style="color:#8b949e;font-size:.8rem;margin-top:.5rem">Save the script as <code>~/.claude/hooks/custom-hook.sh</code>, run <code>chmod +x</code>, and merge the settings entry.</p>';
+}
+
 // Auto-load from URL parameter: ?config=base64encodedJSON
 (function() {
   const params = new URLSearchParams(window.location.search);

package/docs/README.ja.md

@@ -0,0 +1,64 @@
+# cc-safe-setup
+
+**Claude Codeを安全にするワンコマンドツール。**
+
+8個の安全フック + 36個のインストール可能なexample。destructive guard、branch protection、secret leak prevention、syntax check、context monitor、その他。
+
+```bash
+npx cc-safe-setup
+```
+
+## 何ができるか
+
+| コマンド | 機能 |
+|---|---|
+| `npx cc-safe-setup` | 8個の安全フックをインストール |
+| `--create "説明"` | 自然言語でカスタムフック生成 |
+| `--audit` | 安全スコア（0-100） |
+| `--lint` | 設定の静的解析 |
+| `--diff <file>` | 設定を比較 |
+| `--benchmark` | フック実行速度を計測 |
+| `--doctor` | 動かない原因を診断 |
+| `--watch` | ブロックされたコマンドをリアルタイム表示 |
+| `--stats` | ブロック統計レポート |
+| `--share` | 共有URLを生成 |
+| `--export / --import` | チームで設定を共有 |
+| `--verify` | 各フックの動作確認 |
+| `--install-example <name>` | 36個のexampleフック |
+
+## インストール
+
+```bash
+npx cc-safe-setup
+```
+
+Claude Codeを再起動。完了。
+
+## 何がブロックされるか
+
+| 操作 | Before | After |
+|---|---|---|
+| `rm -rf /` | 実行される | ブロック |
+| `git push --force` | 実行される | ブロック |
+| `git push origin main` | 実行される | ブロック |
+| `git add .env` | 実行される | ブロック |
+| Python構文エラー | 気づかない | 自動検出 |
+| コンテキスト枯渇 | 突然死 | 段階的警告 |
+
+## ドキュメント
+
+- [settings.jsonリファレンス](../SETTINGS_REFERENCE.md) — 全設定の解説
+- [移行ガイド](../MIGRATION.md) — permissionsからhooksへ
+- [トラブルシューティング](../TROUBLESHOOTING.md) — 動かない時の対処法
+- [チートシート](https://yurukusa.github.io/cc-safe-setup/cheatsheet.html) — 印刷用A4
+- [エコシステム比較](https://yurukusa.github.io/cc-safe-setup/ecosystem.html) — 全hookプロジェクト比較
+- [Web版](https://yurukusa.github.io/cc-safe-setup/) — ブラウザで診断＋セットアップ生成
+
+## 必要なもの
+
+- `jq`: `brew install jq` / `apt install jq`
+- Claude Code 2.1以上
+
+## ライセンス
+
+MIT

package/docs/index.html

@@ -88,6 +88,31 @@ a { color: #58a6ff; text-decoration: none; }
 <div class="tab-content" id="tab-fix"></div>
 <div class="tab-content" id="tab-manual"></div>
 
+<h2 style="margin-top:2rem">Hook Builder</h2>
+<p class="subtitle">Build a custom hook without writing code.</p>
+
+<div style="display:flex;gap:1rem;flex-wrap:wrap;margin:.5rem 0">
+  <div style="flex:1;min-width:200px">
+    <label style="color:#8b949e;font-size:.8rem">What should the hook do?</label>
+    <select id="hb-action" style="width:100%;padding:.5rem;background:#161b22;border:1px solid #30363d;border-radius:4px;color:#c9d1d9;margin-top:.25rem">
+      <option value="block">Block a command</option>
+      <option value="warn">Warn about a command</option>
+      <option value="approve">Auto-approve a command</option>
+    </select>
+  </div>
+  <div style="flex:2;min-width:300px">
+    <label style="color:#8b949e;font-size:.8rem">Command pattern (regex)</label>
+    <input id="hb-pattern" placeholder="e.g. rm\s+-rf, git push --force, npm publish" style="width:100%;padding:.5rem;background:#161b22;border:1px solid #30363d;border-radius:4px;color:#c9d1d9;margin-top:.25rem;font-family:monospace;font-size:.85rem">
+  </div>
+</div>
+<div style="margin:.5rem 0">
+  <label style="color:#8b949e;font-size:.8rem">Message shown to Claude</label>
+  <input id="hb-message" placeholder="e.g. Run tests before publishing" style="width:100%;padding:.5rem;background:#161b22;border:1px solid #30363d;border-radius:4px;color:#c9d1d9;margin-top:.25rem">
+</div>
+<button class="btn" onclick="buildHook()">Generate Hook</button>
+
+<div id="hb-result" style="margin-top:1rem"></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> · <a href="ecosystem.html">Compare all hook projects</a></p>
 </div>
 
@@ -599,6 +624,48 @@ exit 0`
   return scripts[id] || '#!/bin/bash\nexit 0';
 }
 
+function buildHook() {
+  const action = document.getElementById('hb-action').value;
+  const pattern = document.getElementById('hb-pattern').value.trim();
+  const message = document.getElementById('hb-message').value.trim() || 'Blocked by hook';
+  const el = document.getElementById('hb-result');
+
+  if (!pattern) { el.innerHTML = '<p style="color:#f85149">Enter a command pattern.</p>'; return; }
+
+  let script = '#!/bin/bash\n';
+  script += 'INPUT=$(cat)\n';
+  script += 'COMMAND=$(echo "$INPUT" | jq -r \'.tool_input.command // empty\' 2>/dev/null)\n';
+  script += '[ -z "$COMMAND" ] && exit 0\n\n';
+
+  if (action === 'block') {
+    script += 'if echo "$COMMAND" | grep -qE \'' + pattern.replace(/'/g, "'\\''") + '\'; then\n';
+    script += '    echo "BLOCKED: ' + message.replace(/"/g, '\\"') + '" >&2\n';
+    script += '    echo "Command: $COMMAND" >&2\n';
+    script += '    exit 2\n';
+    script += 'fi\n';
+  } else if (action === 'warn') {
+    script += 'if echo "$COMMAND" | grep -qE \'' + pattern.replace(/'/g, "'\\''") + '\'; then\n';
+    script += '    echo "WARNING: ' + message.replace(/"/g, '\\"') + '" >&2\n';
+    script += '    echo "Command: $COMMAND" >&2\n';
+    script += 'fi\n';
+  } else if (action === 'approve') {
+    script += 'if echo "$COMMAND" | grep -qE \'' + pattern.replace(/'/g, "'\\''") + '\'; then\n';
+    script += '    jq -n \'{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"' + message.replace(/"/g, '\\"') + '"}}\'\n';
+    script += 'fi\n';
+  }
+  script += 'exit 0';
+
+  const settings = {
+    hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: '~/.claude/hooks/custom-hook.sh' }] }] }
+  };
+
+  el.innerHTML = '<h3>Hook Script</h3>' +
+    '<div class="code-block"><button class="copy-btn" onclick="copyText(\'hb-script\')">Copy</button><pre id="hb-script">' + escHtml(script) + '</pre></div>' +
+    '<h3>settings.json entry</h3>' +
+    '<div class="code-block"><button class="copy-btn" onclick="copyText(\'hb-settings\')">Copy</button><pre id="hb-settings">' + escHtml(JSON.stringify(settings, null, 2)) + '</pre></div>' +
+    '<p style="color:#8b949e;font-size:.8rem;margin-top:.5rem">Save the script as <code>~/.claude/hooks/custom-hook.sh</code>, run <code>chmod +x</code>, and merge the settings entry.</p>';
+}
+
 // Auto-load from URL parameter: ?config=base64encodedJSON
 (function() {
   const params = new URLSearchParams(window.location.search);

package/examples/cost-tracker.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# ================================================================
+# cost-tracker.sh — Estimate session token cost
+# ================================================================
+# PURPOSE:
+#   Claude Code doesn't show token costs. This hook tracks
+#   tool calls and estimates cumulative cost, warning at thresholds.
+#
+# TRIGGER: PostToolUse
+# MATCHER: ""
+#
+# HOW IT WORKS:
+#   Counts tool calls as a proxy for token usage.
+#   Average tool call ≈ 2K tokens input + 1K output.
+#   Opus: $15/M input, $75/M output
+#   Sonnet: $3/M input, $15/M output
+#
+# CONFIGURATION:
+#   CC_COST_MODEL=opus   (default) or sonnet
+#   CC_COST_WARN=1.00    warn at $1 (default)
+#   CC_COST_BLOCK=5.00   warn at $5 (default, doesn't block)
+# ================================================================
+
+COUNTER_FILE="/tmp/cc-cost-tracker-calls"
+LAST_WARN="/tmp/cc-cost-tracker-warned"
+
+COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo 0)
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+
+MODEL="${CC_COST_MODEL:-opus}"
+WARN="${CC_COST_WARN:-1.00}"
+BLOCK="${CC_COST_BLOCK:-5.00}"
+
+# Estimate: ~2K input + ~1K output tokens per tool call
+if [ "$MODEL" = "opus" ]; then
+    # Opus: $15/M in, $75/M out → ~$0.105 per tool call
+    COST=$(echo "scale=2; $COUNT * 0.105" | bc 2>/dev/null || echo "0")
+else
+    # Sonnet: $3/M in, $15/M out → ~$0.021 per tool call
+    COST=$(echo "scale=2; $COUNT * 0.021" | bc 2>/dev/null || echo "0")
+fi
+
+# Graduated warnings (with cooldown)
+WARNED=$(cat "$LAST_WARN" 2>/dev/null || echo "0")
+
+if [ "$(echo "$COST >= $BLOCK" | bc 2>/dev/null)" = "1" ] && [ "$WARNED" != "block" ]; then
+    echo "COST: ~\$${COST} estimated ($COUNT tool calls, $MODEL)" >&2
+    echo "Consider finishing current task and compacting." >&2
+    echo "block" > "$LAST_WARN"
+elif [ "$(echo "$COST >= $WARN" | bc 2>/dev/null)" = "1" ] && [ "$WARNED" = "0" ]; then
+    echo "COST: ~\$${COST} estimated ($COUNT tool calls, $MODEL)" >&2
+    echo "warn" > "$LAST_WARN"
+fi
+
+exit 0

package/examples/read-before-edit.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# ================================================================
+# read-before-edit.sh — Warn when editing files not recently read
+# ================================================================
+# PURPOSE:
+#   Claude Code sometimes tries to Edit files it hasn't Read,
+#   leading to old_string mismatches. This hook tracks which
+#   files were recently Read and warns when Edit targets an
+#   unread file.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Edit"
+#
+# HOW IT WORKS:
+#   - PostToolUse Read hook records file paths to /tmp/cc-read-files
+#   - This PreToolUse Edit hook checks if the target was read
+#   - Warns (doesn't block) if file wasn't read recently
+#
+# NOTE: Requires companion PostToolUse hook to record Read events.
+#   Or just install this and accept the warning.
+# ================================================================
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+# Only check Edit tool
+if [[ "$TOOL" != "Edit" ]] || [[ -z "$FILE" ]]; then
+    exit 0
+fi
+
+READ_LOG="/tmp/cc-read-files"
+
+# Check if file was recently read
+if [ -f "$READ_LOG" ]; then
+    if grep -qF "$FILE" "$READ_LOG" 2>/dev/null; then
+        exit 0  # File was read, safe to edit
+    fi
+fi
+
+echo "NOTE: Editing $FILE without reading it first." >&2
+echo "Consider using Read before Edit to avoid old_string mismatches." >&2
+
+exit 0

package/index.mjs

@@ -356,6 +356,8 @@ function examples() {
       'commit-quality-gate.sh': 'Warn on vague or too-long commit messages',
       'diff-size-guard.sh': 'Warn/block on large diffs (10+ files warn, 50+ block)',
       'dependency-audit.sh': 'Warn on new package installs not in manifest',
+      'cost-tracker.sh': 'Estimate session token cost ($1 warn, $5 alert)',
+      'read-before-edit.sh': 'Warn when editing files not recently read',
     },
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-safe-setup",
-  "version": "3.7.0",
+  "version": "3.8.1",
   "description": "One command to make Claude Code safe for autonomous operation. 8 built-in + 36 examples. 21 commands: create, audit, lint, diff, share, benchmark, watch, learn. 2,500+ daily npm downloads.",
   "main": "index.mjs",
   "bin": {