fix(cli): document rewrite exit-code contract

[tandede]

Summary

• document all four exit statuses returned by rtk rewrite
• remove integration guidance that discards valid rewrites returned with exit 3
• align the feature documentation and add regression coverage for the public CLI help contract

Context

Exit 3 intentionally includes the rewritten command on stdout and indicates that user approval is still required. The existing CLI help only documents exits 0 and 1 and recommends a shell idiom that treats every nonzero result as a passthrough.

The shipped hooks already distinguish exit 3 correctly, so this change does not alter runtime permission behavior. It makes the public integration contract match the existing implementation.

Testing

• cargo fmt --all --check
• cargo clippy --all-targets -- -D warnings
• cargo test — 2705 passed, 8 ignored
• manually verified exit 3 with rewrite output and exit 1 without output

Addresses #3634.

[CLAassistant]

All committers have signed the CLA.

[jondmarien]

Confirmed on RTK 0.49.0 with Codex CLI 0.155.1 on Linux: rtk rewrite 'git status' prints rtk git status but exits 3; an unsupported command such as pwd exits 1 with no output.

Workaround on my setup: route Codex PreToolUse through TokSave’s toksave rtk-hook codex adapter. It uses the rewrite output instead of treating every nonzero status as “no rewrite,” then returns the changed command through hookSpecificOutput.updatedInput. End-to-end, Codex’s ls -la ran as rtk ls -la and exited 0; output went from 5,130 to 864 characters (about 83% fewer bytes). A generic adapter can likewise capture stdout and apply a non-empty rewrite even when the process exits 3.

Thanks for documenting the exit-code contract here; this workaround kept my Codex integration working without relying on the misleading || exit 0 pattern.

[KuSh]

Thanks for this, and for spotting that rtk rewrite --help still described a two-code protocol. #4204 makes the same change, and I'm landing it there rather than reviewing both.

Your docs/usage/FEATURES.md section and your help test go into #4204 in d0abeeb, with you as co-author. I adjusted both to the current code: the test now checks that each code renders as its own paragraph (clap joins consecutive doc lines, so the four Exit N: lines came out as one), and the French text covers exit 0 needing allow rules on every command of a chain and RTK_REWRITE_HOST=openclaw, which landed in #3909 after this PR opened.

Closing in favour of #4204.