Refresh project instructions when AGENTS.md scope changes across turns

Resolved 💬 4 comments Opened Apr 1, 2026 by ansh-info Closed Apr 2, 2026

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.md as 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.md content 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.rs
  • snapshot_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

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗