AGENTS.md: git submodule stops discovery at submodule root; superproject AGENTS.md silently ignored

What variant of Codex are you using?

CLI

What feature would you like to see?

When a Codex session starts inside a git submodule whose superproject also contains an AGENTS.md, discovery stops at the submodule's own .git marker and the superproject's AGENTS.md is silently invisible. Detect this case (superproject AGENTS.md present + not loaded) and emit a one-line stderr hint telling the user how to opt in via project_root_markers.

Reproducer

/repo/                          <- superproject
  .git                          <- superproject .git dir (or .gitmodules present)
  .gitmodules
  AGENTS.md                     <- family-wide rules (Caveman, Ponytail, no-card, etc.)
  sub/
    .git                        <- submodule .git file/dir
    AGENTS.md                   <- submodule-specific rules

cd /repo/sub && codex ? agents_md_paths walks sub/, finds sub/.git, treats sub/ as project root, loads sub/AGENTS.md only.

The superproject AGENTS.md never enters context. The user gets no signal that a plausibly-relevant instruction file is being ignored.

Confirmed empirically with codex-cli 0.142.4 on Windows: running codex debug prompt-input "hi" from C:\D\oriz\repos\frk\omniroute (a git submodule of C:\D\oriz, superproject has its own AGENTS.md with universal cross-cutting rules) shows only the submodule's AGENTS.md in the developer message. The umbrella's rules never load.

Source-level confirmation

codex-rs/core/src/agents_md.rs:

Determine the project root by walking upwards from the current working directory until a configured project_root_markers entry is found. When project_root_markers is unset, the default marker list is used (.git).

Default marker is .git. git submodule places .git (a file, not a dir, but same filename) inside the submodule, so the walk terminates one level too shallow for polyrepo/umbrella-of-submodules layouts.

Why the existing escape hatch isn't enough

project_root_markers can be set to something like [".gitmodules", ".git"] to reach the superproject — but:

1. It's a workspace-wide config, not per-cwd — setting it globally breaks single-repo projects that happen to have a .gitmodules file for their own submodules.
2. It's silently misconfigured: the failure mode is "your family rules never load," which the user notices only when the model violates one of them. There's no warning at session start.
3. The docs for project_root_markers (search the repo — the only mentions are the two closed bugs #12128 and #12539 from Feb 2026) do not call out the submodule case. New users who inherit a polyrepo workspace hit this cold.

Proposed fix

At session start, after agents_md_paths resolves the project root, do a bounded look-up-one-more-level check:

1. If the chosen project root has an ancestor within N=5 levels that contains both .gitmodules (or a git worktree list entry showing this repo as a submodule) and an AGENTS.md, emit a single stderr line:

``
codex: superproject AGENTS.md at /repo/AGENTS.md is not being loaded (walk stopped at submodule root /repo/sub/).
codex: to include it, add project_root_markers = [".gitmodules", ".git"] to ~/.codex/config.toml.
``

1. One line, stderr, once per session. No prompting, no auto-loading (auto-loading would surprise users who genuinely want submodule isolation).
2. Suppress with --quiet or -c project_root_markers_hint=false.

Alternative shape

Alternatively, treat .gitmodules as an implicit marker: if the walk hits .git inside a directory whose parent has .gitmodules, keep walking up until either (a) a marker without a .gitmodules parent, or (b) filesystem root. This behaves correctly for the common umbrella-of-submodules case without config changes. Users who want strict submodule isolation set project_root_markers = [".git"] explicitly.

Second option is cleaner but more behavior-changing. The stderr-hint option is strictly additive and doesn't change discovery semantics.

Why this matters

Submodule-based monorepo layouts are common (Codex's own repo uses submodules for docs/openai-python, etc.; every workspace using git submodule for polyrepo aggregation hits this). AGENTS.md was designed as a cross-tool standard specifically for teams that share instruction sets across repos — and the most natural way to share is via a superproject with an umbrella AGENTS.md plus per-submodule specialization. The current behavior silently regresses that use case.

Related

• #28903 — "AGENTS.md not loaded from ancestor directories above repo root" — covers the projectless-chat case (no .git anywhere). Distinct from the git-submodule case (both submodule and superproject are proper git repos).
• #12128, #12539 (both closed) — project_root_markers bugs. Fixed, but the config option is undocumented for the submodule case.
• #17401 — @include directive for composable AGENTS.md — orthogonal (composition inside a file); this issue is about which files enter the graph at all.
• #29535 — "Global AGENTS.md relative links resolve against the workspace cwd" — related family (link resolution across ancestor files).

Version tested

codex-cli 0.142.4 (Windows x64). Reproducer: C:\D\oriz (superproject with own AGENTS.md) ? C:\D\oriz\repos\frk\omniroute (submodule with own AGENTS.md) ? codex debug prompt-input from submodule shows only submodule's rules.