Hook Engine + Chained Command Rewriting (PR #131 Part 1)

[ahundt]

PR 131 Part 1: Hook Engine + Chained Command Rewriting

Branch: feat/rust-hooks-v2 | Base: master | Tests: 541 pass
Closes: #112 | Split from: PR #131
New dep: which = "7"
PR: #156

TL;DR: PR #156 replaces the current shell script with a fully tested Rust hook engine featuring an integrated lexer that prevents AI timeouts via line-by-line output streaming, increases tokens saved by successfully rewriting compound commands, and stops RTK from breaking standard tools like find and vitest.

---

Context

FlorianBruniaux requested splitting PR #131 (52 files, 8K+ additions) into separate PRs:

1. Gemini CLI support — standalone, no deps on the rest
2. Data safety rules (rm->trash, git reset --hard->stash) + rtk.*.md files
3. Chained command rewriting (cd && git status) — note: feat(hooks): add cross-platform Node.js/Bun hook for Windows support #141 also implements this
4. Rust-based hooks — the hook infrastructure changes

This PR combines items 3 + 4 because they are architecturally inseparable: the hook protocol handler calls lexer::tokenize() then analysis::parse_chain() to process chained commands. Separating them would require duplicating the lexer.

Coordination with PR #141: FlorianBruniaux noted overlap with #141's JS-based hook for Windows. This PR achieves Windows support via compiled Rust binary instead -- no bash, node, or bun required. CI/CD already builds Windows binaries. exec.rs uses cfg!(windows) for shell selection.

---

Merge Sequence

1. This PR -> master (foundation)
2. Retarget PR 2 (data safety) and PR 3 (Gemini) from feat/rust-hooks-v2 -> master
3. PR 2 and PR 3 can merge in any order (zero file conflicts between them)

---

Summary

Replaces the 204-line bash hook with a native Rust binary that provides quote-aware chained command rewriting. Closes #112 where cd /path && git status only rewrote cd.

Impact: Captures ~12-20M tokens/month in previously-missed optimizations across chained commands.

Why Rust over bash:

1. Chained commands work (cd && git status rewrites both)
2. Extensible (data safety rules in Part 2)
3. Debuggable (rtk hook check shows exact rewrites)
4. Multi-platform (Windows support, no JS dependencies)
5. Backward compatible (legacy .sh becomes 4-line shim)

rtk hook claude -- Claude Code PreToolUse handler

Reads JSON from stdin, applies rewriting, outputs JSON to stdout. Fail-open: malformed input exits 0 with no output so Claude proceeds unchanged.

stdin:  {"tool_input":{"command":"git status"}}
stdout: {"hookSpecificOutput":{"permissionDecision":"allow","updatedInput":{"command":"rtk run -c 'git status'"}}}

Chained command rewriting (closes #112)

Before: cd /tmp && git status -- hook only saw cd, missed git status
After: lexer splits on &&/||/; respecting quotes, each command wrapped independently

git commit -m "Fix && Bug" is NOT split (quote-aware).

rtk run -c <command> -- Command executor

Parses chains, detects shellisms (globs/pipes/subshells -> passthrough to sh/cmd), handles builtins (cd/export/pwd), applies output filters, prevents recursion via RTK_ACTIVE env guard.

rtk hook check -- Debugger

rtk hook check "cd /tmp && git status"
# Output: rtk run -c 'cd /tmp' && rtk run -c 'git status'

---

Changes

16 files changed (+2969, -221)

New (src/cmd/): mod.rs, hook.rs, claude_hook.rs, lexer.rs, analysis.rs, builtins.rs, exec.rs, filters.rs, predicates.rs, test_helpers.rs

Modified: src/main.rs (+Commands::Run, +Commands::Hook), src/init.rs (register binary hook), hooks/rtk-rewrite.sh (204-line script -> 4-line shim), Cargo.toml (+which), INSTALL.md (+Windows section)

Intentionally excluded (stacked PRs):

• Safety rules -> PR 2 (feat/data-safety-rules-v2)
• Gemini support -> PR 3 (feat/gemini-support-v2)

---

Review Guide

Focus areas:

1. src/cmd/lexer.rs + analysis.rs -- Chain parsing correctness (quote handling)
2. src/cmd/claude_hook.rs -- Protocol compliance, fail-open design
3. src/cmd/exec.rs -- Builtin handling, Windows shell selection (cfg!(windows))
4. src/cmd/hook.rs -- Shared decision logic (used by Parts 2 and 3)

---

Implementation Notes

Binary size: Compiled with LTO + stripping. Size increase from which dependency minimal (<0.1 MB). Full size impact measurable after all 3 parts merge (PR #131 reported 5.1 MB total, +0.3 MB from combined deps).

Backward compatible: All existing RTK features work unchanged. Legacy bash hook becomes 4-line shim forwarding to rtk hook claude.

---

Test Plan

• cargo test -- 541 tests pass (hook:22, claude_hook:18, lexer:28, analysis:10, builtins:8, exec:22, filters:5, predicates:4)
• echo '{"tool_input":{"command":"git status"}}' | cargo run -- hook claude -- JSON rewrite works
• echo '{"tool_input":{"command":"cd /tmp && git status"}}' | cargo run -- hook claude -- chain split works
• cargo run -- hook check "git status" -- text debugger works
• cargo run -- run -c "echo hello" -- executor works
• grep 'cfg!(windows)' src/cmd/exec.rs -- Windows shell selection present

---

Related PRs (Split from PR #131)

Part	PR	Description
1	#156	Hook Engine + Chained Commands (this PR)
2	#157	Data Safety Rules
3	#158	Gemini CLI Support

Merge order: Part 1 first → retarget Parts 2 & 3 to master → merge in any order

[FlorianBruniaux]

Hi @ahundt! PRs #156 and #158 are showing as CONFLICTING after recent merges. Before we can review the full series (#156, #157, #158), they need to be rebased. Also, given the scope (Hook Engine + Data Safety Rules + Gemini = ~28K lines across 100+ files), could we discuss the rollout strategy in an issue first? We want to make sure we integrate this thoughtfully rather than all at once.

[ahundt]

I updated it again, but new changes keep being merged every time i update it to resolve all the conflicts. Also there is far less code than it seems because there is a massive number of unit tests, check out #361 for details and the discussion as @FlorianBruniaux requested!

[ahundt]

updated again, ready for review! PR #156 is independent of the other two and should be considered on its own, then the other two can be updated if they are desired as they are much smaller changes on top of 156.