codex - 💡(How to fix) Fix Custom Subagents Limited to 3 nicknames but no Documentation

What version of the Codex App are you using (From “About Codex” dialog)?

26.506.31421 (2620)

What subscription do you have?

Enterprise API Key

What platform is your computer?

Darwin 24.6.0 arm64 arm

What issue are you seeing?

I tried creating a custom MiniMe subagent in ~/.codex/agents/MiniMe.toml, but Codex kept picking a different agent when I referenced it with [@MiniMe](subagent://MiniMe).

What finally made it work was reducing nickname_candidates from 5 entries down to 3. That suggests there may be an undocumented limit or selection quirk in how Codex resolves custom subagents.

The subagents docs show examples with 3 nickname candidates here: OpenAI Codex Subagents, but they do not explicitly say that 3 is the maximum or required number.

It would help to either document the limit clearly or make the resolver behave consistently regardless of how many nickname candidates are listed.

What steps can reproduce the bug?

Reproduction steps

1. Create a custom agent file at ~/.codex/agents/MiniMe.toml.
2. Set name = "MiniMe".
3. Add 5 entries to nickname_candidates.
4. Restart Codex so it reloads the agent definition.
5. In Codex, reference the agent with [@MiniMe](subagent://MiniMe).
6. Observe that Codex spawns a different agent type instead of the custom MiniMe agent.
7. Change nickname_candidates back to 3 entries.
8. Restart Codex again.
9. Reference [@MiniMe](subagent://MiniMe) a second time.
10. Observe that the custom MiniMe agent is now selected correctly.

What is the expected behavior?

Expected behavior

When I reference [@MiniMe](subagent://MiniMe), Codex should consistently spawn the custom agent defined in ~/.codex/agents/MiniMe.toml.

The number of nickname_candidates should not prevent the agent from being selected, unless the docs explicitly say there is a limit.

Additional information

No response