perf(guardrails): block-dangerous-git.sh has 127 external-command call sites, the most in the set - reduce process spawns

[kyle-sexton]

Summary

Child of #3508. guardrails/hooks/block-dangerous-git.sh has the highest external-command call-site count of any hook in the marketplace (127) and timed out 59 times in the measured window.

This was initially left unfiled on the assumption a parallel session had claimed it. That session has confirmed it has not claimed this file and is not working it — its scope is two files in disk-hygiene. So this is unowned and is the largest single reduction opportunity in guardrails.

Measured

Plugin	guardrails
Hook	hooks/block-dangerous-git.sh
Event(s)	PreToolUse:Bash + PreToolUse:PowerShell
Timeouts in window	59
External-command call sites	127 — highest in the set
Configured timeout	15 s

Durations are deliberately omitted as a ranking signal: spawn cost on the affected host is bimodal with a 15.7x spread (see #3508), so cross-hook duration comparisons are unreliable. The call-site count is the durable number.

Why this one matters most

At a measured 0.3-0.9 s per process spawn, every call site that executes is most of a second. 127 call sites is an upper bound (many sit in branches), but even a modest executed fraction dominates the hook's wall-clock. A completed fix on a comparable launcher went from 4 spawns to 1 and improved median wall-clock 3.71x.

Proposed work

1. Count spawns first, before changing anything. Use a PATH shim directory of wrapper scripts that log their own name then exec the real tool; diff the count before and after. Deterministic, so it survives the host's drift, and cheap for a reviewer to verify.
2. Collapse multi-jq call sites into a single jq program per invocation.
3. Replace grep/sed/cut/tr/basename/dirname on the hot path with bash builtins.
4. Watch for x="$(f)" — command substitution forks a subshell, which on MSYS is a real process spawn. A builtins-only helper that reports on stdout still costs a full process; hot-path helpers must assign to a global.
5. Early-exit before any spawn when the invocation is not a git command at all — this guard fires on every Bash and PowerShell call but only acts on dangerous git forms.

Acceptance criteria

• Spawn count on the common path is reported before and after, measured by PATH shim.
• No more than 2 external process spawns on the common path.
• A non-git command exits before any spawn.
• Existing behavioural tests still pass; every dangerous git form blocked before is still blocked.
• Wall-clock reported alongside the concurrent-process count at sample time (see perf(hooks): Windows process-creation tax makes the hook set unusable - 1,778 timeouts / 20.6 hours blocked over 9 days #3508 for why a bare duration is not a valid claim on this host).

[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.