refactor(hooks): read stdin via hook::buffer_stdin in advisory hooks (8 plugins)

[kyle-sexton]

Summary

Replaces the bare INPUT=$(cat) fd0 read in the 8 advisory entry hooks (actionlint, bash-format, biome-format, ruff-format, markdown-format, powershell-format, eol-normalizer, desktop-notification) with the shared hook::buffer_stdin helper. The bare cat blocks indefinitely on the Windows Win32-pipe late-EOF stall; buffer_stdin bounds the read (default 2s) and returns the payload, so a stalled pipe degrades to a visible skip instead of hanging the hook. Empty or timed-out stdin exits 0, matching the existing empty-payload skip behavior.

Scope decisions (from the #313 item-3 scout):

• No stdin_read_timeout manifest options are re-added. The option was deliberately removed from these plugins in the feat: migrate hook kill switches to native userConfig (10 plugins) #323 review ("least churn" option); the 2s default bound fixes the actual defect. Only claude-ops still declares the knob.
• claude-ops/hook-telemetry-sink.sh is intentionally untouched: it reads a fire-and-forget producer telemetry envelope (not a hook payload) whose producer discards stdout+stderr, its bare cat is silent-skip-ok-annotated, and it must never block.
• The 7 guardrails hooks ship separately with fail-closed timeout semantics for the 5 blocking guards.

Test change: markdown-format's telemetry-gate assertion now expects the additional jq -e . payload-completeness probe buffer_stdin spawns (a piped read always ends read -d '' with a non-zero status at EOF, so the probe runs every invocation).

Version bumps: actionlint 0.4.1, bash-format 0.5.1, biome-format 0.4.1, ruff-format 0.4.1, markdown-format 0.5.2, powershell-format 0.4.2, eol-normalizer 0.4.1, desktop-notification 0.4.1.

Verification

• shellcheck (--rcfile=.shellcheckrc) + shfmt -d clean on all 8 hooks
• All 8 hook test suites green (35/39/3/50/65/46/35/54 passes)
• validate-plugins.sh, validate-plugin-contracts.mjs, check-silent-skips.sh clean
• markdownlint clean on all touched CHANGELOGs

Related

Epic #313 (deferred-backlog item 3, advisory half). Also relates to #317, #323.

No linked issue: incremental epic work; closes nothing.

🤖 Generated with Claude Code

[claude]

Claude finished @kyle-sexton's task in 3m 49s —— View job

---

PR Review

• Gather context and understand the request
• Read the PR diff and changed files
• Review hook script changes (8 hooks)
• Review test file changes (markdown-format)
• Review version bumps and CHANGELOGs
• Post review findings

---

Summary

The core change — replacing INPUT=$(cat) with INPUT=$(hook::buffer_stdin) || exit 0 in 8 advisory hooks — is correct and well-scoped. The helper is properly defined in every plugin's hook-utils.sh, the || exit 0 idiom correctly degrades all failure modes (empty, incomplete, timeout) to advisory skips, and the version bumps and CHANGELOGs are consistent. The scope exclusions for claude-ops/hook-telemetry-sink.sh and the 7 guardrails hooks are justified and match the PR description.

One finding and one observation below.

---

Finding: Stale "bare cat" header comment in 7 of 8 hooks

7 of the 8 changed hook scripts still carry a comment block that explicitly references the now-removed cat read:

# Read inherited fd0 directly (bare cat) — NEVER `</dev/stdin`: on Windows Git
# Bash, CC spawns hooks with stdin = a Win32 pipe that `/dev/stdin` cannot
# resolve (ENOENT → silent no-op). stdin is read ONCE here and fed to both
# hook::read_file_path (file_path) and the tool_name parse below; reading fd0
# twice would drain the pipe on the second call.

Affected files:

• actionlint-check.sh L14–18
• bash-format.sh L16–20
• biome-format.sh L20–24
• eol-normalizer.sh L18–22
• markdown-format.sh L11–15
• powershell-format.sh L24–28
• ruff-format.sh L28–32

desktop-notification.sh was correctly handled — its inline comment just above INPUT= was rewritten to describe buffer_stdin. These 7 hooks had the comment placed above source hook-utils.sh instead, so it wasn't touched by the one-line swap.

The "stdin is read ONCE" / "twice would drain the pipe" logic is still accurate, but the "bare cat" description and the "NEVER </dev/stdin" rationale now belongs in hook-utils.sh's own comment block (line 231–238), not repeated in each hook. The fix should replace the stale block with a concise forward-reference, consistent with how desktop-notification was updated:

# hook::buffer_stdin encapsulates the Win32-pipe-safe bounded fd0 read. stdin is
# read ONCE here; reading fd0 twice would drain the pipe.
# shellcheck source=hook-utils.sh
source "$(dirname "${BASH_SOURCE[0]}")/hook-utils.sh"

Fix this →

---

Observation: jq -e . probe runs on every non-empty invocation

read -r -d '' -t N reads until a NUL byte or EOF or timeout. On a normal pipe, EOF arrives before any NUL, so read always exits non-zero (read_status != 0). This means jq -e . (the payload-completeness probe inside buffer_stdin) runs on every invocation when jq is available — even when the pipe closed cleanly with a complete payload.

The test change in markdown-format.test.sh L736 correctly captures this (1 → 2 jq spawns) and the PR description acknowledges it. The extra spawn is lightweight and the correctness benefit (distinguishing a truncated timeout read from a clean small payload) justifies it. Noted here for visibility since it's a permanent behavior change.

---

Everything else looks good

• || exit 0 correctly handles all three non-success return codes from buffer_stdin (1 = empty, 1 = incomplete, 2 = timeout) with a clean advisory exit
• The BLOCKED stderr message on return 2 remains visible even through || exit 0, giving operators a signal when a real Win32 stall occurs
• All 8 hook-utils.sh files carry hook::buffer_stdin at line 240 — the function is never missing for the callers added in this PR
• Guardrails hooks (plugins/guardrails/hooks/*.sh) and hook-telemetry-sink.sh correctly retain bare cat pending their separate treatment
• Version bumps are correct patch-level increments; all 8 CHANGELOGs are consistent