Preserve `AGENTS.md` Source File Locations In Model-Visible `user_instructions`

What variant of Codex are you using?

CLI

What feature would you like to see?

Expose the source file locations of discovered AGENTS.md documents in the model-visible project-instructions payload, instead of flattening all discovered project-doc text into a single unlabeled blob.

Problem

Today, Codex discovers project instructions from multiple files along the scope chain, but the model-visible user_instructions payload appears to contain only:

• a single wrapper like # AGENTS.md instructions for <cwd>
• the concatenated instruction text

This means the model sees the instruction content, but not which text came from which file.

That creates a few practical problems:

• Large AGENTS.md setups are hard to maintain. Once guidance grows, teams naturally want to split it into smaller scoped files.
• The model loses provenance. It cannot tell whether a rule came from the repo root, a nested subtree, an override file, or a fallback project doc.
• Users must duplicate information manually. If we want the agent to know where a rule came from, the workaround is to hardcode file paths inside the document text, even though Codex already knows the discovered file paths internally.
• Debugging precedence becomes harder. When rules conflict or the model follows an unexpected instruction, neither the user nor the model can easily tell which file supplied it.

Why this matters

This discourages decomposition of project guidance into smaller scoped files, even though scoped AGENTS.md is a core part of the feature.

It is especially painful in:

• monorepos
• multi-directory projects
• teams with root rules plus package-specific rules
• setups using AGENTS.override.md or configured fallback filenames

Current behavior

Codex internally discovers the relevant project-doc paths, but the final model-visible instructions flatten them into plain text without preserving per-file provenance.

As a result, the model can read the instructions, but cannot tell:

• which files were discovered
• in what order they were applied
• which instruction text came from which file

Expected behavior

Codex should preserve source provenance for discovered project-doc files in the model-visible payload.

For example:

# AGENTS.md instructions for /repo/packages/foo

<INSTRUCTIONS>
<AGENTS_FILE path="AGENTS.md">
...root instructions...
</AGENTS_FILE>

<AGENTS_FILE path="packages/foo/AGENTS.md">
...package instructions...
</AGENTS_FILE>
</INSTRUCTIONS>

The exact syntax is flexible, but the model should be able to tell:

• which files were discovered
• in what order they were applied
• which instruction text came from which file

Suggested behavior

• Include one structured section per discovered project-doc file
• Use project-root-relative paths when possible
• Fall back to cwd-relative or absolute paths only when necessary
• Preserve current precedence/order from root to deeper scope
• Update documentation to explicitly state whether source file locations are included or omitted

Acceptance criteria

• If multiple AGENTS.md files are active, the model-visible payload identifies each source file separately
• The payload preserves source order
• The payload works with AGENTS.override.md and fallback project-doc filenames too
• Documentation explicitly states whether source file locations are included or omitted

Related issues

Related, but distinct from, AGENTS refresh/reload requests:

• #3198
• #8547
• #16403

Loosely related:

• #11757

Additional information

This is not just a debugging aid. It improves maintainability and reduces user burden by letting teams split guidance into smaller scoped files without losing provenance at prompt-construction time.