Proposal: explain routing decisions through rtk hook check

[jacobshaw01-del]

I would like to contribute an incremental improvement to RTK's routing diagnostics and would appreciate maintainer feedback before implementing a core change.

I use RTK in a development workflow spanning Rust and iOS tooling. While contributing fixes and simulator support, I became interested in making it easier for users to understand why a particular command is rewritten, passed through, or skipped.

Proposed first contribution

The shared decision layer is already in place. In the code I reviewed at 6d104308, registry None results and HookDecision::Defer can discard why a command was skipped. My proposed first PR would propagate reason codes from the actual decision path and expose them through an opt-in diagnostic, for example:

rtk hook check --agent codex --explain 'git status'

The explanation would distinguish cases such as:

• A supported filter matched.
• A user exclusion prevented rewriting.
• No filter matched the command.
• An existing shell or pipeline guard prevented rewriting.
• An already RTK-prefixed command needed no change.

This would extend the existing decision layer. Explanations should come from the branch that made the decision, so the diagnostic stays consistent with the selected host's behavior.

Compatibility and validation

The first PR would preserve current hook responses, approval behavior, and default CLI output when the explanation option is absent. Host-specific permission differences would remain explicit. Existing rtk rewrite exit codes and hook JSON protocols would be covered by regression tests, alongside checks that the diagnostic executes no user command. I would also benchmark the ordinary routing path to check for added overhead.

Possible follow-up work

Once that foundation is useful, follow-up contributions could distinguish filter coverage from actual rewrite eligibility in reporting, make filter capabilities such as stdin/streaming requirements more explicit, and improve wrapper or compound-command support through focused regression cases.

The request in discussion #2486 to identify uncovered commands seems related. A per-command explanation could complement that reporting by showing why a command was missed.

Does this fit the direction you want for the routing layer? Would you prefer a particular result type or diagnostic interface, or is there existing work I should build on? I'm happy to start with a small, focused PR based on your guidance.