Auto-rewriting discovery commands can silently lose exact file/path semantics for agents

Summary

RTK's Claude Code hook currently auto-rewrites common discovery commands such as find, grep/rg, and ls into rtk find, rtk grep, and rtk ls.

That works well for noisy output, but it is risky for source discovery workflows where the agent needs exact native command semantics and exact file paths. In a real Claude Code session, this made the agent look confused because it was reasoning from lossy/changed search output rather than the native command output.

This is related to hook/output issues such as #1282 and #1233, but the issue here is narrower: read-only discovery commands are rewritten even when the RTK equivalent is not semantically equivalent to the native command.

Concrete example from a real session

The agent tried to locate a local skill:

find ~/.claude -type d -name "copywriting" 2>/dev/null

The hook rewrote it to:

rtk find ~/.claude -type d -name "copywriting" 2>/dev/null

The native command would return an exact path. The RTK output returned a compact grouped form:

1F 1D:

skills/ copywriting

That removed the exact absolute path the agent needed for the next Read/cat step.

Another command:

find ~/.claude -path "*blog*SKILL.md" 2>/dev/null

was rewritten to:

rtk find ~/.claude -path "*blog*SKILL.md" 2>/dev/null

In the observed session this produced a compact no-result line:

0 for '/Users/<user>/.claude'

This appears consistent with the current parser: rtk find only treats -name, -iname, -type, and -maxdepth as native find flags, and does not support -path.

The agent then searched wider with grep -rl and ended up matching Claude session JSONL files instead of the actual skill definition, causing the investigation to drift.

Why this matters

For build/test/log output, compression is usually a win.

For discovery commands, the exact output is often the data the agent uses to decide what file to inspect next. If the output is compressed, path-stripped, truncated, or parsed with a different subset of native flags, the agent can draw a wrong conclusion while everything still exits successfully.

In other words, the failure mode is not a visible crash. It is a false observation.

Source pointers

Current behavior I checked on commit 5a149a7fdb92afe758a0c28d805873ce61d8259f:

• Hook-based agents rewrite Bash commands before execution: https://github.com/rtk-ai/rtk/blob/5a149a7fdb92afe758a0c28d805873ce61d8259f/README.md#L119-L121
• Claude hook emits updatedInput.command: https://github.com/rtk-ai/rtk/blob/5a149a7fdb92afe758a0c28d805873ce61d8259f/src/hooks/hook_cmd.rs#L300-L352
• Rewrite rules include grep, ls, and find: https://github.com/rtk-ai/rtk/blob/5a149a7fdb92afe758a0c28d805873ce61d8259f/src/discover/rules.rs#L91-L117
• rtk find only recognizes a limited native flag subset: https://github.com/rtk-ai/rtk/blob/5a149a7fdb92afe758a0c28d805873ce61d8259f/src/cmds/system/find_cmd.rs#L59-L76 https://github.com/rtk-ai/rtk/blob/5a149a7fdb92afe758a0c28d805873ce61d8259f/src/cmds/system/find_cmd.rs#L100-L142
• rtk find stores paths relative to the search root: https://github.com/rtk-ai/rtk/blob/5a149a7fdb92afe758a0c28d805873ce61d8259f/src/cmds/system/find_cmd.rs#L264-L269
• rtk find prints 0 for '<pattern>' on no result: https://github.com/rtk-ai/rtk/blob/5a149a7fdb92afe758a0c28d805873ce61d8259f/src/cmds/system/find_cmd.rs#L280-L282
• rtk find prints compact grouped output like 1F 1D: https://github.com/rtk-ai/rtk/blob/5a149a7fdb92afe758a0c28d805873ce61d8259f/src/cmds/system/find_cmd.rs#L309-L315
• rtk grep also compacts/truncates search output: https://github.com/rtk-ai/rtk/blob/5a149a7fdb92afe758a0c28d805873ce61d8259f/src/cmds/system/grep_cmd.rs#L101-L149 https://github.com/rtk-ai/rtk/blob/5a149a7fdb92afe758a0c28d805873ce61d8259f/src/cmds/system/grep_cmd.rs#L248-L264
• rtk ls always runs native ls -la internally and filters the result, so native intent such as ls -d <path> can be changed into a compact listing: https://github.com/rtk-ai/rtk/blob/5a149a7fdb92afe758a0c28d805873ce61d8259f/src/cmds/system/ls.rs#L22-L90

Expected behavior

Discovery commands should preserve native semantics unless RTK can guarantee equivalence.

At minimum, I would expect one of these:

1. Do not auto-rewrite find, grep/rg, or ls by default in the hook path.
2. Only rewrite a small allowlist of safe forms, and pass through unsupported native flags such as find -path.
3. Provide a separate "agent-safe discovery mode" where these commands return exact native paths/output by default.
4. Add a documented default config recommendation to exclude discovery commands:

[hooks]
exclude_commands = ["find", "grep", "rg", "ls"]

Actual behavior

The hook rewrites these commands automatically. The RTK commands then return compact output that can remove exact paths, group files by directory, truncate paths/lines, or parse only a subset of native flags.

Impact

This can make an AI coding agent confidently follow the wrong trail:

• cannot read the exact path returned by find
• thinks a skill/config/file does not exist because rtk find did not support the native predicate
• follows session logs or unrelated matches from a broad rewritten search
• spends extra turns debugging the wrong layer

I think RTK is still useful for noisy output, but discovery/search/file-location commands are a different class: false negatives and path loss are more expensive than token savings.