AGENTS.md instructions can be read correctly but then applied inconsistently later in the same session

Open 💬 4 comments Opened Jun 2, 2026 by cellis-saasoptics
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What variant of Codex are you using?

CLI / terminal agent workflow

What version of Codex CLI is running?

codex-cli 0.136.0

What subscription do you have?

Using Codex through a managed terminal session. I do not have the subscription tier exposed in the session UI.

Which model were you using?

GPT-5 family. The session UI did not expose the exact runtime model, but the local Codex cache on this machine was current as of 2026-06-02 and included gpt-5.5.

What platform is your computer?

macOS

What issue are you seeing?

Codex can correctly read project AGENTS.md files early in a session, but later turns may stop applying those rules reliably.

In practice, Codex will sometimes:

  • miss explicit mandatory rules from AGENTS.md
  • act as if it checked AGENTS.md when it had not re-read the relevant file
  • continue making changes that violate repo policy until the user forces a review

This seems different from AGENTS.md discovery, truncation, or precedence issues. In my case, the files were small enough to be read, and Codex could summarize the rules correctly. The problem was inconsistent retention/application across turns.

What steps can reproduce the bug?

  1. Use a repository with nested AGENTS.md files (for example, a repo root AGENTS.md plus a subproject-specific AGENTS.md).
  2. Put concrete mandatory repo rules in the active AGENTS.md, such as:
  • all new functions/methods/class attributes must have type hints
  • migrations must be additive / forward-only
  • new non-null columns must use db_default
  • when a source or test file changes, run the complete corresponding test file(s)
  1. Start a multi-turn coding session inside the subproject.
  2. Ask Codex to implement a task that touches models, migrations, and tests.
  3. Continue the same session for follow-up work or ask Codex to review its own work against the repo rules.
  4. Observe that later in the same session Codex may still miss explicit AGENTS.md requirements it previously knew, for example by creating a reversible RunPython migration, omitting db_default, omitting type hints, or needing the user to remind it to re-read AGENTS.md at all.

What is the expected behavior?

Once the relevant AGENTS.md files are in scope, Codex should apply those mandatory repo rules reliably for the rest of the session, or until directory context changes.

If directory or repo context changes, Codex should automatically refresh the relevant AGENTS.md files before acting.

Codex also should not say or imply that it followed AGENTS.md unless it actually checked the active files.

What is the actual behavior?

In a live session, Codex initially read the repo AGENTS.md files and could restate the rules. But on later turns it still:

  • missed repo-mandated migration rules
  • missed repo-mandated type-hint rules
  • needed user correction to notice AGENTS.md-driven testing/validation expectations
  • repeated the same pattern more than once in the same session

The net effect is that AGENTS.md behaves more like a soft hint than a durable operating constraint.

Additional information

  • This was observed in a macOS terminal-based Codex session.
  • The repo had both root-level and subproject-level AGENTS.md files.
  • The issue seems to be about instruction retention/application across turns, not file discovery.
  • This feels related to, but distinct from:
  • #25515 (AGENTS.md validation requirements losing to higher-precedence runtime instructions)
  • #13386 (AGENTS.md truncation)

Requested fix

  1. Treat active AGENTS.md rules as sticky session constraints, not one-turn context.
  2. Refresh the relevant AGENTS.md files automatically when cwd/repo scope changes.
  3. Give the model a structured summary of active AGENTS.md requirements every turn or at least every task/context transition.
  4. Add visible diagnostics showing which AGENTS.md files are currently active.
  5. Prevent the assistant from claiming AGENTS.md compliance unless the active files were actually loaded/checked.

View original on GitHub ↗

4 Comments

github-actions[bot] contributor · 2 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #25792

Powered by Codex Action

jazzathoth · 2 months ago

I found a problem from probably same source. I discovered codex is not using new/changed agents.md even after restarting the Codex app. It would be very helpful for large project workflows to be able to reliably use and update AGENTS.md for longer sessions vs just setting it as one time context at the beginning, which seems to be what is happening.
Steps:

Start Codex in repo root with AGENTS.md containing marker A.
Ask marker question; marker A behavior works.
Exit Codex.
Edit AGENTS.md to marker B.
Run codex again from the same repo root.
Use /resume to resume the prior session.
Ask marker question.

Result:
The resumed session still behaves as if old AGENTS.md contents are active.

Workaround:
Asking codex to check AGENTS.md does help temporarily.
However, AGENTS.md should be treated as high priority system prompt type rules, not normal project context.
If that isn't possible with current architecture, it would be nice to have another file that is treated that way.

I'm on the same codex version, codex-cli 0.136.0, but on linux (ubuntu 24.04).
Didn't see anything obvious in changelogs, but I'll update codex to 0.139 and if behavior changes, I will comment.

Necmttn · 2 months ago

AGENTS.md should be tracked as a versioned instruction artifact in the session state.

For each loaded file, persist path, hash, scope, loaded_at turn id, and whether it was revalidated after edits. Later tool calls can reference the instruction hash they were operating under, and resume/long sessions can refresh when the file hash changes.

That makes drift visible instead of behavioral.

---

_Generated with ax._

MemoAsh · 1 month ago

One mitigation that has worked well for me is to make critical AGENTS.md rules active checks, not only background instructions.

For rules like "do not edit migrations except additively", "do not touch generated files", or "run the matching test file", I would structure the workflow as:

  1. before editing, list the repo instruction files that are in scope
  2. extract the task-relevant mandatory rules into a short checklist
  3. list planned files to edit
  4. compare planned edits against restricted paths/rules
  5. before finishing, report which checklist items were verified and which were not

That does not replace native sticky AGENTS.md handling, but it makes drift visible. If the agent skipped the active rule check, the final answer is obviously incomplete instead of silently wrong.

I made a small "safe edit" example of this pattern here:

https://github.com/MemoAsh/agent-workflow-pack/tree/main/examples/safe-edit-workflow

The important part is the verification.md file: it forces the agent to state what it checked, not just claim it followed the instructions.