feat(codex): add native hooks integration

[sf-jin-ku]

Summary

• add native Codex PreToolUse integration via rtk hook codex
• extend rtk init --codex to patch .codex/config.toml and .codex/hooks.json
• fall back to prompt-only Codex setup on Windows and honor CODEX_HOME for global installs

Problem

rtk init --codex was prompt-only. It wrote RTK.md and patched AGENTS.md, but it did not install Codex lifecycle hooks, so Codex had no hard guardrail to route supported raw Bash commands through rtk.

What changed

Hook runtime

• add rtk hook codex
• reuse the existing rewrite source of truth via get_rewritten()
• for supported raw Bash commands, return Codex-native permissionDecision: "deny" with the exact rtk ... replacement
• pass through unchanged for unsupported commands, excluded commands, heredocs, and already-rtk commands

Codex install / uninstall / show

• rtk init --codex now patches:
  • RTK.md
  • AGENTS.md
  • .codex/config.toml
  • .codex/hooks.json
• ensure features.codex_hooks = true
• install one PreToolUse matcher group for Bash
• rtk init --show --codex now reports local/global Codex hook state
• rtk init --codex --uninstall now supports local uninstall
• leave codex_hooks = true in place on uninstall, but remove RTK-managed hook entries

Compatibility / edge cases

• use CODEX_HOME for global Codex path resolution instead of hardcoding ~/.codex
• on Windows, fall back to the old prompt-only Codex setup because upstream Codex disables lifecycle hooks there
• local .codex installs still depend on Codex project trust
• update Codex-facing docs and hook README/test layout to match the current hook structure under src/hooks and hooks/codex

Test plan

• cargo test --all
• cargo build && RTK=target/debug/rtk bash hooks/codex/test-rtk-rewrite.sh

Notes

Codex currently does not support transparent updatedInput rewrites for PreToolUse, so this integration uses deny-and-retry instead of the Claude/Cursor transparent rewrite flow.

[CLAassistant]

All committers have signed the CLA.

[pragmaton]

This is a solid improvement!

One important gap still seems unresolved: rtk verify still checks only the Claude hook path (~/.claude/hooks/rtk-rewrite.sh) and does not verify Codex hook installation/state.

That means after this PR, a Codex user can run rtk init -g --codex, get .codex/config.toml + .codex/hooks.json configured correctly, and still see:

SKIP RTK hook not installed

[sf-jin-ku]

This is a solid improvement!

One important gap still seems unresolved: rtk verify still checks only the Claude hook path (~/.claude/hooks/rtk-rewrite.sh) and does not verify Codex hook installation/state.

That means after this PR, a Codex user can run rtk init -g --codex, get .codex/config.toml + .codex/hooks.json configured correctly, and still see:

SKIP RTK hook not installed

Thanks! It has been fixed!

[rolandkakonyi]

@sf-jin-ku did you verify that Codex actually resolves the @RTK.md from a user-global ~/.codex/AGENTS.md?

I tried this branch and it seems this is a Codex limitation that @FILE is not resolved in global AGENTS.md but only in project-local AGENTS.md files.

See issue on Codex here: openai/codex#6038

A workaround could be to just inline the contents of RTK.md (wrapped into some markers maybe) to unblock global rtk installs.

[sf-jin-ku]

@rolandkakonyi addressed in e633de6.

I changed the Codex install path so it no longer relies on @RTK.md resolution for either global or project-local Codex installs. rtk init --codex now writes RTK-managed guidance inline into AGENTS.md, migrates legacy @RTK.md installs forward, and rtk verify now reports Codex AGENTS.md health explicitly alongside the Codex hook/config status.

That means global $CODEX_HOME/AGENTS.md / ~/.codex/AGENTS.md no longer depends on upstream @file include support.

[sf-jin-ku]

@aeppling quick note on the pending CLAassistant check: the only unsigned committer appears to be github-actions[bot], coming from commit 51939a5 (chore(master): release 0.34.2) that entered this branch when I merged upstream history earlier in the review cycle. The human contributors on this PR have already signed.

Also, 0.34.2 is no longer the current release line anyway: the latest stable release is v0.34.3 (April 2, 2026), and the repo is already publishing dev-0.35.0-rc.* prereleases today (latest I see is dev-0.35.0-rc.108 from April 3, 2026).

If the implementation looks good otherwise, could you bypass/ignore the CLAassistant pending state for this PR and include it in a later release batch instead of tying it to 0.34.2? The branch is mergeable again and includes the follow-up fixes for global Codex AGENTS guidance plus the rtk verify updates.

[callme-sy]

this looks good.

one thing i was wondering about is the rewrite-miss path.

from the PR it looks like commands that rtk rewrite can map get the deny-and-retry flow with the exact rtk ... replacement, and everything else passes through unchanged.

i’ve been testing a local codex hook prototype around the same idea, and i ran into a couple cases where rtk rewrite missed but direct rtk <cmd> still worked better.

do you think there’s eventually room for a lighter fallback for some rewrite misses before leaving the original command unchanged?

[rtk-release-bot]

This pull request has been automatically marked as stale due to 90 days of inactivity. If this pull request is still relevant, please leave any comment (for example, "bump"), and we'll keep it open. Your contribution is very much appreciated — we're sorry we haven't been able to review it yet.

[KuSh]

Closing in favour of #3552, which covers the same Codex PreToolUse integration, is the version a collaborator has reviewed, and uses the transparent updatedInput path that Codex now applies end to end. Thanks for the work here. Please take anything your branch handles that #3552 misses to that thread so the effort stays in one place.