Gemini CLI support, rm→trash / git→stash data safety rtk.*.md rules, chained command rewriting, Rust-based hooks

[ahundt]

Executive summary

Adds Gemini CLI support (rtk init --gemini), 11 data safety rules (rm→trash, git reset --hard→stash), chained command rewriting (cd && git status rewrites both), and extensible rtk.*.md data safety rule files. Closes #112 (chained commands missed) and #115 (destructive command safety). 53 files, 656 tests, 2 new deps (trash, which).

Features

#	Feature	What it does	Impact
1	Gemini CLI support	RTK now works on Gemini CLI — same token optimization, data safety rules, and rewrites as Claude Code. rtk init installs hooks for both platforms.	First multi-platform support; 65% shared code, one new protocol handler per future platform
2	Data loss prevention (#115)	11 rules intercept destructive commands (rm, git reset --hard, git clean -f, etc.) and make them recoverable via trash or git stash	Prevents ~20-50K token costs per data loss incident
3	Chained commands (#112)	cd /path && git status now rewrites each command independently instead of only seeing cd	Captures ~12-20M tokens/month in previously-missed optimizations
4	Extensible rtk.*.md data safety rule files	Each rule is a markdown file with YAML frontmatter (patterns, action, redirect, when, env_var). 11 built-in rules ship compiled into the binary; users drop override/new files in .rtk/, .claude/, or .gemini/ dirs. Config system split into config/{mod,discovery,rules}.rs with [discovery] section, CRUD commands, and per-project overlay.	User-customizable data safety rules and remaps without recompilation; same-name files override builtins

Context: RTK has saved 1.25B tokens across 3,757 tracked commands on my test machine. Issue #112 documents 271 git status, 65 tail, 81 grep, 105 ls calls in chained commands that were passing through unoptimized.

---

What Changed

1. Gemini CLI Support

RTK's token optimization now works on Gemini CLI in addition to Claude Code. Both platforms share the same command parsing, data safety rules, and rewrite engine. Only the JSON protocol layer differs.

• rtk init with no flags installs both Claude and Gemini hooks
• rtk init --claude installs Claude hooks only (~/.claude/settings.json)
• rtk init --gemini installs Gemini hooks only (~/.gemini/settings.json)
• Individual flags select one platform; combine --claude --gemini to install both, or use no flags for both
• 65% code reuse between platforms — adding a third platform means writing one protocol handler

Architecture: src/cmd/hook.rs (shared logic) → src/cmd/claude_hook.rs (Claude JSON protocol) / src/cmd/gemini_hook.rs (Gemini JSON protocol)

2. Data Safety Rules (#115)

11 rule files (each an rtk.*.md file in src/rules/) intercept destructive commands and make them recoverable. The table below groups related rules into rows (e.g., git clean -f, -fd, -df are 3 separate rule files). Built-in rules use one pattern per file for clarity, though users can combine multiple patterns in a single rule file. Each incident of data loss costs ~20-50K tokens in recovery (investigate damage → restore/rewrite → regenerate → debug differences).

Pattern	Rewrite
rm	Move to OS trash instead of delete
git reset --hard	git stash push -m 'RTK: reset backup' && git reset --hard {args}
git checkout . / git checkout --	git stash push -m 'RTK: checkout backup' && git checkout ... {args}
git clean -f/-fd/-df	git stash -u -m 'RTK: clean backup' && git clean ... {args}
git stash drop	git stash pop
cat, sed, head	Block execution and return error with tool suggestion (use Read/Edit tools instead)

Action types: trash (move to OS trash via trash crate), rewrite (modify command before execution), warn (print message, allow execution), block/suggest_tool (fail with error and suggest alternative).

Rules define their own when: conditions. git reset --hard, git checkout ., and git checkout -- use when: has_unstaged_changes (only fire when there are uncommitted changes to protect). The remaining rules default to when: always. See src/rules/*.md for per-rule conditions and redirect templates.

Opt-out env vars: RTK_SAFE_COMMANDS=0 disables rm/git data safety rules. RTK_BLOCK_TOKEN_WASTE=0 disables cat/sed/head blocking. Each rule specifies which env var controls it via the env_var: field in its frontmatter.

Key files: src/cmd/safety.rs, src/rules/*.md

3. Chained Command Parsing (#112)

Before this PR, cd /path && git status && git diff only saw cd as the binary. git status and git diff passed through unoptimized. Each missed optimization wastes ~300K tokens/month at typical usage. The new lexer splits chains on &&, ||, ; (respecting quotes), rewrites each command independently, and reassembles the chain.

Before: cd /path && git status && git diff
  Hook sees "cd" → no rewrite for git status or git diff

After:  cd /path && git status && git diff
  → cd /path && rtk git status && rtk git diff
  Each command extracted and rewritten independently (95%/75% savings)

• Smart quoting: git commit -m "Fix && Bug" doesn't split on && inside quotes
• Pipes and redirects detected — commands like echo test | grep test execute as-is (no rewrites inside pipes)
• Builtins (cd, export, pwd, echo) handled natively to preserve session state

Key files: src/cmd/lexer.rs, src/cmd/analysis.rs, src/cmd/builtins.rs

4. Extensible Data Safety Rule System

Rules are markdown files with YAML frontmatter (similar to SKILL.md files). 11 built-in data safety rules ship compiled into the binary via include_str!(). Users can override or extend them by placing rtk.*.md files in discoverable directories.

Built-in rule — src/rules/rtk.safety.rm-to-trash.md:

---
name: rm-to-trash
patterns: [rm]
action: trash
redirect: "trash {args}"
env_var: RTK_SAFE_COMMANDS
---

Safety: Moving to trash instead of permanent deletion.

Built-in rule — src/rules/rtk.safety.git-reset-hard.md:

---
name: git-reset-hard
patterns: ["git reset --hard"]
action: rewrite
redirect: "git stash push -m 'RTK: reset backup' && git reset --hard {args}"
when: has_unstaged_changes
env_var: RTK_SAFE_COMMANDS
---

Safety: Stashing before reset.

Users can create their own rules the same way. For example, intercepting chmod -R 777 only inside git repos (~/.config/rtk/rtk.safety.chmod-777.md):

---
name: chmod-777
patterns: ["chmod -R 777", "chmod 777"]
action: warn
when: "git rev-parse --is-inside-work-tree 2>/dev/null"
env_var: RTK_SAFE_COMMANDS
---

Warning: chmod 777 grants full read/write/execute to all users. Consider chmod 755 or chmod 644 instead.

The when: field supports named predicates (always, has_unstaged_changes) or arbitrary shell commands. Any command that exits 0 means the rule applies.

Rule priority (highest to lowest):

1. --rules-add CLI paths
2. .claude/, .gemini/, .rtk/ in each ancestor from cwd to $HOME (closest to cwd wins)
3. ~/.claude/, ~/.gemini/ (global, LLM-visible)
4. ~/.config/rtk/ (global config)
5. Built-in include_str!() defaults

Same-name rules override by priority. enabled: false disables a rule entirely. All search directories are configurable via [discovery] in config.toml.

Key files: src/config/rules.rs, src/config/discovery.rs

Config changes: Split config.rs into config/{mod,discovery,rules}.rs. Added [discovery] section for configurable search dirs, global dirs, and rules dirs. Config CRUD via rtk config get/set/unset/list. Per-project .rtk/config.toml overlay. Env var overrides: RTK_SEARCH_DIRS and RTK_RULES_DIRS (comma-separated paths, replace defaults when set).

---

Implementation Notes

1. Hooks moved from shell to Rust
   • Previous: hooks/rtk-rewrite.sh (204 lines of hard-coded sed/grep patterns, only rewrote the first command in chains)
   • New: rtk hook claude / rtk hook gemini (native Rust handlers)
   • Improvements over the shell approach:
     1. Chained commands work. cd /path && git status rewrites both commands independently (core fix for Hook: chained commands (cd dir && cmd) are never rewritten #112)
     2. Extensible. Add new commands via src/rules/*.md files, not bash edits
     3. Debuggable. rtk hook check <cmd> shows exact rewrites (impossible with bash)
     4. Multi-platform. Single codebase for both Claude Code and Gemini CLI (protocol adapters only)
     5. Backward compatible. Legacy hook script becomes a 3-line shim that forwards to rtk hook claude
2. Backward compatible: All existing token-saving features work unchanged. Data safety rules are opt-out via env vars.
3. Binary size: 5.1 MB (+0.3 MB over master's 4.8 MB, from trash + which deps and embedded rules; LTO + stripping enabled).
4. New dependencies: trash (cross-platform trash API for rm safety), which (binary path validation for hook installation).

Not Included (Future)

• Extended data safety rules: sudo rm, docker rm, kubectl delete with confirmations
• Analytics on which data safety rules fire most often
• Additional built-in predicates (currently: always, has_unstaged_changes, plus arbitrary shell commands)

---

Review Guide

1. src/cmd/lexer.rs + src/cmd/analysis.rs — Chain parsing correctness
2. src/cmd/safety.rs + src/rules/ — Data safety rule matching and rewriting
3. src/cmd/claude_hook.rs + src/cmd/gemini_hook.rs — Protocol compliance with each platform
4. src/config/rules.rs + src/config/discovery.rs — Rule loading, precedence, override semantics
5. src/init.rs — Installation flow (rtk init --claude --gemini)
6. Cargo.toml — New dependencies (trash, which) validated through functional tests above

Test Plan

• cargo test — 656 tests pass
• rtk hook check "rm file" — hook rewrites to rtk run -c 'rm file' (hook layer)
• rtk run -c "rm file" — executes the rewrite: file moved to trash, not deleted (execution layer)
• rtk hook check "cd /tmp && git status" — rewrites both commands independently
• RTK_SAFE_COMMANDS=0 rtk run -c "rm file" — passes through (opt-out works)
• RTK_BLOCK_TOKEN_WASTE=0 rtk run -c "cat file" — cat executes (opt-out works)
• In a clean working tree, rtk run -c "git reset --hard" — no stash created (when: has_unstaged_changes condition fails)
• rtk run -c "git clean -fd" — stashes untracked files before cleaning (when: always)
• rtk run -c "git stash drop" — rewrites to git stash pop (when: always)
• rtk config list — shows [discovery] section with search_dirs, global_dirs
• rtk config set discovery.search_dirs .rtk,.custom && rtk config get discovery.search_dirs — config CRUD works
• rtk init --claude && rtk init --gemini — installs hooks for both platforms
• Place custom rtk.safety.chmod-777.md in ~/.config/rtk/ — rtk run -c "chmod 777 file" triggers warning
• Place override rtk.safety.rm-to-trash.md with enabled: false in .rtk/ — project-level rule overrides global, rm passes through

Please let me know what you think!