Skip to content

fix(hooks/codex): write RTK reference to AGENTS.override.md, not AGENTS.md#1977

Open
YOMXXX wants to merge 1 commit into
rtk-ai:developfrom
YOMXXX:fix/codex-agents-override-target
Open

fix(hooks/codex): write RTK reference to AGENTS.override.md, not AGENTS.md#1977
YOMXXX wants to merge 1 commit into
rtk-ai:developfrom
YOMXXX:fix/codex-agents-override-target

Conversation

@YOMXXX
Copy link
Copy Markdown
Contributor

@YOMXXX YOMXXX commented May 20, 2026

Summary

`rtk init --codex` previously injected its `@RTK.md` reference into Codex's base `AGENTS.md` file, mingling RTK output with user-authored base instructions. Codex's documented layering puts user/tool overrides in `AGENTS.override.md` — the least-destructive layer — so this PR routes RTK there. Existing installs that wrote into `AGENTS.md` are migrated cleanly: the legacy RTK reference (and any older inline `` block) is stripped from `AGENTS.md`, and the modern `@RTK.md` reference is added to `AGENTS.override.md`.

Reproduction

```bash
mkdir -p /tmp/codex-repro && cd /tmp/codex-repro
printf '# Base rules\nAnswer in Spanish.\n' > AGENTS.md
rtk init --codex
diff -u <(printf '# Base rules\nAnswer in Spanish.\n') AGENTS.md

Before this PR: diff (AGENTS.md was modified, @RTK.md appended)

After this PR: no diff (AGENTS.md untouched, @RTK.md lives in AGENTS.override.md)

cat AGENTS.override.md

After this PR: contains the @RTK.md reference

```

Root cause

`src/hooks/init.rs:2287-2353` (`run_codex_mode` / `run_codex_mode_with_paths`): both global and local codex install paths joined `codex_dir / AGENTS.md` and called `patch_agents_md()` on that path. `hook_check.rs:172` similarly used `AGENTS.md` as the install marker.

Fix approach

  • Add `CODEX_OVERRIDE_MD = "AGENTS.override.md"` constant.
  • Replace `run_codex_mode_with_paths(agents_md_path, rtk_md_path, …)` with `run_codex_mode_at(codex_dir, global, ctx)`. Inside, derive `AGENTS.md` (read-only legacy migration target) and `AGENTS.override.md` (write target) from `codex_dir`.
  • New `migrate_agents_md_to_override(agents_md, _override, ctx)`: strips RTK-owned content (`@RTK.md` reference and/or rtk-instructions marker block) from a legacy `AGENTS.md`. The companion `patch_agents_md(&override_md_path, …)` call (already idempotent) then writes the canonical `@RTK.md` reference into `AGENTS.override.md`. The legacy inline block content is not copied to override.md — it would be stale relative to the freshly written `RTK.md` and `patch_agents_md` would treat it as a migration candidate anyway.
  • `uninstall_codex_at` now scrubs both `AGENTS.md` and `AGENTS.override.md`, so users upgrading from an older RTK install get fully cleaned up regardless of which file was touched.
  • `hook_check.rs:172` now treats either `AGENTS.md` or `AGENTS.override.md` as a valid codex-installed marker.
  • `run_codex_mode_with_paths(…)` is retained behind `#[cfg(test)]` as a thin compatibility shim so unchanged tests keep compiling.

Behavior changes

  • Fresh install (no legacy state): writes `AGENTS.override.md` and `RTK.md`; `AGENTS.md` is never touched.
  • Legacy install (RTK content lives in `AGENTS.md`): on next `rtk init --codex`, RTK content is stripped from `AGENTS.md` (user content preserved verbatim) and re-added to `AGENTS.override.md`.
  • Uninstall: scrubs both files (legacy + current).
  • Public API (`pub fn run_codex_mode`) unchanged.

Test plan

  • `test_run_codex_mode_global_writes_absolute_reference_to_override_md` — fresh install path writes `AGENTS.override.md` only, `AGENTS.md` not created.
  • `test_run_codex_mode_preserves_user_agents_md_content` — pre-existing `AGENTS.md` byte-for-byte unchanged.
  • `test_run_codex_mode_migrates_legacy_agents_md_reference` — legacy `@RTK.md` reference moved out of `AGENTS.md` into `AGENTS.override.md`.
  • `test_run_codex_mode_migrates_legacy_agents_md_rtk_block` — legacy inline `rtk-instructions` block stripped from `AGENTS.md`; `AGENTS.override.md` holds the modern reference.
  • `test_uninstall_codex_at_cleans_legacy_agents_md_and_override` — uninstall touches both files.
  • Existing codex tests updated (one renamed) and pass unchanged.
  • `cargo fmt --all` clean.
  • `cargo clippy --all-targets` zero warnings.
  • `cargo test --bin rtk -- --test-threads=8` 1905 passed, 0 failed.

Fixes #1943

…TS.md

Codex CLI exposes two layered instruction files: AGENTS.md (base) and
AGENTS.override.md (local overrides). The override layer is the
intended target for tool-generated content because it keeps the base
file pristine and makes generated changes easy to reason about and
clean up.

Prior behavior: rtk init --codex wrote '@RTK.md' into AGENTS.md, which
mingled RTK output with user-authored base instructions and made
provenance harder to track.

New behavior:
- run_codex_mode now routes through run_codex_mode_at(codex_dir, ...),
  which writes the @RTK.md reference into AGENTS.override.md.
- On install, any RTK content found in a legacy AGENTS.md (inline
  rtk-instructions block and/or @RTK.md reference) is stripped from
  the base file; the reference is then added to AGENTS.override.md.
  User-authored AGENTS.md content is preserved verbatim.
- uninstall_codex_at scrubs both AGENTS.md (legacy) and
  AGENTS.override.md (current), so users upgrading get fully cleaned
  up.
- hook_check tests now treat AGENTS.override.md as a valid codex
  install marker alongside AGENTS.md.

Five new tests cover: fresh install writes to override.md only,
existing AGENTS.md content is preserved, legacy @RTK.md reference is
migrated, legacy inline RTK block is stripped, uninstall cleans both
files.

Fixes rtk-ai#1943
@CLAassistant
Copy link
Copy Markdown

CLAassistant commented May 20, 2026

CLA assistant check
All committers have signed the CLA.

@YOMXXX
Copy link
Copy Markdown
Contributor Author

YOMXXX commented May 20, 2026

recheck

1 similar comment
@YOMXXX
Copy link
Copy Markdown
Contributor Author

YOMXXX commented May 20, 2026

recheck

@YOMXXX YOMXXX closed this May 20, 2026
@YOMXXX YOMXXX reopened this May 20, 2026
@YOMXXX
Copy link
Copy Markdown
Contributor Author

YOMXXX commented May 20, 2026

@CLAassistant recheck

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Codex rtk init edits .codex/AGENTS.md instead of .codex/AGENTS.override.md

2 participants