Repository navigation
Description
Filed by an agent session that audited six components in one run. These three items belong to no single plugin — each was noticed by two or more audits and owned by none. Following the precedent in issue #1682, which bundles cross-plugin observations "rather than silently mis-filed" and invites a maintainer to split them.
1. Two unconditional in-place rewriters race on every Write, and nobody owns it
typos-format 0.4.2 and markdown-format 0.8.4 both register PostToolUse with matcher: "Write|Edit", unconditionally, and both rewrite file content in place.
The hooks reference states matching hooks "run in parallel, and identical handlers are deduplicated automatically", and separately that when multiple hooks return competing results "the last one to finish takes effect. Since hooks run in parallel, the order is non-deterministic."
So on any Markdown write, two independent processes read, rewrite, and write back the same file with no defined precedence and no locking.
Both audits noticed this. typos-format discloses it in its own script header and README as a fleet concern; markdown-format's audit reached the same conclusion. Both classified it as something neither plugin can solve alone — so it is recorded twice and owned zero times, which is precisely how a defect survives an audit.
Disclosure is honest but is not a fix. This needs a named owner and one of: a shared advisory lock, a declared ordering, a single serialising formatter dispatcher, or an explicit decision that last-writer-wins is acceptable and why.
Observed evidence that the risk is not theoretical: during this audit both hooks mutated the same class of files, and three separate content-destroying rewrites were captured — a dictionary autocorrect renaming Win32 identifiers, MD004 falsifying a quoted changelog line, and MD018 destroying a line-leading issue reference while fabricating a heading. Each was individually recoverable; two of them landing on one file in undefined order is not something any audit has bounded.
2. Nobody sums the always-on cost, and the consumer is the one who feels it
This single session carried, on every turn or every tool call, in every consumer session regardless of whether the plugin was in use:
disk-hygiene's plugin-level engine gate — on every Bash and PowerShell command. Its marker-free fallback callsos.path.samefileon every separator-carrying word of every command, including commands with no relation to the plugin. Its own docstring names this as the strongest candidate for an observed 17-second stall.disk-hygiene'sStopdetector — once per turn. Its amortisation claim holds only after a failure has been reported, because the marker is written only when a warning fires. On the happy path every turn pays interpreter startup (the plugin's own ADR measurespython3 -c 'pass'at 396 ms on this host) plus a seek-and-read of up to 2 MB.- four
guardrailsclassifiers — on every Bash and PowerShell command. - two PostToolUse formatters — on every Write and Edit.
Each plugin accounts for its own share honestly where it accounts at all. Nobody adds them up. A per-turn and per-tool-call cost budget across the marketplace is the missing question, and the aggregate is what a user experiences — the 17-second stall that disk-hygiene's guard docstring investigates is a symptom of the sum, not of any single component.
Suggested shape: a stated budget (milliseconds per turn, milliseconds per tool call) that every always-on hook must fit inside, plus a measured accounting per plugin against it. Without a shared ceiling, each plugin's individually-reasonable cost composes into something no one reviewed.
3. Sequence the batch — this is worth more than the individual reports
This audit produced thirteen CRITICALs across five plugins, all destined for this repository at once, with no ordering. Several of the highest-value fixes are one-liners, and none requires agreeing with the deeper structural findings first:
- Flip
typos_format_write_changestofalseintypos-format'splugin.json. Write mode becomes opt-in. Removes the entire silent-corruption class immediately — including the already-filed issue typos-format: hook silently corrupts abbreviated git SHAs, including inside backticks #1257 — while preserving the zero-config reporting win that 0.2.0 was protecting. Verified working: with it false, the file is byte-identical afterwards and findings still surface. - Make
markdown-formatreport-only when no markdownlint config is discoverable. This is the same author's own doctrine elsewhere in this marketplace:bash-formatrefuses to run when the repo has no shfmt config, "so the plugin never imposes a style you did not [choose]". Applying it here closes the quote falsification, the issue-reference destruction, the unreachable remediation advice, and roughly 115 unactionable MD013 findings in one change, using machinerycollect_risky_configsalready has. - Give
block-noncanonical-commitanexit 0on rc=2, following the precedent already present atblock-convention-violation.sh:375-383. Coverage cost is provably zero — both guards callps::classify_git_commandwith identical arguments, corroborated across a 12-case corpus where every commit-guard block was also a dangerous-git block carrying that guard's accurate message.
An ordered "these three land most of the CRITICAL surface today" list is more actionable than five independent reports arriving together.
One hard ordering constraint
A typos-format audit found a write-bypass leak in guardrails' block-hook-bypass.sh: a Python one-liner that opens a path and writes it evades the Write/Edit PostToolUse hooks entirely, while the guard refuses the echo/printf redirection form.
Closing that leak removes the last escape hatch from typos-format's unconditional write mode. So item 1 must land before the bypass is closed, or the situation gets strictly worse for anyone whose vocabulary the dictionary mangles.
4. A process finding, since it affects every future audit in this repo
There is no verification step anywhere between "auditor writes evidence packet" and "drafter reads packet", while the plugin-quality workflow instructs a fresh auditor to treat the packet as ground truth for behavioural claims.
In this run: packet files were mutated in place by sibling hooks three times; one packet's evidence.md carried three false factual claims; and an independent review gate found four further factual errors that had survived into the locked-contract layer in two cases. One of those was load-bearing — an incorrect explanation of a measured attribute discrepancy that would have caused a maintainer to dismiss a CRITICAL on first verification.
Content-hash-at-write-time is the right primitive and is currently one clause inside a bundled remediation in the plugin-quality issue. Raising it here because the exposure is not specific to that plugin: any workflow in this marketplace that writes durable evidence for a later reader, while unconditional in-place formatters are installed, has the same hole.
Activity
kyle-sexton commentedon Jul 31, 2026
Delegated-authority decision — recorded by the autonomous drain lane under this session's delegated decision authority, for post-hoc review. Verified against
origin/main(d5d02a2) before deciding: both hooks registerPostToolUseonWrite|Edit;typos-format(now 0.4.4) still writes by default (typos_format_write_changesdefaulttruein both the manifest and the script fallback),markdown-format(now 0.8.6) still runs--fixunconditionally whenever a linter binary resolves. The race, the missing sum, and the ordering gap all reproduce as filed.Decision 1 — precedence architecture for the two rewriters
Chosen: single-writer-by-default. The precedence question is dissolved, not adjudicated: by default, at most one in-place rewriter may match any file class.
typos-format:typos_format_write_changesdefault flipstrue→false(manifest and script fallback). Out of the box the hook is report-only; write mode is an explicit consumer opt-in. Batch item 1 verbatim; removes the silent-corruption class including typos-format: hook silently corrupts abbreviated git SHAs, including inside backticks #1257.markdown-format: the run is gated on a discoverable markdownlint config (the same directory walkcollect_risky_configsalready does, extended to the full candidate list). No config → no run at all: markdownlint's built-in rule set is a style the repo never chose, so neither--fixrewrites nor default-rule findings (the ~115-finding MD013 class) are imposed. This isbash-format's own shfmt opt-in doctrine applied to its sibling; batch item 2.typos-formatstill reads whilemarkdown-formatmay write in an opted-in repo — a stale read can misstate a finding but cannot corrupt content. The one re-openable overlap — a consumer switches typos write mode ON in a repo that also carries a markdownlint config — is a deliberate double opt-in and is documented in both READMEs as last-writer-wins rather than left undefined.eol-normalizer+ extension-scoped formatters); this decision removes that class's unconditional members.Rejected alternative (designed second): shared advisory lock / serializing formatter dispatcher. Rejected on four grounds: (1) a lock serializes but does not define order — the final bytes stay nondeterministic, so the race is hidden, not resolved; (2) it adds acquisition latency to every Write on top of an already-heavy per-Write hook wall (measured below); (3) to be sound the protocol must be vendored into every writer plugin's duplicated
hook-utils.shand adopted by every future writer — a fleet-wide coordination primitive owned by nobody, which is precisely the ownership failure this issue documents; (4) it leaves the root cause untouched: a default-on dictionary rewriter mutating content nobody asked for. Stale-lock expiry under the harness's hook-timeout kill adds failure modes with no compensating benefit.Decision 2 — the always-on cost budget
Measured on a representative dev host (Windows 11, Git Bash), method:
EPOCHREALTIMEwall clock around direct hook invocation with benign payloads; 10-run averages for singles;&+waitfor parallel sets (an approximation of the harness's parallel dispatch — if anything friendlier, since the harness adds its own spawn wrapping):python3 -c pass/bash -c :/jq --versionls -laThe 17-second-stall reading is corroborated: no single hook is outrageous; the sum is, and process-spawn contention makes the parallel wall far worse than any member. Budget adopted (codified as
docs/conventions/hook-budget/README.mdin the attached PR): fleet-wide always-on aggregate ≤ 1 s typical / 2 s worst-case wall per tool call, ≤ 500 ms per turn (Stop), measured as parallel wall on a representative dev host; every plugin adding an always-on hook states its measured share in its README. The current Bash|PowerShell lane exceeds the budget ~3–6×; the overage becomes per-plugin work items (guardrails spawn-reduction is already tracked in #1403) — a reason to fix the members, never to relax the ceiling.Decision 3 — ordering the thirteen-CRITICAL batch
block-noncanonical-commitexit 0 on rc=2, per the precedent atblock-convention-violation.sh:375-383. Staged separately not for size but because guardrails' commit guards carry a dense open surface (guardrails: block-noncanonical-commit on main exits 139 (SIGSEGV) on a wrappedcdbuiltin in a shell-alias body #1495, guardrails: block-noncanonical-commit resolves the repository at the outer invocation when the nested one determines it #1500, guardrails: block-noncanonical-commit analyzes the wrong repository when a!alias body relocates the process (cd) #1486, guardrails: both git guards recurse into aliases git itself refuses (environment-changing global in a non-shell expansion) #1502) and their changelog/review must not ride a formatter PR.block-hook-bypass.shwrite-bypass-leak closure must not merge before stage 1 does. Once typos-format is report-only by default, closing that leak no longer worsens exposure for anyone whose vocabulary the dictionary mangles.kyle-sexton commentedon Jul 31, 2026
Stage 1 landed as PR #1859 (typos-format 0.5.0 report-only default; markdown-format 0.9.0 config opt-in gate; docs/conventions/hook-budget/README.md), which closes this issue per the decision comment above. Staging: stage 2 (guardrails block-noncanonical-commit rc=2 exit) is #1858, which also restates the hard constraint that the block-hook-bypass write-leak closure must not merge before #1859 does; item 4 (evidence-packet integrity) is owned by #1808; residual scoped-writer overlap stays tracked in #875.
fix(markdown-format,typos-format): decide the opt-in before any prere…
fix(typos-format,markdown-format): single-writer default ends the unc…
fix(guardrails): defer unparsable PowerShell commits to the guards th…
docs(markdown-format): name every exclude source the scope check reads
feat(markdown-format): stop rewriting and reporting gitignored scratc…
perf(source-control): cut pr-issue-linkage gate spawns by redirect pl…