perf(guardrails): block-no-verify.sh averages 76.1s and timed out 44x - reduce process spawns

[kyle-sexton]

Summary

Child of #3508 (Windows process-creation tax). This issue covers one hook: block-no-verify.sh in the guardrails plugin.

Measured

Plugin	guardrails
Hook	block-no-verify.sh
Event(s)	PreToolUse:Bash + PreToolUse:PowerShell
Timeouts in window	44
Average duration	76.1s
Worst observed	134.1s
Configured timeout	15 s

Every recorded run exceeded the 15 s timeout, so this guard is killed before it renders a verdict. It currently costs wall-clock without providing protection on this platform.

Context from the parent

Process creation on the affected host costs 0.3-0.9 s per spawn (bash -c true = 661 ms, jq -n 1 = 908 ms, cmd.exe /c exit = 872 ms, against ~3-5 ms on a healthy host). User CPU time is ~1% of wall-clock, so the fix is reducing the number of process spawns, not optimizing script logic. See #3508 for the full measurement and environment detail.

Specific guidance

30 external call sites. Detection is a simple substring match on the command; should be achievable with bash builtins and zero subprocesses.

Acceptance criteria

• This hook makes no more than 2 external process spawns on its common path (its own shell plus at most one jq).
• Subprocess calls to grep/sed/cut/tr/basename/dirname on the hot path are replaced with bash builtins.
• Where the guard only applies to a subset of commands, the matcher or an early guard clause exits before any spawn for non-matching invocations.
• Existing behavioural tests still pass; the guard still blocks what it blocked before.
• Measured on a Windows host, a single run of this hook completes in under 2 s.

Method

Counts from ~/.claude/projects/**/*.jsonl hook_cancelled attachments with timedOut: true, across 236 sessions, 2026-08-23 to 2026-08-31.

[kyle-sexton]

Shared correction (applies to every child of #3508)

1. The "15 s" timeout in the table above is wrong for most of these hooks. Timeouts are declared per hook in each plugin hooks/hooks.json, and they vary widely. Verified against the installed manifests and cross-checked against the timeoutMs field the harness records in transcripts:

source-control  PreToolUse Bash                    timeout=15
guardrails      PreToolUse Bash|PowerShell         timeout=60
guardrails      PreToolUse Write|Edit|NotebookEdit timeout=60
guardrails      PostToolUse Write|Edit             timeout=30
context-guard   PreToolUse / PostToolBatch         timeout=60
disk-hygiene    PreToolUse Bash|PowerShell         timeout=60 ; Stop timeout=20
claude-ops      Stop timeout=10 ; StopFailure timeout=5
autonomy        Stop timeout=15

Observed timeoutMs distribution across the transcript corpus confirms it: 1,365 PreToolUse:Bash timeouts at 15,000 ms (source-control), 246 at 60,000 ms and 384 PreToolUse:PowerShell at 60,000 ms (guardrails), Stop at 10,000 / 15,000 / 20,000 ms.

This makes the guardrails hooks worse than reported, not better — each one burns a full 60 seconds before being killed, not 15.

2. The acceptance criteria should cite the repo's existing budget, not the ad-hoc ones I wrote. docs/conventions/hook-budget/README.md (adopted in #1809, surfaced by .claude/rules/hook-budget.md on plugins/*/hooks/**) already defines the binding ceiling:

Surface	Budget
Per tool call (PreToolUse + PostToolUse for one matcher)	<= 1 s typical, <= 2 s worst-case
Per turn (Stop / notification-shaped)	<= 500 ms

Measured as parallel wall time, not the sum. Rule 1 of that doc requires a plugin adding or widening an always-on hook to state its measured share in its README; Rule 2 states the budget never relaxes to absorb an overage. Use those numbers as the bar. My "under 2 s on a Windows host" was an accidental near-restatement of the per-tool-call worst case; the per-turn 500 ms figure I did not have at all, and it binds every Stop-event child.

3. Prior art exists and should not be re-derived. #1403 (closed, needs-human) captures the spawn-reduction work from the unmerged PR #1385, including:

• hook::jq_fields batched field extraction in lib/hook-utils.sh, replacing per-field jq calls across eight guards
• a strip_quoted_spans shell-builtin replacement for a printf | sed | sed pipeline
• a deferred git rev-parse --is-inside-work-tree probe in hardcoded-path-check.sh
• a census of 65 process spawns per Bash tool call, and a measured 437 ms per-spawn unit price

It also records why #1385 did not merge: a fresh-context verification found four contract-test regressions, two of which failed open. Any revival must clear those first.

4. hook-utils.sh is synced, not per-plugin. It exists in 17 copies across plugins/*/hooks/hook-utils.sh, delivered by scripts/sync-hook-utils.sh. A change there must go through that script with all copies verified identical — editing one plugin's copy will be reverted or will diverge the fleet.

5. Validate with scripts/affected-tests.sh --run (add --explain to see suite selection), per the repo AGENTS.md. A changed file mapping to zero suites is an error, not "nothing to run".

6. Reference baseline for the host. The budget doc's reference measurements (2026-07-31, Windows 11 + Git Bash) are bash -c : ~ 80 ms and python3 -c pass ~ 160 ms, with the per-Bash-call always-on set at **~ 5.9 s parallel wall**. The host in #3508 measures a bimodal no-op spawn at 180-2,841 ms (median 1,108 ms) at 501 concurrent processes — 2-35x worse than that reference. Report the spawn baseline alongside any timing so a result on a healthy box is not mistaken for a pass on a contended one.

[kyle-sexton]

Verification: PARTLY FIXED, and #3788's contribution here was not a spawn

Read-and-report pass over plugins/guardrails/hooks/block-no-verify.sh at origin/main (a34a96bc). This lane does not close issues; the recommendation below is for the triage lane.

Method

Guards no longer run as standalone hooks. Every guard in the Bash|PowerShell matcher is sourced in-process by run-guards.sh, which calls hook::buffer_stdin once for the whole batch and primes the jq field cache once. Verified on current main by reading the dispatcher and by measurement.

Counted with strace -f -e trace=clone,clone3,fork,vfork,execve, two separate counters: successful execve (PATH-visible program images, failed PATH probes discarded) and clone/fork (process creations including pure subshells, which is what an MSYS2 fork costs on the affected host). No xtrace command-position count: #3520 showed it reads 2 where the kernel makes 8. The plugin's own budget test (run-guards.test.sh:168-215) uses PATH shims and its own comment concedes forks are invisible to them, so nothing in the suite pins the fork dimension.

Per-guard figures are deltas against a dispatcher run carrying a single no-op guard. HOOK_TELEMETRY_SINK unset. Linux, bash 5.2.21, jq present.

What the issue claimed vs what main has

Named overhead	State on main
30 external call sites	Runtime figures below; static counts were withdrawn in the maintainer addendum on #3514.
"Detection is a simple substring match; should be achievable with zero subprocesses"	True on execve. Zero contributed. Not yet true on process creations: 3 remain.
source "$(dirname "${BASH_SOURCE[0]}")/hook-utils.sh"	Gone. Lines 53-56 are _HOOK_SELF="${BASH_SOURCE[0]%/*}" with the bare-filename fallback.
<= 2 external process spawns on the common path	Met on execve (the batch's 2 jq are the dispatcher's, amortized over all eight guards). Missed on process creations (3).
grep/sed/cut/tr/basename/dirname on the hot path	Met. Zero on the common path.
Behavioural tests still pass	Met. block-no-verify.test.sh PASS=240 FAIL=0; git commit --no-verify -m x still exits 2.
Under 2 s on a Windows host	Unverified. Measured on Linux.

Which commits changed it, and what #3788 actually bought

Two commits touched it, and the scout's "fixed by #3788" credits the wrong one for the spawn reduction:

commit	change	measured effect on spawns
a5f5e799 (#3781)	source "$(dirname …)" replaced by ${BASH_SOURCE[0]%/*}, lines 53-56	removed 1 dirname exec
5101f5a2 (#3788)	moved the lib/powershell/ps-command.sh source, and the PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$_HOOK_SELF/.." && pwd)}" line with it, inside the if [[ "$TOOL_NAME" == "PowerShell" ]] branch at lines 279-282	zero. Exec and fork counts are byte-identical before and after. Claude Code always sets CLAUDE_PLUGIN_ROOT, so that $(cd … && pwd) never forked in production either. What #3788 bought was the ~41 KB parse of the classifier on the Bash lane, which is CPU, not a process.

The parse saving is real: batch p50 fell 78 -> 67 ms across #3788. But it is not what the acceptance criteria measure.

Batch-level history on git status --short (whole matcher, all eight guards):

tree	execve	process creations	batch p50 (n=25)
a5f5e799^ (pre-#3781)	16 (3 bash, 7 dirname, 3 git, 2 jq, 1 sed)	65	97 ms
a5f5e799 (#3781)	8 (3 bash, 3 git, 2 jq)	54	78 ms
5101f5a2 (#3788)	8	54	67 ms
273c20fe (#3820)	3 (1 bash, 2 jq)	36	49 ms

Measured counts for this guard

On git status --short, on git commit -m "feat: thing", and on git commit --no-verify -m x (which still blocks), inside the dispatcher:

• execve contributed: 0, on all three payloads.
• Process creations contributed: 3.

Attributed with a BASHPID-logging DEBUG trap on the dispatcher's isolation subshell:

line	site	ownership
block-no-verify.sh:70	INPUT=$(hook::buffer_stdin)	shared pattern, all eight guards
block-no-verify.sh:133	SUBJECT=$(hook::extract_bash_subject "$TOOL_NAME" "$COMMAND"), file scope, unconditional	in-file
hook-utils.sh:2717	while IFS= read -rN1 c; …; done < <(printf '%s' "$cmd") in hook::bash_parse_segments	shared library

Residual the scout's read missed

Line 133 is a one-line in-file win. block-windows-drive-tmp.sh:186 already carries the fixed shape: SUBJECT is resolved lazily inside emit_tel, behind hook::telemetry_enabled, so it costs nothing when no sink is wired (the fleet default). Line 133 pays the fork on every Bash tool call whether or not telemetry is on. block-hook-bypass.sh:159 and block-noncanonical-commit.sh:177 share the defect, so one change fixes three guards.

The other two are shared, not this file's to fix:

• hook::buffer_stdin_to <var> in lib/hook-utils.sh (synced to 17 copies via scripts/sync-hook-utils.sh). Under the dispatcher the payload is already sitting in RUN_GUARDS_INPUT; INPUT=$(hook::buffer_stdin) copies it back out through a fork and a pipe. 1 fork per guard, 8 of the 36 process creations per Bash tool call. Largest remaining win in the plugin and worth its own issue.
• hook-utils.sh:2717, the per-character parse loop fed by a process substitution.

I also checked the two shapes the scout could have missed and found neither in this file: the source "$(dirname …)" fork is already the ${BASH_SOURCE[0]%/*} form, and there are no $( … 2>/dev/null ) or $( … | … ) in-substitution redirect or pipe double-forks anywhere in it.

One more thing the criterion does not yet meet at the batch level: the dispatcher spends 2 jq, not 1. The second is hook::json_complete's validity probe (hook-utils.sh:1386, called from buffer_stdin at line 1600).

Recommendation

Close as fixed, with the residual re-filed. Every overhead this issue names is gone, the guard contributes zero external process spawns on its common path, and its detection really is builtins-only as the issue asked. The 3 remaining process creations are one shared line-level fix plus two shared-library items. Suggest a successor issue covering the lazy-SUBJECT hoist in block-no-verify.sh:133, block-hook-bypass.sh:159 and block-noncanonical-commit.sh:177, plus hook::buffer_stdin_to. For the record, the commit that removed this guard's spawn is a5f5e799 (#3781); #3788 removed a parse, not a process.

---

Generated by Claude Code