MultiAgentV2: reserved spawn_agent schema blocks per-child model and reasoning-effort overrides

Open 💬 5 comments Opened Jul 13, 2026 by kckylechen1

💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

Summary

MultiAgentV2 currently cannot expose per-child model or reasoning_effort overrides to users of the native collaboration.spawn_agent tool.

The client implementation supports the fields, but exposing them changes the schema of a server-reserved tool. The backend rejects that request before any model or child-agent work begins.

This is separate from lifecycle/Wait rendering issues: it is a tool-schema compatibility gap that prevents heterogeneous subagent routing.

Environment

Codex CLI 0.144.1
macOS (Apple Silicon)
ChatGPT-authenticated native collaboration tools

Minimal reproduction

The normal configuration keeps the schema hidden:

[features.multi_agent_v2]
hide_spawn_agent_metadata = true

An ephemeral, no-tool request succeeds under that baseline:

codex exec --ephemeral --json --skip-git-repo-check --ignore-rules -C /tmp \
  'Reply with exactly SCHEMA_PROBE_OK. Do not call any tools.'

Output includes:

SCHEMA_PROBE_OK

The same harmless request, with only the V2 schema-exposure override, fails before the model can invoke a tool:

codex exec --ephemeral --json --skip-git-repo-check --ignore-rules -C /tmp \
  -c 'features.multi_agent_v2.hide_spawn_agent_metadata=false' \
  'Reply with exactly SCHEMA_PROBE_OK. Do not call any tools.'

Actual result:

Invalid Value: 'tools'. Function 'collaboration.spawn_agent' is reserved for use by this model and must match the configured schema.

Why this is surprising

The V2 client schema and spawn handler already define and apply optional model and reasoning_effort. However, the default hidden-metadata mode removes them to retain compatibility with the server-reserved schema. Users therefore cannot select a different model or effort for an individual native subagent, even though the underlying child configuration supports it.

Expected behavior

The server-reserved collaboration.spawn_agent schema should accept optional model and reasoning_effort fields and forward them to V2 child configuration. Omitting them should continue to inherit the parent settings.

This would permit model/effort routing for bounded subagent tasks without asking clients to send a schema that the server rejects.

View original on GitHub ↗

5 Comments

github-actions[bot] contributor · 1 month ago

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

#32031
#32430
#31814
#31893
#32587

Powered by Codex Action

jiangxiaoxu · 1 month ago

try
[features.multi_agent_v2]
hide_spawn_agent_metadata = false
tool_namespace = "agents"

kckylechen1 · 1 month ago

@jiangxiaoxu thank you — I tested this on codex-cli 0.144.3 with an app-server lifecycle probe.

Changing the namespace to agents does bypass the reserved collaboration.spawn_agent schema 400, and a real V2 child thread was created and completed. However, it did not restore per-child routing in the observed run. The parent was explicitly instructed to spawn with model="gpt-5.6-luna" and reasoning_effort="low", but the persisted parent function_call contained model: null and reasoning_effort: null. The child thread's own turn_context then showed model="gpt-5.6-sol", effort="high", matching the parent.

So this is a useful partial workaround for the 400, but not yet a fix for the issue's model/reasoning override contract. Leaving the issue open; the next verification boundary is a spawn call that preserves those arguments and a child turn_context that proves they were applied.

jiangxiaoxu · 1 month ago

@kckylechen1 I think the default value for fork_turns may be all. You could try explicitly instructing it to use none or an integer from 1 to N; the subagent should then be spawned correctly.
Using all means subagents can only be spawned with the same model and reasoning effort as the parent agent, which seems highly unreasonable.

jiangxiaoxu · 1 month ago

Here is my configuration:
Using this multi_agent_mode_hint_text allows /root to spawn subagents while preventing those subagents from spawning additional subagents. This works in most cases, although I occasionally still see a subagent spawn another subagent—but it happens very rarely.

[features.multi_agent_v2]
hide_spawn_agent_metadata = false
tool_namespace = "agents"
max_concurrent_threads_per_session = 16
default_wait_timeout_ms = 300_000
multi_agent_mode_hint_text = "Proactive multi-agent delegation is active for /root. For /root, any earlier instruction requiring an explicit user request before spawning sub-agents no longer applies; /root should use sub-agents when parallel work would materially improve speed or quality. A sub-agent must not spawn additional sub-agents unless explicitly authorized to do so by /root, by a user instruction applying to that sub-agent, or by a separate developer instruction. This message authorizes proactive delegation only for /root and is not itself authorization for sub-agents to delegate. This mode remains active until superseded by a later multi-agent mode developer message."