docs(hooks): document tee fallback and RTK_DISABLED in Claude agent template

[mrskwiw]

Problem

RTK_DISABLED=1 and the tee-file fallback are both documented on the docs site
(docs/guide/getting-started/configuration.md) and in hooks/README.md, and
hooks/pi/rtk.ts surfaces RTK_DISABLED to the Pi agent directly.

hooks/claude/rtk-awareness.md mentions neither — and that file is the agent's
documentation. rtk init -g writes it to ~/.claude/RTK.md and @-references
it into context on every session. For a Claude Code agent, it is effectively the
only RTK docs that exist: nothing else is loaded, and an agent has no reason to
go read the docs site mid-task.

The practical consequence is that an agent which hits a case genuinely needing
raw output has no recorded option. It cannot reach for RTK_DISABLED=1 (never
seen it) and does not know the tee file is byte-complete ground truth. The
fallback it does have is to distrust the filtering — which costs far more
savings than an occasional deliberate opt-out would.

#508 added a stderr warning on RTK_DISABLED "so agents learn to stop
overusing it". That presumes agents know it exists; today the discovery path for
a Claude Code agent is reading src/discover/registry.rs.

Change

Adds a "When You Need the Full Output" section to
hooks/claude/rtk-awareness.md, documenting, in this order:

1. The tee file first — where it is, and that Read bypasses the hook so
   retrieving it is free.
2. RTK_DISABLED=1 second — for when raw output is needed in the same call,
   with explicit guidance to use it deliberately.

The ordering is the point. Routing agents to the tee file preserves token
savings while giving a concrete answer to "I need the full output" — which is
the actual underlying need behind most reflexive opt-outs.

Docs only; no behavior change. Note RTK_SLIM is also written as Gemini's
GEMINI.md (src/hooks/init.rs:4238), so the Gemini template benefits too.

Verification

Measured on v0.44.2, Windows 11, against this repo and a pytest fixture:

Command	Raw	RTK	Saved	Recoverable from tee?
git status	323 B	41 B	87%	n/a — nothing lost but git's hints
ls -la src/	594 B	124 B	79%	n/a
pytest (2 failures)	1274 B	272 B	79%	yes — full traceback, byte-complete
git diff (small)	300 B	159 B	47%	yes
curl (JSON API)	6767 B	6767 B	0%	passthrough, still jq-parseable

The pytest row is the one that motivated this. The compact output correctly
named both failing tests and their exception types, and the tee file held the
complete traceback — source lines, variable state, exact line numbers. That is
exactly the behavior the template should be telling agents about.

Escape hatch verified end to end:

$ rtk rewrite "cargo test"
rtk cargo test                          # exit 3 — rewritten

$ rtk rewrite "RTK_DISABLED=1 cargo test"
[rtk] RTK_DISABLED=1 detected — skipping filter for this command.
                                        # exit 1 — passthrough

Scope

Deliberately limited to the Claude template to keep the diff reviewable. The
same gap exists in hooks/codex/rtk-awareness.md, hooks/windsurf/rules.md,
hooks/cline/rules.md, hooks/antigravity/rules.md, and
hooks/kilocode/rules.md. Happy to extend this PR to all of them, or follow up
separately — maintainer's preference.

Checklist

• cargo fmt --all --check — clean
• cargo clippy --all-targets — clean
• cargo test — 2552 passed, 2 failed (pre-existing, see below)
• Single-focus diff, in scope with the title
• CHANGELOG.md not touched (release-please managed)

Unrelated: two non-hermetic tests

cargo test fails identically on a clean develop checkout with this branch
stashed, so these are not from this PR:

hooks::rewrite_cmd::tests::unattestable_passthrough::test_plain_command_still_rewrites
hooks::rewrite_cmd::tests::unattestable_passthrough::test_fd_dup_redirect_still_rewrites

Both assert matches!(evaluate("git status", ...), RewriteOutcome::Ask(_)).
evaluate() (src/hooks/rewrite_cmd.rs:47) calls check_command(cmd), which
reads the developer's ambient Claude Code settings.json. On a machine with a
Bash(git…) allow rule the verdict is Allow, not Ask, and both fail — so
they pass or fail depending on who runs them.

The sibling tests in hook_cmd.rs avoid this by using the injectable
check_command_with_rules(cmd, &[], &[], &[...]). Routing these two through the
same helper would make them hermetic. Left out of this PR to keep the diff
single-focus — happy to open a separate one if useful.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[KuSh]

Thanks for this, and for the measurements in the description. The file this patches, hooks/claude/rtk-awareness.md, was removed by #3372 (merged 2026-09-07), which replaced the per-agent rules files with three shared templates: hooks/rtk-awareness.md, rtk-awareness-high.md and rtk-awareness-full.md. The escape hatch you wanted recorded is in the new text already, as RTK_DISABLED=1 <cmd> in both the high and full variants, alongside rtk proxy <cmd>, and the templates point agents at the recovery path a truncated result prints. What none of the variants do is name the tee file explicitly as byte-complete ground truth, so if you still want that spelled out, a one line addition to hooks/rtk-awareness-full.md would be welcome as a small follow-up PR against the current templates. Reopen or comment if I have missed a part of this that the new templates do not cover.