fleet: concurrent PostToolUse hook writes can silently clobber each other (no locking/ordering)

[kyle-sexton]

Summary

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:

• Extension-unscoped writers (no file-type filter): eol-normalizer, and now typos-format (feat(typos-format): add per-file typos autofix hook plugin #872) — both fire on every Write/Edit.
• Extension-scoped formatters: ruff-format (.py/.pyi), markdown-format (.md/.mdc), biome-format, bash-format, powershell-format.

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:

1. A convention/pattern this repo's hooks adopt (e.g. a shared file lock via flock, already used elsewhere in hook::append_jsonl).
2. An upstream feature request to Claude Code for ordered or serialized PostToolUse hook execution.

Related

• Surfaced during feat(typos-format): add per-file typos autofix hook plugin #872 (epic Epic: lint/static-analysis gap closure #830, docs/topics/lint-static-analysis-gaps/PLAN.md). Sibling epic item 6 (hook-observability convention) and item 7 (bespoke CI guards) may be a natural home for a locking convention if one is adopted; alternatively a standalone convention doc.

[kyle-sexton]

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 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:

if command -v flock >/dev/null 2>&1; then
  ( flock -w 2 9 || exit 0
    printf '%s\n' "$line" >>"$file"
  ) 9>"${file}.lock" 2>/dev/null
else
  printf '%s\n' "$line" >>"$file" 2>/dev/null   # bare append — NO lock
fi

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:

• Unscoped: eol-normalizer (verified) · typos-format (pending feat(typos-format): add per-file typos autofix hook plugin #872)
• Scoped formatters: 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 (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.
• Contention semantics. append_jsonl drops the line on -w 2 timeout. 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:

1. Add a cross-platform hook::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).
2. Retrofit the ~6 writer hooks to wrap their full read-modify-write span under ${file}.lock.
3. 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.

[kyle-sexton]

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_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.