cc-safe-setup 29.7.0 → 30.0.4

package/audit/find-dead-hooks.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+# find-dead-hooks.sh — list hook registrations whose script is not on disk.
+#
+# Why this exists: Claude Code treats a hook that fails to launch as a
+# non-blocking error and lets the tool call proceed. A registration pointing at
+# a path that does not exist therefore produces no symptom at all — the guard
+# is simply absent, and everything looks normal.
+#
+# It reads all three settings files, because a registration can rot in any of
+# them and each is merged into the others.
+#
+# Usage:  ./find-dead-hooks.sh            # run from your project directory
+#
+# Output: one line per registration whose script is missing. No output is good.
+set -u
+
+# The same file can appear twice — when HOME is the project directory, or when
+# one path is a symlink to the other. Reporting a registration twice makes it
+# look like two separate problems, so collapse the list by resolved path first.
+raw=(
+  "$HOME/.claude/settings.json"
+  "$PWD/.claude/settings.json"
+  "$PWD/.claude/settings.local.json"
+)
+files=()
+seen=""
+for f in "${raw[@]}"; do
+  [ -f "$f" ] || continue
+  real=$(readlink -f "$f" 2>/dev/null || printf '%s' "$f")
+  case ":$seen:" in *":$real:"*) continue ;; esac
+  seen="$seen:$real"
+  files+=("$f")
+done
+
+reader=""
+for r in jq python3 python node; do command -v "$r" >/dev/null 2>&1 && { reader="$r"; break; }; done
+if [ -z "$reader" ]; then
+  echo "find-dead-hooks: needs jq, python3 or node to read settings.json" >&2
+  exit 70
+fi
+
+extract() {   # print every command string registered under any hook event
+  case "$reader" in
+    jq) jq -r '.hooks // {} | .[]?[]?.hooks[]?.command // empty' "$1" 2>/dev/null ;;
+    *)  "$reader" - "$1" <<'PY' 2>/dev/null
+import json, sys
+try:
+    data = json.load(open(sys.argv[1], encoding="utf-8"))
+except Exception:
+    sys.exit(0)
+for groups in (data.get("hooks") or {}).values():
+    for group in groups or []:
+        for hook in (group or {}).get("hooks") or []:
+            cmd = hook.get("command")
+            if cmd:
+                print(cmd)
+PY
+    ;;
+  esac
+}
+
+found=0
+for f in "${files[@]}"; do
+  [ -f "$f" ] || continue
+  extract "$f" | grep -oE '(~|/|\$\{?[A-Za-z_]+\}?/)[^ ";|&)]*\.(sh|py|js|mjs)' | sort -u |
+  while read -r script; do
+    p="${script/#\~/$HOME}"
+    p="${p//\$\{CLAUDE_PROJECT_DIR\}/${CLAUDE_PROJECT_DIR:-$PWD}}"
+    p="${p//\$CLAUDE_PROJECT_DIR/${CLAUDE_PROJECT_DIR:-$PWD}}"
+    p="${p//\$\{HOME\}/$HOME}"
+    if [ ! -e "$p" ]; then
+      echo "MISSING  $p"
+      echo "         registered in $f"
+      found=1
+    fi
+  done
+done
+
+# The subshell above cannot set `found` in the parent, so report on emptiness instead.
+echo "---"
+echo "Nothing listed above means every registered hook script exists."
+echo "It does NOT mean any of them fires. Use fire.sh for that."

package/audit/find-unfirable-rules.sh

@@ -0,0 +1,142 @@
+#!/bin/bash
+# find-unfirable-rules.sh — list guard rules whose pattern cannot match anything.
+#
+# Why this exists: find-dead-hooks.sh covers the case where the script is not
+# there. This covers the case where the script is there, is registered, runs on
+# every call, and its rule still cannot return true. The operator-visible
+# symptom is identical to a guard that has simply never seen a dangerous
+# command: an `exit 2` rule, an `exit 0` outcome, and no diagnostic anywhere.
+#
+# Two mechanisms, both measured on shipped guards of mine:
+#
+#   1. The pattern is eaten as options. grep reads an argument that starts with
+#      a dash as flags, so
+#          grep -qE '--no-verify|SKIP_CI'
+#      dies with "unrecognized option" and matches nothing, for every input,
+#      forever. Two of my own guards carried this from 2026-03-29 to
+#      2026-09-20 with their tests passing the whole time. Fix: `--` before the
+#      pattern, or `-e`.
+#
+#   2. Lookaround in an engine that has none. ERE has no (?! (?= (?<, so
+#          grep -qE '(?!origin\b)'
+#      is either a warning and exit 1 (GNU grep) or a syntax error and exit 2
+#      (ugrep) — and both look the same to the `if` around it. Fix: grep -P
+#      where it is available, or restructure the rule.
+#
+# It looks at the scripts your settings actually register, and at inline
+# command strings, because a rule written directly into settings.json has the
+# same failure and no file to inspect.
+#
+# Usage:  ./find-unfirable-rules.sh          # run from your project directory
+#
+# Output: one block per suspect rule. No output is good.
+#
+# What it does NOT tell you: whether a rule that CAN match ever DOES. A pattern
+# can be well-formed and still name the wrong thing. Use fire.sh and
+# boundary.sh for that. This only rules out the rules that could never have
+# worked.
+set -u
+
+raw=(
+  "$HOME/.claude/settings.json"
+  "$PWD/.claude/settings.json"
+  "$PWD/.claude/settings.local.json"
+)
+files=()
+seen=""
+for f in "${raw[@]}"; do
+  [ -f "$f" ] || continue
+  real=$(readlink -f "$f" 2>/dev/null || printf '%s' "$f")
+  case ":$seen:" in *":$real:"*) continue ;; esac
+  seen="$seen:$real"
+  files+=("$f")
+done
+
+reader=""
+for r in jq python3 python node; do command -v "$r" >/dev/null 2>&1 && { reader="$r"; break; }; done
+if [ -z "$reader" ]; then
+  echo "find-unfirable-rules: needs jq, python3 or node to read settings.json" >&2
+  exit 70
+fi
+
+extract() {   # print every command string registered under any hook event
+  case "$reader" in
+    jq) jq -r '.hooks // {} | .[]?[]?.hooks[]?.command // empty' "$1" 2>/dev/null ;;
+    *)  "$reader" - "$1" <<'PY' 2>/dev/null
+import json, sys
+try:
+    data = json.load(open(sys.argv[1], encoding="utf-8"))
+except Exception:
+    sys.exit(0)
+for groups in (data.get("hooks") or {}).values():
+    for group in groups or []:
+        for hook in (group or {}).get("hooks") or []:
+            cmd = hook.get("command")
+            if cmd:
+                print(cmd)
+PY
+    ;;
+  esac
+}
+
+# A quoted grep pattern whose first character is a dash. The quote may be
+# backslash-escaped, because the same commands appear inline inside JSON.
+EATEN='grep[[:space:]]+(-[A-Za-z]+[[:space:]]+)*\\?['"'"'"]-'
+# ... unless -- or -e comes first, which is the correct spelling.
+SPELLED_OK='grep[[:space:]]+(-[A-Za-z]+[[:space:]]+)*(--|-e)[[:space:]]'
+# Lookaround, only a problem when the engine is ERE or BRE (no -P).
+LOOKAROUND='grep[[:space:]]+(-[A-Za-z]+[[:space:]]+)*\\?['"'"'"][^'"'"'"]*\(\?[!=<]'
+
+report() {  # report <where> <line-no-or-dash> <text> <why> <fix>
+  echo "UNFIRABLE  $1${2:+:$2}"
+  echo "           $3"
+  echo "           why: $4"
+  echo "           fix: $5"
+  echo
+}
+
+scan_text() {  # scan_text <where> <text-on-stdin>
+  local where="$1" n=0
+  while IFS= read -r line; do
+    n=$((n + 1))
+    case "$line" in \#*) continue ;; esac
+    if printf '%s' "$line" | grep -qE -- "$EATEN" \
+       && ! printf '%s' "$line" | grep -qE -- "$SPELLED_OK"; then
+      report "$where" "$n" "$(printf '%s' "$line" | cut -c1-140)" \
+        "the pattern starts with a dash, so grep reads it as options and matches nothing" \
+        "put -- before the pattern, or use -e"
+    fi
+    if printf '%s' "$line" | grep -qE -- "$LOOKAROUND" \
+       && ! printf '%s' "$line" | grep -qE -- 'grep[[:space:]]+(-[A-Za-z]*P[A-Za-z]*[[:space:]])'; then
+      report "$where" "$n" "$(printf '%s' "$line" | cut -c1-140)" \
+        "lookaround ((?! (?= (?<) does not exist in ERE/BRE; this pattern can never match" \
+        "use grep -P if available, or restructure the rule"
+    fi
+  done
+}
+
+# 1) the scripts the settings register
+for f in "${files[@]}"; do
+  extract "$f" | grep -oE '(~|/|\$\{?[A-Za-z_]+\}?/)[^ ";|&)]*\.sh' | sort -u |
+  while read -r script; do
+    p="${script/#\~/$HOME}"
+    p="${p//\$\{CLAUDE_PROJECT_DIR\}/${CLAUDE_PROJECT_DIR:-$PWD}}"
+    p="${p//\$CLAUDE_PROJECT_DIR/${CLAUDE_PROJECT_DIR:-$PWD}}"
+    p="${p//\$\{HOME\}/$HOME}"
+    [ -f "$p" ] || continue
+    scan_text "$p" < "$p"
+  done
+done
+
+# 2) inline command strings, which have no file to open
+for f in "${files[@]}"; do
+  extract "$f" | while IFS= read -r cmd; do
+    case "$cmd" in *grep*) ;; *) continue ;; esac
+    printf '%s\n' "$cmd" | scan_text "$f (inline)"
+  done
+done
+
+echo "---"
+echo "Nothing listed above means no rule was found that is structurally unable"
+echo "to match. It does NOT mean any rule fires on the thing you care about."
+echo "Use fire.sh for that, and boundary.sh for the neighbours it misses."

package/audit/fire.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+# fire.sh — fire one Claude Code hook by hand and print what it decided.
+#
+# Why this exists: installing a hook and having a hook are not the same thing.
+# The only evidence that a guard works is that it exits 2 when you hand it the
+# operation it is supposed to refuse. This script hands it that operation.
+#
+# Usage:
+#   ./fire.sh <hook-script> <tool-name> <json-field>=<value> [more=fields...]
+#
+# Examples:
+#   ./fire.sh ~/.claude/hooks/rm-safety-net.sh Bash command="rm -rf \$HOME/projects"
+#   ./fire.sh ~/.claude/hooks/env-write-guard.sh Write file_path=/home/me/app/.env
+#
+# Exit codes you will see printed:
+#   2  the hook refused the operation   <- what a working guard does
+#   0  the hook allowed the operation   <- if you expected a refusal, it is not working
+#   1  the hook itself errored          <- it is not protecting you either
+#
+# One flag matters for the audit:
+#   --bare   run with a PATH that has no jq, no python3 and no node.
+#            Many hooks parse the tool-call JSON with one of those. On a
+#            minimal container or a fresh CI image they are absent, and a hook
+#            that cannot parse its input often exits 0 (allow) instead of 2.
+#   A throwaway HOME is always used, so a hook that writes state into ~/.claude
+#   cannot touch yours while you are testing. There is no flag for that and no
+#   way to turn it off.
+#
+set -u
+
+BARE=0
+for a in "$@"; do [ "$a" = "--bare" ] && BARE=1; done
+ARGS=(); for a in "$@"; do [ "$a" = "--bare" ] || ARGS+=("$a"); done
+set -- "${ARGS[@]+"${ARGS[@]}"}"
+
+if [ $# -lt 2 ]; then
+  sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'
+  exit 64
+fi
+
+HOOK="$1"; TOOL="$2"; shift 2
+
+if [ ! -f "$HOOK" ]; then
+  echo "fire.sh: no such hook: $HOOK" >&2
+  exit 64
+fi
+
+# Build the tool-call JSON that Claude Code would send on stdin.
+# Values are passed through a JSON string escaper so quotes and backslashes survive.
+esc() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }
+fields=""
+for kv in "$@"; do
+  k="${kv%%=*}"; v="${kv#*=}"
+  [ -n "$fields" ] && fields="$fields,"
+  fields="$fields\"$(esc "$k")\":\"$(esc "$v")\""
+done
+PAYLOAD="{\"tool_name\":\"$(esc "$TOOL")\",\"tool_input\":{$fields}}"
+
+SANDBOX_HOME=$(mktemp -d)
+cleanup() {
+  [ -n "${FAKEBIN:-}" ] && [ -d "$FAKEBIN" ] && { find "$FAKEBIN" -maxdepth 1 -type l -delete 2>/dev/null; rmdir "$FAKEBIN" 2>/dev/null; }
+  rmdir "$SANDBOX_HOME" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+FAKEBIN=""
+if [ "$BARE" = "1" ]; then
+  # A PATH with the shell tools a hook needs to run at all, but without any
+  # JSON parser. This is what a slim container looks like.
+  FAKEBIN=$(mktemp -d)
+  for c in bash sh env printf echo grep sed awk tr cat cut head tail sort uniq wc dirname basename mktemp rmdir find ln test true false date id whoami; do
+    p=$(command -v "$c" 2>/dev/null) && ln -sf "$p" "$FAKEBIN/$c" 2>/dev/null
+  done
+  for j in jq python3 python node; do
+    if PATH="$FAKEBIN" command -v "$j" >/dev/null 2>&1; then
+      echo "fire.sh: --bare failed: $j is still reachable" >&2; exit 70
+    fi
+  done
+fi
+
+OUT=$(mktemp); trap 'rm -f "$OUT" 2>/dev/null; cleanup' EXIT
+if [ "$BARE" = "1" ]; then
+  printf '%s' "$PAYLOAD" | HOME="$SANDBOX_HOME" PATH="$FAKEBIN" bash "$HOOK" >"$OUT" 2>&1
+else
+  printf '%s' "$PAYLOAD" | HOME="$SANDBOX_HOME" bash "$HOOK" >"$OUT" 2>&1
+fi
+CODE=$?
+
+echo "hook   : $HOOK"
+echo "input  : $PAYLOAD"
+[ "$BARE" = "1" ] && echo "mode   : --bare (no jq, no python3, no node)"
+echo "exit   : $CODE  $( [ "$CODE" = 2 ] && echo '(refused)' || { [ "$CODE" = 0 ] && echo '(allowed)' || echo '(hook error)'; } )"
+if [ -s "$OUT" ]; then
+  echo "message:"
+  sed 's/^/  /' "$OUT" | head -20
+fi
+exit "$CODE"

package/audit/selftest.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# selftest.sh - prove that find-dead-hooks.sh really detects a registration
+# whose script is missing.
+#
+# A detector that finds nothing proves nothing until you have seen it find
+# something. This builds a deliberately broken settings file in a throwaway
+# directory, with one registration pointing at a script that does not exist and
+# one pointing at a script that does, and checks both directions.
+set -u
+HERE=$(cd "$(dirname "$0")" && pwd)
+T=$(mktemp -d)
+mkdir -p "$T/.claude/hooks"
+printf '#!/bin/bash\nexit 0\n' > "$T/.claude/hooks/real.sh"
+chmod +x "$T/.claude/hooks/real.sh"
+
+cat > "$T/.claude/settings.json" <<'JSON'
+{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[
+  {"type":"command","command":"${CLAUDE_PROJECT_DIR}/.claude/hooks/ghost.sh"},
+  {"type":"command","command":"${CLAUDE_PROJECT_DIR}/.claude/hooks/real.sh"}
+]}]}}
+JSON
+
+echo "=== control: one registration points at a missing script, one at a real one ==="
+out=$(cd "$T" && CLAUDE_PROJECT_DIR="$T" HOME="$T" bash "$HERE/find-dead-hooks.sh" 2>&1)
+printf '%s\n' "$out"
+echo
+
+if printf '%s' "$out" | grep -q "ghost.sh"; then
+  echo "result: PASS - the missing registration was reported"
+else
+  echo "result: FAIL - the missing registration was NOT reported"
+fi
+if printf '%s' "$out" | grep -q "real.sh"; then
+  echo "result: FAIL - the real registration was reported too"
+else
+  echo "result: PASS - the real registration was not reported"
+fi
+
+# clean up: remove only what we created, one path at a time
+for f in "$T/.claude/settings.json" "$T/.claude/hooks/real.sh"; do [ -f "$f" ] && unlink "$f"; done
+rmdir "$T/.claude/hooks" "$T/.claude" "$T" 2>/dev/null
+echo "(cleaned up the throwaway directory)"

package/audit/unfirable-selftest.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# unfirable-selftest.sh - prove that find-unfirable-rules.sh really detects a
+# rule that cannot match, and does not report rules that can.
+#
+# A detector that finds nothing proves nothing until you have seen it find
+# something. This builds a throwaway setup with four rules: two that cannot
+# match (one of each mechanism), and two correct spellings of the same
+# patterns. Both directions are checked, because a detector that flags
+# everything is as useless as one that flags nothing.
+set -u
+HERE=$(cd "$(dirname "$0")" && pwd)
+T=$(mktemp -d)
+mkdir -p "$T/.claude/hooks"
+
+cat > "$T/.claude/hooks/broken.sh" <<'SH'
+#!/bin/bash
+# eaten as options: the pattern starts with a dash
+if grep -qE '--no-verify|SKIP_CI' "$1"; then echo "skip detected" >&2; fi
+# lookaround in an engine that has none
+if grep -qE '(?!origin\b)' "$1"; then echo "non-origin remote" >&2; fi
+SH
+
+cat > "$T/.claude/hooks/correct.sh" <<'SH'
+#!/bin/bash
+# the same two rules, spelled so they can actually match
+if grep -qE -- '--no-verify|SKIP_CI' "$1"; then echo "skip detected" >&2; fi
+if grep -qP '(?!origin\b)' "$1"; then echo "non-origin remote" >&2; fi
+SH
+chmod +x "$T/.claude/hooks/broken.sh" "$T/.claude/hooks/correct.sh"
+
+cat > "$T/.claude/settings.json" <<'JSON'
+{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[
+  {"type":"command","command":"${CLAUDE_PROJECT_DIR}/.claude/hooks/broken.sh"},
+  {"type":"command","command":"${CLAUDE_PROJECT_DIR}/.claude/hooks/correct.sh"},
+  {"type":"command","command":"if echo \"$X\" | grep -qE \"--force-with-lease\"; then exit 2; fi"},
+  {"type":"command","command":"if echo \"$X\" | grep -qE -- \"--force-with-lease\"; then exit 2; fi"}
+]}]}}
+JSON
+
+echo "=== control: two rules that cannot match, two that can, plus the same pair inline ==="
+out=$(cd "$T" && CLAUDE_PROJECT_DIR="$T" HOME="$T" bash "$HERE/find-unfirable-rules.sh" 2>&1)
+printf '%s\n' "$out"
+echo
+
+fails=0
+expect_present() {
+  if printf '%s' "$out" | grep -q -- "$1"; then
+    echo "result: PASS - $2"
+  else
+    echo "result: FAIL - $2"; fails=$((fails + 1))
+  fi
+}
+expect_absent() {
+  if printf '%s' "$out" | grep -q -- "$1"; then
+    echo "result: FAIL - $2"; fails=$((fails + 1))
+  else
+    echo "result: PASS - $2"
+  fi
+}
+
+expect_present "broken.sh"        "the script with two unfirable rules was reported"
+expect_present "reads it as options" "the option-eating mechanism was named"
+expect_present "lookaround"       "the lookaround mechanism was named"
+expect_present "(inline)"         "the inline rule written into settings.json was reported"
+expect_absent  "correct.sh"       "the correctly spelled script was not reported"
+
+# The correct inline spelling uses -- ; it must not appear as a finding. The
+# broken one does, so count the inline blocks rather than the substring.
+inline_hits=$(printf '%s' "$out" | grep -c -- "(inline)" || true)
+if [ "$inline_hits" -eq 1 ]; then
+  echo "result: PASS - exactly one of the two inline rules was reported"
+else
+  echo "result: FAIL - expected 1 inline finding, got $inline_hits"; fails=$((fails + 1))
+fi
+
+for f in "$T/.claude/settings.json" "$T/.claude/hooks/broken.sh" "$T/.claude/hooks/correct.sh"; do
+  [ -f "$f" ] && unlink "$f"
+done
+rmdir "$T/.claude/hooks" "$T/.claude" "$T" 2>/dev/null
+echo "(cleaned up the throwaway directory)"
+[ "$fails" -eq 0 ]

package/audit-web/index.html

@@ -155,7 +155,7 @@ exit 0</pre>
 
 <h3>Quick Commands</h3>
 <table>
-<tr><td><code>npx cc-safe-setup</code></td><td>Install 8 hooks</td></tr>
+<tr><td><code>npx github:yurukusa/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>Score 0-100</td></tr>
 <tr><td><code>--dashboard</code></td><td>Live status</td></tr>
@@ -194,16 +194,16 @@ function analyze(s) {
   const risks=[], good=[];
   const pre=s.hooks?.PreToolUse||[], post=s.hooks?.PostToolUse||[];
   const all=JSON.stringify(pre).toLowerCase();
-  if(!pre.length) risks.push({s:'CRITICAL',i:'No PreToolUse hooks',f:'npx cc-safe-setup'});
+  if(!pre.length) risks.push({s:'CRITICAL',i:'No PreToolUse hooks',f:'npx github:yurukusa/cc-safe-setup'});
   else { good.push('PreToolUse ('+pre.length+')');
-    if(!all.match(/destructive|guard|rm.*rf/)) risks.push({s:'HIGH',i:'No destructive guard',f:'npx cc-safe-setup'});
+    if(!all.match(/destructive|guard|rm.*rf/)) risks.push({s:'HIGH',i:'No destructive guard',f:'npx github:yurukusa/cc-safe-setup'});
     else good.push('Destructive protection');
-    if(!all.match(/branch|push|main/)) risks.push({s:'HIGH',i:'No branch guard',f:'npx cc-safe-setup'});
+    if(!all.match(/branch|push|main/)) risks.push({s:'HIGH',i:'No branch guard',f:'npx github:yurukusa/cc-safe-setup'});
     else good.push('Branch protection');
-    if(!all.match(/secret|env|credential/)) risks.push({s:'HIGH',i:'No secret guard',f:'npx cc-safe-setup'});
+    if(!all.match(/secret|env|credential/)) risks.push({s:'HIGH',i:'No secret guard',f:'npx github:yurukusa/cc-safe-setup'});
     else good.push('Secret protection');
   }
-  if(!post.length) risks.push({s:'MEDIUM',i:'No PostToolUse hooks',f:'npx cc-safe-setup'});
+  if(!post.length) risks.push({s:'MEDIUM',i:'No PostToolUse hooks',f:'npx github:yurukusa/cc-safe-setup'});
   else good.push('PostToolUse ('+post.length+')');
   const score=Math.max(0,100-risks.reduce((n,r)=>n+(r.s==='CRITICAL'?30:r.s==='HIGH'?20:10),0));
   return {risks,good,score};
@@ -239,10 +239,10 @@ const RECIPES=[
   {cat:'block',t:'Block .env staging',d:'Secret leak prevention (#6527)',code:'CMD=$(cat|jq -r \'.tool_input.command // empty\')\n[ -z "$CMD" ] && exit 0\necho "$CMD"|grep -qiE \'git\\s+add.*\\.env\' && echo "BLOCKED" >&2 && exit 2\nexit 0',trigger:'PreToolUse'},
   {cat:'block',t:'Block database wipe',d:'migrate:fresh, DROP DATABASE (#37405)',code:'CMD=$(cat|jq -r \'.tool_input.command // empty\')\n[ -z "$CMD" ] && exit 0\necho "$CMD"|grep -qiE \'migrate:fresh|DROP\\s+DATABASE|prisma\\s+migrate\\s+reset\' && echo "BLOCKED" >&2 && exit 2\nexit 0',trigger:'PreToolUse'},
   {cat:'approve',t:'Auto-approve git read',d:'git status/log/diff with -C flag (#36900)',code:'CMD=$(cat|jq -r \'.tool_input.command // empty\')\n[ -z "$CMD" ] && exit 0\necho "$CMD"|grep -qE \'^\\s*git\\s+(-C\\s+\\S+\\s+)?(status|log|diff|branch|show)\' && jq -n \'{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\'\nexit 0',trigger:'PreToolUse'},
-  {cat:'approve',t:'Compound commands',d:'cd && git log auto-approve (#30519)',code:'# Full: npx cc-safe-setup --install-example compound-command-approver',trigger:'PreToolUse'},
+  {cat:'approve',t:'Compound commands',d:'cd && git log auto-approve (#30519)',code:'# Full: npx github:yurukusa/cc-safe-setup --install-example compound-command-approver',trigger:'PreToolUse'},
   {cat:'detect',t:'Loop detector',d:'Break command repetition (5+ times)',code:'CMD=$(cat|jq -r \'.tool_input.command // empty\')\n[ -z "$CMD" ] && exit 0\nSTATE=/tmp/cc-loop\necho "$CMD">>$STATE\ntail -n 10 $STATE>${STATE}.tmp&&mv ${STATE}.tmp $STATE\nCOUNT=$(grep -cF "$CMD" $STATE||echo 0)\n[ "$COUNT" -ge 5 ]&&echo "BLOCKED: repeated $COUNT times" >&2&&exit 2\nexit 0',trigger:'PreToolUse'},
-  {cat:'utility',t:'Session handoff',d:'Save state for next session',code:'# npx cc-safe-setup --install-example session-handoff',trigger:'Stop'},
-  {cat:'utility',t:'Cost tracker',d:'Estimate session token cost',code:'# npx cc-safe-setup --install-example cost-tracker',trigger:'PostToolUse'},
+  {cat:'utility',t:'Session handoff',d:'Save state for next session',code:'# npx github:yurukusa/cc-safe-setup --install-example session-handoff',trigger:'Stop'},
+  {cat:'utility',t:'Cost tracker',d:'Estimate session token cost',code:'# npx github:yurukusa/cc-safe-setup --install-example cost-tracker',trigger:'PostToolUse'},
   {cat:'utility',t:'tmp cleanup',d:'/tmp/claude-*-cwd files (#8856)',code:'find /tmp -maxdepth 1 -name \'claude-*-cwd\' -type f -mmin +60 -delete 2>/dev/null\nexit 0',trigger:'Stop'},
 ];
 

package/examples/README.md

@@ -1,28 +1,65 @@
 # Example Hooks
 
-675 installable hooks. Each solves a real problem from GitHub Issues or autonomous operation. 9,200+ tests.
+As of 2026-08-31 this directory held 914 installable hooks; it holds 916 today
+(2026-09-20). Each solves a real problem from GitHub Issues or autonomous operation.
+Covered by the 296 test files in [`tests/`](../tests) — 295 shell, one Python
+(counted 2026-09-20).
+The category table below is the 2026-08-31 count and has not been recut since.
 
 ```bash
-npx cc-safe-setup --install-example <name>   # install one
-npx cc-safe-setup --examples                  # list all
-npx cc-safe-setup --examples safety           # filter by category
-npx cc-safe-setup --shield                    # install recommended set
+npx github:yurukusa/cc-safe-setup --install-example <name>   # install one
+npx github:yurukusa/cc-safe-setup --examples                  # list all
+npx github:yurukusa/cc-safe-setup --examples safety           # filter by category
+npx github:yurukusa/cc-safe-setup --shield                    # install recommended set
 ```
 
 ## Categories
 
-| Category | Count | Examples |
-|----------|-------|---------|
-| Destructive Command Prevention | 14 | `destructive-guard`, `branch-guard`, `no-sudo-guard`, `symlink-guard`, `shell-wrapper-guard`, `compound-inject-guard` |
-| Data Protection | 5 | `block-database-wipe`, `secret-guard`, `hardcoded-secret-detector` |
-| Git Safety | 11 | `git-config-guard`, `no-verify-blocker`, `push-requires-test-pass` |
-| Auto-Approve (PreToolUse) | 11 | `auto-approve-readonly`, `auto-approve-build`, `auto-approve-docker` |
-| Auto-Approve (PermissionRequest) | 7 | `allow-git-hooks-dir`, `allow-protected-dirs`, `edit-always-allow` |
-| Code Quality | 10 | `syntax-check`, `diff-size-guard`, `test-deletion-guard` |
-| Security | 10 | `credential-file-cat-guard`, `credential-exfil-guard`, `prompt-injection-guard` |
-| Deploy | 4 | `deploy-guard`, `no-deploy-friday`, `work-hours-guard` |
-| Monitoring & Cost | 14 | `context-monitor`, `cost-tracker`, `loop-detector`, `edit-error-counter`, `dotenv-watch` |
-| Utility | 20 | `comment-strip`, `session-handoff`, `auto-checkpoint`, `edit-retry-loop-guard`, `direnv-auto-reload`, `pre-compact-checkpoint` |
+| Category | Hooks | Of which can refuse a call |
+|----------|------:|---------------------------:|
+| Safety Guards | 318 | 132 |
+| Auto-Approve | 35 | 18 |
+| Quality | 174 | 12 |
+| Agent Controls | 15 | 9 |
+| Monitoring | 28 | 2 |
+| Recovery | 32 | 2 |
+| UX | 51 | 13 |
+| Other | 2 | 0 |
+| (uncategorised) | 259 | 112 |
+| **total** | **914** | **300** |
+
+"Can refuse" means the script contains `exit 2`, a permission decision,
+`"decision": "block"` or `"deny"` **outside a comment**. The other 614 warn, count or log —
+useful, but they cannot stop a tool call, whatever the filename suggests. (Of those 614, 609
+have no refusal at all; 5 end with a computed exit code such as `exit "$RC"` and have to be
+opened to tell.)
+
+**The word "outside a comment" is doing real work here.** A plain `grep` over the file counts
+matches inside comments, and 19 scripts here match only there — including three whose comment
+says, in so many words, that they are not blockers:
+
+```
+network-guard.sh:5         # This is a warning hook (exit 0), not a blocker (exit 2),
+plan-mode-edit-guard.sh:74 # Warning only (exit 0). Change to exit 2 to block.
+no-push-without-tests.sh:41 # Warning only. Change exit 0 to exit 2 to enforce.
+```
+
+So strip comments before you trust the match. To check the hooks you already rely on:
+
+```bash
+for f in "$HOME"/.claude/hooks/*.sh; do
+  sed 's/#.*//' "$f" | grep -qE 'exit 2|permissionDecision|"decision": *"block"|"deny"' \
+    || echo "WITNESS $f"
+done
+```
+
+This is still a floor, not a census. `broad-prefix-session-trap-warner.sh` carries
+`permissionDecision: deny` inside a *message string* and its only exit is `exit 0`. The `sed`
+above does drop that line — but only because an issue number, `(#62437)`, appears earlier on the
+same line and takes the rest of it with it. Right answer, wrong reason: write the same warning
+without an issue number and the file counts as a refuser. Telling code from string needs a shell
+parser, which one line of `sed` is not. Adjust the extension too — a hooks directory can hold
+`.py` and `.js`.
 
 ## Popular Hooks