fix(guardrails): every hook calling hook::require_jq fails OPEN when jq is absent, while the same guard fails closed on length

[kyle-sexton]

Filed by AI. Measured, not read — an earlier draft of this was withheld precisely because a
code-reading is not a verified negative, and readings have been wrong twice on this effort.

Two opposite failure postures in one guard

plugins/guardrails/hooks/block-dangerous-git.sh:

• Fails CLOSED on length. MAX_COMMAND_LEN=16384 (:105); an over-ceiling command is treated as
  obfuscation and blocked.
• Fails OPEN on missing jq. hook::require_jq (hook-utils.sh:132) is
  command -v jq >/dev/null 2>&1 && return 0, otherwise a once-per-session skip notice and
  exit 0 — the whole hook is skipped and the tool call proceeds.

Measured, four cells

The two-cell version of this test cannot distinguish "the guard was skipped" from "the harness
returns ALLOW for everything," so the jq-present column is the discrimination control:

                       jq PRESENT   jq HIDDEN
  dangerous push       DENY         ALLOW
  safe command         ALLOW        ALLOW

git push --force origin main is allowed when jq is unreachable. The jq-present column
proves the harness discriminates, so the ALLOW is the guard being skipped and not a stuck function.

Method: jq hidden via a BASH_ENV command() override that intercepts command -v jq and leaves
PATH untouched — stripping PATH directories would also remove git, which the guard needs, and
would produce the same ALLOW for an unrelated reason. The hook is a pure decision function (payloads
in, verdicts out), so nothing was executed and this is read-only by construction.

The length half was verified separately by the same shape: a safe command padded past 16384 is also
DENIED, which proves the denial is length-driven.

Why this is worth a design decision rather than a patch

Both postures are individually defensible and the file argues for each locally. Neither acknowledges
the other, and together they produce an odd threat model:

• An obfuscation-length command — a deliberate, adversarial act — is treated as hostile and blocked.
• An environment without jq — an ordinary, undramatic state, and one a user is unlikely to
  associate with a security guard at all — disables the guard entirely, silently after one
  notice per session.

Someone who cannot get a dangerous command past 16384 characters can simply be somewhere without
jq. That is not a sophisticated bypass; it is the default state of a machine that has not installed
one dependency.

hook::require_jq is shared, so this posture is not local to this guard — it is the failure mode of
every hook that calls it, including block-convention-violation, block-hook-bypass, and
block-no-verify. The question is therefore worth answering once, at the helper.

Options, no recommendation implied

1. Intended, leave it. The plugin's stated philosophy may be that an advisory guard must never
   block work over a missing prerequisite. If so, this issue is closed by writing that reasoning next
   to require_jq, where the two postures can be seen together.
2. Fail closed for the irreversible-operation guards specifically, keeping fail-open for advisory
   ones. Deny with a message naming jq as the missing prerequisite. Costs a hard dependency on a
   tool the README already lists as required for other plugins.
3. Degrade rather than skip. A jq-free substring pre-check for the highest-severity forms
   (--force, -f, +refspec, --mirror) — weaker than the real parser, but not nothing. Risks a
   false sense of coverage, which this repository has spent real effort learning to distrust.

Acceptance, whichever is chosen

• A test pinning the chosen posture with the four-cell shape above. Two cells cannot tell a skipped
  guard from a broken harness.
• If the posture stays fail-open, the reasoning belongs at hook::require_jq itself, not only at the
  call sites — the call-site comments assert the behaviour, and nothing where the decision is made
  explains why.

Related

• fix(guardrails): block-dangerous-git still clears an unsafe --force-with-lease via payload cwd and env -S #2124 — a separate live bypass in the same guard; unrelated to this posture
• docs(guardrails): block-dangerous-git's contract line says Bash-only; the matcher is Bash|PowerShell #2145 — the contract-line inaccuracy in the same file
• Triage the remaining stranded P2 review findings from the post-merge sweep #1938 — the stranded post-merge review-findings sweep

[kyle-sexton]

Independently confirmed by run — and one nuance that softens the "silent" framing

A second party reproduced this without sight of my method. Both halves now measured rather than one argued:

=== control: jq PRESENT — the guard must DENY ===
  git push --force        -> rc=2 DENY
  git reset --hard HEAD~1 -> rc=2 DENY

=== jq ABSENT (git and bash still reachable) ===
  git push --force        -> rc=0 ALLOW
  git reset --hard HEAD~1 -> rc=0 ALLOW

Nuance worth having before anyone acts on this. The fail-open is not literally silent: the hook emits its skip notice exactly once per session, as documented. Verified with a fresh CLAUDE_PLUGIN_DATA:

  no session_id            rc=0  377-byte notice  ("jq not found on…")
  session_id present (1st) rc=0  377-byte notice
  session_id present (2nd) rc=0  0 bytes

Two things temper it. The notice is additionalContext — it lands in the model's context, not obviously as a user-visible warning — and every subsequent dangerous command in that session is allowed with no output at all. So the accurate statement is "one notice, then silence," not "silent."

The methodology note is the most useful part

Three attempts to hide jq were invalid, and each produced exactly the ALLOW the tester was looking for:

1. PATH with the jq directory removed — also removed git and timeout; the hook never ran.
2. A symlink farm shadowing only jq — ln -s produced 0 entries (WinGet Links are reparse points), leaving an empty directory on PATH.
3. PATH=/usr/bin:/bin — hides jq, but git lives in /mingw64/bin, so git was missing too.

Only the fourth was sound: PATH=/mingw64/bin:/usr/bin:/bin, with a printed precondition line asserting jq=hidden git=visible bash=visible before reading any verdict.

Three separate broken fixtures each yielded the correct-looking answer for the wrong reason. Anyone re-testing this should assert the precondition explicitly rather than trusting that the intended tool is the only one hidden — that is what separates this measurement from a coincidence.

Still not covered

• Confirmed fail-open on block-dangerous-git only. hook::require_jq is shared by at least five hooks; the conclusion very likely generalizes but was not run against the others.
• Whether a jq-less environment is plausible in practice — this was synthesized by PATH manipulation; nobody checked whether Claude Code ships jq.
• Whether additionalContext actually surfaces to a human.
• Marker durability. If the once-per-session file survives in the real CLAUDE_PLUGIN_DATA, "once per session" may be once per machine until something clears it — which decides how silent the silence really is. Untested, and it bears directly on option 1.