Change Codex system instruction about unexpected worktree changes for better support of concurrent agent edits

What version of Codex is running?

codex-cli 0.117.0

Which model were you using?

gpt-5.4 with xhigh reasoning

What platform is your computer?

Linux

What issue are you seeing?

Codex has a built-in system/developer instruction about unexpected worktree changes that is too broad for repos where multiple agents intentionally work concurrently on the same integration branch.

The exact injected instruction is:

"While you are working, you might notice unexpected changes that you didn't make. If this happens, STOP IMMEDIATELY and ask the user how they would like to proceed."

In practice, this causes the agent to notice an unrelated file changed by another agent, treat it as a blocker, and stop to ask the user how to proceed.

That is the wrong behavior for a shared integration branch. In this workflow, other agent changes are expected, and agents are explicitly instructed to treat concurrent work on the branch as normal branch state. When committing, the working rule is to treat those changes as your own branch state and commit appropriately, not to treat them as suspicious by default.

The correct behavior is to continue unless there is a real semantic conflict in the same code path being edited.

This creates unnecessary interruptions and slows down multi-agent execution.

What steps can reproduce the bug?

1. Use Codex in a repo where multiple agents are expected to commit to the same branch.
2. Have another agent or process modify a different file in the worktree.
3. Ask Codex to continue implementation work in another area.
4. Observe that it may stop and ask what to do about “unexpected changes” even when there is no direct conflict.

What is the expected behavior?

Codex should continue automatically when unrelated worktree changes appear in a concurrent-agent repo.

A better default would be:

• continue for unrelated or non-conflicting changes
• only stop if there is a direct semantic conflict in the files or code path currently being modified

What do you see instead?

The agent can over-trigger on the injected rule above and ask the user how to proceed, even when the concurrent change is normal and non-conflicting.

Additional information

I verified that a persisted local Codex instruction cache includes similar guidance in the base instructions:

• ~/.codex/models_cache.json

In my environment, I implement the opposite local rule for concurrent-agent repos:

• do not stop for unrelated worktree changes
• assume they are another agent’s work
• treat the shared branch state as normal
• when committing, treat those changes as your own branch state and commit appropriately
• only escalate when there is a direct conflict

The injected system/developer message still interferes with that intended workflow, because the agent can over-apply the built-in “unexpected changes” guidance.

So the issue is not that Codex lacks a rule here. The issue is that the system/developer instruction is too broad for concurrent-agent integration branches and interferes with repo-local workflow rules.

A useful fix would be one of:

1. narrow the default instruction text
2. make repo-level / local rules override this behavior more reliably
3. detect multi-agent integration-branch workflows and default to “continue unless directly conflicting”