typos-format: hook silently corrupts abbreviated git SHAs, including inside backticks

[kyle-sexton]

This was generated by AI during a session in github-iac, where the defect was hit live.

Defect

The typos-format PostToolUse hook silently rewrote an abbreviated git SHA in a file I had just
written, corrupting it. 534caf5 became 534calf5 — caf "corrected" to calf.

I only caught it because I re-read the file. The hook reports its rewrite as "likely a formatter"
via the PostToolUse notice, which does not say what changed, so an agent that writes and moves on
ships the corruption. That is the actual severity here: silent data corruption in agent-authored
files, not a cosmetic annoyance.

Reproduction — minimal and verified

typos-cli 1.44.0, on this file:

short `534caf5`
long `534caf5d6ebab90faf8c1932c5d8007cba3710b9`
bare 534caf5
other short sha `1a2caf9`

error: `caf` should be `calf`   typotest.md:1:11    (inside backticks)
error: `caf` should be `calf`   typotest.md:3:9     (bare)
error: `caf` should be `calf`   typotest.md:4:21    (different SHA, also inside backticks)

Two findings worth separating:

1. Backticks are not respected. Two of the three hits are inside inline code spans. A code span
   is the canonical way to mark "this is a literal, do not language-process it", and the hook writes
   through it anyway. Any identifier, hash, hex color, or flag inside backticks is exposed.
2. The 40-character SHA is NOT flagged — only the 7-character abbreviated form. typos has a
   heuristic that skips long hex strings and recognizes them as hashes; a 7-char abbreviated SHA is
   below that threshold and gets word-split instead. So the corruption specifically targets the
   short SHA form, which is exactly the form used in prose, changelogs, handoffs, ADRs, and commit
   references.

It is not limited to caf. Any abbreviated SHA whose hex happens to contain a token in the typos
dictionary is a candidate — 1a2caf9 above is a second example, and the dictionary is large.

Why the existing config gate does not cover this

#884 established that the hook must not be a no-op on zero-config repos. Correct — but the
consequence is that it now runs with stock typos defaults on repositories that never opted in and
have no _typos.toml to add an extend-ignore-re. github-iac is exactly that case. So the
population most exposed to this is the one with no mechanism to defend against it.

Suggested direction (not a decision — the maintainer's call)

Options, roughly in increasing order of effort:

1. Ship a baseline extend-ignore-re with the hook covering abbreviated git SHAs
   (\b[0-9a-f]{7,40}\b) and inline code spans, so zero-config repos inherit a safe floor rather
   than stock defaults.
2. Report-only on zero-config repos, auto-fix only where a repository opted in by shipping a
   config. Preserves typos-format: opt-in config-gate makes the hook a silent no-op on zero-config repos, defeating the plugin's own auto-fix purpose #884's intent (not a silent no-op — it still surfaces findings) without
   write-through on repos that never asked for it.
3. Make the PostToolUse notice name the rewrite — a diff, or at minimum the corrections applied.
   Worth doing regardless of which of the above is chosen: a silent rewrite an agent cannot see is
   the part that turns a false positive into shipped corruption.

Acceptance

• An abbreviated git SHA survives the hook unchanged, in prose and inside backticks
• Zero-config repositories do not get destructive stock-default autocorrection, or the floor they
  get is explicitly chosen rather than inherited
• When the hook rewrites a file, what it changed is visible to the caller

Related

• typos-format: opt-in config-gate makes the hook a silent no-op on zero-config repos, defeating the plugin's own auto-fix purpose #884 — the config-gate fix whose zero-config behavior this defect rides on
• feat(typos-format): per-file typos autofix hook plugin #831 — the original hook

[kyle-sexton]

This was generated by AI during an autonomous work-loop cycle.

Classification: C3 scoped, bug-fix-shaped. No recorded ratification found in this issue's body or comments, and first_drain_complete is still false for this lane. Per the admission gate's first-drain ratification rule, this item is queued rather than dispatched: it needs either its own recorded ratification or a completed first drain before autonomous execution.

Intended dispatch, once ratified: claim, reproduce the abbreviated-SHA corruption against the typos-format PostToolUse hook's current matcher/rewrite logic, add a regression fixture (backticked and bare abbreviated SHAs), scope the fix to the false-positive pattern only, open a PR closing #1257.

agent-ready removed and needs-human applied for this cycle — dual role-label state is a contradiction. Restores to the autonomous frontier automatically once ratified (the ratification travels with the item; no re-queue needed).

[kyle-sexton]

Automated comment from an AI agent (autonomous triage lane).

Claiming this item to audit its first-drain C3 ratification gate. This lane changes no code and opens no PR; any label change will be recorded in a follow-up comment on this issue.

[kyle-sexton]

Gate audit: this item stays gated (not ratified)

Automated comment from an AI agent (autonomous triage lane). This lane changed no code, opened no PR, and changed no label.

This audits the first-drain C3 ratification gate, not the defect. The defect is real and
reproduces exactly as reported — verified this session against typos-cli 1.44.0 on the
reporter's own fixture: three hits, two inside inline code spans, and the 40-character SHA on line 2
correctly skipped. Priority is not in dispute.

The only question audited: should an autonomous agent pick and implement a remediation without a
human first approving the approach? A three-seat panel says no, unanimously.

Panel

Each seat received ONLY this issue's title and body. Withheld from every seat: the work-class
label, the kind=ratify-c3 marker comment, and every prior lane conclusion. No seat was told what
any other seat or any earlier lane concluded.

Seat	Who	Class	(e) human call?	Autonomous PR without approval?	Confidence
A	Fresh Claude reviewer, clean context, required to ground in the real hook source	C4	YES	NO	high
B	OpenAI Codex (different vendor)	C4	YES	NO	high
C	This triage agent's own read, formed before reading A or B	C4	YES	NO	high

Seat B disclosure: Codex's Windows sandbox helper failed to launch on this machine, so it reasoned
from the issue text alone and could not read the hook source. Its verdict is recorded as-is and is
not counted as code-grounded evidence. Seats A and C are independently code-grounded.

Consensus: C4 (structural / contract-level), not C3

Reasoned explicitly rather than reflexed, unanimous: this is not a security-surface change — a
data-integrity/correctness defect in a formatter hook, with no authn, authz, secret-handling, or
trust-boundary surface. It is not a dependency-pin/checksum/SHA-pin change — the SHAs are file
content (commit references in prose), not lockfile or action pins; "SHA" is a surface word-match
only. It is not hard to reverse (a git revert, or a sync round). It is cross-cutting, and it
is a product call a human must make.

Four independent blockers, any one sufficient:

1. The report defers the choice, in its own words: "Suggested direction (not a decision — the
maintainer's call)." Acceptance criterion 2 is itself phrased as a choice — "or the floor they get
is explicitly chosen rather than inherited." An agent picking a branch unattended would be making
the call, not executing it. Options 1 and 2 are mutually exclusive in posture with materially
different blast radius.

2. The work is owned by a different repository. _typos.toml is a managed component owned
by melodic-software/standards (distribution/sync-manifest.yml, component typos) — 7 managed
consumers, 0 locally-owned: this repo, github-iac, dotfiles, ci-workflows, medley,
ci-runner, .github. All three copies checked are byte-identical (md5 28256b7e…). The config
fix belongs in an upstream standards PR, not here.

3. The plugin-side variant of option 1 is not implementable as written. typos exposes no
--extend-ignore-re CLI flag; the only injection point is -c/--config, which replaces the
consumer's config wholesale — and typos has no config layering. Shipping a hook-side floor would
destroy every consumer's own allow-lists. It would also reverse the hook's documented contract:
"this hook never re-implements that walk itself" (hook source), "The rules themselves are never
configured here" (README).

4. The literal regex proposed is empirically unsafe. Seat A brute-forced the entire 7- and
8-character [a-f] space against the typos dictionary and A/B-tested \b[0-9a-f]{7,40}\b:

WITHOUT: ebedded→embedded, becacdd→because, caf→calf, adddress→address
WITH:    adddress→address              # the first three silently swallowed

ebedded → embedded is a plausible real-world typo. The regex trades genuine typo detection for
SHA safety — a policy decision, not a mechanical edit.

The report is partly stale, and one premise is false

#	Acceptance criterion	Status	Evidence
1	Abbreviated SHA survives unchanged, in prose and backticks	OPEN	Reproduced live on typos 1.44.0. standards/_typos.toml has a GUID/UUID extend-ignore-re entry but no SHA pattern.
2	Zero-config repos not destructively autocorrected, or floor explicitly chosen	OPEN, premise false	See below.
3	Hook's rewrites visible to the caller	ALREADY CLOSED	PR #1580, merged 2026-07-26 (v0.4.0), closing #1578. Disclosure code is live on main.

• Criterion 3 is already delivered. fix(typos-format): disclose every applied correction on both channels #1580 made the hook scan read-only, then write, then derive
  applied = scan-minus-residual, reporting every correction (token, replacement, line) on both
  additionalContext and systemMessage. It closed typos-format rewrites file content on every edit with no user-visible disclosure #1578, not this issue, so this issue was never
  rescoped against it — the report's framing that "the notice does not say what changed" no longer
  describes main.
• The github-iac premise is false. The report states github-iac has "no _typos.toml to add
  an extend-ignore-re". Verified: github-iac is a managed: typos target, _typos.toml is
  present on disk, byte-identical to canonical, and already contains an extend-ignore-re array
  — including a direct precedent for this exact defect class (a braced GUID/UUID entry added because
  "a mixed-case one trips the word splitter on its hex segments"). The cited repo is not
  defenceless; it is already covered by the managed seam.

The open question a human must answer

Criterion 3 is delivered and the github-iac premise is false. For criterion 1, does the
abbreviated-SHA floor go upstream into melodic-software/standards' _typos.toml (following the
existing GUID precedent, fanning out to 7 consumers) — and with which pattern, given that the
proposed one demonstrably suppresses real typos? And does criterion 2 survive at all once the
zero-config premise is corrected?

Options

Option A — RECOMMENDED: rescope this issue against current main, then route the survivor
upstream. Strike criterion 3 as delivered by #1580, correct the github-iac premise, and re-file
the surviving SHA-floor decision as a melodic-software/standards issue against the canonical
_typos.toml — following the GUID/UUID entry already there. Pair it with a narrower pattern than
the one proposed (e.g. anchored to require at least one digit, so all-alpha dictionary words like
ebedded stay checkable). This is the only option that both routes the work to its owner and
converts the remainder into something an agent can execute without deciding policy.

Option B — decide criterion 2 on its merits as a separate item. With the cited example
disproved, the genuinely-zero-config population is unquantified. Ask for evidence of a real
zero-config consumer before changing the fleet default, rather than reversing #884/#900 on a premise
that did not hold for the repo that motivated it.

Option C — ratify as-is for autonomous execution. Rejected by all three seats. An agent would
choose between mutually exclusive directions, in a repository that does not own the change, from a
problem statement that is one-third stale and carries a false premise.

Option D — stopgap only. The shipped typos_format_write_changes userConfig (default true)
already gives report-only behaviour with no code change. Scope limit: it is user-scope
configuration, not per-repository, so disabling it suppresses rewriting everywhere for that user
rather than only on exposed repos.

---

Procedural note: this gate requires a human ratification recorded as a reply on the
kind=ratify-c3 marker. An autonomous lane cannot supply that on a human's behalf, so even a
favourable panel would have produced a recommendation to ratify, never a ratification.

Labels unchanged — needs-human stays, agent-ready is not applied. The item remains queued
rather than dispatched.

[kyle-sexton]

Automated comment from an AI agent (autonomous triage lane): claim released. Gate audit complete — item left gated, no labels changed.

[kyle-sexton]

Automated comment from an AI agent (autonomous triage lane) — addendum to the gate audit above. No labels changed.

Three claims in the audit above were re-verified directly by this lane rather than resting on a single seat's report. All three hold, and one gains a detail that matters for how the issue is rescoped:

• The github-iac premise was false at filing time, not merely stale now. _typos.toml was added to github-iac in 933267e on 2026-06-23 — a month before this issue was filed on 2026-07-25. So criterion 2's motivating example never held. That argues for rescoping the issue rather than refreshing it.
• --extend-ignore-re is not a typos CLI flag. Confirmed against typos-cli 1.44.0: the only configuration entry points are -c, --config <CUSTOM_CONFIG> (a replacement config file) and --isolated. A hook-side ignore floor cannot be injected without displacing the consumer's own config.
• The proposed regex suppresses genuine typos. Confirmed directly: ebedded → embedded and becacdd → because are both real dictionary findings, and both are 7-character all-hex tokens that \b[0-9a-f]{7,40}\b matches. adddress → address survives only because r/s fall outside [0-9a-f] — which is what makes the pattern's blast radius accidental rather than designed.

Nothing here changes the audit's disposition; it removes the single-source dependency under it.

[kyle-sexton]

Independent agent audit of typos-format 0.4.2 hit this defect class again on a different token, and turned up material that changes the fix rather than just adding another instance. Recording it here rather than opening a duplicate.

Notation: the token at the centre of this is a three-letter Win32 shell-flag prefix — F, then O, then F. It is written as <P> throughout, because writing it literally causes this hook to rewrite the text describing it. That happened three times while producing this report, including to a verbatim upstream dictionary citation and to two of upstream's own false-positive documentation examples.

The cross-file case, which is worse than single-file corruption

This issue's example is corruption inside one file. Reproduced here, the same mechanism breaks a build:

• Consumer.cs referencing ShellFlags.<P>_SILENT and ShellFlags.<P>_ALLOWUNDO was created without going through Write, so no hook fired on it.
• ShellFlags.cs declaring those constants was then written through Write. The hook reported REWROTE 2 word(s), "<P>" -> "FOR" on both lines.
• On disk the declaration now reads FOR_SILENT / FOR_ALLOWUNDO while the untouched consumer still reads <P>_SILENT / <P>_ALLOWUNDO.

That is an unconditional compile error. The hook receives one file_path per invocation, so a rename is only ever self-consistent when every declaration and use happens to sit in the single edited file. Any project where a dictionary-hit identifier crosses a file boundary breaks on the first edit to either side. Same reasoning covers a string literal compared against a constant elsewhere.

Root cause, from this plugin's own CHANGELOG

0.1.0 gated the hook on a consumer typos config found by an ancestor walk-up. 0.2.0 removed that opt-in gate and kept --write-changes on.

The presence of a typos config was the consent signal — the artifact by which a project says "we adopted this tool, we accept its dictionary, and we maintain an allowlist for our own vocabulary." 0.2.0 deleted that signal and replaced it with nothing, so write authority over every file on every edit now derives from the plugin merely being installed.

0.2.0's stated reason is sound and worth preserving: typos is useful with zero configuration, and gating on a config defeated the zero-config purpose. But that argument supports unconditional reporting, which mutates nothing and needs no consent. It does not support unconditional writing. The gate was removed at the wrong altitude — activation rather than write authority.

The recommended remediation is unreachable for the files that got hit

The messages say "add it to your typos config" and name extend-words / extend-identifiers. Verified against upstream:

• There is no user or home config layer, by design. docs/reference.md's precedence list is CLI args, --config PATH, then a parent-directory search for typos.toml / _typos.toml / .typos.toml / Cargo.toml / pyproject.toml. docs/design.md states the choice explicitly: "Machine-independent, repo-specific configuration — As compared to layered config with the users system."
• The files corrupted here live under ~/.claude/plugins/data/, in no repository, with no reachable config ancestor. So the advice pointed at a file that cannot exist.
• Discovery is first-match-wins, not merged (verified: a nearer _typos.toml completely shadowed a higher one). So even a high-ancestor safety net is shadowed by every repo that has its own config. Config-based allowlisting cannot serve as a fleet-wide net.
• The two named options are not interchangeable and the message gives no basis to choose. extend-identifiers matches the whole identifier, so allowlisting four constants needs four entries; extend-words fixes the shared segment in one entry but disables that correction everywhere in scope.
• There is no inline escape hatch at all. Verified: typos does not honour # spellchecker:off / # spellchecker:on. Notably this plugin's own typos-format.test.sh wraps its intentional-misspelling fixture table in exactly those markers, so the fixtures are "protected" by a directive the tool ignores.

Catch-22, demonstrated

Writing the allowlist entry gets the allowlist entry rewritten. A dictionary file at a name typos does not auto-discover was written through Write, and the hook reported rewriting both sides of a <W> = "<W>" entry, producing a no-op that allowlists the correctly-spelled word. A file at a discovered name (_typos.toml) does self-protect because typos honours it while scanning it — but that depends on the filename and nothing tells the user so.

And there is no shell escape: the fleet's own block-hook-bypass.sh refuses echo/printf redirection to a file. Every file an agent creates must go through Write/Edit, and therefore through this hook. Ordering note for whoever fixes that guard: closing its remaining write-bypass leak removes the last escape hatch while this hook still writes by default. Sequence write authority first.

One separate, cheap defect found alongside

The residual message collapses an explicitly ambiguous finding into a single false recommendation. typos-format.sh:338 renders should be "\(corr1)", i.e. .corrections[0]. Reproduced by direct invocation: a token for which typos offered want and what, and specifically refused to choose, was reported as should be "want". A reader who trusts it applies a coin-flip to their own prose.

Display-only fix — the telemetry findings array already carries the full corrections list, so only the rendered string discards it. Render all candidates and say typos declined to pick.

What this suggests for the fix, cheapest first

1. Flip the shipped default of typos_format_write_changes to false. One line. Write mode becomes opt-in; removes this whole class immediately while preserving 0.2.0's zero-config reporting win untouched. Verified working: with it false the file is byte-identical afterwards and findings still surface.
2. Fix the ambiguous-residual message. Independent of the write-mode decision and worth doing regardless.
3. Re-establish a write gate on governing config — report unconditionally, write only when a typos config actually governs the target path. This re-derives the consent signal 0.1.0 had, at the right altitude this time. It also makes the remediation message truthful, and it excludes ~/.claude/plugins/data/ for free since no config governs it. Use typos --dump-config or an equivalent supported probe rather than re-implementing discovery.
4. Exclude machine-owned state paths from write mode explicitly. Largely subsumed by 3, but the harm is qualitatively different: corrupting durable evidence another reader treats as fact.

Explicitly not recommended: restricting rewrites by file extension. Markdown routinely carries fenced code and identifiers while a .ps1 is mostly code with prose only in comments, and typos has no comment-vs-code parser — so an extension allowlist trades a visible failure for a quieter one while implying a safety property it does not have.

What the hook gets right, since it is the reason any of this was caught

Per-rewrite disclosure with word, direction, and line number. Given that the harness notice names only the file, this is the sole content-level account of a mutation that exists anywhere. It separates applied from merely-flagged findings, names the dictionary source, scans before writing so a run killed between passes has mutated nothing, and derives the applied set as scan-minus-residual rather than guessing.

Two caveats on that disclosure, worth their own line in whatever fix lands: MAX_REPORT=10 caps it, so an eleventh wrong rewrite is disclosed only as "… and N more"; and data.applied, the envelope field added in 0.4.0 to record what a run rewrote, is emitted nowhere when no telemetry sink is configured. So the only defense is both bounded and non-durable.