guardrails: PowerShell commands with no git commit are blocked fail-closed on {} or () grouping

[kyle-sexton]

Reproduced first-hand, twice, in one session

block-noncanonical-commit.sh blocks PowerShell commands that contain no git commit at all,
when the command carries {} or () grouping. Both of these were blocked while driving PR merges:

BLOCKED: this PowerShell git command cannot be parsed with confidence — blocked (fail-closed).
Remove the obfuscating construct (backtick, --%, subexpression, or {}/() grouping).

The commands that tripped it:

git fetch origin --prune 2>&1 | Select-Object -Last 5; git rev-list --left-right --count A...B; git merge-base A B | ForEach-Object { git log --oneline -1 $_ }

$r = ... ; foreach ($t in $p.reviewThreads.nodes) { if (-not $t.isResolved) { ... } }

Neither contains git commit. The second contains no git subcommand the guard cares about at all —
it is a GraphQL result loop that happens to sit in the same pipeline as a git status.

The same shape was independently reported by the L5 lane of the context-engineering pass against
block-no-verify.sh as well, on & 'script.ps1' and Get-ChildItem | ForEach-Object {...}.

Why this is worth fixing rather than living with

The guard is fail-closed by design, which is right for a commit guard. But the fail-closed
branch currently triggers on the presence of a grouping construct anywhere in the command line,
rather than on an unparseable git commit invocation. In PowerShell, {} and () are ordinary
control flow and subexpression syntax — foreach, if, ForEach-Object, $(...) — so the guard
denies a large fraction of legitimate non-commit PowerShell.

The cost is not only friction. A guard that blocks routine commands trains its users to reach for
the other shell to get work done, which is exactly the bypass the guard exists to prevent.

Suggested direction

Gate the fail-closed branch on the command actually containing a git commit invocation
(git commit, git -C … commit, an alias resolving to one) before applying the
unparseable-construct test. A command with no commit in it is out of the guard's stated scope and
should exit 0 regardless of its syntax.

Both guards need the same treatment: block-noncanonical-commit.sh and block-no-verify.sh.

Related

Refs #1403 — the guardrails performance work; PR #1385 explicitly did not address this false
positive, and the fresh-context verification recorded it as "ignored, neither fixed nor worsened".

[kyle-sexton]

This was generated by AI during triage.

Verified against origin/main source directly. Read
plugins/guardrails/lib/powershell/ps-command.sh::ps::classify_git_command (lines 331-359): when
ps::has_special_constructs trips on any {}/()/backtick/--% anywhere in the command, the
function falls through to ps::might_invoke_git "$PS_BLANKED" && return 2. ps::might_invoke_git
(lines 190-207) is a bare substring/regex match for the literal word git anywhere in the command
— it has no concept of git commit specifically. Both block-noncanonical-commit.sh (line 358)
and block-no-verify.sh (line 231) call this same shared classifier and both treat return code 2
as an unconditional block. The diagnosis is exactly right: the fail-closed branch keys on
"contains a grouping construct AND mentions git anywhere," not "contains an unparseable git commit
invocation." A git fetch/git rev-list/git status pipeline with an unrelated foreach {} or
ForEach-Object {} block gets blocked identically to an actual unparseable commit.

Agent Brief

Type: Bug
Summary: ps::classify_git_command's fail-closed branch blocks any PowerShell command that
mixes a grouping construct with the word git anywhere, instead of scoping the block to
commands that actually invoke git commit. Both block-noncanonical-commit.sh and
block-no-verify.sh share this classifier and inherit the false positive.

Current behavior:
ps::might_invoke_git matches the bare word git (or iex/invoke-expression, or a
dot-source/call-operator/start-process-family launcher pattern) anywhere in an unparseable
command and blocks unconditionally. Non-commit git subcommands (fetch, rev-list, merge-base,
log, status, …) sharing a pipeline with ordinary PowerShell control-flow syntax (foreach {},
if () {}, ForEach-Object {}, $(...)) get blocked even though neither guard's stated scope is
about non-commit git commands at all.

Desired behavior:
The fail-closed branch triggers only when the unparseable command plausibly contains a git commit invocation (git commit, git -C … commit, an alias resolving to one) — not any mention
of git. A command with a grouping construct but no commit invocation returns the existing
"non-commit, allow" code path (currently return 1) instead of the block path (return 2).
block-no-verify.sh's own no-verify scope (commit and push) needs the equivalent tightening for
its own subcommand set, since it shares the same classifier — check whether its return-2 path
needs to stay broader (it also guards git push --no-verify) or can use the same narrowed probe.

Acceptance criteria:

• A PowerShell command with grouping syntax ({}/()) and a non-commit git subcommand
  (git fetch, git rev-list, git merge-base, git status, git log, …) and no git commit/git push invocation is no longer blocked by either guard.
• A PowerShell command with grouping syntax that genuinely obscures a git commit invocation
  (the guard's actual stated scope) is still blocked, unchanged.
• block-no-verify.sh's coverage of both git commit --no-verify and git push --no-verify
  is preserved — the narrowing does not silently drop push coverage.
• Existing guardrails contract-test suites (Bash and PowerShell) still pass, and new tests
  cover both examples from the issue body (a git fetch/rev-list/merge-base pipeline with
  a ForEach-Object {}, and a GraphQL-result foreach {}/if () {} loop sharing a pipeline
  with an unrelated git status).

Out of scope:

• Any change to what counts as "unparseable" (backtick, --%, subexpression, {}/() grouping)
  — this brief only narrows which unparseable commands trigger the block, not the unparseability
  test itself.
• The companion finding from the same issue about & 'script.ps1' and bare
  Get-ChildItem | ForEach-Object {...} reported independently by another lane's L5 pass — same
  root cause, already covered by the acceptance criteria above, not a separate design question.

---

Work-loop admission note. Security-surface: both guards are commit-integrity fail-closed
hooks, so per the admission gate's hard-gate table this item runs at the frontier capability tier
whenever dispatched, regardless of its C3 classification. Blast radius is bounded (one shared
library function plus two call sites), the change is behavior-narrowing (strictly reduces false
positives without touching the guards' actual protected scope), and it is verifiable via the
existing contract-test suites — C3 scoped-change shaped. No prior ratification on this item and
this lane's durable state has not recorded first_drain_complete: true, so per the first-drain
rule this is queued, not dispatched, pending an operator ratification reply.

[kyle-sexton]

This was generated by AI, delegated directly by the repository operator to resolve this blocker.

NOT RATIFIED — the proposed narrowing is a live fail-open

The bug report is real and reproduces. The suggested fix direction is not safe and must be
reworked before this item is dispatched. Detail below.

What I checked

Re-verified against current origin/main, reading ps::classify_git_command,
ps::might_invoke_git, ps::has_special_constructs, ps::has_dynamic_invocation, and
ps::has_launcher in plugins/guardrails/lib/powershell/ps-command.sh in full, then executing the
real library against adversarial inputs rather than reasoning about it.

Finding 1 — the OR-chain members do not independently block

The ratification request asked specifically whether ps::has_dynamic_invocation and
ps::has_launcher already catch alias/iex/launcher obfuscation independently, which would make
narrowing ps::might_invoke_git safe. They do not. At lines 338–348 they are entry conditions
of the if that routes into the sink; the sole block decision is one line:

ps::might_invoke_git "$PS_BLANKED" && return 2
return 1

Every trigger funnels through that single probe. Narrowing it weakens all four entry paths at once,
not just the grouping path.

Finding 2 — the brief names two call sites; there are four

ps::classify_git_command is called by block-convention-violation.sh:375,
block-dangerous-git.sh:977, block-no-verify.sh:231, and block-noncanonical-commit.sh:361.

block-dangerous-git.sh is the one that breaks this fix. It owns reset --hard, clean -fd,
checkout, and restore, and its own comment at lines 972–976 states outright that it depends on
the sink being git-presence-based precisely so that git --% reset --hard cannot slip through. A
commit-scoped narrowing is not a false-positive removal for that consumer — it is a direct
fail-open.

Finding 3 — the narrowing is the #740/#903 class the file's own doctrine forbids

Lines 43–51 of ps-command.sh state the rule explicitly: the allow decision must not be a
negative commit/push shape match on the mangled scan, because the very construct that defeats
the tokenizer also mangles that scan, so a negative match is not evidence of safety.
"Gate the fail-closed branch on the command actually containing a git commit invocation" is exactly
that forbidden negative-absence test.

The bypasses this would open

Each of the following is classified rc=2 (blocked) by current origin/main, and each carries no
literal commit token anywhere — so a commit-token-gated probe returns rc=1 (allow) and the
guard exits 0. Verified by executing the library, not by inspection:

Command	Guard defeated
git ('com'+'mit') -m 'x' --no-verify	block-no-verify, block-noncanonical-commit
git push --force ( $b )	block-no-verify push coverage
iex $c (where $c holds a commit)	all four
git --% reset --hard	block-dangerous-git
& { git clean -fd }	block-dangerous-git
git checkout -- ( $f )	block-dangerous-git
git reset --hard HEAD~1; ForEach-Object { $_ }	block-dangerous-git

The first row is the decisive one: a working git commit --no-verify reaching the repository through
the guard whose entire purpose is to stop it, via nothing more exotic than PowerShell string
concatenation in the subcommand position.

Consequently acceptance criterion 1 as written is unsafe. It asks that non-commit git
subcommands stop being blocked, with no read-only restriction; satisfying it literally produces the
reset --hard hole. AC-3 likewise needs extending beyond block-no-verify's push coverage to
block-dangerous-git's destructive set.

Separately, and not a hole introduced by this analysis: git $sub --no-verify -m x already
classifies rc=0 today (it carries no unparsable construct at all) and takes the Bash-parser path.
That is the documented variable-command-word residual at lines 62–66, unchanged either way.

Corrected direction

Invert the test. Do not ask "is commit absent?" (negative, mangle-vulnerable). Ask "is every git
invocation here provably a literal read-only subcommand?" (positive, fail-closed on anything
unproven). Default stays block; the carve-out must prove its own safety.

A command earns the allow only when both hold:

1. Grouping (()/{}) was the only sink trigger — no backtick, no --%, no unbalanced
   here-string, no ps::has_dynamic_invocation, no ps::has_launcher. Anything that can compute or
   hide a command word keeps the hard block. I confirmed this holds for both reproductions in the
   issue body: each trips grouping alone, and ps::has_dynamic_invocation does not fire on
   $p.reviewThreads.nodes (the . there is preceded by an alphanumeric, outside the function's
   separator boundary class).
2. Every git token is followed by a literal subcommand on a read-only allowlist. A subcommand
   position holding a variable, a subexpression, or a concatenation is not literal and fails closed —
   which is what keeps git ('com'+'mit') and git $sub blocked.

I prototyped this against the library in a scratch harness: all three reported false positives flip
to allow, and all thirteen adversarial strings above stay blocked. That is evidence the direction is
sound, not an implementation to copy. The design surface the corrected brief must still specify:

• The allowlist itself, validated against each of the four consumers' protected scopes — not
  asserted once. Under-counting the consumers is precisely how the current brief went wrong.
• config must not be on it. git config writes, and it can set an alias — the same injection
  vector as the git -c alias.z=commit z form.
• fetch needs a per-consumer ruling. It mutates remote-tracking refs; likely fine for all four,
  but that is a ruling to make, not to assume.
• Skip and hard-fail rules for global options: which are skippable (--no-pager, -C <literal>),
  and git -c failing closed outright.

Decision

Not ratified. needs-human retained; agent-ready not applied. The blocker to clear is the fix
direction itself: AC-1 reworded from "non-commit git subcommand" to "provably read-only git
subcommand", AC-3 extended to block-dangerous-git's destructive set, the call-site count corrected
from two to four, and the allowlist ruled on per consumer. With those settled, the item is
dispatchable at the frontier tier as the admission note already requires.

[kyle-sexton]

This was generated by AI. Triage lane claim for a gate audit of the first-drain C3 ratification marker on this item. Read-only until a decision is posted; no labels are changed under this claim unless a ratification is recorded.

[kyle-sexton]

This was generated by AI. Gate audit complete: a blind 3-seat panel (fresh Claude reviewer, OpenAI Codex, this agent) unanimously classified the remediation as C4 (structural/contract-level), not autonomous-PR-eligible, high confidence — corroborating the existing "NOT RATIFIED" decision already on this item. No new decision-ready summary posted (one already exists) and no labels changed. Releasing the lane claim.

[kyle-sexton]

This is an automated triage comment from an AI agent (autonomous triage lane, instance MELO-LAP-001-triage-20260729T123842Z). No labels changed — this item stays on the human floor.

Gate audit: gate CONFIRMED legitimate. Decision-ready summary below.

This item was re-audited this cycle by a three-seat panel (a fresh-context Claude reviewer and OpenAI Codex gpt-5.6-sol, both given only the title and body with all prior rationale withheld, plus this agent's own read). The panel did not overturn the existing hold, and the prior NOT RATIFIED analysis stands on its own evidence: the originally proposed narrowing opens a live fail-open, most decisively git ('com'+'mit') -m 'x' --no-verify reaching the repo through the guard built to stop it.

Posting this because the item was carrying a correct hold with no single-glance decision surface. Nothing here is new analysis — it is the existing conclusion made actionable.

What is actually blocked

Not the bug report. The defect is real and reproduces. The blocker is the fix direction: acceptance criterion 1 as written ("non-commit git subcommands stop being blocked") is unsafe, because satisfying it literally also un-blocks git reset --hard and git clean -fd.

The decision you are being asked to make

Approve the corrected fix direction — invert the test from the negative "is commit absent?" to the positive "is every git invocation provably a literal read-only subcommand?", default staying block — and approve the four scope corrections that come with it.

Options

• RECOMMENDED — approve the corrected direction and dispatch at frontier tier. Adopt the inverted test, and require the dispatch to: reword AC-1 to "provably read-only git subcommand"; extend AC-3 beyond block-no-verify's push coverage to block-dangerous-git's destructive set; correct the call-site count from two to four consumers; and rule the read-only allowlist per consumer, with config excluded outright (it writes, and can set an alias — the same injection vector as git -c alias.z=commit z) and fetch given an explicit per-consumer ruling rather than an assumption. This is the only option that fixes the reported friction without trading it for a worse hole, and the direction already has evidence behind it: prototyped against the real library, all three reported false positives flip to allow while all thirteen adversarial strings stay blocked.
• Narrow to the two reproductions only. Special-case just the grouping-alone shapes from the issue body and leave the general classifier untouched. Smaller blast radius and faster to land, but leaves the same class of false positive live for every shape not yet reported, and the friction that drives users to the other shell persists.
• Accept the friction; close as working-as-intended. Zero risk of a new hole. Costs the ongoing false-positive rate and the bypass pressure the issue body documents — users reaching for a different shell to get routine work done is itself a guard-integrity problem.

Why this stays on the human floor either way

Whichever option is chosen, the implementing change is a security-surface change to a fail-closed guard, and the allowlist is a risk-appetite ruling across four consumers rather than an engineering detail. The admission note already routes it to the frontier tier. This lane has no authority to approve a guard relaxation, and did not.

[kyle-sexton]

Independent agent audit of guardrails 0.18.1 reproduced this four times in one session and traced the mechanism. Adding the material rather than opening a duplicate. The headline addition: the guard blocks its own prescribed remedy, and it makes safe command shapes harder to express than unsafe ones.

The trigger is not what it looks like

hooks/block-noncanonical-commit.sh:767 delegates the whole PowerShell decision to ps::classify_git_command (lib/powershell/ps-command.sh:331). The commit-specific logic in check_segment is never reached on the blocking path — exit 2 happens at line 771, before hook::bash_parse_segments is called at 798. The subcommand is never consulted, so commit has nothing to do with it.

It blocks when both hold:

• A — not faithfully Bash-tokenizable: an unbalanced here-string, ps::has_special_constructs on quote-stripped text (a backtick, --%, or any of (, ), {, }), ps::has_dynamic_invocation, or ps::has_launcher.
• B — ps::might_invoke_git cannot prove the command git-free. Deliberately coarse, and run quote-intact, so a quoted git still counts.

One correction worth recording, because it is the natural first guess: the literal substring .git is not a trigger. The regex is (^|[^[:alnum:]_.])git([.]exe)?([^[:alnum:]_]|$) and the leading boundary class excludes ., so .git never matches. Verified: Test-Path (Join-Path $d '.git') is allowed.

What actually fired in the observed cases was the bare word git inside a double-quoted display string — e.g. "=== $_ (git: …)" — and ps::has_dynamic_invocation on & '<path>.ps1', which needs no bracket at all. A Get-ChildItem with @{n=…;e={…}} calculated properties passed, which shows brace usage alone is not the discriminator.

Net scope: on the PowerShell tool, a commit-canonicalization guard refuses any command carrying a paren, brace, backtick, --%, launcher, or & '…' that mentions the word "git" anywhere, including in human-readable output text. In an agent session that inspects repositories, "git" in a label is routine.

The guard refuses its own canonical form

This is the part that makes it self-defeating rather than merely broad:

• @'…'@ | & 'C:\Program Files\Git\cmd\git.exe' commit -F - — rc=2. Invoking a space-containing executable path through the call operator is the correct PowerShell idiom; ps::has_dynamic_invocation refuses it.
• if ((git status --porcelain).Length -eq 0) { @'…'@ | git commit -F - } else { Write-Error … } — rc=2. A canonical commit behind a clean-tree precondition.

A guard whose refusal set includes its own prescribed remedy cannot be satisfied by following its own message.

For scope discipline: a repo path containing parentheses is fine. git -C 'C:\Program Files (x86)\repo' commit -F - passes in both quoted spellings, because ps::blank_quoted_spans strips the span before ps::has_special_constructs runs.

Safe patterns are harder to express than unsafe ones

Controlled A/B — in each pair the only difference is the presence of a precondition:

• if ((git status --porcelain).Length -eq 0) { Remove-Item -Recurse -Force C:\build } else { Write-Error 'dirty' } — BLOCKED
• Remove-Item -Recurse -Force C:\build — allowed

and

• $o = Get-Process -Id 9552 …; if ($o) { Write-Error 'owner alive' } else { & 'C:\tools\recycle-one.ps1' -Path 'C:\x' } — BLOCKED
• C:\tools\recycle-one.ps1 -Path C:\x — allowed

if/else requires braces (predicate A) and checking repository state necessarily names git (predicate B), so expressing a precondition is what triggers the block. In the real session the workaround was to split the liveness check away from the deletion it guarded — decomposing an atomic check-then-act, which is strictly worse than the command that was refused.

The guard's stated purpose is preventing a mangled commit message. Here it degraded deletion safety.

The message misinforms, and its audience is the agent

ps::print_unparsable_block_message (ps-command.sh:370) emits, unconditionally: BLOCKED: this PowerShell git command cannot be parsed with confidence.

• "git command" is an assertion the code has not established. ps::might_invoke_git answers "I cannot prove this is not git" — the negation of the claim. Two of the observed blocks invoked no git binary at all; a fourth invoked none and contained no git substring anywhere.
• "Remove the obfuscating construct" names ()/{} as obfuscation. In PowerShell they are ordinary control flow and property access, and there is no non-obfuscated rewrite of an if/else.
• The remedy and its fallback are both closed for the commands actually being blocked. A here-string piped to git commit -F - is meaningless for a Test-Path pipeline, and "run the commit via the Bash tool" cannot execute Get-Process, Join-Path, or ForEach-Object at all.

And per the hooks reference, on a PreToolUse deny the reason is shown to Claude, not to the user (permissionDecisionReason for deny is "shown to Claude"; exit-2 stderr is "fed back to Claude"; the per-event table marks non-blocking events as user-facing and PreToolUse is not among them). A human sees it only under claude --debug. So the false premise is delivered to the actor deciding what to do next.

That produced a real correctness regression, not a style compromise: to get past & '<path>.ps1' the call operator and quoting were dropped for a bare path. Verified — & 'x.ps1' blocks, & x.ps1 passes — and a bare unquoted path breaks for any path containing a space, which on Windows is most of them. The guard rewards the fragile spelling.

No discoverable escape hatch

• block_noncanonical_commit_allow=message-flag is structurally unreachable on this path: allowed() is called at line 741 inside check_segment, which the rc=2 branch never reaches. Verified — allow-list set, still rc=2.
• block_noncanonical_commit_enabled=false works but is insufficient. Four hooks call ps::classify_git_command with identical arguments. Measured on one blocked command: with none disabled, three guards block; disabling the commit guard leaves two; then one; three separate user-scope options must be flipped to run one benign command.
• The message names no hatch at all. It never mentions block_noncanonical_commit_enabled, unlike this guard's two other block paths (:503, :565), which both do. The PowerShell path is the only one that omits it.
• Attribution is impossible from the text: block-no-verify.sh:234 prints the same ps::print_unparsable_block_message, so two of the three blocking hooks emit byte-identical output and a user cannot tell which switch to flip.

Root cause: the shared classifier is tuned for a different harm profile

lib/powershell/ps-command.sh has no test file of its own — the shared predicate deciding every PowerShell command's fate across four guards is covered only indirectly through each consumer's suite.

Its sink doctrine is sound where it was written: for block-dangerous-git the harm is reset --hard / clean -fd, irreversible, so refusing an unprovable command is the right trade. block-noncanonical-commit inherits that posture unchanged, but its harm is a commit message with flattened newlines — cosmetic and recoverable via git commit --amend. Its own header calls it "a friction guard against the accidental anti-pattern, not a sandbox" (block-noncanonical-commit.sh:54). The severity asymmetry is the whole story.

Proximate cause of shipping: block-noncanonical-commit.test.sh has exactly seven PowerShell cases (L729-744) and every one contains git. There is no case asserting a non-git PowerShell command with an unparsable construct passes through. The Bash lane has that control (L259), and so does the sibling's PowerShell lane (block-dangerous-git.test.sh:567, 'Remove-Item $(Get-Foo)' expected 0). So this is an inconsistency between two suites sharing one classifier.

Suggested fix

Do not gate on a resolved git … commit before running obfuscation analysis. ps-command.sh:44-52 identifies that as the #740/#903 fail-open class and is right — the construct that defeats the tokenizer also mangles the shape scan. Do not narrow the shared ps::might_invoke_git either; four guards depend on it and loosening it weakens block-dangerous-git, whose fail-closed posture is the defensible one.

The seam is per-consumer rc=2 handling, and the precedent is already in this codebase: follow block-convention-violation.sh:375-383 and exit 0 on rc=2 in block-noncanonical-commit.

Coverage cost is provably zero today. Both guards call ps::classify_git_command with identical arguments and no other state, so rc is identical by construction; corroborated across a 12-case corpus where every commit-guard block was also a dangerous-git block, carrying that guard's accurate message. Anything reaching rc=2 here is already refused next door.

One design question to decide rather than assume: a user who disables block_dangerous_git_enabled while keeping the commit guard on would open a gap. The same asymmetry already exists in reverse today, and the measured three-switch lockout is the present cost of the coupling.

Cheapest companion changes: add the missing negative tests (port the sibling's control, plus the two shapes no suite covers — git in inert output text, and & '<literal>' with no git — and add the canonical-form cases above as must-allow regressions); rewrite the unparsable-block message to stop asserting an unestablished premise and to name the kill switch as the other two paths do; give block-no-verify its own message; and add direct unit tests for ps-command.sh, notably ps::might_invoke_git's boundary classes, where the . exclusion that makes .git inert is subtle, load-bearing, and currently unpinned by any test.

One inherited handoff that belongs to this plugin

A parallel typos-format audit found a write-bypass leak in block-hook-bypass.sh: a Python one-liner that opens a path and writes it evades the Write/Edit PostToolUse hooks entirely, while the guard refuses the echo/printf redirection form. That audit covered only block-noncanonical-commit, so without an explicit carry the finding falls between components.

It carries an ordering constraint: closing that leak removes the last escape hatch from typos-format's unconditional write mode. Flip typos_format_write_changes to false first, then close the bypass, or the situation gets strictly worse.

What the guard gets right

It fails closed rather than guessing, which is the correct default for a commit-integrity guard, and the library's refusal to trust a negative shape match on mangled text is well reasoned (ps-command.sh:44-52). No command was ever silently altered — every block was visible and exited 2. hook::require_jq fails open with a visible once-per-session notice, which is the right asymmetry. The kill switch does cleanly no-op the guard. And block-convention-violation.sh already demonstrates that the correct per-consumer seam exists here.

A fourth reproduction, from a bystander

While reviewing this audit, a separate agent doing unrelated work was blocked with the exact verbatim text on a Python attribute probe containing no git substring at all. Trigger: & $py $tmp — call operator on a variable — plus {}/(). It named no kill switch. A reviewer can run that in seconds, and it defeats the natural objection that the guard only misfires on commands that at least mention git.

[kyle-sexton]

Drain: tracked by open PR #2468 fix(guardrails): do not fail-closed on read-only PowerShell git with grouping (no duplicate opened).