Custom agents cannot be selected because spawn_agent exposes only task_name

What version of Codex are you using?

• Codex App: 26.707.72221 (build 5307, bundle com.openai.codex)
• Codex CLI: 0.144.4

What subscription do you have?

ChatGPT-authenticated local Codex session.

What platform is your computer?

macOS 26.5.2 (25F84), arm64

What issue are you seeing?

Configured custom agents cannot be selected by their exact name because the model-visible spawn_agent interface exposes only a task/thread label (task_name) and a prompt, not a registered custom-agent selector such as agent_name, agent_type, or role.

A valid custom agent exists under ~/.codex/agents/ with the required fields documented at https://developers.openai.com/codex/multi-agent:

name = "luna_file_scout"
description = "Read-only targeted discovery."
model = "gpt-5.6-luna"
model_reasoning_effort = "low"
sandbox_mode = "read-only"
developer_instructions = "Perform only bounded read-only discovery."

The documentation says that the name field is the source of truth and that Codex identifies and spawns the custom agent by that name. However, the available runtime tool schema does not provide a field that can carry that name. Passing the value as task_name would only label the task and would not prove that the TOML configuration was applied.

This also prevents selecting built-in agent types such as explorer through the same interface, so the problem appears to be the exposed spawn contract rather than the custom TOML file itself.

What steps can reproduce the bug?

1. Create ~/.codex/agents/luna_file_scout.toml using the valid schema shown above.
2. Confirm multi_agent is enabled. Leave multi_agent_v2 and use_agent_identity disabled.
3. Restart Codex and start a new session.
4. Ask Codex to use the configured custom agent by exact name:

Use the configured custom agent whose exact name is luna_file_scout. Delegate a small read-only lookup. Do not substitute a generic or built-in agent.

1. Inspect the model-visible spawn interface and subagent activity.
2. As a control, ask Codex to use the built-in explorer agent for the same read-only lookup.

A/B result

Case A: configured custom agent

• Requested agent: luna_file_scout
• Result: not dispatched
• Evidence: the runtime schema exposed no configured-agent selector; task_name was correctly rejected as proof of custom-agent selection
• Fallback agent: none

Case B: built-in control

• Requested agent: explorer
• Result: not dispatched
• Evidence: the runtime again exposed only task_name, with no built-in agent-type selector
• Fallback agent: none

What is the expected behavior?

The spawn interface should expose a registered agent selector whose accepted values include built-in and loaded custom-agent names. When luna_file_scout is selected, the activity metadata should identify the underlying configured agent type as luna_file_scout, and the child should receive its configured model, reasoning effort, instructions, and sandbox settings subject to documented parent runtime overrides.

What is the actual behavior?

Only a task/thread label and prompt are available. The runtime cannot select or verify either luna_file_scout or the built-in explorer agent, so compliant orchestration must refuse to dispatch rather than silently substitute a generic agent.

Feature state

• multi_agent: stable, enabled
• multi_agent_v2: under development, disabled
• use_agent_identity: under development, disabled

No under-development feature was enabled for this reproduction.

Additional information

Restarting the App and creating a fresh session did not change the exposed spawn interface. The custom-agent TOML is present at the documented location and contains the documented required fields.