Repository navigation
Description
This was generated by AI during attend-queue.
Problem
#4373 closed on 2026-10-14 with Windows Stop at p50 470 ms and p95 1,624 ms against its 2,000 ms
budget. A second Windows host now measures the Stop wall at p50 576 ms and p95 2,072 ms (8 of 125
Stops over 2 s, max 4,052 ms), with 11 to 12 Stop hooks firing on every turn. Two rows set the wall;
the other ten each cost one process start that exits without doing work.
Owners, verified by grepping each statusMessage in plugins/*/hooks/hooks.json on origin/main
(31eafaa). The source item guessed autonomy for the first row; it is disk-hygiene.
| Stop row (statusMessage) | Owner | p50 ms | p95 ms | What runs when idle |
|---|---|---|---|---|
| Checking for silent destructive-guard failures | disk-hygiene (hooks.json:139) |
580 | 2072 | node, then bash and Python once the session holds a launch marker: child issue |
| Checking for unsurfaced hook failures | harness-ops (hooks.json:146) |
436 | 1924 | shell-form bash plus one tail, every turn: child issue |
| Checking spelling in uncommitted changes | typos-format | 378 | 1472 | node only (option gate) |
| Checking Python in uncommitted changes | ruff-format | 362 | 1224 | node only |
| Checking PowerShell in uncommitted changes | powershell-format | 355 | 1220 | node only |
| Checking Markdown in uncommitted changes | markdown-format | 341 | 1100 | node only |
| Checking JavaScript, TypeScript and JSON in uncommitted changes | biome-format | 289 | 1100 | node only |
| Checking Go in uncommitted changes | go-format | 292 | 1016 | node only |
| Checking shell scripts in uncommitted changes | bash-format | 284 | 1016 | node only |
| Checking lane-stop gate | autonomy | 285 | 1014 | node only (env and settings-mention gate, from #6254) |
| Checking workflows in uncommitted changes | actionlint | 283 | 991 | node only |
Evidence
- Per-hook numbers:
findings.py stop-hook-timingin a 2026-10-20/performance:go-fasterrun,
104 timed samples per hook, Stop event only. Wall numbers: recomputed this pass from the same
transcript's 125stop_hook_summaryrecords as the maxdurationMsper record (hooks for one event
run in parallel, per https://code.claude.com/docs/en/hooks.md). Summed hook time per Stop: p50
3,856 ms, p95 13,576 ms. - Host context: a home-rooted session, 5 to 10 concurrent sessions, and more than 500 workflow agents
in the same session. These numbers are contention-heavy; the perf(hooks): Stop and per-tool-call hook fan-out exceed budget on Windows (Stop p50 2.9 s, grows with session length) #4373 laptop numbers are not. - The nine "uncommitted changes" rows are default-off end-of-turn checks
(--require-true <PLUGIN>_END_OF_TURN, e.g.plugins/markdown-format/hooks/hooks.jsonStop row;
manifest default false,plugins/markdown-format/.claude-plugin/plugin.json:30-35). On the
measuring host none of those options is set (userpluginConfigschecked), and the installed
versions match main (markdown-format 0.14.2). So these rows exit insideexec-bash.mjsat the
option gate, before bash, git or any linter runs. Their ~280 to 380 ms p50 is a node cold start
under load. - Did NOT reproduce: the item's premise that the per-language checks do git or lint work outside a git
work tree. They do no work at all when the option is off. Its first proposed fix (a shared cached
git diff --name-onlyand a work-tree check) only helps once someone enables an end-of-turn option. - Not measured: PreToolUse overhead (the item saw a ~4.5 s median Bash call even for
date; not attributed).
Proposed approach
Children handle the two rows that set the wall (#8771, #8772). This issue holds the decision for the ten node-only rows. Decision defaulted on this issue: A (veto before merge).
- A. Recommended: accept them at the exec-form floor. Each is one process (k = 1 in perf(hooks): Stop and per-tool-call hook fan-out exceed budget on Windows (Stop p50 2.9 s, grows with session length) #4373's model),
runs in parallel, and does not set the wall. Record the decision indocs/conventions/hook-budget. - B.
async: trueon the default-off rows. Removes them from the wall, but an enabled end-of-turn
check must hand findings back before the turn ends, so this needsasyncRewake(wakes Claude on exit
2 with stderr as a system reminder, per the hooks page) and a behavior check that findings still land. - C. Shared Stop dispatcher. Not possible across plugins: each plugin registers its own
hooks.json.
Rejected: a matcher or if on Stop rows. Stop has no matcher support, and a hook with if set on a
non-tool event never runs (hooks page, if field).
Acceptance criteria
This issue is now doc text in one convention file (C3). The live Windows re-measure is split to the needs-human child.
-
docs/conventions/hook-budget/README.mdrecords that default-off Stop rows that exit at theexec-bash.mjsoption gate are accepted at the exec-form floor (k = 1, parallel), citing the hooks page section (https://code.claude.com/docs/en/hooks.md, hooks for one event run in parallel), with the 2026-10-20 measurement above as the basis. - No
hooks.jsonchanges. - The PR's CI runs the markdown lint and the local link and anchor check, and both pass.
- A changelog fragment only if
scripts/check-changelog-fragments.sh --checkrequires one; that check passes.
docs/conventions/** is on the HIGH floor, so a human merges it.
Constraints and gotchas
- Exec-form rows are deliberate (feat(hooks): complete exec-form fleet (zero shell-form rows) #5153, zero shell-form rows); do not reintroduce shell-form gating.
- harness-ops' audit is shell-form on purpose, as a detector decoupled from the launch path it watches.
- Rerun the timing on the same host before and after; contention moves these numbers by 2x or more.
Context
Source: local handoff item 20261020-235600-stop-hook-fanout-latency-per-turn.md (retired into this
issue). Prior work: #4373 (fan-out container, closed 2026-10-14), #6254 (autonomy and disk-hygiene
launcher gates), #4389/#4408 (harness-ops incremental audit), #3516 (disk-hygiene marker skip),
#4671 (format hooks outside a work tree, PostToolUse side).
Activity
github-actions commentedon Oct 21, 2026
Thanks for the report. Automated triage handed this issue to a maintainer.
Proposed work class: work-class: structural
Basis: automated intake triage; a maintainer confirms or changes it.
Automated triage. A maintainer reviews it.
kyle-sexton commentedon Oct 22, 2026
This was generated by AI during attend-queue.
Decision defaulted: A — accept the ten node-only Stop rows at the exec-form floor and record it in docs/conventions/hook-budget/README.md — veto before merge
Basis: verified, https://code.claude.com/docs/en/hooks.md (line 398: "When an event fires, its matching hooks run in parallel"); docs/conventions/hook-budget/README.md:159 (exec-form k of 1)