guardrails: all guards run after a block, and the README does not document the PowerShell over-blocks

[kyle-sexton]

Problem

Session: Windows 11, Claude Code 2.1.278, auto mode, guardrails 0.35.0, PowerShell lane.

• A single blocked command produced two long denial paragraphs, one from block-no-verify and one from block-dangerous-git (guardrails: read-only git inside {} blocked by two guards, with irrelevant commit guidance, Bash-lane advice, and no narrow lever #4235).
• Every PowerShell call in the session went through the full guard chain. The operator's own notes record guard hooks costing about 5x more per PowerShell call on this machine. That figure is not measured by this audit.
• The two false-positive classes in guardrails: & $var script record dir blocked as a file write; block reason names the wrong cause #4234 and guardrails: read-only git inside {} blocked by two guards, with irrelevant commit guidance, Bash-lane advice, and no narrow lever #4235 are not described in the README, so an operator or agent hitting them has no documented rewrite.

Root cause

Traced by reading the installed source; not executed (the audit session's Bash tool was blocked by another plugin, so nothing was profiled and packet integrity is ungradable).

F5. The dispatcher runs every guard after a block.

• run-guards.sh lines 367-393: run_from sources every remaining guard after one exits 2. The code only raises RC (lines 346-347) and never stops early.
• On the PowerShell lane, 8 guards run, and the ps-command.sh library is sourced once per event (lines 126-131). That is 2300+ lines of bash parsed on every PowerShell call.
• RUN_GUARDS_PROFILE=1 (lines 340-345) is the built-in way to measure. Not run.

F6. README gap.

• A search of README.md for & $, "computed", "positional", and "Path+Value" found no coverage of the guardrails: & $var script record dir blocked as a file write; block reason names the wrong cause #4234 class, although it is a deliberate choice pinned in the tests.

Related: #3508, #3623 (hook performance).

Proposed fix

Cheapest first:

1. README, block-hook-bypass section: & $var script arg1 arg2 (a call through a variable followed by two or more positionals with at least one bare word) is blocked as a file write. Rewrite it as & 'C:/literal/path.exe' script args, or put a flag first.
2. README, PowerShell sink section: a foreach { git ... } loop is refused by the git guards regardless of verb. Unroll it into flat git -C <path> ...; statements.
3. Profile the allow path with RUN_GUARDS_PROFILE=1 on a Windows host to confirm or refute the per-call cost.
4. Stop after the first block. This removes duplicate denial paragraphs and saves time on the block path. Weigh it against losing all reasons in one denial.

Acceptance criteria

• README's block-hook-bypass section documents the & $var positional rule and the literal-path rewrite.
• README's PowerShell sink section documents the {} / () git refusal and the unrolled-statement rewrite.
• A command blocked by two guards produces at most one full-length denial paragraph.
• A RUN_GUARDS_PROFILE=1 measurement of the PowerShell allow path on Windows is recorded in the issue or the README.

Found by /plugin-quality:audit (run 20260919T170952Z).

[kyle-sexton]

This was generated by AI during triage.

Decision defaulted: keep run-guards.sh running the full remaining chain after a block (a multi-reason denial is worth more to the operator than the perf save on an already-failing path); ship the two README additions (owned by #4234/#4235 respectively) and a RUN_GUARDS_PROFILE=1 measurement as the uncontroversial part — veto before merge

[kyle-sexton]

This was generated by AI during triage.

Agent Brief

Type: Task
Summary: The guard dispatcher keeps running every remaining guard after one has already blocked a command, and the plugin's documentation does not yet describe two known PowerShell over-block classes or their rewrites.

Current behavior:
Once any guard in the dispatcher's chain exits with a block, the dispatcher still runs every remaining guard in the chain before finishing, rather than stopping at the first block. On the PowerShell lane this means a blocked command can produce multiple long denial paragraphs, one per guard that also objects, and pays the parsing cost of every remaining guard's library on a call that is already refused. Separately, the plugin's documentation does not describe the call-through-a-variable positional-operand block or its literal-path rewrite, nor the read-only-git-inside-grouping block or its unrolled-statement rewrite.

Desired behavior:
Defaulted decision: keep the dispatcher running the full remaining guard chain after a block — a multi-reason denial is judged more valuable to the operator than the time saved on a path that is already failing, so this is not changed. Ship the two documentation additions instead: a section describing the call-through-a-variable positional-operand rule and its literal-path (or flag-first) rewrite, and a section describing the brace/parenthesis grouping git refusal and its unrolled-flat-statement rewrite. Also record one measurement of the PowerShell allow-path cost, taken with the dispatcher's existing profiling mechanism on a Windows host, in the plugin's documentation.
Maintainer-vetoable alternative: stop the guard chain at the first block instead of running the remainder, accepting the loss of every additional reason in one denial in exchange for the time saved on an already-blocked call.

Key interfaces:

• The plugin's README needs a documented section, alongside the call-through-a-variable write-detection section, naming the positional-operand rule and its rewrite (owned by the sibling positional-operand issue).
• The plugin's README needs a documented section, alongside its PowerShell sink coverage, naming the brace/parenthesis grouping git refusal and its unrolled-statement rewrite (owned by the sibling grouping issue).
• The dispatcher's existing profiling mechanism (an environment-variable-gated per-guard timing report) is what should produce the recorded measurement; no new instrumentation is needed.

Acceptance criteria:

• The README's section covering the call-through-a-variable write detection documents the positional-operand rule and its rewrite.
• The README's section covering the PowerShell sink documents the brace/parenthesis git refusal and its unrolled-statement rewrite.
• A recorded measurement (in the issue or the README) shows the per-guard timing of the PowerShell allow path on a Windows host, produced via the dispatcher's existing profiling mechanism.
• The dispatcher's behavior of running every remaining guard after a block is unchanged and has a passing regression test demonstrating a doubly-blocked command still produces both guards' denial text.

Out of scope:

• Stopping the guard chain early after the first block — considered and explicitly rejected as the defaulted decision; only pursue if the maintainer vetoes the default.
• The underlying fixes for the two documented over-block classes themselves — tracked in the sibling positional-operand and grouping issues respectively.