Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion plugins/guardrails/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
30 changes: 30 additions & 0 deletions plugins/guardrails/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
106 changes: 84 additions & 22 deletions plugins/guardrails/hooks/skill-reference-verify.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved
((${#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'
Comment thread
kyle-sexton marked this conversation as resolved.
Resolved
done
[[ -n "$ctx" ]] || return 0
local saved="$SCAN_CONTENT"
Expand Down
72 changes: 70 additions & 2 deletions plugins/guardrails/hooks/skill-reference-verify.test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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" \
Expand All @@ -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" \
Expand Down