codex - 💡(How to fix) Fix Parent agent redundantly re-explores the repo after spawning an explorer sub-agent [2 comments, 3 participants]

What version of Codex CLI is running?

codex-cli 0.121.0

What subscription do you have?

plus

Which model were you using?

gpt-5.4-high

What platform is your computer?

Linux 6.12.0-124.27.1.el10_1.aarch64

What terminal emulator and version are you using (if applicable)?

No response

What issue are you seeing?

When I ask Codex CLI to investigate a repository, the parent agent often spawns an explorer sub-agent and then continues reading many of the same high-value files itself instead of primarily coordinating and relying on the explorer’s findings.

In practice, this leads to duplicated repo exploration work:

• the parent agent reads top-level docs / entrypoints
• an explorer sub-agent reads the same or very similar files
• the parent agent then reads several of those files again to prepare the final answer

I have seen this happen multiple times in the same day on repo-investigation tasks. It does not usually produce a wrong answer, but it appears to waste time, tokens, and context window, and makes sub-agent delegation less effective than expected.

This seems especially surprising because the prompt stack appears to contain conflicting guidance:

• the base instructions tell the main agent to “build context by examining the codebase first without making assumptions”
• the explorer role says to avoid redundant work and typically trust explorer results without additional verification
• the orchestrator prompt says that when a sub-agent is doing the work, the parent should coordinate rather than do the actual work

The observed behavior suggests these instructions are not reconciling cleanly, and the current result is redundant exploration instead of efficient delegation.

What steps can reproduce the bug?

The observed behavior suggests these instructions are not reconciling cleanly, and the current result is redundant exploration instead of efficient delegation.

What steps can reproduce the bug?

1. Open a medium-to-large repository.
2. Ask Codex CLI a repo-investigation question such as:
   • explore this repo and tell me what it is for
   • investigate this repository and summarize the main components
   • read this codebase and explain how it is organized
3. Watch the transcript/tool activity.
4. In some runs, Codex spawns an explorer sub-agent.
5. After spawning the explorer, the parent agent still reads many of the same README/config/entrypoint files itself instead of mostly coordinating and waiting for the explorer result.
6. Compare the files read by the parent and the explorer; there is substantial overlap.

What is the expected behavior?

If Codex decides to delegate repo exploration to an explorer sub-agent, the parent agent should minimize overlapping file reads and mostly act as a coordinator unless there is a clear reason to verify something independently.

Expected behavior would be one of these:

• the parent agent does a very small initial scan, then delegates exploration and mainly synthesizes the explorer result
• or the parent agent explores directly and does not spawn an explorer for the same scope
• or the parent agent only performs targeted follow-up reads that are clearly narrower than the explorer’s scope

In short, spawning an explorer should reduce duplicated reading, not create two agents doing nearly the same investigation.

Additional information

I inspected the current repo and found prompt/rule sources that seem relevant:

• Base instruction in codex-rs/models-manager/models.json tells the main agent to build context by examining the codebase first.
• explorer role definition in codex-rs/core/src/agent/role.rs says to avoid redundant work, typically trust explorer results without additional verification, and continue working on local tasks while waiting.
• Orchestrator guidance in codex-rs/core/templates/agents/orchestrator.md says to prefer multiple sub-agents, wait for them before yielding, and coordinate rather than doing the actual work while they are working.

That combination may be producing contradictory incentives:

• “main agent should inspect the repo itself”
• “spawn explorers in parallel”
• “don’t duplicate explorer work”
• “do local tasks while waiting”

This issue may belong under sub-agent / multi-agent orchestration rather than a single-tool bug.