Document global hook trust model for users

Summary

RTK v0.39.0 has a detailed hook permission/trust model in maintainer-facing docs, but the user-facing install/supported-agent docs do not expose the full model users need before enabling global hooks.

This is a hardening/documentation issue, not an accusation of malware. The code paths reviewed here mostly show deny-before-rewrite and safe pass-through behavior; the gap is that the exact trust model is not easy for users to find before rtk init -g.

Version / tag / commit

• Tag: v0.39.0
• Commit: 2fbc7514f6964acabcfac65501b8bb6b525e3aa8

Evidence

Maintainer-facing docs contain the detailed model:

• src/hooks/README.md:52-58 documents patch modes: Ask default, --auto-patch, and --no-patch.
• src/hooks/README.md:64-79 documents permission precedence: Deny > Ask > Allow (explicit) > Default (ask).
• src/hooks/README.md:81-89 documents per-tool differences, including Gemini no-ask behavior and Codex prompt-level limitations.

User-facing docs describe hooks and overrides, but not the complete permission/trust model:

• docs/guide/getting-started/supported-agents.md:12-24 explains that agent commands are intercepted and rewritten.
• docs/guide/getting-started/supported-agents.md:137-143 explains full hook vs plugin vs rules-file tiers.
• docs/guide/getting-started/supported-agents.md:155-175 documents fail-open behavior, RTK_DISABLED=1, and exclude_commands.
• README.md:294-308 documents installing the auto-rewrite hook.
• README.md:395-399 documents uninstall commands.

The install source has important file-system and behavior details that are not summarized in one user-facing trust model:

• src/hooks/init.rs:935-1007 for default global Claude mode writes ~/.claude/RTK.md, patches ~/.claude/CLAUDE.md, patches ~/.claude/settings.json, and writes a global filters template.
• src/hooks/init.rs:766-837 shows settings.json patching prompts by default, backs up existing settings to .json.bak, and writes atomically.
• src/hooks/init.rs:545-692 and :695-764 remove RTK-owned Claude/Codex artifacts and preserve surrounding user content.
• src/hooks/init.rs:1879-1916 and :2071-2133 install/remove Cursor hook entries.
• src/hooks/init.rs:2453-2643 installs/removes Gemini hook artifacts.
• src/hooks/rewrite_cmd.rs:18-47, src/hooks/hook_cmd.rs:300-352, and src/hooks/permissions.rs:31-88 show deny-before-rewrite and default-to-ask semantics for the supported processors.

Duplicate search performed:

• gh issue list -R rtk-ai/rtk --search "global hook trust model user docs"
• gh issue list -R rtk-ai/rtk --search "document hook permission model"
• gh issue list -R rtk-ai/rtk --search "supported agents permission model"
• gh issue list -R rtk-ai/rtk --search "Gemini hook allow default docs"

Related broad issues found: #587 and #640. They are not focused duplicates of this user-facing trust-model documentation gap.

Impact

Users deciding whether to run rtk init -g need one user-facing page that answers:

• exactly which files can be created, modified, backed up, or removed per agent;
• which commands are intercepted and which agent tools bypass hooks;
• how deny, ask, allow, and default verdicts map to hook behavior;
• which integrations can prompt and which integrations fail open or allow by platform/API limitation;
• how to disable per-command or permanently exclude commands;
• what uninstall removes and what it intentionally preserves.

Without that, a user can correctly see that RTK changes global agent behavior but has to read maintainer docs and source code to understand the precise boundary.

Verification steps

1. Inspect src/hooks/README.md:52-89 for the complete maintainer-facing model.
2. Inspect docs/guide/getting-started/supported-agents.md and README.md for the current user-facing install docs.
3. Compare those docs against src/hooks/init.rs, src/hooks/rewrite_cmd.rs, src/hooks/hook_cmd.rs, and src/hooks/permissions.rs.
4. Confirm that the complete trust model is not linked prominently from the global hook install path.

Suggested mitigation

Add a user-facing "Global hook trust model" or "Security model for agent hooks" page, linked from README install instructions and Supported Agents. It should include:

• per-agent file map for install/uninstall;
• patch mode table;
• permission precedence and per-agent behavior table;
• fail-open/pass-through behavior;
• RTK_DISABLED=1 and [hooks].exclude_commands;
• clear note that rules-file integrations are prompt guidance, while full hooks/plugins can rewrite commands before execution;
• clear note that this is command-rewrite hardening/privacy documentation, not malware concern.