diff --git a/CLAUDE.md b/CLAUDE.md
index ab5129619..f9f1b3ec4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -426,6 +426,19 @@ Core dependencies (see Cargo.toml):
 - **colored**: Terminal output formatting
 - **serde/serde_json**: Configuration and JSON parsing
 
+## Debug & Profiling Builds
+
+Global `~/.cargo/config.toml` sets `debug = "line-tables-only"` for dev builds — smaller artifacts, faster builds. Use these named profiles when you need full symbols:
+
+```bash
+cargo build --profile debugging    # Full DWARF symbols for lldb/gdb/CodeLLDB step-through
+cargo test --profile debugging     # Run tests fully debuggable
+cargo build --profile profiling    # Optimized + source lines for flamegraphs/Instruments
+samply record cargo run --profile profiling
+```
+
+---
+
 ## Build Optimizations
 
 Release profile (Cargo.toml:31-36):
@@ -603,3 +616,137 @@ rtk newcmd args
 # 7. Document
 # Update README.md, CHANGELOG.md, this file
 ```
+
+<!-- rtk-instructions v2 -->
+# RTK (Rust Token Killer) - Token-Optimized Commands
+
+## Golden Rule
+
+**Always prefix commands with `rtk`**. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use.
+
+**Important**: Even in command chains with `&&`, use `rtk`:
+```bash
+# ❌ Wrong
+git add . && git commit -m "msg" && git push
+
+# ✅ Correct
+rtk git add . && rtk git commit -m "msg" && rtk git push
+```
+
+## RTK Commands by Workflow
+
+### Build & Compile (80-90% savings)
+```bash
+rtk cargo build         # Cargo build output
+rtk cargo check         # Cargo check output
+rtk cargo clippy        # Clippy warnings grouped by file (80%)
+rtk tsc                 # TypeScript errors grouped by file/code (83%)
+rtk lint                # ESLint/Biome violations grouped (84%)
+rtk prettier --check    # Files needing format only (70%)
+rtk next build          # Next.js build with route metrics (87%)
+```
+
+### Test (90-99% savings)
+```bash
+rtk cargo test          # Cargo test failures only (90%)
+rtk vitest run          # Vitest failures only (99.5%)
+rtk playwright test     # Playwright failures only (94%)
+rtk test <cmd>          # Generic test wrapper - failures only
+```
+
+### Git (59-80% savings)
+```bash
+rtk git status          # Compact status
+rtk git log             # Compact log (works with all git flags)
+rtk git diff            # Compact diff (80%)
+rtk git show            # Compact show (80%)
+rtk git add             # Ultra-compact confirmations (59%)
+rtk git commit          # Ultra-compact confirmations (59%)
+rtk git push            # Ultra-compact confirmations
+rtk git pull            # Ultra-compact confirmations
+rtk git branch          # Compact branch list
+rtk git fetch           # Compact fetch
+rtk git stash           # Compact stash
+rtk git worktree        # Compact worktree
+```
+
+Note: Git passthrough works for ALL subcommands, even those not explicitly listed.
+
+### GitHub (26-87% savings)
+```bash
+rtk gh pr view <num>    # Compact PR view (87%)
+rtk gh pr checks        # Compact PR checks (79%)
+rtk gh run list         # Compact workflow runs (82%)
+rtk gh issue list       # Compact issue list (80%)
+rtk gh api              # Compact API responses (26%)
+```
+
+### JavaScript/TypeScript Tooling (70-90% savings)
+```bash
+rtk pnpm list           # Compact dependency tree (70%)
+rtk pnpm outdated       # Compact outdated packages (80%)
+rtk pnpm install        # Compact install output (90%)
+rtk npm run <script>    # Compact npm script output
+rtk npx <cmd>           # Compact npx command output
+rtk prisma              # Prisma without ASCII art (88%)
+```
+
+### Files & Search (60-75% savings)
+```bash
+rtk ls <path>           # Tree format, compact (65%)
+rtk read <file>         # Code reading with filtering (60%)
+rtk grep <pattern>      # Search grouped by file (75%)
+rtk find <pattern>      # Find grouped by directory (70%)
+```
+
+### Analysis & Debug (70-90% savings)
+```bash
+rtk err <cmd>           # Filter errors only from any command
+rtk log <file>          # Deduplicated logs with counts
+rtk json <file>         # JSON structure without values
+rtk deps                # Dependency overview
+rtk env                 # Environment variables compact
+rtk summary <cmd>       # Smart summary of command output
+rtk diff                # Ultra-compact diffs
+```
+
+### Infrastructure (85% savings)
+```bash
+rtk docker ps           # Compact container list
+rtk docker images       # Compact image list
+rtk docker logs <c>     # Deduplicated logs
+rtk kubectl get         # Compact resource list
+rtk kubectl logs        # Deduplicated pod logs
+```
+
+### Network (65-70% savings)
+```bash
+rtk curl <url>          # Compact HTTP responses (70%)
+rtk wget <url>          # Compact download output (65%)
+```
+
+### Meta Commands
+```bash
+rtk gain                # View token savings statistics
+rtk gain --history      # View command history with savings
+rtk discover            # Analyze Claude Code sessions for missed RTK usage
+rtk proxy <cmd>         # Run command without filtering (for debugging)
+rtk init                # Add RTK instructions to CLAUDE.md
+rtk init --global       # Add RTK to ~/.claude/CLAUDE.md
+```
+
+## Token Savings Overview
+
+| Category | Commands | Typical Savings |
+|----------|----------|-----------------|
+| Tests | vitest, playwright, cargo test | 90-99% |
+| Build | next, tsc, lint, prettier | 70-87% |
+| Git | status, log, diff, add, commit | 59-80% |
+| GitHub | gh pr, gh run, gh issue | 26-87% |
+| Package Managers | pnpm, npm, npx | 70-90% |
+| Files | ls, read, grep, find | 60-75% |
+| Infrastructure | docker, kubectl | 85% |
+| Network | curl, wget | 65-70% |
+
+Overall average: **60-90% token reduction** on common development operations.
+<!-- /rtk-instructions -->
\ No newline at end of file
diff --git a/Cargo.lock b/Cargo.lock
index fd00d7554..9aa0c41c7 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -40,9 +40,9 @@ dependencies = [
 
 [[package]]
 name = "anstream"
-version = "0.6.21"
+version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "43d5b281e737544384e969a5ccad3f1cdd24b48086a0fc1b2a5262a26b8f4f4a"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
 dependencies = [
  "anstyle",
  "anstyle-parse",
@@ -61,9 +61,9 @@ checksum = "5192cca8006f1fd4f7237516f40fa183bb07f8fbdfedaa0036de5ea9b0b45e78"
 
 [[package]]
 name = "anstyle-parse"
-version = "0.2.7"
+version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4e7644824f0aa2c7b9384579234ef10eb7efb6a0deb83f9630a49594dd9c15c2"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
 dependencies = [
  "utf8parse",
 ]
@@ -168,9 +168,9 @@ dependencies = [
 
 [[package]]
 name = "clap"
-version = "4.5.60"
+version = "4.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2797f34da339ce31042b27d23607e051786132987f595b02ba4f6a6dffb7030a"
+checksum = "b193af5b67834b676abd72466a96c1024e6a6ad978a1f484bd90b85c94041351"
 dependencies = [
  "clap_builder",
  "clap_derive",
@@ -178,9 +178,9 @@ dependencies = [
 
 [[package]]
 name = "clap_builder"
-version = "4.5.60"
+version = "4.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "24a241312cea5059b13574bb9b3861cabf758b879c15190b37b6d6fd63ab6876"
+checksum = "714a53001bf66416adb0e2ef5ac857140e7dc3a0c48fb28b2f10762fc4b5069f"
 dependencies = [
  "anstream",
  "anstyle",
@@ -190,9 +190,9 @@ dependencies = [
 
 [[package]]
 name = "clap_derive"
-version = "4.5.55"
+version = "4.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a92793da1a46a5f2a02a6f4c46c6496b28c43638adea8306fcb0caa1634f24e5"
+checksum = "1110bd8a634a1ab8cb04345d8d878267d57c3cf1b38d91b71af6686408bbca6a"
 dependencies = [
  "heck",
  "proc-macro2",
@@ -202,9 +202,9 @@ dependencies = [
 
 [[package]]
 name = "clap_lex"
-version = "1.0.0"
+version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3a822ea5bc7590f9d40f1ba12c0dc3c2760f3482c6984db1573ad11031420831"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
 
 [[package]]
 name = "colorchoice"
@@ -323,12 +323,6 @@ dependencies = [
  "syn",
 ]
 
-[[package]]
-name = "env_home"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c7f84e12ccf0a7ddc17a6c41c93326024c42920d7ee630d04950e6926645c0fe"
-
 [[package]]
 name = "equivalent"
 version = "1.0.2"
@@ -687,9 +681,9 @@ checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
 [[package]]
 name = "libc"
-version = "0.2.182"
+version = "0.2.183"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6800badb6cb2082ffd7b6a67e6125bb39f18782f793520caee8cb8846be06112"
+checksum = "b5b646652bf6661599e1da8901b3b9522896f01e736bad5f723fe7a3a27f899d"
 
 [[package]]
 name = "libredox"
@@ -756,9 +750,9 @@ dependencies = [
 
 [[package]]
 name = "once_cell"
-version = "1.21.3"
+version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "42f5e15c9953c5e4ccceeb2e7382a716482c34515315f7b03532b8b4e8393d2d"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
 [[package]]
 name = "once_cell_polyfill"
@@ -1124,9 +1118,9 @@ dependencies = [
 
 [[package]]
 name = "tempfile"
-version = "3.26.0"
+version = "3.27.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "82a72c767771b47409d2345987fda8628641887d5466101319899796367354a0"
+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
  "fastrand",
  "getrandom 0.4.2",
@@ -1415,13 +1409,11 @@ dependencies = [
 
 [[package]]
 name = "which"
-version = "8.0.1"
+version = "8.0.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3a824aeba0fbb27264f815ada4cff43d65b1741b7a4ed7629ff9089148c4a4e0"
+checksum = "81995fafaaaf6ae47a7d0cc83c67caf92aeb7e5331650ae6ff856f7c0c60c459"
 dependencies = [
- "env_home",
- "rustix",
- "winsafe",
+ "libc",
 ]
 
 [[package]]
@@ -1658,12 +1650,6 @@ dependencies = [
  "memchr",
 ]
 
-[[package]]
-name = "winsafe"
-version = "0.0.19"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d135d17ab770252ad95e9a872d365cf3090e3be864a34ab46f48555993efc904"
-
 [[package]]
 name = "wit-bindgen"
 version = "0.51.0"
@@ -1783,18 +1769,18 @@ dependencies = [
 
 [[package]]
 name = "zerocopy"
-version = "0.8.40"
+version = "0.8.42"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a789c6e490b576db9f7e6b6d661bcc9799f7c0ac8352f56ea20193b2681532e5"
+checksum = "f2578b716f8a7a858b7f02d5bd870c14bf4ddbbcf3a4c05414ba6503640505e3"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.40"
+version = "0.8.42"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f65c489a7071a749c849713807783f70672b28094011623e200cb86dcb835953"
+checksum = "7e6cc098ea4d3bd6246687de65af3f920c430e236bee1e3bf2e441463f08a02f"
 dependencies = [
  "proc-macro2",
  "quote",
diff --git a/Cargo.toml b/Cargo.toml
index 488d962dc..cacc74281 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -26,19 +26,23 @@ rusqlite = { version = "0.31", features = ["bundled"] }
 toml = "0.8"
 chrono = "0.4"
 thiserror = "1.0"
+which = "8"
 tempfile = "3"
 sha2 = "0.10"
 ureq = "2"
 hostname = "0.4"
 flate2 = "1.0"
 quick-xml = "0.37"
-which = "8"
 
 [build-dependencies]
 toml = "0.8"
 
 [dev-dependencies]
 
+[profile.dev.package."*"]
+debug = 0       # No debug symbols for deps — smaller target dir
+opt-level = 1   # Light optimization for deps — faster runtime
+
 [profile.release]
 opt-level = 3
 lto = true
diff --git a/hooks/rtk-rewrite.sh b/hooks/rtk-rewrite.sh
index c9c00f47c..ec2c83610 100644
--- a/hooks/rtk-rewrite.sh
+++ b/hooks/rtk-rewrite.sh
@@ -33,6 +33,32 @@ fi
 INPUT=$(cat)
 CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
 
+# RAII temp file cleanup — trap handles SIGTERM/SIGINT/EXIT to prevent leaks.
+TEMP_FILES=()
+cleanup() { for f in "${TEMP_FILES[@]}"; do [ -n "$f" ] && rm -f "$f"; done; }
+trap cleanup EXIT INT TERM
+
+# Helper: check if response JSON contains a deny decision (CC + Gemini dual format)
+# CC format:     hookSpecificOutput.permissionDecision == "deny"
+# Gemini format: decision == "deny"  (top-level; Gemini handlers use this today)
+# jq -e exits 0 for truthy, 1 for false/null. >/dev/null suppresses output.
+has_json_deny() {
+  local f="$1"; [ -s "$f" ] || return 1
+  jq -e '(.hookSpecificOutput.permissionDecision == "deny") or (.decision == "deny")' \
+    "$f" >/dev/null 2>&1
+}
+
+# Helper: check if response JSON contains updatedInput (rewrite path)
+has_updated_input() {
+  local f="$1"; [ -s "$f" ] || return 1
+  jq -e '.hookSpecificOutput.updatedInput != null' "$f" >/dev/null 2>&1
+}
+
+# Handler tracking arrays — declared here so BEGIN_RTK_BASH_HANDLERS can append to them.
+HANDLER_PIDS=()
+HANDLER_OUTS=()
+HANDLER_ERRS=()
+
 if [ -z "$CMD" ]; then
   exit 0
 fi
@@ -41,21 +67,72 @@ fi
 # rtk rewrite exits 1 when there's no rewrite — hook passes through silently.
 REWRITTEN=$(rtk rewrite "$CMD" 2>/dev/null) || exit 0
 
+
 # No change — nothing to do.
 if [ "$CMD" = "$REWRITTEN" ]; then
   exit 0
 fi
 
-ORIGINAL_INPUT=$(echo "$INPUT" | jq -c '.tool_input')
-UPDATED_INPUT=$(echo "$ORIGINAL_INPUT" | jq --arg cmd "$REWRITTEN" '.command = $cmd')
+# === BEGIN_RTK_BASH_HANDLERS (managed by rtk init — parallel launch) ===
+# rtk init adds handler entries here; each entry must:
+#   1. Allocate and register temp files:  _HN_OUT=$(mktemp); TEMP_FILES+=("$_HN_OUT")
+#   2. Launch in background:              printf '%s' "$INPUT" | handler >"$_HN_OUT" 2>"$_HN_ERR" &
+#   3. Register PID/OUT/ERR:              HANDLER_PIDS+=($!); HANDLER_OUTS+=("$_HN_OUT"); HANDLER_ERRS+=("$_HN_ERR")
+# === END_RTK_BASH_HANDLERS ===
+
+# Build RTK rewrite JSON into temp file (if applicable)
+RTK_OUT=$(mktemp 2>/dev/null) || RTK_OUT=""
+[ -n "$RTK_OUT" ] && TEMP_FILES+=("$RTK_OUT")
+if [ -n "$REWRITTEN" ] && [ -n "$RTK_OUT" ]; then
+  # Build the updated tool_input with all original fields preserved, only command changed
+  ORIGINAL_INPUT=$(echo "$INPUT" | jq -c '.tool_input')
+  UPDATED_INPUT=$(echo "$ORIGINAL_INPUT" | jq --arg cmd "$REWRITTEN" '.command = $cmd')
+  jq -n \
+    --argjson updated "$UPDATED_INPUT" \
+    '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "allow",
+        "permissionDecisionReason": "RTK auto-rewrite",
+        "updatedInput": $updated
+      }
+    }' >"$RTK_OUT" 2>/dev/null
+fi
+
+# COLLECT PHASE: wait for all registered handlers (launched in BEGIN_RTK_BASH_HANDLERS above)
+# ALL handlers run — no short-circuit before this point.
+HANDLER_EXITS=()
+for pid in "${HANDLER_PIDS[@]}"; do
+  wait "$pid" 2>/dev/null
+  HANDLER_EXITS+=($?)
+done
+
+# MERGE PHASE: deny wins over rewrite; rewrite wins over pass-through.
+# Block detection is ONLY here — not in launch phase (all handlers always run).
+BLOCK_OUT=""
+BLOCK_ERR=""
+for i in "${!HANDLER_PIDS[@]}"; do
+  if [ "${HANDLER_EXITS[$i]}" -eq 2 ] || has_json_deny "${HANDLER_OUTS[$i]}"; then
+    BLOCK_OUT="${HANDLER_OUTS[$i]}"
+    BLOCK_ERR="${HANDLER_ERRS[$i]}"
+    break  # First block wins; all handlers already ran above
+  fi
+done
+
+# Block propagation: exit 2 (reliable; bug #4669 workaround for CC, also valid when fixed)
+# trap cleanup handles temp file removal on exit
+if [ -n "$BLOCK_OUT" ]; then
+  [ -s "$BLOCK_OUT" ] && cat "$BLOCK_OUT"
+  [ -n "$BLOCK_ERR" ] && [ -s "$BLOCK_ERR" ] && cat "$BLOCK_ERR" >&2
+  exit 2
+fi
+
+# RTK rewrite: apply if RTK produced one and no handler blocked
+if has_updated_input "$RTK_OUT"; then
+  cat "$RTK_OUT"
+  exit 0
+fi
 
-jq -n \
-  --argjson updated "$UPDATED_INPUT" \
-  '{
-    "hookSpecificOutput": {
-      "hookEventName": "PreToolUse",
-      "permissionDecision": "allow",
-      "permissionDecisionReason": "RTK auto-rewrite",
-      "updatedInput": $updated
-    }
-  }'
+# No opinions from any handler — pass-through (no stdout)
+# (trap cleanup runs automatically on exit)
+exit 0
diff --git a/src/cargo_cmd.rs b/src/cargo_cmd.rs
index 63eea4b7f..5de11a427 100644
--- a/src/cargo_cmd.rs
+++ b/src/cargo_cmd.rs
@@ -1,3 +1,4 @@
+use crate::stream::{FilterMode, StdinMode, StreamFilter};
 use crate::tracking;
 use crate::utils::{resolved_command, truncate};
 use anyhow::{Context, Result};
@@ -122,8 +123,190 @@ fn run_build(args: &[String], verbose: u8) -> Result<()> {
     run_cargo_filtered("build", args, verbose, filter_cargo_build)
 }
 
+/// Progressive streaming filter for `cargo test` output.
+///
+/// Replicates `filter_cargo_test` logic line-by-line. Defers all output to
+/// `flush()` so the full failure+summary picture is available before emitting.
+pub struct CargoTestStreamFilter {
+    failures: Vec<String>,
+    summary_lines: Vec<String>,
+    in_failure_section: bool,
+    current_failure: Vec<String>,
+}
+
+impl CargoTestStreamFilter {
+    pub fn new() -> Self {
+        Self {
+            failures: Vec::new(),
+            summary_lines: Vec::new(),
+            in_failure_section: false,
+            current_failure: Vec::new(),
+        }
+    }
+}
+
+impl Default for CargoTestStreamFilter {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl StreamFilter for CargoTestStreamFilter {
+    fn feed_line(&mut self, line: &str) -> Option<String> {
+        // Skip compilation lines
+        if line.trim_start().starts_with("Compiling")
+            || line.trim_start().starts_with("Downloading")
+            || line.trim_start().starts_with("Downloaded")
+            || line.trim_start().starts_with("Finished")
+        {
+            return None;
+        }
+
+        // Skip "running N tests" and individual "test ... ok" lines
+        if line.starts_with("running ") || (line.starts_with("test ") && line.ends_with("... ok")) {
+            return None;
+        }
+
+        // Detect failures section
+        if line == "failures:" {
+            self.in_failure_section = true;
+            return None;
+        }
+
+        if self.in_failure_section {
+            if line.starts_with("test result:") {
+                self.in_failure_section = false;
+                self.summary_lines.push(line.to_string());
+            } else if line.starts_with("    ") || line.starts_with("---- ") {
+                self.current_failure.push(line.to_string());
+            } else if line.trim().is_empty() && !self.current_failure.is_empty() {
+                let block = self.current_failure.join("\n");
+                self.failures.push(block);
+                self.current_failure.clear();
+            } else if !line.trim().is_empty() {
+                self.current_failure.push(line.to_string());
+            }
+        }
+
+        // Capture test result summary outside failure section
+        if !self.in_failure_section && line.starts_with("test result:") {
+            self.summary_lines.push(line.to_string());
+        }
+
+        None
+    }
+
+    fn flush(&mut self) -> String {
+        // Close any open failure block
+        if !self.current_failure.is_empty() {
+            let block = self.current_failure.join("\n");
+            self.failures.push(block);
+            self.current_failure.clear();
+        }
+
+        build_cargo_test_summary(&self.failures, &self.summary_lines)
+    }
+}
+
+/// Build the formatted cargo test output from accumulated failures + summaries.
+///
+/// Shared by `filter_cargo_test` (buffered) and `CargoTestStreamFilter`
+/// (streaming) to ensure identical output format.
+fn build_cargo_test_summary(failures: &[String], summary_lines: &[String]) -> String {
+    let mut result = String::new();
+
+    if failures.is_empty() && !summary_lines.is_empty() {
+        // All passed - try to aggregate
+        let mut aggregated: Option<AggregatedTestResult> = None;
+        let mut all_parsed = true;
+
+        for line in summary_lines {
+            if let Some(parsed) = AggregatedTestResult::parse_line(line) {
+                if let Some(ref mut agg) = aggregated {
+                    agg.merge(&parsed);
+                } else {
+                    aggregated = Some(parsed);
+                }
+            } else {
+                all_parsed = false;
+                break;
+            }
+        }
+
+        if all_parsed {
+            if let Some(agg) = aggregated {
+                if agg.suites > 0 {
+                    return agg.format_compact();
+                }
+            }
+        }
+
+        // Fallback: use original behavior if regex failed
+        for line in summary_lines {
+            result.push_str(&format!("✓ {}\n", line));
+        }
+        return result.trim().to_string();
+    }
+
+    if !failures.is_empty() {
+        result.push_str(&format!("FAILURES ({}):\n", failures.len()));
+        result.push_str("═══════════════════════════════════════\n");
+        for (i, failure) in failures.iter().enumerate().take(10) {
+            result.push_str(&format!("{}. {}\n", i + 1, truncate(failure, 200)));
+        }
+        if failures.len() > 10 {
+            result.push_str(&format!("\n... +{} more failures\n", failures.len() - 10));
+        }
+        result.push('\n');
+    }
+
+    for line in summary_lines {
+        result.push_str(&format!("{}\n", line));
+    }
+
+    result.trim().to_string()
+}
+
 fn run_test(args: &[String], verbose: u8) -> Result<()> {
-    run_cargo_filtered("test", args, verbose, filter_cargo_test)
+    let timer = tracking::TimedExecution::start();
+
+    let mut cmd = resolved_command("cargo");
+    cmd.arg("test");
+    let restored_args = restore_double_dash(args);
+    for arg in &restored_args {
+        cmd.arg(arg);
+    }
+
+    if verbose > 0 {
+        eprintln!("Running: cargo test {}", restored_args.join(" "));
+    }
+
+    let filter = CargoTestStreamFilter::new();
+    let result = crate::stream::run_streaming(
+        &mut cmd,
+        StdinMode::Inherit,
+        FilterMode::Streaming(Box::new(filter)),
+    )
+    .context("Failed to run cargo test")?;
+
+    if let Some(hint) = crate::tee::tee_and_hint(&result.raw, "cargo_test", result.exit_code) {
+        println!("{}\n{}", result.filtered, hint);
+    } else {
+        println!("{}", result.filtered);
+    }
+
+    timer.track(
+        &format!("cargo test {}", args.join(" ")),
+        &format!("rtk cargo test {}", args.join(" ")),
+        &result.raw,
+        &result.filtered,
+    );
+
+    if result.exit_code != 0 {
+        std::process::exit(result.exit_code);
+    }
+
+    Ok(())
 }
 
 fn run_clippy(args: &[String], verbose: u8) -> Result<()> {
@@ -746,7 +929,7 @@ impl AggregatedTestResult {
 }
 
 /// Filter cargo test output - show failures + summary only
-fn filter_cargo_test(output: &str) -> String {
+pub(crate) fn filter_cargo_test(output: &str) -> String {
     let mut failures: Vec<String> = Vec::new();
     let mut summary_lines: Vec<String> = Vec::new();
     let mut in_failure_section = false;
@@ -1761,4 +1944,178 @@ error: test run failed
             result
         );
     }
+
+    // ── CargoTestStreamFilter tests ────────────────────────────────────────────
+
+    const CARGO_ALL_PASS: &str = r#"   Compiling rtk v0.5.0
+    Finished test [unoptimized + debuginfo] target(s) in 2.53s
+     Running target/debug/deps/rtk-abc123
+
+running 15 tests
+test utils::tests::test_truncate_short_string ... ok
+test utils::tests::test_truncate_long_string ... ok
+
+test result: ok. 15 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s
+"#;
+
+    const CARGO_WITH_FAILURE: &str = r#"running 5 tests
+test foo::test_a ... ok
+test foo::test_b ... FAILED
+test foo::test_c ... ok
+
+failures:
+
+---- foo::test_b stdout ----
+thread 'foo::test_b' panicked at 'assert_eq!(1, 2)'
+
+failures:
+    foo::test_b
+
+test result: FAILED. 4 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out
+"#;
+
+    #[test]
+    fn test_cargo_test_stream_filter_feed_and_flush_all_pass() {
+        let mut f = CargoTestStreamFilter::new();
+        for line in CARGO_ALL_PASS.lines() {
+            assert_eq!(
+                f.feed_line(line),
+                None,
+                "streaming filter must defer output"
+            );
+        }
+        let output = f.flush();
+        assert!(output.contains("cargo test:"), "output={}", output);
+        assert!(output.contains("15 passed"), "output={}", output);
+    }
+
+    #[test]
+    fn test_cargo_test_stream_filter_feed_and_flush_with_failure() {
+        let mut f = CargoTestStreamFilter::new();
+        for line in CARGO_WITH_FAILURE.lines() {
+            f.feed_line(line);
+        }
+        let output = f.flush();
+        assert!(output.contains("FAILURES"), "output={}", output);
+        assert!(output.contains("test_b"), "output={}", output);
+    }
+
+    #[test]
+    fn test_cargo_test_stream_filter_matches_buffered_all_pass() {
+        let buffered = filter_cargo_test(CARGO_ALL_PASS);
+        let mut f = CargoTestStreamFilter::new();
+        for line in CARGO_ALL_PASS.lines() {
+            f.feed_line(line);
+        }
+        let streamed = f.flush();
+        assert_eq!(streamed.trim(), buffered.trim());
+    }
+
+    #[test]
+    fn test_cargo_test_stream_filter_matches_buffered_with_failures() {
+        let buffered = filter_cargo_test(CARGO_WITH_FAILURE);
+        let mut f = CargoTestStreamFilter::new();
+        for line in CARGO_WITH_FAILURE.lines() {
+            f.feed_line(line);
+        }
+        let streamed = f.flush();
+        assert_eq!(streamed.trim(), buffered.trim());
+    }
+
+    #[test]
+    fn test_cargo_test_stream_filter_default_equals_new() {
+        let mut f1 = CargoTestStreamFilter::new();
+        let mut f2 = CargoTestStreamFilter::default();
+        assert_eq!(f1.flush(), f2.flush());
+    }
+
+    // ── additional restore_double_dash edge case tests ─────────────────────
+    // (adapted from hooks-v2's split_at_double_dash tests to cover extra cases)
+
+    #[test]
+    fn test_restore_double_dash_with_flag_before_separator() {
+        // rtk cargo test --lib -- --test-threads=1
+        // Clap gives ["--lib", "--test-threads=1"] (-- stripped)
+        let args = vec!["--lib".into(), "--test-threads=1".into()];
+        let raw = vec![
+            "rtk".into(),
+            "cargo".into(),
+            "test".into(),
+            "--lib".into(),
+            "--".into(),
+            "--test-threads=1".into(),
+        ];
+        let result = restore_double_dash_with_raw(&args, &raw);
+        assert_eq!(result, vec!["--lib", "--", "--test-threads=1"]);
+    }
+
+    #[test]
+    fn test_restore_double_dash_bare_separator_no_args_after() {
+        // rtk cargo test --lib --  (bare -- with nothing after)
+        // Clap gives ["--lib"] (-- stripped, nothing after it)
+        let args = vec!["--lib".into()];
+        let raw = vec![
+            "rtk".into(),
+            "cargo".into(),
+            "test".into(),
+            "--lib".into(),
+            "--".into(),
+        ];
+        let result = restore_double_dash_with_raw(&args, &raw);
+        // Should insert -- even though nothing follows it
+        assert_eq!(result, vec!["--lib", "--"]);
+    }
+
+    #[test]
+    fn test_restore_double_dash_no_separator_in_raw() {
+        // rtk cargo test --lib (no -- anywhere)
+        let args = vec!["--lib".into()];
+        let raw = vec!["rtk".into(), "cargo".into(), "test".into(), "--lib".into()];
+        let result = restore_double_dash_with_raw(&args, &raw);
+        // No --, args unchanged
+        assert_eq!(result, vec!["--lib"]);
+    }
+
+    #[test]
+    fn test_restore_double_dash_multiple_args_before_and_after() {
+        // rtk cargo test --lib my_test -- --nocapture --test-threads=4
+        let args = vec![
+            "--lib".into(),
+            "my_test".into(),
+            "--nocapture".into(),
+            "--test-threads=4".into(),
+        ];
+        let raw = vec![
+            "rtk".into(),
+            "cargo".into(),
+            "test".into(),
+            "--lib".into(),
+            "my_test".into(),
+            "--".into(),
+            "--nocapture".into(),
+            "--test-threads=4".into(),
+        ];
+        let result = restore_double_dash_with_raw(&args, &raw);
+        assert_eq!(
+            result,
+            vec!["--lib", "my_test", "--", "--nocapture", "--test-threads=4"]
+        );
+    }
+
+    #[test]
+    fn test_restore_double_dash_nextest() {
+        // rtk cargo nextest run -- --test-threads 1
+        let args = vec!["--test-threads".into(), "1".into()];
+        let raw = vec![
+            "rtk".into(),
+            "cargo".into(),
+            "nextest".into(),
+            "run".into(),
+            "--".into(),
+            "--test-threads".into(),
+            "1".into(),
+        ];
+        let result = restore_double_dash_with_raw(&args, &raw);
+        assert_eq!(result, vec!["--", "--test-threads", "1"]);
+    }
 }
diff --git a/src/cmd/analysis.rs b/src/cmd/analysis.rs
new file mode 100644
index 000000000..c2e82df47
--- /dev/null
+++ b/src/cmd/analysis.rs
@@ -0,0 +1,868 @@
+//! Analyzes tokens to decide: Native execution or Passthrough?
+
+use super::lexer::{strip_quotes, ParsedToken, TokenKind};
+
+/// Represents a single command in a chain
+#[derive(Debug, Clone, PartialEq)]
+pub struct NativeCommand {
+    pub binary: String,
+    pub args: Vec<String>,
+    pub operator: Option<String>, // &&, ||, ;, or None for last command
+}
+
+/// Try to strip a known "safe" redirect or pipe suffix from the end of a token list.
+///
+/// Safe suffixes are shell constructs that can be applied to any command's output
+/// without changing the command's semantics.  By stripping them, the hook can route
+/// the core command through an RTK filter and then re-attach the suffix in the shell.
+///
+/// # Returns
+/// `(core_tokens, suffix_string)` where:
+/// - `core_tokens` is the token list with the suffix removed (unchanged if no match)
+/// - `suffix_string` is the raw shell suffix to append to the rewritten command, or `""`
+///
+/// # Recognized patterns (checked from longest to shortest)
+/// - `2>&1`           — Arg("2") + Redirect(">") + Shellism("&") + Arg("1")
+/// - `| tee <file>`   — Pipe + Arg("tee") + Arg(any)
+/// - `| head <arg>`   — Pipe + Arg("head"/"tail") + Arg(any)
+/// - `| cat`          — Pipe + Arg("cat")
+/// - `2>/dev/null`    — Arg("2") + Redirect(">") + Arg("/dev/null")
+/// - `> /dev/null`    — Redirect(">") + Arg("/dev/null")
+/// - `>> <file>`      — Redirect(">>") + Arg(any)
+/// - `&`              — Shellism("&") at end, only when no other Shellism in core
+///   (`cargo build &` → core `cargo build`, suffix `&`; `cargo build 2>&1 &` → no strip,
+///   because the `&` in `2>&1` is already a Shellism in the core)
+pub fn split_safe_suffix(mut tokens: Vec<ParsedToken>) -> (Vec<ParsedToken>, String) {
+    let mut suffixes: Vec<String> = Vec::new();
+
+    loop {
+        let n = tokens.len();
+        let mut matched_len: usize = 0;
+        let mut matched_suffix = String::new();
+
+        // 4-token: 2>&1
+        if n >= 5 {
+            let t = &tokens[n - 4..];
+            if matches!(t[0].kind, TokenKind::Arg)
+                && t[0].value == "2"
+                && matches!(t[1].kind, TokenKind::Redirect)
+                && t[1].value == ">"
+                && matches!(t[2].kind, TokenKind::Shellism)
+                && t[2].value == "&"
+                && matches!(t[3].kind, TokenKind::Arg)
+                && t[3].value == "1"
+            {
+                matched_suffix = "2>&1".to_string();
+                matched_len = 4;
+            }
+        }
+
+        // 3-token: | tee <file>
+        if matched_len == 0 && n >= 4 {
+            let t = &tokens[n - 3..];
+            if matches!(t[0].kind, TokenKind::Pipe)
+                && matches!(t[1].kind, TokenKind::Arg)
+                && t[1].value == "tee"
+                && matches!(t[2].kind, TokenKind::Arg)
+            {
+                matched_suffix = format!("| tee {}", t[2].value);
+                matched_len = 3;
+            }
+        }
+
+        // 3-token: | head <arg> or | tail <arg>
+        if matched_len == 0 && n >= 4 {
+            let t = &tokens[n - 3..];
+            if matches!(t[0].kind, TokenKind::Pipe)
+                && matches!(t[1].kind, TokenKind::Arg)
+                && matches!(t[1].value.as_str(), "head" | "tail")
+                && matches!(t[2].kind, TokenKind::Arg)
+            {
+                matched_suffix = format!("| {} {}", t[1].value, t[2].value);
+                matched_len = 3;
+            }
+        }
+
+        // 3-token: 2>/dev/null
+        if matched_len == 0 && n >= 4 {
+            let t = &tokens[n - 3..];
+            if matches!(t[0].kind, TokenKind::Arg)
+                && t[0].value == "2"
+                && matches!(t[1].kind, TokenKind::Redirect)
+                && t[1].value == ">"
+                && matches!(t[2].kind, TokenKind::Arg)
+                && t[2].value == "/dev/null"
+            {
+                matched_suffix = "2>/dev/null".to_string();
+                matched_len = 3;
+            }
+        }
+
+        // 2-token: | cat
+        if matched_len == 0 && n >= 3 {
+            let t = &tokens[n - 2..];
+            if matches!(t[0].kind, TokenKind::Pipe)
+                && matches!(t[1].kind, TokenKind::Arg)
+                && t[1].value == "cat"
+            {
+                matched_suffix = "| cat".to_string();
+                matched_len = 2;
+            }
+        }
+
+        // 2-token: > /dev/null
+        if matched_len == 0 && n >= 3 {
+            let t = &tokens[n - 2..];
+            if matches!(t[0].kind, TokenKind::Redirect)
+                && t[0].value == ">"
+                && matches!(t[1].kind, TokenKind::Arg)
+                && t[1].value == "/dev/null"
+            {
+                matched_suffix = "> /dev/null".to_string();
+                matched_len = 2;
+            }
+        }
+
+        // 2-token: >> <file>
+        if matched_len == 0 && n >= 3 {
+            let t = &tokens[n - 2..];
+            if matches!(t[0].kind, TokenKind::Redirect)
+                && t[0].value == ">>"
+                && matches!(t[1].kind, TokenKind::Arg)
+            {
+                matched_suffix = format!(">> {}", t[1].value);
+                matched_len = 2;
+            }
+        }
+
+        // 1-token: & (trailing background job operator)
+        // Guard: strip only when no other Shellism exists in the core.
+        if matched_len == 0 && n >= 2 {
+            let last = &tokens[n - 1];
+            if matches!(last.kind, TokenKind::Shellism) && last.value == "&" {
+                let core = &tokens[..n - 1];
+                if !core.iter().any(|t| matches!(t.kind, TokenKind::Shellism)) {
+                    matched_suffix = "&".to_string();
+                    matched_len = 1;
+                }
+            }
+        }
+
+        if matched_len == 0 {
+            break;
+        }
+
+        tokens.truncate(n - matched_len);
+        suffixes.push(matched_suffix);
+    }
+
+    suffixes.reverse();
+    let suffix = suffixes.join(" ");
+    (tokens, suffix)
+}
+
+/// Check if command needs real shell (has shellisms, pipes, redirects)
+pub fn needs_shell(tokens: &[ParsedToken]) -> bool {
+    tokens.iter().any(|t| {
+        matches!(
+            t.kind,
+            TokenKind::Shellism | TokenKind::Pipe | TokenKind::Redirect
+        )
+    })
+}
+
+/// Parse tokens into native command chain
+/// Returns error if syntax is invalid (e.g., operator with no preceding command)
+pub fn parse_chain(tokens: Vec<ParsedToken>) -> Result<Vec<NativeCommand>, String> {
+    let mut commands = Vec::new();
+    let mut current_args = Vec::new();
+
+    for token in tokens {
+        match token.kind {
+            TokenKind::Arg => {
+                // Strip quotes from the argument
+                current_args.push(strip_quotes(&token.value));
+            }
+            TokenKind::Operator => {
+                if current_args.is_empty() {
+                    return Err(format!(
+                        "Syntax error: operator {} with no command",
+                        token.value
+                    ));
+                }
+                // First arg is the binary, rest are args
+                let binary = current_args.remove(0);
+                commands.push(NativeCommand {
+                    binary,
+                    args: current_args.clone(),
+                    operator: Some(token.value.clone()),
+                });
+                current_args.clear();
+            }
+            TokenKind::Pipe | TokenKind::Redirect | TokenKind::Shellism => {
+                // Should not reach here if needs_shell() was checked first
+                // But handle gracefully
+                return Err(format!(
+                    "Unexpected {:?} in native mode - use passthrough",
+                    token.kind
+                ));
+            }
+        }
+    }
+
+    // Handle last command (no trailing operator)
+    if !current_args.is_empty() {
+        let binary = current_args.remove(0);
+        commands.push(NativeCommand {
+            binary,
+            args: current_args,
+            operator: None,
+        });
+    }
+
+    Ok(commands)
+}
+
+/// Should the next command run based on operator and last result?
+pub fn should_run(operator: Option<&str>, last_success: bool) -> bool {
+    match operator {
+        Some("&&") => last_success,
+        Some("||") => !last_success,
+        Some(";") | None => true,
+        _ => true, // Unknown operator, just run
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cmd::lexer::tokenize;
+
+    // === SPLIT_SAFE_SUFFIX TESTS ===
+
+    #[test]
+    fn test_split_suffix_2_redirect() {
+        let tokens = tokenize("cargo test 2>&1");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(suffix, "2>&1");
+        assert!(!needs_shell(&core), "core must not need shell");
+        let cmds = parse_chain(core).unwrap();
+        assert_eq!(cmds[0].binary, "cargo");
+        assert_eq!(cmds[0].args, vec!["test"]);
+    }
+
+    #[test]
+    fn test_split_suffix_dev_null() {
+        let tokens = tokenize("cargo test 2>/dev/null");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(suffix, "2>/dev/null");
+        let cmds = parse_chain(core).unwrap();
+        assert_eq!(cmds[0].binary, "cargo");
+    }
+
+    #[test]
+    fn test_split_suffix_stdout_dev_null() {
+        let tokens = tokenize("cargo test > /dev/null");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(suffix, "> /dev/null");
+        let cmds = parse_chain(core).unwrap();
+        assert_eq!(cmds[0].binary, "cargo");
+    }
+
+    #[test]
+    fn test_split_suffix_pipe_tee() {
+        let tokens = tokenize("cargo test | tee /tmp/log.txt");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert!(suffix.starts_with("| tee"), "suffix: {suffix}");
+        assert!(suffix.contains("/tmp/log.txt"), "suffix: {suffix}");
+        let cmds = parse_chain(core).unwrap();
+        assert_eq!(cmds[0].binary, "cargo");
+    }
+
+    #[test]
+    fn test_split_suffix_pipe_head() {
+        let tokens = tokenize("git log | head -20");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert!(suffix.starts_with("| head"), "suffix: {suffix}");
+        let cmds = parse_chain(core).unwrap();
+        assert_eq!(cmds[0].binary, "git");
+    }
+
+    #[test]
+    fn test_split_suffix_pipe_tail() {
+        let tokens = tokenize("git log | tail -10");
+        let (_core, suffix) = split_safe_suffix(tokens);
+        assert!(suffix.starts_with("| tail"), "suffix: {suffix}");
+    }
+
+    #[test]
+    fn test_split_suffix_pipe_cat() {
+        let tokens = tokenize("ls --color | cat");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(suffix, "| cat");
+        let cmds = parse_chain(core).unwrap();
+        assert_eq!(cmds[0].binary, "ls");
+    }
+
+    #[test]
+    fn test_split_suffix_append_redirect() {
+        let tokens = tokenize("cargo build >> /tmp/build.log");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert!(suffix.starts_with(">>"), "suffix: {suffix}");
+        let cmds = parse_chain(core).unwrap();
+        assert_eq!(cmds[0].binary, "cargo");
+    }
+
+    #[test]
+    fn test_split_suffix_none() {
+        // No suffix — returns all tokens unchanged, empty suffix
+        let tokens = tokenize("cargo test");
+        let n = tokens.len();
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert!(suffix.is_empty(), "no suffix expected, got: {suffix}");
+        assert_eq!(core.len(), n);
+    }
+
+    #[test]
+    fn test_split_suffix_glob_core_stays_shellism() {
+        // "ls *.rs 2>&1" — suffix strips fine but core has glob (needs shell)
+        let tokens = tokenize("ls *.rs 2>&1");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(suffix, "2>&1", "suffix must be stripped");
+        assert!(needs_shell(&core), "core still needs shell due to glob");
+    }
+
+    #[test]
+    fn test_split_suffix_requires_core_token() {
+        // "2>&1" alone has no core — should not strip (or return empty core)
+        // The function requires at least 1 core token before the suffix
+        let tokens = tokenize("2>&1");
+        let (core, suffix) = split_safe_suffix(tokens);
+        // No valid split (core would be empty)
+        assert!(
+            suffix.is_empty() || core.is_empty(),
+            "bare suffix with no core should not produce a valid split"
+        );
+    }
+
+    // === NEEDS_SHELL TESTS ===
+
+    #[test]
+    fn test_needs_shell_simple() {
+        let tokens = tokenize("git status");
+        assert!(!needs_shell(&tokens));
+    }
+
+    #[test]
+    fn test_needs_shell_with_glob() {
+        let tokens = tokenize("ls *.rs");
+        assert!(needs_shell(&tokens));
+    }
+
+    #[test]
+    fn test_needs_shell_with_pipe() {
+        let tokens = tokenize("cat file | grep x");
+        assert!(needs_shell(&tokens));
+    }
+
+    #[test]
+    fn test_needs_shell_with_redirect() {
+        let tokens = tokenize("cmd > file");
+        assert!(needs_shell(&tokens));
+    }
+
+    #[test]
+    fn test_needs_shell_with_chain() {
+        let tokens = tokenize("cd dir && git status");
+        // && is an Operator, not a Shellism - should NOT need shell
+        assert!(!needs_shell(&tokens));
+    }
+
+    // === PARSE_CHAIN TESTS ===
+
+    #[test]
+    fn test_parse_simple_command() {
+        let tokens = tokenize("git status");
+        let cmds = parse_chain(tokens).unwrap();
+        assert_eq!(cmds.len(), 1);
+        assert_eq!(cmds[0].binary, "git");
+        assert_eq!(cmds[0].args, vec!["status"]);
+        assert_eq!(cmds[0].operator, None);
+    }
+
+    #[test]
+    fn test_parse_command_with_multiple_args() {
+        let tokens = tokenize("git commit -m message");
+        let cmds = parse_chain(tokens).unwrap();
+        assert_eq!(cmds.len(), 1);
+        assert_eq!(cmds[0].binary, "git");
+        assert_eq!(cmds[0].args, vec!["commit", "-m", "message"]);
+    }
+
+    #[test]
+    fn test_parse_chained_and() {
+        let tokens = tokenize("cd dir && git status");
+        let cmds = parse_chain(tokens).unwrap();
+        assert_eq!(cmds.len(), 2);
+        assert_eq!(cmds[0].binary, "cd");
+        assert_eq!(cmds[0].args, vec!["dir"]);
+        assert_eq!(cmds[0].operator, Some("&&".to_string()));
+        assert_eq!(cmds[1].binary, "git");
+        assert_eq!(cmds[1].args, vec!["status"]);
+        assert_eq!(cmds[1].operator, None);
+    }
+
+    #[test]
+    fn test_parse_chained_or() {
+        let tokens = tokenize("cmd1 || cmd2");
+        let cmds = parse_chain(tokens).unwrap();
+        assert_eq!(cmds.len(), 2);
+        assert_eq!(cmds[0].operator, Some("||".to_string()));
+    }
+
+    #[test]
+    fn test_parse_chained_semicolon() {
+        let tokens = tokenize("cmd1 ; cmd2 ; cmd3");
+        let cmds = parse_chain(tokens).unwrap();
+        assert_eq!(cmds.len(), 3);
+        assert_eq!(cmds[0].operator, Some(";".to_string()));
+        assert_eq!(cmds[1].operator, Some(";".to_string()));
+        assert_eq!(cmds[2].operator, None);
+    }
+
+    #[test]
+    fn test_parse_triple_chain() {
+        let tokens = tokenize("a && b && c");
+        let cmds = parse_chain(tokens).unwrap();
+        assert_eq!(cmds.len(), 3);
+    }
+
+    #[test]
+    fn test_parse_operator_at_start() {
+        let tokens = tokenize("&& cmd");
+        let result = parse_chain(tokens);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_parse_operator_at_end() {
+        let tokens = tokenize("cmd &&");
+        let cmds = parse_chain(tokens).unwrap();
+        // cmd is parsed, && triggers flush but no second command
+        assert_eq!(cmds.len(), 1);
+        assert_eq!(cmds[0].operator, Some("&&".to_string()));
+    }
+
+    #[test]
+    fn test_parse_quoted_arg() {
+        let tokens = tokenize("git commit -m \"Fix && Bug\"");
+        let cmds = parse_chain(tokens).unwrap();
+        assert_eq!(cmds.len(), 1);
+        // The && inside quotes should be in the arg, not an operator
+        // args are: commit, -m, "Fix && Bug"
+        assert_eq!(cmds[0].args.len(), 3);
+        assert_eq!(cmds[0].args[2], "Fix && Bug");
+    }
+
+    #[test]
+    fn test_parse_empty() {
+        let tokens = tokenize("");
+        let cmds = parse_chain(tokens).unwrap();
+        assert!(cmds.is_empty());
+    }
+
+    // === PIPE/FIND/GREP ROUTING TESTS ===
+    // These verify that piped invocations of find/grep/rg correctly trigger
+    // needs_shell(), so the hook routes them to /bin/sh instead of native mode.
+
+    #[test]
+    fn test_needs_shell_find_piped_to_grep() {
+        // `find . -name "*.rs" | grep pattern` must go through shell (has Pipe)
+        let tokens = tokenize("find . -name \"*.rs\" | grep pattern");
+        assert!(
+            needs_shell(&tokens),
+            "find | grep must trigger shell (Pipe token present)"
+        );
+    }
+
+    #[test]
+    fn test_needs_shell_rg_piped_to_head() {
+        let tokens = tokenize("rg pattern src/ | head -20");
+        assert!(needs_shell(&tokens), "rg | head must trigger shell");
+    }
+
+    #[test]
+    fn test_needs_shell_grep_with_redirect() {
+        let tokens = tokenize("grep -r pattern . > results.txt");
+        assert!(needs_shell(&tokens), "grep > file must trigger shell");
+    }
+
+    #[test]
+    fn test_needs_shell_find_with_glob_arg() {
+        // find . -name *.rs — glob in arg triggers Shellism
+        let tokens = tokenize("find . -name *.rs");
+        assert!(needs_shell(&tokens), "unquoted glob arg must trigger shell");
+    }
+
+    #[test]
+    fn test_needs_shell_quoted_pipe_in_grep_arg_no_shell() {
+        // grep "a|b" file — pipe inside quotes is an Arg, not a Pipe token
+        let tokens = tokenize("grep \"a|b\" src/");
+        assert!(
+            !needs_shell(&tokens),
+            "pipe inside quoted arg must NOT trigger shell"
+        );
+    }
+
+    #[test]
+    fn test_parse_chain_find_with_quoted_name() {
+        // `find . -name "*.rs"` with quoted glob → no shellism; parses natively
+        let tokens = tokenize("find . -name \"*.rs\"");
+        assert!(!needs_shell(&tokens), "quoted glob should not need shell");
+        let cmds = parse_chain(tokens).unwrap();
+        assert_eq!(cmds[0].binary, "find");
+        assert!(cmds[0].args.contains(&"-name".to_string()));
+        // strip_quotes removes the outer quotes
+        assert!(
+            cmds[0].args.iter().any(|a| a == "*.rs"),
+            "quoted glob stripped to bare glob in args: {:?}",
+            cmds[0].args
+        );
+    }
+
+    #[test]
+    fn test_parse_chain_grep_native_no_pipe() {
+        // `grep pattern file` — no pipe/redirect, parses natively
+        let tokens = tokenize("grep pattern file.rs");
+        assert!(!needs_shell(&tokens));
+        let cmds = parse_chain(tokens).unwrap();
+        assert_eq!(cmds[0].binary, "grep");
+        assert_eq!(cmds[0].args, vec!["pattern", "file.rs"]);
+    }
+
+    // === SHOULD_RUN TESTS ===
+
+    #[test]
+    fn test_should_run_and_success() {
+        assert!(should_run(Some("&&"), true));
+    }
+
+    #[test]
+    fn test_should_run_and_failure() {
+        assert!(!should_run(Some("&&"), false));
+    }
+
+    #[test]
+    fn test_should_run_or_success() {
+        assert!(!should_run(Some("||"), true));
+    }
+
+    #[test]
+    fn test_should_run_or_failure() {
+        assert!(should_run(Some("||"), false));
+    }
+
+    #[test]
+    fn test_should_run_semicolon() {
+        assert!(should_run(Some(";"), true));
+        assert!(should_run(Some(";"), false));
+    }
+
+    #[test]
+    fn test_should_run_none() {
+        assert!(should_run(None, true));
+        assert!(should_run(None, false));
+    }
+
+    // === SUFFIX REDIRECT TESTS — common patterns Claude Code appends ===
+    // These lock in behaviour that must never silently regress.
+
+    // --- stdout / stderr discard ---
+    #[test]
+    fn test_needs_shell_redirect_to_dev_null() {
+        let tokens = tokenize("cmd > /dev/null");
+        assert!(needs_shell(&tokens), "> /dev/null must trigger shell");
+    }
+
+    #[test]
+    fn test_needs_shell_stderr_to_dev_null() {
+        // "2>/dev/null" produces a "2>" Redirect token → needs_shell
+        let tokens = tokenize("cmd 2>/dev/null");
+        assert!(needs_shell(&tokens), "2>/dev/null must trigger shell");
+    }
+
+    #[test]
+    fn test_needs_shell_stderr_to_dev_null_spaced() {
+        let tokens = tokenize("cmd 2> /dev/null");
+        assert!(needs_shell(&tokens), "2> /dev/null must trigger shell");
+    }
+
+    // --- compound FD redirects (2>&1, 1>&2) ---
+    // The `&` in "2>&1" tokenises as Shellism; Shellism triggers needs_shell.
+    #[test]
+    fn test_needs_shell_stderr_to_stdout() {
+        let tokens = tokenize("cmd 2>&1");
+        assert!(
+            needs_shell(&tokens),
+            "2>&1 must trigger shell (& is Shellism)"
+        );
+    }
+
+    #[test]
+    fn test_needs_shell_stdout_to_stderr() {
+        let tokens = tokenize("cmd 1>&2");
+        assert!(
+            needs_shell(&tokens),
+            "1>&2 must trigger shell (& is Shellism)"
+        );
+    }
+
+    #[test]
+    fn test_needs_shell_combined_redirect_chain() {
+        // Classic "silence everything": >/dev/null 2>&1
+        let tokens = tokenize("cmd > /dev/null 2>&1");
+        assert!(needs_shell(&tokens), ">/dev/null 2>&1 must trigger shell");
+    }
+
+    #[test]
+    fn test_needs_shell_redirect_append() {
+        let tokens = tokenize("cmd >> /tmp/output.txt");
+        assert!(needs_shell(&tokens), ">> must trigger shell");
+    }
+
+    #[test]
+    fn test_needs_shell_stderr_redirect_to_file() {
+        let tokens = tokenize("cmd 2> /tmp/err.log");
+        assert!(needs_shell(&tokens), "2> file must trigger shell");
+    }
+
+    // --- pipe suffixes ---
+    #[test]
+    fn test_needs_shell_pipe_to_tail() {
+        let tokens = tokenize("git log | tail -20");
+        assert!(needs_shell(&tokens), "| tail must trigger shell");
+    }
+
+    #[test]
+    fn test_needs_shell_pipe_to_cat() {
+        // Piping to `cat` forces non-TTY output; must go through shell
+        let tokens = tokenize("ls --color | cat");
+        assert!(needs_shell(&tokens), "| cat must trigger shell");
+    }
+
+    #[test]
+    fn test_needs_shell_pipe_to_tee() {
+        let tokens = tokenize("cargo build 2>&1 | tee /tmp/build.log");
+        assert!(needs_shell(&tokens), "| tee must trigger shell");
+    }
+
+    #[test]
+    fn test_needs_shell_pipe_to_wc() {
+        let tokens = tokenize("find . -name '*.rs' | wc -l");
+        assert!(needs_shell(&tokens), "| wc must trigger shell");
+    }
+
+    // --- compound chains that must NOT trigger shell alone ---
+    #[test]
+    fn test_operator_and_does_not_trigger_shell() {
+        // && is an Operator, not Shellism/Pipe/Redirect; handled by parse_chain
+        let tokens = tokenize("cargo fmt && cargo clippy");
+        assert!(
+            !needs_shell(&tokens),
+            "&& alone must NOT trigger needs_shell"
+        );
+    }
+
+    #[test]
+    fn test_operator_or_does_not_trigger_shell() {
+        let tokens = tokenize("cargo test || true");
+        assert!(
+            !needs_shell(&tokens),
+            "|| alone must NOT trigger needs_shell"
+        );
+    }
+
+    #[test]
+    fn test_operator_semicolon_does_not_trigger_shell() {
+        let tokens = tokenize("true ; false");
+        assert!(
+            !needs_shell(&tokens),
+            "; alone must NOT trigger needs_shell"
+        );
+    }
+
+    // --- RTK-rewrite end-to-end: suffix redirect preserves original command ---
+    #[test]
+    fn test_redirect_suffix_is_passed_through_verbatim() {
+        // When needs_shell, the hook wraps in "rtk run -c '<raw>'"
+        // Verify routing logic sends the command to passthrough, not native routing
+        use crate::cmd::analysis::needs_shell;
+        use crate::cmd::lexer::tokenize;
+        let raw = "cargo test 2>&1 | tee /tmp/test.log";
+        let tokens = tokenize(raw);
+        assert!(
+            needs_shell(&tokens),
+            "complex redirect+pipe must trigger shell passthrough"
+        );
+    }
+
+    // === BACKGROUND JOB SUFFIX TESTS ===
+    // These lock in correct behaviour for trailing `&` (background job operator).
+
+    #[test]
+    fn test_background_job_suffix_simple() {
+        // "cargo build &" → core "cargo build", suffix "&"
+        // RTK can rewrite the core; shell handles backgrounding.
+        let tokens = tokenize("cargo build &");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(suffix, "&", "trailing & must be stripped as safe suffix");
+        assert_eq!(core.len(), 2, "core must contain only 'cargo' and 'build'");
+        assert!(
+            !needs_shell(&core),
+            "core with no Shellism must not require shell"
+        );
+    }
+
+    #[test]
+    fn test_background_job_suffix_git_status() {
+        // "git status &" — a common RTK-handled command with trailing &
+        let tokens = tokenize("git status &");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(suffix, "&");
+        assert_eq!(core.len(), 2);
+        assert!(!needs_shell(&core));
+    }
+
+    #[test]
+    fn test_background_job_suffix_blocked_by_fd_redirect_shellism() {
+        // "cargo build 2>&1 &" — the & in 2>&1 is Shellism in the core.
+        // Guard must fire → trailing & NOT stripped → shell handles whole command.
+        let tokens = tokenize("cargo build 2>&1 &");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert!(
+            suffix.is_empty(),
+            "& must NOT be stripped when core contains Shellism from 2>&1; got suffix={:?}",
+            suffix
+        );
+        // core still has the & from 2>&1, so needs_shell must be true
+        assert!(
+            needs_shell(&core),
+            "2>&1 & must need shell (Shellism from 2>&1 in core)"
+        );
+    }
+
+    #[test]
+    fn test_background_job_suffix_single_token_not_stripped() {
+        // Edge case: a single "&" token with nothing before it.
+        // n >= 2 guard means we must have at least 1 core token to strip.
+        let tokens = tokenize("&");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert!(
+            suffix.is_empty(),
+            "bare & with no core command must not be stripped"
+        );
+        assert_eq!(core.len(), 1, "token list must be returned unchanged");
+    }
+
+    #[test]
+    fn test_cargo_test_pipe_grep_is_not_safe_suffix() {
+        // "cargo test | grep FAILED" — the pipe to grep is NOT a safe suffix (grep is format-sensitive).
+        // This is the key regression guard: general non-transparent pipes must route to shell.
+        // split_safe_suffix must not strip "| grep FAILED"; needs_shell must be true for all tokens.
+        let tokens = tokenize("cargo test | grep FAILED");
+        let (_core, suffix) = split_safe_suffix(tokens.clone());
+        assert!(
+            suffix.is_empty(),
+            "| grep must NOT be a safe suffix; got: {:?}",
+            suffix
+        );
+        assert!(
+            needs_shell(&tokens),
+            "pipe to grep must trigger shell passthrough"
+        );
+    }
+
+    #[test]
+    fn test_nohup_background_strips_ampersand() {
+        // "nohup cargo build &" — nohup is a command, & is the trailing background operator.
+        // The & safe-suffix fix strips it; core = ["nohup", "cargo", "build"].
+        // nohup is not an RTK-routed command → routes to passthrough → correct behavior.
+        let tokens = tokenize("nohup cargo build &");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(
+            suffix, "&",
+            "trailing & after nohup must be stripped as safe suffix"
+        );
+        assert_eq!(core[0].value, "nohup", "first core token must be nohup");
+        assert_eq!(core.len(), 3, "core must be [nohup, cargo, build]");
+        // nohup is not in RTK routing table → passthrough (correct; nohup+RTK = double-wrapping)
+        assert!(
+            !needs_shell(&core),
+            "core with no Shellism must not require shell"
+        );
+    }
+
+    // === COMPOUND SUFFIX TESTS (iterative stripping) ===
+
+    #[test]
+    fn test_split_suffix_compound_redirect_pipe_tail() {
+        // "cargo test 2>&1 | tail -50" — needs iterative stripping:
+        // iteration 1: strip "| tail -50" (3-token pipe+tail)
+        // iteration 2: strip "2>&1" (4-token redirect)
+        // result: core = [cargo, test], suffix = "2>&1 | tail -50"
+        let tokens = tokenize("cargo test 2>&1 | tail -50");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(suffix, "2>&1 | tail -50");
+        assert!(!needs_shell(&core));
+        let cmds = parse_chain(core).expect("core must parse");
+        assert_eq!(cmds[0].binary, "cargo");
+        assert_eq!(cmds[0].args, vec!["test"]);
+    }
+
+    #[test]
+    fn test_split_suffix_compound_devnull_redirect() {
+        // "cmd > /dev/null 2>&1" — both should strip
+        let tokens = tokenize("cmd > /dev/null 2>&1");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(suffix, "> /dev/null 2>&1");
+        assert!(!needs_shell(&core));
+        assert_eq!(core.len(), 1);
+    }
+
+    #[test]
+    fn test_split_suffix_compound_redirect_pipe_tee() {
+        // "cargo build 2>&1 | tee /tmp/log" — both should strip
+        let tokens = tokenize("cargo build 2>&1 | tee /tmp/log");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(suffix, "2>&1 | tee /tmp/log");
+        assert!(!needs_shell(&core));
+    }
+
+    #[test]
+    fn test_split_suffix_triple_compound() {
+        // "cmd >> /tmp/log 2>&1 | tail -5" — three layers
+        let tokens = tokenize("cmd >> /tmp/log 2>&1 | tail -5");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(suffix, ">> /tmp/log 2>&1 | tail -5");
+        assert!(!needs_shell(&core));
+        assert_eq!(core.len(), 1);
+    }
+
+    #[test]
+    fn test_split_suffix_unsafe_pipe_with_redirect_not_stripped() {
+        // "cargo test | grep FAILED 2>&1" — only 2>&1 should strip, not | grep
+        let tokens = tokenize("cargo test | grep FAILED 2>&1");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(suffix, "2>&1");
+        assert!(needs_shell(&core), "core has Pipe -> must need shell");
+    }
+
+    #[test]
+    fn test_split_suffix_devnull_background() {
+        // "cargo build > /dev/null &" — both should strip
+        let tokens = tokenize("cargo build > /dev/null &");
+        let (core, suffix) = split_safe_suffix(tokens);
+        assert_eq!(suffix, "> /dev/null &");
+        assert!(!needs_shell(&core));
+    }
+}
diff --git a/src/cmd/builtins.rs b/src/cmd/builtins.rs
new file mode 100644
index 000000000..8ed265663
--- /dev/null
+++ b/src/cmd/builtins.rs
@@ -0,0 +1,293 @@
+//! Built-in commands that RTK handles natively within a single `rtk run -c` invocation.
+//! Note: state does NOT persist across separate Claude Code hook calls (each is a new process).
+
+use super::predicates::{expand_tilde, get_home};
+use anyhow::{Context, Result};
+
+/// Change directory within the current `rtk run -c` invocation.
+/// Does NOT persist across separate hook invocations.
+pub fn builtin_cd(args: &[String]) -> Result<bool> {
+    let target = args
+        .first()
+        .map(|s| expand_tilde(s))
+        .unwrap_or_else(get_home);
+
+    std::env::set_current_dir(&target)
+        .with_context(|| format!("cd: {}: No such file or directory", target))?;
+
+    Ok(true)
+}
+
+/// Returns true if the name is a valid POSIX shell identifier: [A-Za-z_][A-Za-z0-9_]*
+fn is_valid_env_name(name: &str) -> bool {
+    let mut chars = name.chars();
+    matches!(chars.next(), Some(c) if c.is_ascii_alphabetic() || c == '_')
+        && chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
+}
+
+/// Export environment variable
+pub fn builtin_export(args: &[String]) -> Result<bool> {
+    for arg in args {
+        if let Some((key, value)) = arg.split_once('=') {
+            // Reject invalid identifiers (e.g. "123=x") — fail-open: skip without error.
+            // bash rejects these with "not a valid identifier"; we silently skip to preserve
+            // RTK's fail-open principle (user workflow is never broken).
+            if !is_valid_env_name(key) {
+                continue;
+            }
+            // Handle quoted values: export FOO="bar baz"
+            let clean_value = value
+                .strip_prefix('"')
+                .and_then(|v| v.strip_suffix('"'))
+                .or_else(|| value.strip_prefix('\'').and_then(|v| v.strip_suffix('\'')))
+                .unwrap_or(value);
+            std::env::set_var(key, clean_value);
+        }
+    }
+    Ok(true)
+}
+
+/// Check if a binary is a builtin
+pub fn is_builtin(binary: &str) -> bool {
+    matches!(
+        binary,
+        "cd" | "export" | "pwd" | "echo" | "true" | "false" | ":"
+    )
+}
+
+/// Execute a builtin command
+pub fn execute(binary: &str, args: &[String]) -> Result<bool> {
+    match binary {
+        "cd" => builtin_cd(args),
+        "export" => builtin_export(args),
+        "pwd" => {
+            println!("{}", std::env::current_dir()?.display());
+            Ok(true)
+        }
+        "echo" => {
+            let (print_args, no_newline) = if args.first().map(|s| s.as_str()) == Some("-n") {
+                (&args[1..], true)
+            } else {
+                (args, false)
+            };
+            print!("{}", print_args.join(" "));
+            if !no_newline {
+                println!();
+            }
+            Ok(true)
+        }
+        "true" | ":" => Ok(true),
+        "false" => Ok(false),
+        _ => anyhow::bail!("Unknown builtin: {}", binary),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::env;
+
+    // === CD TESTS ===
+    // Consolidated into one test: cwd is process-global, so parallel tests race.
+
+    #[test]
+    fn test_cd_all_cases() {
+        let original = env::current_dir().unwrap();
+        let home = get_home();
+
+        // 1. cd to existing dir
+        let result = builtin_cd(&["/tmp".to_string()]).unwrap();
+        assert!(result);
+        let new_dir = env::current_dir().unwrap();
+        // On macOS /tmp symlinks to /private/tmp — canonicalize both sides
+        let canon_tmp = std::fs::canonicalize("/tmp").unwrap();
+        let canon_new = std::fs::canonicalize(&new_dir).unwrap();
+        assert_eq!(canon_new, canon_tmp, "cd /tmp should land in /tmp");
+
+        // 2. cd to nonexistent dir
+        let result = builtin_cd(&["/nonexistent/path/xyz".to_string()]);
+        assert!(result.is_err());
+        // cwd unchanged after failed cd
+        assert_eq!(
+            std::fs::canonicalize(env::current_dir().unwrap()).unwrap(),
+            canon_tmp
+        );
+
+        // 3. cd with no args → home
+        let result = builtin_cd(&[]).unwrap();
+        assert!(result);
+        let cwd = env::current_dir().unwrap();
+        let canon_home = std::fs::canonicalize(&home).unwrap();
+        let canon_cwd = std::fs::canonicalize(&cwd).unwrap();
+        assert_eq!(canon_cwd, canon_home, "cd with no args should go home");
+
+        // 4. cd ~ → home
+        let _ = env::set_current_dir("/tmp");
+        let result = builtin_cd(&["~".to_string()]).unwrap();
+        assert!(result);
+        let cwd = std::fs::canonicalize(env::current_dir().unwrap()).unwrap();
+        assert_eq!(cwd, canon_home, "cd ~ should go home");
+
+        // 5. cd ~/nonexistent-subpath — may fail, just verify no panic
+        let _ = builtin_cd(&["~/nonexistent_rtk_test_subpath_xyz".to_string()]);
+
+        // Restore original cwd
+        let _ = env::set_current_dir(&original);
+    }
+
+    // === EXPORT TESTS ===
+
+    #[test]
+    fn test_export_simple() {
+        builtin_export(&["RTK_TEST_SIMPLE=value".to_string()]).unwrap();
+        assert_eq!(env::var("RTK_TEST_SIMPLE").unwrap(), "value");
+        env::remove_var("RTK_TEST_SIMPLE");
+    }
+
+    #[test]
+    fn test_export_with_equals_in_value() {
+        builtin_export(&["RTK_TEST_EQUALS=key=value".to_string()]).unwrap();
+        assert_eq!(env::var("RTK_TEST_EQUALS").unwrap(), "key=value");
+        env::remove_var("RTK_TEST_EQUALS");
+    }
+
+    #[test]
+    fn test_export_quoted_value() {
+        builtin_export(&["RTK_TEST_QUOTED=\"hello world\"".to_string()]).unwrap();
+        assert_eq!(env::var("RTK_TEST_QUOTED").unwrap(), "hello world");
+        env::remove_var("RTK_TEST_QUOTED");
+    }
+
+    #[test]
+    fn test_export_multiple() {
+        builtin_export(&["RTK_TEST_A=1".to_string(), "RTK_TEST_B=2".to_string()]).unwrap();
+        assert_eq!(env::var("RTK_TEST_A").unwrap(), "1");
+        assert_eq!(env::var("RTK_TEST_B").unwrap(), "2");
+        env::remove_var("RTK_TEST_A");
+        env::remove_var("RTK_TEST_B");
+    }
+
+    #[test]
+    fn test_export_no_equals() {
+        // Should be silently ignored (like bash)
+        let result = builtin_export(&["NO_EQUALS_HERE".to_string()]).unwrap();
+        assert!(result);
+    }
+
+    #[test]
+    fn test_export_invalid_identifier_ignored() {
+        // "export 123=x" — identifier starts with digit; must be silently skipped (fail-open).
+        // bash rejects this: "123: not a valid identifier"
+        let result = builtin_export(&["123=x".to_string()]).unwrap();
+        assert!(
+            result,
+            "builtin_export must succeed even with invalid identifier"
+        );
+        assert!(
+            env::var("123").is_err(),
+            "var with numeric-start name must not be set"
+        );
+    }
+
+    #[test]
+    fn test_export_empty_name_ignored() {
+        // "export =x" — empty key before =; must be skipped
+        let result = builtin_export(&["=x".to_string()]).unwrap();
+        assert!(result);
+    }
+
+    #[test]
+    fn test_is_valid_env_name() {
+        assert!(is_valid_env_name("FOO"));
+        assert!(is_valid_env_name("_FOO"));
+        assert!(is_valid_env_name("foo_bar_123"));
+        assert!(!is_valid_env_name("123foo"));
+        assert!(!is_valid_env_name(""));
+        assert!(!is_valid_env_name("foo-bar"));
+        assert!(!is_valid_env_name("foo bar"));
+    }
+
+    // === IS_BUILTIN TESTS ===
+
+    #[test]
+    fn test_is_builtin_cd() {
+        assert!(is_builtin("cd"));
+    }
+
+    #[test]
+    fn test_is_builtin_export() {
+        assert!(is_builtin("export"));
+    }
+
+    #[test]
+    fn test_is_builtin_pwd() {
+        assert!(is_builtin("pwd"));
+    }
+
+    #[test]
+    fn test_is_builtin_echo() {
+        assert!(is_builtin("echo"));
+    }
+
+    #[test]
+    fn test_is_builtin_true() {
+        assert!(is_builtin("true"));
+    }
+
+    #[test]
+    fn test_is_builtin_false() {
+        assert!(is_builtin("false"));
+    }
+
+    #[test]
+    fn test_is_builtin_external() {
+        assert!(!is_builtin("git"));
+        assert!(!is_builtin("ls"));
+        assert!(!is_builtin("cargo"));
+    }
+
+    // === EXECUTE TESTS ===
+
+    #[test]
+    fn test_execute_pwd() {
+        let result = execute("pwd", &[]).unwrap();
+        assert!(result);
+    }
+
+    #[test]
+    fn test_execute_echo() {
+        let result = execute("echo", &["hello".to_string(), "world".to_string()]).unwrap();
+        assert!(result);
+    }
+
+    #[test]
+    fn test_execute_true() {
+        let result = execute("true", &[]).unwrap();
+        assert!(result);
+    }
+
+    #[test]
+    fn test_execute_false() {
+        let result = execute("false", &[]).unwrap();
+        assert!(!result);
+    }
+
+    #[test]
+    fn test_execute_unknown_builtin() {
+        let result = execute("notabuiltin", &[]);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_execute_echo_n_flag() {
+        // echo -n should succeed (prints without newline)
+        let result = execute("echo", &["-n".to_string(), "hello".to_string()]).unwrap();
+        assert!(result);
+    }
+
+    #[test]
+    fn test_execute_echo_empty_args() {
+        let result = execute("echo", &[]).unwrap();
+        assert!(result);
+    }
+}
diff --git a/src/cmd/exec.rs b/src/cmd/exec.rs
new file mode 100644
index 000000000..c2e8a1c73
--- /dev/null
+++ b/src/cmd/exec.rs
@@ -0,0 +1,550 @@
+//! Command executor: runs simple chains natively, delegates complex shell to /bin/sh.
+
+use anyhow::{Context, Result};
+use std::process::Command;
+
+use super::{analysis, builtins, filters, lexer};
+use crate::stream::{FilterMode, LineFilter, StdinMode};
+use crate::tracking;
+
+/// Check if RTK is already active (recursion guard)
+fn is_rtk_active() -> bool {
+    std::env::var("RTK_ACTIVE").is_ok()
+}
+
+/// RAII guard: sets RTK_ACTIVE on creation, removes on drop (even on panic).
+struct RtkActiveGuard;
+
+impl RtkActiveGuard {
+    fn new() -> Self {
+        std::env::set_var("RTK_ACTIVE", "1");
+        RtkActiveGuard
+    }
+}
+
+impl Drop for RtkActiveGuard {
+    fn drop(&mut self) {
+        std::env::remove_var("RTK_ACTIVE");
+    }
+}
+
+/// Execute a raw command string.
+///
+/// Returns the exit code: 0 = success, non-zero = failure.
+pub fn execute(raw: &str, verbose: u8) -> Result<i32> {
+    // Recursion guard
+    if is_rtk_active() {
+        if verbose > 0 {
+            eprintln!("rtk: Recursion detected, passing through");
+        }
+        return run_passthrough(raw, verbose);
+    }
+
+    // Handle empty input
+    if raw.trim().is_empty() {
+        return Ok(0);
+    }
+
+    let _guard = RtkActiveGuard::new();
+    execute_inner(raw, verbose)
+}
+
+fn execute_inner(raw: &str, verbose: u8) -> Result<i32> {
+    // PR 2 adds: crate::config::rules::try_remap() alias expansion
+
+    let tokens = lexer::tokenize(raw);
+
+    // === STEP 1: Decide Native vs Passthrough ===
+    if analysis::needs_shell(&tokens) {
+        // PR 2 adds: safety::check_raw(raw) before passthrough
+        return run_passthrough(raw, verbose);
+    }
+
+    // === STEP 2: Parse into native command chain ===
+    let commands =
+        analysis::parse_chain(tokens).map_err(|e| anyhow::anyhow!("Parse error: {}", e))?;
+
+    // === STEP 3: Execute native chain ===
+    run_native(&commands, verbose)
+}
+
+/// Run commands in native mode (iterate, check safety, filter output)
+fn run_native(commands: &[analysis::NativeCommand], verbose: u8) -> Result<i32> {
+    let mut last_exit: i32 = 0;
+    let mut prev_operator: Option<&str> = None;
+
+    for cmd in commands {
+        // === SHORT-CIRCUIT LOGIC ===
+        // Check if we should run based on PREVIOUS operator and result
+        // The operator stored in cmd is the one AFTER it, so we use prev_operator
+        if !analysis::should_run(prev_operator, last_exit == 0) {
+            // For && with failure or || with success, skip this command
+            prev_operator = cmd.operator.as_deref();
+            continue;
+        }
+
+        // === RECURSION PREVENTION ===
+        // Handle "rtk run" or "rtk" binary specially
+        if cmd.binary == "rtk" && cmd.args.first().map(|s| s.as_str()) == Some("run") {
+            // Flatten: execute the inner command directly
+            // rtk run -c "git status" → args = ["run", "-c", "git status"]
+            let inner = if cmd.args.get(1).map(|s| s.as_str()) == Some("-c") {
+                cmd.args.get(2).cloned().unwrap_or_default()
+            } else {
+                cmd.args.get(1).cloned().unwrap_or_default()
+            };
+            if verbose > 0 {
+                eprintln!("rtk: Flattening nested rtk run");
+            }
+            return execute(&inner, verbose);
+        }
+        // Other rtk commands: spawn as external (they have their own filters)
+
+        // PR 2 adds: safety::check() dispatch block
+
+        // === BUILTINS ===
+        if builtins::is_builtin(&cmd.binary) {
+            let ok = builtins::execute(&cmd.binary, &cmd.args)?;
+            last_exit = if ok { 0 } else { 1 };
+            prev_operator = cmd.operator.as_deref();
+            continue;
+        }
+
+        // === EXTERNAL COMMAND WITH FILTERING ===
+        last_exit = spawn_with_filter(&cmd.binary, &cmd.args, verbose)?;
+        prev_operator = cmd.operator.as_deref();
+    }
+
+    Ok(last_exit)
+}
+
+/// Spawn external command and apply appropriate filter.
+///
+/// Returns the real exit code (0–254) or 128+N for signal-killed processes.
+fn spawn_with_filter(binary: &str, args: &[String], verbose: u8) -> Result<i32> {
+    let timer = tracking::TimedExecution::start();
+
+    if verbose > 1 {
+        eprintln!(
+            "[rtk exec] binary={} interactive={} unstaged={}",
+            binary,
+            super::predicates::is_interactive(),
+            super::predicates::has_unstaged_changes(),
+        );
+    }
+
+    // Try to find the binary in PATH
+    let binary_path = match which::which(binary) {
+        Ok(path) => path,
+        Err(_) => {
+            eprintln!("rtk: {}: command not found", binary);
+            return Ok(127); // standard "command not found" exit code
+        }
+    };
+
+    let mut cmd = Command::new(&binary_path);
+    cmd.args(args);
+
+    let mode = filters::get_filter_mode(binary);
+    let result = crate::stream::run_streaming(&mut cmd, StdinMode::Inherit, mode)
+        .with_context(|| format!("Failed to execute: {}", binary))?;
+
+    // Track usage with raw vs filtered for accurate savings
+    let orig_cmd = if args.is_empty() {
+        binary.to_string()
+    } else {
+        format!("{} {}", binary, args.join(" "))
+    };
+
+    // Check if this command could be routed - if so, track with the routed name
+    // This ensures tracking accuracy even when commands are executed directly
+    let rtk_cmd = if binary == "rtk" {
+        // RTK calling itself - track as "rtk <subcommand>" not "rtk run rtk <subcommand>"
+        if args.is_empty() {
+            "rtk".to_string()
+        } else {
+            format!("rtk {}", args.join(" "))
+        }
+    } else {
+        // Try to route the command to see if it has an RTK equivalent
+        let native_cmd = analysis::NativeCommand {
+            binary: binary.to_string(),
+            args: args.to_vec(),
+            operator: None,
+        };
+        match super::hook::try_route_native_command(&native_cmd, &orig_cmd) {
+            Some(routed) => routed,
+            None => format!("rtk run {}", orig_cmd),
+        }
+    };
+    timer.track(&orig_cmd, &rtk_cmd, &result.raw, &result.filtered);
+
+    Ok(result.exit_code)
+}
+
+/// Run command via system shell (passthrough mode — complex shell expressions).
+///
+/// Returns the real exit code propagated from the shell.
+pub fn run_passthrough(raw: &str, verbose: u8) -> Result<i32> {
+    if verbose > 0 {
+        eprintln!("rtk: Passthrough mode for complex command");
+    }
+
+    let timer = tracking::TimedExecution::start();
+
+    let shell = if cfg!(windows) { "cmd" } else { "sh" };
+    let flag = if cfg!(windows) { "/C" } else { "-c" };
+
+    let mut cmd = Command::new(shell);
+    cmd.arg(flag).arg(raw);
+
+    // Per-line ANSI strip while streaming — no full-buffer wait
+    let filter = LineFilter::new(|l| Some(format!("{}\n", crate::utils::strip_ansi(l))));
+    let result = crate::stream::run_streaming(
+        &mut cmd,
+        StdinMode::Inherit,
+        FilterMode::Streaming(Box::new(filter)),
+    )
+    .context("Failed to execute passthrough")?;
+
+    timer.track(
+        raw,
+        &format!("rtk passthrough {}", raw),
+        &result.raw,
+        &result.filtered,
+    );
+
+    Ok(result.exit_code)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cmd::hook;
+    use crate::cmd::test_helpers::EnvGuard;
+
+    // === RAII GUARD TESTS ===
+
+    #[test]
+    fn test_is_rtk_active_default() {
+        let _env = EnvGuard::new();
+        assert!(!is_rtk_active());
+    }
+
+    #[test]
+    fn test_raii_guard_sets_and_clears() {
+        let _env = EnvGuard::new();
+        {
+            let _guard = RtkActiveGuard::new();
+            assert!(is_rtk_active());
+        }
+        assert!(
+            !is_rtk_active(),
+            "RTK_ACTIVE must be cleared when guard drops"
+        );
+    }
+
+    #[test]
+    fn test_raii_guard_clears_on_panic() {
+        let _env = EnvGuard::new();
+        let result = std::panic::catch_unwind(|| {
+            let _guard = RtkActiveGuard::new();
+            assert!(is_rtk_active());
+            panic!("simulated panic");
+        });
+        assert!(result.is_err());
+        assert!(
+            !is_rtk_active(),
+            "RTK_ACTIVE must be cleared even after panic"
+        );
+    }
+
+    // === EXECUTE TESTS ===
+
+    #[test]
+    fn test_execute_empty() {
+        assert_eq!(execute("", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_whitespace_only() {
+        assert_eq!(execute("   ", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_simple_command() {
+        assert_eq!(execute("echo hello", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_builtin_cd() {
+        let original = std::env::current_dir().unwrap();
+        assert_eq!(execute("cd /tmp", 0).unwrap(), 0);
+        // On macOS, /tmp might be a symlink to /private/tmp
+        let _ = std::env::set_current_dir(&original);
+    }
+
+    #[test]
+    fn test_execute_builtin_pwd() {
+        assert_eq!(execute("pwd", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_builtin_true() {
+        assert_eq!(execute("true", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_builtin_false() {
+        // `false` returns exit code 1
+        assert_ne!(execute("false", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_chain_and_success() {
+        assert_eq!(execute("true && echo success", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_chain_and_failure() {
+        // Chain stops at false; exit code is non-zero
+        assert_ne!(execute("false && echo should_not_run", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_chain_or_success() {
+        // true succeeds; || skips second command; exit code 0
+        assert_eq!(execute("true || echo should_not_run", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_chain_or_failure() {
+        // false fails; || runs fallback (echo), which succeeds
+        assert_eq!(execute("false || echo fallback", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_chain_semicolon() {
+        // Both run; last result (false) is non-zero
+        assert_ne!(execute("true ; false", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_passthrough_for_glob() {
+        assert_eq!(execute("echo *", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_passthrough_for_pipe() {
+        assert_eq!(execute("echo hello | cat", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_quoted_operator() {
+        assert_eq!(execute(r#"echo "hello && world""#, 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_binary_not_found() {
+        // 127 = standard "command not found" exit code
+        assert_eq!(execute("nonexistent_command_xyz_123", 0).unwrap(), 127);
+    }
+
+    #[test]
+    fn test_execute_chain_and_three_commands() {
+        // true && false && true: stops at false → non-zero
+        assert_ne!(execute("true && false && true", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_chain_semicolon_last_wins() {
+        // false ; true: last command succeeds → 0
+        assert_eq!(execute("false ; true", 0).unwrap(), 0);
+    }
+
+    // === INTEGRATION TESTS (moved from edge_cases.rs) ===
+
+    #[test]
+    fn test_chain_mixed_operators() {
+        // false || true && echo works → 0
+        assert_eq!(execute("false || true && echo works", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_passthrough_redirect() {
+        assert_eq!(execute("echo test > /dev/null", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_integration_cd_tilde() {
+        let original = std::env::current_dir().unwrap();
+        assert_eq!(execute("cd ~", 0).unwrap(), 0);
+        let _ = std::env::set_current_dir(&original);
+    }
+
+    #[test]
+    fn test_integration_export() {
+        assert_eq!(execute("export TEST_VAR=value", 0).unwrap(), 0);
+        std::env::remove_var("TEST_VAR");
+    }
+
+    #[test]
+    fn test_integration_env_prefix() {
+        let result = execute("TEST=1 echo hello", 0);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn test_integration_dash_args() {
+        assert_eq!(execute("echo --help -v --version", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_integration_quoted_empty() {
+        assert_eq!(execute(r#"echo """#, 0).unwrap(), 0);
+    }
+
+    // === RECURRENCE PREVENTION TESTS ===
+
+    #[test]
+    fn test_execute_rtk_recursion() {
+        // This should flatten, not infinitely recurse
+        let result = execute("rtk run \"echo hello\"", 0);
+        assert!(result.is_ok());
+    }
+
+    // === EXIT CODE ACCURACY TESTS ===
+
+    #[test]
+    fn test_execute_returns_real_exit_code() {
+        // sh -c "exit 42" must return 42, not 0 or 1
+        let code = execute("sh -c \"exit 42\"", 0).unwrap();
+        assert_eq!(code, 42, "exit code must be propagated exactly");
+    }
+
+    #[test]
+    fn test_execute_success_returns_zero() {
+        assert_eq!(execute("true", 0).unwrap(), 0);
+    }
+
+    #[test]
+    fn test_run_native_and_chain_exit_code() {
+        // "true && false" — last command fails, exit code non-zero
+        assert_ne!(execute("true && false", 0).unwrap(), 0);
+    }
+
+    // === TRACKING LABEL TESTS ===
+    // These tests verify that spawn_with_filter tracks commands with the correct
+    // RTK command name, not always "rtk run <cmd>"
+
+    /// Helper to test what rtk_cmd would be tracked for a given binary/args
+    fn compute_rtk_cmd_label(binary: &str, args: &[&str]) -> String {
+        let native_cmd = analysis::NativeCommand {
+            binary: binary.to_string(),
+            args: args.iter().map(|s| s.to_string()).collect(),
+            operator: None,
+        };
+        let orig_cmd = if args.is_empty() {
+            binary.to_string()
+        } else {
+            format!("{} {}", binary, args.join(" "))
+        };
+
+        if binary == "rtk" {
+            if args.is_empty() {
+                "rtk".to_string()
+            } else {
+                format!("rtk {}", args.join(" "))
+            }
+        } else {
+            match hook::try_route_native_command(&native_cmd, &orig_cmd) {
+                Some(routed) => routed,
+                None => format!("rtk run {}", orig_cmd),
+            }
+        }
+    }
+
+    #[test]
+    fn test_tracking_routed_command_uses_rtk_prefix() {
+        // Commands that have an RTK equivalent should be tracked as "rtk <cmd>"
+        // NOT as "rtk run <cmd>"
+        let label = compute_rtk_cmd_label("ls", &["-F"]);
+        assert!(
+            label == "rtk ls -F",
+            "Expected 'rtk ls -F', got '{}'",
+            label
+        );
+    }
+
+    #[test]
+    fn test_tracking_git_status_uses_rtk_git() {
+        // git status should be tracked as "rtk git status"
+        let label = compute_rtk_cmd_label("git", &["status"]);
+        assert!(
+            label == "rtk git status",
+            "Expected 'rtk git status', got '{}'",
+            label
+        );
+    }
+
+    #[test]
+    fn test_tracking_cargo_test_uses_rtk_cargo() {
+        // cargo test should be tracked as "rtk cargo test"
+        let label = compute_rtk_cmd_label("cargo", &["test"]);
+        assert!(
+            label == "rtk cargo test",
+            "Expected 'rtk cargo test', got '{}'",
+            label
+        );
+    }
+
+    #[test]
+    fn test_tracking_unknown_command_uses_rtk_run() {
+        // Commands without an RTK equivalent should be tracked as "rtk run <cmd>"
+        let label = compute_rtk_cmd_label("python3", &["--version"]);
+        assert!(
+            label == "rtk run python3 --version",
+            "Expected 'rtk run python3 --version', got '{}'",
+            label
+        );
+    }
+
+    #[test]
+    fn test_tracking_rtk_self_reference_no_double_rtk() {
+        // When RTK calls itself, track as "rtk <subcommand>" not "rtk run rtk <subcommand>"
+        let label = compute_rtk_cmd_label("rtk", &["git", "status"]);
+        assert!(
+            label == "rtk git status",
+            "Expected 'rtk git status', got '{}'",
+            label
+        );
+        assert!(
+            !label.contains("rtk run rtk"),
+            "Should NOT contain 'rtk run rtk', got '{}'",
+            label
+        );
+    }
+
+    #[test]
+    fn test_tracking_find_uses_rtk_run() {
+        // NOTE: find is NOT in the ROUTES lookup table, so it falls through to rtk run
+        // This is intentional - find commands often have complex arguments that need shell
+        let label = compute_rtk_cmd_label("find", &[".", "-name", "*.rs"]);
+        assert!(
+            label.starts_with("rtk run"),
+            "Expected 'rtk run ...' (find not in ROUTES), got '{}'",
+            label
+        );
+    }
+
+    #[test]
+    fn test_tracking_grep_uses_rtk_grep() {
+        // grep should be tracked as "rtk grep"
+        let label = compute_rtk_cmd_label("grep", &["-r", "pattern"]);
+        assert!(
+            label.starts_with("rtk grep"),
+            "Expected 'rtk grep ...', got '{}'",
+            label
+        );
+    }
+}
diff --git a/src/cmd/filters.rs b/src/cmd/filters.rs
new file mode 100644
index 000000000..aed969b03
--- /dev/null
+++ b/src/cmd/filters.rs
@@ -0,0 +1,377 @@
+//! Filter Registry — basic token reduction for `rtk run` native execution.
+//!
+//! This module provides **basic filtering (20-40% savings)** for commands
+//! executed through rtk run. It is a **fallback** for commands
+//! without dedicated RTK implementations.
+//!
+//! For **specialized filtering (60-90% savings)**, use dedicated modules:
+//! - `src/git.rs` — git commands (diff, log, status, etc.)
+//! - `src/runner.rs` — test commands (cargo test, pytest, etc.)
+//! - `src/grep_cmd.rs` — code search (grep, ripgrep)
+//! - `src/pnpm_cmd.rs` — package managers
+
+use crate::stream::{FilterMode, LineFilter};
+use crate::utils;
+
+/// Filter cargo output: remove verbose "Compiling" lines
+fn filter_cargo_output(output: &str) -> String {
+    output
+        .lines()
+        .filter(|line| {
+            let line = line.trim();
+            !line.starts_with("Compiling ") || line.contains("error") || line.contains("warning")
+        })
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+
+/// Filter test output: remove passing tests, keep failures
+fn filter_test_output(output: &str) -> String {
+    output
+        .lines()
+        .filter(|line| {
+            let line = line.trim();
+            line.contains("FAILED")
+                || line.contains("error")
+                || line.contains("Error")
+                || line.contains("failed")
+                || line.contains("test result:")
+                || line.starts_with("----")
+        })
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+
+/// Map a binary name to a [`FilterMode`] for use with [`crate::stream::run_streaming`].
+///
+/// Used by `spawn_with_filter` in exec.rs for external commands without dedicated modules.
+pub fn get_filter_mode(binary: &str) -> FilterMode {
+    match binary {
+        // Streaming: per-line ANSI strip + line truncation (low savings, low overhead)
+        "ls" | "find" | "grep" | "rg" | "fd" => {
+            FilterMode::Streaming(Box::new(LineFilter::new(|l| {
+                let stripped = utils::strip_ansi(l);
+                let truncated = if stripped.len() > 120 {
+                    format!("{}...", &stripped[..117])
+                } else {
+                    stripped
+                };
+                Some(format!("{}\n", truncated))
+            })))
+        }
+        // Buffered: cargo, git, and test runners use simple filters here
+        // (dedicated modules like cargo_cmd.rs / go_cmd.rs provide 60-90% savings)
+        "cargo" => FilterMode::Buffered(filter_cargo_output),
+        "pytest" | "jest" | "mocha" | "vitest" | "mypy" | "ruff" | "golangci-lint" => {
+            FilterMode::Buffered(filter_test_output)
+        }
+        // git: ANSI strip per-line (dedicated git.rs handles git subcommands)
+        "git" => FilterMode::Streaming(Box::new(LineFilter::new(|l| {
+            Some(format!("{}\n", utils::strip_ansi(l)))
+        }))),
+        // npm/pnpm: ANSI strip (dedicated pnpm_cmd.rs handles specific subcommands)
+        "npm" | "npx" | "pnpm" => FilterMode::Streaming(Box::new(LineFilter::new(|l| {
+            Some(format!("{}\n", utils::strip_ansi(l)))
+        }))),
+        // Unknown commands: passthrough (no filtering, preserves all output)
+        _ => FilterMode::Passthrough,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // === STRIP_ANSI TESTS (now testing utils::strip_ansi) ===
+
+    #[test]
+    fn test_strip_ansi_no_codes() {
+        assert_eq!(utils::strip_ansi("hello world"), "hello world");
+    }
+
+    #[test]
+    fn test_strip_ansi_color() {
+        assert_eq!(utils::strip_ansi("\x1b[32mgreen\x1b[0m"), "green");
+    }
+
+    #[test]
+    fn test_strip_ansi_bold() {
+        assert_eq!(utils::strip_ansi("\x1b[1mbold\x1b[0m"), "bold");
+    }
+
+    #[test]
+    fn test_strip_ansi_multiple() {
+        assert_eq!(
+            utils::strip_ansi("\x1b[31mred\x1b[0m \x1b[32mgreen\x1b[0m"),
+            "red green"
+        );
+    }
+
+    #[test]
+    fn test_strip_ansi_complex() {
+        assert_eq!(
+            utils::strip_ansi("\x1b[1;31;42mbold red on green\x1b[0m"),
+            "bold red on green"
+        );
+    }
+
+    // === FILTER_CARGO_OUTPUT TESTS ===
+
+    #[test]
+    fn test_filter_cargo_keeps_errors() {
+        let input = "Compiling dep1\nerror: something wrong\nCompiling dep2";
+        let output = filter_cargo_output(input);
+        assert!(output.contains("error"));
+        assert!(!output.contains("Compiling dep1"));
+    }
+
+    #[test]
+    fn test_filter_cargo_keeps_warnings() {
+        let input = "Compiling dep1\nwarning: unused variable\nCompiling dep2";
+        let output = filter_cargo_output(input);
+        assert!(output.contains("warning"));
+    }
+
+    // === FILTER_TEST_OUTPUT TESTS ===
+
+    #[test]
+    fn test_filter_test_keeps_failures() {
+        let input = "test foo ... ok\ntest bar ... FAILED\ntest result: 1 passed; 1 failed";
+        let output = filter_test_output(input);
+        assert!(output.contains("FAILED"));
+        assert!(output.contains("test result:"));
+        assert!(!output.contains("test foo"));
+    }
+
+    // === TRUNCATE_LINES TESTS ===
+
+    /// Truncate output to max lines (test utility)
+    fn truncate_lines(output: &str, max_lines: usize) -> String {
+        let lines: Vec<&str> = output.lines().collect();
+        if lines.len() <= max_lines {
+            output.to_string()
+        } else {
+            let truncated: Vec<&str> = lines.iter().take(max_lines).copied().collect();
+            format!(
+                "{}\n... ({} more lines)",
+                truncated.join("\n"),
+                lines.len() - max_lines
+            )
+        }
+    }
+
+    #[test]
+    fn test_truncate_short() {
+        let input = "line1\nline2\nline3";
+        let output = truncate_lines(input, 10);
+        assert_eq!(output, input);
+    }
+
+    #[test]
+    fn test_truncate_long() {
+        let input = "line1\nline2\nline3\nline4\nline5";
+        let output = truncate_lines(input, 3);
+        assert!(output.contains("line3"));
+        assert!(!output.contains("line4"));
+        assert!(output.contains("2 more lines"));
+    }
+
+    // === GET_FILTER_MODE TESTS ===
+
+    #[test]
+    fn test_get_filter_mode_grep_is_streaming() {
+        assert!(matches!(get_filter_mode("grep"), FilterMode::Streaming(_)));
+    }
+
+    #[test]
+    fn test_get_filter_mode_rg_is_streaming() {
+        assert!(matches!(get_filter_mode("rg"), FilterMode::Streaming(_)));
+    }
+
+    #[test]
+    fn test_get_filter_mode_find_is_streaming() {
+        assert!(matches!(get_filter_mode("find"), FilterMode::Streaming(_)));
+    }
+
+    #[test]
+    fn test_get_filter_mode_fd_is_streaming() {
+        assert!(matches!(get_filter_mode("fd"), FilterMode::Streaming(_)));
+    }
+
+    #[test]
+    fn test_get_filter_mode_ls_is_streaming() {
+        assert!(matches!(get_filter_mode("ls"), FilterMode::Streaming(_)));
+    }
+
+    #[test]
+    fn test_get_filter_mode_cargo_is_buffered() {
+        assert!(matches!(get_filter_mode("cargo"), FilterMode::Buffered(_)));
+    }
+
+    #[test]
+    fn test_get_filter_mode_mypy_is_buffered() {
+        assert!(matches!(get_filter_mode("mypy"), FilterMode::Buffered(_)));
+    }
+
+    #[test]
+    fn test_get_filter_mode_ruff_is_buffered() {
+        assert!(matches!(get_filter_mode("ruff"), FilterMode::Buffered(_)));
+    }
+
+    #[test]
+    fn test_get_filter_mode_golangci_lint_is_buffered() {
+        assert!(matches!(
+            get_filter_mode("golangci-lint"),
+            FilterMode::Buffered(_)
+        ));
+    }
+
+    #[test]
+    fn test_get_filter_mode_npm_is_streaming() {
+        assert!(matches!(get_filter_mode("npm"), FilterMode::Streaming(_)));
+    }
+
+    #[test]
+    fn test_get_filter_mode_pnpm_is_streaming() {
+        assert!(matches!(get_filter_mode("pnpm"), FilterMode::Streaming(_)));
+    }
+
+    #[test]
+    fn test_get_filter_mode_git_is_streaming() {
+        assert!(matches!(get_filter_mode("git"), FilterMode::Streaming(_)));
+    }
+
+    #[test]
+    fn test_get_filter_mode_unknown_is_passthrough() {
+        assert!(matches!(
+            get_filter_mode("unknowncmd"),
+            FilterMode::Passthrough
+        ));
+    }
+
+    #[test]
+    fn test_get_filter_mode_grep_strips_ansi_and_emits() {
+        // Feed a line with ANSI codes; the streaming filter must strip them and emit.
+        let mut mode = get_filter_mode("grep");
+        if let FilterMode::Streaming(ref mut filter) = mode {
+            let result = filter.feed_line("\x1b[32msrc/main.rs:42:fn main\x1b[0m");
+            assert!(result.is_some(), "streaming filter must emit a line");
+            let out = result.unwrap();
+            assert!(
+                out.contains("src/main.rs"),
+                "ANSI stripped, path preserved: {}",
+                out
+            );
+            assert!(
+                !out.contains("\x1b["),
+                "ANSI codes must be stripped: {}",
+                out
+            );
+        } else {
+            panic!("Expected FilterMode::Streaming for 'grep'");
+        }
+    }
+
+    #[test]
+    fn test_get_filter_mode_find_truncates_long_lines() {
+        // Feed a line > 120 chars; the streaming filter must truncate it.
+        let long_line = "a".repeat(200);
+        let mut mode = get_filter_mode("find");
+        if let FilterMode::Streaming(ref mut filter) = mode {
+            let result = filter.feed_line(&long_line);
+            assert!(result.is_some());
+            let out = result.unwrap();
+            // Truncated content should end with "..." and be ≤ 120+3+1 ("\n") chars
+            assert!(
+                out.len() <= 125,
+                "line must be truncated: len={}",
+                out.len()
+            );
+            assert!(out.contains("..."), "truncated line must contain '...'");
+        } else {
+            panic!("Expected FilterMode::Streaming for 'find'");
+        }
+    }
+
+    #[test]
+    fn test_get_filter_mode_rg_short_line_passes_through() {
+        let short_line = "src/foo.rs:10:hello";
+        let mut mode = get_filter_mode("rg");
+        if let FilterMode::Streaming(ref mut filter) = mode {
+            let result = filter.feed_line(short_line);
+            assert!(result.is_some());
+            let out = result.unwrap();
+            assert!(out.contains("src/foo.rs"), "out={}", out);
+        } else {
+            panic!("Expected FilterMode::Streaming for 'rg'");
+        }
+    }
+
+    // === EDGE CASE: go subcommands not handled by go_cmd.rs must passthrough ===
+
+    #[test]
+    fn test_get_filter_mode_go_is_passthrough() {
+        // go mod tidy, go get, go run etc. are not in the registry's Only(&["test","build","vet"])
+        // so they reach spawn_with_filter. They must passthrough, not get test-filtered.
+        assert!(matches!(get_filter_mode("go"), FilterMode::Passthrough));
+    }
+
+    // === EDGE CASE: npx should get ANSI stripping ===
+
+    #[test]
+    fn test_get_filter_mode_npx_is_streaming() {
+        assert!(matches!(get_filter_mode("npx"), FilterMode::Streaming(_)));
+    }
+
+    // === EDGE CASE: npm streaming filter strips ANSI ===
+
+    #[test]
+    fn test_get_filter_mode_npm_strips_ansi() {
+        let mut mode = get_filter_mode("npm");
+        if let FilterMode::Streaming(ref mut filter) = mode {
+            let result = filter.feed_line("\x1b[33mWARN\x1b[0m deprecated package");
+            assert!(result.is_some());
+            let out = result.unwrap();
+            assert!(out.contains("WARN"), "content preserved: {}", out);
+            assert!(!out.contains("\x1b["), "ANSI codes stripped: {}", out);
+        } else {
+            panic!("Expected FilterMode::Streaming for 'npm'");
+        }
+    }
+
+    // === EDGE CASE: filter_test_output with no matching lines returns empty ===
+
+    #[test]
+    fn test_filter_test_output_no_failures_returns_empty() {
+        let input = "test foo ... ok\ntest bar ... ok\ntest baz ... ok";
+        let output = filter_test_output(input);
+        assert!(
+            output.is_empty(),
+            "all-passing tests should produce empty output"
+        );
+    }
+
+    // === EDGE CASE: filter_cargo_output with only Compiling lines ===
+
+    #[test]
+    fn test_filter_cargo_output_only_compiling() {
+        let input = "Compiling dep1\nCompiling dep2\nCompiling dep3";
+        let output = filter_cargo_output(input);
+        assert!(
+            output.is_empty() || output.trim().is_empty(),
+            "pure Compiling output should be filtered out"
+        );
+    }
+
+    // === EDGE CASE: filter_test_output keeps error separator lines ===
+
+    #[test]
+    fn test_filter_test_output_keeps_separator_lines() {
+        let input = "test foo ... ok\n---- test_bar stdout ----\nerror: assertion failed\ntest result: 0 passed; 1 failed";
+        let output = filter_test_output(input);
+        assert!(output.contains("----"), "separator lines preserved");
+        assert!(output.contains("error:"), "error lines preserved");
+        assert!(output.contains("test result:"), "summary preserved");
+        assert!(!output.contains("test foo"), "passing test filtered out");
+    }
+}
diff --git a/src/cmd/hook/claude.rs b/src/cmd/hook/claude.rs
new file mode 100644
index 000000000..092df2ac3
--- /dev/null
+++ b/src/cmd/hook/claude.rs
@@ -0,0 +1,745 @@
+//! Claude Code PreToolUse hook protocol handler.
+//!
+//! Reads JSON from stdin, applies safety checks and rewrites,
+//! outputs JSON to stdout.
+//!
+//! Protocol: https://docs.anthropic.com/en/docs/claude-code/hooks
+//!
+//! ## Exit Code Behavior
+//!
+//! - Exit 0 = success (allow/rewrite) — tool proceeds
+//! - Exit 2 = blocking error (deny) — tool rejected
+//!
+//! ## Claude Code Stderr Rule (CRITICAL)
+//!
+//! **Source:** https://docs.anthropic.com/en/docs/claude-code/hooks
+//!
+//! ```text
+//! CRITICAL: ANY stderr output at exit 0 = hook error = fail-open
+//! ```
+//!
+//! **Implication:**
+//! - Exit 0 + ANY stderr → Claude Code treats hook as FAILED → tool executes anyway (fail-open)
+//! - Exit 2 + stderr → Claude Code treats stderr as the block reason → tool blocked, AI sees reason
+//!
+//! **This module's stderr usage:**
+//! - ✅ Exit 0 paths (NoOpinion, Allow): **NEVER write to stderr**
+//! - ✅ Exit 2 path (Deny): **stderr ONLY** for bug #4669 workaround (see below)
+//!
+//! ## Bug #4669 Workaround (Dual-Path Deny)
+//!
+//! **Issue:** https://github.com/anthropics/claude-code/issues/4669
+//! **Versions:** v1.0.62+ through current (not fixed)
+//! **Problem:** `permissionDecision: "deny"` at exit 0 is IGNORED — tool executes anyway
+//!
+//! **Workaround:**
+//! ```text
+//! stdout: JSON with permissionDecision "deny" (documented main path, but broken)
+//! stderr: plain text reason (fallback path that actually works)
+//! exit code: 2 (triggers Claude Code to read stderr as error)
+//! ```
+//!
+//! This ensures deny works regardless of which path Claude Code processes.
+//!
+//! ## I/O Enforcement (Module-Specific)
+//!
+//! **This restriction applies ONLY to claude_hook.rs and gemini_hook.rs.**
+//! All other RTK modules (main.rs, git.rs, etc.) use `println!`/`eprintln!` normally.
+//!
+//! **Why restricted here:**
+//! - Hook protocol requires JSON-only stdout
+//! - Claude Code's "ANY stderr = hook error" rule (see above)
+//! - Accidental prints corrupt the JSON protocol
+//!
+//! **Enforcement mechanism:**
+//! - `#![deny(clippy::print_stdout, clippy::print_stderr)]` at module level (line 52)
+//! - `run_inner()` returns `HookResponse` enum — pure logic, no I/O
+//! - `run()` is the ONLY function that writes output — single I/O point
+//! - Uses `write!`/`writeln!` which are NOT caught by the clippy lint
+//!
+//! **Pathway:** main.rs → Commands::Hook → claude_hook::run() [DENY ENFORCED HERE]
+//!
+//! Fail-open: Any parse error or unexpected input → exit 0, no output.
+
+// Compile-time I/O enforcement for THIS MODULE ONLY.
+// Other RTK modules (main.rs, git.rs, etc.) use println!/eprintln! normally.
+//
+// Why restrict here:
+// - Claude Code hook protocol requires JSON-only stdout
+// - Claude Code rule: "ANY stderr at exit 0 = hook error = fail-open"
+//   (Source: https://docs.anthropic.com/en/docs/claude-code/hooks)
+// - Accidental prints would corrupt the JSON response
+//
+// Mechanism:
+// - Denies println!/eprintln! at compile-time
+// - Allows write!/writeln! (used only in run() for controlled output)
+// - run_inner() returns HookResponse (no I/O)
+// - run() is the single I/O point
+#![deny(clippy::print_stdout, clippy::print_stderr)]
+
+use super::{
+    check_for_hook, is_hook_disabled, should_passthrough, update_command_in_tool_input,
+    HookResponse, HookResult,
+};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::io::{self, Read, Write};
+
+// --- Wire format structs (field names must match Claude Code spec exactly) ---
+
+#[derive(Deserialize)]
+pub(crate) struct ClaudePayload {
+    tool_input: Option<Value>,
+    // Claude Code also sends: tool_name, session_id, session_cwd,
+    // transcript_path — serde silently ignores unknown fields.
+    // The settings.json matcher already filters to Bash-only events.
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct ClaudeResponse {
+    hook_specific_output: HookOutput,
+}
+
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+struct HookOutput {
+    hook_event_name: &'static str,
+    permission_decision: &'static str,
+    permission_decision_reason: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    updated_input: Option<Value>,
+}
+
+// --- Manifest fallthrough structs ---
+// Minimal subset of rtk-bash-manifest.json needed for reading.
+
+#[derive(Deserialize)]
+struct ManifestFallthroughEntry {
+    fallthrough_command: String,
+}
+
+#[derive(Deserialize)]
+struct ManifestFallthrough {
+    entries: Vec<ManifestFallthroughEntry>,
+}
+
+// --- Guard logic (extracted for testability) ---
+
+/// Extract the command string from a parsed payload.
+/// Returns None if payload has no tool_input or no command field.
+pub(crate) fn extract_command(payload: &ClaudePayload) -> Option<&str> {
+    payload
+        .tool_input
+        .as_ref()?
+        .get("command")?
+        .as_str()
+        .filter(|s| !s.is_empty())
+}
+
+// Guard functions `is_hook_disabled()` and `should_passthrough()` are shared
+// with gemini_hook.rs via hook.rs to avoid duplication (DRY).
+
+/// Build a ClaudeResponse for an allowed/rewritten command.
+pub(crate) fn allow_response(reason: String, updated_input: Option<Value>) -> ClaudeResponse {
+    ClaudeResponse {
+        hook_specific_output: HookOutput {
+            hook_event_name: "PreToolUse",
+            permission_decision: "allow",
+            permission_decision_reason: reason,
+            updated_input,
+        },
+    }
+}
+
+/// Build a ClaudeResponse for a blocked command.
+pub(crate) fn deny_response(reason: String) -> ClaudeResponse {
+    ClaudeResponse {
+        hook_specific_output: HookOutput {
+            hook_event_name: "PreToolUse",
+            permission_decision: "deny",
+            permission_decision_reason: reason,
+            updated_input: None,
+        },
+    }
+}
+
+// --- Entry point ---
+
+/// Run the Claude Code hook handler.
+///
+/// This is the ONLY function that performs I/O (stdout/stderr).
+/// `run_inner()` returns a `HookResponse` enum — pure logic, no I/O.
+/// Combined with `#![deny(clippy::print_stdout, clippy::print_stderr)]`,
+/// this ensures no stray output corrupts the JSON hook protocol.
+///
+/// Fail-open design: malformed input → exit 0, no output.
+/// Claude Code interprets this as "no opinion" and proceeds normally.
+pub fn run() -> anyhow::Result<()> {
+    // Read stdin once here so the raw payload is available for run_manifest_fallthrough.
+    let mut buffer = String::new();
+    io::stdin().read_to_string(&mut buffer)?;
+
+    // Fail-open: wrap entire handler so ANY error → exit 0 (no opinion).
+    let response = match run_inner(&buffer) {
+        Ok(r) => r,
+        Err(_) => HookResponse::NoOpinion, // Fail-open: swallow errors
+    };
+
+    // ┌────────────────────────────────────────────────────────────────┐
+    // │ SINGLE I/O POINT - All stdout/stderr output happens here only │
+    // │                                                                │
+    // │ Why: Claude Code rule "ANY stderr at exit 0 = hook error"     │
+    // │      (Source: hooks_api_reference.md:720-728)                 │
+    // │                                                                │
+    // │ Enforcement: #![deny(...)] at line 52 prevents println!/eprintln! │
+    // │              write!/writeln! are not caught by lint (allowed) │
+    // └────────────────────────────────────────────────────────────────┘
+    match response {
+        HookResponse::NoOpinion => {
+            // No RTK opinion — run ALL manifest handlers on original payload.
+            // All handlers run; first block wins; pass-through if none block.
+            // INVARIANT: payload is always the original unmodified stdin.
+            match run_manifest_handlers(&buffer) {
+                ManifestResult::Blocked { json, stderr_bytes } => {
+                    writeln!(io::stdout(), "{json}")?;
+                    io::stderr().write_all(&stderr_bytes)?;
+                    if stderr_bytes.is_empty() {
+                        writeln!(io::stderr(), "Command blocked by registered handler")?;
+                    }
+                    std::process::exit(2);
+                }
+                ManifestResult::NoBlock => {
+                    // No opinion from any handler — exit 0, no stdout (implicit allow).
+                }
+            }
+        }
+        HookResponse::Allow(rtk_json) => {
+            // RTK wants to rewrite — check manifest handlers as veto gate first.
+            // Uses ORIGINAL payload so handlers see the command Claude requested, not the rewrite.
+            // Deny wins over rewrite (autorun can block grep even if RTK would rewrite it).
+            match run_manifest_handlers(&buffer) {
+                ManifestResult::Blocked {
+                    json: handler_json,
+                    stderr_bytes,
+                } => {
+                    // Deny wins over rewrite. Forward handler's own JSON verbatim.
+                    writeln!(io::stdout(), "{handler_json}")?;
+                    io::stderr().write_all(&stderr_bytes)?;
+                    if stderr_bytes.is_empty() {
+                        let reason = extract_deny_reason(&handler_json).unwrap_or_else(|| {
+                            "Command blocked by registered safety handler".to_owned()
+                        });
+                        writeln!(io::stderr(), "{reason}")?;
+                    }
+                    std::process::exit(2);
+                }
+                ManifestResult::NoBlock => {
+                    // No block — emit RTK's rewrite. Exit 0, JSON to stdout.
+                    writeln!(io::stdout(), "{rtk_json}")?;
+                }
+            }
+        }
+        HookResponse::Deny(json, reason) => {
+            // Exit 2, JSON to stdout, reason to stderr
+            // This is the ONLY path that writes to stderr (valid at exit 2 only)
+            //
+            // Dual-path deny for bug #4669 workaround:
+            // - stdout: JSON with permissionDecision "deny" (documented path, but ignored)
+            // - stderr: plain text reason (actual blocking mechanism via exit 2)
+            // - exit 2: Triggers Claude Code to read stderr and block tool
+            writeln!(io::stdout(), "{json}")?;
+            writeln!(io::stderr(), "{reason}")?;
+            std::process::exit(2);
+        }
+    }
+    Ok(())
+}
+
+/// Inner handler: pure decision logic, no I/O.
+/// Returns `HookResponse` for `run()` to output.
+fn run_inner(buffer: &str) -> anyhow::Result<HookResponse> {
+    let payload: ClaudePayload = match serde_json::from_str(buffer) {
+        Ok(p) => p,
+        Err(_) => return Ok(HookResponse::NoOpinion),
+    };
+
+    let cmd = match extract_command(&payload) {
+        Some(c) => c,
+        None => return Ok(HookResponse::NoOpinion),
+    };
+
+    if is_hook_disabled() || should_passthrough(cmd) {
+        return Ok(HookResponse::NoOpinion);
+    }
+
+    let result = check_for_hook(cmd, "claude");
+
+    match result {
+        HookResult::Rewrite(new_cmd) => {
+            // Preserve all original tool_input fields, only replace "command"
+            // Shared helper (DRY with gemini_hook.rs via hook.rs)
+            let updated = update_command_in_tool_input(payload.tool_input, new_cmd);
+
+            let response = allow_response("RTK safety rewrite applied".into(), Some(updated));
+            let json = serde_json::to_string(&response)?;
+            Ok(HookResponse::Allow(json))
+        }
+        HookResult::Blocked(msg) => {
+            let response = deny_response(msg.clone());
+            let json = serde_json::to_string(&response)?;
+            Ok(HookResponse::Deny(json, msg))
+        }
+    }
+}
+
+/// Path to the RTK bash manifest written by `rtk init`.
+fn manifest_path() -> Option<std::path::PathBuf> {
+    // Check HOME first (Unix), then USERPROFILE (Windows) as fallback.
+    let home = std::env::var("HOME")
+        .or_else(|_| std::env::var("USERPROFILE"))
+        .ok()?;
+    Some(
+        std::path::Path::new(&home)
+            .join(".claude")
+            .join("hooks")
+            .join("rtk-bash-manifest.json"),
+    )
+}
+
+/// Check if JSON string contains a deny decision in either CLI format.
+/// - Claude Code format (current + future when bug #4669 fixed):
+///   `hookSpecificOutput.permissionDecision = "deny"`
+/// - Gemini CLI format (correct today, no bug):
+///   `decision = "deny"` (top-level; deprecated for CC PreToolUse per api docs,
+///   but Gemini sub-handlers legitimately output this format)
+/// Both formats accepted so coordinator works for sub-handlers targeting either CLI.
+fn is_json_deny(json_str: &str) -> bool {
+    let Ok(v) = serde_json::from_str::<Value>(json_str.trim()) else {
+        return false;
+    };
+    let cc_deny = v
+        .get("hookSpecificOutput")
+        .and_then(|o| o.get("permissionDecision"))
+        .and_then(|d| d.as_str())
+        == Some("deny");
+    let gemini_deny = v.get("decision").and_then(|d| d.as_str()) == Some("deny");
+    cc_deny || gemini_deny
+}
+
+/// Extract deny reason from JSON — supports CC and Gemini formats.
+fn extract_deny_reason(json_str: &str) -> Option<String> {
+    let v: Value = serde_json::from_str(json_str.trim()).ok()?;
+    // Claude Code: hookSpecificOutput.permissionDecisionReason
+    if let Some(r) = v
+        .get("hookSpecificOutput")
+        .and_then(|o| o.get("permissionDecisionReason"))
+        .and_then(|r| r.as_str())
+    {
+        return Some(r.to_owned());
+    }
+    // Gemini: reason field
+    v.get("reason").and_then(|r| r.as_str()).map(str::to_owned)
+}
+
+/// Result returned by `run_manifest_handlers()`.
+/// Never emits to stdout/stderr — caller (`run()`) is the sole I/O point.
+enum ManifestResult {
+    /// At least one handler blocked (exit 2 or JSON deny).
+    /// `json`: first blocking handler's stdout (forwarded to Claude Code).
+    /// `stderr_bytes`: buffered stderr from blocked handler — forward only at exit 2.
+    Blocked { json: String, stderr_bytes: Vec<u8> },
+    /// No handler blocked.
+    NoBlock,
+}
+
+/// Load the RTK bash manifest from disk.
+fn load_manifest() -> Option<ManifestFallthrough> {
+    let path = manifest_path()?;
+    if !path.exists() {
+        return None;
+    }
+    let content = std::fs::read_to_string(&path).ok()?;
+    serde_json::from_str(&content).ok()
+}
+
+/// Run ALL manifest handlers from rtk-bash-manifest.json and collect results.
+///
+/// Designed for both NoOpinion (fallthrough) and Allow (veto gate) paths.
+/// ALL handlers run regardless of individual results — no short-circuit.
+///
+/// I/O contract: NEVER writes to stdout or stderr.
+/// Returns `ManifestResult`; caller (`run()`) does all I/O.
+///
+/// INVARIANT: `payload` is always the ORIGINAL unmodified stdin — never a rewrite.
+fn run_manifest_handlers(payload: &str) -> ManifestResult {
+    let manifest = match load_manifest() {
+        Some(m) => m,
+        None => return ManifestResult::NoBlock,
+    };
+
+    let mut block_json: Option<String> = None;
+    let mut block_stderr: Vec<u8> = Vec::new();
+
+    for entry in &manifest.entries {
+        let mut child = match std::process::Command::new("sh")
+            .arg("-c")
+            .arg(&entry.fallthrough_command)
+            .stdin(std::process::Stdio::piped())
+            .stdout(std::process::Stdio::piped()) // Capture: check JSON deny; avoid stdout concat
+            .stderr(std::process::Stdio::piped()) // Capture: buffer, forward only on exit 2
+            .spawn()
+        {
+            Ok(c) => c,
+            Err(_) => continue, // fail-open: handler binary not found
+        };
+
+        // Write payload; track success so we don't propagate a false-positive exit 2
+        // if the write failed and the child received empty/partial stdin.
+        let write_ok = if let Some(mut stdin) = child.stdin.take() {
+            io::Write::write_all(&mut stdin, payload.as_bytes()).is_ok()
+            // stdin dropped here → EOF sent to child
+        } else {
+            false
+        };
+
+        let output = match child.wait_with_output() {
+            Ok(o) => o,
+            Err(_) => continue, // fail-open
+        };
+
+        let exit_code = output.status.code().unwrap_or(0);
+        let stdout_str = String::from_utf8_lossy(&output.stdout);
+        let blocked = (exit_code == 2 && write_ok) || is_json_deny(&stdout_str);
+
+        if blocked && block_json.is_none() {
+            // Record FIRST block; continue running ALL remaining handlers.
+            block_json = Some(stdout_str.into_owned());
+            block_stderr.extend_from_slice(&output.stderr);
+        }
+        // Continue — ALL handlers run regardless of this result.
+    }
+
+    match block_json {
+        Some(json) => ManifestResult::Blocked {
+            json,
+            stderr_bytes: block_stderr,
+        },
+        None => ManifestResult::NoBlock,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cmd::test_helpers::EnvGuard;
+
+    // =========================================================================
+    // CLAUDE CODE WIRE FORMAT CONFORMANCE
+    // https://docs.anthropic.com/en/docs/claude-code/hooks
+    //
+    // These tests verify exact JSON field names per the Claude Code spec.
+    // A wrong field name means Claude Code silently ignores the response.
+    // =========================================================================
+
+    // --- Output: field name conformance ---
+
+    #[test]
+    fn test_output_uses_hook_specific_output() {
+        // Claude expects "hookSpecificOutput" (camelCase), NOT "hook_specific_output"
+        let response = allow_response("test".into(), None);
+        let json = serde_json::to_string(&response).unwrap();
+        let parsed: Value = serde_json::from_str(&json).unwrap();
+
+        assert!(
+            parsed.get("hookSpecificOutput").is_some(),
+            "must have 'hookSpecificOutput' field"
+        );
+        assert!(
+            parsed.get("hook_specific_output").is_none(),
+            "must NOT have snake_case field"
+        );
+    }
+
+    #[test]
+    fn test_output_uses_permission_decision() {
+        // Claude expects "permissionDecision", NOT "decision"
+        let response = allow_response("test".into(), None);
+        let json = serde_json::to_string(&response).unwrap();
+        let parsed: Value = serde_json::from_str(&json).unwrap();
+        let output = &parsed["hookSpecificOutput"];
+
+        assert!(
+            output.get("permissionDecision").is_some(),
+            "must have 'permissionDecision' field"
+        );
+        assert!(
+            output.get("decision").is_none(),
+            "must NOT have Gemini-style 'decision' field"
+        );
+    }
+
+    #[test]
+    fn test_output_uses_permission_decision_reason() {
+        let response = deny_response("blocked".into());
+        let json = serde_json::to_string(&response).unwrap();
+        let parsed: Value = serde_json::from_str(&json).unwrap();
+        let output = &parsed["hookSpecificOutput"];
+
+        assert!(
+            output.get("permissionDecisionReason").is_some(),
+            "must have 'permissionDecisionReason'"
+        );
+    }
+
+    #[test]
+    fn test_output_uses_hook_event_name() {
+        let response = allow_response("test".into(), None);
+        let json = serde_json::to_string(&response).unwrap();
+        let parsed: Value = serde_json::from_str(&json).unwrap();
+
+        assert_eq!(parsed["hookSpecificOutput"]["hookEventName"], "PreToolUse");
+    }
+
+    #[test]
+    fn test_output_uses_updated_input_for_rewrite() {
+        let input = serde_json::json!({"command": "rtk run -c 'git status'"});
+        let response = allow_response("rewrite".into(), Some(input));
+        let json = serde_json::to_string(&response).unwrap();
+        let parsed: Value = serde_json::from_str(&json).unwrap();
+
+        assert!(
+            parsed["hookSpecificOutput"].get("updatedInput").is_some(),
+            "must have 'updatedInput' for rewrites"
+        );
+    }
+
+    #[test]
+    fn test_allow_omits_updated_input_when_none() {
+        let response = allow_response("passthrough".into(), None);
+        let json = serde_json::to_string(&response).unwrap();
+
+        assert!(
+            !json.contains("updatedInput"),
+            "updatedInput must be omitted when None"
+        );
+    }
+
+    #[test]
+    fn test_rewrite_preserves_other_tool_input_fields() {
+        let original = serde_json::json!({
+            "command": "git status",
+            "timeout": 30,
+            "description": "check repo"
+        });
+
+        let mut updated = original.clone();
+        if let Some(obj) = updated.as_object_mut() {
+            obj.insert(
+                "command".into(),
+                Value::String("rtk run -c 'git status'".into()),
+            );
+        }
+
+        assert_eq!(updated["timeout"], 30);
+        assert_eq!(updated["description"], "check repo");
+        assert_eq!(updated["command"], "rtk run -c 'git status'");
+    }
+
+    #[test]
+    fn test_output_decision_values() {
+        let allow = allow_response("test".into(), None);
+        let deny = deny_response("blocked".into());
+
+        let allow_json: Value =
+            serde_json::from_str(&serde_json::to_string(&allow).unwrap()).unwrap();
+        let deny_json: Value =
+            serde_json::from_str(&serde_json::to_string(&deny).unwrap()).unwrap();
+
+        assert_eq!(
+            allow_json["hookSpecificOutput"]["permissionDecision"],
+            "allow"
+        );
+        assert_eq!(
+            deny_json["hookSpecificOutput"]["permissionDecision"],
+            "deny"
+        );
+    }
+
+    // --- Input: payload parsing ---
+
+    #[test]
+    fn test_input_extra_fields_ignored() {
+        // Claude sends session_id, tool_name, transcript_path, etc.
+        let json = r#"{"tool_input": {"command": "ls"}, "tool_name": "Bash", "session_id": "abc-123", "session_cwd": "/tmp", "transcript_path": "/path/to/transcript.jsonl"}"#;
+        let payload: ClaudePayload = serde_json::from_str(json).unwrap();
+        assert_eq!(extract_command(&payload), Some("ls"));
+    }
+
+    #[test]
+    fn test_input_tool_input_is_object() {
+        let json = r#"{"tool_input": {"command": "git status", "timeout": 30}}"#;
+        let payload: ClaudePayload = serde_json::from_str(json).unwrap();
+        let input = payload.tool_input.unwrap();
+        assert_eq!(input["command"].as_str().unwrap(), "git status");
+        assert_eq!(input["timeout"].as_i64().unwrap(), 30);
+    }
+
+    // --- Guard function tests ---
+
+    #[test]
+    fn test_extract_command_basic() {
+        let payload: ClaudePayload =
+            serde_json::from_str(r#"{"tool_input": {"command": "git status"}}"#).unwrap();
+        assert_eq!(extract_command(&payload), Some("git status"));
+    }
+
+    #[test]
+    fn test_extract_command_missing_tool_input() {
+        let payload: ClaudePayload = serde_json::from_str(r#"{}"#).unwrap();
+        assert_eq!(extract_command(&payload), None);
+    }
+
+    #[test]
+    fn test_extract_command_missing_command_field() {
+        let payload: ClaudePayload =
+            serde_json::from_str(r#"{"tool_input": {"cwd": "/tmp"}}"#).unwrap();
+        assert_eq!(extract_command(&payload), None);
+    }
+
+    #[test]
+    fn test_extract_command_empty_string() {
+        let payload: ClaudePayload =
+            serde_json::from_str(r#"{"tool_input": {"command": ""}}"#).unwrap();
+        assert_eq!(extract_command(&payload), None);
+    }
+
+    #[test]
+    fn test_shared_should_passthrough_rtk_prefix() {
+        assert!(should_passthrough("rtk run -c 'ls'"));
+        assert!(should_passthrough("rtk cargo test"));
+        assert!(should_passthrough("/usr/local/bin/rtk run -c 'ls'"));
+    }
+
+    #[test]
+    fn test_shared_should_passthrough_heredoc() {
+        assert!(should_passthrough("cat <<EOF\nhello\nEOF"));
+        assert!(should_passthrough("cat <<'EOF'\nhello\nEOF"));
+    }
+
+    #[test]
+    fn test_shared_should_passthrough_normal_commands() {
+        assert!(!should_passthrough("git status"));
+        assert!(!should_passthrough("ls -la"));
+        assert!(!should_passthrough("echo hello"));
+    }
+
+    #[test]
+    fn test_malformed_json_does_not_panic() {
+        let bad_inputs = ["", "not json", "{}", r#"{"tool_input": 42}"#, "null"];
+        for input in bad_inputs {
+            let _ = serde_json::from_str::<ClaudePayload>(input);
+        }
+    }
+
+    // --- Fail-open behavior ---
+
+    #[test]
+    fn test_run_inner_returns_no_opinion_for_empty_payload() {
+        // "{}" has no tool_input → no command → NoOpinion
+        let payload: ClaudePayload = serde_json::from_str("{}").unwrap();
+        assert_eq!(extract_command(&payload), None);
+    }
+
+    #[test]
+    fn test_shared_is_hook_disabled_hook_enabled_zero() {
+        let _env = EnvGuard::new();
+        std::env::set_var("RTK_HOOK_ENABLED", "0");
+        assert!(is_hook_disabled());
+    }
+
+    #[test]
+    fn test_shared_is_hook_disabled_rtk_active() {
+        let _env = EnvGuard::new();
+        std::env::set_var("RTK_ACTIVE", "1");
+        assert!(is_hook_disabled());
+    }
+
+    // --- Integration: Bug #4669 workaround verification ---
+
+    #[test]
+    fn test_deny_response_includes_reason_for_stderr() {
+        // Bug #4669 workaround: deny must provide plain text reason
+        // that can be output to stderr alongside the JSON stdout.
+        // The msg is cloned for both paths in run_inner().
+        let msg = "RTK: cat is blocked (use rtk read instead)";
+        let response = deny_response(msg.to_string());
+        let json = serde_json::to_string(&response).unwrap();
+        let parsed: Value = serde_json::from_str(&json).unwrap();
+
+        // JSON stdout path
+        assert_eq!(parsed["hookSpecificOutput"]["permissionDecision"], "deny");
+        assert_eq!(
+            parsed["hookSpecificOutput"]["permissionDecisionReason"],
+            msg
+        );
+        // The same msg string is used for stderr in run() via HookResponse::Deny
+    }
+
+    // Note: Integration tests for check_for_hook() safety decisions are in
+    // src/cmd/hook.rs (test_safe_commands_rewrite, test_blocked_commands, etc.)
+    // to avoid duplication. This module focuses on Claude Code wire format.
+
+    // --- is_json_deny() and extract_deny_reason() ---
+
+    #[test]
+    fn test_is_json_deny_claude_code_format() {
+        let json = r#"{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"blocked"}}"#;
+        assert!(is_json_deny(json));
+    }
+
+    #[test]
+    fn test_is_json_deny_gemini_format() {
+        let json = r#"{"decision":"deny","reason":"blocked"}"#;
+        assert!(is_json_deny(json));
+    }
+
+    #[test]
+    fn test_is_json_deny_allow_not_matched() {
+        assert!(!is_json_deny(
+            r#"{"hookSpecificOutput":{"permissionDecision":"allow"}}"#
+        ));
+        assert!(!is_json_deny(r#"{"decision":"allow"}"#));
+        assert!(!is_json_deny(""));
+        assert!(!is_json_deny("not json"));
+    }
+
+    #[test]
+    fn test_extract_deny_reason_cc_format() {
+        let json = r#"{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason":"Use Grep tool"}}"#;
+        assert_eq!(extract_deny_reason(json), Some("Use Grep tool".to_owned()));
+    }
+
+    #[test]
+    fn test_extract_deny_reason_gemini_format() {
+        let json = r#"{"decision":"deny","reason":"command blocked"}"#;
+        assert_eq!(
+            extract_deny_reason(json),
+            Some("command blocked".to_owned())
+        );
+    }
+
+    #[test]
+    fn test_extract_deny_reason_missing() {
+        assert_eq!(extract_deny_reason("{}"), None);
+        assert_eq!(extract_deny_reason("not json"), None);
+    }
+
+    #[test]
+    fn test_load_manifest_returns_none_when_missing() {
+        // When HOME doesn't exist or manifest is absent → None (fail-open)
+        let result = load_manifest(); // may return Some or None depending on environment
+                                      // The key invariant: load_manifest must not panic
+        drop(result);
+    }
+}
diff --git a/src/cmd/hook/mod.rs b/src/cmd/hook/mod.rs
new file mode 100644
index 000000000..d04072333
--- /dev/null
+++ b/src/cmd/hook/mod.rs
@@ -0,0 +1,2028 @@
+//! Hook protocol for Claude Code and Gemini support.
+//!
+//! This module provides **shared decision logic** for both Claude Code and Gemini CLI hooks.
+//! Protocol-specific I/O handling lives in `hook/claude.rs` and `hook/gemini.rs`.
+//!
+//! ## Architecture: Separation of Concerns
+//!
+//! ```text
+//! main.rs (CAN use println! - normal RTK behavior)
+//!    ↓
+//! Commands::Hook match
+//!    ├─→ HookCommands::Check → hook::check_for_hook() (THIS MODULE - CAN use println!)
+//!    ├─→ HookCommands::Claude → hook::claude::run() [DENY ENFORCED - see hook/claude.rs]
+//!    └─→ HookCommands::Gemini → hook::gemini::run() [DENY ENFORCED - see hook/gemini.rs]
+//! ```
+//!
+//! **I/O Policy Scope:**
+//! - **This module (hook/mod.rs)**: CAN use `println!`/`eprintln!` (used by `rtk hook check` text protocol)
+//! - **main.rs and all command modules**: CAN use `println!`/`eprintln!` (normal RTK behavior)
+//! - **hook/claude.rs, hook/gemini.rs ONLY**: CANNOT use `println!`/`eprintln!` (JSON protocols)
+//!
+//! The `#![deny(clippy::print_stdout, clippy::print_stderr)]` attribute is applied
+//! at the **module boundary** (earliest possible stage) — when control enters
+//! `claude::run()` or `gemini::run()`, the deny is enforced.
+//!
+//! ## Protocol Differences
+//!
+//! **Claude Code** (`rtk hook check` text protocol):
+//! - Success: rewritten command on stdout, exit 0
+//! - Blocked: error message on stderr, exit 2 (blocking error)
+//! - Other exit codes: non-blocking errors
+//!
+//! **Claude Code** (JSON protocol via `hook/claude.rs`):
+//! - See `claude` module documentation
+//!
+//! **Gemini CLI** (JSON protocol via `hook/gemini.rs`):
+//! - See `gemini` module documentation
+
+// LLM protocol adapters
+pub(crate) mod claude;
+
+use super::{analysis, lexer};
+// PR 2 adds: use super::safety;
+
+/// Hook check result
+#[derive(Debug, Clone)]
+pub enum HookResult {
+    /// Command is safe, rewrite to this
+    Rewrite(String),
+    /// Command is blocked with this message
+    Blocked(String),
+}
+
+/// Maximum rewrite depth to prevent infinite recursion from cyclic safety rules.
+const MAX_REWRITE_DEPTH: usize = 3;
+
+/// Check a command for the hook protocol.
+/// Returns the rewritten command or an error message.
+///
+/// The `_agent` parameter is reserved for future per-agent behavior.
+pub fn check_for_hook(raw: &str, _agent: &str) -> HookResult {
+    check_for_hook_inner(raw, 0)
+}
+
+fn check_for_hook_inner(raw: &str, depth: usize) -> HookResult {
+    if depth >= MAX_REWRITE_DEPTH {
+        return HookResult::Blocked("Rewrite loop detected (max depth exceeded)".to_string());
+    }
+    if raw.trim().is_empty() {
+        return HookResult::Rewrite(raw.to_string());
+    }
+    // PR 2 adds: crate::config::rules::try_remap() alias expansion
+    // PR 2 adds: safety::check_raw() and safety::check() dispatch
+
+    let tokens = lexer::tokenize(raw);
+
+    // === SUFFIX-AWARE ROUTING ===
+    // Strip known safe redirect/pipe suffixes (2>&1, | tee, | head, etc.) from the
+    // end of the command so the core can be routed through an RTK filter.  The suffix
+    // is appended verbatim to the rewritten command; the shell applies it to rtk's output.
+    //
+    // Example: "cargo test 2>&1" → strip suffix → core "cargo test" → "rtk cargo test 2>&1"
+    let (core_tokens, suffix) = analysis::split_safe_suffix(tokens);
+
+    if analysis::needs_shell(&core_tokens) {
+        // Core needs shell even after suffix stripping — full passthrough.
+        // (When suffix is empty, core_tokens == original tokens so this is unchanged.)
+        return HookResult::Rewrite(format!("rtk run -c '{}'", escape_quotes(raw)));
+    }
+
+    match analysis::parse_chain(core_tokens) {
+        Ok(commands) => {
+            // Single command: route to optimized RTK subcommand.
+            // Chained commands (&&, ||, ;): wrap entire chain in rtk run -c.
+            if commands.len() == 1 {
+                let routed = if suffix.is_empty() {
+                    // No suffix stripped: use original raw to preserve quoting
+                    try_route_native_command(&commands[0], raw)
+                } else {
+                    // Suffix was stripped: reconstruct core_raw from parsed command.
+                    // Quoting is simplified (join with spaces) but acceptable for the
+                    // common cases where suffix-bearing commands use simple args.
+                    let core_raw = if commands[0].args.is_empty() {
+                        commands[0].binary.clone()
+                    } else {
+                        format!("{} {}", commands[0].binary, commands[0].args.join(" "))
+                    };
+                    try_route_native_command(&commands[0], &core_raw)
+                };
+
+                match routed {
+                    Some(rtk_cmd) => {
+                        if suffix.is_empty() {
+                            HookResult::Rewrite(rtk_cmd)
+                        } else {
+                            HookResult::Rewrite(format!("{} {}", rtk_cmd, suffix))
+                        }
+                    }
+                    // Unknown command — pass through unchanged (no wrapping)
+                    None => HookResult::Rewrite(raw.to_string()),
+                }
+            } else {
+                // Multi-command chain (&&, ||, ;): wrap in shell but substitute each
+                // known command with its RTK equivalent for maximum token savings.
+                //
+                // Example: "cargo test && git log" →
+                //   rtk run -c 'rtk cargo test && rtk git log'
+                //
+                // Unknown commands pass through unchanged — no nested rtk run -c.
+                let substituted = reconstruct_with_rtk(&commands);
+                let inner = if suffix.is_empty() {
+                    substituted
+                } else {
+                    format!("{} {}", substituted, suffix)
+                };
+                HookResult::Rewrite(format!("rtk run -c '{}'", escape_quotes(&inner)))
+            }
+        }
+        Err(_) => HookResult::Rewrite(raw.to_string()),
+    }
+}
+
+// --- Shared guard logic (used by both claude_hook.rs and gemini_hook.rs) ---
+
+/// Check if hook processing is disabled by environment.
+///
+/// Returns true if:
+/// - `RTK_HOOK_ENABLED=0` (master toggle off)
+/// - `RTK_ACTIVE` is set (recursion prevention — rtk sets this when running commands)
+pub fn is_hook_disabled() -> bool {
+    std::env::var("RTK_HOOK_ENABLED").as_deref() == Ok("0") || std::env::var("RTK_ACTIVE").is_ok()
+}
+
+/// Check if this command should bypass hook processing entirely.
+///
+/// Returns true for commands that should not be rewritten:
+/// - Already routed through rtk (`rtk ...` or `/path/to/rtk ...`)
+/// - Contains heredoc (`<<`) which needs raw shell processing
+pub fn should_passthrough(cmd: &str) -> bool {
+    // Already rtk or heredoc → no-op
+    if cmd.starts_with("rtk ") || cmd.contains("/rtk ") || cmd.contains("<<") {
+        return true;
+    }
+    // #196: gh --json/--jq/--template produces structured output that rtk gh
+    // would corrupt. Pass through unchanged so callers get raw JSON.
+    // Mirrors the guard in registry::rewrite_segment.
+    if (cmd.starts_with("gh ") || cmd.contains(" gh "))
+        && (cmd.contains("--json") || cmd.contains("--jq") || cmd.contains("--template"))
+    {
+        return true;
+    }
+    false
+}
+
+/// Replace the command field in a tool_input object, preserving other fields.
+///
+/// Used by both claude_hook.rs and gemini_hook.rs when rewriting commands.
+/// If tool_input is None or not an object, creates a new object with just the command.
+///
+/// # Arguments
+/// * `tool_input` - The original tool_input from the hook payload (may be None)
+/// * `new_cmd` - The rewritten command string to replace with
+///
+/// # Returns
+/// A Value with the command field updated, all other fields preserved.
+pub fn update_command_in_tool_input(
+    tool_input: Option<serde_json::Value>,
+    new_cmd: String,
+) -> serde_json::Value {
+    use serde_json::Value;
+    let mut updated = tool_input.unwrap_or_else(|| Value::Object(Default::default()));
+    if let Some(obj) = updated.as_object_mut() {
+        obj.insert("command".into(), Value::String(new_cmd));
+    }
+    updated
+}
+
+/// Hook output for protocol handlers (claude_hook.rs, gemini_hook.rs).
+///
+/// This enum separates decision logic from I/O: `run_inner()` returns a
+/// `HookResponse`, and `run()` is the single place that writes to stdout/stderr.
+/// Combined with `#[deny(clippy::print_stdout, clippy::print_stderr)]` on the
+/// hook modules, this prevents any stray output from corrupting the JSON protocol.
+#[derive(Debug, Clone, PartialEq)]
+pub enum HookResponse {
+    /// No opinion — exit 0, no output. Host proceeds normally.
+    NoOpinion,
+    /// Allow/rewrite — exit 0, JSON to stdout.
+    Allow(String),
+    /// Deny — exit 2, JSON to stdout + reason to stderr.
+    /// Fields: (stdout_json, stderr_reason)
+    Deny(String, String),
+}
+
+/// Commands whose RTK output format matches their raw output, making them
+/// safe as the left side of any pipe.
+///
+/// Commands whose RTK output format matches raw output (format-preserving).
+///
+/// For a command to be format-preserving, RTK must emit the same logical
+/// lines as the underlying tool — just possibly with ANSI codes stripped.
+/// These can be substituted on the left of a pipe without breaking the
+/// right-side consumer.
+///
+/// # Contrast with format-changing commands
+/// `cargo test`, `git log`, `pytest`, `go test` etc. heavily compress output.
+/// They must **not** appear here — substituting them as a pipe-left would
+/// break right-side semantic sinks (`grep`, `jq`, `awk`, `patch`, `xargs`).
+#[cfg(test)]
+const FORMAT_PRESERVING: &[&str] = &["tail", "echo", "cat", "find", "fd"];
+
+/// Right-side commands that accept any input format (transparent sinks).
+///
+/// These commands copy, truncate, or tee their stdin without interpreting its
+/// structure, so RTK's compressed output is always compatible with them.
+/// Already handled at the routing level by `split_safe_suffix` — listed here
+/// for classification documentation and future pipe-left substitution logic.
+#[cfg(test)]
+const TRANSPARENT_SINKS: &[&str] = &["tee", "head", "tail", "cat"];
+
+/// Escape single quotes for shell
+fn escape_quotes(s: &str) -> String {
+    s.replace("'", "'\\''")
+}
+
+/// Returns true if `s` looks like a shell env-var assignment: `IDENT=VALUE`.
+///
+/// Accepts: `FOO=bar`, `FOO=`, `_FOO=123`, `FOO_BAR=baz`
+/// Rejects: `=value`, `123=abc`, plain args, flag args like `--foo=bar`
+fn is_env_assign(s: &str) -> bool {
+    if let Some(eq_pos) = s.find('=') {
+        let key = &s[..eq_pos];
+        !key.is_empty()
+            && key
+                .chars()
+                .next()
+                .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
+            && key.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
+    } else {
+        false
+    }
+}
+
+/// Replace the first occurrence of `old_prefix` in `raw` with `new_prefix`.
+///
+/// Preserves everything after the prefix (including original quoting).
+/// Falls back to `rtk run -c '<raw>'` if prefix not found (safe degradation).
+///
+/// # Examples
+/// - `replace_first_word("grep -r p src/", "grep", "rtk grep")` → `"rtk grep -r p src/"`
+/// - `replace_first_word("rg pattern", "rg", "rtk grep")` → `"rtk grep pattern"`
+fn replace_first_word(raw: &str, old_prefix: &str, new_prefix: &str) -> String {
+    raw.strip_prefix(old_prefix)
+        .map(|rest| format!("{new_prefix}{rest}"))
+        .unwrap_or_else(|| format!("rtk run -c '{}'", escape_quotes(raw)))
+}
+
+/// Route pnpm subcommands to RTK equivalents.
+///
+/// Uses `cmd.args` (parsed, quote-stripped) for routing decisions.
+/// Uses `raw` or reconstructed args for output to preserve original quoting.
+fn route_pnpm(cmd: &analysis::NativeCommand, raw: &str) -> String {
+    let sub = cmd.args.first().map(String::as_str).unwrap_or("");
+    match sub {
+        "list" | "ls" | "outdated" | "install" => format!("rtk {raw}"),
+
+        // pnpm vitest [run] [flags] → rtk vitest run [flags]
+        // Shell script sed bug: 's/^(pnpm )?vitest/rtk vitest run/' on
+        // "pnpm vitest run --coverage" produces "rtk vitest run run --coverage".
+        // Binary hook corrects this by stripping the leading "run" from parsed args.
+        "vitest" => {
+            let after_vitest: Vec<&str> = cmd.args[1..]
+                .iter()
+                .map(String::as_str)
+                .skip_while(|&a| a == "run")
+                .collect();
+            if after_vitest.is_empty() {
+                "rtk vitest run".to_string()
+            } else {
+                format!("rtk vitest run {}", after_vitest.join(" "))
+            }
+        }
+
+        // pnpm test [flags] → rtk vitest run [flags]
+        "test" => {
+            let after_test: Vec<&str> = cmd.args[1..].iter().map(String::as_str).collect();
+            if after_test.is_empty() {
+                "rtk vitest run".to_string()
+            } else {
+                format!("rtk vitest run {}", after_test.join(" "))
+            }
+        }
+
+        "tsc" => replace_first_word(raw, "pnpm tsc", "rtk tsc"),
+        "lint" => replace_first_word(raw, "pnpm lint", "rtk lint"),
+        "eslint" => replace_first_word(raw, "pnpm eslint", "rtk lint"),
+        "playwright" => replace_first_word(raw, "pnpm playwright", "rtk playwright"),
+
+        _ => format!("rtk run -c '{}'", escape_quotes(raw)),
+    }
+}
+
+/// Route npx subcommands to RTK equivalents.
+fn route_npx(cmd: &analysis::NativeCommand, raw: &str) -> String {
+    let sub = cmd.args.first().map(String::as_str).unwrap_or("");
+    match sub {
+        "tsc" | "typescript" => replace_first_word(raw, &format!("npx {sub}"), "rtk tsc"),
+        "eslint" => replace_first_word(raw, "npx eslint", "rtk lint"),
+        "prettier" => replace_first_word(raw, "npx prettier", "rtk prettier"),
+        "playwright" => replace_first_word(raw, "npx playwright", "rtk playwright"),
+        "prisma" => replace_first_word(raw, "npx prisma", "rtk prisma"),
+
+        // npx vitest [run] [flags] → rtk vitest run [flags]
+        // Mirrors pnpm vitest handling: strip double-"run" if user writes "npx vitest run".
+        "vitest" => {
+            let after_vitest: Vec<&str> = cmd.args[1..]
+                .iter()
+                .map(String::as_str)
+                .skip_while(|&a| a == "run")
+                .collect();
+            if after_vitest.is_empty() {
+                "rtk vitest run".to_string()
+            } else {
+                format!("rtk vitest run {}", after_vitest.join(" "))
+            }
+        }
+
+        _ => format!("rtk run -c '{}'", escape_quotes(raw)),
+    }
+}
+
+/// Route a single parsed native command to its optimized RTK subcommand.
+///
+/// ## Design
+/// - Uses `cmd.binary`/`cmd.args` (lexer→parse_chain output) for routing DECISIONS.
+/// - Uses `raw: &str` with `replace_first_word` for string REPLACEMENT (preserves quoting).
+/// - `format!("rtk {raw}")` works when the binary name equals the RTK subcommand.
+/// - `replace_first_word` handles renames: `rg → rtk grep`, `cat → rtk read`.
+///
+/// ## Fallback
+/// Unknown binaries or unrecognized subcommands → `rtk run -c '<raw>'` (safe passthrough).
+///
+/// ## Mirrors
+/// `~/.claude/hooks/rtk-rewrite.sh` routing table. Corrects the shell script's
+/// `vitest run` double-"run" bug by using parsed args rather than regex substitution.
+///
+/// ## Safety interaction
+/// `safety::check` runs BEFORE this function. Blocked commands (cat, head, sed)
+/// never reach here. The `cat` arm is defensive for when `RTK_BLOCK_TOKEN_WASTE=0`.
+
+/// Subcommand-aware routing table for the binary hook.
+/// Returns (rtk_cmd_full, prefix_to_replace) when a command should be routed to an RTK subcommand.
+/// Conservative whitelist — excludes commands that are better handled by `rtk run -c`.
+fn hook_lookup<'a>(binary: &'a str, sub: &str) -> Option<(&'static str, &'a str)> {
+    // Extract basename for full-path binaries: /opt/homebrew/bin/gh → gh
+    let base = binary.rsplit('/').next().unwrap_or(binary);
+    // Match on basename but return original `binary` as prefix for replace_first_word
+    match base {
+        "git" => {
+            // Only well-supported subcommands; others (checkout, rebase, cherry-pick) → rtk run
+            match sub {
+                "status" | "log" | "diff" | "show" | "add" | "commit" | "push" | "pull"
+                | "fetch" | "stash" | "branch" | "worktree" => Some(("rtk git", binary)),
+                _ => None,
+            }
+        }
+        "gh" => match sub {
+            "pr" | "issue" | "run" => Some(("rtk gh", binary)),
+            _ => None,
+        },
+        "cargo" => match sub {
+            "test" | "build" | "clippy" | "check" | "install" | "fmt" => {
+                Some(("rtk cargo", binary))
+            }
+            _ => None,
+        },
+        "docker" => match sub {
+            "ps" | "images" | "logs" => Some(("rtk docker", binary)),
+            _ => None,
+        },
+        "kubectl" => match sub {
+            "get" | "logs" => Some(("rtk kubectl", binary)),
+            _ => None,
+        },
+        "go" => match sub {
+            "test" | "build" | "vet" => Some(("rtk go", binary)),
+            _ => None,
+        },
+        "ruff" => match sub {
+            "check" | "format" => Some(("rtk ruff", binary)),
+            _ => None,
+        },
+        "pip" | "pip3" => match sub {
+            "list" | "outdated" | "install" | "show" => Some(("rtk pip", binary)),
+            _ => None,
+        },
+        // Rename routes: binary → rtk subcommand (different name)
+        "grep" => Some(("rtk grep", binary)),
+        "rg" => Some(("rtk grep", binary)),
+        "ls" => Some(("rtk ls", binary)),
+        "eslint" => Some(("rtk lint", binary)),
+        "biome" => Some(("rtk lint", binary)),
+        "tsc" => Some(("rtk tsc", binary)),
+        "prettier" => Some(("rtk prettier", binary)),
+        "golangci-lint" | "golangci" => Some(("rtk golangci-lint", binary)),
+        "mypy" => Some(("rtk mypy", binary)),
+        // Any-subcommand direct routes
+        "playwright" => Some(("rtk playwright", binary)),
+        "prisma" => Some(("rtk prisma", binary)),
+        "curl" => Some(("rtk curl", binary)),
+        "pytest" => Some(("rtk pytest", binary)),
+        "wc" => Some(("rtk wc", binary)),
+        // Graphite CLI — all subcommands route through RTK for token optimization
+        "gt" => Some(("rtk gt", binary)),
+        "wget" | "diff" | "tree" | "find" => None, // passthrough: builtins_not_blocked
+        _ => None,
+    }
+}
+
+/// Returns true if the token is a shell prefix builtin that modifies the
+/// execution of the following command (e.g. `noglob`, `command`, `nocorrect`).
+/// These builtins are NOT standalone executables — they must stay in shell context.
+fn is_shell_prefix_builtin(token: &str) -> bool {
+    matches!(
+        token,
+        "noglob" | "command" | "builtin" | "exec" | "nocorrect"
+    )
+}
+
+pub(crate) fn route_native_command(cmd: &analysis::NativeCommand, raw: &str) -> String {
+    // === SHELL PREFIX BUILTIN STRIPPING ===
+    // When the "binary" is a shell prefix builtin (noglob, command, etc.),
+    // strip it, route the real command, and re-prepend the prefix.
+    // These builtins modify execution context — they are NOT executables
+    // and cannot be wrapped in `rtk run -c`.
+    //
+    // Example: "noglob gh release create v0.3.0-rc1 --title ..."
+    //   → prefix="noglob", real_binary="gh", args=["release","create",...]
+    //   → route "gh release create ..." → "rtk gh release create ..."
+    //   → result: "noglob rtk gh release create v0.3.0-rc1 --title ..."
+    if is_shell_prefix_builtin(&cmd.binary) {
+        if let Some(real_binary) = cmd.args.first() {
+            let prefix = &cmd.binary;
+            let real_args = cmd.args[1..].to_vec();
+            let real_cmd = analysis::NativeCommand {
+                binary: real_binary.clone(),
+                args: real_args,
+                operator: cmd.operator.clone(),
+            };
+            let core_raw = raw
+                .strip_prefix(prefix)
+                .map(|s| s.trim_start())
+                .unwrap_or(raw);
+            return match try_route_native_command(&real_cmd, core_raw) {
+                Some(routed) => format!("{} {}", prefix, routed),
+                None => raw.to_string(), // Unknown cmd — pass through with prefix intact
+            };
+        }
+        // Bare prefix with no following command — pass through unchanged
+        return raw.to_string();
+    }
+
+    // === ENV PREFIX STRIPPING ===
+    // When the "binary" is actually a VAR=val env assignment (e.g. "GIT_PAGER=cat"),
+    // collect all leading env assigns, find the real binary in args, route it, and
+    // prepend the env vars so the shell sets them for the rtk subprocess.
+    //
+    // Example: "GIT_PAGER=cat git status"
+    //   → env_prefix="GIT_PAGER=cat", real_binary="git", args=["status"]
+    //   → route "git status" → "rtk git status"
+    //   → result: "GIT_PAGER=cat rtk git status"
+    if is_env_assign(&cmd.binary) {
+        let mut env_parts: Vec<&str> = vec![cmd.binary.as_str()];
+        let mut arg_idx = 0;
+        while arg_idx < cmd.args.len() && is_env_assign(&cmd.args[arg_idx]) {
+            env_parts.push(&cmd.args[arg_idx]);
+            arg_idx += 1;
+        }
+        if arg_idx < cmd.args.len() {
+            let env_prefix_str = env_parts.join(" ");
+            // Strip env prefix from raw to get core_raw, preserving original quoting.
+            let core_raw = raw
+                .strip_prefix(&env_prefix_str)
+                .map(|s| s.trim_start())
+                .unwrap_or_else(|| {
+                    // Fallback: count the env prefix length and skip past it
+                    let skip = env_prefix_str.len();
+                    if skip < raw.len() {
+                        raw[skip..].trim_start()
+                    } else {
+                        raw
+                    }
+                });
+            let real_binary = cmd.args[arg_idx].clone();
+            let real_args = cmd.args[arg_idx + 1..].to_vec();
+            let real_cmd = analysis::NativeCommand {
+                binary: real_binary,
+                args: real_args,
+                operator: cmd.operator.clone(),
+            };
+            return match try_route_native_command(&real_cmd, core_raw) {
+                Some(routed) => format!("{} {}", env_prefix_str, routed),
+                None => raw.to_string(), // Unknown cmd — pass through with env prefix intact
+            };
+        }
+        // All tokens are env assigns (no real command) — fall through to passthrough
+    }
+
+    let sub = cmd.args.first().map(String::as_str).unwrap_or("");
+    let sub2 = cmd.args.get(1).map(String::as_str).unwrap_or("");
+
+    // 1. Static routing table: subcommand-aware whitelist (hook_lookup).
+    //    More conservative than classify_command (discovery) — only routes
+    //    commands/subcommands that RTK optimizes well.
+    if let Some((rtk_full, prefix)) = hook_lookup(&cmd.binary, sub) {
+        return replace_first_word(raw, prefix, rtk_full);
+    }
+
+    // 2. Complex cases that require Rust logic and cannot be expressed as table entries.
+
+    // cat: blocked by safety rules before reaching here; defensive for RTK_BLOCK_TOKEN_WASTE=0
+    if cmd.binary == "cat" {
+        return replace_first_word(raw, "cat", "rtk read");
+    }
+
+    match cmd.binary.as_str() {
+        // vitest: bare invocation → rtk vitest run (not rtk vitest)
+        "vitest" if sub.is_empty() => "rtk vitest run".to_string(),
+        "vitest" => format!("rtk {raw}"),
+
+        // uv pip: two-word prefix replacement
+        "uv" if sub == "pip" && matches!(sub2, "list" | "outdated" | "install" | "show") => {
+            replace_first_word(raw, "uv pip", "rtk pip")
+        }
+
+        // python/python3 -m pytest: two-arg prefix replacement
+        "python" | "python3" if sub == "-m" && sub2 == "pytest" => {
+            let prefix = format!("{} -m pytest", cmd.binary);
+            replace_first_word(raw, &prefix, "rtk pytest")
+        }
+
+        // python/python3 -m mypy: two-arg prefix replacement
+        "python" | "python3" if sub == "-m" && sub2 == "mypy" => {
+            let prefix = format!("{} -m mypy", cmd.binary);
+            replace_first_word(raw, &prefix, "rtk mypy")
+        }
+
+        // pnpm / npx: delegated to helpers (complex sub-routing)
+        "pnpm" => route_pnpm(cmd, raw),
+        "npx" => route_npx(cmd, raw),
+
+        // Fallback: unknown binary or unrecognized subcommand
+        _ => format!("rtk run -c '{}'", escape_quotes(raw)),
+    }
+}
+/// Try to route a single command to its optimised RTK subcommand.
+///
+/// Returns `Some(rtk_cmd)` when the command is natively routable (direct or renamed).
+/// Returns `None` when the command would fall back to `rtk run -c '...'` passthrough —
+/// the caller should keep the original `raw` string unchanged in that case.
+///
+/// This avoids embedding nested `rtk run -c` calls inside an outer shell string,
+/// which would require double-escaping and never improves token savings.
+pub(crate) fn try_route_native_command(cmd: &analysis::NativeCommand, raw: &str) -> Option<String> {
+    let routed = route_native_command(cmd, raw);
+    if routed.starts_with("rtk run -c") {
+        None // passthrough — keep original
+    } else {
+        Some(routed)
+    }
+}
+
+/// Substitute RTK commands within a multi-command chain string.
+///
+/// Iterates each command in the parsed chain.  Known commands (those with an RTK
+/// subcommand equivalent) are replaced with their `rtk <cmd>` form.  Unknown commands
+/// are kept verbatim so the shell can handle them.  Operators (`&&`, `||`, `;`) are
+/// preserved between commands.
+///
+/// # Why this is safe
+/// Only `&&`/`||`/`;` chains reach this function (pipe characters trigger `needs_shell`
+/// before `parse_chain`, so pipes never appear here).  Each command's stdout is
+/// independent — no cross-command parsing is affected by RTK's output format changes.
+///
+/// # Example
+/// ```text
+/// "cargo test && git log $BRANCH"
+///   cmd[0]: binary="cargo" args=["test"] op=Some("&&")  → "rtk cargo test"
+///   cmd[1]: binary="git"   args=["log","$BRANCH"] op=None → "rtk git log $BRANCH"
+///   result: "rtk cargo test && rtk git log $BRANCH"
+/// ```
+fn reconstruct_with_rtk(commands: &[analysis::NativeCommand]) -> String {
+    commands
+        .iter()
+        .map(|cmd| {
+            // Reconstruct the core raw string from parsed binary + args.
+            // Quote-stripping in parse_chain means we lose original quoting here,
+            // but this is acceptable for the common cases (simple args, no spaces).
+            let core_raw = if cmd.args.is_empty() {
+                cmd.binary.clone()
+            } else {
+                format!("{} {}", cmd.binary, cmd.args.join(" "))
+            };
+
+            // Route if known; otherwise preserve the original core_raw verbatim.
+            let part = match try_route_native_command(cmd, &core_raw) {
+                Some(routed) => routed,
+                None => core_raw,
+            };
+
+            // Append operator if present (all but the last command have one).
+            match &cmd.operator {
+                Some(op) => format!("{} {}", part, op),
+                None => part,
+            }
+        })
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+/// Format hook result for Claude (text output)
+///
+/// Exit codes:
+/// - 0: Success, command rewritten/allowed
+/// - 2: Blocking error, command should be denied
+pub fn format_for_claude(result: HookResult) -> (String, bool, i32) {
+    match result {
+        HookResult::Rewrite(cmd) => (cmd, true, 0),
+        HookResult::Blocked(msg) => (msg, false, 2), // Exit 2 = blocking error per Claude Code spec
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // === TEST HELPERS ===
+
+    fn assert_rewrite(input: &str, contains: &str) {
+        match check_for_hook(input, "claude") {
+            HookResult::Rewrite(cmd) => assert!(
+                cmd.contains(contains),
+                "'{}' rewrite should contain '{}', got '{}'",
+                input,
+                contains,
+                cmd
+            ),
+            other => panic!("Expected Rewrite for '{}', got {:?}", input, other),
+        }
+    }
+
+    /// Assert that a command at the given rewrite depth produces a Blocked result
+    /// containing the expected message substring.
+    fn assert_blocked(input: &str, depth: usize, contains: &str) {
+        match check_for_hook_inner(input, depth) {
+            HookResult::Blocked(msg) => assert!(
+                msg.contains(contains),
+                "'{}' block msg should contain '{}', got '{}'",
+                input,
+                contains,
+                msg
+            ),
+            other => panic!("Expected Blocked for '{}', got {:?}", input, other),
+        }
+    }
+
+    // === ESCAPE_QUOTES ===
+
+    #[test]
+    fn test_escape_quotes() {
+        assert_eq!(escape_quotes("hello"), "hello");
+        assert_eq!(escape_quotes("it's"), "it'\\''s");
+        assert_eq!(escape_quotes("it's a test's"), "it'\\''s a test'\\''s");
+    }
+
+    // === EMPTY / WHITESPACE ===
+
+    #[test]
+    fn test_check_empty_and_whitespace() {
+        match check_for_hook("", "claude") {
+            HookResult::Rewrite(cmd) => assert!(cmd.is_empty()),
+            _ => panic!("Expected Rewrite for empty"),
+        }
+        match check_for_hook("   ", "claude") {
+            HookResult::Rewrite(cmd) => assert!(cmd.trim().is_empty()),
+            _ => panic!("Expected Rewrite for whitespace"),
+        }
+    }
+
+    // === COMMANDS THAT SHOULD REWRITE (table-driven) ===
+
+    #[test]
+    fn test_safe_commands_rewrite() {
+        // Known commands route to RTK subcommands
+        assert_rewrite("git status", "rtk git status");
+        assert_rewrite(r#"git commit -m "Fix && Bug""#, "rtk git commit"); // quoted &&: single cmd, routes
+
+        // Shell metacharacters still go through rtk run -c (needs_shell detects them)
+        let shell_cases = [
+            ("ls *.rs", "rtk run"),               // glob
+            ("echo `date`", "rtk run"),           // backticks
+            ("echo $(date)", "rtk run"),          // subshell
+            ("echo {a,b}.txt", "rtk run"),        // brace expansion
+            ("cd /tmp && git status", "rtk run"), // chain rewrite
+        ];
+        for (input, expected) in shell_cases {
+            assert_rewrite(input, expected);
+        }
+
+        // Single unknown commands pass through unchanged (no wrapping)
+        assert_passthrough("FOO=bar echo hello"); // env prefix + unknown cmd
+        assert_passthrough("echo 'hello!@#$%^&*()'"); // special chars in quotes (no shell metachar)
+        assert_passthrough("echo '日本語 🎉'"); // unicode in quotes
+        assert_passthrough(&format!("echo {}", "a".repeat(1000))); // very long command
+
+        // Chain rewrite preserves operator structure
+        match check_for_hook("cd /tmp && git status", "claude") {
+            HookResult::Rewrite(cmd) => assert!(
+                cmd.contains("&&"),
+                "Chain rewrite must preserve '&&', got '{}'",
+                cmd
+            ),
+            other => panic!("Expected Rewrite for chain, got {:?}", other),
+        }
+    }
+
+    // === ENV VAR PREFIX ROUTING ===
+    // Commands prefixed with KEY=VALUE env vars must route to the optimized RTK
+    // subcommand with the env var preserved, not fall back to rtk run -c passthrough.
+
+    #[test]
+    fn test_env_prefix_routes_to_rtk_subcommand() {
+        // Each case: (input, expected_rtk_subcommand_prefix, env_prefix_preserved)
+        let cases = [
+            ("GIT_PAGER=cat git status", "rtk git", "GIT_PAGER=cat"),
+            (
+                "GIT_PAGER=cat git log --oneline -10",
+                "rtk git",
+                "GIT_PAGER=cat",
+            ),
+            ("RUST_LOG=debug cargo test", "rtk cargo", "RUST_LOG=debug"),
+            ("LANG=C ls -la", "rtk ls", "LANG=C"),
+            (
+                "TEST_SESSION_ID=2 npx playwright test --config=foo",
+                "rtk playwright",
+                "TEST_SESSION_ID=2",
+            ),
+        ];
+        for (input, rtk_sub, env_prefix) in cases {
+            match check_for_hook(input, "claude") {
+                HookResult::Rewrite(cmd) => {
+                    assert!(
+                        cmd.contains(rtk_sub),
+                        "'{input}' must route to '{rtk_sub}', got '{cmd}'"
+                    );
+                    assert!(
+                        cmd.contains(env_prefix),
+                        "'{input}' must preserve env prefix '{env_prefix}', got '{cmd}'"
+                    );
+                }
+                other => panic!("Expected Rewrite for '{input}', got {other:?}"),
+            }
+        }
+    }
+
+    #[test]
+    fn test_env_prefix_multi_var_routes() {
+        // Multiple env vars before a known command
+        let input = "NODE_ENV=test CI=1 npx vitest run";
+        match check_for_hook(input, "claude") {
+            HookResult::Rewrite(cmd) => {
+                assert!(
+                    cmd.contains("rtk vitest"),
+                    "must route to rtk vitest, got '{cmd}'"
+                );
+                assert!(
+                    cmd.contains("NODE_ENV=test"),
+                    "must preserve NODE_ENV, got '{cmd}'"
+                );
+                assert!(cmd.contains("CI=1"), "must preserve CI, got '{cmd}'");
+            }
+            other => panic!("Expected Rewrite, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_env_prefix_unknown_cmd_fallback() {
+        // Unknown command after env prefix → passes through unchanged
+        assert_passthrough("VAR=1 unknown_xyz_abc_cmd");
+    }
+
+    #[test]
+    fn test_env_prefix_npm_still_passthrough() {
+        // npm has no RTK subcommand → passes through unchanged
+        assert_passthrough("NODE_ENV=test npm run test:e2e");
+    }
+
+    #[test]
+    fn test_env_prefix_docker_compose_passthrough() {
+        // docker compose up has no RTK route → passes through unchanged
+        assert_passthrough("COMPOSE_PROJECT_NAME=test docker compose up -d");
+    }
+
+    // === GLOBAL OPTIONS (PR #99 parity) ===
+    // Commands with global options before subcommands must not be blocked.
+    // Ported from upstream hooks/rtk-rewrite.sh global option stripping.
+
+    #[test]
+    fn test_global_options_not_blocked() {
+        // Commands with global options must NOT be blocked.
+        // They pass through unchanged since hook_lookup doesn't strip global options.
+        let cases = [
+            // Git global options
+            "git --no-pager status",
+            "git -C /path/to/project status",
+            "git -C /path --no-pager log --oneline",
+            "git --no-optional-locks diff HEAD",
+            "git --bare log",
+            // Cargo toolchain prefix
+            "cargo +nightly test",
+            "cargo +stable build --release",
+            // Docker global options
+            "docker --context prod ps",
+            "docker -H tcp://host:2375 images",
+            // Kubectl global options
+            "kubectl -n kube-system get pods",
+            "kubectl --context prod describe pod foo",
+        ];
+        for input in cases {
+            assert_passthrough(input);
+        }
+    }
+
+    // === SPECIFIC COMMANDS NOT BLOCKED ===
+    // Ported from old hooks/test-rtk-rewrite.sh Sections 1 & 3.
+    // These commands must pass through (not be blocked by safety rules).
+
+    #[test]
+    fn test_specific_commands_not_blocked() {
+        let cases = [
+            // Git variants
+            "git log --oneline -10",
+            "git diff HEAD",
+            "git show abc123",
+            "git add .",
+            // GitHub CLI
+            "gh pr list",
+            "gh api repos/owner/repo",
+            "gh release list",
+            // Package managers
+            "npm run test:e2e",
+            "npm run build",
+            "npm test",
+            // Docker
+            "docker compose up -d",
+            "docker compose logs postgrest",
+            "docker compose down",
+            "docker run --rm postgres",
+            "docker exec -it db psql",
+            // Kubernetes
+            "kubectl describe pod foo",
+            "kubectl apply -f deploy.yaml",
+            // Test runners
+            "npx playwright test",
+            "npx prisma migrate",
+            "cargo test",
+            // Vitest variants (dedup is internal to rtk run, not hook level)
+            "vitest",
+            "vitest run",
+            "vitest run --reporter=verbose",
+            "npx vitest run",
+            "pnpm vitest run --coverage",
+            // TypeScript
+            "vue-tsc -b",
+            "npx vue-tsc --noEmit",
+            // Utilities
+            "curl -s https://example.com",
+            "ls -la",
+            "grep -rn pattern src/",
+            "rg pattern src/",
+        ];
+        for input in cases {
+            // Test name intent: commands must Rewrite (not Blocked), regardless of routing target.
+            // Specific routing targets are verified in test_routing_native_commands.
+            assert!(
+                matches!(check_for_hook(input, "claude"), HookResult::Rewrite(_)),
+                "'{}' should Rewrite (not Blocked)",
+                input
+            );
+        }
+    }
+
+    // === COMMANDS THAT PASS THROUGH (builtins/unknown) ===
+    // Ported from old hooks/test-rtk-rewrite.sh Section 5.
+    // These are not blocked — they pass through unchanged (no rtk run -c wrapping).
+
+    #[test]
+    fn test_builtins_not_blocked() {
+        let cases = [
+            "echo hello world",
+            "cd /tmp",
+            "mkdir -p foo/bar",
+            "python3 script.py",
+            "find . -name '*.ts'",
+            "tree src/",
+            "wget https://example.com/file",
+        ];
+        for input in cases {
+            assert_passthrough(input);
+        }
+        // node -e with single quotes: lexer handles as quoted string, passes through
+        assert_passthrough("node -e 'console.log(1)'");
+    }
+
+    // === SHELL PREFIX BUILTINS (noglob, command, builtin, exec, nocorrect) ===
+    // These zsh/bash builtins modify the execution of the NEXT command.
+    // The hook should strip the prefix, route the real command, and
+    // re-prepend the prefix so the shell applies it correctly.
+    //
+    // Bug: `noglob gh release create v0.3.0-rc1 ...` was being wrapped in
+    // `rtk run -c 'noglob gh ...'` which fails because noglob is a shell
+    // builtin, not an executable that rtk can invoke.
+
+    #[test]
+    fn test_noglob_prefix_routes_inner_command() {
+        // noglob + known command: should route the inner command through RTK
+        assert_rewrite("noglob gh pr view 123", "noglob rtk gh pr view 123");
+    }
+
+    #[test]
+    fn test_noglob_prefix_with_unknown_command() {
+        // noglob + unknown command: should preserve noglob prefix, wrap inner in rtk run -c
+        match check_for_hook("noglob some-unknown-tool --arg", "claude") {
+            HookResult::Rewrite(cmd) => {
+                // noglob should be OUTSIDE the rtk run -c, not inside it
+                assert!(
+                    !cmd.contains("rtk run -c 'noglob"),
+                    "noglob should not be inside rtk run -c, got '{}'",
+                    cmd
+                );
+            }
+            HookResult::Blocked(_) => panic!("should not be blocked"),
+        }
+    }
+
+    #[test]
+    fn test_command_prefix_routes_inner_command() {
+        assert_rewrite("command git status", "command rtk git status");
+    }
+
+    #[test]
+    fn test_builtin_prefix_passthrough() {
+        // builtin cd should just pass through with noglob-style prefix handling
+        match check_for_hook("builtin cd /tmp", "claude") {
+            HookResult::Rewrite(cmd) => {
+                assert!(
+                    !cmd.contains("rtk run -c 'builtin"),
+                    "builtin should not be inside rtk run -c, got '{}'",
+                    cmd
+                );
+            }
+            HookResult::Blocked(_) => panic!("should not be blocked"),
+        }
+    }
+
+    #[test]
+    fn test_nocorrect_prefix_routes_inner_command() {
+        assert_rewrite("nocorrect git log -10", "nocorrect rtk git log");
+    }
+
+    #[test]
+    fn test_noglob_gh_release_create_exact_bug_report() {
+        // Exact command from the bug report that triggered `rtk: noglob: command not found`
+        let input = "noglob gh release create v0.3.0-rc1 --title v0.3.0-rc1 --notes test --prerelease --draft";
+        match check_for_hook(input, "claude") {
+            HookResult::Rewrite(cmd) => {
+                // gh release is not in hook_lookup whitelist (only pr/issue/run),
+                // so inner routes to rtk run -c. noglob must stay outside.
+                assert!(
+                    !cmd.contains("rtk run -c 'noglob"),
+                    "noglob must not be inside rtk run -c, got '{}'",
+                    cmd
+                );
+                assert!(
+                    cmd.starts_with("noglob "),
+                    "noglob must be the outermost prefix, got '{}'",
+                    cmd
+                );
+            }
+            HookResult::Blocked(_) => panic!("should not be blocked"),
+        }
+    }
+
+    #[test]
+    fn test_nested_shell_prefixes() {
+        // noglob + command: both should be stripped, inner command routed
+        assert_rewrite("noglob command git status", "noglob command rtk git status");
+    }
+
+    #[test]
+    fn test_shell_prefix_plus_env_prefix() {
+        // noglob + GIT_PAGER=cat + git log: all three layers stripped correctly
+        assert_rewrite(
+            "noglob GIT_PAGER=cat git log -10",
+            "noglob GIT_PAGER=cat rtk git log",
+        );
+    }
+
+    #[test]
+    fn test_exec_prefix_routes_inner_command() {
+        assert_rewrite("exec git status", "exec rtk git status");
+    }
+
+    #[test]
+    fn test_bare_shell_prefix_passthrough() {
+        // Bare "noglob" with no following command — pass through unchanged
+        match check_for_hook("noglob", "claude") {
+            HookResult::Rewrite(cmd) => {
+                assert_eq!(cmd, "noglob", "bare prefix should pass through unchanged");
+            }
+            HookResult::Blocked(_) => panic!("should not be blocked"),
+        }
+    }
+
+    // === UNKNOWN COMMAND PASSTHROUGH ===
+    // Unknown commands (not in hook_lookup whitelist) should pass through
+    // unchanged instead of being wrapped in `rtk run -c '...'`.
+    // Wrapping adds an extra shell layer for zero token savings and causes
+    // quoting/globbing bugs (e.g. zsh NOMATCH on version strings).
+
+    /// Assert that a command passes through unchanged (no `rtk run -c` wrapping).
+    fn assert_passthrough(input: &str) {
+        match check_for_hook(input, "claude") {
+            HookResult::Rewrite(cmd) => {
+                assert!(
+                    !cmd.contains("rtk run -c"),
+                    "command should NOT be wrapped in rtk run -c, got '{}'",
+                    cmd
+                );
+                assert_eq!(cmd, input, "unknown command should pass through unchanged");
+            }
+            HookResult::Blocked(_) => panic!("Expected passthrough for '{}', got Blocked", input),
+        }
+    }
+
+    #[test]
+    fn test_unknown_command_passthrough() {
+        // gh release is NOT in hook_lookup whitelist — should pass through unchanged
+        assert_passthrough("gh release create v0.3.0 --title test");
+    }
+
+    #[test]
+    fn test_full_path_binary_routes_correctly() {
+        // Full-path binary should be recognized via basename extraction
+        assert_rewrite("/opt/homebrew/bin/git status", "rtk git status");
+    }
+
+    #[test]
+    fn test_full_path_unknown_command_passthrough() {
+        assert_passthrough("/opt/homebrew/bin/gh release create v0.3.0");
+    }
+
+    #[test]
+    fn test_env_prefix_unknown_command_passthrough() {
+        assert_passthrough("GH_DEBUG= gh release create v0.3.0");
+    }
+
+    #[test]
+    fn test_noglob_unknown_command_passthrough() {
+        assert_passthrough("noglob gh release create v0.3.0");
+    }
+
+    #[test]
+    fn test_chain_mixed_known_unknown() {
+        // Chains still wrap in rtk run -c, but unknown cmds are preserved inside
+        match check_for_hook("gh release create v1 && git status", "claude") {
+            HookResult::Rewrite(cmd) => {
+                assert!(cmd.contains("rtk run -c"), "chains still need rtk run -c");
+                assert!(cmd.contains("rtk git status"), "known cmd routed");
+                assert!(
+                    cmd.contains("gh release create v1"),
+                    "unknown cmd preserved"
+                );
+            }
+            HookResult::Blocked(_) => panic!("should not be blocked"),
+        }
+    }
+
+    #[test]
+    fn test_gh_release_create_exact_bug_report() {
+        let input = r#"gh release create v0.3.0 --title "ai_session_tools v0.3.0" --notes-file notes/v0.3.0-release.md"#;
+        assert_passthrough(input);
+    }
+
+    #[test]
+    fn test_completely_unknown_binary_passthrough() {
+        // Binaries RTK has never heard of should pass through
+        assert_passthrough("some-custom-tool --flag value");
+    }
+
+    // === COMPOUND COMMANDS (chained with &&, ||, ;) ===
+    // Shell script only matched FIRST command in a chain.
+    // Rust hook parses each command independently (#112).
+
+    #[test]
+    fn test_compound_commands_rewrite() {
+        let cases = [
+            // Basic chains — each command rewritten independently
+            ("cd /tmp && git status", "&&"),
+            ("cd dir && git status && git diff", "&&"),
+            ("git add . && git commit -m msg", "&&"),
+            // Semicolon chains
+            ("echo start ; git status ; echo done", ";"),
+            // Or-chains
+            ("git pull || echo failed", "||"),
+        ];
+        for (input, operator) in cases {
+            match check_for_hook(input, "claude") {
+                HookResult::Rewrite(cmd) => {
+                    assert!(cmd.contains("rtk run"), "'{input}' should rewrite");
+                    assert!(
+                        cmd.contains(operator),
+                        "'{input}' must preserve '{operator}', got '{cmd}'"
+                    );
+                }
+                other => panic!("Expected Rewrite for '{input}', got {other:?}"),
+            }
+        }
+    }
+
+    // PR 2 adds: test_compound_blocked_in_chain (safety-dependent test)
+
+    #[test]
+    fn test_compound_quoted_operators_not_split() {
+        // && inside quotes must NOT split the command into a chain.
+        // parse_chain sees one command: git commit with args ["-m", "Fix && Bug"].
+        // That single command routes to rtk git commit (not rtk run -c).
+        let input = r#"git commit -m "Fix && Bug""#;
+        match check_for_hook(input, "claude") {
+            HookResult::Rewrite(cmd) => {
+                assert!(
+                    cmd.contains("rtk git commit"),
+                    "Quoted && must not split; should route to rtk git commit, got '{cmd}'"
+                );
+            }
+            other => panic!("Expected Rewrite for quoted &&, got {other:?}"),
+        }
+    }
+
+    // PR 2 adds: test_blocked_commands (safety-dependent test)
+
+    // === SUFFIX-AWARE ROUTING: redirect/pipe suffix preserved, RTK filter applied ===
+    // When a known RTK command has a "safe" redirect or pipe suffix, the hook should
+    // rewrite to `rtk <cmd> <suffix>` so RTK's filter applies AND the shell handles the suffix.
+
+    #[test]
+    fn test_suffix_2_redirect_routes_to_rtk() {
+        // "cargo test 2>&1" → "rtk cargo test 2>&1" (not rtk run -c)
+        let input = "cargo test 2>&1";
+        match check_for_hook(input, "claude") {
+            HookResult::Rewrite(cmd) => {
+                assert!(
+                    cmd.contains("rtk cargo"),
+                    "must use rtk cargo filter, got '{cmd}'"
+                );
+                assert!(
+                    cmd.contains("2>&1"),
+                    "must preserve 2>&1 suffix, got '{cmd}'"
+                );
+                assert!(
+                    !cmd.contains("rtk run -c"),
+                    "must NOT fall back to passthrough, got '{cmd}'"
+                );
+            }
+            other => panic!("Expected Rewrite, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_suffix_dev_null_routes_to_rtk() {
+        // "cargo test 2>/dev/null" → "rtk cargo test 2>/dev/null"
+        let input = "cargo test 2>/dev/null";
+        match check_for_hook(input, "claude") {
+            HookResult::Rewrite(cmd) => {
+                assert!(cmd.contains("rtk cargo"), "must use rtk cargo, got '{cmd}'");
+                assert!(
+                    cmd.contains("/dev/null"),
+                    "must preserve /dev/null suffix, got '{cmd}'"
+                );
+                assert!(
+                    !cmd.contains("rtk run -c"),
+                    "must NOT fall back to passthrough, got '{cmd}'"
+                );
+            }
+            other => panic!("Expected Rewrite, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_suffix_pipe_tee_routes_to_rtk() {
+        // "cargo test | tee /tmp/log.txt" → "rtk cargo test | tee /tmp/log.txt"
+        let input = "cargo test | tee /tmp/log.txt";
+        match check_for_hook(input, "claude") {
+            HookResult::Rewrite(cmd) => {
+                assert!(
+                    cmd.contains("rtk cargo"),
+                    "must use rtk cargo filter, got '{cmd}'"
+                );
+                assert!(cmd.contains("tee"), "must preserve tee suffix, got '{cmd}'");
+            }
+            other => panic!("Expected Rewrite, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_suffix_pipe_head_routes_to_rtk() {
+        // "git log | head -20" → "rtk git log | head -20" (not passthrough)
+        let input = "git log | head -20";
+        match check_for_hook(input, "claude") {
+            HookResult::Rewrite(cmd) => {
+                assert!(cmd.contains("rtk git"), "must use rtk git, got '{cmd}'");
+                assert!(
+                    cmd.contains("head"),
+                    "must preserve head suffix, got '{cmd}'"
+                );
+                assert!(
+                    !cmd.contains("rtk run -c"),
+                    "must NOT fall back to passthrough, got '{cmd}'"
+                );
+            }
+            other => panic!("Expected Rewrite, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_suffix_unknown_cmd_still_passthrough() {
+        // Unknown command with redirect suffix → passes through unchanged
+        assert_passthrough("unknown_xyz_cmd 2>&1");
+    }
+
+    #[test]
+    fn test_suffix_unsafe_pipe_still_passthrough() {
+        // Pipe to grep (not a known safe sink) → stays as rtk run -c passthrough
+        // This is debatable; for safety, unknown pipe destinations stay in shell
+        let input = "cargo test | grep FAILED";
+        match check_for_hook(input, "claude") {
+            HookResult::Rewrite(cmd) => {
+                // Either passthrough or rtk routing is acceptable, but must not panic
+                let _ = cmd;
+            }
+            other => panic!("Expected Rewrite, got {other:?}"),
+        }
+    }
+
+    // === SHELLISM PASSTHROUGH: cat/sed/head allowed with pipe/redirect ===
+
+    #[test]
+    fn test_token_waste_allowed_in_pipelines() {
+        let cases = [
+            "cat file.txt | grep pattern",
+            "cat file.txt > output.txt",
+            "sed 's/old/new/' file.txt > output.txt",
+            "head -n 10 file.txt | grep pattern",
+            "for f in *.txt; do cat \"$f\" | grep x; done",
+        ];
+        for input in cases {
+            assert_rewrite(input, "rtk run");
+        }
+    }
+
+    // === MULTI-AGENT ===
+
+    #[test]
+    fn test_different_agents_same_result() {
+        // Both agents must Rewrite (not Block) safe commands.
+        // Specific routing targets verified in test_cross_agent_routing_identical.
+        for agent in ["claude", "gemini"] {
+            match check_for_hook("git status", agent) {
+                HookResult::Rewrite(_) => {}
+                other => panic!("Expected Rewrite for agent '{}', got {:?}", agent, other),
+            }
+        }
+    }
+
+    // === FORMAT_FOR_CLAUDE ===
+
+    #[test]
+    fn test_format_for_claude() {
+        let (output, success, code) =
+            format_for_claude(HookResult::Rewrite("rtk run -c 'git status'".to_string()));
+        assert_eq!(output, "rtk run -c 'git status'");
+        assert!(success);
+        assert_eq!(code, 0);
+
+        let (output, success, code) =
+            format_for_claude(HookResult::Blocked("Error message".to_string()));
+        assert_eq!(output, "Error message");
+        assert!(!success);
+        assert_eq!(code, 2); // Exit 2 = blocking error per Claude Code spec
+    }
+
+    // === $VAR LEXER FIX: NATIVE ROUTING ===
+    // After the lexer fix, simple $IDENT vars are Arg tokens, not Shellisms.
+    // This enables native RTK routing for commands with simple variable references.
+
+    #[test]
+    fn test_dollar_var_routes_natively() {
+        // git log $BRANCH: $BRANCH should be Arg → routes to rtk git, not rtk run -c
+        let result = match check_for_hook("git log $BRANCH", "claude") {
+            HookResult::Rewrite(cmd) => cmd,
+            other => panic!("Expected Rewrite, got {:?}", other),
+        };
+        assert!(
+            result.contains("rtk git"),
+            "Expected rtk git routing for 'git log $BRANCH', got: {}",
+            result
+        );
+        assert!(
+            !result.contains("rtk run"),
+            "Should not fall to passthrough for simple $VAR, got: {}",
+            result
+        );
+    }
+
+    #[test]
+    fn test_dollar_subshell_still_passthrough() {
+        // git log $(git rev-parse HEAD): $(…) needs shell — must passthrough
+        let result = match check_for_hook("git log $(git rev-parse HEAD)", "claude") {
+            HookResult::Rewrite(cmd) => cmd,
+            other => panic!("Expected Rewrite, got {:?}", other),
+        };
+        assert!(
+            result.contains("rtk run"),
+            "Subshell $(…) must route to passthrough, got: {}",
+            result
+        );
+    }
+
+    // === RECURSION DEPTH LIMIT ===
+
+    #[test]
+    fn test_rewrite_depth_limit_blocked() {
+        // At max depth → blocked with loop detection message
+        assert_blocked("echo hello", MAX_REWRITE_DEPTH, "loop");
+    }
+
+    #[test]
+    fn test_rewrite_depth_limit_allowed() {
+        // At depth 0 → normal rewrite (unknown cmd passes through unchanged)
+        match check_for_hook_inner("echo hello", 0) {
+            HookResult::Rewrite(cmd) => assert_eq!(cmd, "echo hello"),
+            _ => panic!("Expected Rewrite at depth 0"),
+        }
+    }
+
+    // =========================================================================
+    // CLAUDE CODE WIRE FORMAT CONFORMANCE
+    // https://docs.anthropic.com/en/docs/claude-code/hooks
+    //
+    // Claude Code hook protocol:
+    // - Rewrite: command on stdout, exit code 0
+    // - Block: message on stderr, exit code 2
+    // - Other exit codes are non-blocking errors
+    //
+    // format_for_claude() is the boundary between HookResult and the wire.
+    // These tests verify it produces the exact contract Claude Code expects.
+    // =========================================================================
+
+    #[test]
+    fn test_claude_rewrite_exit_code_is_zero() {
+        let (_, _, code) = format_for_claude(HookResult::Rewrite("rtk run -c 'ls'".into()));
+        assert_eq!(code, 0, "Rewrite must exit 0 (success)");
+    }
+
+    #[test]
+    fn test_claude_block_exit_code_is_two() {
+        let (_, _, code) = format_for_claude(HookResult::Blocked("denied".into()));
+        assert_eq!(
+            code, 2,
+            "Block must exit 2 (blocking error per Claude Code spec)"
+        );
+    }
+
+    #[test]
+    fn test_claude_rewrite_output_is_command_text() {
+        // Claude Code reads stdout as the rewritten command — must be plain text, not JSON
+        let (output, success, _) =
+            format_for_claude(HookResult::Rewrite("rtk run -c 'git status'".into()));
+        assert_eq!(output, "rtk run -c 'git status'");
+        assert!(success);
+        // Must NOT be JSON
+        assert!(
+            !output.starts_with('{'),
+            "Rewrite output must be plain text, not JSON"
+        );
+    }
+
+    #[test]
+    fn test_claude_block_output_is_human_message() {
+        // Claude Code reads stderr for the block reason
+        let (output, success, _) =
+            format_for_claude(HookResult::Blocked("Use Read tool instead".into()));
+        assert_eq!(output, "Use Read tool instead");
+        assert!(!success);
+        // Must NOT be JSON
+        assert!(
+            !output.starts_with('{'),
+            "Block output must be plain text, not JSON"
+        );
+    }
+
+    #[test]
+    fn test_claude_rewrite_success_flag_true() {
+        let (_, success, _) = format_for_claude(HookResult::Rewrite("cmd".into()));
+        assert!(success, "Rewrite must set success=true");
+    }
+
+    #[test]
+    fn test_claude_block_success_flag_false() {
+        let (_, success, _) = format_for_claude(HookResult::Blocked("msg".into()));
+        assert!(!success, "Block must set success=false");
+    }
+
+    #[test]
+    fn test_claude_exit_codes_not_one() {
+        // Exit code 1 means non-blocking error in Claude Code — we must never use it
+        let (_, _, rewrite_code) = format_for_claude(HookResult::Rewrite("cmd".into()));
+        let (_, _, block_code) = format_for_claude(HookResult::Blocked("msg".into()));
+        assert_ne!(
+            rewrite_code, 1,
+            "Exit code 1 is non-blocking error, not valid for rewrite"
+        );
+        assert_ne!(
+            block_code, 1,
+            "Exit code 1 is non-blocking error, not valid for block"
+        );
+    }
+
+    // === CROSS-PROTOCOL: Same decision for both agents ===
+
+    #[test]
+    fn test_cross_protocol_safe_command_allowed_by_both() {
+        // Both Claude and Gemini must allow the same safe commands
+        for cmd in ["git status", "cargo test", "ls -la", "echo hello"] {
+            let claude = check_for_hook(cmd, "claude");
+            let gemini = check_for_hook(cmd, "gemini");
+            match (&claude, &gemini) {
+                (HookResult::Rewrite(_), HookResult::Rewrite(_)) => {}
+                _ => panic!(
+                    "'{}': Claude={:?}, Gemini={:?} — both should Rewrite",
+                    cmd, claude, gemini
+                ),
+            }
+        }
+    }
+
+    // PR 2 adds: test_cross_protocol_blocked_command_denied_by_both (safety-dependent test)
+
+    // =====================================================================
+    // ROUTING TESTS — verify route_native_command dispatch
+    // =====================================================================
+
+    #[test]
+    fn test_routing_native_commands() {
+        // Table-driven: commands that route to optimized rtk subcommands.
+        // Each (input, expected_substr) must appear in the rewritten output.
+        let cases = [
+            // Git: known subcommands
+            ("git status", "rtk git status"),
+            ("git log --oneline -10", "rtk git log --oneline -10"),
+            ("git diff HEAD", "rtk git diff HEAD"),
+            ("git add .", "rtk git add ."),
+            ("git commit -m msg", "rtk git commit"),
+            // GitHub CLI
+            ("gh pr view 156", "rtk gh pr view 156"),
+            // Cargo
+            ("cargo test", "rtk cargo test"),
+            (
+                "cargo clippy --all-targets",
+                "rtk cargo clippy --all-targets",
+            ),
+            // File ops (rg → rtk grep rename)
+            // NOTE: PR 2 adds safety that blocks cat before reaching router; arm is defensive.
+            ("grep -r pattern src/", "rtk grep -r pattern src/"),
+            ("rg pattern src/", "rtk grep pattern src/"),
+            ("ls -la", "rtk ls -la"),
+            // JS/TS tooling
+            ("vitest", "rtk vitest run"),     // bare → rtk vitest run
+            ("vitest run", "rtk vitest run"), // explicit run preserved
+            ("vitest run --coverage", "rtk vitest run --coverage"),
+            ("pnpm test", "rtk vitest run"),
+            ("pnpm vitest", "rtk vitest run"),
+            ("pnpm lint", "rtk lint"),
+            ("pnpm eslint src/", "rtk lint"), // pnpm eslint → rtk lint
+            ("pnpm eslint .", "rtk lint ."),  // pnpm eslint bare form
+            ("pnpm eslint --fix src/", "rtk lint"), // pnpm eslint with flag
+            ("npx tsc --noEmit", "rtk tsc --noEmit"),
+            // Python
+            ("python -m pytest tests/", "rtk pytest tests/"),
+            ("uv pip list", "rtk pip list"),
+            // Go
+            ("go test ./...", "rtk go test ./..."),
+            ("go build ./...", "rtk go build ./..."),
+            ("go vet ./...", "rtk go vet ./..."),
+            // All ROUTES entries not yet covered above
+            ("eslint src/", "rtk lint src/"), // rename: eslint → lint
+            ("tsc --noEmit", "rtk tsc --noEmit"), // bare tsc (not npx tsc)
+            ("prettier src/", "rtk prettier src/"),
+            ("playwright test", "rtk playwright test"),
+            ("prisma migrate dev", "rtk prisma migrate dev"),
+            (
+                "curl https://api.example.com",
+                "rtk curl https://api.example.com",
+            ),
+            ("pytest tests/", "rtk pytest tests/"), // bare pytest (not python -m pytest)
+            ("pytest -x tests/unit", "rtk pytest -x tests/unit"),
+            ("golangci-lint run ./...", "rtk golangci-lint run ./..."),
+            ("docker ps", "rtk docker ps"),
+            ("docker images", "rtk docker images"),
+            ("docker logs mycontainer", "rtk docker logs mycontainer"),
+            ("kubectl get pods", "rtk kubectl get pods"),
+            ("kubectl logs mypod", "rtk kubectl logs mypod"),
+            ("ruff check src/", "rtk ruff check src/"),
+            ("ruff format src/", "rtk ruff format src/"),
+            ("pip list", "rtk pip list"),
+            ("pip install requests", "rtk pip install requests"),
+            ("pip outdated", "rtk pip outdated"),
+            ("pip show requests", "rtk pip show requests"),
+            ("gh issue list", "rtk gh issue list"),
+            ("gh run view 123", "rtk gh run view 123"),
+            ("git stash pop", "rtk git stash pop"),
+            ("git fetch origin", "rtk git fetch origin"),
+            // Graphite CLI — all subcommands route through RTK
+            ("gt log", "rtk gt log"),
+            ("gt submit", "rtk gt submit"),
+            ("gt sync", "rtk gt sync"),
+            ("gt create feat/new-branch", "rtk gt create feat/new-branch"),
+        ];
+        for (input, expected) in cases {
+            assert_rewrite(input, expected);
+        }
+    }
+
+    #[test]
+    fn test_routing_subcommand_filter_fallback() {
+        // Commands where binary is in ROUTES but subcommand is NOT in the Only list
+        // must pass through unchanged (no wrapping in rtk run -c).
+        let cases = [
+            "docker build .",            // docker Only: ps, images, logs
+            "docker run -it nginx",      // docker Only: ps, images, logs
+            "kubectl apply -f dep.yaml", // kubectl Only: get, logs
+            "kubectl delete pod mypod",  // kubectl Only: get, logs
+            "go mod tidy",               // go Only: test, build, vet
+            "go generate ./...",         // go Only: test, build, vet
+            "ruff lint src/",            // ruff Only: check, format
+            "pip freeze",                // pip Only: list, outdated, install, show
+            "pip uninstall requests",    // pip Only: list, outdated, install, show
+            "cargo publish",             // cargo Only: test, build, clippy, check
+            "cargo run",                 // cargo Only: test, build, clippy, check
+            "git rebase -i HEAD~3",      // git Only list (rebase not included)
+            "git cherry-pick abc123",    // git Only list
+            "gh repo clone foo/bar",     // gh Only: pr, issue, run
+        ];
+        for input in cases {
+            assert_passthrough(input);
+        }
+    }
+
+    #[test]
+    fn test_routing_vitest_no_double_run() {
+        // Shell script sed bug: 's/^(pnpm )?vitest/rtk vitest run/' on
+        // "pnpm vitest run --coverage" produces "rtk vitest run run --coverage".
+        // Binary hook corrects this by using parsed args instead of regex substitution.
+        let result = match check_for_hook("pnpm vitest run --coverage", "claude") {
+            HookResult::Rewrite(cmd) => cmd,
+            other => panic!("Expected Rewrite, got {:?}", other),
+        };
+        assert_rewrite("pnpm vitest run --coverage", "rtk vitest run --coverage");
+        assert!(
+            !result.contains("run run"),
+            "Must not double 'run' in output: '{}'",
+            result
+        );
+    }
+
+    #[test]
+    fn test_routing_fallbacks_to_rtk_run() {
+        // Chains (2+ cmds) and pipes still fall back to rtk run -c.
+        let chain_cases = [
+            "git add . && git commit -m msg", // chain → 2 commands → rtk run -c
+            "git log | grep fix",             // pipe → needs_shell → rtk run -c
+        ];
+        for input in chain_cases {
+            assert_rewrite(input, "rtk run -c");
+        }
+        // Single unknown commands pass through unchanged (no wrapping).
+        let passthrough_cases = [
+            "git checkout main", // unknown git subcommand
+            "tail -n 20 file.txt",
+            "tail -f server.log",
+        ];
+        for input in passthrough_cases {
+            assert_passthrough(input);
+        }
+    }
+
+    #[test]
+    fn test_cross_agent_routing_identical() {
+        // Both claude and gemini must route the same commands to the same output.
+        for cmd in ["git status", "cargo test", "ls -la"] {
+            let claude_result = check_for_hook(cmd, "claude");
+            let gemini_result = check_for_hook(cmd, "gemini");
+            match (&claude_result, &gemini_result) {
+                (HookResult::Rewrite(c), HookResult::Rewrite(g)) => {
+                    assert_eq!(c, g, "claude and gemini must route '{}' identically", cmd);
+                    assert!(
+                        !c.contains("rtk run -c"),
+                        "'{}' should not fall back to rtk run -c",
+                        cmd
+                    );
+                }
+                _ => panic!(
+                    "'{}' should Rewrite for both agents: claude={:?} gemini={:?}",
+                    cmd, claude_result, gemini_result
+                ),
+            }
+        }
+    }
+
+    // === INNER COMMAND SUBSTITUTION (&&, ||, ; chains) ===
+    // When a multi-command chain is wrapped in "rtk run -c '...'", each individual
+    // command that has an RTK equivalent should be substituted so RTK's filter
+    // applies inside the shell string.
+    //
+    // Example: "cargo test && git log"
+    //   Before: rtk run -c 'cargo test && git log'
+    //   After:  rtk run -c 'rtk cargo test && rtk git log'
+    //
+    // Safety invariant: only &&/||/; chains are substituted here.
+    // Pipe-separated commands are handled separately (split_safe_suffix / needs_shell).
+
+    #[test]
+    fn test_chain_both_commands_substituted() {
+        // Both cargo test AND git log should route to rtk inside the shell string
+        let result = match check_for_hook("cargo test && git log", "claude") {
+            HookResult::Rewrite(cmd) => cmd,
+            other => panic!("Expected Rewrite, got {:?}", other),
+        };
+        assert!(
+            result.contains("rtk cargo"),
+            "cargo test must be substituted to rtk cargo inside chain: {}",
+            result
+        );
+        assert!(
+            result.contains("rtk git"),
+            "git log must be substituted to rtk git inside chain: {}",
+            result
+        );
+        // The outer wrapper is rtk run -c because && needs a shell
+        assert!(
+            result.contains("rtk run"),
+            "chain still needs shell wrapper (rtk run -c): {}",
+            result
+        );
+    }
+
+    #[test]
+    fn test_chain_with_dollar_var_substituted() {
+        // cargo test && git log $BRANCH: $BRANCH is Arg (after lexer fix) → both route natively
+        let result = match check_for_hook("cargo test && git log $BRANCH", "claude") {
+            HookResult::Rewrite(cmd) => cmd,
+            other => panic!("Expected Rewrite, got {:?}", other),
+        };
+        assert!(
+            result.contains("rtk cargo"),
+            "cargo test must be rtk in chain: {}",
+            result
+        );
+        assert!(
+            result.contains("rtk git log"),
+            "git log $BRANCH must be rtk with var preserved: {}",
+            result
+        );
+        assert!(
+            result.contains("$BRANCH"),
+            "$BRANCH must be preserved in rewritten chain: {}",
+            result
+        );
+    }
+
+    #[test]
+    fn test_chain_unknown_command_not_substituted() {
+        // unknown_xyz_cmd not in registry → stays unmodified inside the shell string
+        let result = match check_for_hook("cargo test && unknown_xyz_cmd", "claude") {
+            HookResult::Rewrite(cmd) => cmd,
+            other => panic!("Expected Rewrite, got {:?}", other),
+        };
+        assert!(
+            result.contains("rtk cargo"),
+            "cargo test must be substituted to rtk: {}",
+            result
+        );
+        assert!(
+            result.contains("unknown_xyz_cmd"),
+            "unknown command must pass through unchanged: {}",
+            result
+        );
+        assert!(
+            !result.contains("rtk unknown"),
+            "must not invent rtk subcommands for unknown binary: {}",
+            result
+        );
+    }
+
+    #[test]
+    fn test_semicolon_chain_substituted() {
+        // ; chains: each known command should be substituted
+        let result = match check_for_hook("cargo test ; git status", "claude") {
+            HookResult::Rewrite(cmd) => cmd,
+            other => panic!("Expected Rewrite, got {:?}", other),
+        };
+        assert!(
+            result.contains("rtk cargo"),
+            "cargo must be rtk in semicolon chain: {}",
+            result
+        );
+        assert!(
+            result.contains("rtk git"),
+            "git must be rtk in semicolon chain: {}",
+            result
+        );
+    }
+
+    #[test]
+    fn test_or_chain_substituted() {
+        // || chains: each known command should be substituted
+        let result = match check_for_hook("cargo test || go test ./...", "claude") {
+            HookResult::Rewrite(cmd) => cmd,
+            other => panic!("Expected Rewrite, got {:?}", other),
+        };
+        assert!(
+            result.contains("rtk cargo"),
+            "cargo must be rtk in || chain: {}",
+            result
+        );
+        assert!(
+            result.contains("rtk go"),
+            "go must be rtk in || chain: {}",
+            result
+        );
+    }
+
+    // === PIPE OUTPUT CLASSIFICATION TESTS ===
+    // FORMAT_PRESERVING: commands whose RTK output format matches raw output,
+    //   making them safe as the left side of any pipe.
+    // TRANSPARENT_SINKS: right-side commands that consume any input format
+    //   (already handled by split_safe_suffix for routing purposes).
+    //
+    // These classification constants document the safety policy for future
+    // pipe-left substitution logic and must contain the expected entries.
+
+    #[test]
+    fn test_format_preserving_contains_expected() {
+        assert!(
+            FORMAT_PRESERVING.contains(&"tail"),
+            "tail is format-preserving (line-per-line passthrough)"
+        );
+        assert!(
+            FORMAT_PRESERVING.contains(&"echo"),
+            "echo is format-preserving (output equals input)"
+        );
+        assert!(
+            FORMAT_PRESERVING.contains(&"find"),
+            "find is format-preserving (path-per-line)"
+        );
+        assert!(
+            FORMAT_PRESERVING.contains(&"cat"),
+            "cat is format-preserving (byte passthrough)"
+        );
+    }
+
+    #[test]
+    fn test_format_changing_not_in_format_preserving() {
+        // Commands that transform output heavily must NOT be in FORMAT_PRESERVING.
+        // If substituted as left side of a semantic-sink pipe (grep, jq, awk),
+        // the right side would receive unexpected compressed format and break.
+        assert!(
+            !FORMAT_PRESERVING.contains(&"cargo"),
+            "cargo test compresses output — not format-preserving"
+        );
+        assert!(
+            !FORMAT_PRESERVING.contains(&"git"),
+            "git log/diff compresses output — not format-preserving"
+        );
+        assert!(
+            !FORMAT_PRESERVING.contains(&"pytest"),
+            "pytest compresses output — not format-preserving"
+        );
+        assert!(
+            !FORMAT_PRESERVING.contains(&"go"),
+            "go test compresses output — not format-preserving"
+        );
+    }
+
+    #[test]
+    fn test_transparent_sinks_contains_expected() {
+        // Transparent sinks accept any input format — already handled by split_safe_suffix.
+        assert!(
+            TRANSPARENT_SINKS.contains(&"tee"),
+            "tee is a transparent sink (copies stdin to file + stdout)"
+        );
+        assert!(
+            TRANSPARENT_SINKS.contains(&"head"),
+            "head is a transparent sink (truncates lines)"
+        );
+        assert!(
+            TRANSPARENT_SINKS.contains(&"cat"),
+            "cat is a transparent sink (passes through)"
+        );
+        assert!(
+            TRANSPARENT_SINKS.contains(&"tail"),
+            "tail is a transparent sink (last N lines)"
+        );
+    }
+
+    // ── End-to-end token savings tests ───────────────────────────────────────
+    // These tests simulate the full hook pipeline from the start:
+    //   raw command → check_for_hook (lexer + router) → rewritten rtk cmd
+    //   → execute both → compare token counts
+    //
+    // Run with: cargo test e2e -- --ignored
+    // Requires: `cargo install --path .` (rtk binary on PATH) + git repo
+
+    fn count_tokens(text: &str) -> usize {
+        text.split_whitespace().count()
+    }
+
+    fn exec(cmd: &str) -> String {
+        let parts: Vec<&str> = cmd.split_whitespace().collect();
+        let out = std::process::Command::new(parts[0])
+            .args(&parts[1..])
+            .output()
+            .unwrap_or_else(|e| panic!("failed to exec '{cmd}': {e}"));
+        String::from_utf8_lossy(&out.stdout).to_string()
+    }
+
+    #[test]
+    #[ignore = "requires installed rtk binary (cargo install --path .) and git repo"]
+    fn test_e2e_git_status_saves_tokens() {
+        // Step 1: route through the full hook pipeline (lexer → router)
+        let raw_cmd = "git status";
+        let rtk_cmd = match check_for_hook(raw_cmd, "claude") {
+            HookResult::Rewrite(cmd) => cmd,
+            other => panic!("Expected Rewrite for '{raw_cmd}', got {other:?}"),
+        };
+        assert!(
+            rtk_cmd.starts_with("rtk git"),
+            "lexer+router should produce rtk git status, got: {rtk_cmd}"
+        );
+
+        // Step 2: execute both and compare token counts
+        let raw_out = exec(raw_cmd);
+        let rtk_out = exec(&rtk_cmd);
+        let raw_tok = count_tokens(&raw_out);
+        let rtk_tok = count_tokens(&rtk_out);
+        assert!(raw_tok > 0, "raw git status produced no output");
+
+        let savings = 100.0 * (1.0 - rtk_tok as f64 / raw_tok as f64);
+        assert!(
+            savings >= 40.0,
+            "rtk git status should save ≥40% tokens vs raw git status, \
+             got {savings:.1}% ({raw_tok} raw → {rtk_tok} rtk tokens)"
+        );
+    }
+
+    #[test]
+    #[ignore = "requires installed rtk binary (cargo install --path .) and directory with files"]
+    fn test_e2e_ls_saves_tokens() {
+        // Step 1: route through the full hook pipeline (lexer → router)
+        let raw_cmd = "ls -la .";
+        let rtk_cmd = match check_for_hook(raw_cmd, "claude") {
+            HookResult::Rewrite(cmd) => cmd,
+            other => panic!("Expected Rewrite for '{raw_cmd}', got {other:?}"),
+        };
+        assert!(
+            rtk_cmd.starts_with("rtk ls"),
+            "lexer+router should produce rtk ls, got: {rtk_cmd}"
+        );
+
+        // Step 2: execute both and compare token counts
+        let raw_out = exec(raw_cmd);
+        let rtk_out = exec(&rtk_cmd);
+        let raw_tok = count_tokens(&raw_out);
+        let rtk_tok = count_tokens(&rtk_out);
+        assert!(raw_tok > 0, "raw ls -la produced no output");
+
+        let savings = 100.0 * (1.0 - rtk_tok as f64 / raw_tok as f64);
+        assert!(
+            savings >= 40.0,
+            "rtk ls should save ≥40% tokens vs raw ls -la, \
+             got {savings:.1}% ({raw_tok} raw → {rtk_tok} rtk tokens)"
+        );
+    }
+
+    #[test]
+    #[ignore = "requires installed rtk binary (cargo install --path .) and git repo with history"]
+    fn test_e2e_git_log_saves_tokens() {
+        // Step 1: route through the full hook pipeline (lexer → router)
+        let raw_cmd = "git log --oneline -20";
+        let rtk_cmd = match check_for_hook(raw_cmd, "claude") {
+            HookResult::Rewrite(cmd) => cmd,
+            other => panic!("Expected Rewrite for '{raw_cmd}', got {other:?}"),
+        };
+        assert!(
+            rtk_cmd.starts_with("rtk git"),
+            "lexer+router should produce rtk git log, got: {rtk_cmd}"
+        );
+
+        // Step 2: execute both and compare token counts
+        let raw_out = exec(raw_cmd);
+        let rtk_out = exec(&rtk_cmd);
+        let raw_tok = count_tokens(&raw_out);
+        let rtk_tok = count_tokens(&rtk_out);
+        assert!(
+            raw_tok > 0,
+            "raw git log produced no output — need a repo with commits"
+        );
+
+        // git log --oneline is already compact; rtk may not save much beyond
+        // line-length capping.  Truncating long lines with "..." can add a
+        // marginal token.  Allow ≤5% overhead to account for this artefact.
+        let ratio = rtk_tok as f64 / raw_tok.max(1) as f64;
+        assert!(
+            ratio <= 1.05,
+            "rtk git log must not significantly bloat output vs raw git log \
+             ({raw_tok} raw → {rtk_tok} rtk, ratio {ratio:.2})"
+        );
+    }
+
+    // === CAT BEHAVIOR TESTS ===
+    // Note: this branch does NOT include the data-safety rules system (that's in
+    // feat/multi-platform-hooks). Without safety rules, cat hits the defensive
+    // fallback in route_native_command() and rewrites to rtk read.
+    // In feat/multi-platform-hooks, cat is Blocked by src/rules/rtk.safety.block-cat.md.
+
+    #[test]
+    fn test_cat_multi_file_rewrites_to_rtk_read() {
+        // Without safety rules, cat→rtk read fallback fires for all arities.
+        let result = check_for_hook("cat file1.txt file2.txt", "claude");
+        assert!(
+            matches!(&result, HookResult::Rewrite(s) if s == "rtk read file1.txt file2.txt"),
+            "cat (multi-file) must rewrite to rtk read on this branch; got: {:?}",
+            result
+        );
+    }
+
+    #[test]
+    fn test_cat_single_file_rewrites_to_rtk_read() {
+        // Same fallback applies for single-file cat — no special-casing by arity.
+        let result = check_for_hook("cat CLAUDE.md", "claude");
+        assert!(
+            matches!(&result, HookResult::Rewrite(s) if s == "rtk read CLAUDE.md"),
+            "cat (single-file) must rewrite to rtk read on this branch; got: {:?}",
+            result
+        );
+    }
+    // --- #196: gh --json/--jq/--template passthrough ---
+
+    #[test]
+    fn test_gh_json_flag_passes_through() {
+        // gh --json produces structured JSON that rtk gh would corrupt
+        assert!(should_passthrough("gh pr list --json number,title"));
+        assert!(should_passthrough(
+            "gh pr list --json number --jq '.[].number'"
+        ));
+        assert!(should_passthrough("gh pr view 42 --template '{{.title}}'"));
+        assert!(should_passthrough("gh api repos/owner/repo --jq '.name'"));
+    }
+
+    #[test]
+    fn test_gh_without_json_not_passthrough() {
+        // gh without structured output flags → still eligible for rewriting
+        assert!(!should_passthrough("gh pr list"));
+        assert!(!should_passthrough("gh issue list"));
+    }
+
+    // === HOOK_LOOKUP: git branch/worktree ===
+
+    #[test]
+    fn test_hook_lookup_git_branch() {
+        assert_eq!(hook_lookup("git", "branch"), Some(("rtk git", "git")));
+    }
+
+    #[test]
+    fn test_hook_lookup_git_worktree() {
+        assert_eq!(hook_lookup("git", "worktree"), Some(("rtk git", "git")));
+    }
+
+    #[test]
+    fn test_git_branch_routes_via_hook() {
+        assert_rewrite("git branch", "rtk git branch");
+    }
+
+    #[test]
+    fn test_git_worktree_list_routes_via_hook() {
+        assert_rewrite("git worktree list", "rtk git worktree");
+    }
+}
diff --git a/src/cmd/lexer.rs b/src/cmd/lexer.rs
new file mode 100644
index 000000000..60404e950
--- /dev/null
+++ b/src/cmd/lexer.rs
@@ -0,0 +1,718 @@
+//! State-machine lexer that respects quotes and escapes.
+//! Critical: `git commit -m "Fix && Bug"` must NOT split on &&
+
+#[derive(Debug, PartialEq, Clone)]
+pub enum TokenKind {
+    Arg,      // Regular argument
+    Operator, // &&, ||, ;
+    Pipe,     // |
+    Redirect, // >, >>, <, 2>
+    Shellism, // *, ?, `, (, ), {, }, !, & — forces passthrough; $ only for complex forms
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct ParsedToken {
+    pub kind: TokenKind,
+    pub value: String, // The actual string value
+    pub offset: usize, // Byte offset in the original input
+}
+
+/// Tokenize input with quote awareness.
+/// Returns Vec of parsed tokens with byte offsets into the original input.
+pub fn tokenize(input: &str) -> Vec<ParsedToken> {
+    let mut tokens = Vec::new();
+    let mut current = String::new();
+    let mut current_start: usize = 0; // byte offset where current token started
+    let mut byte_pos: usize = 0; // current byte position in input
+    let mut chars = input.chars().peekable();
+
+    let mut quote: Option<char> = None; // None, Some('\''), Some('"')
+    let mut escaped = false;
+
+    while let Some(c) = chars.next() {
+        let char_len = c.len_utf8();
+
+        // Handle escape sequences (but NOT inside single quotes)
+        if escaped {
+            current.push(c);
+            byte_pos += char_len;
+            escaped = false;
+            continue;
+        }
+        if c == '\\' && quote != Some('\'') {
+            escaped = true;
+            if current.is_empty() {
+                current_start = byte_pos;
+            }
+            current.push(c);
+            byte_pos += char_len;
+            continue;
+        }
+
+        // Handle quotes
+        if let Some(q) = quote {
+            if c == q {
+                quote = None; // Close quote
+            }
+            current.push(c);
+            byte_pos += char_len;
+            continue;
+        }
+        if c == '\'' || c == '"' {
+            quote = Some(c);
+            if current.is_empty() {
+                current_start = byte_pos;
+            }
+            current.push(c);
+            byte_pos += char_len;
+            continue;
+        }
+
+        // Outside quotes - handle operators and shellisms
+        match c {
+            // '$' handling: simple $IDENT forms become Arg tokens.
+            // The shell expands them when executing the rewritten "rtk cmd $VAR" —
+            // RTK itself never needs to expand variables.
+            // Complex forms ($(), ${}, $?, $$, $!, $0–$9) remain Shellism.
+            '$' => {
+                flush_arg(&mut tokens, &mut current, current_start);
+                let dollar_pos = byte_pos;
+                byte_pos += char_len;
+                // Peek at the next char: alphabetic or '_' → consume a $IDENT as Arg.
+                // Digits and special chars → Shellism (positional/special variables).
+                if chars
+                    .peek()
+                    .is_some_and(|&nc| nc.is_ascii_alphabetic() || nc == '_')
+                {
+                    let mut name = String::from("$");
+                    while chars
+                        .peek()
+                        .is_some_and(|&nc| nc.is_ascii_alphanumeric() || nc == '_')
+                    {
+                        let nc = chars.next().unwrap();
+                        byte_pos += nc.len_utf8();
+                        name.push(nc);
+                    }
+                    tokens.push(ParsedToken {
+                        kind: TokenKind::Arg,
+                        value: name,
+                        offset: dollar_pos,
+                    });
+                } else {
+                    // $(), ${}, $?, $$, $!, $1, bare $ — all need real shell
+                    tokens.push(ParsedToken {
+                        kind: TokenKind::Shellism,
+                        value: "$".to_string(),
+                        offset: dollar_pos,
+                    });
+                }
+                current_start = byte_pos;
+            }
+            // Remaining shellisms force passthrough (includes ! for history expansion/negation)
+            '*' | '?' | '`' | '(' | ')' | '{' | '}' | '!' => {
+                flush_arg(&mut tokens, &mut current, current_start);
+                tokens.push(ParsedToken {
+                    kind: TokenKind::Shellism,
+                    value: c.to_string(),
+                    offset: byte_pos,
+                });
+                byte_pos += char_len;
+                current_start = byte_pos;
+            }
+            // Operators
+            '&' | '|' | ';' | '>' | '<' => {
+                flush_arg(&mut tokens, &mut current, current_start);
+                let op_start = byte_pos;
+                byte_pos += char_len;
+
+                let mut op = c.to_string();
+                // Lookahead for double-char operators
+                if let Some(&next) = chars.peek() {
+                    if (next == c && c != ';' && c != '<') || (c == '>' && next == '>') {
+                        byte_pos += next.len_utf8();
+                        op.push(chars.next().unwrap());
+                    }
+                }
+
+                let kind = match op.as_str() {
+                    "&&" | "||" | ";" => TokenKind::Operator,
+                    "|" => TokenKind::Pipe,
+                    "&" => TokenKind::Shellism, // Background job needs real shell
+                    _ => TokenKind::Redirect,
+                };
+                tokens.push(ParsedToken {
+                    kind,
+                    value: op,
+                    offset: op_start,
+                });
+                current_start = byte_pos;
+            }
+            // Whitespace delimits arguments
+            c if c.is_whitespace() => {
+                flush_arg(&mut tokens, &mut current, current_start);
+                byte_pos += c.len_utf8();
+                current_start = byte_pos;
+            }
+            // Regular character
+            _ => {
+                if current.is_empty() {
+                    current_start = byte_pos;
+                }
+                current.push(c);
+                byte_pos += char_len;
+            }
+        }
+    }
+
+    // Handle unclosed quote (treat remaining as arg, don't panic)
+    flush_arg(&mut tokens, &mut current, current_start);
+    tokens
+}
+
+fn flush_arg(tokens: &mut Vec<ParsedToken>, current: &mut String, offset: usize) {
+    let trimmed = current.trim();
+    if !trimmed.is_empty() {
+        // Adjust offset for leading whitespace that was trimmed
+        let leading_ws = current.len() - current.trim_start().len();
+        tokens.push(ParsedToken {
+            kind: TokenKind::Arg,
+            value: trimmed.to_string(),
+            offset: offset + leading_ws,
+        });
+    }
+    current.clear();
+}
+
+/// Strip quotes from a token value
+pub fn strip_quotes(s: &str) -> String {
+    let chars: Vec<char> = s.chars().collect();
+    if chars.len() >= 2
+        && ((chars[0] == '"' && chars[chars.len() - 1] == '"')
+            || (chars[0] == '\'' && chars[chars.len() - 1] == '\''))
+    {
+        return chars[1..chars.len() - 1].iter().collect();
+    }
+    s.to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // === BASIC FUNCTIONALITY TESTS ===
+
+    #[test]
+    fn test_simple_command() {
+        let tokens = tokenize("git status");
+        assert_eq!(tokens.len(), 2);
+        assert_eq!(tokens[0].kind, TokenKind::Arg);
+        assert_eq!(tokens[0].value, "git");
+        assert_eq!(tokens[1].value, "status");
+    }
+
+    #[test]
+    fn test_command_with_args() {
+        let tokens = tokenize("git commit -m message");
+        assert_eq!(tokens.len(), 4);
+        assert_eq!(tokens[0].value, "git");
+        assert_eq!(tokens[1].value, "commit");
+        assert_eq!(tokens[2].value, "-m");
+        assert_eq!(tokens[3].value, "message");
+    }
+
+    // === QUOTE HANDLING TESTS ===
+
+    #[test]
+    fn test_quoted_operator_not_split() {
+        let tokens = tokenize(r#"git commit -m "Fix && Bug""#);
+        // && inside quotes should NOT be an Operator token
+        assert!(!tokens
+            .iter()
+            .any(|t| matches!(t.kind, TokenKind::Operator) && t.value == "&&"));
+        assert!(tokens.iter().any(|t| t.value.contains("Fix && Bug")));
+    }
+
+    #[test]
+    fn test_single_quoted_string() {
+        let tokens = tokenize("echo 'hello world'");
+        assert!(tokens.iter().any(|t| t.value == "'hello world'"));
+    }
+
+    #[test]
+    fn test_double_quoted_string() {
+        let tokens = tokenize("echo \"hello world\"");
+        assert!(tokens.iter().any(|t| t.value == "\"hello world\""));
+    }
+
+    #[test]
+    fn test_empty_quoted_string() {
+        let tokens = tokenize("echo \"\"");
+        // Should have echo and ""
+        assert!(tokens.iter().any(|t| t.value == "\"\""));
+    }
+
+    #[test]
+    fn test_nested_quotes() {
+        let tokens = tokenize(r#"echo "outer 'inner' outer""#);
+        assert!(tokens.iter().any(|t| t.value.contains("'inner'")));
+    }
+
+    #[test]
+    fn test_strip_quotes_double() {
+        assert_eq!(strip_quotes("\"hello\""), "hello");
+    }
+
+    #[test]
+    fn test_strip_quotes_single() {
+        assert_eq!(strip_quotes("'hello'"), "hello");
+    }
+
+    #[test]
+    fn test_strip_quotes_none() {
+        assert_eq!(strip_quotes("hello"), "hello");
+    }
+
+    #[test]
+    fn test_strip_quotes_mismatched() {
+        assert_eq!(strip_quotes("\"hello'"), "\"hello'");
+    }
+
+    // === ESCAPE HANDLING TESTS ===
+
+    #[test]
+    fn test_escaped_space() {
+        let tokens = tokenize("echo hello\\ world");
+        // Escaped space should be part of the arg
+        assert!(tokens.iter().any(|t| t.value.contains("hello")));
+    }
+
+    #[test]
+    fn test_backslash_in_single_quotes() {
+        // In single quotes, backslash is literal
+        let tokens = tokenize(r#"echo 'hello\nworld'"#);
+        assert!(tokens.iter().any(|t| t.value.contains(r#"\n"#)));
+    }
+
+    #[test]
+    fn test_escaped_quote_in_double() {
+        let tokens = tokenize(r#"echo "hello\"world""#);
+        assert!(tokens.iter().any(|t| t.value.contains("hello")));
+    }
+
+    // === EDGE CASE TESTS ===
+
+    #[test]
+    fn test_empty_input() {
+        let tokens = tokenize("");
+        assert!(tokens.is_empty());
+    }
+
+    #[test]
+    fn test_whitespace_only() {
+        let tokens = tokenize("   ");
+        assert!(tokens.is_empty());
+    }
+
+    #[test]
+    fn test_unclosed_single_quote() {
+        // Should not panic, treat remaining as part of arg
+        let tokens = tokenize("'unclosed");
+        assert!(!tokens.is_empty());
+    }
+
+    #[test]
+    fn test_unclosed_double_quote() {
+        // Should not panic, treat remaining as part of arg
+        let tokens = tokenize("\"unclosed");
+        assert!(!tokens.is_empty());
+    }
+
+    #[test]
+    fn test_unicode_preservation() {
+        let tokens = tokenize("echo \"héllo wörld\"");
+        assert!(tokens.iter().any(|t| t.value.contains("héllo")));
+    }
+
+    #[test]
+    fn test_multiple_spaces() {
+        let tokens = tokenize("git   status");
+        assert_eq!(tokens.len(), 2);
+    }
+
+    #[test]
+    fn test_leading_trailing_spaces() {
+        let tokens = tokenize("  git status  ");
+        assert_eq!(tokens.len(), 2);
+    }
+
+    // === OPERATOR TESTS ===
+
+    #[test]
+    fn test_and_operator() {
+        let tokens = tokenize("cmd1 && cmd2");
+        assert!(tokens
+            .iter()
+            .any(|t| matches!(t.kind, TokenKind::Operator) && t.value == "&&"));
+    }
+
+    #[test]
+    fn test_or_operator() {
+        let tokens = tokenize("cmd1 || cmd2");
+        assert!(tokens
+            .iter()
+            .any(|t| matches!(t.kind, TokenKind::Operator) && t.value == "||"));
+    }
+
+    #[test]
+    fn test_semicolon() {
+        let tokens = tokenize("cmd1 ; cmd2");
+        assert!(tokens
+            .iter()
+            .any(|t| matches!(t.kind, TokenKind::Operator) && t.value == ";"));
+    }
+
+    #[test]
+    fn test_multiple_and() {
+        let tokens = tokenize("a && b && c");
+        let ops: Vec<_> = tokens
+            .iter()
+            .filter(|t| matches!(t.kind, TokenKind::Operator))
+            .collect();
+        assert_eq!(ops.len(), 2);
+    }
+
+    #[test]
+    fn test_mixed_operators() {
+        let tokens = tokenize("a && b || c");
+        let ops: Vec<_> = tokens
+            .iter()
+            .filter(|t| matches!(t.kind, TokenKind::Operator))
+            .collect();
+        assert_eq!(ops.len(), 2);
+    }
+
+    #[test]
+    fn test_operator_at_start() {
+        let tokens = tokenize("&& cmd");
+        // Should still parse, just with operator first
+        assert!(tokens.iter().any(|t| t.value == "&&"));
+    }
+
+    #[test]
+    fn test_operator_at_end() {
+        let tokens = tokenize("cmd &&");
+        assert!(tokens.iter().any(|t| t.value == "&&"));
+    }
+
+    // === PIPE TESTS ===
+
+    #[test]
+    fn test_pipe_detection() {
+        let tokens = tokenize("cat file | grep pattern");
+        assert!(tokens.iter().any(|t| matches!(t.kind, TokenKind::Pipe)));
+    }
+
+    #[test]
+    fn test_quoted_pipe_not_pipe() {
+        let tokens = tokenize("\"a|b\"");
+        // Pipe inside quotes is not a Pipe token
+        assert!(!tokens.iter().any(|t| matches!(t.kind, TokenKind::Pipe)));
+    }
+
+    #[test]
+    fn test_multiple_pipes() {
+        let tokens = tokenize("a | b | c");
+        let pipes: Vec<_> = tokens
+            .iter()
+            .filter(|t| matches!(t.kind, TokenKind::Pipe))
+            .collect();
+        assert_eq!(pipes.len(), 2);
+    }
+
+    // === SHELLISM TESTS ===
+
+    #[test]
+    fn test_glob_detection() {
+        let tokens = tokenize("ls *.rs");
+        assert!(tokens.iter().any(|t| matches!(t.kind, TokenKind::Shellism)));
+    }
+
+    #[test]
+    fn test_quoted_glob_not_shellism() {
+        let tokens = tokenize("echo \"*.txt\"");
+        // Glob inside quotes is not a Shellism token
+        assert!(!tokens.iter().any(|t| matches!(t.kind, TokenKind::Shellism)));
+    }
+
+    // === $VAR HANDLING TESTS ===
+    // Simple $IDENT forms are Arg (shell expands at execution time when running
+    // the rewritten "rtk cmd $VAR" command).  Complex forms ($(), ${}, $?, $$,
+    // $!, $0–$9) remain Shellism and force passthrough to the real shell.
+
+    #[test]
+    fn test_simple_var_is_arg() {
+        // $HOME after space → Arg("$HOME"), NOT Shellism.
+        // The shell expands it when executing the rewritten "rtk cmd $HOME" — RTK does not.
+        let tokens = tokenize("echo $HOME");
+        assert!(
+            tokens
+                .iter()
+                .any(|t| matches!(t.kind, TokenKind::Arg) && t.value == "$HOME"),
+            "Simple $VAR must be Arg, not Shellism — shell expands at execution time"
+        );
+        assert!(
+            !tokens.iter().any(|t| matches!(t.kind, TokenKind::Shellism)),
+            "No Shellism token expected for simple $VAR"
+        );
+    }
+
+    #[test]
+    fn test_simple_var_enables_native_routing() {
+        // git log $BRANCH: no Shellism → needs_shell()=false → can route to rtk git
+        let tokens = tokenize("git log $BRANCH");
+        assert!(
+            !tokens.iter().any(|t| matches!(t.kind, TokenKind::Shellism)),
+            "git log $BRANCH must have no Shellism — simple $VAR is Arg, not Shellism"
+        );
+    }
+
+    #[test]
+    fn test_dollar_subshell_stays_shellism() {
+        // $() needs real shell for command substitution
+        let tokens = tokenize("echo $(date)");
+        assert!(
+            tokens.iter().any(|t| matches!(t.kind, TokenKind::Shellism)),
+            "$(cmd) must produce Shellism — command substitution needs shell"
+        );
+    }
+
+    #[test]
+    fn test_dollar_brace_stays_shellism() {
+        // ${VAR} needs real shell (complex expansion / parameter substitution)
+        let tokens = tokenize("echo ${HOME}");
+        assert!(
+            tokens.iter().any(|t| matches!(t.kind, TokenKind::Shellism)),
+            "${{VAR}} must produce Shellism — brace expansion needs shell"
+        );
+    }
+
+    #[test]
+    fn test_dollar_special_vars_stay_shellism() {
+        // $? $$ $! are special variables — not simple identifiers
+        for s in &["echo $?", "echo $$", "echo $!"] {
+            let tokens = tokenize(s);
+            assert!(
+                tokens.iter().any(|t| matches!(t.kind, TokenKind::Shellism)),
+                "{} should produce Shellism — special var needs shell",
+                s
+            );
+        }
+    }
+
+    #[test]
+    fn test_dollar_digit_stays_shellism() {
+        // $0–$9 are positional parameters — leave to shell
+        let tokens = tokenize("echo $1");
+        assert!(
+            tokens.iter().any(|t| matches!(t.kind, TokenKind::Shellism)),
+            "$1 (positional parameter) must be Shellism — handled by shell"
+        );
+    }
+
+    #[test]
+    fn test_quoted_variable_not_shellism() {
+        let tokens = tokenize("echo \"$HOME\"");
+        // $ inside double quotes is NOT detected as a Shellism token
+        // because the lexer respects quotes
+        // This is correct - the variable can't be expanded by us anyway
+        // so the whole command will need to passthrough to shell
+        // But at the tokenization level, it's not a Shellism
+        assert!(!tokens.iter().any(|t| matches!(t.kind, TokenKind::Shellism)));
+    }
+
+    #[test]
+    fn test_backtick_substitution() {
+        let tokens = tokenize("echo `date`");
+        assert!(tokens.iter().any(|t| matches!(t.kind, TokenKind::Shellism)));
+    }
+
+    #[test]
+    fn test_subshell_detection() {
+        let tokens = tokenize("echo $(date)");
+        // Both $ and ( should be shellisms
+        let shellisms: Vec<_> = tokens
+            .iter()
+            .filter(|t| matches!(t.kind, TokenKind::Shellism))
+            .collect();
+        assert!(!shellisms.is_empty());
+    }
+
+    #[test]
+    fn test_brace_expansion() {
+        let tokens = tokenize("echo {a,b}.txt");
+        assert!(tokens.iter().any(|t| matches!(t.kind, TokenKind::Shellism)));
+    }
+
+    #[test]
+    fn test_escaped_glob() {
+        let tokens = tokenize("echo \\*.txt");
+        // Escaped glob should not be a shellism
+        assert!(!tokens
+            .iter()
+            .any(|t| matches!(t.kind, TokenKind::Shellism) && t.value == "*"));
+    }
+
+    // === REDIRECT TESTS ===
+
+    #[test]
+    fn test_redirect_out() {
+        let tokens = tokenize("cmd > file");
+        assert!(tokens.iter().any(|t| matches!(t.kind, TokenKind::Redirect)));
+    }
+
+    #[test]
+    fn test_redirect_append() {
+        let tokens = tokenize("cmd >> file");
+        assert!(tokens
+            .iter()
+            .any(|t| matches!(t.kind, TokenKind::Redirect) && t.value == ">>"));
+    }
+
+    #[test]
+    fn test_redirect_in() {
+        let tokens = tokenize("cmd < file");
+        assert!(tokens.iter().any(|t| matches!(t.kind, TokenKind::Redirect)));
+    }
+
+    #[test]
+    fn test_redirect_stderr() {
+        let tokens = tokenize("cmd 2> file");
+        assert!(tokens.iter().any(|t| matches!(t.kind, TokenKind::Redirect)));
+    }
+
+    #[test]
+    fn test_redirect_stderr_no_space() {
+        // "2>/dev/null" — the lexer flushes "2" as Arg then creates Redirect(">").
+        // Both a Redirect token AND an Arg("2") must be present.
+        let tokens = tokenize("cmd 2>/dev/null");
+        assert!(
+            tokens.iter().any(|t| matches!(t.kind, TokenKind::Redirect)),
+            "2>/dev/null must produce a Redirect token (needs_shell must fire)"
+        );
+        // "2" appears as a separate Arg preceding the redirect
+        assert!(
+            tokens
+                .iter()
+                .any(|t| matches!(t.kind, TokenKind::Arg) && t.value == "2"),
+            "2 in 2>/dev/null must be a separate Arg token"
+        );
+    }
+
+    #[test]
+    fn test_redirect_dev_null() {
+        let tokens = tokenize("cmd > /dev/null");
+        assert!(
+            tokens
+                .iter()
+                .any(|t| matches!(t.kind, TokenKind::Redirect) && t.value == ">"),
+            ">/dev/null must produce a > Redirect token"
+        );
+    }
+
+    #[test]
+    fn test_compound_fd_redirect_2_to_1_has_shellism() {
+        // "2>&1" tokenises as: Arg("2"), Redirect(">"), Shellism("&"), Arg("1")
+        // The & in the middle is what forces shell passthrough via needs_shell().
+        let tokens = tokenize("cmd 2>&1");
+        assert!(
+            tokens
+                .iter()
+                .any(|t| matches!(t.kind, TokenKind::Shellism) && t.value == "&"),
+            "& in 2>&1 must be Shellism — this is what triggers needs_shell"
+        );
+        assert!(
+            tokens
+                .iter()
+                .any(|t| matches!(t.kind, TokenKind::Redirect) && t.value == ">"),
+            "> in 2>&1 must be a Redirect token"
+        );
+        // The "2" is a bare Arg before the redirect
+        assert!(
+            tokens
+                .iter()
+                .any(|t| matches!(t.kind, TokenKind::Arg) && t.value == "2"),
+            "2 in 2>&1 must be a separate Arg token"
+        );
+    }
+
+    #[test]
+    fn test_compound_fd_redirect_1_to_2_has_shellism() {
+        // "1>&2" — same pattern as 2>&1
+        let tokens = tokenize("cmd 1>&2");
+        assert!(
+            tokens
+                .iter()
+                .any(|t| matches!(t.kind, TokenKind::Shellism) && t.value == "&"),
+            "& in 1>&2 must be Shellism"
+        );
+        assert!(
+            tokens.iter().any(|t| matches!(t.kind, TokenKind::Redirect)),
+            "1>&2 must produce a Redirect token"
+        );
+    }
+
+    #[test]
+    fn test_combined_redirect_chain() {
+        // ">/dev/null 2>&1": > Redirect, then Arg("2"), >, &(Shellism)
+        let tokens = tokenize("cmd > /dev/null 2>&1");
+        assert!(
+            tokens
+                .iter()
+                .any(|t| matches!(t.kind, TokenKind::Redirect) && t.value == ">"),
+            "Must have > Redirect"
+        );
+        assert!(
+            tokens
+                .iter()
+                .any(|t| matches!(t.kind, TokenKind::Shellism) && t.value == "&"),
+            "Must have & Shellism from 2>&1"
+        );
+    }
+
+    #[test]
+    fn test_redirect_append_to_file() {
+        let tokens = tokenize("echo hello >> /tmp/output.txt");
+        assert!(
+            tokens
+                .iter()
+                .any(|t| matches!(t.kind, TokenKind::Redirect) && t.value == ">>"),
+            ">> must produce a >> Redirect token"
+        );
+    }
+
+    // === EXCLAMATION / NEGATION TESTS ===
+
+    #[test]
+    fn test_exclamation_is_shellism() {
+        let tokens = tokenize("if ! grep -q pattern file; then echo missing; fi");
+        assert!(
+            tokens
+                .iter()
+                .any(|t| matches!(t.kind, TokenKind::Shellism) && t.value == "!"),
+            "! (negation) must be Shellism"
+        );
+    }
+
+    // === BACKGROUND JOB TESTS ===
+
+    #[test]
+    fn test_background_job_is_shellism() {
+        let tokens = tokenize("sleep 10 &");
+        assert!(
+            tokens
+                .iter()
+                .any(|t| matches!(t.kind, TokenKind::Shellism) && t.value == "&"),
+            "Single & (background job) must be Shellism, not Redirect"
+        );
+    }
+}
diff --git a/src/cmd/mod.rs b/src/cmd/mod.rs
new file mode 100644
index 000000000..9d339860f
--- /dev/null
+++ b/src/cmd/mod.rs
@@ -0,0 +1,30 @@
+//! Command execution subsystem for RTK hook integration.
+//!
+//! This module provides the core hook engine that powers `rtk hook claude`.
+//! It handles chained command rewriting, native command execution, and output filtering.
+
+// Analysis and lexing (no external deps)
+pub(crate) mod analysis;
+pub(crate) mod lexer;
+
+// Predicates and utilities (no external deps)
+pub(crate) mod predicates;
+
+// Builtins (depends on predicates)
+pub(crate) mod builtins;
+
+// Filters (depends on crate::utils)
+pub(crate) mod filters;
+
+// Exec (depends on analysis, builtins, filters, lexer)
+pub mod exec;
+
+// Hook logic + LLM protocol adapters (hook/mod.rs, hook/claude.rs)
+pub mod hook;
+
+#[cfg(test)]
+pub(crate) mod test_helpers;
+
+// Public exports
+pub use exec::execute;
+pub use hook::check_for_hook;
diff --git a/src/cmd/predicates.rs b/src/cmd/predicates.rs
new file mode 100644
index 000000000..f6b6fef85
--- /dev/null
+++ b/src/cmd/predicates.rs
@@ -0,0 +1,94 @@
+//! Context-aware predicates for conditional safety rules.
+//! These give RTK "situational awareness" - checking git state, file existence, etc.
+
+use std::process::Command;
+
+/// Check if there are unstaged changes in the current git repo
+pub(crate) fn has_unstaged_changes() -> bool {
+    Command::new("git")
+        .args(["diff", "--quiet"])
+        .status()
+        .map(|s| !s.success()) // git diff --quiet returns 1 if changes exist
+        .unwrap_or(false)
+}
+
+/// Critical for token reduction: detect if output goes to human or agent
+pub(crate) fn is_interactive() -> bool {
+    use std::io::IsTerminal;
+    std::io::stderr().is_terminal()
+}
+
+/// Expand ~ to $HOME, with fallback
+pub(crate) fn expand_tilde(path: &str) -> String {
+    if path.starts_with("~") {
+        // Try HOME first, then USERPROFILE (Windows)
+        let home = std::env::var("HOME")
+            .or_else(|_| std::env::var("USERPROFILE"))
+            .unwrap_or_else(|_| "/".to_string());
+        path.replacen("~", &home, 1)
+    } else {
+        path.to_string()
+    }
+}
+
+/// Get HOME directory with fallback
+pub(crate) fn get_home() -> String {
+    std::env::var("HOME")
+        .or_else(|_| std::env::var("USERPROFILE"))
+        .unwrap_or_else(|_| "/".to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::env;
+
+    // === PATH EXPANSION TESTS ===
+
+    #[test]
+    fn test_expand_tilde_simple() {
+        let home = env::var("HOME").unwrap_or("/".to_string());
+        assert_eq!(expand_tilde("~/src"), format!("{}/src", home));
+    }
+
+    #[test]
+    fn test_expand_tilde_no_tilde() {
+        assert_eq!(expand_tilde("/absolute/path"), "/absolute/path");
+    }
+
+    #[test]
+    fn test_expand_tilde_only_tilde() {
+        let home = env::var("HOME").unwrap_or("/".to_string());
+        assert_eq!(expand_tilde("~"), home);
+    }
+
+    #[test]
+    fn test_expand_tilde_relative() {
+        assert_eq!(expand_tilde("relative/path"), "relative/path");
+    }
+
+    // === HOME DIRECTORY TESTS ===
+
+    #[test]
+    fn test_get_home_returns_something() {
+        let home = get_home();
+        assert!(!home.is_empty());
+    }
+
+    // === INTERACTIVE TESTS ===
+
+    #[test]
+    fn test_is_interactive_returns_false_in_tests() {
+        // When running under cargo test, stderr is not a terminal
+        assert!(!is_interactive(), "Tests should report non-interactive");
+    }
+
+    // === GIT PREDICATE TESTS ===
+
+    #[test]
+    fn test_has_unstaged_changes_does_not_panic() {
+        // In a git repo, this should return a valid bool (not panic).
+        // The actual value depends on repo state.
+        let _result: bool = has_unstaged_changes();
+    }
+}
diff --git a/src/cmd/test_helpers.rs b/src/cmd/test_helpers.rs
new file mode 100644
index 000000000..8d6d11687
--- /dev/null
+++ b/src/cmd/test_helpers.rs
@@ -0,0 +1,36 @@
+//! Shared test utilities for the cmd module.
+
+use std::sync::{Mutex, MutexGuard, OnceLock};
+
+static ENV_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+
+/// RAII guard that serializes env-var-mutating tests and auto-cleans on drop.
+/// Prevents race conditions between parallel test threads and ensures cleanup
+/// even if a test panics.
+pub struct EnvGuard {
+    _lock: MutexGuard<'static, ()>,
+}
+
+impl EnvGuard {
+    pub fn new() -> Self {
+        let lock = ENV_LOCK
+            .get_or_init(|| Mutex::new(()))
+            .lock()
+            .unwrap_or_else(|e| e.into_inner());
+        Self::cleanup();
+        Self { _lock: lock }
+    }
+
+    fn cleanup() {
+        std::env::remove_var("RTK_SAFE_COMMANDS");
+        std::env::remove_var("RTK_BLOCK_TOKEN_WASTE");
+        std::env::remove_var("RTK_ACTIVE");
+        std::env::remove_var("RTK_DB_PATH");
+    }
+}
+
+impl Drop for EnvGuard {
+    fn drop(&mut self) {
+        Self::cleanup();
+    }
+}
diff --git a/src/discover/registry.rs b/src/discover/registry.rs
index d04a112a1..8d0285fcb 100644
--- a/src/discover/registry.rs
+++ b/src/discover/registry.rs
@@ -2,6 +2,7 @@ use lazy_static::lazy_static;
 use regex::{Regex, RegexSet};
 
 use super::rules::{IGNORED_EXACT, IGNORED_PREFIXES, PATTERNS, RULES};
+use crate::cmd::lexer::{tokenize, TokenKind};
 
 /// Result of classifying a command.
 #[derive(Debug, PartialEq)]
@@ -360,93 +361,90 @@ pub fn rewrite_command(cmd: &str, excluded: &[String]) -> Option<String> {
     rewrite_compound(trimmed, excluded)
 }
 
-/// Rewrite a compound command (with `&&`, `||`, `;`, `|`) by rewriting each segment.
+/// Rewrite a compound command (with `&&`, `||`, `;`, `|`, `&`) by rewriting each segment.
+///
+/// Uses `cmd::lexer::tokenize()` for quote-aware operator detection, then extracts
+/// original substrings by byte offset for each segment. This handles edge cases the
+/// old byte scanner missed: escape sequences, `$()` / backtick detection, glob detection,
+/// and proper redirect parsing (e.g. `2>&1` not confused with `&&`).
 fn rewrite_compound(cmd: &str, excluded: &[String]) -> Option<String> {
-    let bytes = cmd.as_bytes();
-    let len = bytes.len();
-    let mut result = String::with_capacity(len + 32);
+    let tokens = tokenize(cmd);
+    let mut result = String::with_capacity(cmd.len() + 32);
     let mut any_changed = false;
-    let mut seg_start = 0;
-    let mut i = 0;
-    let mut in_single = false;
-    let mut in_double = false;
 
-    while i < len {
-        let b = bytes[i];
-        match b {
-            b'\'' if !in_double => {
-                in_single = !in_single;
-                i += 1;
-            }
-            b'"' if !in_single => {
-                in_double = !in_double;
-                i += 1;
-            }
-            b'|' if !in_single && !in_double => {
-                if i + 1 < len && bytes[i + 1] == b'|' {
-                    // `||` operator — rewrite left, continue
-                    let seg = cmd[seg_start..i].trim();
-                    let rewritten =
-                        rewrite_segment(seg, excluded).unwrap_or_else(|| seg.to_string());
-                    if rewritten != seg {
-                        any_changed = true;
-                    }
-                    result.push_str(&rewritten);
-                    result.push_str(" || ");
-                    i += 2;
-                    while i < len && bytes[i] == b' ' {
-                        i += 1;
+    // Find operator/pipe/background split points using token offsets.
+    // For each split, extract the original substring from `cmd` to preserve
+    // exact spacing, quotes, and redirects that rewrite_segment expects.
+    let mut seg_start: usize = 0; // byte offset of current segment start
+    let mut prev_kind: Option<&TokenKind> = None;
+
+    for (idx, tok) in tokens.iter().enumerate() {
+        match tok.kind {
+            TokenKind::Operator => {
+                // &&, ||, ; — rewrite left segment, append operator, continue
+                let seg = cmd[seg_start..tok.offset].trim();
+                let rewritten = rewrite_segment(seg, excluded).unwrap_or_else(|| seg.to_string());
+                if rewritten != seg {
+                    any_changed = true;
+                }
+                result.push_str(&rewritten);
+                // Normalize operator spacing
+                if tok.value == ";" {
+                    result.push(';');
+                    // Add space after semicolon if there's more content
+                    let after = tok.offset + tok.value.len();
+                    if after < cmd.len() {
+                        result.push(' ');
                     }
-                    seg_start = i;
                 } else {
-                    // `|` pipe — rewrite first segment only, pass through the rest unchanged
-                    let seg = cmd[seg_start..i].trim();
-                    // Skip rewriting `find`/`fd` in pipes — rtk find outputs a grouped
-                    // format that is incompatible with pipe consumers like xargs, grep,
-                    // wc, sort, etc. which expect one path per line (#439).
-                    let is_pipe_incompatible = seg.starts_with("find ")
-                        || seg == "find"
-                        || seg.starts_with("fd ")
-                        || seg == "fd";
-                    let rewritten = if is_pipe_incompatible {
-                        seg.to_string()
-                    } else {
-                        rewrite_segment(seg, excluded).unwrap_or_else(|| seg.to_string())
-                    };
-                    if rewritten != seg {
-                        any_changed = true;
-                    }
-                    result.push_str(&rewritten);
-                    // Preserve the space before the pipe that was lost by trim()
                     result.push(' ');
-                    result.push_str(cmd[i..].trim_start());
-                    return if any_changed { Some(result) } else { None };
+                    result.push_str(&tok.value);
+                    result.push(' ');
+                }
+                // Advance past the operator and any trailing whitespace
+                seg_start = tok.offset + tok.value.len();
+                while seg_start < cmd.len()
+                    && cmd.as_bytes().get(seg_start).is_some_and(|&b| b == b' ')
+                {
+                    seg_start += 1;
                 }
             }
-            b'&' if !in_single && !in_double && i + 1 < len && bytes[i + 1] == b'&' => {
-                // `&&` operator — rewrite left, continue
-                let seg = cmd[seg_start..i].trim();
-                let rewritten = rewrite_segment(seg, excluded).unwrap_or_else(|| seg.to_string());
+            TokenKind::Pipe => {
+                // | — rewrite first segment only, pass through the rest unchanged
+                let seg = cmd[seg_start..tok.offset].trim();
+                // Skip rewriting `find`/`fd` in pipes — rtk find outputs a grouped
+                // format that is incompatible with pipe consumers like xargs, grep,
+                // wc, sort, etc. which expect one path per line (#439).
+                let is_pipe_incompatible = seg.starts_with("find ")
+                    || seg == "find"
+                    || seg.starts_with("fd ")
+                    || seg == "fd";
+                let rewritten = if is_pipe_incompatible {
+                    seg.to_string()
+                } else {
+                    rewrite_segment(seg, excluded).unwrap_or_else(|| seg.to_string())
+                };
                 if rewritten != seg {
                     any_changed = true;
                 }
                 result.push_str(&rewritten);
-                result.push_str(" && ");
-                i += 2;
-                while i < len && bytes[i] == b' ' {
-                    i += 1;
-                }
-                seg_start = i;
-            }
-            b'&' if !in_single && !in_double => {
-                // #346: redirect detection — 2>&1 / >&2 (> before &) or &>file / &>>file (> after &)
-                let is_redirect =
-                    (i > 0 && bytes[i - 1] == b'>') || (i + 1 < len && bytes[i + 1] == b'>');
-                if is_redirect {
-                    i += 1;
+                // Preserve the pipe and everything after it unchanged
+                result.push(' ');
+                result.push_str(cmd[tok.offset..].trim_start());
+                return if any_changed { Some(result) } else { None };
+            }
+            TokenKind::Shellism if tok.value == "&" => {
+                // Single `&` — distinguish background operator from redirect context.
+                // If preceded by a Redirect token (2>&1) or followed by a Redirect
+                // token (&>/dev/null, &>>file), this is part of redirect syntax.
+                let next_is_redirect = tokens
+                    .get(idx + 1)
+                    .is_some_and(|t| t.kind == TokenKind::Redirect);
+                if prev_kind == Some(&TokenKind::Redirect) || next_is_redirect {
+                    // Part of redirect (e.g. 2>&1 or &>/dev/null) — not a segment separator
                 } else {
-                    // single `&` background execution operator
-                    let seg = cmd[seg_start..i].trim();
+                    // Background operator — rewrite left segment, continue
+                    let seg = cmd[seg_start..tok.offset].trim();
                     let rewritten =
                         rewrite_segment(seg, excluded).unwrap_or_else(|| seg.to_string());
                     if rewritten != seg {
@@ -454,39 +452,21 @@ fn rewrite_compound(cmd: &str, excluded: &[String]) -> Option<String> {
                     }
                     result.push_str(&rewritten);
                     result.push_str(" & ");
-                    i += 1;
-                    while i < len && bytes[i] == b' ' {
-                        i += 1;
+                    seg_start = tok.offset + tok.value.len();
+                    while seg_start < cmd.len()
+                        && cmd.as_bytes().get(seg_start).is_some_and(|&b| b == b' ')
+                    {
+                        seg_start += 1;
                     }
-                    seg_start = i;
-                }
-            }
-            b';' if !in_single && !in_double => {
-                // `;` separator
-                let seg = cmd[seg_start..i].trim();
-                let rewritten = rewrite_segment(seg, excluded).unwrap_or_else(|| seg.to_string());
-                if rewritten != seg {
-                    any_changed = true;
-                }
-                result.push_str(&rewritten);
-                result.push(';');
-                i += 1;
-                while i < len && bytes[i] == b' ' {
-                    i += 1;
-                }
-                if i < len {
-                    result.push(' ');
                 }
-                seg_start = i;
-            }
-            _ => {
-                i += 1;
             }
+            _ => {}
         }
+        prev_kind = Some(&tok.kind);
     }
 
     // Last (or only) segment
-    let seg = cmd[seg_start..len].trim();
+    let seg = cmd[seg_start..].trim();
     let rewritten = rewrite_segment(seg, excluded).unwrap_or_else(|| seg.to_string());
     if rewritten != seg {
         any_changed = true;
@@ -2074,6 +2054,43 @@ mod tests {
         }
     }
 
+    // --- wc rule ---
+
+    #[test]
+    fn test_classify_wc() {
+        assert_eq!(
+            classify_command("wc -l src/main.rs"),
+            Classification::Supported {
+                rtk_equivalent: "rtk wc",
+                category: "System",
+                estimated_savings_pct: 60.0,
+                status: super::super::report::RtkStatus::Existing,
+            }
+        );
+    }
+
+    #[test]
+    fn test_classify_wc_bare() {
+        assert_eq!(
+            classify_command("wc"),
+            Classification::Supported {
+                rtk_equivalent: "rtk wc",
+                category: "System",
+                estimated_savings_pct: 60.0,
+                status: super::super::report::RtkStatus::Existing,
+            }
+        );
+    }
+
+    #[test]
+    fn test_route_wc() {
+        let excluded: Vec<String> = vec![];
+        assert_eq!(
+            rewrite_command("wc -l src/main.rs", &excluded),
+            Some("rtk wc -l src/main.rs".into())
+        );
+    }
+
     // --- #196: gh --json/--jq/--template passthrough ---
 
     #[test]
diff --git a/src/discover/rules.rs b/src/discover/rules.rs
index 00c793016..2e5427dda 100644
--- a/src/discover/rules.rs
+++ b/src/discover/rules.rs
@@ -48,6 +48,8 @@ pub const PATTERNS: &[&str] = &[
     r"^aws\s+",
     // PostgreSQL
     r"^psql(\s|$)",
+    // System utilities
+    r"^wc(\s|$)",
     // TOML-filtered commands
     r"^ansible-playbook\b",
     r"^brew\s+(install|upgrade)\b",
@@ -350,6 +352,15 @@ pub const RULES: &[RtkRule] = &[
         subcmd_savings: &[],
         subcmd_status: &[],
     },
+    // System utilities
+    RtkRule {
+        rtk_cmd: "rtk wc",
+        rewrite_prefixes: &["wc"],
+        category: "System",
+        savings_pct: 60.0,
+        subcmd_savings: &[],
+        subcmd_status: &[],
+    },
     // TOML-filtered commands
     RtkRule {
         rtk_cmd: "rtk ansible-playbook",
@@ -635,7 +646,6 @@ pub const IGNORED_PREFIXES: &[&str] = &[
     "kill ",
     "set ",
     "unset ",
-    "wc ",
     "sort ",
     "uniq ",
     "tr ",
diff --git a/src/gain.rs b/src/gain.rs
index bafdc0018..1a9468f14 100644
--- a/src/gain.rs
+++ b/src/gain.rs
@@ -56,7 +56,7 @@ pub fn run(
     }
 
     let summary = tracker
-        .get_summary_filtered(project_scope.as_deref()) // changed: use filtered variant
+        .get_summary_filtered(project_scope.as_deref())
         .context("Failed to load token savings summary from database")?;
 
     if summary.total_commands == 0 {
@@ -223,7 +223,7 @@ pub fn run(
         }
 
         if history {
-            let recent = tracker.get_recent_filtered(10, project_scope.as_deref())?; // changed: filtered
+            let recent = tracker.get_recent_filtered(10, project_scope.as_deref())?;
             if !recent.is_empty() {
                 println!("{}", styled("Recent Commands", true)); // added: styled header
                 println!("──────────────────────────────────────────────────────────");
diff --git a/src/gh_cmd.rs b/src/gh_cmd.rs
index 9073c7e0f..408679f8c 100644
--- a/src/gh_cmd.rs
+++ b/src/gh_cmd.rs
@@ -649,12 +649,10 @@ fn list_issues(args: &[String], _verbose: u8, ultra_compact: bool) -> Result<()>
                 } else {
                     "C"
                 }
+            } else if state == "OPEN" {
+                "🟢"
             } else {
-                if state == "OPEN" {
-                    "[open]"
-                } else {
-                    "[closed]"
-                }
+                "[closed]"
             };
             let line = format!("  {} #{} {}\n", icon, number, truncate(title, 60));
             filtered.push_str(&line);
diff --git a/src/git.rs b/src/git.rs
index 3d49fdd6c..d96e403ce 100644
--- a/src/git.rs
+++ b/src/git.rs
@@ -450,7 +450,6 @@ fn run_log(
     Ok(())
 }
 
-/// Filter git log output: truncate long messages, cap lines
 /// Parse the user-specified limit from git log args.
 /// Handles: -20, -n 20, --max-count=20, --max-count 20
 fn parse_user_limit(args: &[String]) -> Option<usize> {
@@ -495,7 +494,7 @@ fn parse_user_limit(args: &[String]) -> Option<usize> {
 /// so we skip line capping (git already returns exactly N commits) and use a
 /// wider truncation threshold (120 chars) to preserve commit context that LLMs
 /// need for rebase/squash operations.
-fn filter_log_output(
+pub(crate) fn filter_log_output(
     output: &str,
     limit: usize,
     user_set_limit: bool,
@@ -560,7 +559,7 @@ fn truncate_line(line: &str, width: usize) -> String {
 }
 
 /// Format porcelain output into compact RTK status display
-fn format_status_output(porcelain: &str) -> String {
+pub(crate) fn format_status_output(porcelain: &str) -> String {
     let lines: Vec<&str> = porcelain.lines().collect();
 
     if lines.is_empty() {
@@ -907,6 +906,14 @@ fn run_commit(args: &[String], verbose: u8, global_args: &[String]) -> Result<()
         println!("{}", compact);
 
         timer.track(&original_cmd, "rtk git commit", &raw_output, &compact);
+    } else if stderr.contains("nothing to commit") || stdout.contains("nothing to commit") {
+        println!("ok (nothing to commit)");
+        timer.track(
+            &original_cmd,
+            "rtk git commit",
+            &raw_output,
+            "ok (nothing to commit)",
+        );
     } else {
         if stderr.contains("nothing to commit") || stdout.contains("nothing to commit") {
             println!("ok (nothing to commit)");
@@ -1253,13 +1260,16 @@ fn filter_branch_output(output: &str) -> String {
 
         if let Some(branch) = line.strip_prefix("* ") {
             current = branch.to_string();
-        } else if line.starts_with("remotes/origin/") {
-            let branch = line.strip_prefix("remotes/origin/").unwrap_or(line);
-            // Skip HEAD pointer
-            if branch.starts_with("HEAD ") {
-                continue;
+        } else if let Some(rest) = line.strip_prefix("remotes/") {
+            // Match any remote: remotes/origin/*, remotes/upstream/*, etc.
+            if let Some(pos) = rest.find('/') {
+                let branch = &rest[pos + 1..];
+                // Skip HEAD pointers (e.g., "HEAD -> origin/main")
+                if branch.starts_with("HEAD ") {
+                    continue;
+                }
+                remote.push(branch.to_string());
             }
-            remote.push(branch.to_string());
         } else {
             local.push(line.to_string());
         }
@@ -1275,10 +1285,11 @@ fn filter_branch_output(output: &str) -> String {
     }
 
     if !remote.is_empty() {
-        // Filter out remotes that already exist locally
+        // Deduplicate remote branches and filter out ones that exist locally
+        let mut seen = std::collections::HashSet::new();
         let remote_only: Vec<&String> = remote
             .iter()
-            .filter(|r| *r != &current && !local.contains(r))
+            .filter(|r| *r != &current && !local.contains(r) && seen.insert(r.as_str().to_string()))
             .collect();
         if !remote_only.is_empty() {
             result.push(format!("  remote-only ({}):", remote_only.len()));
@@ -1769,6 +1780,95 @@ mod tests {
         assert!(result.contains("release/v2"));
     }
 
+    #[test]
+    fn test_filter_branch_multi_remote() {
+        // Multi-remote repo: origin, upstream, fork — each with branches
+        let output = "* main\n  feature/auth\n  fix/bug-123\n  \
+            remotes/origin/HEAD -> origin/main\n  remotes/origin/main\n  \
+            remotes/origin/feature/auth\n  remotes/origin/release/v2\n  \
+            remotes/upstream/main\n  remotes/upstream/develop\n  \
+            remotes/upstream/release/v1\n  remotes/upstream/release/v2\n  \
+            remotes/upstream/release/v3\n  \
+            remotes/fork/main\n  remotes/fork/feature/auth\n  \
+            remotes/fork/experiment/new-ui\n";
+        let result = filter_branch_output(output);
+        // Must recognize all remotes, not just origin
+        assert!(result.contains("* main"));
+        assert!(result.contains("feature/auth"));
+        // Remote-only branches should be grouped and deduped against local
+        assert!(
+            result.contains("remote-only"),
+            "must show remote-only section: {}",
+            result
+        );
+        // release/v2 is origin+upstream (both remote-only)
+        assert!(
+            result.contains("release/v2"),
+            "must show release/v2: {}",
+            result
+        );
+        // upstream-only branches like develop, release/v1, release/v3
+        assert!(
+            result.contains("develop"),
+            "must show upstream develop: {}",
+            result
+        );
+        // fork experiment is remote-only
+        assert!(
+            result.contains("experiment/new-ui"),
+            "must show fork experiment: {}",
+            result
+        );
+        // Branches that exist locally should NOT appear in remote-only
+        // (main is local+current, feature/auth is local)
+        let remote_section_start = result.find("remote-only").unwrap();
+        let remote_section = &result[remote_section_start..];
+        // main and feature/auth should not be in remote-only section
+        // (they may appear earlier as local branches)
+        assert!(
+            !remote_section.contains("\n    main\n"),
+            "main should not be in remote-only"
+        );
+    }
+
+    #[test]
+    fn test_filter_branch_multi_remote_savings() {
+        // Realistic multi-remote with many branches — must achieve meaningful savings
+        let mut lines = vec!["* main", "  develop", "  feature/auth"];
+        let mut remote_lines = Vec::new();
+        for remote in &["origin", "upstream", "fork"] {
+            for branch in &[
+                "main",
+                "develop",
+                "feature/auth",
+                "release/v1",
+                "release/v2",
+                "release/v3",
+                "hotfix/urgent",
+                "ci/pipeline",
+                "docs/update",
+            ] {
+                remote_lines.push(format!("  remotes/{}/{}", remote, branch));
+            }
+        }
+        let remote_strs: Vec<&str> = remote_lines.iter().map(|s| s.as_str()).collect();
+        lines.extend(remote_strs);
+        let output = lines.join("\n");
+        let result = filter_branch_output(&output);
+
+        fn count_tokens(s: &str) -> usize {
+            s.split_whitespace().count()
+        }
+        let input_tokens = count_tokens(&output);
+        let output_tokens = count_tokens(&result);
+        let savings = 100.0 - (output_tokens as f64 / input_tokens as f64 * 100.0);
+        assert!(
+            savings >= 40.0,
+            "Multi-remote branch filter: expected ≥40% savings, got {:.1}% (in={}, out={})\nResult:\n{}",
+            savings, input_tokens, output_tokens, result
+        );
+    }
+
     #[test]
     fn test_filter_branch_no_remotes() {
         let output = "* main\n  develop\n";
@@ -2227,6 +2327,36 @@ no changes added to commit (use "git add" and/or "git commit -a")
         );
     }
 
+    #[test]
+    fn test_commit_three_messages() {
+        // Three -m flags for multi-paragraph commits
+        let args = vec![
+            "-m".to_string(),
+            "title".to_string(),
+            "-m".to_string(),
+            "body".to_string(),
+            "-m".to_string(),
+            "footer: refs #202".to_string(),
+        ];
+        let cmd = build_commit_command(&args, &[]);
+        let cmd_args: Vec<_> = cmd
+            .get_args()
+            .map(|a| a.to_string_lossy().to_string())
+            .collect();
+        assert_eq!(
+            cmd_args,
+            vec![
+                "commit",
+                "-m",
+                "title",
+                "-m",
+                "body",
+                "-m",
+                "footer: refs #202"
+            ]
+        );
+    }
+
     // #327: git commit -am "msg" must pass -am through to git
     #[test]
     fn test_commit_am_flag() {
@@ -2274,6 +2404,9 @@ no changes added to commit (use "git add" and/or "git commit -a")
         let output = std::process::Command::new(&bin_path)
             .args(["git", "status"])
             .current_dir(&tmp)
+            // Point GIT_DIR to a non-existent path so git always fails,
+            // regardless of whether a parent directory has .git
+            .env("GIT_DIR", tmp.join("nonexistent.git"))
             .output()
             .expect("Failed to run rtk");
 
@@ -2296,4 +2429,112 @@ no changes added to commit (use "git add" and/or "git commit -a")
 
         let _ = std::fs::remove_dir_all(&tmp);
     }
+
+    #[test]
+    fn test_commit_file_flag() {
+        let args = vec!["-F".to_string(), "/tmp/msg.txt".to_string()];
+        let cmd = build_commit_command(&args, &[]);
+        let cmd_args: Vec<_> = cmd
+            .get_args()
+            .map(|a| a.to_string_lossy().to_string())
+            .collect();
+        assert_eq!(cmd_args, vec!["commit", "-F", "/tmp/msg.txt"]);
+    }
+
+    #[test]
+    fn test_commit_amend_no_edit() {
+        let args = vec!["--amend".to_string(), "--no-edit".to_string()];
+        let cmd = build_commit_command(&args, &[]);
+        let cmd_args: Vec<_> = cmd
+            .get_args()
+            .map(|a| a.to_string_lossy().to_string())
+            .collect();
+        assert_eq!(cmd_args, vec!["commit", "--amend", "--no-edit"]);
+    }
+
+    #[test]
+    fn test_commit_message_and_extra_args() {
+        // With flat args, -m and --no-verify are all in the same args vec
+        let args = vec![
+            "-m".to_string(),
+            "fix: typo".to_string(),
+            "--no-verify".to_string(),
+        ];
+        let cmd = build_commit_command(&args, &[]);
+        let cmd_args: Vec<_> = cmd
+            .get_args()
+            .map(|a| a.to_string_lossy().to_string())
+            .collect();
+        assert_eq!(cmd_args, vec!["commit", "-m", "fix: typo", "--no-verify"]);
+    }
+
+    #[test]
+    fn test_commit_empty_args() {
+        // Edge: no args at all (would prompt for editor)
+        let cmd = build_commit_command(&[], &[]);
+        let cmd_args: Vec<_> = cmd
+            .get_args()
+            .map(|a| a.to_string_lossy().to_string())
+            .collect();
+        assert_eq!(cmd_args, vec!["commit"]);
+    }
+
+    #[test]
+    fn test_commit_with_global_args() {
+        // Global args like -C <dir> should appear before "commit"
+        let args = vec!["-m".to_string(), "msg".to_string()];
+        let global = vec!["-C".to_string(), "/tmp/repo".to_string()];
+        let cmd = build_commit_command(&args, &global);
+        let cmd_args: Vec<_> = cmd
+            .get_args()
+            .map(|a| a.to_string_lossy().to_string())
+            .collect();
+        assert_eq!(cmd_args, vec!["-C", "/tmp/repo", "commit", "-m", "msg"]);
+    }
+
+    #[test]
+    fn test_commit_signoff() {
+        // git commit -s -m "msg" (--signoff shorthand)
+        let args = vec!["-s".to_string(), "-m".to_string(), "msg".to_string()];
+        let cmd = build_commit_command(&args, &[]);
+        let cmd_args: Vec<_> = cmd
+            .get_args()
+            .map(|a| a.to_string_lossy().to_string())
+            .collect();
+        assert_eq!(cmd_args, vec!["commit", "-s", "-m", "msg"]);
+    }
+
+    #[test]
+    fn test_commit_fixup() {
+        // git commit --fixup=abc123
+        let args = vec!["--fixup=abc123".to_string()];
+        let cmd = build_commit_command(&args, &[]);
+        let cmd_args: Vec<_> = cmd
+            .get_args()
+            .map(|a| a.to_string_lossy().to_string())
+            .collect();
+        assert_eq!(cmd_args, vec!["commit", "--fixup=abc123"]);
+    }
+
+    #[test]
+    fn test_commit_message_with_special_chars() {
+        // Messages with quotes, newlines, unicode
+        let args = vec![
+            "-m".to_string(),
+            "fix: handle \"quoted\" strings & special chars 日本語".to_string(),
+        ];
+        let cmd = build_commit_command(&args, &[]);
+        let cmd_args: Vec<_> = cmd
+            .get_args()
+            .map(|a| a.to_string_lossy().to_string())
+            .collect();
+        assert_eq!(
+            cmd_args,
+            vec![
+                "commit",
+                "-m",
+                "fix: handle \"quoted\" strings & special chars 日本語"
+            ]
+        );
+    }
 }
diff --git a/src/go_cmd.rs b/src/go_cmd.rs
index d250c4276..71fe96613 100644
--- a/src/go_cmd.rs
+++ b/src/go_cmd.rs
@@ -247,7 +247,7 @@ pub fn run_other(args: &[OsString], verbose: u8) -> Result<()> {
 }
 
 /// Parse go test -json output (NDJSON format)
-fn filter_go_test_json(output: &str) -> String {
+pub fn filter_go_test_json(output: &str) -> String {
     let mut packages: HashMap<String, PackageResult> = HashMap::new();
     let mut current_test_output: HashMap<(String, String), Vec<String>> = HashMap::new(); // (package, test) -> outputs
     let mut build_output: HashMap<String, Vec<String>> = HashMap::new(); // import_path -> error lines
@@ -428,7 +428,7 @@ fn filter_go_test_json(output: &str) -> String {
 }
 
 /// Filter go build output - show only errors
-fn filter_go_build(output: &str) -> String {
+pub fn filter_go_build(output: &str) -> String {
     let mut errors: Vec<String> = Vec::new();
 
     for line in output.lines() {
diff --git a/src/grep_cmd.rs b/src/grep_cmd.rs
index c1819dded..6de9fee21 100644
--- a/src/grep_cmd.rs
+++ b/src/grep_cmd.rs
@@ -4,6 +4,7 @@ use crate::utils::resolved_command;
 use anyhow::{Context, Result};
 use regex::Regex;
 use std::collections::HashMap;
+use std::process::Command;
 
 #[allow(clippy::too_many_arguments)]
 pub fn run(
@@ -22,7 +23,7 @@ pub fn run(
         eprintln!("grep: '{}' in {}", pattern, path);
     }
 
-    // Fix: convert BRE alternation \| → | for rg (which uses PCRE-style regex)
+    // BRE alternation \| → | for rg (which uses PCRE-style regex)
     let rg_pattern = pattern.replace(r"\|", "|");
 
     let mut rg_cmd = resolved_command("rg");
@@ -33,7 +34,7 @@ pub fn run(
     }
 
     for arg in extra_args {
-        // Fix: skip grep-ism -r flag (rg is recursive by default; rg -r means --replace)
+        // Skip grep-ism -r flag (rg is recursive by default; rg -r means --replace)
         if arg == "-r" || arg == "--recursive" {
             continue;
         }
@@ -42,11 +43,7 @@ pub fn run(
 
     let output = rg_cmd
         .output()
-        .or_else(|_| {
-            resolved_command("grep")
-                .args(["-rn", pattern, path])
-                .output()
-        })
+        .or_else(|_| Command::new("grep").args(["-rn", pattern, path]).output())
         .context("grep/rg failed")?;
 
     let stdout = String::from_utf8_lossy(&output.stdout);
@@ -153,6 +150,170 @@ pub fn run(
     Ok(())
 }
 
+/// Filter raw rg/grep output into compact grouped display.
+///
+/// Handles two formats:
+/// - Three-part `file:line_num:content` — produced by `rg -n` or `grep -n`
+/// - Two-part `file:content` — produced by `grep` without `-n` or BSD grep
+///
+/// Suitable for `rtk pipe --filter grep` / `rtk pipe --filter rg`.
+/// Uses defaults: max_line_len=80, max_results=50.
+pub(crate) fn filter_grep_raw(input: &str) -> String {
+    if input.trim().is_empty() {
+        return "0 matches\n".to_string();
+    }
+
+    let mut by_file: HashMap<String, Vec<(usize, String)>> = HashMap::new();
+    let mut total = 0;
+    const MAX_RESULTS: usize = 50;
+    const MAX_LINE_LEN: usize = 80;
+
+    for line in input.lines() {
+        if line.trim().is_empty() {
+            continue;
+        }
+        let parts: Vec<&str> = line.splitn(3, ':').collect();
+        // Three-part: file:line_num:content  (rg -n / grep -n)
+        // Two-part:   file:content           (grep without -n)
+        let (file, line_num, content) = if parts.len() == 3 {
+            if let Ok(ln) = parts[1].parse::<usize>() {
+                // Confirmed three-part with numeric line number
+                (parts[0].to_string(), ln, parts[2])
+            } else {
+                // parts[1] is not a number; treat as two-part with ':' in content
+                let content = &line[parts[0].len() + 1..]; // everything after first ':'
+                (parts[0].to_string(), 0, content)
+            }
+        } else if parts.len() == 2 {
+            // Two-part: file:content
+            (parts[0].to_string(), 0, parts[1])
+        } else {
+            continue;
+        };
+
+        total += 1;
+        let cleaned = clean_line(content, MAX_LINE_LEN, None, "");
+        by_file.entry(file).or_default().push((line_num, cleaned));
+    }
+
+    if total == 0 {
+        return "0 matches\n".to_string();
+    }
+
+    let mut out = String::new();
+    out.push_str(&format!("{} in {}F:\n\n", total, by_file.len()));
+
+    let mut shown = 0;
+    let mut files: Vec<_> = by_file.iter().collect();
+    files.sort_by_key(|(f, _)| *f);
+
+    for (file, matches) in files {
+        if shown >= MAX_RESULTS {
+            break;
+        }
+        let file_display = compact_path(file);
+        out.push_str(&format!("{} ({}):\n", file_display, matches.len()));
+        for (line_num, content) in matches.iter().take(10) {
+            out.push_str(&format!("  {:>4}: {}\n", line_num, content));
+            shown += 1;
+            if shown >= MAX_RESULTS {
+                break;
+            }
+        }
+        if matches.len() > 10 {
+            out.push_str(&format!("  +{}\n", matches.len() - 10));
+        }
+        out.push('\n');
+    }
+
+    if total > shown {
+        out.push_str(&format!("... +{}\n", total - shown));
+    }
+
+    out
+}
+
+/// Filter `find`/`fd` output (one path per line) into a compact summary.
+///
+/// Groups results by parent directory and counts files by extension.
+/// Suitable for `rtk pipe --filter find` and `rtk pipe --filter fd`.
+pub(crate) fn filter_find_output(input: &str) -> String {
+    if input.trim().is_empty() {
+        return "find: 0 results\n".to_string();
+    }
+
+    let mut by_dir: HashMap<String, usize> = HashMap::new();
+    let mut by_ext: HashMap<String, usize> = HashMap::new();
+    let mut total = 0usize;
+
+    for line in input.lines() {
+        let path = line.trim();
+        if path.is_empty() {
+            continue;
+        }
+        total += 1;
+
+        // Parent directory
+        let dir = if let Some(pos) = path.rfind('/') {
+            &path[..pos]
+        } else {
+            "."
+        };
+        *by_dir.entry(dir.to_string()).or_insert(0) += 1;
+
+        // Extension
+        let ext = if let Some(pos) = path.rfind('.') {
+            let candidate = &path[pos + 1..];
+            // Only treat as extension if no '/' after the dot (i.e. it's in the filename)
+            if candidate.contains('/') {
+                "(no ext)"
+            } else {
+                candidate
+            }
+        } else {
+            "(no ext)"
+        };
+        *by_ext.entry(ext.to_string()).or_insert(0) += 1;
+    }
+
+    if total == 0 {
+        return "find: 0 results\n".to_string();
+    }
+
+    let mut out = String::new();
+    out.push_str(&format!("find: {} files\n", total));
+
+    // Top directories (up to 10)
+    let mut dirs: Vec<_> = by_dir.iter().collect();
+    dirs.sort_by(|a, b| b.1.cmp(a.1).then(a.0.cmp(b.0)));
+    out.push_str("Dirs:\n");
+    for (dir, count) in dirs.iter().take(10) {
+        out.push_str(&format!("  {} ({})\n", dir, count));
+    }
+    if dirs.len() > 10 {
+        out.push_str(&format!("  ... +{} more dirs\n", dirs.len() - 10));
+    }
+
+    // Extension breakdown (up to 8)
+    let mut exts: Vec<_> = by_ext.iter().collect();
+    exts.sort_by(|a, b| b.1.cmp(a.1).then(a.0.cmp(b.0)));
+    if !exts.is_empty() {
+        out.push_str("Types: ");
+        let ext_parts: Vec<String> = exts
+            .iter()
+            .take(8)
+            .map(|(ext, count)| format!(".{} ({})", ext, count))
+            .collect();
+        out.push_str(&ext_parts.join(", "));
+        if exts.len() > 8 {
+            out.push_str(&format!(", +{} more", exts.len() - 8));
+        }
+        out.push('\n');
+    }
+
+    out
+}
+
 fn clean_line(line: &str, max_len: usize, context_re: Option<&Regex>, pattern: &str) -> String {
     let trimmed = line.trim();
 
@@ -281,20 +442,143 @@ mod tests {
     }
 
     // Verify line numbers are always enabled in rg invocation (grep_cmd.rs:24).
-    // The -n/--line-numbers clap flag in main.rs is a no-op accepted for compat.
     #[test]
     fn test_rg_always_has_line_numbers() {
-        // grep_cmd::run() always passes "-n" to rg (line 24).
-        // This test documents that -n is built-in, so the clap flag is safe to ignore.
         let mut cmd = resolved_command("rg");
         cmd.args(["-n", "--no-heading", "NONEXISTENT_PATTERN_12345", "."]);
-        // If rg is available, it should accept -n without error (exit 1 = no match, not error)
         if let Ok(output) = cmd.output() {
             assert!(
                 output.status.code() == Some(1) || output.status.success(),
                 "rg -n should be accepted"
             );
         }
-        // If rg is not installed, skip gracefully (test still passes)
+    }
+
+    // ── filter_grep_raw: 3-part format (rg -n / grep -n) ─────────────────────
+
+    #[test]
+    fn test_filter_grep_raw_three_part() {
+        let input = "src/main.rs:42:fn main() {\nsrc/lib.rs:10:pub fn helper() {}\n";
+        let out = filter_grep_raw(input);
+        assert!(out.contains("main.rs"), "out={}", out);
+        assert!(out.contains("lib.rs"), "out={}", out);
+        assert!(out.contains("2 in"), "expected 2 matches: out={}", out);
+    }
+
+    #[test]
+    fn test_filter_grep_raw_empty() {
+        let out = filter_grep_raw("");
+        assert!(out.contains("0 matches"), "out={}", out);
+    }
+
+    #[test]
+    fn test_filter_grep_raw_whitespace_only() {
+        let out = filter_grep_raw("   \n\t\n");
+        assert!(out.contains("0 matches"), "out={}", out);
+    }
+
+    // ── filter_grep_raw: 2-part format (grep without -n) ─────────────────────
+
+    #[test]
+    fn test_filter_grep_raw_two_part_no_line_number() {
+        // grep without -n produces "file:content" (no line number)
+        let input = "src/main.rs:fn main() {\nsrc/lib.rs:pub fn helper() {}\n";
+        let out = filter_grep_raw(input);
+        assert!(out.contains("main.rs"), "2-part: out={}", out);
+        assert!(out.contains("lib.rs"), "2-part: out={}", out);
+        assert!(
+            out.contains("2 in"),
+            "2-part: expected 2 matches: out={}",
+            out
+        );
+    }
+
+    #[test]
+    fn test_filter_grep_raw_two_part_content_with_colon() {
+        // Two-part where content itself contains ':' (e.g. URL or time)
+        let input = "config.yaml:server: http://localhost:8080\n";
+        let out = filter_grep_raw(input);
+        // Should not panic and should show config.yaml
+        assert!(out.contains("config.yaml"), "out={}", out);
+    }
+
+    #[test]
+    fn test_filter_grep_raw_mixed_two_and_three_part() {
+        // Some lines have line numbers, some don't — both should be counted
+        let input = "src/a.rs:10:fn foo() {}\nsrc/b.rs:fn bar() {}\n";
+        let out = filter_grep_raw(input);
+        assert!(out.contains("a.rs"), "out={}", out);
+        assert!(out.contains("b.rs"), "out={}", out);
+    }
+
+    #[test]
+    fn test_filter_grep_raw_three_part_nonnumeric_middle() {
+        // Three-part split but middle is not a number (e.g. Windows path C:\file:content)
+        // Should fall back gracefully — either include or skip, but not panic
+        let input = "C:\\path\\file.rs:some content\n";
+        let out = filter_grep_raw(input); // must not panic
+        assert!(!out.is_empty());
+    }
+
+    // ── filter_find_output ────────────────────────────────────────────────────
+
+    #[test]
+    fn test_filter_find_output_empty() {
+        let out = filter_find_output("");
+        assert!(out.contains("0 results"), "out={}", out);
+    }
+
+    #[test]
+    fn test_filter_find_output_basic() {
+        let input = "./src/main.rs\n./src/lib.rs\n./src/cmd/mod.rs\n";
+        let out = filter_find_output(input);
+        assert!(out.contains("3 files"), "out={}", out);
+        // Extension breakdown
+        assert!(out.contains(".rs"), "out={}", out);
+    }
+
+    #[test]
+    fn test_filter_find_output_groups_by_dir() {
+        let input = "./src/a.rs\n./src/b.rs\n./tests/c.rs\n";
+        let out = filter_find_output(input);
+        assert!(out.contains("./src"), "out={}", out);
+        assert!(out.contains("./tests"), "out={}", out);
+    }
+
+    #[test]
+    fn test_filter_find_output_extension_counts() {
+        let input = "./a.rs\n./b.rs\n./c.toml\n./d.md\n";
+        let out = filter_find_output(input);
+        // .rs appears twice, toml and md once each
+        assert!(out.contains(".rs (2)"), "out={}", out);
+        assert!(
+            out.contains(".toml (1)") || out.contains(".md (1)"),
+            "out={}",
+            out
+        );
+    }
+
+    #[test]
+    fn test_filter_find_output_no_extension() {
+        let input = "./Makefile\n./Dockerfile\n";
+        let out = filter_find_output(input);
+        assert!(out.contains("2 files"), "out={}", out);
+        assert!(out.contains("(no ext)"), "out={}", out);
+    }
+
+    #[test]
+    fn test_filter_find_output_many_dirs_truncated() {
+        // More than 10 unique dirs — should show "+N more dirs"
+        let mut input = String::new();
+        for i in 0..15 {
+            input.push_str(&format!("./dir{}/file.rs\n", i));
+        }
+        let out = filter_find_output(&input);
+        assert!(out.contains("15 files"), "out={}", out);
+        assert!(
+            out.contains("more dirs"),
+            "should truncate dirs: out={}",
+            out
+        );
     }
 }
diff --git a/src/hook_audit_cmd.rs b/src/hook_audit_cmd.rs
index 489eecc0f..4ffd58bfa 100644
--- a/src/hook_audit_cmd.rs
+++ b/src/hook_audit_cmd.rs
@@ -7,10 +7,12 @@ fn default_log_path() -> PathBuf {
     if let Ok(dir) = std::env::var("RTK_AUDIT_DIR") {
         PathBuf::from(dir).join("hook-audit.log")
     } else {
-        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
-        PathBuf::from(home)
-            .join(".local/share/rtk")
-            .join("hook-audit.log")
+        // Use dirs for cross-platform home: ~/.local/share/rtk/ on Unix,
+        // %APPDATA%\rtk\ on Windows (dirs::data_local_dir handles both).
+        let base = dirs::data_local_dir()
+            .or_else(|| dirs::home_dir().map(|h| h.join(".local").join("share")))
+            .unwrap_or_else(std::env::temp_dir);
+        base.join("rtk").join("hook-audit.log")
     }
 }
 
diff --git a/src/init.rs b/src/init.rs
index 241a7ef55..83dd53d90 100644
--- a/src/init.rs
+++ b/src/init.rs
@@ -67,6 +67,21 @@ pub enum PatchResult {
     Skipped,        // --no-patch flag used
 }
 
+/// Selects which hook mechanism to install for Claude Code PreToolUse:Bash.
+///
+/// Script: deploys `rtk-rewrite.sh` and installs it as the hook. Shell-portable,
+///         phased-transition approach. Default for this branch.
+/// Binary: installs `"rtk hook claude"` directly. Fastest, no shell dependency.
+///
+/// Both produce equivalent behavior after the parallel-merge coordinator changes.
+#[derive(clap::ValueEnum, Clone, Debug, PartialEq)]
+pub enum HookType {
+    /// Deploy rtk-rewrite.sh and install it as the Claude Code hook (shell-portable)
+    Script,
+    /// Install "rtk hook claude" as the Claude Code hook (fast, no shell dependency)
+    Binary,
+}
+
 // Legacy full instructions for backward compatibility (--claude-md mode)
 const RTK_INSTRUCTIONS: &str = r##"<!-- rtk-instructions v2 -->
 # RTK (Rust Token Killer) - Token-Optimized Commands
@@ -203,6 +218,272 @@ Overall average: **60-90% token reduction** on common development operations.
 <!-- /rtk-instructions -->
 "##;
 
+/// Severity of an environment check result.
+#[derive(Debug, Clone, Copy, PartialEq)]
+enum IssueSeverity {
+    Hard,
+    Soft,
+}
+
+struct EnvIssue {
+    severity: IssueSeverity,
+    problem: String,
+    instructions: Vec<String>,
+    links: Vec<&'static str>,
+}
+
+/// Return shell-specific PATH setup instructions for the user's current shell.
+///
+/// Reads `$SHELL` from the environment and dispatches to per-shell advice.
+/// Falls back to POSIX generic instructions for unknown/missing shells.
+/// This avoids hard-coding zsh/bash assumptions for fish, nushell, elvish, etc.
+#[cfg(unix)]
+fn path_setup_instructions(cargo_bin: &str) -> Vec<String> {
+    let shell = std::env::var("SHELL").unwrap_or_default();
+    let shell_name = std::path::Path::new(&shell)
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or("");
+
+    match shell_name {
+        "zsh" => vec![
+            "Add to ~/.zprofile (login shell — read by non-interactive shells too):".to_owned(),
+            format!(r#"  export PATH="{cargo_bin}:$PATH""#),
+            "Reload: source ~/.zprofile  or open a new terminal".to_owned(),
+        ],
+        "bash" => vec![
+            "Add to ~/.bash_profile (or ~/.profile if that file doesn't exist):".to_owned(),
+            format!(r#"  export PATH="{cargo_bin}:$PATH""#),
+            "Reload: source ~/.bash_profile  or open a new terminal".to_owned(),
+        ],
+        "fish" => vec![
+            "Run once in fish to permanently add Cargo's bin to PATH:".to_owned(),
+            format!("  fish_add_path {cargo_bin}"),
+            "(fish_add_path writes to universal variables — no file edit needed)".to_owned(),
+        ],
+        "nu" | "nush" | "nushell" => vec![
+            "Add to ~/.config/nushell/env.nu:".to_owned(),
+            format!(r#"  $env.PATH = ($env.PATH | split row (char esep) | append "{cargo_bin}")"#),
+            "Then restart nushell or run: source ~/.config/nushell/env.nu".to_owned(),
+        ],
+        _ => vec![
+            format!("Add {cargo_bin} to your shell's PATH (consult your shell's documentation)."),
+            "For POSIX shells (sh, dash, ksh, etc.) add to ~/.profile:".to_owned(),
+            format!(r#"  export PATH="{cargo_bin}:$PATH""#),
+            "Then open a new terminal or reload your profile.".to_owned(),
+        ],
+    }
+}
+
+/// Return advice on where jq PATH must be exported for non-interactive sh invocations.
+/// Claude Code hooks are spawned as login-shell children; they see login-profile PATH,
+/// not interactive-shell PATH (.zshrc, .bashrc). The advice is shell-specific.
+#[cfg(unix)]
+fn jq_path_profile_hint() -> String {
+    let shell = std::env::var("SHELL").unwrap_or_default();
+    let shell_name = std::path::Path::new(&shell)
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or("");
+
+    match shell_name {
+        "zsh" => {
+            "If jq is installed but not detected, ensure it is exported in ~/.zprofile,\n  not only in ~/.zshrc (which is not sourced by non-interactive shells).".to_owned()
+        }
+        "bash" => {
+            "If jq is installed but not detected, ensure it is exported in ~/.bash_profile\n  or ~/.profile, not only in ~/.bashrc.".to_owned()
+        }
+        "fish" => {
+            "If jq is installed but not detected, run: fish_add_path $(which jq | xargs dirname)\n  (fish universal PATH is inherited by subprocesses including Claude Code hooks).".to_owned()
+        }
+        _ => {
+            "If jq is installed but not detected, ensure your shell's login profile exports PATH\n  (not only the interactive rc file). Hook subprocesses use the login-shell environment.".to_owned()
+        }
+    }
+}
+
+/// Run pre-flight environment checks before attempting hook installation.
+///
+/// Checks (in order):
+/// 1. `~/.claude/` directory exists → Claude Code has been launched at least once.
+/// 2. For `HookType::Script`: `jq` is on PATH → required by `rtk-rewrite.sh`.
+/// 3. `rtk hook` subcommand is responsive → correct binary (not reachingforthejack/rtk).
+///
+/// Note: missing `settings.json` is NOT checked here. `patch_settings_shared` creates
+/// it from scratch when absent, so a warning would be noise on new Claude Code installs.
+///
+/// Returns a `Vec<EnvIssue>`. Hard issues mean the caller should bail; soft
+/// issues are printed as warnings and execution continues.
+#[cfg(unix)]
+fn check_environment(hook_type: &HookType) -> Vec<EnvIssue> {
+    let mut issues = Vec::new();
+
+    let claude_dir = match dirs::home_dir() {
+        Some(h) => h.join(".claude"),
+        None => {
+            issues.push(EnvIssue {
+                severity: IssueSeverity::Hard,
+                problem: "$HOME is not set; cannot locate ~/.claude/".to_owned(),
+                instructions: vec![
+                    "Ensure the HOME environment variable points to your home directory."
+                        .to_owned(),
+                ],
+                links: vec![],
+            });
+            return issues;
+        }
+    };
+
+    if !claude_dir.exists() {
+        issues.push(EnvIssue {
+            severity: IssueSeverity::Hard,
+            problem: format!("Claude Code directory not found: {}", claude_dir.display()),
+            instructions: vec![
+                "Install Claude Code if you haven't already.".to_owned(),
+                "Launch Claude Code at least once so it creates its configuration directory."
+                    .to_owned(),
+                "Then re-run: rtk init -g".to_owned(),
+            ],
+            links: vec![
+                "https://code.claude.com/docs/en/",
+                "https://code.claude.com/docs/en/settings",
+            ],
+        });
+        return issues;
+    }
+
+    // jq — required only for Script mode (default on this branch).
+    // Uses `sh -c "command -v jq"` (POSIX built-in; same PATH Claude Code hooks see).
+    // If jq is only in an interactive shell profile (.zshrc, not .zprofile), sh won't
+    // see it — we note this in the instructions to avoid a false Hard failure.
+    if *hook_type == HookType::Script {
+        let jq_found = std::process::Command::new("sh")
+            .args(["-c", "command -v jq"])
+            .output()
+            .map(|o| o.status.success())
+            .unwrap_or(false);
+
+        if !jq_found {
+            let mut instrs = vec![
+                "Install jq using your system package manager:".to_owned(),
+                "  macOS:          brew install jq".to_owned(),
+                "  Ubuntu/Debian:  sudo apt install jq".to_owned(),
+                "  Fedora/RHEL:    sudo dnf install jq".to_owned(),
+                "  Windows (WSL):  sudo apt install jq".to_owned(),
+                jq_path_profile_hint(),
+                "Then re-run: rtk init -g --hook-type script".to_owned(),
+                "Or use the binary hook (no jq needed): rtk init -g --hook-type binary".to_owned(),
+            ];
+            instrs.retain(|s| !s.is_empty());
+            issues.push(EnvIssue {
+                severity: IssueSeverity::Hard,
+                problem: "`jq` not found on PATH (required by rtk-rewrite.sh hook script)"
+                    .to_owned(),
+                instructions: instrs,
+                links: vec![
+                    "https://jqlang.org/download/",
+                    "https://code.claude.com/docs/en/hooks",
+                ],
+            });
+        }
+    }
+
+    // rtk self-check: verify the correct binary is installed.
+    // Two "rtk" packages exist on crates.io:
+    //   - rtk-ai/rtk (Rust Token Killer) — has `rtk hook` subcommand
+    //   - reachingforthejack/rtk (Rust Type Kit) — does NOT
+    // We probe `rtk hook --help` to catch the name-collision case.
+    let rtk_hook_ok = std::process::Command::new("rtk")
+        .args(["hook", "--help"])
+        .output()
+        .map(|o| o.status.success())
+        .unwrap_or(false);
+
+    if !rtk_hook_ok {
+        // Distinguish: rtk not on PATH vs wrong rtk binary.
+        // Use `which rtk` (POSIX, available on macOS and Linux) rather than
+        // `command -v rtk` via sh to avoid spawning an extra shell just for this.
+        let rtk_on_path = std::process::Command::new("which")
+            .arg("rtk")
+            .output()
+            .map(|o| o.status.success())
+            .unwrap_or(false);
+
+        if rtk_on_path {
+            // Found an rtk binary, but it doesn't support `hook` → name collision.
+            issues.push(EnvIssue {
+                severity: IssueSeverity::Hard,
+                problem:
+                    "`rtk` on PATH does not support `hook` subcommand (wrong package installed)"
+                        .to_owned(),
+                instructions: vec![
+                    "Two packages share the name 'rtk' on crates.io:".to_owned(),
+                    "  ✅ rtk-ai/rtk    (Rust Token Killer — this project)".to_owned(),
+                    "  ❌ reachingforthejack/rtk  (Rust Type Kit — unrelated)".to_owned(),
+                    "Uninstall the wrong one:  cargo uninstall rtk".to_owned(),
+                    "Install the correct one:  cargo install --git https://github.com/rtk-ai/rtk"
+                        .to_owned(),
+                    "Verify: rtk --version  (should show 'rtk X.Y.Z')".to_owned(),
+                    "        rtk gain       (should show token savings stats)".to_owned(),
+                ],
+                links: vec!["https://github.com/rtk-ai/rtk"],
+            });
+        } else {
+            // rtk not on PATH at all — provide shell-specific PATH setup instructions.
+            let cargo_bin = dirs::home_dir()
+                .map(|h| h.join(".cargo").join("bin").to_string_lossy().into_owned())
+                .unwrap_or_else(|| "$HOME/.cargo/bin".to_owned());
+            let mut instrs =
+                vec!["Ensure your shell's PATH includes Cargo's bin directory.".to_owned()];
+            instrs.extend(path_setup_instructions(&cargo_bin));
+            instrs.push("Then re-run: rtk init -g".to_owned());
+            issues.push(EnvIssue {
+                severity: IssueSeverity::Hard,
+                problem: "`rtk` not found on PATH after installation".to_owned(),
+                instructions: instrs,
+                links: vec!["https://doc.rust-lang.org/cargo/getting-started/installation.html"],
+            });
+        }
+    }
+
+    issues
+}
+
+/// Print environment issues to stderr with clear formatting.
+/// Returns `true` if any hard issues were found (caller should bail).
+#[cfg(unix)]
+fn report_env_issues(issues: &[EnvIssue]) -> bool {
+    let mut has_hard = false;
+    for issue in issues {
+        let label = match issue.severity {
+            IssueSeverity::Hard => "❌ SETUP REQUIRED",
+            IssueSeverity::Soft => "⚠️  WARNING",
+        };
+        eprintln!("\n{}: {}", label, issue.problem);
+        if !issue.instructions.is_empty() {
+            eprintln!("\n  How to fix:");
+            for (i, step) in issue.instructions.iter().enumerate() {
+                eprintln!("  {}. {}", i + 1, step);
+            }
+        }
+        if !issue.links.is_empty() {
+            eprintln!("\n  Reference:");
+            for link in &issue.links {
+                eprintln!("    → {}", link);
+            }
+        }
+        if issue.severity == IssueSeverity::Hard {
+            has_hard = true;
+        }
+    }
+    if has_hard {
+        eprintln!(
+            "\n💡 Tip: If you need help setting this up, copy the output above and paste it\n   into your AI assistant (e.g., Claude) — it can walk you through the steps.\n"
+        );
+    }
+    has_hard
+}
+
 /// Main entry point for `rtk init`
 #[allow(clippy::too_many_arguments)]
 pub fn run(
@@ -216,6 +497,7 @@ pub fn run(
     hook_only: bool,
     codex: bool,
     patch_mode: PatchMode,
+    hook_type: HookType,
     verbose: u8,
 ) -> Result<()> {
     // Validation: Codex mode conflicts
@@ -265,8 +547,12 @@ pub fn run(
     match (install_claude, install_opencode, claude_md, hook_only) {
         (false, true, _, _) => run_opencode_only_mode(verbose)?,
         (true, opencode, true, _) => run_claude_md_mode(global, verbose, opencode)?,
-        (true, opencode, false, true) => run_hook_only_mode(global, patch_mode, verbose, opencode)?,
-        (true, opencode, false, false) => run_default_mode(global, patch_mode, verbose, opencode)?,
+        (true, opencode, false, true) => {
+            run_hook_only_mode(global, patch_mode, hook_type, verbose, opencode)?
+        }
+        (true, opencode, false, false) => {
+            run_default_mode(global, patch_mode, hook_type, verbose, opencode)?
+        }
         (false, false, _, _) => {
             if !install_cursor {
                 anyhow::bail!("at least one of install_claude or install_opencode must be true")
@@ -292,20 +578,60 @@ fn prepare_hook_paths() -> Result<(PathBuf, PathBuf)> {
     Ok((hook_dir, hook_path))
 }
 
-/// Write hook file if missing or outdated, return true if changed
+/// Extract the handler section between BEGIN/END markers from a script string.
+///
+/// Returns a `&str` slice from "# === BEGIN_RTK_BASH_HANDLERS" through the end of
+/// the "# === END_RTK_BASH_HANDLERS" line (including its trailing newline if present).
+/// EOF-safe: `unwrap_or(content.len())` handles files with no trailing newline.
+fn extract_handler_section(content: &str) -> Option<&str> {
+    const BEGIN: &str = "# === BEGIN_RTK_BASH_HANDLERS";
+    const END: &str = "# === END_RTK_BASH_HANDLERS";
+    let start = content.find(BEGIN)?;
+    let end_rel = content[start..].find(END)?;
+    let end_abs = start + end_rel;
+    // Include the END marker line plus its trailing newline; fall back to EOF if no newline.
+    let section_end = content[end_abs..]
+        .find('\n')
+        .map(|nl| end_abs + nl + 1)
+        .unwrap_or(content.len()); // EOF-safe
+    Some(&content[start..section_end])
+}
+
+/// Merge compiled template with handler section preserved from an existing installed file.
+///
+/// On fresh install (existing has no handler section), returns `REWRITE_HOOK` unchanged.
+/// On upgrade, replaces the template's empty handler section with the existing handlers —
+/// so any entries added by `rtk init` (via `patch_plugin_caches`) survive script upgrades.
+/// Uses `replacen(..., 1)` — simpler than byte-index arithmetic, no off-by-one risk.
+fn merge_hook_with_handlers(existing: &str) -> String {
+    let template_section = extract_handler_section(REWRITE_HOOK)
+        .unwrap_or("# === BEGIN_RTK_BASH_HANDLERS\n# === END_RTK_BASH_HANDLERS\n");
+    match extract_handler_section(existing) {
+        Some(existing_handlers) => REWRITE_HOOK.replacen(template_section, existing_handlers, 1),
+        None => REWRITE_HOOK.to_owned(), // Fresh install: no existing handlers to preserve
+    }
+}
+
+/// Write hook file if missing or outdated, return true if changed.
+///
+/// On upgrade, preserves the BEGIN/END_RTK_BASH_HANDLERS section from the existing
+/// installed file so plugin entries added by `patch_plugin_caches` survive script updates.
 #[cfg(unix)]
 fn ensure_hook_installed(hook_path: &Path, verbose: u8) -> Result<bool> {
     let changed = if hook_path.exists() {
         let existing = fs::read_to_string(hook_path)
             .with_context(|| format!("Failed to read existing hook: {}", hook_path.display()))?;
 
-        if existing == REWRITE_HOOK {
+        // Merge: preserve existing handler section (entries added by patch_plugin_caches)
+        let target = merge_hook_with_handlers(&existing);
+
+        if existing == target {
             if verbose > 0 {
                 eprintln!("Hook already up to date: {}", hook_path.display());
             }
             false
         } else {
-            fs::write(hook_path, REWRITE_HOOK)
+            fs::write(hook_path, &target)
                 .with_context(|| format!("Failed to write hook to {}", hook_path.display()))?;
             if verbose > 0 {
                 eprintln!("Updated hook: {}", hook_path.display());
@@ -397,6 +723,91 @@ fn atomic_write(path: &Path, content: &str) -> Result<()> {
     Ok(())
 }
 
+/// Back up a file to `<filename>.rtk-backup` before RTK modifies it.
+///
+/// Uses "once" semantics: if the backup already exists it is left untouched so
+/// that the backup always reflects the *pre-RTK original*, not some intermediate
+/// state from a previous `rtk init` run.
+///
+/// Non-fatal: a backup failure emits a warning but does not abort the operation.
+/// Returns the backup path (whether it was just created or already existed).
+fn backup_file_once(path: &Path) -> Option<PathBuf> {
+    if !path.exists() {
+        return None;
+    }
+    let backup_name = format!(
+        "{}.rtk-backup",
+        path.file_name().unwrap_or_default().to_string_lossy()
+    );
+    let backup_path = path.with_file_name(backup_name);
+    if !backup_path.exists() {
+        if let Err(e) = fs::copy(path, &backup_path) {
+            eprintln!(
+                "Warning: could not backup {}: {} (continuing without backup)",
+                path.display(),
+                e
+            );
+            return None;
+        }
+    }
+    // Register in the persistent backup list (idempotent — deduplicates on re-run).
+    if let Ok(claude_dir) = resolve_claude_dir() {
+        let registry = claude_dir.join("hooks").join("rtk-backups.json");
+        append_to_backup_registry(&registry, &backup_path);
+    }
+    Some(backup_path)
+}
+
+/// Append a backup path to the persistent registry, deduplicating across re-runs.
+/// Errors are non-fatal: the backup file itself already exists.
+fn append_to_backup_registry(registry_path: &Path, backup_path: &Path) {
+    let backup_str = backup_path.to_string_lossy().into_owned();
+
+    // Read existing entries (empty list if file absent or unparseable).
+    let mut entries: Vec<String> = registry_path
+        .exists()
+        .then(|| fs::read_to_string(registry_path).ok())
+        .flatten()
+        .and_then(|c| serde_json::from_str(&c).ok())
+        .unwrap_or_default();
+
+    // Idempotent: skip if already registered.
+    if entries.iter().any(|e| e == &backup_str) {
+        return;
+    }
+    entries.push(backup_str);
+
+    if let Some(parent) = registry_path.parent() {
+        let _ = fs::create_dir_all(parent);
+    }
+    if let Ok(json) = serde_json::to_string_pretty(&entries) {
+        let _ = atomic_write(registry_path, &json);
+    }
+}
+
+/// Read backup paths from the registry; returns empty vec if absent or unparseable.
+fn read_backup_registry(claude_dir: &Path) -> Vec<String> {
+    let registry_path = claude_dir.join("hooks").join("rtk-backups.json");
+    registry_path
+        .exists()
+        .then(|| fs::read_to_string(&registry_path).ok())
+        .flatten()
+        .and_then(|c| serde_json::from_str(&c).ok())
+        .unwrap_or_default()
+}
+
+/// Print backup registry entries with a context-specific header and per-entry indent.
+/// No-op when the registry is empty or absent.
+fn print_backup_registry(claude_dir: &Path, header: &str, indent: &str) {
+    let backups = read_backup_registry(claude_dir);
+    if !backups.is_empty() {
+        println!("{header}");
+        for p in &backups {
+            println!("{indent}{p}");
+        }
+    }
+}
+
 /// Prompt user for consent to patch settings.json
 /// Prints to stderr (stdout may be piped), reads from stdin
 /// Default is No (capital N)
@@ -459,7 +870,10 @@ fn remove_hook_from_json(root: &mut serde_json::Value) -> bool {
         if let Some(hooks_array) = entry.get("hooks").and_then(|h| h.as_array()) {
             for hook in hooks_array {
                 if let Some(command) = hook.get("command").and_then(|c| c.as_str()) {
-                    if command.contains("rtk-rewrite.sh") {
+                    if command.contains("rtk-rewrite.sh")
+                        || command.contains("rtk hook claude")
+                        || command.contains("rtk-autorun-bash.sh")
+                    {
                         return false; // Remove this entry
                     }
                 }
@@ -497,10 +911,8 @@ fn remove_hook_from_settings(verbose: u8) -> Result<bool> {
     let removed = remove_hook_from_json(&mut root);
 
     if removed {
-        // Backup original
-        let backup_path = settings_path.with_extension("json.bak");
-        fs::copy(&settings_path, &backup_path)
-            .with_context(|| format!("Failed to backup to {}", backup_path.display()))?;
+        // Backup before overwriting (once — preserves pre-RTK original across re-runs).
+        let _ = backup_file_once(&settings_path);
 
         // Atomic write
         let serialized =
@@ -606,7 +1018,79 @@ pub fn uninstall(global: bool, gemini: bool, codex: bool, cursor: bool, verbose:
         }
     }
 
-    // 4. Remove hook entry from settings.json
+    // 4. Restore plugin caches from manifest and remove manifest
+    let manifest_path = claude_dir.join("hooks").join("rtk-bash-manifest.json");
+    if manifest_path.exists() {
+        if let Ok(content) = fs::read_to_string(&manifest_path) {
+            if let Ok(manifest) = serde_json::from_str::<BashManifest>(&content) {
+                for entry in &manifest.entries {
+                    // Restore original_matcher to the cache file
+                    let cache_path = std::path::Path::new(&entry.cache_path);
+                    if cache_path.exists() {
+                        if let Ok(cache_content) = fs::read_to_string(cache_path) {
+                            if let Ok(mut cache_json) =
+                                serde_json::from_str::<serde_json::Value>(&cache_content)
+                            {
+                                let mut matcher_restored = false;
+                                if let Some(pre_tool_use) = cache_json
+                                    .get_mut("hooks")
+                                    .and_then(|h| h.get_mut("PreToolUse"))
+                                    .and_then(|p| p.as_array_mut())
+                                {
+                                    for entry_obj in pre_tool_use.iter_mut() {
+                                        let patched = entry_obj
+                                            .get("matcher")
+                                            .and_then(|m| m.as_str())
+                                            .unwrap_or("")
+                                            .to_string();
+                                        if patched == entry.patched_matcher {
+                                            if let Some(obj) = entry_obj.as_object_mut() {
+                                                obj.insert(
+                                                    "matcher".to_string(),
+                                                    serde_json::Value::String(
+                                                        entry.original_matcher.clone(),
+                                                    ),
+                                                );
+                                            }
+                                            matcher_restored = true;
+                                        }
+                                    }
+                                }
+                                if !matcher_restored {
+                                    eprintln!(
+                                        "Warning: could not restore '{}' — patched matcher '{}' \
+                                         not found. Plugin may have been updated since 'rtk init'.",
+                                        cache_path.display(),
+                                        entry.patched_matcher
+                                    );
+                                }
+                                if let Ok(restored) = serde_json::to_string_pretty(&cache_json) {
+                                    let _ = atomic_write(cache_path, &restored);
+                                    if matcher_restored {
+                                        removed.push(format!(
+                                            "Plugin cache restored: {}",
+                                            cache_path.display()
+                                        ));
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        let _ = fs::remove_file(&manifest_path);
+        removed.push(format!("Manifest: {}", manifest_path.display()));
+    }
+
+    // 5. Remove Part 1 wrapper script (if present)
+    let wrapper_path = claude_dir.join("hooks").join("rtk-autorun-bash.sh");
+    if wrapper_path.exists() {
+        let _ = fs::remove_file(&wrapper_path);
+        removed.push(format!("Wrapper: {}", wrapper_path.display()));
+    }
+
+    // 6. Remove hook entry from settings.json
     if remove_hook_from_settings(verbose)? {
         removed.push("settings.json: removed RTK hook entry".to_string());
     }
@@ -632,6 +1116,13 @@ pub fn uninstall(global: bool, gemini: bool, codex: bool, cursor: bool, verbose:
         println!("\nRestart Claude Code, OpenCode, and Cursor (if used) to apply changes.");
     }
 
+    // Show preserved backups from the registry (never deleted — user's safety net).
+    print_backup_registry(
+        &claude_dir,
+        "\nBackups preserved (originals from before rtk init):",
+        "  ",
+    );
+
     Ok(())
 }
 
@@ -683,14 +1174,19 @@ fn uninstall_codex_at(codex_dir: &Path, verbose: u8) -> Result<Vec<String>> {
 fn patch_settings_json(
     hook_path: &Path,
     mode: PatchMode,
+    hook_type: HookType,
     verbose: u8,
     include_opencode: bool,
 ) -> Result<PatchResult> {
     let claude_dir = resolve_claude_dir()?;
     let settings_path = claude_dir.join("settings.json");
-    let hook_command = hook_path
-        .to_str()
-        .context("Hook path contains invalid UTF-8")?;
+    // Select hook command based on hook_type:
+    //   Script → use the deployed rtk-rewrite.sh path (phased-transition approach)
+    //   Binary → use "rtk hook claude" (fast, no shell dependency)
+    let hook_command: String = match hook_type {
+        HookType::Script => hook_path.to_string_lossy().into_owned(),
+        HookType::Binary => "rtk hook claude".to_owned(),
+    };
 
     // Read or create settings.json
     let mut root = if settings_path.exists() {
@@ -707,8 +1203,12 @@ fn patch_settings_json(
         serde_json::json!({})
     };
 
-    // Check idempotency
-    if hook_already_present(&root, hook_command) {
+    // Remove any stale RTK hooks first (idempotent upgrade path: wrapper -> "rtk hook claude").
+    remove_hook_from_json(&mut root);
+
+    // Check idempotency after removal
+    let cmd = hook_command.as_str();
+    if hook_already_present(&root, cmd) {
         if verbose > 0 {
             eprintln!("settings.json: hook already present");
         }
@@ -733,15 +1233,14 @@ fn patch_settings_json(
     }
 
     // Deep-merge hook
-    insert_hook_entry(&mut root, hook_command);
+    insert_hook_entry(&mut root, cmd)?;
 
     // Backup original
-    if settings_path.exists() {
-        let backup_path = settings_path.with_extension("json.bak");
-        fs::copy(&settings_path, &backup_path)
-            .with_context(|| format!("Failed to backup to {}", backup_path.display()))?;
-        if verbose > 0 {
-            eprintln!("Backup: {}", backup_path.display());
+    // Backup before overwriting (once — preserves pre-RTK original across re-runs).
+    let backup_path = backup_file_once(&settings_path);
+    if verbose > 0 {
+        if let Some(ref bp) = backup_path {
+            eprintln!("Backup: {}", bp.display());
         }
     }
 
@@ -751,11 +1250,8 @@ fn patch_settings_json(
     atomic_write(&settings_path, &serialized)?;
 
     println!("\n  settings.json: hook added");
-    if settings_path.with_extension("json.bak").exists() {
-        println!(
-            "  Backup: {}",
-            settings_path.with_extension("json.bak").display()
-        );
+    if let Some(ref bp) = backup_path {
+        println!("  Backup: {}", bp.display());
     }
     if include_opencode {
         println!("  Restart Claude Code and OpenCode. Test with: git status");
@@ -798,29 +1294,35 @@ fn clean_double_blanks(content: &str) -> String {
 
 /// Deep-merge RTK hook entry into settings.json
 /// Creates hooks.PreToolUse structure if missing, preserves existing hooks
-fn insert_hook_entry(root: &mut serde_json::Value, hook_command: &str) {
-    // Ensure root is an object
-    let root_obj = match root.as_object_mut() {
-        Some(obj) => obj,
-        None => {
-            *root = serde_json::json!({});
-            root.as_object_mut()
-                .expect("Just created object, must succeed")
-        }
-    };
+fn insert_hook_entry(root: &mut serde_json::Value, hook_command: &str) -> Result<()> {
+    if !root.is_object() {
+        *root = serde_json::json!({});
+    }
+    let root_obj = root
+        .as_object_mut()
+        .context("settings.json root is not a JSON object")?;
 
-    // Use entry() API for idiomatic insertion
+    // If 'hooks' exists but isn't an object, overwrite it and warn rather than panic.
+    if root_obj.get("hooks").is_some_and(|v| !v.is_object()) {
+        eprintln!("Warning: settings.json 'hooks' field is not an object; overwriting");
+        root_obj.insert("hooks".to_string(), serde_json::json!({}));
+    }
     let hooks = root_obj
         .entry("hooks")
         .or_insert_with(|| serde_json::json!({}))
         .as_object_mut()
-        .expect("hooks must be an object");
+        .context("settings.json 'hooks' could not be treated as an object")?;
 
+    // Same guard for PreToolUse.
+    if hooks.get("PreToolUse").is_some_and(|v| !v.is_array()) {
+        eprintln!("Warning: settings.json 'hooks.PreToolUse' is not an array; overwriting");
+        hooks.insert("PreToolUse".to_string(), serde_json::json!([]));
+    }
     let pre_tool_use = hooks
         .entry("PreToolUse")
         .or_insert_with(|| serde_json::json!([]))
         .as_array_mut()
-        .expect("PreToolUse must be an array");
+        .context("settings.json 'hooks.PreToolUse' could not be treated as an array")?;
 
     // Append RTK hook entry
     pre_tool_use.push(serde_json::json!({
@@ -830,6 +1332,7 @@ fn insert_hook_entry(root: &mut serde_json::Value, hook_command: &str) {
             "command": hook_command
         }]
     }));
+    Ok(())
 }
 
 /// Check if RTK hook is already present in settings.json
@@ -861,6 +1364,7 @@ fn hook_already_present(root: &serde_json::Value, hook_command: &str) -> bool {
 fn run_default_mode(
     _global: bool,
     _patch_mode: PatchMode,
+    _hook_type: HookType,
     _verbose: u8,
     _install_opencode: bool,
 ) -> Result<()> {
@@ -874,6 +1378,7 @@ fn run_default_mode(
 fn run_default_mode(
     global: bool,
     patch_mode: PatchMode,
+    hook_type: HookType,
     verbose: u8,
     install_opencode: bool,
 ) -> Result<()> {
@@ -884,6 +1389,12 @@ fn run_default_mode(
         return Ok(());
     }
 
+    // Pre-flight: detect unsupportable configurations before modifying anything.
+    let issues = check_environment(&hook_type);
+    if report_env_issues(&issues) {
+        anyhow::bail!("Unsupportable configuration detected. See above for setup instructions.");
+    }
+
     let claude_dir = resolve_claude_dir()?;
     let rtk_md_path = claude_dir.join("RTK.md");
     let claude_md_path = claude_dir.join("CLAUDE.md");
@@ -926,7 +1437,8 @@ fn run_default_mode(
     }
 
     // 5. Patch settings.json
-    let patch_result = patch_settings_json(&hook_path, patch_mode, verbose, install_opencode)?;
+    let patch_result =
+        patch_settings_json(&hook_path, patch_mode, hook_type, verbose, install_opencode)?;
 
     // Report result
     match patch_result {
@@ -946,9 +1458,24 @@ fn run_default_mode(
         }
     }
 
-    // 6. Generate user-global filters template (~/.config/rtk/filters.toml)
+    // 6. Patch plugin caches (remove Bash from matchers, write manifest for fallthrough)
+    if let Err(e) = patch_plugin_caches(verbose) {
+        // Non-fatal: RTK rewrites still work; autorun fallthrough unavailable until re-run
+        if verbose > 0 {
+            eprintln!("Warning: patch_plugin_caches failed: {e}");
+        }
+    }
+
+    // 7. Generate user-global filters template (~/.config/rtk/filters.toml)
     generate_global_filters_template(verbose)?;
 
+    // Show any backups created (or previously created on re-run).
+    print_backup_registry(
+        &claude_dir,
+        "  Backups:   (originals preserved for manual recovery)",
+        "             ",
+    );
+
     println!(); // Final newline
 
     Ok(())
@@ -1008,6 +1535,7 @@ fn generate_global_filters_template(verbose: u8) -> Result<()> {
 fn run_hook_only_mode(
     _global: bool,
     _patch_mode: PatchMode,
+    _hook_type: HookType,
     _verbose: u8,
     _install_opencode: bool,
 ) -> Result<()> {
@@ -1018,6 +1546,7 @@ fn run_hook_only_mode(
 fn run_hook_only_mode(
     global: bool,
     patch_mode: PatchMode,
+    hook_type: HookType,
     verbose: u8,
     install_opencode: bool,
 ) -> Result<()> {
@@ -1027,6 +1556,12 @@ fn run_hook_only_mode(
         return Ok(());
     }
 
+    // Pre-flight: detect unsupportable configurations before modifying anything.
+    let issues = check_environment(&hook_type);
+    if report_env_issues(&issues) {
+        anyhow::bail!("Unsupportable configuration detected. See above for setup instructions.");
+    }
+
     // Prepare and install hook
     let (_hook_dir, hook_path) = prepare_hook_paths()?;
     let hook_changed = ensure_hook_installed(&hook_path, verbose)?;
@@ -1054,7 +1589,8 @@ fn run_hook_only_mode(
     );
 
     // Patch settings.json
-    let patch_result = patch_settings_json(&hook_path, patch_mode, verbose, install_opencode)?;
+    let patch_result =
+        patch_settings_json(&hook_path, patch_mode, hook_type, verbose, install_opencode)?;
 
     // Report result
     match patch_result {
@@ -1074,6 +1610,23 @@ fn run_hook_only_mode(
         }
     }
 
+    // Patch plugin caches (remove Bash from matchers, write manifest for fallthrough)
+    if let Err(e) = patch_plugin_caches(verbose) {
+        if verbose > 0 {
+            eprintln!("Warning: patch_plugin_caches failed: {e}");
+        }
+    }
+
+    // Show any backups created (or previously created on re-run).
+    let claude_dir = resolve_claude_dir()?;
+    let backups = read_backup_registry(&claude_dir);
+    if !backups.is_empty() {
+        println!("  Backups:   (originals preserved for manual recovery)");
+        for p in &backups {
+            println!("             {p}");
+        }
+    }
+
     println!(); // Final newline
 
     Ok(())
@@ -1503,6 +2056,535 @@ fn remove_rtk_block(content: &str) -> (String, bool) {
     }
 }
 
+// =========================================================================
+// PLUGIN CACHE PATCHING
+// Scans ~/.claude/plugins/cache/*/*/hooks/*.json for Bash matchers and
+// removes Bash from them so RTK can be the sole Bash hook responder.
+// Writes ~/.claude/hooks/rtk-bash-manifest.json for uninstall/restore.
+// =========================================================================
+
+/// One entry in the RTK bash manifest
+#[derive(serde::Serialize, serde::Deserialize, Debug, Clone)]
+struct ManifestEntry {
+    cache_path: String,
+    original_matcher: String,
+    patched_matcher: String,
+    fallthrough_command: String,
+}
+
+/// The RTK bash manifest (written by patch_plugin_caches, read by uninstall)
+#[derive(serde::Serialize, serde::Deserialize, Debug)]
+struct BashManifest {
+    #[serde(default = "BashManifest::default_version")]
+    version: u32,
+    #[serde(default)]
+    patched_at: String,
+    #[serde(default)]
+    entries: Vec<ManifestEntry>,
+}
+
+impl Default for BashManifest {
+    fn default() -> Self {
+        Self {
+            version: Self::default_version(),
+            patched_at: String::new(),
+            entries: Vec::new(),
+        }
+    }
+}
+
+impl BashManifest {
+    fn default_version() -> u32 {
+        1
+    }
+}
+
+/// Scan all plugin caches for Bash matchers, remove Bash from each, write manifest.
+/// Returns (newly_patched, already_up_to_date) counts.
+/// Prints a user-visible summary of what changed so the user can verify the install.
+pub(crate) fn patch_plugin_caches(verbose: u8) -> Result<usize> {
+    let claude_dir = resolve_claude_dir()?;
+    let cache_root = claude_dir.join("plugins").join("cache");
+    let manifest_path = claude_dir.join("hooks").join("rtk-bash-manifest.json");
+
+    // Load existing manifest if present (for idempotency); fall back to a fresh one.
+    let mut manifest: BashManifest = manifest_path
+        .exists()
+        .then(|| fs::read_to_string(&manifest_path).ok())
+        .flatten()
+        .and_then(|c| serde_json::from_str(&c).ok())
+        .unwrap_or_default();
+
+    if !cache_root.exists() {
+        if verbose > 0 {
+            eprintln!("Plugin cache directory not found: {}", cache_root.display());
+        }
+        return Ok(0);
+    }
+
+    // Settings JSON for CLAUDE_PLUGIN_ROOT resolution
+    let settings_path = claude_dir.join("settings.json");
+    let settings_root: serde_json::Value = if settings_path.exists() {
+        let content = fs::read_to_string(&settings_path).unwrap_or_default();
+        serde_json::from_str(&content).unwrap_or(serde_json::json!({}))
+    } else {
+        serde_json::json!({})
+    };
+
+    let mut newly_patched = 0usize;
+    let mut already_present = 0usize;
+
+    // Walk cache/*/*/hooks/*.json
+    // Structure: cache/{vendor}/{plugin}/{version}/hooks/{file}.json
+    let vendors = match fs::read_dir(&cache_root) {
+        Ok(d) => d,
+        Err(_) => return Ok(0),
+    };
+
+    for vendor_entry in vendors.flatten() {
+        let vendor_path = vendor_entry.path();
+        if !vendor_path.is_dir() {
+            continue;
+        }
+        let vendor_name = vendor_path
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("")
+            .to_string();
+
+        let plugins = match fs::read_dir(&vendor_path) {
+            Ok(d) => d,
+            Err(_) => continue,
+        };
+
+        for plugin_entry in plugins.flatten() {
+            let plugin_path = plugin_entry.path();
+            if !plugin_path.is_dir() {
+                continue;
+            }
+            let plugin_name = plugin_path
+                .file_name()
+                .and_then(|n| n.to_str())
+                .unwrap_or("")
+                .to_string();
+
+            let versions = match fs::read_dir(&plugin_path) {
+                Ok(d) => d,
+                Err(_) => continue,
+            };
+
+            // Collect version directories and sort by semver (descending).
+            // Claude Code loads the highest version; RTK should only process
+            // that one. Old versions stay on disk for rollback but don't get
+            // manifest entries (avoids double-execution via direct + fallthrough).
+            let mut version_dirs: Vec<PathBuf> = versions
+                .flatten()
+                .map(|e| e.path())
+                .filter(|p| p.is_dir())
+                .collect();
+            version_dirs.sort_by(|a, b| {
+                let va = parse_semver(a.file_name().and_then(|n| n.to_str()).unwrap_or(""));
+                let vb = parse_semver(b.file_name().and_then(|n| n.to_str()).unwrap_or(""));
+                vb.cmp(&va) // Descending: highest version first
+            });
+
+            // Only process the highest (active) version.
+            // Remove manifest entries for older versions of this plugin
+            // (they'd cause double-execution if the active version changed).
+            // Trailing separator ensures we don't match "ar2" when looking for "ar".
+            let plugin_prefix = format!("{}/", plugin_path.to_string_lossy());
+            if let Some(active_version) = version_dirs.first() {
+                let active_prefix = format!("{}/", active_version.to_string_lossy());
+
+                // Remove entries for NON-active versions of this plugin
+                let before_retain = manifest.entries.len();
+                manifest.entries.retain(|e| {
+                    !e.cache_path.starts_with(&plugin_prefix)
+                        || e.cache_path.starts_with(&active_prefix)
+                });
+                if manifest.entries.len() < before_retain && verbose > 0 {
+                    eprintln!(
+                        "Removed {} stale manifest entries for {}/{} (not active version)",
+                        before_retain - manifest.entries.len(),
+                        vendor_name,
+                        plugin_name
+                    );
+                }
+
+                // Process the active version's hook files
+                let hooks_dir = active_version.join("hooks");
+                if !hooks_dir.exists() {
+                    continue;
+                }
+
+                let hook_files = match fs::read_dir(&hooks_dir) {
+                    Ok(d) => d,
+                    Err(_) => continue,
+                };
+
+                for hook_file in hook_files.flatten() {
+                    let hook_path = hook_file.path();
+                    if hook_path.extension().and_then(|e| e.to_str()) != Some("json") {
+                        continue;
+                    }
+
+                    // Check before calling: was this file already patched by a previous run?
+                    let in_manifest = manifest
+                        .entries
+                        .iter()
+                        .any(|e| e.cache_path == hook_path.to_string_lossy().as_ref());
+
+                    match patch_single_cache_file(
+                        &hook_path,
+                        &vendor_name,
+                        &plugin_name,
+                        &settings_root,
+                        &mut manifest,
+                        verbose,
+                    ) {
+                        Ok(true) => newly_patched += 1,
+                        // Only count as "already up-to-date" if it was in the manifest.
+                        // Files that never had Bash are silently ignored (not confusing to users).
+                        Ok(false) if in_manifest => already_present += 1,
+                        Ok(false) => {} // No Bash matcher found; not our concern
+                        Err(e) => {
+                            eprintln!("Warning: failed to patch {}: {}", hook_path.display(), e);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    // Write updated manifest
+    if !manifest.entries.is_empty() {
+        manifest.patched_at = chrono::Utc::now().to_rfc3339();
+        manifest.version = 1;
+        let manifest_json =
+            serde_json::to_string_pretty(&manifest).context("Failed to serialize manifest")?;
+        // Ensure hooks dir exists
+        if let Some(parent) = manifest_path.parent() {
+            fs::create_dir_all(parent).with_context(|| {
+                format!("Failed to create hooks directory: {}", parent.display())
+            })?;
+        }
+        atomic_write(&manifest_path, &manifest_json)?;
+        if verbose > 0 {
+            eprintln!("Manifest written: {}", manifest_path.display());
+        }
+    }
+
+    // Always print a summary so the user can verify the install state.
+    if newly_patched > 0 {
+        println!(
+            "  Plugin caches: {} patched, {} already up-to-date",
+            newly_patched, already_present
+        );
+        for entry in &manifest.entries {
+            println!("    Patched: {}", entry.cache_path);
+            // Show backup path if it exists alongside the patched file
+            let bp_name = format!(
+                "{}.rtk-backup",
+                Path::new(&entry.cache_path)
+                    .file_name()
+                    .unwrap_or_default()
+                    .to_string_lossy()
+            );
+            let bp = Path::new(&entry.cache_path).with_file_name(bp_name);
+            if bp.exists() {
+                println!("    Backup:  {}", bp.display());
+            }
+            println!(
+                "      Matcher: \"{}\" → \"{}\"",
+                entry.original_matcher, entry.patched_matcher
+            );
+            println!("      Fallthrough: {}", entry.fallthrough_command);
+        }
+        println!("  Manifest: {}", manifest_path.display());
+        println!("  Re-run 'rtk init --global' after any plugin update to keep caches in sync.");
+    } else if already_present > 0 {
+        println!(
+            "  Plugin caches: {} already up-to-date (re-run safe)",
+            already_present
+        );
+    }
+
+    Ok(newly_patched)
+}
+
+/// Patch a single plugin cache JSON file: remove Bash from PreToolUse matchers.
+/// Appends to manifest if changed and not already present.
+/// Returns Ok(true) if the manifest was updated (newly patched or reconstructed),
+/// Ok(false) if already present or no PreToolUse hooks found.
+fn patch_single_cache_file(
+    hook_path: &Path,
+    vendor_name: &str,
+    plugin_name: &str,
+    settings_root: &serde_json::Value,
+    manifest: &mut BashManifest,
+    verbose: u8,
+) -> Result<bool> {
+    let content = fs::read_to_string(hook_path)
+        .with_context(|| format!("Failed to read {}", hook_path.display()))?;
+
+    let mut json: serde_json::Value = serde_json::from_str(&content)
+        .with_context(|| format!("Failed to parse {}", hook_path.display()))?;
+
+    // Pre-compute owned string once — used for idempotency check and ManifestEntry below.
+    let cache_path_str = hook_path.to_string_lossy().into_owned();
+
+    // Already in manifest with same path? Skip (idempotent second run).
+    if manifest
+        .entries
+        .iter()
+        .any(|e| e.cache_path == cache_path_str)
+    {
+        return Ok(false);
+    }
+
+    let pre_tool_use = match json
+        .get_mut("hooks")
+        .and_then(|h| h.get_mut("PreToolUse"))
+        .and_then(|p| p.as_array_mut())
+    {
+        Some(arr) => arr,
+        None => return Ok(false), // No PreToolUse hooks → nothing to register
+    };
+
+    // Check whether any entry still has Bash in its matcher.
+    // If Bash is present → first-run path: patch the file and add to manifest.
+    // If no Bash anywhere → reconstruction path: Bash was already removed by a prior
+    //   rtk init that didn't create a backup file. Register the current PreToolUse
+    //   entries in the manifest so the binary hook still calls them as fallthrough
+    //   handlers for Bash events. Safe for uninstall: original_matcher == patched_matcher
+    //   so the restore is a write-back no-op (same value written). If the plugin never
+    //   actually handled Bash, it will return exit 0 (pass-through) when called.
+    let has_any_bash = pre_tool_use
+        .iter()
+        .any(|e| matcher_contains_bash(e.get("matcher").and_then(|m| m.as_str()).unwrap_or("")));
+
+    if !has_any_bash {
+        // Reconstruction path: no Bash in any entry. Add all non-empty matchers to
+        // manifest so fallthrough mechanism includes this plugin's Bash event handling.
+        let mut any_added = false;
+        for entry in pre_tool_use.iter() {
+            let matcher = entry
+                .get("matcher")
+                .and_then(|m| m.as_str())
+                .unwrap_or("")
+                .to_string();
+            if matcher.is_empty() {
+                continue;
+            }
+            let command = entry
+                .get("hooks")
+                .and_then(|h| h.as_array())
+                .and_then(|arr| arr.first())
+                .and_then(|h| h.get("command"))
+                .and_then(|c| c.as_str())
+                .unwrap_or("")
+                .to_string();
+            let resolved_command =
+                resolve_plugin_root_in_command(&command, vendor_name, plugin_name, settings_root);
+            if verbose > 0 {
+                eprintln!(
+                    "Reconstructed manifest entry for '{}' (Bash already removed)",
+                    hook_path.display()
+                );
+            }
+            manifest.entries.push(ManifestEntry {
+                cache_path: cache_path_str.clone(),
+                original_matcher: matcher.clone(), // unknown true original; use current
+                patched_matcher: matcher,          // same → uninstall restore is a no-op
+                fallthrough_command: resolved_command,
+            });
+            any_added = true;
+        }
+        return Ok(any_added);
+    }
+
+    // First-run path: at least one entry has Bash. Patch the file.
+    let mut any_patched = false;
+
+    for entry in pre_tool_use.iter_mut() {
+        // Immutable read phase: extract matcher and command before any mutable borrows.
+        let matcher = entry
+            .get("matcher")
+            .and_then(|m| m.as_str())
+            .unwrap_or("")
+            .to_string();
+
+        if !matcher_contains_bash(&matcher) {
+            continue;
+        }
+
+        // Read command from the first hook entry (immutable).
+        let command = entry
+            .get("hooks")
+            .and_then(|h| h.as_array())
+            .and_then(|arr| arr.first())
+            .and_then(|h| h.get("command"))
+            .and_then(|c| c.as_str())
+            .unwrap_or("")
+            .to_string();
+
+        // Resolve CLAUDE_PLUGIN_ROOT in command
+        let resolved_command =
+            resolve_plugin_root_in_command(&command, vendor_name, plugin_name, settings_root);
+        let new_matcher = remove_bash_from_matcher(&matcher);
+
+        // Guard: if Bash was the only token, the result would be an empty matcher string.
+        // Writing "" back would make Claude Code match the entry against no tools at all,
+        // silently disabling all non-Bash functionality of this plugin hook entry.
+        // Skip patching this entry; log a warning so the user can investigate.
+        if new_matcher.is_empty() {
+            if verbose > 0 || cfg!(test) {
+                eprintln!(
+                    "Warning: skipping '{}' — matcher '{}' contains only Bash; \
+                     cannot patch without breaking the entry.",
+                    hook_path.display(),
+                    matcher
+                );
+            }
+            continue;
+        }
+
+        // Mutable write phase: all reads done, no conflicting borrows.
+        if let Some(entry_obj) = entry.as_object_mut() {
+            entry_obj.insert(
+                "matcher".to_string(),
+                serde_json::Value::String(new_matcher.clone()),
+            );
+        }
+
+        manifest.entries.push(ManifestEntry {
+            cache_path: cache_path_str.clone(),
+            original_matcher: matcher,
+            patched_matcher: new_matcher,
+            fallthrough_command: resolved_command,
+        });
+
+        any_patched = true;
+    }
+
+    if any_patched {
+        // Backup before overwriting (once — preserves pre-RTK original across re-runs).
+        let _ = backup_file_once(hook_path);
+
+        let patched = serde_json::to_string_pretty(&json)
+            .context("Failed to serialize patched cache JSON")?;
+        atomic_write(hook_path, &patched)?;
+        if verbose > 0 {
+            eprintln!("Patched: {}", hook_path.display());
+        }
+    }
+
+    Ok(any_patched)
+}
+
+/// Parse a semver-like version string into (major, minor, patch) for comparison.
+/// Non-numeric or missing components default to 0.
+fn parse_semver(s: &str) -> (u32, u32, u32) {
+    let parts: Vec<u32> = s.split('.').filter_map(|p| p.parse().ok()).collect();
+    (
+        parts.first().copied().unwrap_or(0),
+        parts.get(1).copied().unwrap_or(0),
+        parts.get(2).copied().unwrap_or(0),
+    )
+}
+
+/// Returns true if a matcher string contains "Bash" as a whole token
+fn matcher_contains_bash(matcher: &str) -> bool {
+    matcher.split('|').any(|part| part.trim() == "Bash")
+}
+
+/// Remove "Bash" from a pipe-separated matcher string
+/// e.g. "Write|Edit|Bash|ExitPlanMode" -> "Write|Edit|ExitPlanMode"
+fn remove_bash_from_matcher(matcher: &str) -> String {
+    matcher
+        .split('|')
+        .filter(|part| part.trim() != "Bash")
+        .collect::<Vec<_>>()
+        .join("|")
+}
+
+/// Resolve ${CLAUDE_PLUGIN_ROOT} in a command string to an absolute path.
+/// Looks up the vendor in extraKnownMarketplaces in settings.json.
+fn resolve_plugin_root_in_command(
+    command: &str,
+    vendor_name: &str,
+    plugin_name: &str,
+    settings_root: &serde_json::Value,
+) -> String {
+    if !command.contains("${CLAUDE_PLUGIN_ROOT}") {
+        return command.to_string();
+    }
+
+    // Try extraKnownMarketplaces first
+    if let Some(marketplace_path) = settings_root
+        .get("extraKnownMarketplaces")
+        .and_then(|m| m.get(vendor_name))
+        .and_then(|v| v.get("source"))
+        .and_then(|s| s.get("path"))
+        .and_then(|p| p.as_str())
+    {
+        // Try computed path: {marketplace}/plugins/{plugin_name}
+        let primary = format!("{}/plugins/{}", marketplace_path, plugin_name);
+        if Path::new(&primary).exists() {
+            return command.replace("${CLAUDE_PLUGIN_ROOT}", &primary);
+        }
+
+        // Fallback 1: {marketplace}/plugins/{vendor_name}
+        // Plugin package name (e.g. "ar") may differ from source dir (e.g. "autorun").
+        let by_vendor = format!("{}/plugins/{}", marketplace_path, vendor_name);
+        if Path::new(&by_vendor).exists() {
+            return command.replace("${CLAUDE_PLUGIN_ROOT}", &by_vendor);
+        }
+
+        // Fallback 2: scan immediate subdirs of {marketplace}/plugins/ for first
+        // dir that contains a hooks/ subdirectory (plugin source convention).
+        let plugins_dir = format!("{}/plugins", marketplace_path);
+        if let Ok(entries) = fs::read_dir(&plugins_dir) {
+            for entry in entries.flatten() {
+                let p = entry.path();
+                if p.is_dir()
+                    && p.join("hooks").is_dir()
+                    && !p
+                        .file_name()
+                        .and_then(|n| n.to_str())
+                        .map(|n| n.starts_with('.') || n == "__pycache__" || n.contains("venv"))
+                        .unwrap_or(false)
+                {
+                    return command
+                        .replace("${CLAUDE_PLUGIN_ROOT}", &p.to_string_lossy().into_owned());
+                }
+            }
+        }
+
+        // None of the fallbacks found — use computed primary (will fail at runtime)
+        return command.replace("${CLAUDE_PLUGIN_ROOT}", &primary);
+    }
+
+    // Fall back to standard marketplace location
+    if let Ok(claude_dir) = resolve_claude_dir() {
+        let standard_root = claude_dir
+            .join("plugins")
+            .join(vendor_name)
+            .join(plugin_name);
+        if standard_root.exists() {
+            return command.replace("${CLAUDE_PLUGIN_ROOT}", &standard_root.to_string_lossy());
+        }
+    }
+
+    // Cannot resolve; log and return original (will fail at runtime, but non-blocking)
+    eprintln!(
+        "Warning: cannot resolve CLAUDE_PLUGIN_ROOT for vendor={} plugin={}. \
+         Fallthrough command will not work until re-run after plugin source is found.",
+        vendor_name, plugin_name
+    );
+    command.to_string()
+}
+
 /// Resolve ~/.claude directory with proper home expansion
 fn resolve_claude_dir() -> Result<PathBuf> {
     dirs::home_dir()
@@ -2343,10 +3425,11 @@ mod tests {
 
     #[test]
     fn test_hook_has_guards() {
+        // Shell hook kept for backward compatibility during transition to Rust hook engine.
+        // Users can use either the shell hook or `rtk hook claude` binary.
         assert!(REWRITE_HOOK.contains("command -v rtk"));
         assert!(REWRITE_HOOK.contains("command -v jq"));
         // Guards (rtk/jq availability checks) must appear before the actual delegation call.
-        // The thin delegating hook no longer uses set -euo pipefail.
         let jq_pos = REWRITE_HOOK.find("command -v jq").unwrap();
         let rtk_delegate_pos = REWRITE_HOOK.find("rtk rewrite \"$CMD\"").unwrap();
         assert!(
@@ -2355,6 +3438,66 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_extract_handler_section_normal() {
+        let content =
+            "before\n# === BEGIN_RTK_BASH_HANDLERS\nhello\n# === END_RTK_BASH_HANDLERS\nafter\n";
+        let section = extract_handler_section(content).expect("should find section");
+        assert!(section.starts_with("# === BEGIN_RTK_BASH_HANDLERS"));
+        assert!(section.contains("# === END_RTK_BASH_HANDLERS"));
+        assert!(
+            !section.contains("after"),
+            "section should not include content after END marker"
+        );
+    }
+
+    #[test]
+    fn test_extract_handler_section_eof_no_newline() {
+        // EOF-safety: file ends exactly at END marker with no trailing newline
+        let content = "before\n# === BEGIN_RTK_BASH_HANDLERS\n# === END_RTK_BASH_HANDLERS";
+        let section = extract_handler_section(content);
+        assert!(
+            section.is_some(),
+            "should handle EOF without trailing newline"
+        );
+        assert!(section.unwrap().ends_with("END_RTK_BASH_HANDLERS"));
+    }
+
+    #[test]
+    fn test_extract_handler_section_missing_returns_none() {
+        let content = "#!/bin/bash\n# No handlers section here\nexit 0\n";
+        assert!(extract_handler_section(content).is_none());
+    }
+
+    #[test]
+    fn test_merge_hook_with_handlers_preserves_handlers() {
+        // Helper using inline template (not REWRITE_HOOK) for determinism
+        // merge_hook_with_handlers uses REWRITE_HOOK directly, so we test via a
+        // mock: simulate a REWRITE_HOOK with the markers and an existing file with content
+        let existing = "prefix\n# === BEGIN_RTK_BASH_HANDLERS\nhandler_cmd &\n# === END_RTK_BASH_HANDLERS\nsuffix\n";
+        // extract_handler_section on existing should find the handler
+        let section = extract_handler_section(existing).expect("existing has section");
+        assert!(section.contains("handler_cmd &"));
+        // Verify replacen approach: template section replaced by existing handlers
+        let template_section = "# === BEGIN_RTK_BASH_HANDLERS\n# === END_RTK_BASH_HANDLERS\n";
+        let fake_template = format!("prefix\n{template_section}suffix\n");
+        let result = fake_template.replacen(template_section, section, 1);
+        assert!(result.contains("handler_cmd &"));
+        assert!(result.contains("prefix"));
+        assert!(result.contains("suffix"));
+    }
+
+    #[test]
+    fn test_merge_hook_with_handlers_fresh_install() {
+        // When existing has no handler section, merge returns REWRITE_HOOK unchanged
+        let existing_no_markers = "#!/bin/bash\n# Old version without markers\nexit 0\n";
+        let result = merge_hook_with_handlers(existing_no_markers);
+        assert_eq!(
+            result, REWRITE_HOOK,
+            "fresh install returns template unchanged"
+        );
+    }
+
     #[test]
     fn test_migration_removes_old_block() {
         let input = r#"# My Config
@@ -2533,6 +3676,7 @@ More notes
             false,
             true,
             PatchMode::Auto,
+            HookType::Script,
             0,
         )
         .unwrap_err();
@@ -2555,6 +3699,7 @@ More notes
             false,
             true,
             PatchMode::Skip,
+            HookType::Script,
             0,
         )
         .unwrap_err();
@@ -2697,7 +3842,7 @@ More notes
         let mut json_content = serde_json::json!({});
         let hook_command = "/Users/test/.claude/hooks/rtk-rewrite.sh";
 
-        insert_hook_entry(&mut json_content, hook_command);
+        insert_hook_entry(&mut json_content, hook_command).unwrap();
 
         // Should create full structure
         assert!(json_content.get("hooks").is_some());
@@ -2729,7 +3874,7 @@ More notes
         });
 
         let hook_command = "/Users/test/.claude/hooks/rtk-rewrite.sh";
-        insert_hook_entry(&mut json_content, hook_command);
+        insert_hook_entry(&mut json_content, hook_command).unwrap();
 
         let pre_tool_use = json_content["hooks"]["PreToolUse"].as_array().unwrap();
         assert_eq!(pre_tool_use.len(), 2); // Should have both hooks
@@ -2752,7 +3897,7 @@ More notes
         });
 
         let hook_command = "/Users/test/.claude/hooks/rtk-rewrite.sh";
-        insert_hook_entry(&mut json_content, hook_command);
+        insert_hook_entry(&mut json_content, hook_command).unwrap();
 
         // Should preserve all other keys
         assert_eq!(json_content["env"]["PATH"], "/custom/path");
@@ -2784,12 +3929,8 @@ More notes
         let parsed: serde_json::Value = serde_json::from_str(original).unwrap();
         let serialized = serde_json::to_string(&parsed).unwrap();
 
-        // Keys should appear in same order
-        let _original_keys: Vec<&str> = original.split("\"").filter(|s| s.contains(":")).collect();
-        let _serialized_keys: Vec<&str> =
-            serialized.split("\"").filter(|s| s.contains(":")).collect();
-
-        // Just check that keys exist (preserve_order doesn't guarantee exact order in nested objects)
+        // Verify key preservation by checking keys exist in serialized output
+        // (preserve_order doesn't guarantee exact order in nested objects)
         assert!(serialized.contains("\"env\""));
         assert!(serialized.contains("\"permissions\""));
         assert!(serialized.contains("\"model\""));
@@ -2868,7 +4009,196 @@ More notes
         assert!(!removed);
     }
 
-    // ─── Cursor hooks.json tests ───
+    // --- patch_single_cache_file tests ---
+
+    fn make_cache_json(matcher: &str, command: &str) -> serde_json::Value {
+        serde_json::json!({
+            "hooks": {
+                "PreToolUse": [{
+                    "matcher": matcher,
+                    "hooks": [{"type": "command", "command": command}]
+                }]
+            }
+        })
+    }
+
+    #[test]
+    fn test_patch_single_cache_file_first_run_bash_removed() {
+        let temp = TempDir::new().unwrap();
+        let hook_file = temp.path().join("claude-hooks.json");
+        let json = make_cache_json("Bash|Write|Edit", "my-hook --cli claude");
+        fs::write(&hook_file, serde_json::to_string_pretty(&json).unwrap()).unwrap();
+
+        let mut manifest = BashManifest::default();
+        let settings = serde_json::json!({});
+        let result =
+            patch_single_cache_file(&hook_file, "vendor", "plugin", &settings, &mut manifest, 0);
+
+        assert!(result.unwrap(), "should return true when Bash removed");
+        assert_eq!(manifest.entries.len(), 1);
+        assert_eq!(manifest.entries[0].original_matcher, "Bash|Write|Edit");
+        assert_eq!(manifest.entries[0].patched_matcher, "Write|Edit");
+        assert_eq!(
+            manifest.entries[0].fallthrough_command,
+            "my-hook --cli claude"
+        );
+
+        // Verify file was actually patched
+        let patched: serde_json::Value =
+            serde_json::from_str(&fs::read_to_string(&hook_file).unwrap()).unwrap();
+        let matcher = patched["hooks"]["PreToolUse"][0]["matcher"]
+            .as_str()
+            .unwrap();
+        assert_eq!(matcher, "Write|Edit");
+    }
+
+    #[test]
+    fn test_patch_single_cache_file_reconstruction_no_bash() {
+        // Bash was already removed; no backup exists. Should reconstruct manifest entry.
+        let temp = TempDir::new().unwrap();
+        let hook_file = temp.path().join("claude-hooks.json");
+        let json = make_cache_json("Write|Edit|ExitPlanMode", "autorun-hook --cli claude");
+        fs::write(&hook_file, serde_json::to_string_pretty(&json).unwrap()).unwrap();
+
+        let mut manifest = BashManifest::default();
+        let settings = serde_json::json!({});
+        let result =
+            patch_single_cache_file(&hook_file, "vendor", "plugin", &settings, &mut manifest, 0);
+
+        assert!(result.unwrap(), "should return true for reconstruction");
+        assert_eq!(manifest.entries.len(), 1);
+        // original_matcher == patched_matcher (safe uninstall no-op)
+        assert_eq!(
+            manifest.entries[0].original_matcher,
+            manifest.entries[0].patched_matcher
+        );
+        assert_eq!(
+            manifest.entries[0].patched_matcher,
+            "Write|Edit|ExitPlanMode"
+        );
+        assert_eq!(
+            manifest.entries[0].fallthrough_command,
+            "autorun-hook --cli claude"
+        );
+
+        // File should NOT be modified (no Bash to remove)
+        let after: serde_json::Value =
+            serde_json::from_str(&fs::read_to_string(&hook_file).unwrap()).unwrap();
+        let matcher = after["hooks"]["PreToolUse"][0]["matcher"].as_str().unwrap();
+        assert_eq!(
+            matcher, "Write|Edit|ExitPlanMode",
+            "file should be unchanged"
+        );
+    }
+
+    #[test]
+    fn test_patch_single_cache_file_idempotent_with_manifest() {
+        let temp = TempDir::new().unwrap();
+        let hook_file = temp.path().join("claude-hooks.json");
+        let json = make_cache_json("Write|Edit|ExitPlanMode", "cmd");
+        fs::write(&hook_file, serde_json::to_string_pretty(&json).unwrap()).unwrap();
+
+        let cache_path_str = hook_file.to_string_lossy().into_owned();
+        let mut manifest = BashManifest::default();
+        // Pre-populate manifest as if first run already completed
+        manifest.entries.push(ManifestEntry {
+            cache_path: cache_path_str,
+            original_matcher: "Write|Edit|ExitPlanMode".to_string(),
+            patched_matcher: "Write|Edit|ExitPlanMode".to_string(),
+            fallthrough_command: "cmd".to_string(),
+        });
+
+        let settings = serde_json::json!({});
+        let result =
+            patch_single_cache_file(&hook_file, "vendor", "plugin", &settings, &mut manifest, 0);
+
+        assert!(
+            !result.unwrap(),
+            "should return false (already in manifest)"
+        );
+        assert_eq!(
+            manifest.entries.len(),
+            1,
+            "no new entry added on second run"
+        );
+    }
+
+    #[test]
+    fn test_patch_single_cache_file_no_pretooluse() {
+        let temp = TempDir::new().unwrap();
+        let hook_file = temp.path().join("claude-hooks.json");
+        let json = serde_json::json!({"hooks": {"PostToolUse": []}});
+        fs::write(&hook_file, serde_json::to_string_pretty(&json).unwrap()).unwrap();
+
+        let mut manifest = BashManifest::default();
+        let settings = serde_json::json!({});
+        let result =
+            patch_single_cache_file(&hook_file, "vendor", "plugin", &settings, &mut manifest, 0);
+
+        assert!(!result.unwrap(), "should return false (no PreToolUse)");
+        assert!(manifest.entries.is_empty());
+    }
+
+    #[test]
+    fn test_parse_semver() {
+        assert_eq!(parse_semver("0.9.0"), (0, 9, 0));
+        assert_eq!(parse_semver("0.10.0"), (0, 10, 0));
+        assert_eq!(parse_semver("1.2.3"), (1, 2, 3));
+        assert_eq!(parse_semver("invalid"), (0, 0, 0));
+        assert_eq!(parse_semver(""), (0, 0, 0));
+        // Semver comparison: 0.10.0 > 0.9.0
+        assert!(parse_semver("0.10.0") > parse_semver("0.9.0"));
+    }
+
+    #[test]
+    fn test_catch_all_not_registered_as_fallthrough() {
+        // A catch-all PreToolUse (no matcher field) should NOT create a manifest entry.
+        let temp = TempDir::new().unwrap();
+        let hook_file = temp.path().join("claude-hooks.json");
+        let json = serde_json::json!({
+            "hooks": {
+                "PreToolUse": [{
+                    "hooks": [{"type": "command", "command": "my-hook --cli claude"}]
+                }]
+            }
+        });
+        fs::write(&hook_file, serde_json::to_string_pretty(&json).unwrap()).unwrap();
+
+        let mut manifest = BashManifest::default();
+        let settings = serde_json::json!({});
+        let result =
+            patch_single_cache_file(&hook_file, "vendor", "plugin", &settings, &mut manifest, 0);
+        assert!(
+            !result.unwrap(),
+            "catch-all should not create manifest entry"
+        );
+        assert!(manifest.entries.is_empty(), "no fallthrough for catch-all");
+    }
+
+    #[test]
+    fn test_version_dedup_removes_older_entries() {
+        // When processing the highest version, older version entries should be removed.
+        let mut manifest = BashManifest::default();
+        manifest.entries.push(ManifestEntry {
+            cache_path: "/cache/autorun/ar/0.9.0/hooks/claude-hooks.json".into(),
+            original_matcher: "Write|Edit|ExitPlanMode".into(),
+            patched_matcher: "Write|Edit|ExitPlanMode".into(),
+            fallthrough_command: "some-command".into(),
+        });
+
+        // Trailing '/' prevents matching "ar2" when looking for "ar"
+        let plugin_prefix = "/cache/autorun/ar/";
+        let active_prefix = "/cache/autorun/ar/0.10.0/";
+
+        // Retain only entries for the active version
+        manifest.entries.retain(|e| {
+            !e.cache_path.starts_with(plugin_prefix) || e.cache_path.starts_with(active_prefix)
+        });
+
+        assert!(manifest.entries.is_empty(), "0.9.0 entry should be removed");
+    }
+
+    // --- Cursor hooks.json tests ---
 
     #[test]
     fn test_cursor_hook_already_present_true() {
diff --git a/src/main.rs b/src/main.rs
index 2bbc4bb2d..41a11ccd8 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -3,6 +3,7 @@ mod binlog;
 mod cargo_cmd;
 mod cc_economics;
 mod ccusage;
+mod cmd;
 mod config;
 mod container;
 mod curl_cmd;
@@ -40,6 +41,7 @@ mod next_cmd;
 mod npm_cmd;
 mod parser;
 mod pip_cmd;
+mod pipe_cmd;
 mod playwright_cmd;
 mod pnpm_cmd;
 mod prettier_cmd;
@@ -51,6 +53,7 @@ mod rewrite_cmd;
 mod ruff_cmd;
 mod runner;
 mod session_cmd;
+mod stream;
 mod summary;
 mod tee;
 mod telemetry;
@@ -106,6 +109,10 @@ struct Cli {
     /// Set SKIP_ENV_VALIDATION=1 for child processes (Next.js, tsc, lint, prisma)
     #[arg(long = "skip-env", global = true)]
     skip_env: bool,
+
+    /// Passthrough mode: emit raw output without RTK filtering
+    #[arg(long, global = true)]
+    passthrough: bool,
 }
 
 #[derive(Subcommand)]
@@ -331,7 +338,13 @@ enum Commands {
         /// Show line numbers (always on, accepted for grep/rg compatibility)
         #[arg(short = 'n', long)]
         line_numbers: bool,
-        /// Extra ripgrep arguments (e.g., -i, -A 3, -w, --glob)
+        /// Case insensitive (grep -i)
+        #[arg(short = 'i', long = "ignore-case")]
+        ignore_case: bool,
+        /// Word boundary (grep -w)
+        #[arg(short = 'w', long = "word-regexp")]
+        word_regexp: bool,
+        /// Extra ripgrep arguments (e.g., --glob)
         #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
         extra_args: Vec<String>,
     },
@@ -378,6 +391,10 @@ enum Commands {
         #[arg(long)]
         uninstall: bool,
 
+        /// Hook type to install: "script" (rtk-rewrite.sh, default) or "binary" (rtk hook claude)
+        #[arg(long = "hook-type", value_enum, default_value_t = init::HookType::Script)]
+        hook_type: init::HookType,
+
         /// Target Codex CLI (uses AGENTS.md + RTK.md, no Claude hook patching)
         #[arg(long)]
         codex: bool,
@@ -600,6 +617,16 @@ enum Commands {
         args: Vec<OsString>,
     },
 
+    /// Read stdin and reduce tokens (pipe-as-filter mode)
+    Pipe {
+        /// Filter to apply (cargo-test, pytest, go-test, go-build, tsc, vitest, grep, rg, find, fd, git-log, git-diff, git-status)
+        #[arg(long, short = 'f')]
+        filter: Option<String>,
+        /// Emit stdin unchanged (no filtering)
+        #[arg(long)]
+        passthrough: bool,
+    },
+
     /// Trust project-local TOML filters in current directory
     Trust {
         /// List all trusted projects
@@ -676,6 +703,19 @@ enum Commands {
         since: u64,
     },
 
+    /// Run command with safety checks and token-optimized output
+    Run {
+        /// Command string to execute
+        #[arg(short = 'c', long)]
+        command: String,
+    },
+
+    /// Hook processors for LLM CLI tools (Claude Code, Gemini CLI, Copilot, etc.)
+    Hook {
+        #[command(subcommand)]
+        command: HookCommands,
+    },
+
     /// Rewrite a raw command to its RTK equivalent (single source of truth for hooks)
     ///
     /// Exits 0 and prints the rewritten command if supported.
@@ -689,16 +729,21 @@ enum Commands {
         #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
         args: Vec<String>,
     },
-
-    /// Hook processors for LLM CLI tools (Gemini CLI, Copilot, etc.)
-    Hook {
-        #[command(subcommand)]
-        command: HookCommands,
-    },
 }
 
 #[derive(Subcommand)]
 enum HookCommands {
+    /// Check command for safety and rewrite (text protocol for debugging)
+    Check {
+        /// Agent type: claude or gemini
+        #[arg(long, default_value = "claude")]
+        agent: String,
+        /// Command to check
+        #[arg(trailing_var_arg = true, allow_hyphen_values = true)]
+        command: Vec<String>,
+    },
+    /// Claude Code JSON protocol handler (reads stdin, writes stdout)
+    Claude,
     /// Process Gemini CLI BeforeTool hook (reads JSON from stdin)
     Gemini,
     /// Process Copilot preToolUse hook (VS Code + Copilot CLI, reads JSON from stdin)
@@ -1631,8 +1676,18 @@ fn main() -> Result<()> {
             context_only,
             file_type,
             line_numbers: _, // no-op: line numbers always enabled in grep_cmd::run
+            ignore_case,
+            word_regexp,
             extra_args,
         } => {
+            let mut all_args = Vec::new();
+            if ignore_case {
+                all_args.push("-i".into());
+            }
+            if word_regexp {
+                all_args.push("-w".into());
+            }
+            all_args.extend(extra_args);
             grep_cmd::run(
                 &pattern,
                 &path,
@@ -1640,7 +1695,7 @@ fn main() -> Result<()> {
                 max,
                 context_only,
                 file_type.as_deref(),
-                &extra_args,
+                &all_args,
                 cli.verbose,
             )?;
         }
@@ -1656,6 +1711,7 @@ fn main() -> Result<()> {
             auto_patch,
             no_patch,
             uninstall,
+            hook_type,
             codex,
         } => {
             if show {
@@ -1697,6 +1753,7 @@ fn main() -> Result<()> {
                     hook_only,
                     codex,
                     patch_mode,
+                    hook_type,
                     cli.verbose,
                 )?;
             }
@@ -2037,7 +2094,35 @@ fn main() -> Result<()> {
             hook_audit_cmd::run(since, cli.verbose)?;
         }
 
+        Commands::Run { command } => {
+            let code = cmd::execute(&command, cli.verbose)?;
+            if code != 0 {
+                std::process::exit(code);
+            }
+        }
+
+        Commands::Pipe {
+            filter,
+            passthrough,
+        } => {
+            pipe_cmd::run(filter.as_deref(), passthrough)?;
+        }
+
         Commands::Hook { command } => match command {
+            HookCommands::Check { agent, command } => {
+                let cmd_str = command.join(" ");
+                let result = cmd::check_for_hook(&cmd_str, &agent);
+                let (output, _success, code) = cmd::hook::format_for_claude(result);
+                if code == 0 {
+                    println!("{}", output);
+                } else {
+                    eprintln!("{}", output);
+                    std::process::exit(code);
+                }
+            }
+            HookCommands::Claude => {
+                cmd::hook::claude::run()?;
+            }
             HookCommands::Gemini => {
                 hook_cmd::run_gemini()?;
             }
@@ -2297,7 +2382,26 @@ mod tests {
         }
     }
 
-    // #327: git commit -am "msg" was rejected by Clap
+    #[test]
+    fn test_git_commit_file_flag() {
+        // -F reads commit message from file — trailing_var_arg passes it through unchanged
+        let cli = Cli::try_parse_from(["rtk", "git", "commit", "-F", "/tmp/msg.txt"]).unwrap();
+        match cli.command {
+            Commands::Git {
+                command: GitCommands::Commit { args },
+                ..
+            } => {
+                assert_eq!(
+                    args,
+                    vec!["-F", "/tmp/msg.txt"],
+                    "-F flag and path should pass through as flat args"
+                );
+            }
+            _ => panic!("Expected Git Commit command"),
+        }
+    }
+
+    // #327: git commit -am "msg" was rejected by Clap before trailing_var_arg fix
     #[test]
     fn test_git_commit_am_flag() {
         let cli = Cli::try_parse_from(["rtk", "git", "commit", "-am", "quick fix"]).unwrap();
@@ -2306,14 +2410,58 @@ mod tests {
                 command: GitCommands::Commit { args },
                 ..
             } => {
-                assert_eq!(args, vec!["-am", "quick fix"]);
+                assert_eq!(
+                    args,
+                    vec!["-am", "quick fix"],
+                    "-am combined flag should pass through (PR #327 regression test)"
+                );
             }
             _ => panic!("Expected Git Commit command"),
         }
     }
 
     #[test]
-    fn test_git_commit_amend() {
+    fn test_git_commit_amend_no_edit() {
+        // --amend --no-edit: amend previous commit keeping its message
+        let cli = Cli::try_parse_from(["rtk", "git", "commit", "--amend", "--no-edit"]).unwrap();
+        match cli.command {
+            Commands::Git {
+                command: GitCommands::Commit { args },
+                ..
+            } => {
+                assert_eq!(
+                    args,
+                    vec!["--amend", "--no-edit"],
+                    "--amend --no-edit should pass through as flat args"
+                );
+            }
+            _ => panic!("Expected Git Commit command"),
+        }
+    }
+
+    #[test]
+    fn test_git_commit_message_and_amend() {
+        // -m with --amend: amend with a new message
+        let cli =
+            Cli::try_parse_from(["rtk", "git", "commit", "-m", "fix: update", "--amend"]).unwrap();
+        match cli.command {
+            Commands::Git {
+                command: GitCommands::Commit { args },
+                ..
+            } => {
+                assert_eq!(
+                    args,
+                    vec!["-m", "fix: update", "--amend"],
+                    "message flag and --amend should coexist as flat args"
+                );
+            }
+            _ => panic!("Expected Git Commit command"),
+        }
+    }
+
+    #[test]
+    fn test_git_commit_amend_with_message() {
+        // upstream's test: --amend before -m (order shouldn't matter)
         let cli =
             Cli::try_parse_from(["rtk", "git", "commit", "--amend", "-m", "new msg"]).unwrap();
         match cli.command {
@@ -2321,7 +2469,11 @@ mod tests {
                 command: GitCommands::Commit { args },
                 ..
             } => {
-                assert_eq!(args, vec!["--amend", "-m", "new msg"]);
+                assert_eq!(
+                    args,
+                    vec!["--amend", "-m", "new msg"],
+                    "--amend -m ordering should be preserved"
+                );
             }
             _ => panic!("Expected Git Commit command"),
         }
@@ -2377,7 +2529,8 @@ mod tests {
                         "body",
                         "--message",
                         "footer"
-                    ]
+                    ],
+                    "multiple --message flags should all pass through as flat args"
                 );
             }
             _ => panic!("Expected Git Commit command"),
@@ -2579,4 +2732,14 @@ mod tests {
             }
         }
     }
+
+    #[test]
+    fn test_grep_case_insensitive_and_word_flags_parsed() {
+        let cli = Cli::try_parse_from(["rtk", "grep", "-i", "-w", "pattern"]);
+        assert!(
+            cli.is_ok(),
+            "grep -i -w must parse without error: {:?}",
+            cli.err()
+        );
+    }
 }
diff --git a/src/pipe_cmd.rs b/src/pipe_cmd.rs
new file mode 100644
index 000000000..cf158e342
--- /dev/null
+++ b/src/pipe_cmd.rs
@@ -0,0 +1,439 @@
+//! `rtk pipe` — Read stdin, reduce tokens, print filtered output.
+//!
+//! Enables `command | rtk pipe [--filter <name>]` usage where RTK acts as a
+//! pure token-reduction filter in a Unix pipeline.
+//!
+//! # Supported filters
+//! | Name | Source module | Typical input |
+//! |------|--------------|---------------|
+//! | `cargo-test` | cargo_cmd::filter_cargo_test | `cargo test` output |
+//! | `pytest` | pytest_cmd::filter_pytest_output | `pytest` output |
+//! | `go-test` | go_cmd::filter_go_test_json | `go test -json` output |
+//! | `go-build` | go_cmd::filter_go_build | `go build` stderr |
+//! | `tsc` | tsc_cmd::filter_tsc_output | `tsc` compiler output |
+//! | `vitest` | vitest_cmd::filter_vitest_output | `vitest --reporter=json` |
+//! | `grep` / `rg` | grep_cmd::filter_grep_raw | `rg -n --no-heading` output |
+//! | `find` / `fd` | grep_cmd::filter_find_output | `find` / `fd` path output |
+//! | `git-log` | git::filter_log_output | `git log` output |
+//! | `git-diff` | git::compact_diff | `git diff` output |
+//! | `git-status` | git::format_status_output | `git status --porcelain=v1` |
+//! | `mypy` | mypy_cmd::filter_mypy_output | `mypy` type check output |
+//! | `ruff-check` | ruff_cmd::filter_ruff_check_json | `ruff check --output-format=json` |
+//! | `ruff-format` | ruff_cmd::filter_ruff_format | `ruff format --check` output |
+//! | `prettier` | prettier_cmd::filter_prettier_output | `prettier --check` output |
+
+use anyhow::Result;
+use std::io::Read;
+
+/// Resolve a filter name to a `fn(&str) -> String` function pointer.
+///
+/// Returns `None` if the filter name is not recognised.
+pub fn resolve_filter(name: &str) -> Option<fn(&str) -> String> {
+    match name {
+        "cargo-test" | "cargo" => Some(crate::cargo_cmd::filter_cargo_test),
+        "pytest" => Some(crate::pytest_cmd::filter_pytest_output),
+        "go-test" => Some(go_test_wrapper),
+        "go-build" => Some(crate::go_cmd::filter_go_build),
+        "tsc" => Some(crate::tsc_cmd::filter_tsc_output),
+        "vitest" => Some(crate::vitest_cmd::filter_vitest_output),
+        "grep" | "rg" => Some(crate::grep_cmd::filter_grep_raw),
+        "find" | "fd" => Some(crate::grep_cmd::filter_find_output),
+        "git-log" => Some(git_log_wrapper),
+        "git-diff" => Some(git_diff_wrapper),
+        "git-status" => Some(crate::git::format_status_output),
+        "mypy" => Some(crate::mypy_cmd::filter_mypy_output),
+        "ruff-check" => Some(crate::ruff_cmd::filter_ruff_check_json),
+        "ruff-format" => Some(crate::ruff_cmd::filter_ruff_format),
+        "prettier" => Some(crate::prettier_cmd::filter_prettier_output),
+        _ => None,
+    }
+}
+
+// Wrappers to adapt functions with extra parameters to fn(&str) -> String
+
+fn go_test_wrapper(input: &str) -> String {
+    crate::go_cmd::filter_go_test_json(input)
+}
+
+fn git_log_wrapper(input: &str) -> String {
+    // Default to 50 log lines when used as a pipe filter
+    crate::git::filter_log_output(input, 50, false, false)
+}
+
+fn git_diff_wrapper(input: &str) -> String {
+    // Default to 200 diff lines
+    crate::git::compact_diff(input, 200)
+}
+
+/// Auto-detect the appropriate filter based on input content heuristics.
+///
+/// Falls back to identity (no-op) if no filter is detected.
+pub fn auto_detect_filter(input: &str) -> fn(&str) -> String {
+    let first_1k = &input[..input.len().min(1024)];
+
+    // cargo test: "test result: ok. N passed; M failed"
+    if first_1k.contains("test result:") && first_1k.contains("passed;") {
+        return crate::cargo_cmd::filter_cargo_test;
+    }
+
+    // pytest: starts with "=== test session starts"
+    if first_1k.contains("=== test session starts") {
+        return crate::pytest_cmd::filter_pytest_output;
+    }
+
+    // go test -json: NDJSON with "Action" key
+    let first_trimmed = first_1k.trim_start();
+    if first_trimmed.starts_with('{') && first_1k.contains("\"Action\"") {
+        return go_test_wrapper;
+    }
+
+    // mypy: lines like "file.py:42: error: ..." with optional [error-code]
+    if first_1k.contains(": error:") && first_1k.contains(".py:") {
+        return crate::mypy_cmd::filter_mypy_output;
+    }
+
+    // grep/rg: lines matching file:number:content pattern
+    if first_1k
+        .lines()
+        .take(5)
+        .filter(|l| !l.trim().is_empty())
+        .any(|l| {
+            let parts: Vec<_> = l.splitn(3, ':').collect();
+            parts.len() == 3 && parts[1].parse::<usize>().is_ok()
+        })
+    {
+        return crate::grep_cmd::filter_grep_raw;
+    }
+
+    // vitest: JSON with "testResults" key
+    if first_1k.contains("\"testResults\"") || first_1k.contains("\"numTotalTests\"") {
+        return crate::vitest_cmd::filter_vitest_output;
+    }
+
+    // find/fd: all non-empty lines look like file paths (contain '/' or '.', no ':' separator)
+    // Require at least 3 path-like lines to avoid false positives.
+    let path_like_lines: usize = first_1k
+        .lines()
+        .filter(|l| {
+            let t = l.trim();
+            !t.is_empty()
+                && !t.contains(':')
+                && (t.starts_with('.') || t.starts_with('/') || t.contains('/'))
+        })
+        .count();
+    let nonempty_lines: usize = first_1k.lines().filter(|l| !l.trim().is_empty()).count();
+    if nonempty_lines >= 3 && path_like_lines == nonempty_lines {
+        return crate::grep_cmd::filter_find_output;
+    }
+
+    // Default: identity (no-op)
+    identity_filter
+}
+
+fn identity_filter(input: &str) -> String {
+    input.to_string()
+}
+
+/// Run `rtk pipe`: read stdin, apply filter, print result.
+pub fn run(filter_name: Option<&str>, passthrough: bool) -> Result<()> {
+    // Read all stdin (stdin is complete when piped; no streaming benefit here)
+    let mut buf = String::new();
+    std::io::stdin()
+        .read_to_string(&mut buf)
+        .map_err(|e| anyhow::anyhow!("Failed to read stdin: {}", e))?;
+
+    if passthrough {
+        print!("{}", buf);
+        return Ok(());
+    }
+
+    let filter_fn = match filter_name {
+        Some(name) => resolve_filter(name).ok_or_else(|| {
+            anyhow::anyhow!(
+                "Unknown filter '{}'. Available: cargo-test, pytest, go-test, go-build, \
+                 tsc, vitest, grep, rg, find, fd, git-log, git-diff, git-status, \
+                 mypy, ruff-check, ruff-format, prettier",
+                name
+            )
+        })?,
+        None => auto_detect_filter(&buf),
+    };
+
+    let output = filter_fn(&buf);
+    print!("{}", output);
+    Ok(())
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // ── resolve_filter ─────────────────────────────────────────────────────────
+
+    #[test]
+    fn test_resolve_filter_cargo_test() {
+        let f = resolve_filter("cargo-test").expect("cargo-test filter must exist");
+        let out = f("test result: ok. 5 passed; 0 failed");
+        assert!(out.contains("passed"), "Should contain pass count: {}", out);
+    }
+
+    #[test]
+    fn test_resolve_filter_cargo_alias() {
+        // "cargo" is an alias for "cargo-test"
+        assert!(resolve_filter("cargo").is_some());
+    }
+
+    #[test]
+    fn test_resolve_filter_grep() {
+        let f = resolve_filter("grep").expect("grep filter must exist");
+        let input = "src/main.rs:42:fn main() {\nsrc/lib.rs:10:pub fn helper() {}\n";
+        let out = f(input);
+        assert!(
+            out.contains("main.rs") || out.contains("matches"),
+            "out={}",
+            out
+        );
+    }
+
+    #[test]
+    fn test_resolve_filter_rg_alias() {
+        // "rg" is an alias for "grep"
+        assert!(resolve_filter("rg").is_some());
+    }
+
+    #[test]
+    fn test_resolve_filter_pytest() {
+        assert!(resolve_filter("pytest").is_some());
+    }
+
+    #[test]
+    fn test_resolve_filter_go_test() {
+        assert!(resolve_filter("go-test").is_some());
+    }
+
+    #[test]
+    fn test_resolve_filter_tsc() {
+        assert!(resolve_filter("tsc").is_some());
+    }
+
+    #[test]
+    fn test_resolve_filter_vitest() {
+        assert!(resolve_filter("vitest").is_some());
+    }
+
+    #[test]
+    fn test_resolve_filter_git_log() {
+        assert!(resolve_filter("git-log").is_some());
+    }
+
+    #[test]
+    fn test_resolve_filter_git_diff() {
+        assert!(resolve_filter("git-diff").is_some());
+    }
+
+    #[test]
+    fn test_resolve_filter_git_status() {
+        assert!(resolve_filter("git-status").is_some());
+    }
+
+    #[test]
+    fn test_resolve_filter_unknown_returns_none() {
+        assert!(resolve_filter("nonexistent-filter").is_none());
+    }
+
+    // ── auto_detect_filter ────────────────────────────────────────────────────
+
+    #[test]
+    fn test_auto_detect_cargo_test() {
+        let input = "test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured\n";
+        let f = auto_detect_filter(input);
+        let out = f(input);
+        assert!(!out.is_empty(), "cargo-test filter should produce output");
+    }
+
+    #[test]
+    fn test_auto_detect_pytest() {
+        let input = "=== test session starts ===\ncollected 3 items\n";
+        let f = auto_detect_filter(input);
+        let out = f(input);
+        assert!(!out.is_empty(), "pytest filter should produce output");
+    }
+
+    #[test]
+    fn test_auto_detect_grep_format() {
+        // rg -n --no-heading format: file:line_num:content
+        let input = "src/main.rs:42:fn main() {\nsrc/lib.rs:10:pub fn helper() {}\n";
+        let f = auto_detect_filter(input);
+        let out = f(input);
+        // Should use grep filter and produce grouped output or matches
+        assert!(!out.is_empty());
+    }
+
+    #[test]
+    fn test_auto_detect_go_test_ndjson() {
+        let input = r#"{"Time":"2024-01-01T00:00:00Z","Action":"run","Package":"example/pkg"}
+{"Time":"2024-01-01T00:00:01Z","Action":"pass","Package":"example/pkg","Elapsed":0.5}
+"#;
+        let f = auto_detect_filter(input);
+        let out = f(input);
+        assert!(!out.is_empty());
+    }
+
+    #[test]
+    fn test_auto_detect_unknown_returns_identity() {
+        let input = "some random text that doesn't match any filter pattern\n";
+        let f = auto_detect_filter(input);
+        let out = f(input);
+        // Identity filter returns input unchanged
+        assert_eq!(out, input);
+    }
+
+    // ── git wrappers ───────────────────────────────────────────────────────────
+
+    #[test]
+    fn test_git_log_wrapper() {
+        let input = "abc1234 Fix bug in parser (2 days ago) <alice>\n\
+                     def5678 Add new feature (3 days ago) <bob>\n";
+        let out = git_log_wrapper(input);
+        assert!(!out.is_empty());
+    }
+
+    #[test]
+    fn test_git_diff_wrapper() {
+        let input = "diff --git a/src/main.rs b/src/main.rs\n\
+                     --- a/src/main.rs\n\
+                     +++ b/src/main.rs\n\
+                     @@ -1,3 +1,4 @@\n\
+                     +// new comment\n\
+                      fn main() {}\n";
+        let out = git_diff_wrapper(input);
+        assert!(!out.is_empty());
+    }
+
+    // ── resolve_filter: find/fd ────────────────────────────────────────────────
+
+    #[test]
+    fn test_resolve_filter_find() {
+        let f = resolve_filter("find").expect("find filter must exist");
+        let input = "./src/main.rs\n./src/lib.rs\n./tests/foo.rs\n";
+        let out = f(input);
+        assert!(out.contains("3 files"), "out={}", out);
+    }
+
+    #[test]
+    fn test_resolve_filter_fd_alias() {
+        // "fd" is an alias for "find" filter
+        assert!(resolve_filter("fd").is_some());
+    }
+
+    #[test]
+    fn test_resolve_filter_unknown_error_message_lists_find() {
+        // Confirm the error message mentions find/fd
+        assert!(resolve_filter("not-a-filter").is_none());
+        // We can't easily test the error message from resolve_filter (returns None),
+        // but we verify the mapping exists
+        assert!(resolve_filter("find").is_some());
+        assert!(resolve_filter("fd").is_some());
+    }
+
+    // ── auto_detect_filter: find/fd ────────────────────────────────────────────
+
+    #[test]
+    fn test_auto_detect_find_paths() {
+        // find/fd output: one path per line, no colons
+        let input = "./src/main.rs\n./src/lib.rs\n./src/cmd/mod.rs\n./tests/foo.rs\n";
+        let f = auto_detect_filter(input);
+        let out = f(input);
+        assert!(out.contains("4 files"), "out={}", out);
+    }
+
+    #[test]
+    fn test_auto_detect_find_absolute_paths() {
+        let input = "/home/user/src/main.rs\n/home/user/src/lib.rs\n/home/user/tests/foo.rs\n";
+        let f = auto_detect_filter(input);
+        let out = f(input);
+        assert!(out.contains("3 files"), "out={}", out);
+    }
+
+    #[test]
+    fn test_auto_detect_find_not_triggered_for_few_lines() {
+        // Only 2 path-like lines — should NOT trigger find filter (below threshold of 3)
+        let input = "./src/main.rs\n./src/lib.rs\n";
+        let f = auto_detect_filter(input);
+        let out = f(input);
+        // identity filter: output equals input
+        assert_eq!(out, input);
+    }
+
+    #[test]
+    fn test_auto_detect_find_not_triggered_for_grep_output() {
+        // grep output has colons — should NOT be treated as find paths
+        let input = "src/main.rs:42:fn main() {\nsrc/lib.rs:10:pub fn helper() {}\nsrc/a.rs:1:x\n";
+        let f = auto_detect_filter(input);
+        let out = f(input);
+        // grep filter runs (has colons), find filter must NOT be triggered
+        assert!(
+            !out.contains("files"),
+            "should not trigger find filter: out={}",
+            out
+        );
+    }
+
+    // ── pipe_cmd edge cases ────────────────────────────────────────────────────
+
+    #[test]
+    fn test_auto_detect_empty_input_is_identity() {
+        let f = auto_detect_filter("");
+        let out = f("");
+        assert_eq!(out, "");
+    }
+
+    #[test]
+    fn test_auto_detect_single_line_unknown() {
+        // Single line of unknown content → identity
+        let input = "hello world\n";
+        let f = auto_detect_filter(input);
+        let out = f(input);
+        assert_eq!(out, input);
+    }
+
+    #[test]
+    fn test_resolve_filter_go_build() {
+        assert!(resolve_filter("go-build").is_some());
+    }
+
+    // ── mypy / ruff / prettier filters ──────────────────────────────────────────
+
+    #[test]
+    fn test_resolve_filter_mypy() {
+        assert!(resolve_filter("mypy").is_some());
+    }
+
+    #[test]
+    fn test_resolve_filter_ruff_check() {
+        assert!(resolve_filter("ruff-check").is_some());
+    }
+
+    #[test]
+    fn test_resolve_filter_ruff_format() {
+        assert!(resolve_filter("ruff-format").is_some());
+    }
+
+    #[test]
+    fn test_resolve_filter_prettier() {
+        assert!(resolve_filter("prettier").is_some());
+    }
+
+    #[test]
+    fn test_auto_detect_mypy_output() {
+        let input = "src/app.py:42: error: Argument 1 has incompatible type [arg-type]\n\
+                     src/utils.py:10: error: Missing return statement [return]\n\
+                     Found 2 errors in 2 files\n";
+        let f = auto_detect_filter(input);
+        let out = f(input);
+        // Should use mypy filter (not identity)
+        assert!(!out.is_empty());
+    }
+}
diff --git a/src/pytest_cmd.rs b/src/pytest_cmd.rs
index 0b1b1f2c1..878a328ea 100644
--- a/src/pytest_cmd.rs
+++ b/src/pytest_cmd.rs
@@ -1,15 +1,109 @@
+use crate::stream::{FilterMode, StdinMode, StreamFilter};
 use crate::tracking;
 use crate::utils::{resolved_command, tool_exists, truncate};
 use anyhow::{Context, Result};
 
-#[derive(Debug, PartialEq)]
+#[derive(Debug, PartialEq, Default)]
 enum ParseState {
+    #[default]
     Header,
     TestProgress,
     Failures,
     Summary,
 }
 
+/// Progressive streaming filter for `pytest` output.
+///
+/// Replicates the `filter_pytest_output` state machine line-by-line.
+/// Defers all output to `flush()` so the summary section is always included.
+#[derive(Default)]
+pub struct PyTestStreamFilter {
+    state: ParseState,
+    test_files: Vec<String>,
+    failures: Vec<String>,
+    current_failure: Vec<String>,
+    summary_line: String,
+}
+
+impl PyTestStreamFilter {
+    pub fn new() -> Self {
+        Self::default()
+    }
+}
+
+impl StreamFilter for PyTestStreamFilter {
+    fn feed_line(&mut self, line: &str) -> Option<String> {
+        let trimmed = line.trim();
+
+        // State transitions (same as filter_pytest_output loop body)
+        if trimmed.starts_with("===") && trimmed.contains("test session starts") {
+            self.state = ParseState::Header;
+            return None;
+        } else if trimmed.starts_with("===") && trimmed.contains("FAILURES") {
+            self.state = ParseState::Failures;
+            return None;
+        } else if trimmed.starts_with("===") && trimmed.contains("short test summary") {
+            self.state = ParseState::Summary;
+            if !self.current_failure.is_empty() {
+                let block = self.current_failure.join("\n");
+                self.failures.push(block);
+                self.current_failure.clear();
+            }
+            return None;
+        } else if trimmed.starts_with("===")
+            && (trimmed.contains("passed") || trimmed.contains("failed"))
+        {
+            self.summary_line = trimmed.to_string();
+            return None;
+        }
+
+        // Per-state processing
+        match self.state {
+            ParseState::Header => {
+                if trimmed.starts_with("collected") {
+                    self.state = ParseState::TestProgress;
+                }
+            }
+            ParseState::TestProgress => {
+                if !trimmed.is_empty()
+                    && !trimmed.starts_with("===")
+                    && (trimmed.contains(".py") || trimmed.contains("%]"))
+                {
+                    self.test_files.push(trimmed.to_string());
+                }
+            }
+            ParseState::Failures => {
+                if trimmed.starts_with("___") {
+                    if !self.current_failure.is_empty() {
+                        let block = self.current_failure.join("\n");
+                        self.failures.push(block);
+                        self.current_failure.clear();
+                    }
+                    self.current_failure.push(trimmed.to_string());
+                } else if !trimmed.is_empty() && !trimmed.starts_with("===") {
+                    self.current_failure.push(trimmed.to_string());
+                }
+            }
+            ParseState::Summary => {
+                if trimmed.starts_with("FAILED") || trimmed.starts_with("ERROR") {
+                    self.failures.push(trimmed.to_string());
+                }
+            }
+        }
+
+        None
+    }
+
+    fn flush(&mut self) -> String {
+        if !self.current_failure.is_empty() {
+            let block = self.current_failure.join("\n");
+            self.failures.push(block);
+            self.current_failure.clear();
+        }
+        build_pytest_summary(&self.summary_line, &self.test_files, &self.failures)
+    }
+}
+
 pub fn run(args: &[String], verbose: u8) -> Result<()> {
     let timer = tracking::TimedExecution::start();
 
@@ -42,124 +136,45 @@ pub fn run(args: &[String], verbose: u8) -> Result<()> {
         eprintln!("Running: pytest --tb=short -q {}", args.join(" "));
     }
 
-    let output = cmd
-        .output()
-        .context("Failed to run pytest. Is it installed? Try: pip install pytest")?;
+    let filter = PyTestStreamFilter::new();
+    let result = crate::stream::run_streaming(
+        &mut cmd,
+        StdinMode::Inherit,
+        FilterMode::Streaming(Box::new(filter)),
+    )
+    .context("Failed to run pytest. Is it installed? Try: pip install pytest")?;
 
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    let stderr = String::from_utf8_lossy(&output.stderr);
-    let raw = format!("{}\n{}", stdout, stderr);
-
-    let filtered = filter_pytest_output(&stdout);
-
-    let exit_code = output
-        .status
-        .code()
-        .unwrap_or(if output.status.success() { 0 } else { 1 });
-    if let Some(hint) = crate::tee::tee_and_hint(&raw, "pytest", exit_code) {
-        println!("{}\n{}", filtered, hint);
+    if let Some(hint) = crate::tee::tee_and_hint(&result.raw, "pytest", result.exit_code) {
+        println!("{}\n{}", result.filtered, hint);
     } else {
-        println!("{}", filtered);
-    }
-
-    // Include stderr if present (import errors, etc.)
-    if !stderr.trim().is_empty() {
-        eprintln!("{}", stderr.trim());
+        println!("{}", result.filtered);
     }
 
     timer.track(
         &format!("pytest {}", args.join(" ")),
         &format!("rtk pytest {}", args.join(" ")),
-        &raw,
-        &filtered,
+        &result.raw,
+        &result.filtered,
     );
 
-    // Preserve exit code for CI/CD
-    if !output.status.success() {
-        std::process::exit(exit_code);
+    if result.exit_code != 0 {
+        std::process::exit(result.exit_code);
     }
 
     Ok(())
 }
 
-/// Parse pytest output using state machine
-fn filter_pytest_output(output: &str) -> String {
-    let mut state = ParseState::Header;
-    let mut test_files: Vec<String> = Vec::new();
-    let mut failures: Vec<String> = Vec::new();
-    let mut current_failure: Vec<String> = Vec::new();
-    let mut summary_line = String::new();
-
+/// Parse pytest output using state machine.
+///
+/// Buffered variant -- for use when input is already fully accumulated (e.g.
+/// `rtk pipe --filter pytest`). For live subprocess output, prefer
+/// `PyTestStreamFilter` with `run_streaming`.
+pub(crate) fn filter_pytest_output(output: &str) -> String {
+    let mut filter = PyTestStreamFilter::new();
     for line in output.lines() {
-        let trimmed = line.trim();
-
-        // State transitions
-        if trimmed.starts_with("===") && trimmed.contains("test session starts") {
-            state = ParseState::Header;
-            continue;
-        } else if trimmed.starts_with("===") && trimmed.contains("FAILURES") {
-            state = ParseState::Failures;
-            continue;
-        } else if trimmed.starts_with("===") && trimmed.contains("short test summary") {
-            state = ParseState::Summary;
-            // Save current failure if any
-            if !current_failure.is_empty() {
-                failures.push(current_failure.join("\n"));
-                current_failure.clear();
-            }
-            continue;
-        } else if trimmed.starts_with("===")
-            && (trimmed.contains("passed") || trimmed.contains("failed"))
-        {
-            summary_line = trimmed.to_string();
-            continue;
-        }
-
-        // Process based on state
-        match state {
-            ParseState::Header => {
-                if trimmed.starts_with("collected") {
-                    state = ParseState::TestProgress;
-                }
-            }
-            ParseState::TestProgress => {
-                // Lines like "tests/test_foo.py ....  [ 40%]"
-                if !trimmed.is_empty()
-                    && !trimmed.starts_with("===")
-                    && (trimmed.contains(".py") || trimmed.contains("%]"))
-                {
-                    test_files.push(trimmed.to_string());
-                }
-            }
-            ParseState::Failures => {
-                // Collect failure details
-                if trimmed.starts_with("___") {
-                    // New failure section
-                    if !current_failure.is_empty() {
-                        failures.push(current_failure.join("\n"));
-                        current_failure.clear();
-                    }
-                    current_failure.push(trimmed.to_string());
-                } else if !trimmed.is_empty() && !trimmed.starts_with("===") {
-                    current_failure.push(trimmed.to_string());
-                }
-            }
-            ParseState::Summary => {
-                // FAILED test lines
-                if trimmed.starts_with("FAILED") || trimmed.starts_with("ERROR") {
-                    failures.push(trimmed.to_string());
-                }
-            }
-        }
-    }
-
-    // Save last failure if any
-    if !current_failure.is_empty() {
-        failures.push(current_failure.join("\n"));
+        filter.feed_line(line);
     }
-
-    // Build compact output
-    build_pytest_summary(&summary_line, &test_files, &failures)
+    filter.flush()
 }
 
 fn build_pytest_summary(summary: &str, _test_files: &[String], failures: &[String]) -> String {
@@ -368,4 +383,87 @@ collected 0 items
             (3, 1, 2)
         );
     }
+
+    // ── PyTestStreamFilter tests ───────────────────────────────────────────────
+
+    const PYTEST_ALL_PASS: &str = r#"=== test session starts ===
+platform darwin -- Python 3.11.0
+collected 5 items
+
+tests/test_foo.py .....                                            [100%]
+
+=== 5 passed in 0.50s ==="#;
+
+    const PYTEST_WITH_FAILURE: &str = r#"=== test session starts ===
+collected 5 items
+
+tests/test_foo.py ..F..                                            [100%]
+
+=== FAILURES ===
+___ test_something ___
+
+    def test_something():
+>       assert False
+E       assert False
+
+tests/test_foo.py:10: AssertionError
+
+=== short test summary info ===
+FAILED tests/test_foo.py::test_something - assert False
+=== 4 passed, 1 failed in 0.50s ==="#;
+
+    #[test]
+    fn test_pytest_stream_filter_feed_and_flush_all_pass() {
+        let mut f = PyTestStreamFilter::new();
+        for line in PYTEST_ALL_PASS.lines() {
+            assert_eq!(
+                f.feed_line(line),
+                None,
+                "streaming filter must defer output"
+            );
+        }
+        let output = f.flush();
+        assert!(output.contains("Pytest:"), "output={}", output);
+        assert!(output.contains("5 passed"), "output={}", output);
+    }
+
+    #[test]
+    fn test_pytest_stream_filter_feed_and_flush_with_failure() {
+        let mut f = PyTestStreamFilter::new();
+        for line in PYTEST_WITH_FAILURE.lines() {
+            f.feed_line(line);
+        }
+        let output = f.flush();
+        assert!(output.contains("4 passed, 1 failed"), "output={}", output);
+        assert!(output.contains("test_something"), "output={}", output);
+    }
+
+    #[test]
+    fn test_pytest_stream_filter_matches_buffered_all_pass() {
+        let buffered = filter_pytest_output(PYTEST_ALL_PASS);
+        let mut f = PyTestStreamFilter::new();
+        for line in PYTEST_ALL_PASS.lines() {
+            f.feed_line(line);
+        }
+        let streamed = f.flush();
+        assert_eq!(streamed.trim(), buffered.trim());
+    }
+
+    #[test]
+    fn test_pytest_stream_filter_matches_buffered_with_failures() {
+        let buffered = filter_pytest_output(PYTEST_WITH_FAILURE);
+        let mut f = PyTestStreamFilter::new();
+        for line in PYTEST_WITH_FAILURE.lines() {
+            f.feed_line(line);
+        }
+        let streamed = f.flush();
+        assert_eq!(streamed.trim(), buffered.trim());
+    }
+
+    #[test]
+    fn test_pytest_stream_filter_default_equals_new() {
+        let mut f1 = PyTestStreamFilter::new();
+        let mut f2 = PyTestStreamFilter::default();
+        assert_eq!(f1.flush(), f2.flush());
+    }
 }
diff --git a/src/stream.rs b/src/stream.rs
new file mode 100644
index 000000000..f1835b566
--- /dev/null
+++ b/src/stream.rs
@@ -0,0 +1,566 @@
+//! Streaming process execution infrastructure for RTK.
+//!
+//! Provides a bidirectional process shim that preserves all process state
+//! (exit codes, signals, SIGPIPE) while filtering stdout progressively.
+//!
+//! # Process Transparency
+//! RTK inserts itself between a subprocess and the OS environment.
+//! All process expectations are preserved:
+//! - Exit codes 0–254 propagated exactly via [`StreamResult::exit_code`].
+//! - Signal-killed exit becomes `128 + signal_num` per POSIX convention.
+//! - SIGPIPE (broken downstream pipe) breaks the output loop cleanly.
+//! - SIGINT reaches both RTK and child via shared process group.
+//! - stdin inherited by default (`StdinMode::Inherit`).
+//!
+//! # RAII Guarantees
+//! Three resources follow RAII patterns (mirrors `RtkActiveGuard` in cmd/exec.rs):
+//! - `ChildGuard`: ensures `wait()` is called even on early `?` returns → no zombies.
+//! - `io::stdout().lock()`: released in scoped block before any joins.
+//! - Stdin `JoinHandle`: stored and joined (not detached) to surface panics.
+
+use anyhow::{Context, Result};
+use std::io::{self, BufRead, BufReader, BufWriter, Write};
+use std::process::{Command, Stdio};
+
+// ─── Traits ──────────────────────────────────────────────────────────────────
+
+/// A filter that processes command output incrementally, line by line.
+///
+/// Implement this to stream-filter subprocess output as it's produced,
+/// rather than buffering the entire output first.
+pub trait StreamFilter {
+    /// Process one line from subprocess stdout.
+    /// Returns `Some(output)` to emit that text downstream, `None` to suppress.
+    /// The output string should include a trailing newline if needed.
+    fn feed_line(&mut self, line: &str) -> Option<String>;
+
+    /// Called at end-of-stream to flush any buffered state.
+    /// Returns any final output (e.g., a summary block).
+    fn flush(&mut self) -> String;
+}
+
+/// A filter for stdin transformation. Requires [`Send`] because it runs in a thread.
+pub trait StdinFilter: Send {
+    /// Transform one line of stdin before forwarding to the child process.
+    fn feed_line(&mut self, line: &str) -> Option<String>;
+
+    /// Flush any remaining buffered state at stdin EOF.
+    fn flush(&mut self) -> String;
+}
+
+// ─── LineFilter ──────────────────────────────────────────────────────────────
+
+/// Generic per-line stateless filter adapter (Category A filters).
+///
+/// Wraps a closure for simple line-by-line transformations without state.
+/// The closure receives each line (without trailing newline) and returns
+/// `Some(output)` to emit or `None` to suppress.
+///
+/// # Example
+/// ```rust,ignore
+/// let f = LineFilter::new(|l| Some(format!("{}\n", l.to_uppercase())));
+/// ```
+pub struct LineFilter<F: FnMut(&str) -> Option<String>> {
+    f: F,
+}
+
+impl<F: FnMut(&str) -> Option<String>> LineFilter<F> {
+    pub fn new(f: F) -> Self {
+        Self { f }
+    }
+}
+
+impl<F: FnMut(&str) -> Option<String>> StreamFilter for LineFilter<F> {
+    fn feed_line(&mut self, line: &str) -> Option<String> {
+        (self.f)(line)
+    }
+
+    fn flush(&mut self) -> String {
+        String::new()
+    }
+}
+
+// ─── FilterMode / StdinMode ──────────────────────────────────────────────────
+
+/// How subprocess stdout is processed.
+pub enum FilterMode {
+    /// Line-by-line filtering, emitting output progressively as the subprocess produces it.
+    /// Use for commands with predictable per-line output (go test NDJSON, cargo test, etc.).
+    Streaming(Box<dyn StreamFilter>),
+
+    /// Buffer all stdout, apply a function, emit at end.
+    /// Use only for filters that genuinely require complete input (e.g., full JSON doc).
+    Buffered(fn(&str) -> String),
+
+    /// Emit raw lines immediately without filtering (ANSI codes preserved).
+    Passthrough,
+}
+
+/// How subprocess stdin is handled.
+// Filter and Null are used in tests and reserved for bidirectional shim use.
+#[allow(dead_code)]
+pub enum StdinMode {
+    /// Pass RTK's stdin directly to the child (default, zero overhead, no pipe).
+    Inherit,
+
+    /// Transform input lines through a filter before forwarding to child.
+    /// The filter runs in a dedicated thread to prevent deadlock.
+    Filter(Box<dyn StdinFilter + Send>),
+
+    /// Immediately send EOF to child (child sees no stdin input).
+    Null,
+}
+
+// ─── StreamResult ─────────────────────────────────────────────────────────────
+
+/// Result of [`run_streaming`], carrying the full POSIX exit code.
+pub struct StreamResult {
+    /// POSIX exit code: 0 = success, 1–127 = app error, 128+N = killed by signal N.
+    pub exit_code: i32,
+
+    /// Raw stdout + stderr combined (capped at 1 MiB) for tee recovery.
+    pub raw: String,
+
+    /// Filtered stdout content for token savings tracking.
+    pub filtered: String,
+}
+
+impl StreamResult {
+    /// Returns `true` if `exit_code == 0`.
+    // Used in tests and by future callers; suppress dead_code for binary target.
+    #[allow(dead_code)]
+    pub fn success(&self) -> bool {
+        self.exit_code == 0
+    }
+}
+
+// ─── status_to_exit_code ──────────────────────────────────────────────────────
+
+/// Convert `ExitStatus` to a POSIX-compatible integer exit code.
+///
+/// - Normal exit via `exit(N)`: returns `N`.
+/// - Signal-killed (Unix): returns `128 + signal_number` per POSIX convention.
+///   Example: SIGKILL (9) → 137, SIGTERM (15) → 143.
+/// - Unknown state: returns `1` (generic failure fallback).
+pub fn status_to_exit_code(status: std::process::ExitStatus) -> i32 {
+    if let Some(code) = status.code() {
+        return code;
+    }
+    // Process was killed by a signal — POSIX convention: 128 + signal_num
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::ExitStatusExt;
+        if let Some(sig) = status.signal() {
+            return 128 + sig;
+        }
+    }
+    1 // fallback: unknown failure
+}
+
+// ─── run_streaming ────────────────────────────────────────────────────────────
+
+/// Execute `cmd` as a bidirectional process shim with streaming stdout filtering.
+///
+/// Spawns the command and concurrently:
+/// - **(stdin thread)** Optionally transforms stdin before forwarding to child.
+/// - **(stderr thread)** Streams stderr directly to `io::stderr()` (responsive).
+/// - **(main thread)** Reads stdout, applies `stdout_mode` filter, writes to `io::stdout()`.
+///
+/// # Exit Code Transparency
+/// The returned [`StreamResult::exit_code`] is the child's exact POSIX exit code.
+/// Callers should propagate it via `std::process::exit(result.exit_code)` if non-zero.
+///
+/// # SIGPIPE Handling
+/// If the downstream pipe closes (e.g., `rtk go test | head -5`), writing to stdout
+/// returns `BrokenPipe`. The output loop breaks cleanly, child is drained, and the
+/// child's exit code is returned unchanged.
+///
+/// # Memory Bound
+/// Raw stdout+stderr is capped at 1 MiB (matches `tee.rs` `DEFAULT_MAX_FILE_SIZE`).
+/// Output beyond the cap is streamed to stdout but not accumulated in `raw`.
+pub fn run_streaming(
+    cmd: &mut Command,
+    stdin_mode: StdinMode,
+    stdout_mode: FilterMode,
+) -> Result<StreamResult> {
+    // ── Configure pipes ────────────────────────────────────────────────────────
+    match &stdin_mode {
+        StdinMode::Inherit => {
+            cmd.stdin(Stdio::inherit());
+        }
+        StdinMode::Filter(_) | StdinMode::Null => {
+            cmd.stdin(Stdio::piped());
+        }
+    }
+    cmd.stdout(Stdio::piped());
+    cmd.stderr(Stdio::piped());
+
+    // ── RAII child guard ──────────────────────────────────────────────────────
+    // Nested type definition (valid in Rust). Mirrors `RtkActiveGuard` in
+    // src/cmd/exec.rs:14-28. Ensures child.wait() is always called, preventing zombies.
+    struct ChildGuard(std::process::Child);
+    impl Drop for ChildGuard {
+        fn drop(&mut self) {
+            // Reap zombie. Ignores ECHILD error when child was already waited explicitly.
+            self.0.wait().ok();
+        }
+    }
+
+    let mut child = ChildGuard(cmd.spawn().context("Failed to spawn process")?);
+
+    // ── Stdin thread ──────────────────────────────────────────────────────────
+    // JoinHandle stored (not detached) — avoids clippy `unused_must_use` warning
+    // and ensures panics in the stdin thread are not silently lost.
+    let stdin_thread: Option<std::thread::JoinHandle<()>> = match stdin_mode {
+        StdinMode::Filter(mut filter) => {
+            let child_stdin = child.0.stdin.take().context("No child stdin handle")?;
+            Some(std::thread::spawn(move || {
+                let mut writer = BufWriter::new(child_stdin);
+                // Bind stdin to variable first — avoids temporary lifetime issue with lock().
+                let stdin_handle = io::stdin();
+                for line in BufReader::new(stdin_handle.lock())
+                    .lines()
+                    .map_while(Result::ok)
+                {
+                    if let Some(out) = filter.feed_line(&line) {
+                        if writeln!(writer, "{}", out).is_err() {
+                            break; // child closed its stdin — stop sending
+                        }
+                    }
+                }
+                let tail = filter.flush();
+                if !tail.is_empty() {
+                    write!(writer, "{}", tail).ok();
+                }
+                // writer drop → BufWriter flushes → ChildStdin drops → EOF to child
+            }))
+        }
+        StdinMode::Null => {
+            child.0.stdin.take(); // drop ChildStdin immediately → child gets EOF
+            None
+        }
+        StdinMode::Inherit => None, // stdin already configured as Stdio::inherit()
+    };
+
+    // ── Stderr thread ─────────────────────────────────────────────────────────
+    // Streams stderr directly to io::stderr() (responsive, not buffered).
+    // Accumulates raw string for tee recovery.
+    let stderr = child.0.stderr.take().context("No child stderr handle")?;
+    let stderr_thread = std::thread::spawn(move || -> String {
+        let mut raw_err = String::new();
+        let stderr_out = io::stderr();
+        let mut err_out = stderr_out.lock(); // RAII: released when closure completes
+        for line in BufReader::new(stderr).lines().map_while(Result::ok) {
+            writeln!(err_out, "{}", line).ok(); // emit immediately (responsive)
+            raw_err.push_str(&line);
+            raw_err.push('\n');
+        }
+        raw_err
+    });
+
+    // ── Stdout: main thread ───────────────────────────────────────────────────
+    let stdout = child.0.stdout.take().context("No child stdout handle")?;
+    const RAW_CAP: usize = 1_048_576; // 1 MiB, matches tee.rs DEFAULT_MAX_FILE_SIZE
+    let mut raw_stdout = String::new();
+    let mut filtered = String::new();
+
+    {
+        // Scoped block: stdout lock held ONLY here.
+        // RAII-dropped before joining threads or calling child.wait(),
+        // preventing lock contention during blocking operations.
+        let stdout_handle = io::stdout();
+        let mut out = stdout_handle.lock();
+
+        match stdout_mode {
+            FilterMode::Passthrough => {
+                for line in BufReader::new(stdout).lines().map_while(Result::ok) {
+                    if raw_stdout.len() < RAW_CAP {
+                        raw_stdout.push_str(&line);
+                        raw_stdout.push('\n');
+                    }
+                    match writeln!(out, "{}", line) {
+                        Err(e) if e.kind() == io::ErrorKind::BrokenPipe => break,
+                        Err(e) => return Err(e.into()),
+                        Ok(_) => {}
+                    }
+                }
+                filtered = raw_stdout.clone();
+            }
+            FilterMode::Streaming(mut filter) => {
+                for line in BufReader::new(stdout).lines().map_while(Result::ok) {
+                    if raw_stdout.len() < RAW_CAP {
+                        raw_stdout.push_str(&line);
+                        raw_stdout.push('\n');
+                    }
+                    if let Some(output) = filter.feed_line(&line) {
+                        filtered.push_str(&output);
+                        match write!(out, "{}", output) {
+                            Err(e) if e.kind() == io::ErrorKind::BrokenPipe => break,
+                            Err(e) => return Err(e.into()),
+                            Ok(_) => {}
+                        }
+                    }
+                }
+                let tail = filter.flush();
+                filtered.push_str(&tail);
+                // Guard against BrokenPipe (loop may have broken early above)
+                match write!(out, "{}", tail) {
+                    Err(e) if e.kind() == io::ErrorKind::BrokenPipe => {}
+                    Err(e) => return Err(e.into()),
+                    Ok(_) => {}
+                }
+            }
+            FilterMode::Buffered(filter_fn) => {
+                for line in BufReader::new(stdout).lines().map_while(Result::ok) {
+                    if raw_stdout.len() < RAW_CAP {
+                        raw_stdout.push_str(&line);
+                        raw_stdout.push('\n');
+                    }
+                }
+                let result = filter_fn(&raw_stdout);
+                filtered = result.clone();
+                match write!(out, "{}", result) {
+                    Err(e) if e.kind() == io::ErrorKind::BrokenPipe => {}
+                    Err(e) => return Err(e.into()),
+                    Ok(_) => {}
+                }
+            }
+        }
+    } // stdout lock RAII-dropped here — before any blocking joins or child.wait()
+
+    // ── Join threads ──────────────────────────────────────────────────────────
+    // stderr_thread finishes when child's stderr pipe closes (child exits).
+    let raw_stderr = stderr_thread.join().unwrap_or_else(|_| String::new());
+    // stdin_thread finishes when our stdin closes or child closed its stdin end.
+    if let Some(t) = stdin_thread {
+        t.join().ok();
+    }
+
+    // ── Wait for child ────────────────────────────────────────────────────────
+    // Explicit wait captures the actual exit status.
+    // ChildGuard.drop() will also call wait() as a safety net (ECHILD error ignored).
+    let status = child.0.wait().context("Failed to wait for child")?;
+
+    Ok(StreamResult {
+        exit_code: status_to_exit_code(status),
+        raw: format!("{}{}", raw_stdout, raw_stderr),
+        filtered,
+    })
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::process::Command;
+
+    // ── status_to_exit_code ────────────────────────────────────────────────────
+
+    #[test]
+    fn test_exit_code_zero() {
+        let status = Command::new("true").status().unwrap();
+        assert_eq!(status_to_exit_code(status), 0);
+    }
+
+    #[test]
+    fn test_exit_code_nonzero() {
+        let status = Command::new("false").status().unwrap();
+        assert_eq!(status_to_exit_code(status), 1);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn test_exit_code_signal_kill() {
+        // kill() sends SIGKILL (9); POSIX exit code = 128 + 9 = 137
+        let mut child = Command::new("sleep").arg("60").spawn().unwrap();
+        child.kill().unwrap();
+        let status = child.wait().unwrap();
+        assert_eq!(status_to_exit_code(status), 137);
+    }
+
+    // ── LineFilter ─────────────────────────────────────────────────────────────
+
+    #[test]
+    fn test_line_filter_passes_lines() {
+        let mut f = LineFilter::new(|l| Some(format!("{}\n", l.to_uppercase())));
+        assert_eq!(f.feed_line("hello"), Some("HELLO\n".to_string()));
+    }
+
+    #[test]
+    fn test_line_filter_drops_lines() {
+        let mut f = LineFilter::new(|l| {
+            if l.starts_with('#') {
+                None
+            } else {
+                Some(l.to_string())
+            }
+        });
+        assert_eq!(f.feed_line("# comment"), None);
+        assert_eq!(f.feed_line("code"), Some("code".to_string()));
+    }
+
+    #[test]
+    fn test_line_filter_flush_empty() {
+        let mut f = LineFilter::new(|l| Some(l.to_string()));
+        assert_eq!(f.flush(), String::new());
+    }
+
+    // ── StreamResult ───────────────────────────────────────────────────────────
+
+    #[test]
+    fn test_stream_result_success() {
+        let r = StreamResult {
+            exit_code: 0,
+            raw: String::new(),
+            filtered: String::new(),
+        };
+        assert!(r.success());
+    }
+
+    #[test]
+    fn test_stream_result_failure() {
+        let r = StreamResult {
+            exit_code: 1,
+            raw: String::new(),
+            filtered: String::new(),
+        };
+        assert!(!r.success());
+    }
+
+    #[test]
+    fn test_stream_result_signal_not_success() {
+        let r = StreamResult {
+            exit_code: 137,
+            raw: String::new(),
+            filtered: String::new(),
+        };
+        assert!(!r.success());
+    }
+
+    // ── run_streaming integration ──────────────────────────────────────────────
+
+    #[test]
+    fn test_run_streaming_passthrough_echo() {
+        let mut cmd = Command::new("echo");
+        cmd.arg("hello");
+        let result = run_streaming(&mut cmd, StdinMode::Null, FilterMode::Passthrough).unwrap();
+        assert_eq!(result.exit_code, 0);
+        assert!(result.raw.contains("hello"));
+    }
+
+    #[test]
+    fn test_run_streaming_exit_code_preserved() {
+        // sh -c "exit 42" → exit_code must be exactly 42, not 0 or 1
+        let mut cmd = Command::new("sh");
+        cmd.args(["-c", "exit 42"]);
+        let result = run_streaming(&mut cmd, StdinMode::Null, FilterMode::Passthrough).unwrap();
+        assert_eq!(result.exit_code, 42);
+    }
+
+    #[test]
+    fn test_run_streaming_exit_code_zero() {
+        let mut cmd = Command::new("true");
+        let result = run_streaming(&mut cmd, StdinMode::Null, FilterMode::Passthrough).unwrap();
+        assert_eq!(result.exit_code, 0);
+        assert!(result.success());
+    }
+
+    #[test]
+    fn test_run_streaming_exit_code_one() {
+        let mut cmd = Command::new("false");
+        let result = run_streaming(&mut cmd, StdinMode::Null, FilterMode::Passthrough).unwrap();
+        assert_eq!(result.exit_code, 1);
+        assert!(!result.success());
+    }
+
+    #[test]
+    fn test_run_streaming_streaming_filter_drops_lines() {
+        let mut cmd = Command::new("printf");
+        cmd.arg("a\nb\nc\n");
+        let filter = LineFilter::new(|l| {
+            if l == "b" {
+                None
+            } else {
+                Some(format!("{}\n", l))
+            }
+        });
+        let result = run_streaming(
+            &mut cmd,
+            StdinMode::Null,
+            FilterMode::Streaming(Box::new(filter)),
+        )
+        .unwrap();
+        assert!(result.filtered.contains('a'));
+        assert!(!result.filtered.contains('b'));
+        assert!(result.filtered.contains('c'));
+        assert_eq!(result.exit_code, 0);
+    }
+
+    #[test]
+    fn test_run_streaming_buffered_filter() {
+        let mut cmd = Command::new("printf");
+        cmd.arg("line1\nline2\nline3\n");
+        fn upper(s: &str) -> String {
+            s.to_uppercase()
+        }
+        let result = run_streaming(&mut cmd, StdinMode::Null, FilterMode::Buffered(upper)).unwrap();
+        assert!(result.filtered.contains("LINE1"));
+        assert!(result.filtered.contains("LINE2"));
+        assert_eq!(result.exit_code, 0);
+    }
+
+    #[test]
+    fn test_run_streaming_raw_cap_at_1mb() {
+        // Generate >1 MiB: 'yes | head -600000' ≈ 1.2 MiB of "y\n" lines.
+        // raw must be capped at 1 MiB, not OOM.
+        let mut cmd = Command::new("sh");
+        cmd.args(["-c", "yes | head -600000"]);
+        let result = run_streaming(&mut cmd, StdinMode::Null, FilterMode::Passthrough).unwrap();
+        // Allow small overshoot: last partial line may push us 1-2 bytes over cap.
+        assert!(
+            result.raw.len() <= 1_048_576 + 100,
+            "raw should be capped at ~1 MiB, got {} bytes",
+            result.raw.len()
+        );
+        // Must still have captured significant data.
+        assert!(
+            result.raw.len() > 100_000,
+            "Should have captured significant data"
+        );
+    }
+
+    #[test]
+    fn test_child_guard_prevents_zombie() {
+        // Verifies ChildGuard returns cleanly on fast-exiting commands.
+        let mut cmd = Command::new("true");
+        let result = run_streaming(&mut cmd, StdinMode::Null, FilterMode::Passthrough);
+        assert!(result.is_ok());
+        assert_eq!(result.unwrap().exit_code, 0);
+    }
+
+    #[test]
+    fn test_run_streaming_null_stdin_cat() {
+        // With StdinMode::Null, cat gets EOF and exits 0 with empty output.
+        let mut cmd = Command::new("cat");
+        let result = run_streaming(&mut cmd, StdinMode::Null, FilterMode::Passthrough).unwrap();
+        assert_eq!(result.exit_code, 0);
+    }
+
+    #[test]
+    fn test_run_streaming_raw_contains_stdout() {
+        let mut cmd = Command::new("echo");
+        cmd.arg("test_output_xyz");
+        let result = run_streaming(&mut cmd, StdinMode::Null, FilterMode::Passthrough).unwrap();
+        assert!(result.raw.contains("test_output_xyz"));
+    }
+
+    #[test]
+    fn test_run_streaming_filtered_equals_raw_in_passthrough() {
+        // In passthrough mode, filtered content matches raw stdout.
+        let mut cmd = Command::new("echo");
+        cmd.arg("check_equality");
+        let result = run_streaming(&mut cmd, StdinMode::Null, FilterMode::Passthrough).unwrap();
+        assert_eq!(result.filtered.trim(), result.raw.trim());
+    }
+}
diff --git a/src/tracking.rs b/src/tracking.rs
index dd73788a0..c456bd2f7 100644
--- a/src/tracking.rs
+++ b/src/tracking.rs
@@ -129,7 +129,7 @@ pub struct GainSummary {
     /// Average execution time per command (milliseconds)
     pub avg_time_ms: u64,
     /// Top 10 commands by tokens saved: (cmd, count, saved, avg_pct, avg_time_ms)
-    pub by_command: Vec<(String, usize, usize, f64, u64)>,
+    pub by_command: Vec<CommandStats>,
     /// Last 30 days of activity: (date, saved_tokens)
     pub by_day: Vec<(String, usize)>,
 }
@@ -221,7 +221,8 @@ pub struct MonthStats {
     pub avg_time_ms: u64,
 }
 
-/// Type alias for command statistics tuple: (command, count, saved_tokens, avg_savings_pct, avg_time_ms)
+/// Per-command aggregate statistics from tracking database.
+/// Type alias: (command, count, saved_tokens, avg_savings_pct, avg_time_ms)
 type CommandStats = (String, usize, usize, f64, u64);
 
 impl Tracker {
@@ -567,10 +568,8 @@ impl Tracker {
         })
     }
 
-    fn get_by_command(
-        &self,
-        project_path: Option<&str>, // added
-    ) -> Result<Vec<CommandStats>> {
+    /// (rtk_cmd, count, total_saved_tokens, avg_savings_pct, avg_exec_time_ms)
+    fn get_by_command(&self, project_path: Option<&str>) -> Result<Vec<CommandStats>> {
         let (project_exact, project_glob) = project_filter_params(project_path); // added
         let mut stmt = self.conn.prepare(
             "SELECT rtk_cmd, COUNT(*), SUM(saved_tokens), AVG(savings_pct), AVG(exec_time_ms)
@@ -1200,6 +1199,7 @@ pub fn track(original_cmd: &str, rtk_cmd: &str, input: &str, output: &str) {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::cmd::test_helpers::EnvGuard;
 
     // 1. estimate_tokens — verify ~4 chars/token ratio
     #[test]
@@ -1325,24 +1325,19 @@ mod tests {
     // 7. get_db_path respects environment variable RTK_DB_PATH
     #[test]
     fn test_custom_db_path_env() {
-        use std::env;
+        let _guard = EnvGuard::new(); // Serializes env access and auto-cleans
 
         let custom_path = "/tmp/rtk_test_custom.db";
-        env::set_var("RTK_DB_PATH", custom_path);
+        std::env::set_var("RTK_DB_PATH", custom_path);
 
         let db_path = get_db_path().expect("Failed to get db path");
         assert_eq!(db_path, PathBuf::from(custom_path));
-
-        env::remove_var("RTK_DB_PATH");
     }
 
     // 8. get_db_path falls back to default when no custom config
     #[test]
     fn test_default_db_path() {
-        use std::env;
-
-        // Ensure no env var is set
-        env::remove_var("RTK_DB_PATH");
+        let _guard = EnvGuard::new(); // Serializes env access and ensures RTK_DB_PATH is unset
 
         let db_path = get_db_path().expect("Failed to get db path");
         assert!(db_path.ends_with("rtk/history.db"));
diff --git a/src/tsc_cmd.rs b/src/tsc_cmd.rs
index 0758a149a..de3496311 100644
--- a/src/tsc_cmd.rs
+++ b/src/tsc_cmd.rs
@@ -55,7 +55,7 @@ pub fn run(args: &[String], verbose: u8) -> Result<()> {
 }
 
 /// Filter TypeScript compiler output - group errors by file, show every error
-fn filter_tsc_output(output: &str) -> String {
+pub(crate) fn filter_tsc_output(output: &str) -> String {
     lazy_static::lazy_static! {
         // Pattern: src/file.ts(12,5): error TS2322: Type 'string' is not assignable to type 'number'.
         static ref TSC_ERROR: Regex = Regex::new(
diff --git a/src/vitest_cmd.rs b/src/vitest_cmd.rs
index 2d8adb315..0a3b0ae29 100644
--- a/src/vitest_cmd.rs
+++ b/src/vitest_cmd.rs
@@ -208,6 +208,19 @@ fn extract_failures_regex(output: &str) -> Vec<TestFailure> {
     failures
 }
 
+/// Filter vitest output (JSON or text) for use with `rtk pipe --filter vitest`.
+///
+/// Adapts `VitestParser` (which uses the `OutputParser` trait) to a simple
+/// `fn(&str) -> String` interface for pipe filtering.
+pub(crate) fn filter_vitest_output(input: &str) -> String {
+    let mode = FormatMode::Compact;
+    match VitestParser::parse(input) {
+        ParseResult::Full(data) => data.format(mode),
+        ParseResult::Degraded(data, _) => data.format(mode),
+        ParseResult::Passthrough(raw) => raw,
+    }
+}
+
 #[derive(Debug, Clone)]
 pub enum VitestCommand {
     Run,