diff --git a/plugins/guardrails/.claude-plugin/plugin.json b/plugins/guardrails/.claude-plugin/plugin.json index bebc2238a15..9d5072c80a0 100644 --- a/plugins/guardrails/.claude-plugin/plugin.json +++ b/plugins/guardrails/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "guardrails", - "version": "0.16.1", + "version": "0.16.2", "description": "Eleven safety guards that block secret/credential writes, hardcoded machine-specific paths, git hook-bypass attempts, irreversible git operations (force-push, reset --hard, worktree-wide checkout/restore discards), Bash file-write workarounds that circumvent Write/Edit hooks, commit subjects and gh pr create titles that violate the repo's tracked team convention (when one is declared in .claude/source-control.md), (advisory) hallucinated CLI flags, (advisory) /plugin:skill references that do not resolve, (advisory) un-throttled Workflow fan-out that risks burst 529s, and (advisory) direct git commit/gh pr create calls bypassing this marketplace's own commit/pull-request skills — each independently toggleable.", "author": { "name": "Melodic Software", diff --git a/plugins/guardrails/CHANGELOG.md b/plugins/guardrails/CHANGELOG.md index 8644401565f..d446d5ff393 100644 --- a/plugins/guardrails/CHANGELOG.md +++ b/plugins/guardrails/CHANGELOG.md @@ -3,6 +3,36 @@ All notable changes to the `guardrails` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.16.2] + +### Fixed + +- **`skill-reference-verify`'s partial-Edit reconstruction now anchors on the hunk's own text, and + only where that text occurs exactly once, instead of on its word tokens (#1453).** The guard's + header comment claimed the token filter held the diff-scope contract — a pre-existing unrelated + reference sharing a recovered line never fires — but a 4+ character word token is short enough to + occur where the edit never landed: a hunk of unrelated prose containing `legacy` grepped back every + `*-legacy` reference in the file, including an untouched broken one, which then passed the + substring gate and fired from an edit that never touched it. Anchors are now the hunk's own lines, + each on disk verbatim by `PostToolUse` time, and an anchor is used only when it **occurs exactly + once**; anything repeated cannot say which copy the edit landed on and is dropped rather than + unioned. Occurrences, not matching lines — two copies on one physical line are a single `grep` hit, + so inserting `legacy` into a line that already carried an untouched `` `/alpha:ghost-legacy` `` + would otherwise still fire. The token filter survives as a second gate on what the locator returns, + never as the locator. `replace_all` is read from the payload and exempted: there every occurrence + is a site this call edited, so requiring uniqueness would silence the guard on a genuine multi-site + break. Costs, stated rather than papered over — an edit landing in text that repeats verbatim + elsewhere goes unreported, and under `replace_all` a line that independently read the same is kept + even though the edit never touched it. Both are the right side of the trade for a detect-then-judge + guard, degraded far worse by speaking wrongly than by staying quiet, and reconstruction stays a + best effort rather than a proof. Four regression tests cover the shared-token, bare-token, + same-line-double-occurrence, and `replace_all` shapes; the existing partial-replacement + true-positive cases keep passing, with the composite (complete-reference-plus-bare-word) case + reshaped onto a realistic multi-line hunk since a single Edit's `new_string` cannot land in two + disjoint places on disk. `stale-path-verify` and `cli-flag-verify` carry the same reconstruction + shape and are not fixed here; the guard-wide false-positive class they belong to is tracked on + `#547`, and `#1432` (`65b4f67c`) is the sibling fix this ports from. + ## [0.16.1] ### Fixed diff --git a/plugins/guardrails/hooks/skill-reference-verify.sh b/plugins/guardrails/hooks/skill-reference-verify.sh index b9ab9c7842c..d4a013612f4 100755 --- a/plugins/guardrails/hooks/skill-reference-verify.sh +++ b/plugins/guardrails/hooks/skill-reference-verify.sh @@ -66,8 +66,18 @@ esac # Diff-scope: verify only the content THIS tool call wrote, never re-read the # whole file from disk. TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null | tr -d '\r') +# Edit's `replace_all` (documented at +# https://code.claude.com/docs/en/tools-reference — Edit requires `old_string` to +# occur exactly once, and `replace_all: true` is how Claude edits every occurrence +# instead). Reconstruction needs it: with `replace_all` the same `new_string` +# lands in several places on purpose, so several matches are the edit's own +# footprint rather than an ambiguity. Absent or false on every ordinary Edit. +REPLACE_ALL=false case "$TOOL" in -Edit) SCAN_CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // empty' 2>/dev/null | tr -d '\r') ;; +Edit) + SCAN_CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // empty' 2>/dev/null | tr -d '\r') + REPLACE_ALL=$(printf '%s' "$INPUT" | jq -r '(.tool_input.replace_all // false) | tostring' 2>/dev/null | tr -d '\r') + ;; Write) SCAN_CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null | tr -d '\r') ;; *) exit 0 ;; esac @@ -147,41 +157,93 @@ emit_refs() { sed -nE 's|^(/[a-z][a-z0-9-]*:[a-z][a-z0-9-]*)([[:space:]].*)?$|\1|p' } -# Partial-replacement context reconstruction (Edit only), mirroring -# cli-flag-verify's reconstruct_partial_edit. +# Partial-replacement context reconstruction (Edit only). The same shape lives in +# stale-path-verify and cli-flag-verify; stale-path-verify was fixed for this +# defect class by 65b4f67c (#1432) and this one goes one step further with the +# uniqueness requirement below, so the three are not yet identical. # # An Edit may replace an arbitrary substring: swapping `setup` for `ghost` inside # an existing `/alpha:setup` leaves `/alpha:ghost` on disk, but the hunk is the # bare word `ghost` and carries no command for emit_refs to find, so a # newly-broken reference would be silently missed. # -# Recover bounded context: the edit is already applied by PostToolUse time, so pull -# from disk only the lines carrying one of the hunk's word tokens, scan those, and -# keep only references whose plugin or skill segment appears in the hunk. That -# token filter is what preserves the diff-scope contract — a pre-existing unrelated -# reference sharing one of those lines never fires. The anchor is the token, not -# the line, since a bare-word hunk carries no positional information. +# Recover bounded context: the edit is already applied by PostToolUse time, so +# pull from disk only the lines the hunk's OWN TEXT UNIQUELY locates, scan those, +# and keep only references whose plugin or skill segment contains one of the +# hunk's word tokens. Two gates, and the first is where diff-scope actually lives: +# +# 1. LOCATE by the hunk's own lines, and only where a line OCCURS exactly once +# in the file. Every line of new_string is on disk verbatim, so a unique +# occurrence IS where the edit landed. Anything repeated cannot say which +# copy that was, so it is dropped rather than unioned. Occurrences, not +# matching lines — two copies on one physical line are a single grep hit and +# would otherwise slip through. Exception: under `replace_all` every +# occurrence is a place this call edited, so all are kept. +# 2. FILTER the references found there by the hunk's word tokens. +# +# Gate 2 alone is not sufficient and was never the guarantee: a token short +# enough to occur in unrelated prose is also short enough to be a substring of an +# untouched skill segment, so it would pass the reference through. Uniqueness at +# gate 1 is what keeps the guard inside the diff. +# +# What this does NOT claim: the `replace_all` branch keeps every occurrence, +# including one that pre-existed the edit and merely happens to read the same — +# nothing in the payload separates those. Reconstruction is a best effort under an +# advisory guard, not a proof that every reported line was written by this call. reconstruct_partial_edit() { [[ "$TOOL" == "Edit" && -f "$FILE" ]] || return 0 - # Anchor tokens come from the hunk with any COMPLETE reference removed first. - # A complete reference is already handled by the direct scan, and leaving it in - # would contribute its own plugin name as an anchor — `alpha` then matches every - # reference to that plugin, including untouched ones on neighbouring lines, which - # breaks diff-scope. What remains is the genuinely bare edited text. + # The token filter reads the hunk with any COMPLETE reference removed first. A + # complete reference is already handled by the direct scan, and leaving it in + # would contribute its own plugin name as a token — `alpha` then passes every + # reference to that plugin. What remains is the genuinely bare edited text. local residue residue=$(printf '%s' "$SCAN_CONTENT" | sed -E 's#/[a-z][a-z0-9-]*:[a-z][a-z0-9-]*##g') - # Minimum anchor length. A substring match on a very short token matches almost + # Minimum token length. A substring match on a very short token matches almost # any segment — stripping a reference out of `Run `/alpha:x` now.` leaves the - # fragment `un`, which substring-matches `untouched-ghost` on an untouched line - # and breaks diff-scope. 4 characters is the shortest command segment worth - # anchoring on; below that the token carries no locating power. + # fragment `un`, which substring-matches `untouched-ghost`. 4 characters is the + # shortest command segment worth filtering on; below that the token carries no + # filtering power. local -a toks=() mapfile -t toks < <(printf '%s' "$residue" | grep -oE '[a-z][a-z0-9-]{3,}' 2>/dev/null | sort -u) ((${#toks[@]})) || return 0 - local tok lines ctx="" - for tok in "${toks[@]}"; do - lines=$(grep -F -- "$tok" "$FILE" 2>/dev/null) - [[ -n "$lines" ]] && ctx+="$lines"$'\n' + # Lines are located by the hunk's own lines, never by its tokens. Every line of + # new_string is on disk verbatim, so it matches the line the edit landed in; a + # token, being shorter, also matches lines the edit never touched — a bare + # `legacy` in unrelated prose pulls in every `/alpha:*-legacy` reference on any + # line, and an untouched broken one among them would fire. + local -a anchors=() + mapfile -t anchors < <(printf '%s' "$SCAN_CONTENT" | grep -vE '^[[:space:]]*$' 2>/dev/null) + ((${#anchors[@]})) || return 0 + # An anchor is used ONLY when it OCCURS exactly once in the file — occurrences, + # not matching lines. Counting lines is not enough: two occurrences on one + # physical line are one grep hit, and that is a real shape — inserting `legacy` + # into a line that already carries an untouched `` `/alpha:ghost-legacy` `` + # leaves the anchor twice on that line, and reporting the reference would be an + # advisory about text this call never wrote. Occurrence uniqueness subsumes line + # uniqueness (one occurrence can only be on one line), so it is the only gate. + # + # A non-unique anchor cannot say WHICH occurrence the edit landed on, so it is + # dropped rather than unioned. Cost: a missed advisory when an edit lands in + # text that repeats verbatim elsewhere in the file. For a detect-then-judge + # guard that is the right side of the trade — it is degraded far worse by being + # wrong when it speaks than by staying quiet. + local anchor occ ctx="" + local -a hits=() + for anchor in "${anchors[@]}"; do + mapfile -t hits < <(grep -F -- "$anchor" "$FILE" 2>/dev/null) + ((${#hits[@]})) || continue + # `replace_all` is the one case where repetition is expected rather than + # ambiguous: every occurrence is a place THIS call edited, so all of them are + # in scope and uniqueness must not be required. Accepted narrowing — a line + # that independently contained `new_string` and was never touched is kept too, + # since nothing in the payload distinguishes it from an edited one. + if [[ "$REPLACE_ALL" == "true" ]]; then + for occ in "${hits[@]}"; do ctx+="$occ"$'\n'; done + continue + fi + occ=$(grep -o -F -- "$anchor" "$FILE" 2>/dev/null | grep -c .) + ((occ == 1)) || continue + ctx+="${hits[0]}"$'\n' done [[ -n "$ctx" ]] || return 0 local saved="$SCAN_CONTENT" diff --git a/plugins/guardrails/hooks/skill-reference-verify.test.sh b/plugins/guardrails/hooks/skill-reference-verify.test.sh index 7e0a195c403..e3e40892342 100755 --- a/plugins/guardrails/hooks/skill-reference-verify.test.sh +++ b/plugins/guardrails/hooks/skill-reference-verify.test.sh @@ -245,7 +245,7 @@ assert_contains "CHANGELOG-in-name but not a CHANGELOG → still adjudicated" "$ # PARTIAL-EDIT RECONSTRUCTION. An Edit may replace an arbitrary substring, so a # hunk can be a bare word with no command in it. The edit is already applied by # PostToolUse time, so the containing reference is recovered from disk, anchored to -# the hunk's tokens. +# the hunk's own text. PARTIAL="$REPO/partial.md" printf 'Run `/alpha:ghost-partial` to begin.\n' >"$PARTIAL" OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(edit_json "$PARTIAL" 'ghost-partial')" 2>&1) @@ -264,6 +264,69 @@ assert_contains "reconstruction reports the edited reference" "$OUT" \ assert_absent "reconstruction does NOT report an untouched neighbour" "$OUT" \ "untouched-ghost" +# Diff-scope again, against the harder shape from #1453: the hunk is unrelated +# prose that merely SHARES A WORD TOKEN with an untouched broken reference +# elsewhere in the same file. Anchoring on the token alone (the pre-fix behavior) +# pulls that reference in — `legacy` occurs in both `ghost-legacy` and the prose — +# so the anchor has to be the hunk's own line, which occurs verbatim in exactly +# the line the edit landed in. Verified to fail against the pre-fix guard (which +# fired `UNRESOLVED_SKILL: /alpha:ghost-legacy`), the same shape #1432 proved for +# stale-path-verify's sibling defect. +SEGSHARE="$REPO/segshare.md" +printf 'Stale `/alpha:ghost-legacy` here.\nThe legacy naming convention was updated today.\n' \ + >"$SEGSHARE" +OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" \ + <<<"$(edit_json "$SEGSHARE" 'The legacy naming convention was updated today.')" 2>&1) +RC=$? +assert_exit "prose hunk sharing a word token → exit 0" 0 "$RC" +assert_silent "hunk sharing only a token does not drag in an untouched broken reference" "$OUT" + +# The DEGENERATE shape of the same defect: the hunk IS the shared word, so its +# anchor is no longer than the token and matches BOTH the edited prose line and +# the untouched reference. Anchoring on lines cannot separate them here — only +# requiring the anchor to locate exactly ONE line does. An anchor matching several +# cannot say which the edit landed in, so it is dropped rather than unioned; +# unioning fired `UNRESOLVED_SKILL: /alpha:ghost-legacy` from an edit that never +# touched it, since `legacy` is also a substring of that skill segment and so +# clears the token filter. Trading this for a missed advisory when an edit lands +# in a verbatim-duplicated line is deliberate — an advisory guard is degraded +# worse by speaking wrongly than by staying quiet. +OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(edit_json "$SEGSHARE" 'legacy')" 2>&1) +RC=$? +assert_exit "bare-token hunk matching several lines → exit 0" 0 "$RC" +assert_silent "ambiguous anchor is dropped, not unioned" "$OUT" + +# Same defect one level finer: both occurrences of the anchor are on ONE physical +# line, so `grep` reports a single matching line and a line-count uniqueness check +# sees nothing wrong. Inserting `legacy` into a line that already carried an +# untouched reference must not report that reference — this call never wrote it. +# The gate therefore counts OCCURRENCES, which subsumes counting lines. +SAMELINE="$REPO/sameline.md" +printf 'Run `/alpha:ghost-sameline` and note the sameline convention.\n' >"$SAMELINE" +OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(edit_json "$SAMELINE" 'sameline')" 2>&1) +RC=$? +assert_exit "anchor occurring twice on one line → exit 0" 0 "$RC" +assert_silent "two occurrences on a single line are ambiguous, not unique" "$OUT" + +# `replace_all` is the one shape where repetition is EXPECTED, not ambiguous: +# every occurrence is a place this call edited, so uniqueness must not be +# required or the guard goes silent on a genuine multi-site break. Built inline +# rather than through edit_json — that helper is shared across guard suites and +# gated by hook-utils-sync, so this suite's payload variant stays local to it. +replall_json() { + MSYS_NO_PATHCONV=1 jq -n --arg fp "$1" --arg s "$2" \ + '{tool_name:"Edit",tool_input:{file_path:$fp,new_string:$s,replace_all:true}}' +} +REPLALL="$REPO/replall.md" +printf 'First `/alpha:ghost-one` here.\nSecond `/alpha:ghost-two` there.\n' >"$REPLALL" +OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(replall_json "$REPLALL" 'ghost')" 2>&1) +RC=$? +assert_exit "replace_all Edit → exit 0" 0 "$RC" +assert_contains "replace_all → first edited reference reported" "$OUT" \ + "UNRESOLVED_SKILL: /alpha:ghost-one" +assert_contains "replace_all → second edited reference reported" "$OUT" \ + "UNRESOLVED_SKILL: /alpha:ghost-two" + # A hunk that already carries a full command is scanned directly. OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(edit_json "$PARTIAL2" 'Run `/alpha:ghost-three` now.')" 2>&1) assert_contains "full-command hunk → scanned directly" "$OUT" \ @@ -282,9 +345,14 @@ assert_contains "substring Edit inside a segment → recovered" "$OUT" \ # A hunk carrying BOTH a complete reference and a substring change to another must # report both — gating reconstruction on an empty scan would miss the partial half. +# The two live on separate lines of the SAME hunk: a single Edit's new_string can +# span several lines of a replaced passage, and each line lands on disk verbatim, +# so line-anchoring finds the bare-word line while the complete reference on the +# other line is already caught by the direct scan of the whole hunk. MIXED="$REPO/mixed.md" printf 'First `/alpha:ghost-mixed` here.\nSecond `/alpha:audit` is fine.\n' >"$MIXED" -OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(edit_json "$MIXED" 'ghost-mixed and `/alpha:ghost-direct`')" 2>&1) +OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" \ + <<<"$(edit_json "$MIXED" $'ghost-mixed\nAlso now cites `/alpha:ghost-direct`.')" 2>&1) assert_contains "mixed hunk → direct reference reported" "$OUT" \ "UNRESOLVED_SKILL: /alpha:ghost-direct" assert_contains "mixed hunk → reconstructed reference also reported" "$OUT" \