Repository navigation
Refresh project instructions when AGENTS.md scope changes across turns #16403
Description
What variant of Codex are you using?
CLI
What feature would you like to see?
Codex should refresh the model-visible project instructions when the effective AGENTS.md set changes between turns, especially when the turn cwd moves to a different project subtree.
Today, project docs are discovered from the current cwd and merged into user instructions, but that instruction block is not re-emitted when the applicable AGENTS.md content changes across turns. This means a session can continue using stale project guidance after a cwd change, even though the new directory has different instructions.
This would improve:
- multi-directory and monorepo workflows
- reliability of scoped per-directory instructions
- trust in
AGENTS.mdas the source of truth for local guidance - predictability when users intentionally change cwd between turns
Proposed behavior:
- Recompute the effective project-doc payload for each turn using the submitted cwd
- If the resulting instruction content differs from the last emitted project-doc payload for the thread, emit the updated instructions into the next model-visible request
- Re-emit only when the effective content actually changes
Acceptance criteria:
- Changing cwd to a directory with different effective
AGENTS.mdcontent refreshes the next turn’s project instructions - No duplicate re-emission when the effective content is unchanged
- Existing single-directory behavior remains unchanged
- Test coverage includes cwd-based instruction refresh
Additional information
There is already a TODO and regression snapshot in the codebase pointing at the current behavior:
codex-rs/core/tests/suite/model_visible_layout.rssnapshot_model_visible_layout_cwd_change_does_not_refresh_agents
The test comment explicitly notes that Codex should diff user_instructions and emit updates when AGENTS.md content changes.
Implementation direction:
- Recompute project docs from the turn cwd using the existing discovery path
- Keep the last emitted project-doc payload in thread or session state
- Diff old vs new payload before building the next request
- Update the existing snapshot test to assert refreshed instructions
Activity
ansh-info commentedon Apr 1, 2026
I implemented a candidate fix for this in my fork:
feat/agents-md-refresh-16403b7d1314b2(Refresh AGENTS instructions on cwd changes)What it changes:
AGENTS.md/ project-doc instructions from the per-turn cwduser_instructionsthrough the existing context-diff pathValidation:
cargo test -p codex-core snapshot_model_visible_layout_cwd_change_refreshes_agents -- --nocapturecargo test -p codex-core model_visible_layout_same_cwd_does_not_restate_agents -- --nocaptureBoth targeted checks compiled and completed successfully in my environment. The test bodies were skipped by the suite's sandbox/network guard, but the code and updated test targets compiled cleanly.
I also added coverage for:
I can’t open a PR because this repository restricts PR creation to collaborators, but I’m happy to share the patch/branch details here if helpful.
ansh-info commentedon Apr 1, 2026
@charley-oai I implemented a candidate fix for this in my fork and shared the branch, commit, and verification details above. Since PRs are restricted to collaborators here, I wanted to flag it directly in case it is useful to cherry-pick or adapt.
@aibrahim-oai tagging you as well since this touches the existing context-diff path for model-visible updates.
Fork branch:
Commit:
ansh-info commentedon Apr 1, 2026
Follow-up verification update: I was able to run the two targeted tests outside the Codex sandbox-skipping environment, and both passed at runtime.
Passed:
cargo test -p codex-core snapshot_model_visible_layout_cwd_change_refreshes_agents -- --nocapturecargo test -p codex-core model_visible_layout_same_cwd_does_not_restate_agents -- --nocaptureUpdated commit:
21bd74e58(Refresh AGENTS instructions on cwd changes)etraut-openai commentedon Apr 2, 2026
AGENTS.md instructions are sent at the beginning of a thread. Overriding previous instructions will generally confuse the model. If you decide to modify AGENTS.md, you should create a new thread.
If you change the cwd, you should definitely create a new thread.