GPT-5.6 forces a restricted spawn_agent schema that makes documented custom agents unusable #31893

Codex version

0.144.0

Models

• GPT-5.5: custom subagents are selectable
• GPT-5.6 Sol/Terra: custom subagents are not selectable

Problem

Selecting GPT-5.6 causes Codex to expose this collaboration.spawn_agent schema:

spawn_agent({
  task_name: string,
  message: string,
  fork_turns?: string
})

It contains no agent_type, model, or reasoning_effort.

Consequently, there is no way to select agents configured under ~/.codex/agents/*.toml. Giving the task the same task_name as a custom agent only names the spawned thread; it does not apply that agent's config.

With GPT-5.5, the exposed V1 tool includes agent_type, model, and reasoning_effort, so custom agents can be selected.

Reproduction

1. Define a custom agent in ~/.codex/agents/example.toml with distinctive instructions, model, and reasoning effort.
2. Start Codex using GPT-5.5.
3. Inspect or use spawn_agent; agent_type is available.
4. Start Codex using GPT-5.6.
5. Inspect spawn_agent; only task_name, message, and fork_turns are available.
6. Spawn task_name: "example".
7. Observe that it is a generic inherited agent, not the configured agent.

Attempted workaround

Setting:

[features.multi_agent_v2]
hide_spawn_agent_metadata = false

causes the request to fail:

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

Therefore the omitted fields cannot be restored locally.

Expected behavior

GPT-5.6 should preserve the documented ability to select custom agents.

Possible fixes include:

• Expose agent_type in the reserved GPT-5.6 V2 schema.
• Resolve configured custom-agent names through another supported field.
• Use V1 when custom agents are configured.

model and reasoning_effort could remain hidden if the runtime applies them from the selected agent config. The essential missing capability is selecting the configured role.

Impact

This silently bypasses custom-agent instructions, model selection, and reasoning effort. Generic spawning still succeeds, so users may believe their configured agents are running when they are not.

Related

• Custom-agent documentation: https://learn.chatgpt.com/docs/agent-configuration/subagents?surface=app#custom-agents
• General custom-agent/tool mismatch: Custom subagents in .codex/agents are not accessible from tool-backed Codex sessions as docs imply #15250
• V2 override/fork interaction: MultiAgentV2 spawn_agent defaults to full-history fork, rejecting agent_type/model overrides #20077
• Earlier hidden-metadata regression: Custom .codex/agents no longer selectable in CLI v0.137.0; subagents spawn generic and inherit parent model #26363
• Reserved V2 schema failures: MultiAgentV2 encrypted spawn_agent schema returns 400: model not configured for encrypted tool use #26753

Relevant source changes:

• 668703c23f8a6cde07c317f687d9b95606293752 changed V2 spawn metadata to hidden by default.
• 66232220e21712604b0066f496e966c9a2c1bda8 restored configured-agent selection for V1 but intentionally retained the restricted V2 behavior.