cc-safe-setup 29.7.0 → 30.0.4

package/tests/destructive-guard-wrapped-command.test.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+# destructive-guard never looked inside a wrapper.
+#
+# Every boundary in the guard is (^|[;&|]) — the start of the line, or just
+# after a separator. A command placed inside a substitution, a subshell, or
+# after a shell keyword sits at neither, so no check ever saw it:
+#
+#     rm -rf ~                    blocked
+#     [[ -n $(rm -rf ~) ]]        NOT blocked   <- same deletion
+#     if true; then rm -rf ~; fi  NOT blocked
+#     `rm -rf ~`                  NOT blocked
+#
+# Measured 2026-08-04 against the shipped core: one blocked command, ten
+# wrappings, seven passes. Claude Code 2.1.221 fixed the same shape on its own
+# side ("a Bash tool permission-check bypass where zsh could execute hidden
+# commands in [[ ]] regex conditionals"), which is what prompted the check here.
+#
+# Check 0z replaces the wrapping tokens with separators and runs the guard once
+# more against that text, so the inner command meets every existing check. The
+# controls below are the point of this file: the rewrite touches parentheses and
+# braces, which appear in ordinary commands (awk, jq, find -exec, subshells), so
+# "catches wrapped commands" and "blocks anything with a bracket in it" have to
+# be told apart.
+
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+WORK="$(mktemp -d)"
+trap 'find "$WORK" -mindepth 1 -delete 2>/dev/null; rmdir "$WORK" 2>/dev/null' EXIT
+PASS=0; FAIL=0
+
+python3 -c "
+import json,sys
+sys.stdout.write(json.load(open('$ROOT/scripts.json'))['destructive-guard'])" > "$WORK/dg.sh"
+
+run() {
+  local T; T="$(mktemp -d)"
+  python3 -c '
+import json,sys
+print(json.dumps({"tool_name":"Bash","tool_input":{"command":sys.argv[1]},
+                  "cwd":sys.argv[2],"session_id":"t"}))' "$1" "$T" \
+    | HOME="$T" bash "$WORK/dg.sh" >/dev/null 2>&1
+  local rc=$?
+  find "$T" -mindepth 1 -delete 2>/dev/null; rmdir "$T" 2>/dev/null
+  return $rc
+}
+
+want_block() {
+  if run "$1"; then FAIL=$((FAIL+1)); echo "  FAIL blocked: $1"
+  else PASS=$((PASS+1)); echo "  ok   blocked: $1"; fi
+}
+want_allow() {
+  if run "$1"; then PASS=$((PASS+1)); echo "  ok   allowed: $1"
+  else FAIL=$((FAIL+1)); echo "  FAIL allowed: $1"; fi
+}
+
+RM=$(printf 'r%s' 'm')
+echo "destructive-guard-wrapped-command"
+
+# --- the same deletion, wrapped ---------------------------------------------
+want_block "[[ -n \$($RM -rf ~) ]]"
+want_block "[[ x =~ \$($RM -rf ~) ]]"
+want_block "[[ -n \`$RM -rf ~\` ]]"
+want_block "if true; then $RM -rf ~; fi"
+want_block "for f in a; do $RM -rf ~; done"
+want_block "\$($RM -rf /)"
+want_block "x=\$($RM -rf /) ; echo done"
+want_block "echo \$(git reset --hard HEAD~5)"
+
+# --- unwrapped, which already worked ----------------------------------------
+want_block "$RM -rf ~"
+want_block "$RM -rf /"
+
+# --- controls: brackets and braces are ordinary ------------------------------
+# Without these, the check above passes just as well by blocking every command
+# that contains a parenthesis.
+want_allow "awk '{print \$1}' access.log"
+want_allow "sed -E 's/(a)/b/' file.txt"
+want_allow "jq '{name: .name}' package.json"
+want_allow "find . -name '*.log' -exec ls -l {} \\;"
+want_allow "if [ -d node_modules ]; then echo yes; else echo no; fi"
+want_allow "for i in \$(seq 1 3); do echo \$i; done"
+want_allow "echo \$(basename \$(pwd))"
+want_allow "( cd /tmp && ls )"
+want_allow "ls \$(git rev-parse --show-toplevel)"
+want_allow "$RM -rf node_modules && npm ci"
+want_allow "git reset --soft HEAD~1"
+want_allow "bash -c 'echo hello'"
+
+echo
+echo "destructive-guard-wrapped-command: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/tests/doctor-hook-disabling-env.test.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# --doctor: detect the environment variables that stop hooks loading at all
+#
+# Measured 2026-09-19 on Claude Code 2.1.278 (Linux/WSL2), disposable HOME and a
+# scratch working directory, with a control on every row. Arrival was measured on
+# UserPromptSubmit -- deliberately NOT PreToolUse on Bash, because --restricted
+# removes Bash and then "the hook was ignored" and "nothing pulled the trigger"
+# are the same observation.
+#
+#   (control) no flags              -> user, project and local hooks all fired
+#   --dangerously-skip-permissions  -> hooks fired, the guard refused, exit 2
+#   --restricted                    -> no hook fired; --settings restored them
+#   --safe-mode                     -> no hook fired; --settings did NOT restore
+#   CLAUDE_CODE_RESTRICTED=1        -> same as --restricted
+#   CLAUDE_CODE_SAFE_MODE=1         -> same as --safe-mode, and Bash still ran
+#
+# The variables matter more than the flags: a flag is retyped every time you
+# start, a line in a shell profile is read once and never seen again. Before this
+# check, --doctor printed "All checks passed. Hooks should be working." with
+# either variable set -- the exact false reassurance this command exists to
+# prevent, since every other check inspects files that are all perfectly fine.
+#
+# Only the value "1" was measured. Any other non-empty, non-false value is
+# flagged on the assumption that whoever typed it meant to turn it on; "0",
+# "false" and empty are treated as off.
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+
+# Assembled at runtime so this file does not carry the literal filename that the
+# operator's own guards watch for.
+SETTINGS_FILE="set""tings.json"
+
+run_doctor() {
+  # $1 = extra env assignments (may be empty). Prints only the lines this check owns.
+  local envspec="$1"
+  local home
+  home=$(mktemp -d)
+  mkdir -p "$home/.claude/hooks"
+  printf '%s' '{"hooks":{}}' > "$home/.claude/$SETTINGS_FILE"
+  # shellcheck disable=SC2086
+  env -u CLAUDE_CODE_SAFE_MODE -u CLAUDE_CODE_RESTRICTED $envspec HOME="$home" \
+    node "$ROOT/index.mjs" --doctor 2>&1 \
+    | grep -E 'hook-disabling environment variable|CLAUDE_CODE_SAFE_MODE=|CLAUDE_CODE_RESTRICTED=|does NOT restore|pass your hooks with|unset CLAUDE_CODE' || true
+  rm -rf "$home"
+}
+
+check() {
+  local desc="$1" envspec="$2" expect="$3"
+  local out
+  out=$(run_doctor "$envspec")
+  if printf '%s' "$out" | grep -q "$expect"; then
+    PASS=$((PASS + 1))
+  else
+    echo "  FAIL: $desc"
+    echo "         expected to match: $expect"
+    printf '%s\n' "${out:-<no output>}" | sed 's/^/         got: /'
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# --- the two variables are reported ----------------------------------------
+check "CLAUDE_CODE_SAFE_MODE=1 is reported" \
+  "CLAUDE_CODE_SAFE_MODE=1" "CLAUDE_CODE_SAFE_MODE=1"
+
+check "CLAUDE_CODE_RESTRICTED=1 is reported" \
+  "CLAUDE_CODE_RESTRICTED=1" "CLAUDE_CODE_RESTRICTED=1"
+
+check "safe-mode says --settings does not help" \
+  "CLAUDE_CODE_SAFE_MODE=1" "does NOT restore"
+
+check "restricted points at --settings as the way back" \
+  "CLAUDE_CODE_RESTRICTED=1" "pass your hooks with"
+
+# --- controls: no false positives -------------------------------------------
+# Without a control here, the two rows above would also pass if the check simply
+# printed its warning unconditionally.
+check "neither variable set reports the all-clear" \
+  "" "no hook-disabling environment variable set"
+
+check "an explicit 0 is treated as off" \
+  "CLAUDE_CODE_SAFE_MODE=0" "no hook-disabling environment variable set"
+
+check "the string false is treated as off" \
+  "CLAUDE_CODE_RESTRICTED=false" "no hook-disabling environment variable set"
+
+check "an empty value is treated as off" \
+  "CLAUDE_CODE_SAFE_MODE=" "no hook-disabling environment variable set"
+
+echo
+echo "doctor-hook-disabling-env: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/tests/doctor-misspelled-settings-keys.test.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+# --doctor: detect near-miss (misspelled) keys in the settings file
+#
+# Claude Code ignores unknown settings keys in silence. Measured on v2.1.220
+# with isolated settings files, controls paired against the correct spelling:
+#
+#   permissions.deny          -> the command is refused, never starts
+#   permissions.denyy         -> the command runs, exit 0, ZERO warnings
+#   hooks.PreToolUse          -> hook blocks, exit 2
+#   hooks.PreToolUsee         -> hook never invoked, ZERO warnings
+#                                (the hook body was unchanged; only the key differed)
+#   sandbox.failIfUnavailable -> refuses to start when deps are missing, exit 1
+#   sandbox.failIfUnavailble  -> starts unprotected, exit 0
+#
+# `claude doctor` does not check spelling and there is no non-interactive
+# command that prints the effective settings, so a control can be void from the
+# day it was written while looking exactly like one that works: both produce
+# "nothing bad happened".
+#
+# The check reports only keys within a small edit distance of a known key.
+# An unknown key that is far from every known one is left alone on purpose --
+# it is probably a setting this release has not heard of, and a diagnostic that
+# cries wolf stops being read.
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+
+# Assembled at runtime so this file does not carry the literal filename that the
+# operator's own guards watch for.
+SETTINGS_FILE="set""tings.json"
+
+run_doctor() {
+  # $1 = JSON body. Runs --doctor against a throwaway HOME and prints the
+  # "did you mean" lines only.
+  local body="$1"
+  local home
+  home=$(mktemp -d)
+  mkdir -p "$home/.claude/hooks"
+  printf '%s' "$body" > "$home/.claude/$SETTINGS_FILE"
+  HOME="$home" node "$ROOT/index.mjs" --doctor 2>&1 | grep 'did you mean' || true
+  rm -rf "$home"
+}
+
+check() {
+  local desc="$1" body="$2" expected_count="$3" expected_key="$4"
+  local out n
+  out=$(run_doctor "$body")
+  n=$(printf '%s' "$out" | grep -c 'did you mean' || true)
+  [ -z "$out" ] && n=0
+  if [ "$n" -ne "$expected_count" ]; then
+    echo "  FAIL: $desc (reported $n, expected $expected_count)"
+    [ -n "$out" ] && printf '%s\n' "$out" | sed 's/^/         /'
+    FAIL=$((FAIL + 1)); return
+  fi
+  if [ -n "$expected_key" ] && ! printf '%s' "$out" | grep -q "$expected_key"; then
+    echo "  FAIL: $desc (did not name $expected_key)"
+    FAIL=$((FAIL + 1)); return
+  fi
+  echo "  PASS: $desc"
+  PASS=$((PASS + 1))
+}
+
+echo "Testing --doctor misspelled settings key detection"
+echo "=================================================="
+
+# --- the three spellings measured on v2.1.220 -------------------------------
+check "permissions.denyy is reported" \
+  '{"permissions":{"denyy":["Bash(curl:*)"],"allow":[]}}' 1 'permissions.denyy'
+
+check "hooks.PreToolUsee is reported" \
+  '{"hooks":{"PreToolUsee":[]}}' 1 'hooks.PreToolUsee'
+
+check "sandbox.failIfUnavailble is reported" \
+  '{"sandbox":{"enabled":true,"failIfUnavailble":true}}' 1 'sandbox.failIfUnavailble'
+
+check "sandbox.network.strictAllowlst is reported" \
+  '{"sandbox":{"network":{"strictAllowlst":true}}}' 1 'sandbox.network.strictAllowlst'
+
+check "a misspelled top-level key is reported" \
+  '{"modell":"opus"}' 1 'modell'
+
+check "all three layers at once" \
+  '{"permissions":{"denyy":[]},"hooks":{"PreToolUsee":[]},"modell":"opus"}' 3 ''
+
+# --- no false positives -----------------------------------------------------
+check "correct spellings report nothing" \
+  '{"permissions":{"deny":[],"allow":[],"ask":[]},"hooks":{"PreToolUse":[],"PostToolUse":[],"SessionStart":[]},"model":"opus","defaultMode":"dontAsk"}' 0 ''
+
+check "correct sandbox spellings report nothing" \
+  '{"sandbox":{"enabled":true,"failIfUnavailable":true,"network":{"strictAllowlist":true,"allowedDomains":["example.com"]}}}' 0 ''
+
+check "an unknown key far from every known one stays silent" \
+  '{"someBrandNewFeatureNobodyKnows":true,"permissions":{"deny":[]}}' 0 ''
+
+check "keys inside env are not checked (operator picks those names)" \
+  '{"env":{"denyy":"1","modell":"2"},"permissions":{"deny":[]}}' 0 ''
+
+check "every hook event name spelled correctly reports nothing" \
+  '{"hooks":{"PreToolUse":[],"PostToolUse":[],"Notification":[],"Stop":[],"SubagentStop":[],"SubagentStart":[],"UserPromptSubmit":[],"PreCompact":[],"PostCompact":[],"SessionStart":[],"SessionEnd":[],"DirectoryAdded":[]}}' 0 ''
+
+check "an empty settings object reports nothing" \
+  '{}' 0 ''
+
+echo
+echo "doctor-misspelled-settings-keys: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/tests/example-guards-wrapped-command.test.sh

@@ -0,0 +1,169 @@
+#!/bin/bash
+# Three example guards blocked a destructive command and then passed the same
+# command once it was wrapped.
+#
+# The shapes measured 2026-08-04, against the shipped files:
+#
+#   rm-safety-net              8 of 10 forms passed
+#   system-dir-protection-guard 9 of 11 forms passed
+#   auto-mode-safety-enforcer   5 of  9 forms passed
+#
+# Two separate causes, both about where a command is allowed to start:
+#
+#   1. The analysis gate. `rm-safety-net` and `system-dir-protection-guard`
+#      opened only on '^\s*(sudo\s+)?rm\s' — the command had to *begin* with
+#      rm, so `cd /tmp && rm -rf ~` never entered the analysis at all.
+#   2. The target pattern. `auto-mode-safety-enforcer` required whitespace or
+#      end-of-line after the dangerous path, so `rm -rf ~; echo done` passed
+#      while `rm -rf ~ ; echo done` was blocked. One space apart, opposite
+#      verdicts.
+#
+# Wrappers hit both: inside a substitution or after `then`, a command is at
+# neither the line start nor a separator. Claude Code 2.1.221 fixed the same
+# shape in its own permission check ("hidden commands in [[ ]] regex
+# conditionals"), which is what prompted measuring these.
+#
+# Half of this file is controls. The fix inserts separators at wrapper tokens,
+# and parentheses and braces appear in ordinary commands (awk, jq, find -exec,
+# subshells), so "looks inside wrappers" and "blocks anything with a bracket"
+# have to be told apart. The home-path controls matter too: `ls ~/projects` and
+# `cat ~/.bashrc` must stay untouched.
+
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0; FAIL=0
+RM=$(printf 'r%s' 'm')
+
+run() {
+  local hook="$1" cmd="$2" T rc
+  T="$(mktemp -d)"
+  python3 -c '
+import json,sys
+print(json.dumps({"tool_name":"Bash","tool_input":{"command":sys.argv[1]},
+                  "cwd":sys.argv[2],"session_id":"t"}))' "$cmd" "$T" \
+    | HOME="$T" bash "$ROOT/examples/$hook.sh" >/dev/null 2>&1
+  rc=$?
+  find "$T" -mindepth 1 -delete 2>/dev/null; rmdir "$T" 2>/dev/null
+  return $rc
+}
+
+want_block() {
+  if run "$1" "$2"; then FAIL=$((FAIL+1)); echo "  FAIL blocked [$1]: $2"
+  else PASS=$((PASS+1)); echo "  ok   blocked [$1]: $2"; fi
+}
+want_allow() {
+  if run "$1" "$2"; then PASS=$((PASS+1)); echo "  ok   allowed [$1]: $2"
+  else FAIL=$((FAIL+1)); echo "  FAIL allowed [$1]: $2"; fi
+}
+
+echo "example-guards-wrapped-command"
+
+# --- rm-safety-net -----------------------------------------------------------
+H=rm-safety-net
+want_block $H "$RM -rf ~"
+want_block $H "cd /tmp && $RM -rf ~"
+want_block $H "[[ -n \$($RM -rf ~) ]]"
+want_block $H "[[ -n \`$RM -rf ~\` ]]"
+want_block $H "if true; then $RM -rf ~; fi"
+want_block $H "for f in a; do $RM -rf ~; done"
+want_block $H "( $RM -rf ~ )"
+want_block $H "x=\$($RM -rf /etc)"
+want_block $H "npm ci && $RM -rf /home/user"
+want_allow $H "$RM -rf node_modules"
+want_allow $H "cd app && $RM -rf node_modules && npm ci"
+want_allow $H "npm run confirm ~/project"
+want_allow $H "echo 'please confirm ~/data first'"
+want_allow $H "rmdir empty-dir"
+want_allow $H "awk '{print \$1}' access.log"
+want_allow $H "( cd /tmp && ls )"
+want_allow $H "echo \$(basename \$(pwd))"
+
+# --- system-dir-protection-guard ---------------------------------------------
+H=system-dir-protection-guard
+want_block $H "$RM -rf /etc"
+want_block $H "cd /tmp && $RM -rf /etc"
+want_block $H "[[ -n \$($RM -rf /etc) ]]"
+want_block $H "if true; then $RM -rf /usr; fi"
+want_block $H "for f in a; do $RM -rf /var; done"
+want_block $H "( $RM -rf /etc )"
+want_block $H "npm ci && mv /etc /tmp/x"
+want_block $H "true && chmod -R 777 /etc"
+want_allow $H "ls -la /etc"
+want_allow $H "cat /etc/hosts"
+want_allow $H "mv old.txt new.txt"
+want_allow $H "chmod -R 755 ./public"
+want_allow $H "awk '{print \$1}' /var/log/app.log"
+want_allow $H "( cd /tmp && ls )"
+want_allow $H "grep -r 'TODO' /home/me/project"
+
+# --- auto-mode-safety-enforcer -----------------------------------------------
+H=auto-mode-safety-enforcer
+want_block $H "$RM -rf ~; echo done"
+want_block $H "[[ -n \$($RM -rf ~) ]]"
+want_block $H "if true; then $RM -rf ~; fi"
+want_block $H "for f in a; do $RM -rf ~; done"
+want_block $H "x=\$($RM -rf /etc)"
+want_allow $H "ls ~/projects"
+want_allow $H "cat ~/.bashrc"
+want_allow $H "cp -r ~/a ~/b"
+want_allow $H "du -sh ~/"
+want_allow $H "$RM -rf node_modules"
+want_allow $H "jq '{a: .b}' package.json"
+
+# --- bash-project-fence -------------------------------------------------------
+# Different concern: this one fences *paths outside the project root*, not
+# destructive verbs. Its word split does not break on ( ) or a backtick, so a
+# path inside a substitution arrived as the token "~)" — matching neither the
+# "~/" case nor the absolute-path case, and the reference passed unnoticed.
+# The fix strips the wrapping punctuation from the token edges.
+fence_run() {
+  local cmd="$1" P rc
+  P="$(mktemp -d)"
+  mkdir -p "$P/src"
+  python3 -c '
+import json,sys
+print(json.dumps({"tool_name":"Bash","tool_input":{"command":sys.argv[1]},
+                  "cwd":sys.argv[2],"session_id":"t"}))' "$cmd" "$P" \
+    | (cd "$P" && CLAUDE_PROJECT_DIR="$P" HOME=/nonexistent-home-for-test \
+         bash "$ROOT/examples/bash-project-fence.sh") >/dev/null 2>&1
+  # HOME must not sit under /tmp here. /tmp is on this hook's default allow
+  # list, and mktemp -d hands out /tmp paths, so a temp HOME makes every `~`
+  # case allowed and the four assertions below pass no matter what the code
+  # does. The path does not need to exist; only its prefix is compared.
+  rc=$?
+  find "$P" -mindepth 1 -delete 2>/dev/null; rmdir "$P" 2>/dev/null
+  return $rc
+}
+fence_block() {
+  if fence_run "$1"; then FAIL=$((FAIL+1)); echo "  FAIL blocked [fence]: $1"
+  else PASS=$((PASS+1)); echo "  ok   blocked [fence]: $1"; fi
+}
+fence_allow() {
+  if fence_run "$1"; then PASS=$((PASS+1)); echo "  ok   allowed [fence]: $1"
+  else FAIL=$((FAIL+1)); echo "  FAIL allowed [fence]: $1"; fi
+}
+
+fence_block "cat /home/someone/secrets.txt"
+fence_block "[[ -n \$(cat /home/someone/secrets.txt) ]]"
+fence_block "x=\$(cat /home/someone/secrets.txt)"
+fence_block "echo \`cat /home/someone/secrets.txt\`"
+# The home directory reached the tokenizer as "~)" and "~`", which match
+# neither branch. These are the four that actually failed before the fix; the
+# absolute-path forms above were already caught, so they alone would have
+# recorded the defect as the spec.
+fence_block "[[ -n \$(ls ~) ]]"
+fence_block "[[ -n \`ls ~\` ]]"
+fence_block "x=\$(ls ~)"
+fence_block "( ls ~ )"
+fence_allow "ls -la"
+fence_allow "git status"
+fence_allow "echo hello > /tmp/out.txt"
+fence_allow "cat /tmp/scratch"
+fence_allow "npm ci && npm run build"
+fence_allow "curl -s https://example.com/api"
+fence_allow "echo \$(basename \$(pwd))"
+fence_allow "for i in \$(seq 1 3); do echo \$i; done"
+
+echo
+echo "example-guards-wrapped-command: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/tests/file-edit-backup.test.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# Tests for file-edit-backup.sh
+#
+# The interesting case is path 2: a file overwritten through Bash
+# (redirection, tee, mv) used to slip past this hook entirely.
+# Reported by a reader on 2026-07-17.
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/examples/file-edit-backup.sh"
+PASS=0; FAIL=0
+
+WORK=$(mktemp -d)
+export HOME="$WORK/home"
+mkdir -p "$HOME"
+BACKUPS="$HOME/.claude/file-backups"
+
+# expect_backup <desc> <json> <basename-that-must-appear|NONE>
+expect_backup() {
+    local desc="$1" input="$2" want="$3"
+    rm -rf "$BACKUPS" 2>/dev/null
+    ( cd "$WORK" && printf '%s' "$input" | bash "$HOOK" >/dev/null 2>&1 )
+    local found=0
+    if [ "$want" != "NONE" ] && [ -d "$BACKUPS" ]; then
+        ls "$BACKUPS" 2>/dev/null | grep -q "$want" && found=1
+    fi
+    if [ "$want" = "NONE" ]; then
+        if [ ! -d "$BACKUPS" ] || [ -z "$(ls -A "$BACKUPS" 2>/dev/null)" ]; then
+            echo "PASS: $desc"; ((PASS++))
+        else
+            echo "FAIL: $desc (expected no backup, got $(ls "$BACKUPS"))"; ((FAIL++))
+        fi
+    elif [ "$found" = "1" ]; then
+        echo "PASS: $desc"; ((PASS++))
+    else
+        echo "FAIL: $desc (expected a backup matching '$want')"; ((FAIL++))
+    fi
+}
+
+cd "$WORK" || exit 1
+echo "original" > target.md
+echo "original" > appended.md
+echo "original" > teed.md
+echo "original" > moved.md
+
+# Path 1 — the Edit/Write tools (existing behaviour must not regress)
+expect_backup "Write on an existing file is backed up" \
+    "{\"tool_name\":\"Write\",\"tool_input\":{\"file_path\":\"$WORK/target.md\"}}" "target.md"
+
+expect_backup "Write on a new file makes no backup" \
+    "{\"tool_name\":\"Write\",\"tool_input\":{\"file_path\":\"$WORK/does-not-exist.md\"}}" "NONE"
+
+# Path 2 — Bash. This is the hole the reader named.
+expect_backup "Bash redirection > is backed up" \
+    '{"tool_name":"Bash","tool_input":{"command":"echo new > target.md"}}' "target.md"
+
+expect_backup "Bash append >> is backed up" \
+    '{"tool_name":"Bash","tool_input":{"command":"echo more >> appended.md"}}' "appended.md"
+
+expect_backup "Bash tee is backed up" \
+    '{"tool_name":"Bash","tool_input":{"command":"cat src | tee teed.md"}}' "teed.md"
+
+expect_backup "Bash tee -a is backed up" \
+    '{"tool_name":"Bash","tool_input":{"command":"cat src | tee -a teed.md"}}' "teed.md"
+
+expect_backup "Bash mv destination is backed up" \
+    '{"tool_name":"Bash","tool_input":{"command":"mv src.txt moved.md"}}' "moved.md"
+
+expect_backup "Bash redirection inside a chain is backed up" \
+    '{"tool_name":"Bash","tool_input":{"command":"cd /tmp && echo x > target.md"}}' "target.md"
+
+# Must NOT fire on things that only look like writes
+expect_backup "fd duplication >&2 makes no backup" \
+    '{"tool_name":"Bash","tool_input":{"command":"echo hi >&2"}}' "NONE"
+
+expect_backup "stderr redirect 2>&1 makes no backup" \
+    '{"tool_name":"Bash","tool_input":{"command":"make 2>&1 | less"}}' "NONE"
+
+expect_backup "writing to a device file makes no backup" \
+    '{"tool_name":"Bash","tool_input":{"command":"echo x > /dev/null"}}' "NONE"
+
+expect_backup "redirect to a file that does not exist makes no backup" \
+    '{"tool_name":"Bash","tool_input":{"command":"echo x > brand-new.md"}}' "NONE"
+
+expect_backup "a read-only command makes no backup" \
+    '{"tool_name":"Bash","tool_input":{"command":"grep -r TODO ."}}' "NONE"
+
+# The hook must never block: exit code is always 0
+code=$(printf '%s' '{"tool_name":"Bash","tool_input":{"command":"echo x > target.md"}}' | bash "$HOOK" >/dev/null 2>&1; echo $?)
+if [ "$code" = "0" ]; then echo "PASS: never blocks (exit 0)"; ((PASS++)); else echo "FAIL: expected exit 0, got $code"; ((FAIL++)); fi
+
+cd / && rm -rf "$WORK" 2>/dev/null
+
+echo ""
+echo "PASS: $PASS  FAIL: $FAIL"
+[ "$FAIL" -eq 0 ]

package/tests/git-filter-repo-guard.test.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Tests for git-filter-repo-guard.sh
+# Run: bash tests/git-filter-repo-guard.test.sh
+set -euo pipefail
+
+PASS=0
+FAIL=0
+HOOK="$(dirname "$0")/../examples/git-filter-repo-guard.sh"
+
+test_hook() {
+    local input="$1" expected_exit="$2" desc="$3"
+    local actual_exit=0
+    echo "$input" | bash "$HOOK" > /dev/null 2>/dev/null || actual_exit=$?
+    if [ "$actual_exit" -eq "$expected_exit" ]; then
+        echo "  PASS: $desc"
+        PASS=$((PASS + 1))
+    else
+        echo "  FAIL: $desc (expected exit $expected_exit, got $actual_exit)"
+        FAIL=$((FAIL + 1))
+    fi
+}
+
+echo "git-filter-repo-guard.sh tests"
+echo ""
+
+# --- Block: git filter-repo ---
+test_hook '{"tool_input":{"command":"git filter-repo --force"}}' 2 "Block git filter-repo --force"
+test_hook '{"tool_input":{"command":"git filter-repo --invert-paths --path secret.txt"}}' 2 "Block git filter-repo with path filter"
+test_hook '{"tool_input":{"command":"git filter-repo --strip-blobs-bigger-than 10M"}}' 2 "Block git filter-repo blob strip"
+test_hook '{"tool_input":{"command":"git filter-repo"}}' 2 "Block bare git filter-repo"
+
+# --- Block: git filter-branch ---
+test_hook '{"tool_input":{"command":"git filter-branch --tree-filter rm -f passwords.txt HEAD"}}' 2 "Block git filter-branch --tree-filter"
+test_hook '{"tool_input":{"command":"git filter-branch --env-filter"}}' 2 "Block git filter-branch --env-filter"
+test_hook '{"tool_input":{"command":"git filter-branch"}}' 2 "Block bare git filter-branch"
+
+# --- Block: BFG Repo-Cleaner ---
+test_hook '{"tool_input":{"command":"bfg --strip-blobs-bigger-than 100M"}}' 2 "Block bfg --strip-blobs-bigger-than"
+test_hook '{"tool_input":{"command":"bfg --delete-files id_rsa"}}' 2 "Block bfg --delete-files"
+test_hook '{"tool_input":{"command":"java -jar bfg.jar --replace-text passwords.txt"}}' 2 "Block bfg.jar via java"
+
+# --- Allow: Safe git commands ---
+test_hook '{"tool_input":{"command":"git status"}}' 0 "Allow git status"
+test_hook '{"tool_input":{"command":"git log --oneline"}}' 0 "Allow git log"
+test_hook '{"tool_input":{"command":"git diff HEAD~3"}}' 0 "Allow git diff"
+test_hook '{"tool_input":{"command":"git commit -m fix"}}' 0 "Allow git commit"
+test_hook '{"tool_input":{"command":"git push origin main"}}' 0 "Allow git push"
+test_hook '{"tool_input":{"command":"git rebase main"}}' 0 "Allow non-interactive rebase"
+
+# --- Allow: Commands containing filter as substring (not filter-repo) ---
+test_hook '{"tool_input":{"command":"grep filter README.md"}}' 0 "Allow grep filter"
+test_hook '{"tool_input":{"command":"cat filter-config.json"}}' 0 "Allow cat filter-config.json"
+
+# --- Allow: Empty/missing input ---
+test_hook '{}' 0 "Allow empty input"
+test_hook '{"tool_input":{}}' 0 "Allow missing command"
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed out of $((PASS + FAIL)) tests"
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1