[DevEx] PostToolUse hook: micro-alignment on every edit (cargo check, clippy, shellcheck, shfmt)

[t4w4n3]

Why

Code quality misalignments — compilation errors, lint violations, unsafe shell constructs — are cheap to fix individually but expensive to discover late. When they accumulate across multiple edits, they compound: a broken type cascades into a broken module, a clippy warning multiplies across 10 files, and the developer ends up doing a bulk cleanup pass instead of shipping.

Claude Code edits files frequently and rapidly. Without an inline gate, each Write/Edit is a potential misalignment that silently persists until the developer runs cargo clippy manually or the CI pipeline catches it. In the RTK workflow, that gap can span dozens of tool calls.

The "alignment" principle is simple: the shorter the life of a misalignment, the lower its blast radius. A compilation error caught after one edit costs one fix. The same error caught after twenty edits costs a debugging session.

How

We propose adding a PostToolUse hook that fires on every Write or Edit tool call in Claude Code. It would inspect the modified file, route to the appropriate gates by extension, and either auto-fix or block.

Rust (.rs)

• cargo check — blocks on type/compilation errors
• cargo clippy — blocks on errors, warns on warnings (non-blocking)

Shell (.sh)

• shfmt -w — auto-formats in place (non-blocking)
• shellcheck — blocks on undefined behavior, unsafe constructs

Behavior

Outcome	Hook exit	Effect
All gates pass	0	Emits systemMessage to Claude UI (e.g. cargo check: OK)
Auto-fix applied	0	Emits auto-fixed by shfmt | ...
Gate failure	2	Blocks the edit, surfaces error in Claude UI
Tool not installed	0	Degrades gracefully, records not installed

Setup would require copying .claude/settings.json.example → settings.json. All tool dependencies (cargo, clippy, shfmt, shellcheck) would be declared in .mise/config.toml and auto-installed.

A working implementation is available on branch devex/alignment-claude-hook.

[FlorianBruniaux]

Code review — PostToolUse hook proposal

Analysis against current codebase state. Three observations before the specifics.

First: all existing hooks in RTK are PreToolUse. This would introduce the first PostToolUse hook, which means no battle-tested pattern to follow in this repo yet.

Second: the proposal conflates two distinct problems — micro-alignment (catching errors early) and tool lifecycle management (mise installing shfmt). These should be separated. If #749 (mise) doesn't land, the setup story here collapses.

Third: the performance numbers contradict RTK's core design philosophy in a way that needs addressing directly.

---

Performance problem (blocking concern)

cargo check warm cache: 5-10s. Cold: 30-60s. RTK's documented startup target is <10ms.

Every Write or Edit on a .rs file fires this hook. A typical Claude Code session with RTK has 50-100 file writes. That's 250-1000 seconds of latency injected into the session — not counting clippy on top.

The alignment value proposition ("shorter misalignment lifecycle = lower blast radius") is solid in theory. But if the hook makes every edit feel sluggish, contributors will disable it, which means zero alignment in practice. The same outcome, with friction added.

What the proposal needs here: either benchmark real-world session latency with the hook enabled, or restrict hook invocation (see alternatives below).

---

What works

The exit code protocol is correct: 2 blocks the tool result, 0 passes through. This matches Claude Code's PostToolUse spec.

The graceful degradation on missing tools (exit 0, emit "not installed") is the right call. Never block a contributor because shfmt isn't in their PATH.

The auto-fix approach for shfmt -w (fix in place, don't block) is better than blocking on format violations. Format is noise; behavioral errors are signal.

shellcheck blocking on undefined behavior is exactly the right gate. RTK has 10 shell scripts and .claude/hooks/ bash — this catches real bugs.

---

Missing pieces

No opt-out mechanism. The proposal has no way to disable the hook per-session or per-project. Contributors who need to make 30 quick edits shouldn't have to edit settings.json to get there.

settings.json doesn't exist. RTK currently uses settings.local.json (user-local, gitignored). A settings.json.example in the repo makes sense, but the proposal needs to explain the migration path from the existing local config clearly.

No timeout. If cargo check hangs (network file system, Docker volume mount, corrupted build cache), the hook hangs the agent session. Add a timeout: timeout 30s cargo check or equivalent.

Dependency on #749 is undeclared. The proposal mentions .mise/config.toml for tool deps. If mise isn't adopted, there's no fallback for how contributors get shfmt + shellcheck.

---

Alternatives worth considering

Rate-limit the check: only fire on the 5th edit to the same file, not every single write. The blast radius argument holds whether you catch a bug after 1 edit or after 5. But 5x fewer cargo check invocations changes the UX fundamentally.

Check only on explicit save: fire on a specific marker file write (Cargo.toml, or a sentinel) rather than every .rs file. Less automated, more reliable.

Decouple Rust from shell: ship the shellcheck/shfmt hook first — it's near-instant, zero performance concern, clear value on a repo with 10+ shell scripts. Put the Rust gate in a separate phase once the performance question is answered.

---

Verdict

The concept is sound: catch misalignments early, surface errors inline instead of at CI. The shellcheck/shfmt piece is ready to ship. The Rust gate needs performance data before landing, and the mise dependency needs to be resolved or decoupled.

The branch devex/alignment-claude-hook exists — a benchmark of a real 50-edit session with the hook enabled would answer the performance question definitively.

[pszymkowiak]

wshm · Automated triage by AI

🔍 Automated Triage

✨ Category	feature
🟡 Priority	medium
🎯 Confidence	92%

Summary

Proposes a PostToolUse hook for automatic linting/checking on every Write/Edit (Rust via cargo check/clippy, Shell via shfmt/shellcheck); working branch already provided. Related to #747 and #749 but distinct in scope.

📁 Relevant files

• .claude/settings.json.example
• .mise/config.toml

---

Triaged automatically by wshm · This is an automated analysis, not a human review.