Skip to content

perf(hooks): Stop wall p95 back over the 2,000 ms budget on a loaded Windows host #8770

Description

@kyle-sexton

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-timing in a 2026-10-20 /performance:go-faster run,
    104 timed samples per hook, Stop event only. Wall numbers: recomputed this pass from the same
    transcript's 125 stop_hook_summary records as the max durationMs per 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.json Stop row;
    manifest default false, plugins/markdown-format/.claude-plugin/plugin.json:30-35). On the
    measuring host none of those options is set (user pluginConfigs checked), and the installed
    versions match main (markdown-format 0.14.2). So these rows exit inside exec-bash.mjs at 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-only and 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 in docs/conventions/hook-budget.
  • B. async: true on 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 needs asyncRewake (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.md records that default-off Stop rows that exit at the exec-bash.mjs option 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.json changes.
  • 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 --check requires 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

  1. github-actions commented on Oct 21, 2026

    @github-actions
    Contributor

    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.

  2. added
    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.
    on Oct 21, 2026
  3. added
    status: readyTriaged, unblocked, and fully specified; eligible to pick up.
    and removed
    needs-owner-decisionAwaiting a human or maintainer judgment call.
    needs-humanHuman-in-the-loop required; autonomous sessions must not resolve items carrying this.
    on Oct 22, 2026
  4. kyle-sexton commented on Oct 22, 2026

    @kyle-sexton
    MemberAuthor

    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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readyFully specified and briefed; eligible for autonomous pickup from the frontier.status: readyTriaged, unblocked, and fully specified; eligible to pick up.

    Type

    Fields

    No fields configured for Task.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions