›_ Codex Issues
Codex Issues / #33244

Custom agents cannot be selected because spawn_agent exposes only task_name

Open 💬 3 comments Opened Jul 15, 2026 by mochafreddo
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

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.

View original on GitHub ↗

3 Comments

github-actions[bot] contributor · 1 month ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #33092
  • #32782
  • #32703
  • #32291

Powered by Codex Action

Loong0x00 · 1 month ago

Confirmed on Linux x86_64 with codex-cli 0.144.6 (ChatGPT auth). At the time of testing, both npm and GitHub Releases report 0.144.6 as the latest stable version.

This still reproduces in both interactive TUI and codex exec, and it is not limited to project config discovery:

  • tested project-local .codex/config.toml + .codex/agents/implementer.toml;
  • tested the same registration globally in ~/.codex/config.toml + ~/.codex/agents/implementer.toml;
  • codex --strict-config --version succeeds;
  • restarted into fresh sessions for each test;
  • the model-visible collaboration.spawn_agent schema still exposes only task_name, message, and fork_turns.

The registered profile intentionally had distinctive values:

name = "implementer"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
nickname_candidates = ["Forge", "Kepler", "Turing"]
developer_instructions = "Implement only the assigned task ..."

I forced an exact call with task_name = "implementer" and fork_turns = "none". The child completed successfully, but persisted rollout metadata showed:

agent_path     = /root/implementer
agent_role     = null
agent_nickname = Dirac
model          = gpt-5.6-sol
effort         = max

The distinctive developer-instruction text was also absent from the child rollout. In other words, task_name only named the thread; it did not resolve the configured profile. The child silently inherited the parent configuration instead of using Terra/high.

This silent fallback is especially frustrating because the spawn and delegated task both report success. Without inspecting rollout internals, the user is led to believe the requested role, model, instructions, and safety policy were applied when they were not.

The spawn contract needs separate structured inputs, for example:

{
  "agent_type": "implementer",
  "task_name": "implement_slice_p0",
  "message": "...",
  "fork_turns": "none",
  "model": "gpt-5.6-terra",
  "reasoning_effort": "high"
}

agent_type/role should resolve the complete registered profile; task_name should remain only the task/thread label. An unknown or unavailable role should fail explicitly instead of spawning a generic child with agent_role = null.

This also overlaps #33881. #31814 was closed after a maintainer said model/effort controls and role capabilities would return in the next release, but the latest stable 0.144.6 still has the restricted schema and the same silent inheritance. If the fix is currently alpha-only, please document the target stable version and keep a stable-release tracking issue open until the exact model-visible spawn contract is verified end to end.

geoff-ux · 9 days ago

We have a production headless-certification use case that is blocked on this exact boundary.

A fresh, read-only Linux sandbox contains a trusted repository checkout and a project-scoped custom agent at .codex/agents/flowos_qa.toml. The host needs to invoke that registered agent by exact identity from codex exec, provide a four-field exact-revision handoff, and receive a structured terminal verdict. Silent substitution with a generic child is unacceptable because the custom agent owns the non-authoring permissions, model/reasoning route, and certification instructions.

Observed with codex-cli 0.146.0, stable multi_agent enabled:

  • the project agent definition was present and loadable;
  • an ephemeral codex exec prompt explicitly requested the registered flowos_qa agent;
  • no verified custom-agent dispatch occurred;
  • the run correctly stopped with: Not dispatched. Admission verdict unavailable.

The first-class shape could be either an explicit headless selector such as codex exec --agent flowos_qa, or a structured agent_type/role field that resolves the registered profile. For unattended certification we also need:

  1. unknown or unavailable roles to fail non-zero rather than fall back;
  2. the resolved agent identity and effective config to be observable in structured output/session metadata;
  3. the registered model, reasoning effort, sandbox, and developer instructions to apply exactly;
  4. headless execution to retain normal cancellation and terminal-result behavior.

This currently prevents us from using Codex as an independent repository-owned certifier in a cloud agent loop. We are using a separate cross-vendor certifier temporarily rather than parsing the TOML or copying the agent instructions. Happy to provide a smaller sanitized reproduction if useful.