[Critical UX regression] multi-agent v2 spawn_agent hides model overrides and rejects the default call shape

Summary

On the multi-agent v2 surface (the default for gpt-5.6-sol / gpt-5.6-terra, and for any model when features.multi_agent_v2 is enabled), sub-agent model selection is effectively unusable: the default schema makes it undiscoverable, and the natural override call fails. The runtime fully supports the override — but agents on the default surface see no model property, conclude the capability does not exist, and tell users so. This is a severe UX regression from v1, where the spawn tool advertised up to 5 picker-visible models and fresh spawns with model overrides just worked.

Filing as an issue with a patch branch attached because PRs to this repo are staff-only.

What the user sees

User: "spawn a gpt-5.6-terra sub-agent for this" Agent: "The current spawn_agent interface has no model selection argument, so I cannot spawn a sub-agent on gpt-5.6-terra."

The agent is wrong — SpawnAgentArgs parses and applies model / reasoning_effort regardless of schema visibility — but it has no way to know that, because the schema it sees does not contain those properties. Observed repeatedly with gpt-5.6-sol under ChatGPT auth, codex-cli 0.143.0 / Codex Desktop, main @ 1f0566d3f (2026-07-10).

Root cause: two compounding defaults

1. hide_spawn_agent_metadata defaults to true (core/src/config/mod.rs). The v2 spawn_agent schema strips model, reasoning_effort, agent_type, and service_tier, and drops the v1-style "Available model overrides" description listing up to 5 picker-visible models (hide_spawn_agent_metadata_options, core/src/tools/handlers/multi_agents_spec.rs).
2. Omitted fork_turns defaults to a full-history fork, which rejects overrides (core/src/tools/handlers/multi_agents_v2/spawn.rs + reject_full_fork_spawn_overrides). So even when the model is told the arguments exist, the natural call — overrides without an explicit fork_turns — errors with Full-history forked agents inherit the parent agent type, model, and reasoning effort; .... The override only works with fork_turns: "none" or a partial fork, which nothing on the default surface teaches.

Each default is defensible alone; together they make a supported capability undiscoverable AND broken in its natural call shape. Users relying on the default surface can hit both walls before ever learning the explicit-fork workaround exists.

The config escape hatch does not work under ChatGPT auth

Setting [features.multi_agent_v2] hide_spawn_agent_metadata = false locally is not a workaround for ChatGPT-auth users: in our testing (ChatGPT auth, gpt-5.6-sol, 2026-07-10) the backend treats collaboration.spawn_agent as a reserved function and rejects every request whose declared schema deviates:

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

So for this configuration the hidden schema is the only accepted one, and the only working path is undocumented prompt knowledge. A client-side default flip therefore requires a coordinated update to the backend's reserved-function schema — which is exactly why this needs to be fixed here rather than worked around downstream.

Reproduction

1. codex with a v2-surface model (e.g. gpt-5.6-sol, ChatGPT auth, all defaults).
2. Ask: "spawn a sub-agent on gpt-5.6-terra".
3. Observe the agent either (a) claim model selection is unsupported, or (b) attempt spawn_agent {model: "gpt-5.6-terra"} without fork_turns and receive the full-history-fork rejection.
4. Optionally set hide_spawn_agent_metadata = false and observe the reserved-schema rejection above on every turn.

Proposed fix (patch branch attached)

Branch: https://github.com/lidge-jun/codex/tree/codex/spawn-agent-metadata-ux (single commit fde7de4d0; happy to iterate)

1. Default hide_spawn_agent_metadata to false — restore v1 parity: the schema advertises the override arguments and up to 5 picker-visible models. The slim schema stays available as an explicit opt-in. Note: this also surfaces the spawned agent's nickname in results (SpawnAgentResult::WithNickname), and needs the coordinated backend schema update noted above for ChatGPT-auth configurations.
2. When fork_turns is truly omitted and an override (agent_type/model/reasoning_effort) is present, treat the spawn as fresh (fork_turns: "none") instead of erroring — unstated fork intent plus explicit override intent means a fresh specialist spawn, matching v1 semantics. Explicit input keeps its meaning: fork_turns: "all" (and blank strings) still keep the full-history default and reject overrides, preserving the inherit-everything contract.

Tests: overrides-with-omitted-fork_turns fresh-spawn behavior, explicit-all agent_type-only rejection, blank-fork_turns rejection, surfaced nickname expectations. cargo test -p codex-core --lib multi_agents: 89 passed / config::: 439 passed / integration spawn_agent filter: 7 passed. Pre-existing failure unrelated to this patch: multi_agent_v2_completion_ignores_dead_direct_parent stack-overflows on a clean checkout of main @ 1f0566d3f.

Why this deserves priority

This is a capability regression with active user-facing misinformation: the agent confidently tells users a shipped capability does not exist, and the failure mode (agent denial) means most users will never learn the capability is there at all. The fix is small, v1-parity-restoring, and covered by tests — the main coordination cost is the backend schema update, which only this repo's owners can drive.