codex - 💡(How to fix) Fix MultiAgentV2 spawn_agent defaults to full-history fork, rejecting agent_type/model overrides [3 comments, 3 participants]

What variant of Codex are you using?

Codex Desktop with MultiAgentV2 enabled.

What happened?

With MultiAgentV2 enabled, spawn_agent defaults to a full-history fork when fork_turns is omitted. Full-history forks reject agent_type, model, and reasoning_effort overrides.

That makes the natural/default call shape for a specialized subagent fail:

{
  "agent_type": "domain_expert",
  "task_name": "domain_expert_default_fork_probe",
  "message": "Probe task: reply with exactly one sentence saying whether you started successfully."
}

Observed error:

Full-history forked agents inherit the parent agent type, model, and reasoning effort; omit agent_type, model, and reasoning_effort, or spawn without a full-history fork.

The same failure occurs for built-in roles such as explorer and worker when fork_turns is omitted. This is not specific to domain_expert; it is the MultiAgentV2 default fork behavior interacting with role/model/reasoning overrides.

Expected behavior

One of these should be true:

1. spawn_agent(agent_type=...) should default to a fork mode compatible with role/model/reasoning overrides.
2. The tool schema/docs should explicitly state that agent_type, model, or reasoning_effort require fork_turns: "none" or another non-full-history mode.
3. MultiAgentV2 should support full-history context plus a different child role/model/reasoning configuration, since "same context, specialized child" is a common multi-agent workflow.

Actual behavior

fork_turns is optional, but omission means "all", which maps to SpawnAgentForkMode::FullHistory. In that mode, MultiAgentV2 rejects overrides.

Current implementation appears to do this in codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs:

• fork_turns.unwrap_or("all")
• "all" maps to SpawnAgentForkMode::FullHistory
• full-history mode calls reject_full_fork_spawn_overrides(role_name, model, reasoning_effort)

So a model following the visible spawn_agent schema can easily produce a rejected tool call by combining the default fork mode with an explicit agent_type.

Reproduction steps

1. Start a Codex Desktop/CLI session with MultiAgentV2 enabled.
2. Ask Codex to spawn a specialized subagent, or directly call:

{
  "agent_type": "explorer",
  "task_name": "explorer_default_fork_probe",
  "message": "Reply with exactly: STARTED"
}

1. Observe the full-history fork rejection.
2. Retry with:

{
  "agent_type": "explorer",
  "task_name": "explorer_no_fork_probe",
  "message": "Reply with exactly: STARTED",
  "fork_turns": "none"
}

1. Observe that the specialized role can spawn.

Why this seems like a bug / DX issue

The official subagents docs describe specialized/custom agents with different model configurations and instructions. The tool schema also exposes agent_type, model, and reasoning_effort as ordinary spawn_agent arguments.

But with MultiAgentV2 enabled, the default fork_turns value makes those ordinary-looking arguments fail unless the caller knows to add fork_turns: "none".

This creates a sharp edge for users and orchestrating agents:

• specialized subagent requests fail by default
• the workaround is not discoverable until after a rejected tool call
• users expecting "spawn a domain expert / explorer / worker" get a spawn failure instead of a specialized child

Suggested fix

Best option:

• If agent_type, model, or reasoning_effort is present and fork_turns is omitted, default to a compatible fork mode instead of full-history.

Alternative:

• Keep the current behavior, but update the tool schema/docs to explicitly state that role/model/reasoning overrides require fork_turns: "none" or another non-full-history mode.

Longer-term option:

• Support full-history context with a different child role/model/reasoning configuration, since "same context, specialized child" is a common MultiAgentV2 workflow.

Related issue

Possibly related, but broader and Windows/named-agent focused:

• https://github.com/openai/codex/issues/19399