perf(guardrails): block-windows-drive-tmp.sh averages 73.4s and timed out 49x - reduce process spawns

[kyle-sexton]

Summary

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

Measured

Plugin	guardrails
Hook	block-windows-drive-tmp.sh
Event(s)	PreToolUse:Bash + PreToolUse:PowerShell
Timeouts in window	49
Average duration	73.4s
Worst observed	112.6s
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

Only 9 external call sites, yet still averages 73s - evidence that the cost is spawn overhead rather than script work. Good candidate for proving out the builtins-only rewrite pattern.

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]

Addendum: hook file paths, matcher corrections, and two withdrawn comparative claims.

Several children named no script file, which left a pickup agent to hunt. Verified paths:

Issue	Plugin	Hook file(s)
#3509	source-control	hooks/pr-body-linkage-gate.sh (+ pr-linkage-mcp-gate.sh on the ^mcp__github__(create|update)_pull_request$ matcher; shared pr-linkage-validator.sh)
#3510	source-control	hooks/worktree-add-containment-gate.sh (PostToolUse sibling worktree-add-claim-gate.sh)
#3512	claude-ops	hooks/hook-failure-audit.sh
#3515	autonomy	hooks/lane-stop-gate.sh
#3520	context-guard	hooks/zone-crossing-inject.sh

Matcher corrections:

• perf(context-guard): PostToolBatch: context-zone crossing averages 73.0s and timed out 10x - reduce process spawns #3520 — zone-crossing-inject.sh also fires on UserPromptSubmit, not only PostToolBatch. That changes its cost model: it is both a per-tool-batch and a per-turn cost, so it draws on the <= 500 ms per-turn ceiling as well.
• perf(guardrails): secret-pattern-detection.sh + hardcoded-path-check.sh averages 61.9s / 60.4s and timed out 3x - reduce process spawns #3521 — the event is not PreToolUse:Edit. The actual matcher is Write|Edit|NotebookEdit at timeout 60.
• perf(guardrails): block-windows-drive-tmp.sh averages 73.4s and timed out 49x - reduce process spawns #3517 — block-windows-drive-tmp.sh is registered on Write|Edit|MultiEdit|NotebookEdit in addition to the Bash/PowerShell matcher. The issue accounted for only the latter. See also block-windows-drive-tmp: non-Windows host gate leaves large payloads undrained on stdin #3504, which touches the same file (stdin drain).

Two comparative claims withdrawn:

• perf(guardrails): block-convention-violation.sh averages 70.5s (Bash) / 81.8s (PS) and timed out 207x - reduce process spawns #3511 called itself "worst average duration of any hook in the set" at 81.8 s. perf(guardrails): block-exported-msys-pathconv.sh averages 87.5s and timed out 15x - reduce process spawns #3519 records 87.5 s. The claim is wrong, and per perf(hooks): Windows process-creation tax makes the hook set unusable - 1,778 timeouts / 20.6 hours blocked over 9 days #3508's own correction, cross-hook duration rankings on this host are unreliable anyway (bimodal spawn cost, 15.7x spread). Treat both as "over budget", not as ranked against each other.
• perf(guardrails): block-noncanonical-commit.sh averages 78.0s and timed out 91x - reduce process spawns #3514's "110 call sites, second-highest in the set" conflicts with the parent's own table, which lists hook-utils.sh at 113.

Static call-site counts do not reproduce — treat them as indicative only. An independent pass on shipped 0.29.24 using the stated pattern yields, for block-dangerous-git.sh, 184 with comments / 163 lines-with-match / 44 comment-stripped — none of which is the published 127. The ordering survives under every method (block-dangerous-git.sh is highest), so #3529's headline stands, but the absolute numbers should not be quoted without pinning the exact command and version. #3508's Method section needs that pin.

The spawn-count criterion is the one that matters and it is unaffected: it is measured directly by PATH shim on the executed path, not inferred from source greps.

[kyle-sexton]

Verification: FULLY FIXED

Read-and-report pass over plugins/guardrails/hooks/block-windows-drive-tmp.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 named in a run-guards.sh invocation is sourced in-process, with hook::buffer_stdin called once for the whole batch and the jq field cache primed 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, and the plugin's own budget test (run-guards.test.sh:168-215) uses PATH shims whose comment concedes forks are invisible to them.

Both registered lanes were measured, per the maintainer addendum on #3514: Bash|PowerShell and Write|Edit|MultiEdit|NotebookEdit. The Windows lane was forced with OSTYPE=msys, as the contract suite does. HOOK_TELEMETRY_SINK unset. Linux, bash 5.2.21, jq present. Per-guard figures are deltas against a dispatcher run carrying a single no-op guard.

What the issue claimed vs what main has

Named overhead	State on main
9 external call sites, "still averages 73 s"	Runtime figures below.
source "$(dirname "${BASH_SOURCE[0]}")/hook-utils.sh"	Gone. Lines 61-64 are _HOOK_SELF="${BASH_SOURCE[0]%/*}" with the bare-filename fallback.
<= 2 external process spawns on the common path	Met, on both counters and every lane.
grep/sed/cut/tr/basename/dirname on the hot path	Met. Zero, all lanes.
Early exit before any spawn for non-matching invocations	Met, and this file is the best example in the plugin. The case "${OSTYPE:-}" gate at lines 98-101 runs ahead of hook::buffer_stdin and hook::require_jq_blocking, so on Linux and macOS the guard costs literally nothing on any lane.
Behavioural tests still pass	Met. block-windows-drive-tmp.test.sh PASS=214 FAIL=0; a mkdir /d/tmp/foo payload still exits 2 under OSTYPE=msys.
Under 2 s on a Windows host	Unverified. Measured on Linux.

Which commit changed it

a5f5e799 (#3781, "drop dirname and sed execs from the always-on path"). #3788 (5101f5a2) does not touch this file — confirmed against its file list, refuting the "fixed by #3788" framing for this shard specifically. The later 273c20fe (#3820) also does not touch it.

Batch-level history on git status --short (whole Bash|PowerShell matcher, all eight guards), for context on where this guard's share sits:

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

lane	host	execve contributed	process creations contributed
Bash|PowerShell, git status --short	Linux/macOS	0	0
Bash|PowerShell, git status --short	OSTYPE=msys	0	2
Write (file_path + content)	Linux/macOS	0	0
Write (file_path + content)	OSTYPE=msys	0	1

The batch's 2 jq are the dispatcher's, paid once for all eight guards; this guard adds none.

The two Windows-lane process creations, attributed with a BASHPID-logging DEBUG trap:

• block-windows-drive-tmp.sh:128 INPUT=$(hook::buffer_stdin)
• block-windows-drive-tmp.sh:325 s=$(mask_quoted_redirect_ops "$1") (Bash lane only; the Write lane never reaches it)

Residual: none in this file, and it is the reference shape for the others

I looked specifically for the two patterns the scout could have missed and found neither:

• The source "$(dirname …)" fork: already the ${BASH_SOURCE[0]%/*} form, matching plugins/source-control/hooks/worktree-create-gate.sh.
• In-substitution redirects and pipes: none. There are no $( … 2>/dev/null ) or $( … | … ) double-fork shapes on any path in this file. The one < <(split_shell_segments "$s") at line 470 sits behind has_drive_root_tmp and does not fire on a benign command.

Beyond that, line 186 of this file is the pattern the other three guards should copy. SUBJECT is resolved lazily inside emit_tel, behind hook::telemetry_enabled, so the hook::extract_bash_subject fork costs nothing when no sink is wired. block-hook-bypass.sh:159, block-noncanonical-commit.sh:177 and block-no-verify.sh:133 all still pay it unconditionally at file scope. Worth citing this file when that follow-up is written.

Its remaining 1-2 forks are the shared hook::buffer_stdin $( ) capture and one in-file command substitution, both small. The fleet-level version of the first (hook::buffer_stdin_to <var> in lib/hook-utils.sh, synced to 17 copies via scripts/sync-hook-utils.sh) is worth its own issue: 1 fork per guard, 8 of the 36 process creations per Bash tool call.

Recommendation

Close. Every overhead this issue names is gone, on both registered lanes, and the guard is at or under its own "<= 2 spawns" bar on both counters. The scout's read was correct here. The only caveat on the record is that the "under 2 s on a Windows host" criterion was not verified in this lane, and the binding budget is the docs/conventions/hook-budget/README.md ceiling cited in the shared correction above, not the ad-hoc figure in the issue body.

---

Generated by Claude Code