cc-safe-setup 29.8.0 → 30.0.4

package/examples/plugin-hooks-json-bloat-detector.sh

@@ -0,0 +1,169 @@
+#!/bin/bash
+# ================================================================
+# plugin-hooks-json-bloat-detector.sh — Detect duplicated hook
+#   registrations inside plugin hooks.json files (additive growth
+#   from the multi-agent dispatch path).
+# ================================================================
+# PURPOSE:
+#   Issue #64022 documents a class where a plugin's
+#   `hooks/hooks.json` registrations multiply additively in
+#   multi-agent sessions (observed 1× → 122× per hook). At high
+#   multiples every hook fires N times per tool call and tool
+#   output is corrupted. The reporter's plugin had no additive
+#   writer; the only mechanism that fits is the harness re-running
+#   its plugin-hook load/merge and appending instead of replacing.
+#
+#   The growth is silent until output corruption surfaces it. This
+#   hook scans every installed plugin's hooks.json at session
+#   start, counts duplicate command-string registrations within
+#   each file, and warns when a single command appears more than a
+#   threshold (default 5 times) — well below the 122× blowup but
+#   well above any legitimate "one event, one command, multiple
+#   matchers" registration shape.
+#
+# DETECTION MODEL:
+#   SessionStart fires once per session. We walk every
+#   `~/.claude/plugins/cache/**/hooks/hooks.json` (plus the canonical
+#   `~/.claude/plugins/marketplace/**/hooks/hooks.json` if it exists),
+#   parse each JSON, and within each file count how many times each
+#   distinct command string appears across all event types. If any
+#   command string appears more than CC_PLUGIN_HOOKS_BLOAT_THRESHOLD
+#   times in a single hooks.json, emit a warning identifying the
+#   plugin path, the command, and the duplicate count.
+#
+#   We deliberately ignore the cross-plugin case (the same command
+#   appearing in two different plugins is legitimate) and the
+#   multi-event case (the same command registered for PreToolUse
+#   AND PostToolUse — count each event-bucket separately).
+#
+# CLUSTER:
+#   Candidate cluster #21 — Plugin lifecycle integrity gap
+#   Sub-axis 21A — additive hook-registration growth (#64022).
+#
+# TRIGGER: SessionStart  MATCHER: ""
+#
+# ENV:
+#   CC_PLUGIN_HOOKS_BLOAT_THRESHOLD     default 5  (warn when same command appears >5×)
+#   CC_PLUGIN_HOOKS_BLOAT_DISABLE       non-empty → silent
+#   CC_PLUGIN_HOOKS_BLOAT_QUIET         non-empty → silent
+#   CC_PLUGIN_HOOKS_BLOAT_ROOT          default $HOME/.claude/plugins
+#   CC_PLUGIN_HOOKS_BLOAT_STATE_DIR     default /tmp/cc-plugin-hooks-bloat
+# ================================================================
+
+set -u
+
+# Disable / quiet
+if [ -n "${CC_PLUGIN_HOOKS_BLOAT_DISABLE:-}" ] || [ -n "${CC_PLUGIN_HOOKS_BLOAT_QUIET:-}" ]; then
+    exit 0
+fi
+
+THRESHOLD="${CC_PLUGIN_HOOKS_BLOAT_THRESHOLD:-5}"
+PLUGINS_ROOT="${CC_PLUGIN_HOOKS_BLOAT_ROOT:-$HOME/.claude/plugins}"
+STATE_DIR="${CC_PLUGIN_HOOKS_BLOAT_STATE_DIR:-/tmp/cc-plugin-hooks-bloat}"
+WARN_FILE="$STATE_DIR/last-warn"
+
+mkdir -p "$STATE_DIR" 2>/dev/null || exit 0
+
+# If plugin root doesn't exist, nothing to scan
+[ -d "$PLUGINS_ROOT" ] || exit 0
+
+# Need jq for JSON parsing; fail-soft if missing
+if ! command -v jq >/dev/null 2>&1; then
+    exit 0
+fi
+
+# Read input (Claude Code passes session context on stdin; we don't use it for
+# this detector, but consume it so the harness doesn't block).
+INPUT=$(cat 2>/dev/null || true)
+
+# Track findings across all plugin hooks.json files
+declare -a FINDINGS=()
+
+# Walk every hooks.json under the plugins tree
+while IFS= read -r -d '' HOOKS_FILE; do
+    # Skip if not a file (broken symlink etc.)
+    [ -f "$HOOKS_FILE" ] || continue
+
+    # Skip if the file is not valid JSON (fail-soft, do not warn on broken files
+    # — those are a separate problem)
+    if ! jq -e . "$HOOKS_FILE" >/dev/null 2>&1; then
+        continue
+    fi
+
+    # Extract every hook command string, grouped per event-bucket so that the
+    # same command legitimately registered for PreToolUse AND PostToolUse
+    # doesn't trip the detector. Output format: "<event>\t<command>"
+    EVENT_CMDS=$(jq -r '
+        (.hooks // {}) | to_entries[] |
+        .key as $event |
+        (.value // []) | .[] |
+        ((.hooks // []) | .[]) |
+        select(.command != null) |
+        ($event + "\t" + (.command | tostring))
+    ' "$HOOKS_FILE" 2>/dev/null) || continue
+
+    [ -z "$EVENT_CMDS" ] && continue
+
+    # Count duplicates per event+command pair
+    DUPES=$(printf '%s\n' "$EVENT_CMDS" | sort | uniq -c | awk -v t="$THRESHOLD" '$1 > t {print $0}')
+
+    if [ -n "$DUPES" ]; then
+        # Strip the canonical install root prefix for readability in the warning
+        DISPLAY_PATH="${HOOKS_FILE#$PLUGINS_ROOT/}"
+        FINDINGS+=("$DISPLAY_PATH")
+        FINDINGS+=("$DUPES")
+        FINDINGS+=("---")
+    fi
+done < <(find "$PLUGINS_ROOT" -type f -name 'hooks.json' -path '*/hooks/*' -print0 2>/dev/null)
+
+# No findings → silent exit
+if [ "${#FINDINGS[@]}" -eq 0 ]; then
+    exit 0
+fi
+
+# Debounce: only warn once per hour even if the session restarts repeatedly
+NOW_S=$(date +%s)
+LAST_WARN=0
+if [ -f "$WARN_FILE" ]; then
+    LAST_WARN=$(cat "$WARN_FILE" 2>/dev/null || echo 0)
+fi
+HOUR_AGO=$((NOW_S - 3600))
+if [ "$LAST_WARN" -gt "$HOUR_AGO" ] 2>/dev/null; then
+    exit 0
+fi
+printf '%s' "$NOW_S" > "$WARN_FILE" 2>/dev/null
+
+# Emit advisory warning
+cat >&2 <<EOF
+
+⚠️  Plugin hooks.json bloat detected — duplicate hook registrations.
+
+One or more installed plugins have a hooks.json file where the same command
+string appears more than ${THRESHOLD} times within a single event bucket.
+This is the fingerprint of the additive growth pattern documented in
+anthropics/claude-code Issue #64022 — the harness's plugin-hook load/merge
+path can re-run and append instead of replacing, causing each hook to fire
+N times per tool call.
+
+Findings:
+EOF
+
+for line in "${FINDINGS[@]}"; do
+    printf '  %s\n' "$line" >&2
+done
+
+cat >&2 <<EOF
+
+What to do:
+
+  1. Restore canonical hooks.json from the plugin source (a fresh
+     reinstall of the plugin from its canonical marketplace usually works).
+  2. If the file regrows after restoration, file the recurrence against
+     anthropics/claude-code Issue #64022 with your version and a count.
+  3. Lower this hook's threshold if the false-positive rate is acceptable
+     for your environment (export CC_PLUGIN_HOOKS_BLOAT_THRESHOLD=3).
+
+This warning is advisory. Set CC_PLUGIN_HOOKS_BLOAT_DISABLE=1 to silence.
+EOF
+
+exit 0

package/examples/polyglot-rm-guard.sh

@@ -21,6 +21,18 @@
 #   }
 # }
 
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-polyglot-rm-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [polyglot-rm-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$CMD" ] && exit 0

package/examples/post-compact-safety.sh

@@ -27,6 +27,18 @@
 #
 # Config: CC_POST_COMPACT_GUARD=10 (block for first 10 calls after compact)
 
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-post-compact-safety-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [post-compact-safety]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0

package/examples/post-edit-disk-verify.sh

@@ -0,0 +1,152 @@
+#!/bin/bash
+# post-edit-disk-verify.sh — Catch "Edit/Write reported success but didn't
+# persist to disk" silent failures at the tool boundary.
+#
+# Solves: anthropics/claude-code#61303 — Windows MAX_PATH(260) + isolated
+# worktree + deep nested path yielded an `Edit`/`Write` that reported success
+# in-tool while the filesystem still showed the original content. The agent's
+# `Read` reflected the "edited" state; the disk did not. A defensive
+# verification step inside the dispatched subagent caught it, but the failure
+# mode was invisible until that defensive step fired.
+#
+# The structural class is broader than the MAX_PATH trigger: any condition
+# under which the harness reports a successful write but the on-disk content
+# diverges from the claimed write should be caught at the tool boundary, not
+# at the next session's read.
+#
+# Type: PostToolUse hook on Edit and Write.
+#
+# Decision rule:
+#
+#   exit 0  — verification passed, or hook does not apply
+#   exit 2  — verification failed; stderr explains why and Claude sees it
+#
+# The hook is intentionally permissive on edge cases (Edit with no content
+# field, ephemeral files, non-regular files) and intentionally strict on the
+# specific divergence shape #61303 names.
+#
+# Configuration env vars:
+#
+#   CC_POST_EDIT_VERIFY_DISABLE=1  — skip the hook entirely
+#   CC_POST_EDIT_VERIFY_QUIET=1    — exit 0 even on detected divergence,
+#                                    but still write the divergence to
+#                                    ~/.claude/receipts/post-edit-divergence.jsonl
+#                                    for audit (the "observe but don't gate"
+#                                    mode useful for first-week deployment)
+
+set -u
+
+# Read tool input from stdin (Claude Code passes a JSON envelope).
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-post-edit-disk-verify-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [post-edit-disk-verify]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[[ -z "$TOOL" ]] && exit 0
+[[ "$TOOL" != "Edit" && "$TOOL" != "Write" ]] && exit 0
+
+# Honor the global disable.
+[[ "${CC_POST_EDIT_VERIFY_DISABLE:-0}" == "1" ]] && exit 0
+
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+[[ -z "$FILE" ]] && exit 0
+
+# Helper: append a divergence record to the receipt log.
+# Defined before first use — the missing-after-write path below calls it.
+_record_divergence() {
+    local file="$1"
+    local tool="$2"
+    local kind="$3"
+    local msg="$4"
+    local dir="${CC_POST_EDIT_VERIFY_RECEIPT_DIR:-$HOME/.claude/receipts}"
+    mkdir -p "$dir" 2>/dev/null || return 0
+    local ts
+    ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    # The missing-after-write path calls this for a file that does not exist,
+    # so guard the redirection to avoid a leaked "No such file" shell error.
+    local file_size=0
+    [ -f "$file" ] && file_size=$(wc -c < "$file" 2>/dev/null || echo 0)
+    printf '{"ts":"%s","tool":"%s","file":"%s","kind":"%s","file_size":%s}\n' \
+        "$ts" "$tool" "$file" "$kind" "$file_size" \
+        >> "$dir/post-edit-divergence.jsonl" 2>/dev/null || true
+}
+
+# File must exist (Write may have created it; Edit always operates on existing).
+[[ ! -e "$FILE" ]] && {
+    # If the tool reported success on a Write to a path that doesn't exist
+    # post-call, that is itself a divergence.
+    if [[ "$TOOL" == "Write" ]]; then
+        msg="post-edit-disk-verify: $TOOL claimed success on $FILE but file does not exist on disk (silent fail-to-persist; see anthropics/claude-code#61303)"
+        _record_divergence "$FILE" "$TOOL" "missing-after-write" "$msg"
+        if [[ "${CC_POST_EDIT_VERIFY_QUIET:-0}" != "1" ]]; then
+            echo "$msg" >&2
+            exit 2
+        fi
+    fi
+    exit 0
+}
+
+# Regular file only (skip symlinks, sockets, devices).
+[[ ! -f "$FILE" ]] && exit 0
+
+# --- Check 1: Write with claimed content vs actual on-disk size ---
+# If a Write claimed N bytes but disk shows much less, that is the
+# strongest single signal of silent fail-to-persist.
+if [[ "$TOOL" == "Write" ]]; then
+    CLAIMED=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // ""' 2>/dev/null)
+    CLAIMED_LEN=${#CLAIMED}
+    ACTUAL_LEN=$(wc -c < "$FILE" 2>/dev/null || echo 0)
+
+    # Only fire when claimed content is non-trivial (avoid empty-write false positives).
+    if [[ "$CLAIMED_LEN" -gt 100 ]]; then
+        # Allow up to 2x slack for CRLF / encoding / final newline differences,
+        # but a >50% shortfall is highly suggestive of fail-to-persist.
+        if [[ "$ACTUAL_LEN" -lt $((CLAIMED_LEN / 2)) ]]; then
+            msg="post-edit-disk-verify: Write to $FILE claimed $CLAIMED_LEN bytes but disk shows $ACTUAL_LEN bytes (>50% shortfall — likely silent fail-to-persist per anthropics/claude-code#61303). Check Windows MAX_PATH (260) on Windows, deep worktrees, or filesystem encoding."
+            _record_divergence "$FILE" "$TOOL" "size-shortfall" "$msg"
+            if [[ "${CC_POST_EDIT_VERIFY_QUIET:-0}" != "1" ]]; then
+                echo "$msg" >&2
+                exit 2
+            fi
+        fi
+    fi
+fi
+
+# --- Check 2: Edit with no diff in git ---
+# If an Edit reported success on a git-tracked file and produces no diff,
+# either the Edit was a no-op (legitimate) or the change failed to persist.
+# The hook treats a "claimed-non-trivial Edit with no diff" as the latter.
+if [[ "$TOOL" == "Edit" ]]; then
+    NEW=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // ""' 2>/dev/null)
+    OLD=$(printf '%s' "$INPUT" | jq -r '.tool_input.old_string // ""' 2>/dev/null)
+
+    # Only check if old_string != new_string (a real claimed change).
+    if [[ -n "$NEW" && "$NEW" != "$OLD" ]]; then
+        # Find git root for the file's directory.
+        FILE_DIR=$(dirname "$FILE")
+        if git -C "$FILE_DIR" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+            # File is in a git repo. Check whether the new_string appears in
+            # the on-disk content. If not, the Edit did not persist.
+            if ! grep -F -q -- "$NEW" "$FILE" 2>/dev/null; then
+                msg="post-edit-disk-verify: Edit on $FILE claimed to insert content that is not found in the on-disk file (silent fail-to-persist per anthropics/claude-code#61303). Either the Edit did not land, or in-tool Read is showing stale-cached content."
+                _record_divergence "$FILE" "$TOOL" "edit-not-in-file" "$msg"
+                if [[ "${CC_POST_EDIT_VERIFY_QUIET:-0}" != "1" ]]; then
+                    echo "$msg" >&2
+                    exit 2
+                fi
+            fi
+        fi
+    fi
+fi
+
+exit 0

package/examples/powershell-remove-item-guard.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# powershell-remove-item-guard.sh — Block PowerShell recursive deletion that traverses junctions
+#
+# Solves: Remove-Item -Recurse -Force on pnpm worktrees traverses NTFS junctions,
+#         permanently deleting user profile folders and source code (#29249).
+#         Also prevents wholesale C: drive deletion via PowerShell (#41708).
+#
+# How it works: Intercepts shell-tool commands containing PowerShell Remove-Item patterns.
+#   Hard blocks refuse with exit 2. Measured 2026-09-19 on 2.1.278, PreToolUse,
+#   against a do-nothing control: a body of {"decision":"block"} does refuse, and
+#   {"decision":"DENY"} and {"decision":"deny"} are both ignored - the hook runs,
+#   prints its reason, exits 0, and the command goes through anyway.
+#   Hard-blocks when -Recurse targets system directories, user profiles, or paths
+#   that could traverse NTFS junctions (node_modules, .pnpm). For -Recurse -Force on
+#   any other absolute drive/UNC path it asks for confirmation instead of blocking —
+#   the case that destroyed ~34 client video files in #64310 (D:\Clientes\...) where
+#   -Force bypassed the Recycle Bin and no confirmation was requested.
+#
+# TRIGGER: PreToolUse
+# MATCHER: "Bash|PowerShell"
+#   Claude Code's PowerShell tool is separate from Bash. Register with
+#   matcher "Bash|PowerShell" so Remove-Item run through the native
+#   PowerShell tool is inspected too — a Bash-only matcher never fires
+#   on the PowerShell tool (#69397). The command is read from
+#   tool_input.command, which both tools populate.
+
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-powershell-remove-item-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [powershell-remove-item-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+[ -z "$COMMAND" ] && exit 0
+
+# Only check commands containing Remove-Item or ri (PowerShell alias)
+echo "$COMMAND" | grep -qiE '(Remove-Item|ri\s|del\s).*-Recurse' || exit 0
+
+# Block if targeting system-critical paths
+if echo "$COMMAND" | grep -qiE 'Remove-Item.*-Recurse.*(/|\\)(Users|Windows|Program Files|System32|C:\\|/mnt/c)'; then
+  echo "BLOCKED: Remove-Item -Recurse targeting system directory. NTFS junctions can traverse to user profiles (#29249)." >&2
+  exit 2
+fi
+
+# Block if targeting node_modules with -Force (junction traversal risk)
+if echo "$COMMAND" | grep -qiE 'Remove-Item.*-Recurse.*-Force.*(node_modules|\.pnpm|worktree)'; then
+  echo "BLOCKED: Remove-Item -Recurse -Force on directory with potential NTFS junctions. Use rimraf or manual junction resolution first (#29249)." >&2
+  exit 2
+fi
+
+# Block if targeting home directory patterns
+if echo "$COMMAND" | grep -qiE 'Remove-Item.*-Recurse.*(\$HOME|\$env:USERPROFILE|~\/|~\\)'; then
+  echo "BLOCKED: Remove-Item -Recurse targeting home directory. Risk of irreversible data loss (#41708)." >&2
+  exit 2
+fi
+
+# Confirm before -Recurse -Force on any other absolute drive/UNC path.
+# The hard blocks above only cover system, junction, and home targets. The case
+# that destroyed ~34 client video files in #64310 was Remove-Item -Recurse -Force on
+# an ordinary data path (D:\Clientes\...) — none of the above matched, -Force bypassed
+# the Recycle Bin, and no confirmation was requested (SSD/TRIM made it unrecoverable).
+# Use "ask" rather than a hard block so routine build/dependency cleanup just gets one
+# confirmation instead of being denied; relative paths (./build) don't trigger at all.
+# VERSION NOTE (measured 2026-08-13 on 2.1.228; this comment used to say the
+# reverse): #77212 reported that under bypassPermissions an "ask" is silently
+# auto-approved, so this confirmation would never appear. It does not reproduce
+# on 2.1.228 — interactively the confirmation appears under both
+# --dangerously-skip-permissions and --permission-mode auto, and non-interactively
+# (claude -p) the call is refused rather than approved. Control: with the hook
+# removed, both permissive modes ran the command unprompted. Older builds may
+# still match the report; check your own --version. What does not change: an
+# "ask" needs someone present to answer it, so in genuinely unattended runs the
+# hard blocks above (exit 2) are what hold.
+if echo "$COMMAND" | grep -qiE '\-Force' \
+   && echo "$COMMAND" | grep -qiE '[A-Za-z]:[\\/]|\\\\[A-Za-z0-9]'; then
+  printf '%s\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"Confirm: Remove-Item -Recurse -Force on an absolute path. -Force bypasses the Recycle Bin and is unrecoverable on SSD/TRIM. Verify the target path is correct (and that any move/copy finished) before deleting (#64310)."}}'
+  exit 0
+fi

package/examples/pr-duplicate-guard.sh

@@ -1,3 +1,16 @@
+#!/bin/bash
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-pr-duplicate-guard-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [pr-duplicate-guard]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
 COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
 [ -z "$COMMAND" ] && exit 0
 echo "$COMMAND" | grep -qE '\bgh\s+pr\s+create\b' || exit 0

package/examples/pre-bash-sed-line-ending-windows.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# pre-bash-sed-line-ending-windows.sh — Block sed -i on Windows/Git Bash
+#
+# Solves: sed -i silently converts CRLF→LF on Windows (#63715).
+#         The conversion is invisible in file content but breaks
+#         tools expecting CRLF (XML manifests, .NET configs, batch
+#         files). Reporter lost 4 hours debugging an XML parser
+#         that failed silently after sed edited it.
+#
+# How it works: PreToolUse hook on Bash tool that detects sed -i
+#   patterns on Windows/Git Bash environments and blocks the call
+#   with a structured suggestion (Edit tool, PowerShell Set-Content,
+#   or manual dos2unix/unix2dos preservation).
+#
+# Linux/macOS environments are skipped — sed -i is safe there.
+#
+# Override: Set CC_ALLOW_SED_LINE_ENDING_CHANGE=1 to bypass when
+#   the LF conversion is intentional (e.g., converting a Windows
+#   file to Unix line endings on purpose).
+#
+# TRIGGER: PreToolUse
+# MATCHER: Bash
+
+set -euo pipefail
+
+# Without jq, the parse below silently yields empty and this hook stops
+# guarding - with no error anywhere. Say so. We deliberately do not exit
+# here: blocking would halt every tool call, and exiting 0 would change
+# the behaviour of guards that do not depend on the parsed value.
+if ! command -v jq >/dev/null 2>&1; then
+  _nojq_warned="/tmp/cc-nojq-warned-pre-bash-sed-line-ending-windows-$PPID"
+  [ -f "$_nojq_warned" ] || {
+    echo "WARNING [pre-bash-sed-line-ending-windows]: jq not found - this hook cannot inspect tool calls and is NOT protecting you. Install jq." >&2
+    : > "$_nojq_warned"
+  }
+fi
+
+INPUT=$(cat)
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")
+[ -z "$CMD" ] && exit 0
+
+# Detect Windows/Git Bash environment. uname -s returns MINGW*/MSYS*/CYGWIN*
+# on Git Bash, MSYS2, and Cygwin respectively. Linux/macOS are skipped because
+# sed -i preserves the original LF line endings there.
+case "$(uname -s 2>/dev/null)" in
+    MINGW*|MSYS*|CYGWIN*)
+        ;;
+    *)
+        exit 0
+        ;;
+esac
+
+# Match `sed -i`, `sed -i ''`, `sed --in-place`. Pattern allows leading flags
+# like `sed -E -i` and ensures -i is a complete flag (not part of -inplace=...).
+if echo "$CMD" | grep -qE '\bsed\b[^|;&]*[[:space:]]-(i\b|-in-place)'; then
+    # Honor explicit opt-in for intentional LF conversion.
+    if [ "${CC_ALLOW_SED_LINE_ENDING_CHANGE:-}" = "1" ]; then
+        echo "[INFO] sed -i allowed via CC_ALLOW_SED_LINE_ENDING_CHANGE=1" >&2
+        exit 0
+    fi
+
+    cat >&2 <<'EOF'
+BLOCKED: sed -i on Windows/Git Bash silently converts CRLF to LF line endings.
+
+This breaks files that expect CRLF (XML manifests, .NET configs, batch files,
+.csproj, .vbproj, .sln, .reg files, etc.) without any warning or error. The
+content looks identical in every visual inspection. Documented at
+anthropics/claude-code#63715 with a 4-hour XML manifest debugging incident.
+
+Use one of these instead:
+
+1. The Edit tool — preserves the file's existing line endings.
+
+2. PowerShell:
+     (Get-Content file) -replace 'pattern','replacement' | Set-Content file
+   Or with -NoNewline to avoid adding a trailing newline.
+
+3. Manual line-ending preservation:
+     dos2unix file && sed -i 's/old/new/g' file && unix2dos file
+
+If you intentionally want to convert this file to LF, bypass with:
+     CC_ALLOW_SED_LINE_ENDING_CHANGE=1 sed -i ...
+EOF
+    exit 2
+fi
+
+exit 0