cc-safe-setup 29.8.0 → 30.0.4

package/tests/worktree-escape-write-guard.test.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# Test for worktree-escape-write-guard.sh
+#
+# Verifies the hook blocks (exit 2) Edit/Write/MultiEdit whose absolute
+# file_path escapes the active worktree onto the main checkout
+# (Claude Code issue #70069), while letting through:
+#   - in-worktree absolute paths
+#   - relative paths (resolve against cwd = the worktree)
+#   - sessions not in a worktree
+#   - paths entirely outside the repo (other guards' concern)
+#   - non-edit tools
+
+set -u
+
+HOOK="$(dirname "$0")/../examples/worktree-escape-write-guard.sh"
+[ ! -x "$HOOK" ] && chmod +x "$HOOK"
+
+REPO="/home/dev/myrepo"
+WT="$REPO/.claude/worktrees/feature-x"
+
+PASS=0
+FAIL=0
+
+run_case() {
+    local name="$1" tool="$2" cwd="$3" file="$4" expect="$5"
+    local input rc
+    input=$(jq -nc --arg t "$tool" --arg c "$cwd" --arg f "$file" \
+        '{tool_name:$t, cwd:$c, tool_input:{file_path:$f}}')
+    echo "$input" | "$HOOK" >/dev/null 2>&1
+    rc=$?
+    if [ "$expect" = "block" ]; then
+        if [ "$rc" = "2" ]; then PASS=$((PASS + 1)); echo "PASS: $name"
+        else FAIL=$((FAIL + 1)); echo "FAIL: $name (expected block/exit2, got $rc)"; fi
+    else
+        if [ "$rc" = "0" ]; then PASS=$((PASS + 1)); echo "PASS: $name"
+        else FAIL=$((FAIL + 1)); echo "FAIL: $name (expected allow/exit0, got $rc)"; fi
+    fi
+}
+
+# --- the bug: must block ---
+run_case "Edit escapes to main checkout"      "Edit"  "$WT" "$REPO/packages/rrweb/src/record/foo.ts" block
+run_case "Write escapes to main checkout"     "Write" "$WT" "$REPO/src/index.ts"                      block
+run_case "MultiEdit escapes to main checkout" "MultiEdit" "$WT" "$REPO/README.md"                     block
+run_case "escape from a worktree subdir"      "Edit"  "$WT/packages/a" "$REPO/packages/a/b.ts"        block
+run_case "escape to repo root file"           "Write" "$WT" "$REPO/package.json"                      block
+
+# --- legitimate edits inside the worktree: must allow ---
+run_case "in-worktree absolute path"          "Edit"  "$WT" "$WT/packages/rrweb/src/record/foo.ts"    allow
+run_case "in-worktree repo-root file"         "Write" "$WT" "$WT/package.json"                        allow
+run_case "in-worktree from subdir"            "Edit"  "$WT/packages/a" "$WT/packages/a/b.ts"          allow
+run_case "relative path (resolves in wt)"     "Edit"  "$WT" "packages/rrweb/src/record/foo.ts"        allow
+run_case "relative dotslash path"             "Write" "$WT" "./src/index.ts"                          allow
+
+# --- not a worktree session: hook inactive, must allow ---
+run_case "normal repo, absolute under repo"   "Edit"  "$REPO" "$REPO/packages/a/b.ts"                 allow
+run_case "normal repo, relative"              "Write" "$REPO" "src/index.ts"                          allow
+
+# --- outside the repo entirely: not this guard's concern, allow ---
+run_case "absolute path outside repo"         "Edit"  "$WT" "/etc/hosts"                              allow
+run_case "absolute path other project"        "Write" "$WT" "/home/dev/other/file.ts"                allow
+
+# --- wrong tool: allow ---
+run_case "Bash tool ignored"                  "Bash"  "$WT" "$REPO/packages/a/b.ts"                   allow
+run_case "Read tool ignored"                  "Read"  "$WT" "$REPO/packages/a/b.ts"                   allow
+
+echo ""
+echo "PASS=$PASS FAIL=$FAIL"
+[ "$FAIL" -eq 0 ]

package/tests/worktree-hooks-path-fix.test.sh

@@ -0,0 +1,181 @@
+#!/bin/bash
+# Tests for worktree-hooks-path-fix.sh
+# This suite cds into temp repos before invoking the hook, so a relative path
+# here only resolves when the suite itself was launched with an absolute path.
+HOOK="$(cd "$(dirname "$0")/../examples" && pwd)/worktree-hooks-path-fix.sh"
+PASS=0; FAIL=0
+
+TEST_BASE=$(mktemp -d)
+cleanup() { rm -rf "$TEST_BASE"; }
+trap cleanup EXIT
+
+run_test() {
+    local desc="$1" expect_code="$2" check_fn="${3:-}"
+    if [ -n "$check_fn" ]; then
+        if "$check_fn"; then
+            echo "PASS: $desc"
+            PASS=$((PASS + 1))
+        else
+            echo "FAIL: $desc"
+            FAIL=$((FAIL + 1))
+        fi
+    fi
+}
+
+# === Helper: create a main repo + a Claude-style worktree at known path ===
+setup_repo_with_worktree() {
+    local main_repo="$1"
+    local worktree_subdir="$2"
+
+    rm -rf "$main_repo"
+    mkdir -p "$main_repo"
+    cd "$main_repo" || return 1
+    git init --quiet
+    git config user.email "test@test"
+    git config user.name "test"
+    git commit --allow-empty --quiet -m "init"
+    git config extensions.worktreeConfig true
+    # Simulate Husky-style shared core.hooksPath
+    git config core.hooksPath ".hooks_shared"
+
+    # Create a Claude-style worktree
+    local worktree_path="$main_repo/.claude/worktrees/$worktree_subdir"
+    mkdir -p "$(dirname "$worktree_path")"
+    git worktree add -q "$worktree_path" 2>/dev/null
+}
+
+# === Test 1: bogus absolute hooksPath gets unset ===
+setup_repo_with_worktree "$TEST_BASE/repo1" "wt1"
+WORKTREE="$TEST_BASE/repo1/.claude/worktrees/wt1"
+# Write a bogus absolute hooksPath
+git -C "$WORKTREE" config --worktree core.hooksPath "/tmp/nonexistent/hooks"
+
+# Run the hook
+echo '{"hook_event_name":"SessionStart"}' | CLAUDE_PROJECT_DIR="$WORKTREE" bash "$HOOK" >/dev/null 2>&1
+
+# Verify the worktree config no longer has core.hooksPath
+RESULT=$(git -C "$WORKTREE" config --worktree --get core.hooksPath 2>/dev/null || echo "")
+if [ -z "$RESULT" ]; then
+    echo "PASS: bogus absolute hooksPath unset"
+    PASS=$((PASS + 1))
+else
+    echo "FAIL: hooksPath still set: $RESULT"
+    FAIL=$((FAIL + 1))
+fi
+
+# Verify shared config's hooksPath still resolves
+SHARED=$(git -C "$WORKTREE" config --get core.hooksPath 2>/dev/null || echo "")
+if [ "$SHARED" = ".hooks_shared" ]; then
+    echo "PASS: shared hooksPath fell through correctly"
+    PASS=$((PASS + 1))
+else
+    echo "FAIL: shared hooksPath wrong: $SHARED (expected .hooks_shared)"
+    FAIL=$((FAIL + 1))
+fi
+
+# === Test 2: relative hooksPath is left alone ===
+setup_repo_with_worktree "$TEST_BASE/repo2" "wt2"
+WORKTREE="$TEST_BASE/repo2/.claude/worktrees/wt2"
+git -C "$WORKTREE" config --worktree core.hooksPath ".husky/_"
+echo '{"hook_event_name":"SessionStart"}' | CLAUDE_PROJECT_DIR="$WORKTREE" bash "$HOOK" >/dev/null 2>&1
+RESULT=$(git -C "$WORKTREE" config --worktree --get core.hooksPath 2>/dev/null || echo "")
+if [ "$RESULT" = ".husky/_" ]; then
+    echo "PASS: relative hooksPath left alone"
+    PASS=$((PASS + 1))
+else
+    echo "FAIL: relative hooksPath altered: $RESULT"
+    FAIL=$((FAIL + 1))
+fi
+
+# === Test 3: absolute path inside worktree is left alone ===
+setup_repo_with_worktree "$TEST_BASE/repo3" "wt3"
+WORKTREE="$TEST_BASE/repo3/.claude/worktrees/wt3"
+INTERNAL_PATH="$WORKTREE/.local-hooks"
+git -C "$WORKTREE" config --worktree core.hooksPath "$INTERNAL_PATH"
+echo '{"hook_event_name":"SessionStart"}' | CLAUDE_PROJECT_DIR="$WORKTREE" bash "$HOOK" >/dev/null 2>&1
+RESULT=$(git -C "$WORKTREE" config --worktree --get core.hooksPath 2>/dev/null || echo "")
+if [ "$RESULT" = "$INTERNAL_PATH" ]; then
+    echo "PASS: absolute path inside worktree left alone"
+    PASS=$((PASS + 1))
+else
+    echo "FAIL: internal absolute path altered: $RESULT"
+    FAIL=$((FAIL + 1))
+fi
+
+# === Test 4: non-worktree (main checkout) is a no-op ===
+setup_repo_with_worktree "$TEST_BASE/repo4" "wt4"
+MAIN_REPO="$TEST_BASE/repo4"
+# Set a bogus hooksPath in main config (per-worktree scope not applicable here, use --local)
+git -C "$MAIN_REPO" config core.hooksPath "/tmp/bogus"
+echo '{"hook_event_name":"SessionStart"}' | CLAUDE_PROJECT_DIR="$MAIN_REPO" bash "$HOOK" >/dev/null 2>&1
+RESULT=$(git -C "$MAIN_REPO" config --get core.hooksPath 2>/dev/null || echo "")
+if [ "$RESULT" = "/tmp/bogus" ]; then
+    echo "PASS: main checkout untouched"
+    PASS=$((PASS + 1))
+else
+    echo "FAIL: main checkout altered: $RESULT"
+    FAIL=$((FAIL + 1))
+fi
+
+# === Test 5: worktree NOT under .claude/worktrees/ is left alone ===
+mkdir -p "$TEST_BASE/repo5"
+cd "$TEST_BASE/repo5"
+git init --quiet
+git config user.email t@t; git config user.name t
+git commit --allow-empty --quiet -m i
+git config extensions.worktreeConfig true
+OTHER_WORKTREE="$TEST_BASE/other-wt-location/wt5"
+mkdir -p "$(dirname "$OTHER_WORKTREE")"
+git worktree add -q "$OTHER_WORKTREE" 2>/dev/null
+git -C "$OTHER_WORKTREE" config --worktree core.hooksPath "/tmp/bogus"
+echo '{"hook_event_name":"SessionStart"}' | CLAUDE_PROJECT_DIR="$OTHER_WORKTREE" bash "$HOOK" >/dev/null 2>&1
+RESULT=$(git -C "$OTHER_WORKTREE" config --worktree --get core.hooksPath 2>/dev/null || echo "")
+if [ "$RESULT" = "/tmp/bogus" ]; then
+    echo "PASS: non-Claude worktree path pattern left alone"
+    PASS=$((PASS + 1))
+else
+    echo "FAIL: non-Claude worktree altered: $RESULT"
+    FAIL=$((FAIL + 1))
+fi
+
+# === Test 6: CC_WORKTREE_HOOKS_FIX_DISABLE bypasses ===
+setup_repo_with_worktree "$TEST_BASE/repo6" "wt6"
+WORKTREE="$TEST_BASE/repo6/.claude/worktrees/wt6"
+git -C "$WORKTREE" config --worktree core.hooksPath "/tmp/bogus6"
+echo '{"hook_event_name":"SessionStart"}' | CC_WORKTREE_HOOKS_FIX_DISABLE=1 CLAUDE_PROJECT_DIR="$WORKTREE" bash "$HOOK" >/dev/null 2>&1
+RESULT=$(git -C "$WORKTREE" config --worktree --get core.hooksPath 2>/dev/null || echo "")
+if [ "$RESULT" = "/tmp/bogus6" ]; then
+    echo "PASS: DISABLE env var bypasses hook"
+    PASS=$((PASS + 1))
+else
+    echo "FAIL: DISABLE bypass failed: $RESULT"
+    FAIL=$((FAIL + 1))
+fi
+
+# === Test 7: non-git directory is a no-op ===
+NON_GIT="$TEST_BASE/not-a-repo"
+mkdir -p "$NON_GIT"
+echo '{"hook_event_name":"SessionStart"}' | CLAUDE_PROJECT_DIR="$NON_GIT" bash "$HOOK" >/dev/null 2>&1
+EXIT_CODE=$?
+if [ "$EXIT_CODE" = "0" ]; then
+    echo "PASS: non-git directory exits 0"
+    PASS=$((PASS + 1))
+else
+    echo "FAIL: non-git directory exit code: $EXIT_CODE"
+    FAIL=$((FAIL + 1))
+fi
+
+# === Test 8: empty input is no-op ===
+echo '{}' | CLAUDE_PROJECT_DIR="$TEST_BASE/repo6/.claude/worktrees/wt6" bash "$HOOK" >/dev/null 2>&1
+EXIT_CODE=$?
+if [ "$EXIT_CODE" = "0" ]; then
+    echo "PASS: empty event payload exits 0"
+    PASS=$((PASS + 1))
+else
+    echo "FAIL: empty event exit code: $EXIT_CODE"
+    FAIL=$((FAIL + 1))
+fi
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/tests/worktree-parent-write-guard.test.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# Test for worktree-parent-write-guard.sh
+#
+# Verifies the hook blocks (exit 2) writes that target the PARENT repo while
+# the agent is working in a worktree nested at <repo>/.claude/worktrees/<name>/,
+# and allows (exit 0) correct in-worktree writes and writes that are not part of
+# the nested-worktree danger (normal repos, /tmp, home configs).
+#
+# Customer evidence: anthropics/claude-code #62547, #60679, #69026.
+
+set -u
+
+HOOK="$(dirname "$0")/../examples/worktree-parent-write-guard.sh"
+[ ! -x "$HOOK" ] && chmod +x "$HOOK"
+
+PASS=0
+FAIL=0
+
+run_case() {
+    local name="$1" cwd="$2" target="$3" expect="$4"
+    local input rc
+    input=$(jq -nc --arg cwd "$cwd" --arg t "$target" '{cwd:$cwd, tool_input:{file_path:$t}}')
+    echo "$input" | "$HOOK" >/dev/null 2>&1
+    rc=$?
+    if [ "$expect" = "block" ]; then
+        if [ "$rc" = "2" ]; then PASS=$((PASS+1)); echo "PASS: $name"
+        else FAIL=$((FAIL+1)); echo "FAIL: $name (expected block/2, got $rc)"; fi
+    else
+        if [ "$rc" = "0" ]; then PASS=$((PASS+1)); echo "PASS: $name"
+        else FAIL=$((FAIL+1)); echo "FAIL: $name (expected allow/0, got $rc)"; fi
+    fi
+}
+
+W="/home/u/app/.claude/worktrees/foo"
+
+# --- dangerous: must block ---
+run_case "parent canonical src"      "$W"     "/home/u/app/src/x.js"                     block
+run_case "parent root file"          "$W"     "/home/u/app/README.md"                    block
+run_case "subdir cwd -> parent"      "$W/src" "/home/u/app/src/x.js"                      block
+run_case "sibling worktree target"   "$W"     "/home/u/app/.claude/worktrees/bar/x.js"   block
+
+# --- safe: must allow ---
+run_case "correct in-worktree (abs)" "$W"     "$W/src/x.js"                              allow
+run_case "in-worktree subdir cwd"    "$W/src" "$W/src/x.js"                              allow
+run_case "normal repo (no worktree)" "/home/u/app" "/home/u/app/src/x.js"               allow
+run_case "write to /tmp"             "$W"     "/tmp/scratch.txt"                         allow
+run_case "write to home config"      "$W"     "/home/u/.claude/settings.json"           allow
+
+echo "----------------------------------------"
+echo "PASS=$PASS FAIL=$FAIL"
+[ "$FAIL" -eq 0 ] || exit 1

package/tests/write-empty-content-guard.test.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Tests for write-empty-content-guard.sh (#72666)
+# Run: bash tests/write-empty-content-guard.test.sh
+set -uo pipefail
+
+PASS=0
+FAIL=0
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/examples/write-empty-content-guard.sh"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+
+NONEMPTY="$TMP/keep.txt"; printf 'line1\nline2\nline3\n' > "$NONEMPTY"
+EMPTYF="$TMP/empty.txt";  : > "$EMPTYF"
+NEWF="$TMP/new.txt"       # does not exist
+
+run() { # $1 = file, $2 = content (raw)
+    local exit=0
+    jq -cn --arg f "$1" --arg c "$2" '{tool_input:{file_path:$f,content:$c}}' | bash "$HOOK" >/dev/null 2>/dev/null || exit=$?
+    echo "$exit"
+}
+
+check() { # $1 = expected exit, $2 = actual exit, $3 = desc
+    if [ "$1" = "$2" ]; then echo "  PASS: $3"; PASS=$((PASS+1)); else echo "  FAIL: $3 (expected $1, got $2)"; FAIL=$((FAIL+1)); fi
+}
+
+echo "write-empty-content-guard.sh tests"
+echo ""
+
+check 2 "$(run "$NONEMPTY" "")"            "empty content over non-empty file -> BLOCK (exit 2)"
+check 2 "$(run "$NONEMPTY" "
+	 ")"                                    "whitespace-only content over non-empty file -> BLOCK"
+check 0 "$(run "$NONEMPTY" "new real text")" "real content over non-empty file -> allow"
+check 0 "$(run "$EMPTYF" "")"              "empty content over already-empty file -> allow (nothing to lose)"
+check 0 "$(run "$NEWF" "")"                "empty content to a new (nonexistent) file -> allow (creation)"
+
+echo ""
+echo "PASS=$PASS FAIL=$FAIL"
+[ "$FAIL" -eq 0 ]

package/tests/write-nul-corruption-detector.test.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Standalone tests for write-nul-corruption-detector.sh
+# Run: bash tests/write-nul-corruption-detector.test.sh
+HOOK="$(dirname "$0")/../examples/write-nul-corruption-detector.sh"
+PASS=0; FAIL=0
+TMP=$(mktemp -d)
+
+run() { # desc input expected_exit
+    local desc="$1" input="$2" expected="$3" actual=0
+    echo "$input" | bash "$HOOK" >/dev/null 2>&1 || actual=$?
+    if [ "$actual" -eq "$expected" ]; then echo "  PASS: $desc"; PASS=$((PASS+1));
+    else echo "  FAIL: $desc (expected $expected, got $actual)"; FAIL=$((FAIL+1)); fi
+}
+
+printf 'clean text line\n' > "$TMP/clean.txt"
+printf 'good stuff\x00\x00\x00corrupted tail' > "$TMP/bad.txt"
+# Same byte count as a 12-char file but tail is NUL-padded — wc -c cannot tell.
+printf 'AAAAAA\x00\x00\x00\x00\x00\x00' > "$TMP/pad.txt"
+printf 'binary\x00\x00data' > "$TMP/img.png"
+
+run "empty input passes"                 '{}' 0
+run "missing file passes"                '{"tool_name":"Write","tool_input":{"file_path":"/nonexistent/xyz.txt"}}' 0
+run "clean text passes"                  "{\"tool_name\":\"Write\",\"tool_input\":{\"file_path\":\"$TMP/clean.txt\"}}" 0
+run "NUL corruption flagged"             "{\"tool_name\":\"Write\",\"tool_input\":{\"file_path\":\"$TMP/bad.txt\"}}" 2
+run "NUL padding (size-preserving) flagged" "{\"tool_name\":\"Edit\",\"tool_input\":{\"file_path\":\"$TMP/pad.txt\"}}" 2
+run "binary extension skipped"           "{\"tool_name\":\"Write\",\"tool_input\":{\"file_path\":\"$TMP/img.png\"}}" 0
+
+echo "Results: $PASS/$((PASS+FAIL)) passed"
+[ "$FAIL" -eq 0 ]

package/tests/write-overwrite-unread-content.test.sh

@@ -0,0 +1,178 @@
+#!/bin/bash
+# write-overwrite-confirm judged an overwrite by size alone, so the accident in
+# issue #78273 passed silently: the agent read FIVE lines of a hand-built file,
+# confirmed it had content, then replaced the whole file with its own analysis.
+# The replacement was not smaller, so the size check never fired. The original
+# was not in git and could not be recovered.
+#
+# Check 2 asks the other question — was the content being destroyed ever read —
+# using the coverage recorded by examples/record-read-coverage.sh.
+#
+# The controls matter as much as the failing case. A guard that fires on every
+# overwrite is the failure mode read-before-edit.sh already had while its
+# recorder was missing, so these tests pin down when it must stay silent:
+#   - the whole file was read
+#   - the file is new, or small
+#   - the replacement keeps the existing content
+#   - no recorder is installed (no coverage information exists)
+
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+HOOK="$ROOT/examples/write-overwrite-confirm.sh"
+REC="$ROOT/examples/record-read-coverage.sh"
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK" 2>/dev/null' EXIT
+PASS=0; FAIL=0
+
+mk_file() {  # mk_file <path> <lines>
+  local p="$1" n="$2" i
+  : > "$p"
+  for ((i = 1; i <= n; i++)); do printf 'original line %d\n' "$i" >> "$p"; done
+}
+
+payload() {  # payload <tool> <file> <content>
+  python3 -c '
+import json,sys
+print(json.dumps({"tool_name": sys.argv[1],
+                  "tool_input": {"file_path": sys.argv[2], "content": sys.argv[3]}}))' "$@"
+}
+
+read_payload() {  # read_payload <file> <offset> <limit>
+  python3 -c '
+import json,sys
+ti={"file_path": sys.argv[1]}
+if int(sys.argv[2]): ti["offset"]=int(sys.argv[2])
+if int(sys.argv[3]): ti["limit"]=int(sys.argv[3])
+print(json.dumps({"tool_name":"Read","tool_input":ti}))' "$@"
+}
+
+check() {  # check <label> <expect-fire:0|1> <log> <write-json> [env...]
+  local label="$1" expect="$2" log="$3" json="$4"; shift 4
+  local out fired
+  out=$(printf '%s' "$json" | env CC_READ_LOG="$log" "$@" bash "$HOOK" 2>&1 >/dev/null)
+  if printf '%s' "$out" | grep -q 'never read'; then fired=1; else fired=0; fi
+  if [ "$fired" = "$expect" ]; then
+    PASS=$((PASS + 1)); printf '  ok   %s\n' "$label"
+  else
+    FAIL=$((FAIL + 1)); printf '  FAIL %s (expected fire=%s, got %s)\n' "$label" "$expect" "$fired"
+    printf '%s\n' "$out" | sed 's/^/       /' | head -4
+  fi
+}
+
+# ---- the accident: five lines read, whole file replaced -------------------
+F="$WORK/math.txt"; LOG="$WORK/log1"
+mk_file "$F" 200
+printf '%s' "$(read_payload "$F" 1 5)" | CC_READ_LOG="$LOG" bash "$REC" >/dev/null 2>&1
+NEW=$(python3 -c 'print("\n".join("analysis line %d" % i for i in range(1,221)))')
+check "#78273: read 5 of 200 lines, replaced all 200" 1 "$LOG" "$(payload Write "$F" "$NEW")"
+
+# ---- same write, but the file was actually read in full ------------------
+LOG2="$WORK/log2"
+printf '%s' "$(read_payload "$F" 0 0)" | CC_READ_LOG="$LOG2" bash "$REC" >/dev/null 2>&1
+check "control: whole file read first" 0 "$LOG2" "$(payload Write "$F" "$NEW")"
+
+# ---- read in pages that together cover the file --------------------------
+LOG3="$WORK/log3"
+printf '%s' "$(read_payload "$F" 1 100)"   | CC_READ_LOG="$LOG3" bash "$REC" >/dev/null 2>&1
+printf '%s' "$(read_payload "$F" 101 100)" | CC_READ_LOG="$LOG3" bash "$REC" >/dev/null 2>&1
+check "control: read as two pages covering the whole file" 0 "$LOG3" "$(payload Write "$F" "$NEW")"
+
+# ---- pages that leave a hole --------------------------------------------
+LOG4="$WORK/log4"
+printf '%s' "$(read_payload "$F" 1 50)"    | CC_READ_LOG="$LOG4" bash "$REC" >/dev/null 2>&1
+printf '%s' "$(read_payload "$F" 150 51)"  | CC_READ_LOG="$LOG4" bash "$REC" >/dev/null 2>&1
+check "pages with a gap in the middle still count as unread" 1 "$LOG4" "$(payload Write "$F" "$NEW")"
+
+# ---- the replacement keeps every existing line ---------------------------
+LOG5="$WORK/log5"
+printf '%s' "$(read_payload "$F" 1 5)" | CC_READ_LOG="$LOG5" bash "$REC" >/dev/null 2>&1
+KEEP=$(cat "$F"; printf 'appended line\n')
+check "control: replacement keeps all existing lines" 0 "$LOG5" "$(payload Write "$F" "$KEEP")"
+
+# ---- small file ----------------------------------------------------------
+S="$WORK/small.txt"; LOG6="$WORK/log6"
+mk_file "$S" 5
+printf '%s' "$(read_payload "$S" 1 1)" | CC_READ_LOG="$LOG6" bash "$REC" >/dev/null 2>&1
+check "control: file below the minimum line count" 0 "$LOG6" "$(payload Write "$S" "replaced")"
+
+# ---- new file ------------------------------------------------------------
+check "control: file does not exist yet" 0 "$WORK/log1" "$(payload Write "$WORK/brand-new.txt" "$NEW")"
+
+# ---- no recorder installed ----------------------------------------------
+check "control: no read log at all stays silent" 0 "$WORK/absent-log" "$(payload Write "$F" "$NEW")"
+
+# ---- blocking mode returns exit 2 ---------------------------------------
+printf '%s' "$(payload Write "$F" "$NEW")" | \
+  env CC_READ_LOG="$WORK/log1" CC_WRITE_OVERWRITE_BLOCK=1 bash "$HOOK" >/dev/null 2>&1
+if [ "$?" = "2" ]; then
+  PASS=$((PASS + 1)); echo "  ok   CC_WRITE_OVERWRITE_BLOCK=1 refuses the write (exit 2)"
+else
+  FAIL=$((FAIL + 1)); echo "  FAIL CC_WRITE_OVERWRITE_BLOCK=1 did not exit 2"
+fi
+
+# ---- the label must match what the run actually does --------------------
+OUT=$(printf '%s' "$(payload Write "$F" "$NEW")" | env CC_READ_LOG="$WORK/log1" bash "$HOOK" 2>&1 >/dev/null)
+if printf '%s' "$OUT" | grep -q 'WARNING: overwriting' && ! printf '%s' "$OUT" | grep -q 'BLOCKED'; then
+  PASS=$((PASS + 1)); echo "  ok   warn mode says WARNING, not BLOCKED"
+else
+  FAIL=$((FAIL + 1)); echo "  FAIL warn mode mislabels its own verdict"
+fi
+
+# ---- the original size check still works --------------------------------
+OUT=$(printf '%s' "$(payload Write "$F" "tiny")" | env CC_READ_LOG="$WORK/log2" bash "$HOOK" 2>&1 >/dev/null)
+if printf '%s' "$OUT" | grep -q 'File shrinking from'; then
+  PASS=$((PASS + 1)); echo "  ok   original shrink warning is unchanged"
+else
+  FAIL=$((FAIL + 1)); echo "  FAIL original shrink warning regressed"
+fi
+
+# ---- blocking mode when the recorder was never installed ----------------
+# Measured on 2026-09-19: with CC_WRITE_OVERWRITE_BLOCK=1 set but no read log
+# on disk, every write returned exit 0. Check 2 exits early without coverage
+# information, and check 1 - the shrink check, the one that fires on the
+# 500-lines-to-10 accident this hook was written for - never looked at the
+# variable at all. So the documented "refuse the write" mode refused nothing
+# for anyone who installed this hook without record-read-coverage.sh.
+#
+# The controls below are what make the fix meaningful: a hook that simply
+# exits 2 whenever BLOCK is set would pass the first case and fail all four
+# after it.
+BIG="$WORK/shrink.txt"; NOLOG="$WORK/no-recorder-was-ever-installed"
+mk_file "$BIG" 60
+SAME=$(python3 -c 'print("\n".join("replacement line %d" % i for i in range(1,61)))')
+
+verdict() {  # verdict <label> <expect-exit> <write-json> [env...]
+  local label="$1" expect="$2" json="$3"; shift 3
+  local out rc
+  out=$(printf '%s' "$json" | env CC_READ_LOG="$NOLOG" "$@" bash "$HOOK" 2>&1 >/dev/null); rc=$?
+  if [ "$rc" = "$expect" ]; then
+    PASS=$((PASS + 1)); printf '  ok   %s\n' "$label"
+  else
+    FAIL=$((FAIL + 1)); printf '  FAIL %s (expected exit %s, got %s)\n' "$label" "$expect" "$rc"
+    printf '%s\n' "$out" | sed 's/^/       /' | head -3
+  fi
+}
+
+verdict "shrink + BLOCK=1 + no recorder refuses (exit 2)" 2 \
+  "$(payload Write "$BIG" "one line replaces sixty")" CC_WRITE_OVERWRITE_BLOCK=1
+verdict "control: same write without BLOCK only warns" 0 \
+  "$(payload Write "$BIG" "one line replaces sixty")"
+verdict "control: BLOCK=1 but the file does not shrink" 0 \
+  "$(payload Write "$BIG" "$SAME")" CC_WRITE_OVERWRITE_BLOCK=1
+verdict "control: BLOCK=1 on a file under the size floor" 0 \
+  "$(payload Write "$WORK/small.txt" "x")" CC_WRITE_OVERWRITE_BLOCK=1
+verdict "control: BLOCK=1 creating a file that does not exist" 0 \
+  "$(payload Write "$WORK/still-brand-new.txt" "x")" CC_WRITE_OVERWRITE_BLOCK=1
+
+# The word printed has to match the exit code, in this path too.
+OUT=$(printf '%s' "$(payload Write "$BIG" "one line")" | \
+  env CC_READ_LOG="$NOLOG" CC_WRITE_OVERWRITE_BLOCK=1 bash "$HOOK" 2>&1 >/dev/null)
+if printf '%s' "$OUT" | grep -q 'BLOCKED: File shrinking'; then
+  PASS=$((PASS + 1)); echo "  ok   blocking shrink says BLOCKED, not WARNING"
+else
+  FAIL=$((FAIL + 1)); echo "  FAIL blocking shrink still labels itself WARNING"
+fi
+
+echo ""
+echo "PASS=$PASS FAIL=$FAIL"
+[ "$FAIL" -eq 0 ]

package/tests/wsl-host-disk-space-guard.test.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# Tests for wsl-host-disk-space-guard.sh
+# Run: bash tests/wsl-host-disk-space-guard.test.sh
+#
+# Note: this hook reads real `df` output. We can't easily mock the
+# filesystem, so we test what we can deterministically:
+#   1. The hook exits 0 on a healthy system (most CI environments).
+#   2. The hook respects the DISABLE flag.
+#   3. The hook does not trip on environments with no /mnt/c.
+set -euo pipefail
+
+PASS=0
+FAIL=0
+HOOK="$(dirname "$0")/../examples/wsl-host-disk-space-guard.sh"
+
+run_hook() {
+    local input="$1" expected_exit="$2" desc="$3" extra_env="${4:-}"
+    local actual_exit=0
+    if [ -n "$extra_env" ]; then
+        # shellcheck disable=SC2086
+        echo "$input" | env $extra_env bash "$HOOK" >/dev/null 2>/dev/null || actual_exit=$?
+    else
+        echo "$input" | bash "$HOOK" >/dev/null 2>/dev/null || actual_exit=$?
+    fi
+    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 "wsl-host-disk-space-guard.sh tests"
+echo ""
+
+# --- DISABLE flag bypasses everything (always exits 0) ---
+run_hook '{"tool_input":{"command":"echo hello"}}' 0 "DISABLE flag exits 0" "CC_HOST_DISK_DISABLE=1 CC_HOST_DISK_BLOCK_PCT=0"
+
+# --- With block thresholds at 100, never trips block (any used % is < 100 + small margin) ---
+# We use 101 so even a 100%-full disk stays under threshold.
+run_hook '{"tool_input":{"command":"echo hello"}}' 0 "Generous thresholds: no block" "CC_HOST_DISK_BLOCK_PCT=101 CC_LINUX_DISK_BLOCK_PCT=101 CC_HOST_DISK_WARN_PCT=101 CC_LINUX_DISK_WARN_PCT=101"
+
+# --- Block when host threshold is set absurdly low (and /mnt/c exists or doesn't) ---
+# If /mnt/c does not exist (non-WSL CI), block only triggers from / or /home,
+# whose usage is generally well above 0%. Use threshold 0 to force the block branch.
+run_hook '{"tool_input":{"command":"echo hello"}}' 2 "Block when LINUX_BLOCK threshold is 0" "CC_LINUX_DISK_BLOCK_PCT=0"
+
+# --- Empty / missing input ---
+run_hook '{}' 0 "Allow empty input on healthy system" "CC_HOST_DISK_BLOCK_PCT=101 CC_LINUX_DISK_BLOCK_PCT=101"
+run_hook '{"tool_input":{}}' 0 "Allow missing command" "CC_HOST_DISK_BLOCK_PCT=101 CC_LINUX_DISK_BLOCK_PCT=101"
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed out of $((PASS + FAIL)) tests"
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1