Ambiguous thread tooling causes subthread requests to create visible Codex threads instead of subagents

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

Unknown from this agent session. The issue was observed in Codex Desktop on 2026-06-11.

What subscription do you have?

Unknown from this agent session.

What platform is your computer?

Darwin 24.6.0 arm64 arm

What issue are you seeing?

When a user asks Codex to create or use “subthreads” / “子线程”, or asks to “dispatch agents” for parallel work, Codex may choose the visible Codex thread tools (codex_app.create_thread or codex_app.fork_thread) instead of the lightweight multi-agent/subagent tool (multi_agent_v1.spawn_agent).

This creates visible conversation threads rather than isolated subagents. In workflow-heavy projects, that distinction matters: visible Codex threads can be mistaken for the intended subagent work units, can be left around for the user to archive, and can operate with different workspace assumptions than the requested subagent/worktree process.

We observed this repeatedly over a multi-day workflow. The user specifically asked for “子线程” to review workspaces / dispatch agents, but visible Codex conversation threads were created instead. After investigation, the likely cause is tool-description ambiguity:

• The Codex Desktop thread coordination instructions say to use create_thread, fork_thread, list_threads, etc. when the user asks to create/fork/manage Codex threads.
• The multi-agent tool (multi_agent_v1.spawn_agent) is the correct tool for lightweight subagents / dispatched parallel agents.
• In Chinese usage, “子线程” maps naturally to “subthread”, but the intended operational meaning in this context was “subagent”, not a new visible Codex conversation thread.

Related existing issues were searched before filing. I found related-but-not-duplicate reports, including #16996 about subagent spawn policy conflicts and #16914 about thread/subagent switching behavior, but neither appears to report this specific semantic/tool-selection ambiguity.

What steps can reproduce the bug?

1. In Codex Desktop, work in a repository with multiple worktrees or multiple independent review tasks.
2. Ask Codex in Chinese to create “子线程” or “分派 agent” to review/process each workspace, for example:

• “请你新建子线程，审理各工作区的代码变更情况。”
• “请你分派给各项目的 agent 进行接收处理。”

1. Observe whether Codex uses codex_app.create_thread / codex_app.fork_thread, creating visible Codex conversation threads, instead of multi_agent_v1.spawn_agent.
2. The user then has to archive those visible threads and restate that “子线程” should mean subagents for the project workflow.

This is easiest to reproduce in non-English workflows where “子线程” is used as the natural term for a subordinate execution thread/agent rather than a UI conversation thread.

What is the expected behavior?

The tool descriptions and/or system guidance should clearly disambiguate visible Codex conversation threads from lightweight subagents.

Suggested behavior:

• codex_app.create_thread and codex_app.fork_thread should be described as creating visible Codex conversation threads / UI threads.
• multi_agent_v1.spawn_agent should be described as the preferred tool for “subagent”, “subthread”, “子线程”, “分派 agent”, “parallel review agent”, and similar task-dispatch wording.
• If the user says “子线程” or “subthread” without explicitly requesting a visible conversation thread, Codex should prefer spawn_agent or ask a clarifying question.
• Visible thread tools should be used only when the user explicitly asks for a new/forked/archived/renamed Codex conversation thread.

Additional information

This caused practical workflow problems: visible conversation threads were created and later had to be archived, while the requested workflow expected isolated subagents working in clean worktrees. The resulting confusion also made it harder to enforce repository worktree hygiene and track which execution unit handled which issue.