feat(typos-format): add per-file typos autofix hook plugin

[kyle-sexton]

Summary

New hook plugin plugins/typos-format/: runs typos --write-changes on every Write/Edit, gated on a consumer typos config (typos.toml/_typos.toml/.typos.toml/Cargo.toml/pyproject.toml) found by an ancestor walk-up, mirroring the shipped ruff-format/markdown-format plugin pattern. Residual (unfixable) findings surface via additionalContext with remediation guidance pointing at extend-words/extend-identifiers/extend-ignore-re allowlist entries. Advisory only — never blocks the edit.

• Hook-precision + hook-telemetry convention conformance (schema + registry row added).
• /typos-format:setup check|apply skill.
• 44 black-box contract-test assertions (typos-format.test.sh), including a --force-exclude regression case added after independent review caught the flag was missing (verified empirically: without it, the hook silently overrode a consumer's own typos excludes).

Test plan

• typos-format.test.sh — 44/44 pass against real typos-cli 1.44.0.
• Full fleet scripts/run-plugin-tests.sh — all plugin contract tests pass.
• scripts/validate-plugins.sh (manifest schema, catalog sync, no-npx contract).
• scripts/sync-hook-utils.sh --check, check-silent-skips.sh, check-changelog-parity.sh --check, check-cross-plugin-source-drift.sh --check, check-skill-leaf-names.sh --check, check-changed-skills.sh origin/main.
• typos/shellcheck/markdownlint-cli2 self-check on all new files.
• Two independent fresh-context reviews (code review + security review via CI): one CRITICAL finding (missing --force-exclude) fixed + regression-tested; two SUGGESTION-level security notes triaged (one deferred as a fleet-wide pre-existing test-harness pattern, one out-of-scope for the shared hook-utils.sh library); two minor code-review notes fixed (test assertion strength, marketplace relevance block).

Review follow-ups filed

• docs(ruff-format): missing hook-telemetry data schema + registry row #874 — ruff-format is missing its hook-telemetry data schema + registry row (pre-existing docs-drift gap, surfaced while using it as a reference plugin).
• fleet: concurrent PostToolUse hook writes can silently clobber each other (no locking/ordering) #875 — fleet-wide: concurrent PostToolUse hook writes have no locking/ordering, so overlapping-scope hooks (e.g. this plugin + ruff-format, or eol-normalizer + any formatter) can silently clobber each other's fix. Documented as a known limitation in this plugin's header comment and README; not fixable at the single-plugin level.

Related

• Closes feat(typos-format): per-file typos autofix hook plugin #831 (epic Epic: lint/static-analysis gap closure #830, sub-item 1 of docs/topics/lint-static-analysis-gaps/PLAN.md, contract landed via docs: add lint/static-analysis gaps brief #829).

Implementation plan (docs/topics/typos-format-hook/PLAN.md, pruned from the tree after merge)

typos-format hook plugin

Brief

Issue #831 (epic #830, sub-item 1 of
docs/topics/lint-static-analysis-gaps/PLAN.md, merged via PR #829). New hook
plugin plugins/typos-format/: per-file typos -w autofix on Write/Edit,
mirroring the existing plugins/markdown-format/ and plugins/ruff-format/
patterns. Opt-in via consumer typos config ancestor walk-up (no config = no-op,
never impose typos' defaults on a repo that hasn't adopted it — same posture as
ruff-format). Advisory only, hook-precision + hook-telemetry conventions,
setup skill (check/apply).

Scope: Tier C (no design) — pure pattern replication of two already-shipped,
gate-passing plugins; no new types, no new architecture.

Plan

Phase 1: Hook plugin skeleton

Files (new): .claude-plugin/plugin.json, hooks/hooks.json,
hooks/hook-utils.sh (synced copy of lib/hook-utils.sh),
hooks/typos-format.sh, .claude-plugin/marketplace.json entry.

Hook control flow (modeled on ruff-format.sh): kill-switch check, buffered
stdin read, jq gate, file-path extraction, repo-root resolution, ancestor
config walk-up (typos.toml > _typos.toml > .typos.toml > Cargo.toml
metadata > pyproject.toml [tool.typos], precedence per crate-ci/typos'
own docs and empirical verification), typos binary resolution from PATH,
typos --write-changes --force-exclude --format json fix pass, exit-code
branching (0 = clean/fixed, 2 = residual findings, other = tool break),
residual-finding parsing with remediation guidance pointing at
extend-words/extend-identifiers/extend-ignore-re, and hook-telemetry
envelope emission.

Hook-precision conformance: the convention is fleet-wide by intent (its
owner doc states "every plugin hook follows it") though CI-audited
enforcement is currently guardrails-only; this plugin opts in voluntarily.

Known, documented, out-of-scope risk: concurrent same-file PostToolUse
hook writes (no extension filter + no locking) — tracked in #875.

Phase 2: Setup skill + docs

skills/setup/SKILL.md (check/apply contract; apply is guidance-only
since typos has no per-repo dependency-manager install path, unlike Ruff or
markdownlint-cli2), README.md, CHANGELOG.md (starts at 0.1.0).

Phase 3: Contract test

hooks/typos-format.test.sh — black-box Bash contract test mirroring
ruff-format.test.sh's fixture-corpus shape: opt-in gate (present/absent
config, pyproject with/without [tool.typos], typos.toml/_typos.toml
precedence), fix + residual-finding reporting, config-exclude respect
(--force-exclude), kill switch, telemetry envelope shape, missing-binary
and missing-jq visibility notices.

Phase 4: Local CI-equivalent verification

Ran every gate the new directory trips in plugin-gate/hygiene locally
before opening the PR (hook-utils sync, plugin manifest validation, catalog
sync, changelog parity, silent-skip gate, cross-plugin source drift, skill
leaf names, skill quality gate, full fleet test suite, and a typos/
shellcheck/markdownlint-cli2 self-check on the new files).

Blast radius

LOW — new, additive plugin directory; zero changes to existing plugin
behavior beyond the synced hook-utils.sh copy (mechanical, CI-gated) and
two purely-additive doc/registry rows.

Open questions (resolved during implementation)

1. Binary-file handling — empirically not an issue; typos handles arbitrary
   file content without a hard error.
2. Setup apply scope — resolved to guidance-only (no auto-install),
   confirmed against crate-ci/typos' own install docs (no universal
   per-repo dependency-manager path exists for a standalone Rust binary).

🤖 Generated with Claude Code

[claude]

Claude finished @kyle-sexton's task in 4m 45s —— View job

---

PR Review: feat(typos-format): add per-file typos autofix hook plugin

Tasks:

• Gather context and understand request
• Read plugin manifest and hooks configuration
• Review main hook script (typos-format.sh)
• Review hook-utils.sh
• Review test suite (typos-format.test.sh)
• Review skill, README, and supporting files
• Check marketplace.json and registry changes
• Synthesize findings and post review

---

Overall Assessment

Approve with minor notes. The implementation is correct, secure, and closely follows the established ruff-format/markdown-format patterns. The 44-assertion black-box test suite is comprehensive, the --force-exclude regression case is properly covered, and the hook's advisory-only posture is correctly maintained throughout. Two minor items and one informational note follow.

---

Finding 1 — Minor: Case 4b doesn't fully enforce "only unfixable reported"

File: plugins/typos-format/hooks/typos-format.test.sh lines 203–215

The test description says "mixed fixable+unfixable -> only unfixable reported" but the assertion only checks that "disallowme" appears in additionalContext. It does not verify that "teh" (the fixed typo) is absent from the context:

if printf '%s' "$OUT" | jq -r '.hookSpecificOutput.additionalContext' 2>/dev/null | grep -q 'disallowme'; then
  ok "mixed fixable+unfixable -> only unfixable reported"

The hook's RC=0 branch (all-fixed path) returns before parsing any output, so "teh" cannot leak in that scenario. For the RC=2 branch, the hook only looks at select(.type == "typo") JSON output from typos after --write-changes. That behavior — that typos omits fixed findings from its JSON output when --write-changes completes them — is cited as "verified against typos-cli 1.44.0" in the hook header, but the test doesn't enforce the absence property explicitly.

The practical risk is low given the empirical verification, but a stronger assertion would be:

CTX=$(printf '%s' "$OUT" | jq -r '.hookSpecificOutput.additionalContext' 2>/dev/null)
if printf '%s' "$CTX" | grep -q 'disallowme' && ! printf '%s' "$CTX" | grep -q '"teh"'; then
  ok "mixed fixable+unfixable -> only unfixable reported (fixed 'teh' absent)"

Fix this →

---

Finding 2 — Minor: Marketplace entry has no relevance signals

File: .claude-plugin/marketplace.json lines 61–65

{
  "name": "typos-format",
  "source": "./plugins/typos-format",
  "category": "development",
  "tags": ["typos", "spelling", "formatter", "linter", "hook"]
}

Every other hook-based formatter plugin has a relevance block — ruff-format signals on ["**/*.py"] and cli: ["ruff"], biome-format on **/biome.json and a manifest dep, etc. typos-format is intentionally language-agnostic (no extension filter), but the typos binary and the three canonical config filenames (typos.toml, _typos.toml, .typos.toml) are reliable, unambiguous discovery signals:

"relevance": {
  "topic": "spelling/typo fixing",
  "signals": {
    "filesRead": ["**/typos.toml", "**/_typos.toml", "**/.typos.toml"],
    "cli": ["typos"]
  }
}

Without this the plugin requires a user to know its name. Given that the plugin's own opt-in gate is a typos config, surfacing the plugin when that config is present is exactly the right trigger.

Fix this →

---

Finding 3 — Info: PLAN.md committed to main tree

File: docs/topics/typos-format-hook/PLAN.md

290 lines of implementation-phase planning scaffolding. Similar files exist for other topics in this repo (docs/topics/lint-static-analysis-gaps/PLAN.md is referenced in the PR body), so this follows existing project convention. Not blocking — noting it for completeness and in case the team wants to revisit whether in-flight plans should be committed.

---

Code quality notes (non-blocking)

Hook logic is clean and correct. A few specific verifications:

• Config precedence walk (typos-format.sh:140–157): The for name in typos.toml _typos.toml .typos.toml; do ... && break; done inner loop correctly breaks the for loop (not the while), and the outer [[ -n "$CONFIG_FOUND" ]] && break then exits the walk. Precedence mirrors typos' own Config::from_dir order.

• Cargo.toml grep (typos-format.sh:144–146): '^[[:space:]]*\[(workspace|package)\.metadata\.typos(\]|[.]) correctly anchors to line start so it can't be tricked by a value string like name = "[workspace.metadata.typos]".

• RC=0/2/other handling (typos-format.sh:198–249): Mapping typos' exit codes (0 = clean/fully-fixed, 2 = residual findings, other = tool error) to ok/ok/skipped telemetry status is consistent with how ruff-format handles Ruff's exit codes.

• No command injection: $TYPOS_ARG is passed as a positional argument inside a quoted array via cd "$RUN_DIR" && "$TYPOS_BIN" --write-changes --force-exclude --format json "$TYPOS_ARG". JSON field values from typos output are extracted with jq -r (not eval), and path values are JSON-escaped before emission via hook::json_escape. Clean throughout.

• --force-exclude regression (typos-format.sh:195 + test Case 5): Flag is present and the exclusion case is properly exercised.

• Known race with parallel hooks: Documented in both the hook header and README.md. Not addressable at the hook level today.

---

[claude]

Claude finished @kyle-sexton's task in 5m 48s —— View job

---

Security Review — PR #872 feat(typos-format): add per-file typos autofix hook plugin

• Gather context — reading changed files
• Review shell scripts for injection surfaces and unsafe patterns
• Review hook-utils.sh for command/path injection
• Review typos-format.sh for unsafe variable handling
• Review plugin manifest and hooks config
• Synthesize and post findings

---

Findings

No CRITICAL or IMPORTANT vulnerabilities found. Two SUGGESTION-level findings below.

---

SUGGESTION — Confidence: HIGH

Test script constructs JSON with printf %s without escaping the file path

plugins/typos-format/hooks/typos-format.test.sh — run_hook, L97–100 and run_hook_env, L108–111:

printf '{"tool_input":{"file_path":"%s"},"tool_name":"Write"}' "$file_path" | …

%s does not JSON-escape its argument. A path containing ", \, or a newline would produce malformed JSON, which the hook would silently discard (jq parse failure → hook::buffer_stdin returns empty → exit 0). The test would then misread the skip as a pass. In practice all test paths come from mktemp and fixed string suffixes, so no test path ever carries these characters — but this is a latent fragility rather than a defence.

The production hook is unaffected: it reads file paths from stdin JSON via jq -r, which handles all escaping correctly.

---

SUGGESTION — Confidence: MEDIUM

Relative HOOK_TELEMETRY_SINK resolved without containment check

plugins/typos-format/hooks/hook-utils.sh L438–446 (telemetry sink resolution):

local sink="$HOOK_TELEMETRY_SINK"
case "$sink" in
/* | [A-Za-z]:[/\\]*) ;;     # absolute — used as-is
*)
  local root="${repo_root:-${CLAUDE_PROJECT_DIR:-}}"
  [[ -n "$root" ]] || return 0
  sink="${root%/}/$sink"      # relative — joined onto repo root
  ;;
esac
…
printf '%s\n' "$envelope" | ("$sink" >/dev/null 2>&1) &

A relative HOOK_TELEMETRY_SINK value such as ../../outside-repo/sink is joined onto the repo root with no ..-normalization or containment check, so the resolved executable path can fall outside the repository. The code acknowledges the portability motivation for the relative form (L385–387), and since HOOK_TELEMETRY_SINK is exclusively consumer-set configuration (in settings.json), an escape from the repo root is already under the consumer's full control — they could equally set an absolute path anywhere. Severity is therefore low, but the lack of a guard is worth documenting as a trust boundary for any future consumer-facing docs that describe what relative values mean.

---

What looks good

• No shell-word-splitting injection. All variables passed to external commands ($TYPOS_BIN, $TYPOS_ARG, $RUN_DIR, $FILE, $REPO_ROOT, $sink) are consistently double-quoted. set -u catches unbound variable dereferences early.
• JSON output is safe regardless of file content. The residual-findings path extracts typo words with jq -r and emits them into additionalContext via hook::emit_additional_context, which uses jq -n --arg, so jq handles all JSON-string escaping natively. Skip-notice messages (the only path through hook::emit_channels, which uses hook::json_escape) are entirely author-controlled strings, not derived from file content.
• File path validation chain is correct. hook::read_file_path checks existence with -f and validates project membership by comparing canonicalized (symlink-resolved via hook::physical_path) paths against CLAUDE_PROJECT_DIR, anchored on a path-segment boundary to prevent sibling-repo admittance.
• Session ID sanitized before file-system use. hook::notice_once strips session ID to [A-Za-z0-9_-] before constructing the marker path under CLAUDE_PLUGIN_DATA.
• No command injection through config file content. The Cargo.toml / pyproject.toml opt-in check uses grep -qE with a hardcoded pattern; no config-file content is ever interpolated into a shell command or executed.
• typos binary resolved from $PATH only. No download, no per-repo script execution, no eval.
• hook-utils.sh hook::ansi_c_decode format-string injection prevented. The function pre-escapes % → %% before using the body as a printf format string, preventing injected format specifiers.
• No GitHub Actions files changed. No pull_request_target, workflow permissions: widening, or github context injection surfaces are present.

[claude]

Claude finished @kyle-sexton's task in 1m 13s —— View job

---

PR Review — fix(typos-format): address review findings, prune topic plan

Tasks:

• Gather context and understand the request
• Diff the latest commit against the prior one to see what changed
• Verify test assertion strength (Finding 1 from prior review)
• Verify marketplace relevance block (Finding 2 from prior review)
• Verify PLAN.md was pruned (Finding 3 from prior review / PR body)
• Synthesize findings and post final review

---

Summary

The fix(typos-format) follow-up commit correctly addresses all three findings raised in the prior code review. No new issues introduced.

---

Finding 1 — Resolved: Mixed fixable+unfixable test assertion strengthened

typos-format.test.sh L211–215

The fix matches the suggested approach exactly: the context is captured into CTX_MIXED, and both properties are asserted:

CTX_MIXED=$(printf '%s' "$OUT" | jq -r '.hookSpecificOutput.additionalContext' 2>/dev/null)
if printf '%s' "$CTX_MIXED" | grep -q 'disallowme' && ! printf '%s' "$CTX_MIXED" | grep -q '"teh"'; then
  ok "mixed fixable+unfixable -> only unfixable reported (fixed 'teh' absent)"

The negative assertion (! grep -q '"teh"') now enforces the claim that fixed typos are not leaked into residual advisory output. The failure message also improved to include the actual context value. ✅

---

Finding 2 — Resolved: relevance block added to marketplace entry

.claude-plugin/marketplace.json L64–71

"relevance": {
  "topic": "Spelling / typo fixing",
  "signals": {
    "filesRead": ["**/typos.toml", "**/_typos.toml", "**/.typos.toml"],
    "cli": ["typos"]
  }
}

Signal selection is well-judged: only typos-specific config filenames are listed (not the general-purpose Cargo.toml or pyproject.toml that the opt-in gate also accepts), and cli: ["typos"] adds the binary-presence signal. The structure is consistent with sibling formatter entries. ✅

---

Finding 3 — Resolved: docs/topics/typos-format-hook/PLAN.md removed

The docs/topics/typos-format-hook/ directory has been deleted entirely (290 lines pruned). Plan content is captured in the PR description for the historical record. ✅

---

No new issues

The three changes are minimal, targeted, and correct. The security review's two SUGGESTION-level items (test-harness JSON path escaping, relative HOOK_TELEMETRY_SINK containment) remain noted as pre-existing fleet patterns; nothing in this follow-up commit introduces or worsens them.

Ready to merge.

[kyle-sexton]

Addressed in 1df48cc:

Finding 1 (Case 4b assertion) — CORRECT. Strengthened to also assert the fixed typo is absent from the residual context.

Finding 2 (marketplace relevance) — CORRECT. Added, matching ruff-format's pattern (typos config filenames + typos CLI signal).

Finding 3 (PLAN.md committed) — pruned; the plan is now captured in full in the PR description.

Security suggestion 1 (test JSON escaping) — confirmed and correct, but deferred: plugins/ruff-format/hooks/ruff-format.test.sh and plugins/markdown-format/hooks/markdown-format.test.sh use the identical unescaped printf '%s' pattern for every test fixture — this is a fleet-wide, pre-existing test-harness convention, not something introduced by this PR. Fixing it in one plugin's test file alone would diverge from the shared pattern without closing the gap elsewhere. Filed nothing new here; flagging for a future fleet-wide test-harness hygiene pass if one is warranted.

Security suggestion 2 (relative telemetry sink containment) — confirmed and correct, but out of scope: the code lives in lib/hook-utils.sh (the shared source), synced byte-for-byte into every plugin's hooks/hook-utils.sh copy via scripts/sync-hook-utils.sh. Per this repo's own convention, a plugin's copy is never hand-edited — a fix belongs in the shared source and would affect every hook that emits telemetry, not just typos-format.

Two follow-up issues also filed from findings surfaced during review: #874 (ruff-format missing its own telemetry schema/registry row) and #875 (fleet-wide concurrent-hook-write race, documented as a known limitation in this plugin).

[claude]

Claude finished @kyle-sexton's task in 3m 1s —— View job

---

Security Review — PR #872 feat(typos-format): add per-file typos autofix hook plugin

Tasks:

• Load tools and initialize
• Fetch PR diff / read changed files
• Read main hook script (typos-format.sh)
• Read hook-utils.sh (injection surfaces, telemetry sink)
• Read test script for test-harness security patterns
• Read plugin manifest, hooks.json, marketplace.json
• Synthesize and post findings

---

No CRITICAL or IMPORTANT vulnerabilities found. The two SUGGESTION-level findings from the previous CI security review remain valid and are reproduced below with updated confidence assessments after independent re-verification. No new findings.

---

SUGGESTION — Confidence: HIGH

Test harness constructs hook input JSON with printf %s and an unescaped file path

plugins/typos-format/hooks/typos-format.test.sh L98 and L109:

printf '{"tool_input":{"file_path":"%s"},"tool_name":"Write"}' "$file_path" | …

A path containing ", \, or a newline produces malformed JSON. The hook's hook::buffer_stdin would then parse-fail and exit 0, which the test framework would misread as a pass. In practice, all test paths come from mktemp with fixed suffixes, so no test path ever carries these bytes — the risk is latent fragility only. The production hook is unaffected: it reads file paths from Claude Code's stdin JSON via jq -r, which handles escaping correctly. This is a pre-existing fleet-wide pattern also present in ruff-format.test.sh and markdown-format.test.sh.

---

SUGGESTION — Confidence: MEDIUM

Relative HOOK_TELEMETRY_SINK is joined to the repo root without a path-containment check

plugins/typos-format/hooks/hook-utils.sh L438–446:

case "$sink" in
/* | [A-Za-z]:[/\\]*) ;;     # absolute — used as-is
*)
  local root="${repo_root:-${CLAUDE_PROJECT_DIR:-}}"
  [[ -n "$root" ]] || return 0
  sink="${root%/}/$sink"      # relative — no .. normalization or containment check
  ;;
esac
printf '%s\n' "$envelope" | ("$sink" >/dev/null 2>&1) &

A relative value of ../../outside-repo/sink resolves an executable path outside the repository. Since HOOK_TELEMETRY_SINK is exclusively consumer-set (in settings.json), this is already under the consumer's full control — they could equally provide an absolute path to any executable. Severity is low and documented as a trust boundary in the PR. The code lives in the shared source (lib/hook-utils.sh) and any fix would need to land there and propagate via sync-hook-utils.sh, not in this plugin's copy.

---

What looks correct

• No command injection in the main hook (typos-format.sh:195): $TYPOS_BIN, $RUN_DIR, and $TYPOS_ARG are all double-quoted in the invocation; TYPOS_BIN is resolved from PATH via command -v (no download, no per-repo binary resolution). No eval anywhere.
• typos output safely embedded in JSON (typos-format.sh:211–223): Typo words and corrections extracted with jq -r .typo / jq -r .corrections[0] flow through hook::ctx_append → hook::emit_additional_context → jq -n --arg ctx. JQ handles all JSON string escaping; no hand-built interpolation of file content into JSON.
• Tool-break stderr also safe (typos-format.sh:241–246): Raw typos stderr captured via 2>&1 and echoed line-by-line into the context buffer. The buffer ultimately reaches jq -n --arg ctx, so arbitrary typos error output cannot inject JSON.
• File path validation chain is correct (hook-utils.sh:193–211): hook::read_file_path validates existence (-f) and project membership by comparing canonicalized (symlink-resolved via hook::physical_path) paths against CLAUDE_PROJECT_DIR, anchored on a path-segment boundary.
• Session ID sanitized before filesystem use (hook-utils.sh:98): session="${session//[^A-Za-z0-9_-]/-}" strips all non-alphanumeric-safe characters before using the session ID to construct a marker file path under CLAUDE_PLUGIN_DATA.
• hook::json_escape coverage is complete (hook-utils.sh:37–50): Escapes \, ", \n, \r, \t, then tr -d drops remaining C0 bytes — covers the full JSON string requirement. hook::ansi_c_decode pre-escapes % → %% before using the body as a printf format string, preventing format-specifier injection.
• No GitHub Actions files changed. No pull_request_target, workflow_run, permissions: widening, or github context injection surfaces present.
• No supply-chain risk: No new dependency pins, no action version changes, no external fetch or eval in the hook.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1df48cc3a8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 1m 42s —— View job

---

Tasks:

• Gather context and load tools
• Review latest commit (c9dff9b) diff
• Evaluate Codex P2 finding on inline TOML configs
• Synthesize and post final review

---

Review — fix(typos-format): suppress typos gate hit from own test literal

No issues found. Ready to merge.

---

Latest commit (c9dff9b) — Correct

The Case 4b strengthening in 1df48cc embedded the literal teh twice directly in the test source, causing the repo's own typos CI gate to flag it. The fix routes it through a suppressed variable:

FIXED_TYPO='teh' # spellchecker:disable-line
if … ! printf '%s' "$CTX_MIXED" | grep -qF "\"$FIXED_TYPO\""; then
  ok "mixed fixable+unfixable -> only unfixable reported (fixed typo absent)"

This is the right approach: one variable assignment, one suppression comment, and the test assertion semantics are preserved exactly. The switch from -q to -qF is a minor correctness improvement — the pattern has no regex metacharacters but -F makes the intent explicit.

The approach is consistent with plugins/typos-format/hooks/typos-format.test.sh:227 on the very next case (# spellchecker:disable-line inline), so suppression style is now uniform.

---

Codex P2 finding — Not a merge blocker

The Codex comment observes that the opt-in gate grep does not recognize the TOML inline-table form:

[tool]
typos = { extend-words = { ... } }

This is technically correct: the pyproject.toml grep at typos-format.sh:148–150 only matches [tool.typos]-style section headers, not dotted-key inline tables under [tool]. The Cargo.toml check has the same structural limit.

Two reasons not to fix this now:

1. Severity is low. The consequence of missing the form is the hook silently skips — no incorrect behavior, no data loss, same outcome as having no config. This is a discovery gap, not a correctness defect.
2. The fix is fragile. A multi-pass grep (grep [tool] followed by grep typos =) would produce false positives whenever a pyproject.toml has an unrelated typos = key inside any other section. Reliable detection would require a proper TOML parser, which is out of scope for a shell hook.

The inline-table form for a full section is also unusual enough in real pyproject.toml files that the practical impact is very low. This belongs in a follow-up issue (same class as the concurrent-hook-write race in #875) if the team wants to track it, but it is not a reason to hold this PR.

[claude]

Claude finished @kyle-sexton's task in 3m 3s —— View job

---

Security Review — PR #872 feat(typos-format): add per-file typos autofix hook plugin

Tasks:

• Load tools and initialize
• Fetch PR diff and read changed files
• Audit typos-format.sh (main hook) for injection surfaces
• Audit hook-utils.sh for unsafe patterns
• Audit test script, hooks.json, marketplace.json, plugin.json
• Audit latest fix commit (c9dff9b — suppress typos gate hit from own test literal)
• Synthesize and post findings

---

No CRITICAL or IMPORTANT vulnerabilities found. Two SUGGESTION-level findings remain — both pre-existing fleet-wide patterns, not introduced by this PR. One informational note.

---

SUGGESTION — Confidence: HIGH

Test harness constructs hook input JSON with printf %s and an unescaped file path

plugins/typos-format/hooks/typos-format.test.sh L98 and L109:

printf '{"tool_input":{"file_path":"%s"},"tool_name":"Write"}' "$file_path" | …

A path containing ", \, or a newline produces malformed JSON. The hook's hook::buffer_stdin would parse-fail and exit 0, which the test framework would misread as a pass. In practice all test paths come from mktemp with fixed suffixes, so no test path ever carries these bytes — the risk is latent fragility only. The production hook is unaffected: it reads file paths from Claude Code's stdin JSON via jq -r, which handles escaping correctly. This is a pre-existing fleet-wide pattern also present in ruff-format.test.sh and markdown-format.test.sh. The latest commit (c9dff9b) only modifies lines 211–215 and does not affect this surface.

---

SUGGESTION — Confidence: MEDIUM

Relative HOOK_TELEMETRY_SINK joined to repo root without a path-containment check

plugins/typos-format/hooks/hook-utils.sh L438–446:

case "$sink" in
/* | [A-Za-z]:[/\\]*) ;;     # absolute — used as-is
*)
  local root="${repo_root:-${CLAUDE_PROJECT_DIR:-}}"
  [[ -n "$root" ]] || return 0
  sink="${root%/}/$sink"      # relative — no .. normalization or containment check
  ;;
esac
printf '%s\n' "$envelope" | ("$sink" >/dev/null 2>&1) &

A relative value of ../../outside-repo/sink resolves an executable path outside the repository. Since HOOK_TELEMETRY_SINK is set exclusively by the consumer in settings.json, this is already under the consumer's full control — they could equally provide an absolute path to any executable. The code lives in the shared source (lib/hook-utils.sh); any fix must land there and propagate via scripts/sync-hook-utils.sh, not in this plugin's copy.

---

What looks correct

• No command injection in the main hook (typos-format.sh:195): $TYPOS_BIN, $RUN_DIR, and $TYPOS_ARG are all double-quoted; TYPOS_BIN is resolved from PATH via command -v (no download, no per-repo binary execution, no eval anywhere).

• File-derived content safely embedded in JSON (typos-format.sh:213–222): Typo words extracted with jq -r '.typo // empty' flow through hook::ctx_append → hook::ctx_flush → hook::emit_additional_context → jq -n --arg ctx. JQ handles all JSON string escaping natively; no hand-built interpolation of file content into JSON anywhere in the hot path.

• Tool-break stderr also safe (typos-format.sh:242–245): Raw typos stderr captured via 2>&1 and echoed line-by-line into the context buffer. The buffer reaches jq -n --arg ctx, so arbitrary typos error output cannot inject into the JSON response.

• File path validation chain is correct (hook-utils.sh:193–211): hook::read_file_path validates existence (-f) and project membership by comparing canonicalized (symlink-resolved via hook::physical_path) paths against CLAUDE_PROJECT_DIR, anchored on a path-segment boundary so /c/repo-backup/… cannot be admitted by sharing a prefix with /c/repo.

• Session ID sanitized before filesystem use (hook-utils.sh:98): session="${session//[^A-Za-z0-9_-]/-}" strips all non-alphanumeric-safe characters before constructing the marker file path under CLAUDE_PLUGIN_DATA.

• hook::json_escape coverage is complete (hook-utils.sh:37–50): Escapes \, ", \n, \r, \t, then tr -d drops remaining C0 bytes. hook::ansi_c_decode pre-escapes % → %% before using the body as a printf format string, blocking format-specifier injection.

• Cargo.toml grep pattern anchored correctly (typos-format.sh:145): '^[[:space:]]*\[(workspace|package)\.metadata\.typos(\]|[.])' anchors to line start via ^, so a config value string containing [workspace.metadata.typos] cannot trigger a false opt-in.

• Latest commit (c9dff9b) is minimal and clean: Introduces FIXED_TYPO='teh' as an indirection variable and switches to grep -qF "\"$FIXED_TYPO\"". No new execution surfaces or variable-expansion paths introduced.

• No GitHub Actions files changed. No pull_request_target, workflow_run, permissions: widening, or github context injection surfaces present. No supply-chain risk from loosened action or dependency pins.

---

Ready to merge from a security perspective.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c9dff9b71c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 2m 30s —— View job

---

PR Review — docs(typos-format): clarify config-resolution comment, add nested-config regression test

Tasks:

• Gather context and load tools
• Review latest commit (4626e1e) diff
• Evaluate Codex P2 finding response (nested config resolution)
• Review new regression test (Case 3b)
• Synthesize and post final review

---

Summary

Approve. The commit correctly addresses the Codex P2 concern and adds a permanent regression test locking in the empirically-verified behavior. One minor stale-comment nit, noted below but not blocking.

---

Codex P2 — Correctly refuted and documented

The Codex finding claimed the hook should cd to the discovered config directory or pass --config explicitly because typos' config discovery is "CWD-anchored." Kyle's empirical verification — and this regression test — prove that is incorrect: typos resolves config relative to the target path passed on the command line, not the process CWD. Running from the repo root with a subdirectory-relative path still discovers and honors a config nested at any depth.

The comment update in typos-format.sh:175–181 is accurate and materially more precise than the old "CWD-anchored" label.

---

Case 3b — Correct regression test

typos-format.test.sh:181–196

The test correctly:

• Creates a repo with no config at the root (NO_CONFIG)
• Places a _typos.toml only at packages/pkg/
• Writes a file with the custom pkgword typo there
• Invokes the hook with the absolute file path (the hook will cd to the repo root and pass the relative path to typos)
• Asserts that correctword appears in the file — proving typos found and applied the nested config despite running from a parent directory

The [default.extend-words]\npkgword = "correctword"\n fixture is the right shape: typos treats the key as an incorrect form and replaces it with the value under --write-changes. The assertion is correct.

---

Minor nit — Test file header still carries the old label

typos-format.test.sh:13

# The hook is invoked from an UNRELATED cwd so any reliance on the caller's
# working directory would surface (typos' config discovery is CWD-anchored;
# the hook cd's to the repo root before running).

The parenthetical still says typos' config discovery is CWD-anchored, which is now directly contradicted by the correction in typos-format.sh and the newly-added Case 3b. The commit message says it "Clarifies the header comment's imprecise 'CWD-anchored' wording" but only updated the hook file, not this test-file header. Not blocking — the behavior is correct and the regression test proves it — but the stale phrasing undermines the clarification's completeness.

Fix this →

---

What looks correct

• Behavioral change: none. This is a docs-only commit plus a test addition. No execution path changed.
• New test is self-contained: uses $WORK-prefixed temp dir, proper new_typos_repo NO_CONFIG baseline, and is placed correctly between Case 3 and Case 4 in execution order.
• No spellchecker false positives: pkgword and correctword are not in typos' built-in dictionary, so the test fixture won't accidentally fire on unrelated CI checks.

Ready to merge.

[claude]

Claude finished @kyle-sexton's task in 2m 5s —— View job

---

Security Review — PR #872 feat(typos-format): add per-file typos autofix hook plugin

Tasks:

• Load tools and initialize
• Fetch PR diff and read changed files (latest commit: 4626e1e)
• Audit typos-format.sh — injection surfaces, variable handling
• Audit hook-utils.sh — unsafe patterns, sink resolution
• Audit test script, hooks.json, marketplace.json, plugin.json
• Audit latest commit (nested-config regression test + docs clarification)
• Synthesize and post findings

---

No CRITICAL or IMPORTANT vulnerabilities found. Two SUGGESTION-level findings remain — both pre-existing fleet-wide patterns, not introduced by this PR. The latest commit (4626e1e) is a comment clarification and regression test addition; it introduces no new execution surfaces.

---

SUGGESTION — Confidence: HIGH

Test harness constructs hook input JSON with printf %s and an unescaped file path

plugins/typos-format/hooks/typos-format.test.sh L98 and L109:

printf '{"tool_input":{"file_path":"%s"},"tool_name":"Write"}' "$file_path" | …

A path containing ", \, or a newline produces malformed JSON. The hook's hook::buffer_stdin would parse-fail and exit 0, which the test framework would misread as a pass. In practice all test paths come from mktemp with fixed suffixes, so no test path ever carries these bytes — the risk is latent fragility only. The production hook is unaffected: it reads file paths from Claude Code's stdin JSON via jq -r, which handles escaping correctly. This is a pre-existing fleet-wide pattern also present in ruff-format.test.sh and markdown-format.test.sh. The latest commit adds a new Case 3b test (L188–195) using run_hook with the same pattern — no worsening introduced.

---

SUGGESTION — Confidence: MEDIUM

Relative HOOK_TELEMETRY_SINK joined to repo root without a path-containment check

plugins/typos-format/hooks/hook-utils.sh L438–446:

case "$sink" in
/* | [A-Za-z]:[/\\]*) ;;     # absolute — used as-is
*)
  local root="${repo_root:-${CLAUDE_PROJECT_DIR:-}}"
  [[ -n "$root" ]] || return 0
  sink="${root%/}/$sink"      # relative — no .. normalization or containment check
  ;;
esac
printf '%s\n' "$envelope" | ("$sink" >/dev/null 2>&1) &

A relative value of ../../outside-repo/sink resolves an executable path outside the repository. Since HOOK_TELEMETRY_SINK is set exclusively by the consumer in settings.json, this is already under the consumer's full control — they could equally provide an absolute path to any executable. The code lives in the shared source (lib/hook-utils.sh); any fix must land there and propagate via scripts/sync-hook-utils.sh, not in this plugin's copy.

---

What looks correct

• No command injection in the main hook (typos-format.sh:199): $TYPOS_BIN, $RUN_DIR, and $TYPOS_ARG are all double-quoted; TYPOS_BIN is resolved from PATH via command -v (no download, no per-repo binary execution, no eval anywhere).

• File-derived content safely embedded in JSON (typos-format.sh:213–228): Typo words extracted with jq -r '.typo // empty' flow through hook::ctx_append → hook::ctx_flush → hook::emit_additional_context → jq -n --arg ctx. JQ handles all JSON string escaping natively. build_data_json() (typos-format.sh:109–116) likewise uses jq -n --arg/--argjson throughout — no hand-built JSON interpolation of untrusted values.

• Tool-break stderr also safe (typos-format.sh:244–249): Raw typos stderr captured via 2>&1 and echoed line-by-line into the context buffer. The buffer ultimately reaches jq -n --arg ctx, so arbitrary typos error output cannot inject into the JSON response.

• File path validation chain is correct (hook-utils.sh:193–211): hook::read_file_path validates existence (-f) and project membership by comparing canonicalized (symlink-resolved via hook::physical_path) paths against CLAUDE_PROJECT_DIR, anchored on a path-segment boundary so /c/repo-backup/… cannot be admitted by sharing a prefix with /c/repo.

• Session ID sanitized before filesystem use (hook-utils.sh:98): session="${session//[^A-Za-z0-9_-]/-}" strips all non-alphanumeric-safe characters before constructing the marker file path under CLAUDE_PLUGIN_DATA.

• hook::json_escape coverage is complete (hook-utils.sh:37–50): Escapes \, ", \n, \r, \t, then tr -d drops remaining C0 bytes. hook::ansi_c_decode pre-escapes % → %% before using the body as a printf format string, blocking format-specifier injection.

• Cargo.toml grep pattern anchored correctly (typos-format.sh:145): '^[[:space:]]*\[(workspace|package)\.metadata\.typos(\]|[.])' anchors to line start via ^, so a config value string containing [workspace.metadata.typos] cannot trigger a false opt-in.

• Latest commit (4626e1e) is minimal and clean: A 5-line comment rewrite in typos-format.sh and a 16-line regression test in the test file. No new execution surfaces, variable-expansion paths, or injection vectors introduced.

• No GitHub Actions files changed. No pull_request_target, workflow_run, permissions: widening, or github context injection surfaces present. No supply-chain risk from loosened action or dependency pins.

---

Ready to merge from a security perspective.

[kyle-sexton]

Fixed the stale wording in typos-format.test.sh's own header comment (552fd7f) — it still said "CWD-anchored" after the prior commit only updated typos-format.sh. Both now consistently describe target-path-anchored resolution, matching the Case 3b regression test.

[claude]

Claude finished @kyle-sexton's task in 1m 1s —— View job

---

Tasks

• Gather context and understand request
• Review latest commit (552fd7f) — stale CWD-anchored wording fix
• Synthesize and post final review

---

Review — docs(typos-format): fix stale CWD-anchored wording in test file header

Approved. Ready to merge.

The latest commit (552fd7f) resolves the last open nit from the 4626e1e review: the test file header still described typos' config discovery as "CWD-anchored" after the prior commit had already corrected that framing in typos-format.sh. Both files now consistently describe the actual, empirically-verified behavior.

Updated text (typos-format.test.sh:12–15):

-# working directory would surface (typos' config discovery is CWD-anchored;
-# the hook cd's to the repo root before running).
+# own working directory would surface (typos resolves config relative to the
+# target path passed on the command line, not the process CWD — Case 3b below
+# locks this in — so the hook's own cd to the repo root does not change which
+# config governs).

This is consistent with the correction already in typos-format.sh:175–181 and anchored by the Case 3b regression test added in 4626e1e. No execution path changed; this is documentation only.

---

Summary of all review rounds

Commit	Finding	Status
ed15527	Case 4b assertion didn't verify absence of fixed typo	Fixed in 1df48cc
ed15527	Marketplace typos-format entry missing relevance block	Fixed in 1df48cc
ed15527	docs/topics/typos-format-hook/PLAN.md committed to main tree	Pruned in 1df48cc
1df48cc	Embedded literal teh triggered repo's own typos CI gate	Fixed in c9dff9b
c9dff9b	Codex P2: Inline TOML config form not recognized	Deferred — pre-existing fleet pattern; filed #876
c9dff9b	Codex P2: cd to config dir / pass --config explicitly	Refuted empirically; regression-tested in 4626e1e
4626e1e	Test file header still said "CWD-anchored"	Fixed in 552fd7f
All	Security SUGGESTION: test harness unescaped printf %s path	Pre-existing fleet pattern — deferred
All	Security SUGGESTION: relative HOOK_TELEMETRY_SINK containment	Shared lib concern — deferred to lib/hook-utils.sh

All code-review findings are resolved. Both remaining security suggestions are pre-existing fleet-wide patterns not introduced by this PR, correctly deferred. No blocking issues remain.

[claude]

Claude finished @kyle-sexton's task in 1m 54s —— View job

---

Tasks:

• Gather context and load tools
• Fetch PR diff — read changed files (latest commit: 552fd7f)
• Audit for security issues
• Post findings

---

Security Review — PR #872 feat(typos-format): add per-file typos autofix hook plugin

No CRITICAL or IMPORTANT vulnerabilities found. The two SUGGESTION-level findings from prior CI security review passes remain valid and are reproduced below after independent verification. The latest commit (552fd7f) is a 6-line comment rewrite in the test file header — no code, no execution surfaces changed.

---

SUGGESTION — Confidence: HIGH

Test harness constructs hook input JSON with printf %s and an unescaped file path

plugins/typos-format/hooks/typos-format.test.sh L98 and L109:

printf '{"tool_input":{"file_path":"%s"},"tool_name":"Write"}' "$file_path" | …

A path containing ", \, or a newline produces malformed JSON. The hook's hook::buffer_stdin would then parse-fail and exit 0, which the test framework would misread as a pass. In practice all test paths come from mktemp with fixed suffixes, so no test path ever carries these bytes — the risk is latent fragility only. The production hook is unaffected: it reads file paths from Claude Code's stdin JSON via jq -r, which handles escaping correctly. This is a pre-existing fleet-wide pattern also present in ruff-format.test.sh and markdown-format.test.sh. No changes in the latest commit affect this surface.

---

SUGGESTION — Confidence: MEDIUM

Relative HOOK_TELEMETRY_SINK joined to repo root without a path-containment check

plugins/typos-format/hooks/hook-utils.sh L438–446:

case "$sink" in
/* | [A-Za-z]:[/\\]*) ;;     # absolute — used as-is
*)
  local root="${repo_root:-${CLAUDE_PROJECT_DIR:-}}"
  [[ -n "$root" ]] || return 0
  sink="${root%/}/$sink"      # relative — no .. normalization or containment check
  ;;
esac
printf '%s\n' "$envelope" | ("$sink" >/dev/null 2>&1) &

A relative value of ../../outside-repo/sink resolves an executable path outside the repository. Since HOOK_TELEMETRY_SINK is set exclusively by the consumer in settings.json, this is already under the consumer's full control — they could equally provide an absolute path to any executable. Severity is low. The code lives in the shared source (lib/hook-utils.sh); any fix must land there and propagate via scripts/sync-hook-utils.sh, not in this plugin's copy.

---

What looks correct

• No command injection in the main hook (typos-format.sh:199): $TYPOS_BIN, $RUN_DIR, and $TYPOS_ARG are all double-quoted in the invocation; TYPOS_BIN is resolved from PATH via command -v — no download, no per-repo binary execution, no eval anywhere.

• File-derived content safely embedded in JSON (typos-format.sh:213–228): Typo words extracted with jq -r '.typo // empty' flow through hook::ctx_append → hook::ctx_flush → hook::emit_additional_context → jq -n --arg ctx. JQ handles all JSON string escaping natively; no hand-built interpolation of file content into JSON anywhere in the hot path.

• Tool-break stderr also safe (typos-format.sh:244–249): Raw typos stderr captured via 2>&1 and echoed line-by-line into the context buffer; the buffer ultimately reaches jq -n --arg ctx, so arbitrary tool error output cannot inject into the JSON response.

• File path validation chain is correct (hook-utils.sh:193–211): hook::read_file_path validates existence (-f) and project membership by comparing canonicalized (symlink-resolved via hook::physical_path) paths against CLAUDE_PROJECT_DIR, anchored on a path-segment boundary so /c/repo-backup/… cannot be admitted by sharing a prefix with /c/repo.

• Session ID sanitized before filesystem use (hook-utils.sh:98): session="${session//[^A-Za-z0-9_-]/-}" strips all non-alphanumeric-safe characters before constructing the marker file path under CLAUDE_PLUGIN_DATA.

• hook::json_escape coverage is complete (hook-utils.sh:37–50): Escapes \, ", \n, \r, \t, then tr -d drops remaining C0 bytes. hook::ansi_c_decode pre-escapes % → %% before using the body as a printf format string, blocking format-specifier injection.

• Cargo.toml grep pattern anchored correctly (typos-format.sh:145): '^[[:space:]]*\[(workspace|package)\.metadata\.typos(\]|[.])' anchors to line start via ^, so a config value string containing [workspace.metadata.typos] cannot trigger a false opt-in.

• Latest commit (552fd7f) is a no-op from a security standpoint: Updates a 6-line comment in typos-format.test.sh from "CWD-anchored" to "target-path-anchored" wording. No execution paths, variable expansions, or injection surfaces were touched.

• No GitHub Actions files changed. No pull_request_target, workflow_run, permissions: widening, or github context injection surfaces present. No supply-chain risk from loosened action or dependency pins.

---

Ready to merge from a security perspective.

[kyle-sexton]

Filed independently while comparing this merged plugin against a parallel implementation (#880, now superseded/closing as duplicate of this one). One material behavioral gap worth flagging even though this already merged, since it affects real users of the plugin:

This hook only runs when the consuming repo already has a typos.toml/_typos.toml/.typos.toml/Cargo.toml([*.metadata.typos])/pyproject.toml([tool.typos]) file. Without one, typos-format.sh exits silently via emit_skipped and never invokes typos at all — confirmed by reading the merged hook script and its own test suite (Case 1: opt-in gate OFF (no typos config) -> file left untouched).

That's the ruff-format/biome-format opt-in-gate pattern, but typos isn't shaped like Ruff or Biome:

• typos ships a built-in spelling dictionary and runs standalone with zero configuration — its own README frames it as something you run unconditionally ("fast enough to run on monorepos... low false positives so you can run on PRs"), not something a repo must first adopt a config for.
• Verified empirically against a real typos-cli 1.44.0 binary: typos <file> catches and fixes real typos (e.g. recieve → receive) in a directory tree with no _typos.toml anywhere above it. A _typos.toml only widens the allowlist (extend-words/extend-identifiers/extend-ignore-re) and excludes ([files] extend-exclude) — it is not an activation switch.
• The originating brief (docs/topics/lint-static-analysis-gaps/PLAN.md, brief item 1) describes "consumer _typos.toml ancestor walk-up" in the context of "false-positive remediation via consumer allowlist entries" — i.e., config narrows false positives, it doesn't gate whether the hook does anything.
• The dispatch instructions for this plugin explicitly said to match markdown-format's pattern (zero-config, ships none of its own rules, always active using the tool's own built-in defaults) rather than ruff-format's (opt-in required) — markdown-format never gates on a .markdownlint-cli2.jsonc existing; it always runs markdownlint-cli2 --fix, config or not.

Net effect: for any consumer repo that hasn't already hand-authored a typos config (i.e. most repos on day one), installing this plugin today does nothing — no auto-fix, no advisory, completely inert — until they write a _typos.toml first. That inverts the "auto-fix on edit, zero-config" value proposition the epic's PLAN.md brief called for.

Suggested fix (not filing a new issue per the review-deferral note — flagging here since the PR is merged): drop the opt-in walk/gate entirely; always run typos --force-exclude -w --format json <file> unconditionally (typos' own file-anchored config discovery already picks up an optional _typos.toml if one exists, for allowlist/exclude purposes only). Happy to open a follow-up PR if that's preferred over amending this one directly.