Refresh project instructions when AGENTS.md scope changes across turns
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
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗