You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
fleet: concurrent PostToolUse hook writes can silently clobber each other (no locking/ordering) #875
Claude Code runs every matching PostToolUse hook in parallel for one tool call. Multiple hooks in this fleet write to the same edited file with no locking or ordering primitive between them:
Any file matched by both an unscoped writer and a scoped formatter (e.g. any .py file, with eol-normalizer and ruff-format both applicable — or, once #872 merges, typos-format and ruff-format on any .py file governed by both a typos config and a Ruff config) has two hooks independently reading-then-writing the same file with no coordination. A nondeterministic clobber is possible: whichever write lands last silently discards the other's fix.
Surfaced explicitly during #872's stress-test and independent review; documented (not fixed) in typos-format's hook header comment and README "Known limitation" section as a pre-existing, fleet-wide gap this single plugin cannot address.
Impact
Low-frequency (requires two applicable hooks + concurrent scheduling), but silent when it hits — no error, no diagnostic, just a dropped fix. Grows with every new unscoped or overlapping-scope hook plugin added to the fleet.
Constraints
No native Claude Code feature exists today for sequential/ordered hook execution within one event (verified during #872's research). Any fix is either:
A convention/pattern this repo's hooks adopt (e.g. a shared file lock via flock, already used elsewhere in hook::append_jsonl).
An upstream feature request to Claude Code for ordered or serialized PostToolUse hook execution.
T2 plan brief — concurrent PostToolUse write clobber
1. flock precedent — CONFIRMED, but not cross-platform
hook::append_jsonl (lib/hook-utils.sh, the single source of truth synced to plugins/*/hooks/hook-utils.sh via scripts/sync-hook-utils.sh; CI rejects drift) already serializes a shared-file write under an advisory lock:
The pattern (subshell holding fd 9 on a sidecar ${file}.lock, bounded -w 2 wait) is exactly what a per-target-file lock needs. Wrapping each writer hook's full read-then-write span under the same ${file}.lock name would serialize concurrent hooks: hook A locks → reads v0 → writes A(v0) → unlocks; B then reads A(v0) → writes B(A(v0)). Both fixes compose. That cooperative requirement — every writer wraps its entire read-modify-write under the same lock path — is what makes this a convention, not a local change.
Caveat (decisive):flock is not bundled with the standard Git-for-Windows / cygwin install — verified absent in the maintainer's own environment (cygwin bash 5.3.9). So append_jsonl's flock arm degrades to the bare-append fallback on Windows. A dropped telemetry line is acceptable; a dropped formatter fix is the exact bug #875 is killing. A straight flock reuse therefore provides zero protection on the primary dev platform.
2. Retrofit scope — bounded helper, but no clean cross-platform primitive
Writer hooks (read-then-write on PostToolUse), all verified to exist:
~6 plugins (7 with #872). Each has a boundable mutation region: 2 inspected — eol-normalizer.sh (single normalize_eol_file call) and ruff-format.sh (ruff check --fix + ruff format, lines 212–213); the other 4 are presumed-similar (ruff's header states it mirrors the sibling formatters). Shape = one helper (hook::with_file_lock <file> -- <cmd…>) in lib/hook-utils.sh + sync + ~6 one-line call-site wraps. Bounded convention change, not a per-plugin refactor.
Two design forks make it more than a drop-in:
No auto-release with portable locks. flock's load-bearing property is auto-release on process exit. The portable alternatives (mkdir atomic-create spinlock, or set -C noclobber-create) do not auto-release: a crashed/timed-out hook leaves a stale lock, and every later contended edit eats the full timeout. Stale-lock reaping is a real design decision.
Add a cross-platformhook::with_file_lock to lib/hook-utils.sh — mkdir-based (present everywhere; flock absent on Windows), with stale-lock reaping and block-preferring contention (never silently skip a formatter).
Retrofit the ~6 writer hooks to wrap their full read-modify-write span under ${file}.lock.
File the upstream Claude Code request for ordered/serialized PostToolUse execution as the durable fix (the lock is a mitigation). Re-confirm the "no native ordered-hooks feature" finding against current CC docs first — it was verified during feat(typos-format): add per-file typos autofix hook plugin #872 and CC moves fast.
Routing = needs-human, because the obvious decision-defaulted answer ("reuse the append_jsonl flock pattern") is empirically disproven on the maintainer's own platform, and the remaining choices are genuine open forks: (a) cross-platform lock primitive + stale-lock strategy, (b) contention semantics (block vs skip), (c) doc-home — standalone convention doc vs epic #830 items 6/7, (d) mitigation-now vs wait-for-upstream sequencing. A maintainer must pick; the default above is well-grounded but not auto-adoptable.
Triage → needs-human + wayfind: design. T2 Opus planning pass (full plan in the sibling comment above). Verified the reporter's flock lead empirically: hook::append_jsonl does use flock -w 2 on a sidecar lock — but flock is NOT cross-platform (absent on the maintainer's Windows/cygwin bash → degrades to unsynchronized append), so the drop-in flock reuse is disproven on the maintainer's own platform. Retrofit itself is bounded (one hook::with_file_lock helper + ~6-7 one-line call-site wraps). Human-gated because the residual forks are genuine open convention design: cross-platform lock primitive + stale-lock reaping, block-vs-skip contention semantics, doc-home (standalone vs epic #830 items 6/7), and mitigate-now-vs-upstream-request. A strong recommended default is supplied in the plan for the maintainer to ratify or veto. Priority medium (rule 5; reporter impact LOW / low-frequency, but a genuine silent-dropped-fix class — noted for sub-sorting; touches priority-set hooks). Type Bug.
Issue remains historically valuable but is either advisory, blocked on a larger carrier, or superseded by later conventions. Re-open with a concrete acceptance brief if a consumer needs the work this session.
Title: fleet: concurrent PostToolUse hook writes can silently clobber each other (no locking/ordering)
Activity
kyle-sexton commentedon Jul 21, 2026
This was generated by AI during triage.
T2 plan brief — concurrent PostToolUse write clobber
1. flock precedent — CONFIRMED, but not cross-platform
hook::append_jsonl(lib/hook-utils.sh, the single source of truth synced toplugins/*/hooks/hook-utils.shviascripts/sync-hook-utils.sh; CI rejects drift) already serializes a shared-file write under an advisory lock:The pattern (subshell holding fd 9 on a sidecar
${file}.lock, bounded-w 2wait) is exactly what a per-target-file lock needs. Wrapping each writer hook's full read-then-write span under the same${file}.lockname would serialize concurrent hooks: hook A locks → reads v0 → writes A(v0) → unlocks; B then reads A(v0) → writes B(A(v0)). Both fixes compose. That cooperative requirement — every writer wraps its entire read-modify-write under the same lock path — is what makes this a convention, not a local change.Caveat (decisive):
flockis not bundled with the standard Git-for-Windows / cygwin install — verified absent in the maintainer's own environment (cygwin bash 5.3.9). Soappend_jsonl's flock arm degrades to the bare-append fallback on Windows. A dropped telemetry line is acceptable; a dropped formatter fix is the exact bug #875 is killing. A straight flock reuse therefore provides zero protection on the primary dev platform.2. Retrofit scope — bounded helper, but no clean cross-platform primitive
Writer hooks (read-then-write on PostToolUse), all verified to exist:
eol-normalizer(verified) ·typos-format(pending feat(typos-format): add per-file typos autofix hook plugin #872)ruff-format,markdown-format,biome-format,bash-format,powershell-format(all verified present)~6 plugins (7 with #872). Each has a boundable mutation region: 2 inspected —
eol-normalizer.sh(singlenormalize_eol_filecall) andruff-format.sh(ruff check --fix+ruff format, lines 212–213); the other 4 are presumed-similar (ruff's header states it mirrors the sibling formatters). Shape = one helper (hook::with_file_lock <file> -- <cmd…>) inlib/hook-utils.sh+ sync + ~6 one-line call-site wraps. Bounded convention change, not a per-plugin refactor.Two design forks make it more than a drop-in:
mkdiratomic-create spinlock, orset -Cnoclobber-create) do not auto-release: a crashed/timed-out hook leaves a stale lock, and every later contended edit eats the full timeout. Stale-lock reaping is a real design decision.append_jsonldrops the line on-w 2timeout. For a formatter, "drop on timeout" = silently skip the format = reintroduces the very silent-clobber fleet: concurrent PostToolUse hook writes can silently clobber each other (no locking/ordering) #875 targets. Block-longer vs skip-on-timeout must be chosen deliberately.3. Recommendation (default) + routing: NEEDS-HUMAN
Recommended default a maintainer should ratify:
hook::with_file_locktolib/hook-utils.sh—mkdir-based (present everywhere; flock absent on Windows), with stale-lock reaping and block-preferring contention (never silently skip a formatter).${file}.lock.Routing = needs-human, because the obvious decision-defaulted answer ("reuse the append_jsonl flock pattern") is empirically disproven on the maintainer's own platform, and the remaining choices are genuine open forks: (a) cross-platform lock primitive + stale-lock strategy, (b) contention semantics (block vs skip), (c) doc-home — standalone convention doc vs epic #830 items 6/7, (d) mitigation-now vs wait-for-upstream sequencing. A maintainer must pick; the default above is well-grounded but not auto-adoptable.
kyle-sexton commentedon Jul 21, 2026
This was generated by AI during triage.
Triage →
needs-human+wayfind: design. T2 Opus planning pass (full plan in the sibling comment above). Verified the reporter's flock lead empirically:hook::append_jsonldoes useflock -w 2on a sidecar lock — but flock is NOT cross-platform (absent on the maintainer's Windows/cygwin bash → degrades to unsynchronized append), so the drop-in flock reuse is disproven on the maintainer's own platform. Retrofit itself is bounded (onehook::with_file_lockhelper + ~6-7 one-line call-site wraps). Human-gated because the residual forks are genuine open convention design: cross-platform lock primitive + stale-lock reaping, block-vs-skip contention semantics, doc-home (standalone vs epic #830 items 6/7), and mitigate-now-vs-upstream-request. A strong recommended default is supplied in the plan for the maintainer to ratify or veto. Priority medium (rule 5; reporter impact LOW / low-frequency, but a genuine silent-dropped-fix class — noted for sub-sorting; touches priority-set hooks). TypeBug.feat(typos-format): add per-file typos autofix hook plugin (#872)
fix(typos-format,markdown-format): single-writer default ends the unc…
kyle-sexton commentedon Aug 13, 2026
Frontier disposition (drain session)
Ruling: Close as not planned for this drain wave.
Issue remains historically valuable but is either advisory, blocked on a larger carrier, or superseded by later conventions. Re-open with a concrete acceptance brief if a consumer needs the work this session.
Title: fleet: concurrent PostToolUse hook writes can silently clobber each other (no locking/ordering)