Hook performance program: measure and cut every runtime-cost surface on the Windows host

[kyle-sexton]

Summary

Tracking issue for the hook-performance-levers program. The plan lives in docs/topics/hook-performance-levers/PLAN.md. Goal: every hook and runtime-cost surface this marketplace ships is measured on the Windows Git Bash host and cut where the measurement says so, with no check removed and every hook still a type: command entry in its plugin's hooks/hooks.json.

Phases

• Phase 1: dotfiles harness extension (melodic-software/dotfiles PR)
• Phase 0: baseline capture at main with the extended harness, cache-delivery helper (not a PR)
• Phase 3: if gates, matcher scoping, explicit timeouts
• Phase 5: Windows path-form correctness (index-drift, emit-findings scripts, host-only test skips)
• Phase 2 (measured, not applied): async: true on non-deciding, non-rewriting hooks
• Phase 4a: guard hot path inside the guardrails dispatcher
• Phase 7: statusline tee cost
• Phase 4c: per-Write formatter hook hot path
• Phase 6: skill listing budget (human-gated)
• Phase 4b (re-scoped to the telemetry envelope and payload reader): hook-utils.sh core plus lazy modules (only if phase 4a's parse measurement clears the threshold)
• Phase 8 (docs(hooks): record the post-program hook budget accounting #3679 on auto-merge): accounting, docs, final proof

Related

• PR perf(hooks): dispatch the guardrails guards through one process and if-gate the path-specific hooks #3621 (guardrails dispatcher, already open) is the precursor this program builds on.

[kyle-sexton]

Second dataset from the laptop host (melo-lap-001 class: i9-13980HX 24C/32T, 64 GB, NVMe, Windows 11 26200, Git for Windows 2.55, Claude Code 2.1.259), captured 2026-09-02 evening while five interactive Claude Code sessions were running (ambient CPU 16-40%, privileged time ~8%, MsMpEng ~2% of the machine). Each hook was fed a realistic payload on stdin with CLAUDE_PLUGIN_ROOT/CLAUDE_PLUGIN_DATA exported, N=5, wall-clock milliseconds (min / median / max). Versions are the user-scope installs at capture time (guardrails 0.31.1, context-guard 0.7.34, disk-hygiene 0.21.4, eol-normalizer 0.6.28, typos-format 0.6.35, markdown-format 0.11.38, autonomy 0.22.21, claude-ops 0.41.8, context-budget 0.6.19, codex 1.0.6).

Spawn floors on this host under that load: bash -c true 33/42/55, bash -c 'jq -n 1' 51/61/75, node -e 0 60/73/77, python -c 0 78/81/83.

Hook	min	med	max
guardrails PreToolUse Bash, echo hi	953	1054	1340
guardrails PreToolUse Bash, git status	1039	1233	2156
guardrails PreToolUse PowerShell, Get-Date	1923	2398	3223
guardrails PreToolUse Write	483	574	646
guardrails PostToolUse Write	1023	1069	1204
disk-hygiene PreToolUse PowerShell	125	136	290
disk-hygiene Stop	124	133	245
context-guard PostToolBatch	151	173	264
context-guard UserPromptSubmit	139	176	282
context-guard PreToolUse Write	40	50	172
context-budget PreToolUse Write (node)	104	112	361
eol-normalizer PostToolUse Write	435	452	1017
typos-format PostToolUse Write	310	1040	1133
markdown-format PostToolUse Write (.md)	421	458	841
autonomy Stop	235	925	1904
claude-ops Stop	226	260	382
claude-ops InstructionsLoaded	57	193	410
codex Stop (node)	206	285	611

Per-guard split for the Bash PreToolUse row (RUN_GUARDS_PROFILE=1, one run): no-verify 60, dangerous-git 72, hook-bypass 117, flag-commit-pr 35, noncanonical-commit 86, convention-violation 107, windows-drive-tmp 84, exported-msys-pathconv 161.

End-to-end harness tax on the same host, claude -p 'Reply with exactly: OK' --model sonnet, N=2, wall ms: default settings 8547 / 6748, --bare 931 / 866, --setting-sources "" 2733 / 5491. The default-minus-bare delta (roughly 6-7.5 s per one-turn session) is the number that bounds everything in this table plus SessionStart, UserPromptSubmit, and statusline.

One handoff for the hooks.json rows, measured on this host (7 runs, sorted ms): invoking a hook script directly, so Windows resolves its #!/usr/bin/env bash shebang, costs 84-241 (median ~108); invoking the same script as bash <script> costs 72-209 (median ~91). The env hop is an extra process creation on MSYS. bash -c 'env true' alone is ~40 versus bash -c true ~25. Registering rows as bash "${CLAUDE_PLUGIN_ROOT}/hooks/x.sh" rather than executing the script path would save that hop on every fire.

Scripts used: a hook timing harness and a headless startup harness, both kept outside the repo; happy to attach them if the phase 8 accounting wants the exact payloads.

[kyle-sexton]

Program outcome (2026-09-03)

Every phase is in main. Landed: #3621 (dispatcher and if gates), #3662 (timeouts, rejected settings gate), #3666 (Windows path forms), #3668 (statusline tee), #3671 (context-guard hot path), #3675 (Write formatter hot paths), #3676 (guard hot paths), #3677 (skill listing budget), #3678 (shared-library telemetry envelope and payload reader), dotfiles #620 (harness), and #3679 (accounting docs, on auto-merge). Phase 2 (async) was measured and not applied: async output bypasses the operator, and every candidate row emits a decision or a notice the operator reads.

No check was removed, no if or matcher was narrowed to dodge a sample, every hook stays type: command in its plugin's hooks/hooks.json, and enabledPlugins is unchanged against the pre-program snapshot.

Final run

Installed cache at main 5e3d749cb, every measured plugin's cache directory byte-identical to origin/main, harness common/measure-claude-hook-fanout.sh sha256 5a254b50a67a9e1b158ce9ff7bd3c7c53f7eade80e55a1b2f8c5075026067178, --runs 3, spawn floor S = 18 ms, valid, quiet host.

Event (slowest hook, ms)	Before (2026-09-02 morning)	After
PreToolUse:Bash (git status --short)	2,475	1,599
PreToolUse:Write (in-repo .md)	773	1,360
PostToolUse:Write (in-repo .md)	13,225	1,949
PostToolUse:Edit (in-repo .md)	17,192	3,048
PostToolBatch	1,254	282
UserPromptSubmit	975	297
Stop (slowest of four)	376	410
SessionStart startup	210	114

The before column's Write and Edit rows are the in-repo figures (the phase 0 run sampled an out-of-repo file, on which every Write and verifier guard early-exits; the harness now writes its samples under the measured cwd, which is why PreToolUse:Write reads higher after). Against the hook-budget convention: every per-turn line and every count cap is met; the per-tool-call lines miss the 1 s typical ceiling (1.4 to 1.9 s on the benign samples, 2.1 to 3.3 s on the Edit and substitution samples), and the guardrails dispatcher is the whole of each miss. Its README names the remaining levers.

Where the record lives

• docs/conventions/hook-budget/README.md: reference figures in spawn-equivalents with the harness identity (docs(hooks): record the post-program hook budget accounting #3679).
• Per-plugin READMEs: a hook budget accounting section in guardrails, context-guard, rate-limit-guard, typos-format, eol-normalizer and markdown-format.
• docs/conventions/hook-telemetry/README.md: the envelope is one compact JSON line; sinks parse JSON.
• Branch perf/hook-performance-program: docs/topics/hook-performance-levers/PLAN.md (goal as restated, the constraint 1 mapping table, the final per-event block and STATED CHECK) and DEVIATIONS.md (every ruling, finding and evidence run). Contract tier; pruned, not merged.

Findings worth their own issues

1. On Claude Code 2.1.258 Windows, a hook if file rule never matches an absolute path outside cwd under any anchor form; only in-cwd relative paths match. Upstream candidate.
2. claude plugin update re-points a plugin's gitCommitSha without rewriting its cache directory when the version number is unchanged; the directory keeps the older build. A file-level compare is the only proof of what is installed.
3. A session start refreshes every marketplace and sets autoUpdate: true, re-pointing any plugin whose version main has matched.
4. plugins/skill-quality/scripts/check-skill.sh --require-evals under a vanished scratch directory spins forever.
5. Host-only suite failures on Windows Git Bash: block-windows-drive-tmp.test.sh (15), hardcoded-path-check.test.sh (2), markdown-format.test.sh (4 PATH-shape cases), .claude/hooks/cloud-bootstrap-plugins.test.sh, audit_skill_visibility.test.sh (fixture path).
6. The skill listing aggregate (135,424 characters over 182 skills) is 17x the documented 1 percent default budget; only the user-side skillListingBudgetFraction and skillOverrides settings can close that gap.

[kyle-sexton]

Phase 8 docs landed as #3679. The six follow-ups from the outcome comment are filed: #3680 (Windows if path matching, upstream candidate), #3681 (stale cache directory on claude plugin update), #3682 (check-skill.sh --require-evals hang), #3683 (five host-only suite failures), #3684 (env shebang hop on every hook row), #3685 (guardrails dispatcher remaining per-tool-call cost). The contract slice docs/topics/hook-performance-levers/ on branch perf/hook-performance-program is pruned per the topic-docs lifecycle; its pre-prune commit is named in the prune commit.

[kyle-sexton]

One more follow-up from the peer Performance session's research, filed after the program closed: exec-form hook rows (the hooks doc's args form spawns the executable with no shell, removing the Git Bash spawn every shell-form row pays on Windows, plus the Defender real-time scan the peer measured on the expired-signature bash.exe). Deferred by the program's constraint 8 because upstream anthropics/claude-code#90495 is still open; the new issue carries the live-probe gate and the sweep plan.