perf(source-control): pr-issue-linkage gate averages 24.7s and timed out 423x - reduce process spawns

[kyle-sexton]

Summary

Child of #3508 (Windows process-creation tax). This issue covers one hook: pr-issue-linkage gate in the source-control plugin.

Measured

Plugin	source-control
Hook	pr-issue-linkage gate
Event(s)	PreToolUse:Bash
Timeouts in window	423
Average duration	24.7s
Worst observed	115.3s
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

Highest single offender in the corpus. Fires on every Bash call but only needs to act on PR-creating invocations (gh pr create / gh pr edit). Narrowing the matcher to those removes ~99% of its firings outright.

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.