[CLI] GPT-5.5 forces MultiAgentV2 despite disable and hides documented custom-agent controls

GPT-5.5 no longer has a defined multi_agent_version, so this is likely out of date.

But, GPT-5.6-Sol does, so the broader point is still true.

You can do this to stay on v1:

# ~/.codex/config.toml
model_catalog_json = "~/.codex/models-v1.json"

[features]
multi_agent = true
multi_agent_v2 = false

Then create ~/.codex/models-v1.json from the current model catalog and change only these fields:

"slug": "gpt-5.6-sol",
"multi_agent_version": "v1"

and optionally:

"slug": "gpt-5.6-terra",
"multi_agent_version": "v1"

You can also optionally instead set version as "null" for all three Sol, Terra, and Luna, so that multi-agent schema version is defined by features config, not model catalog, but that's up to you.

Additional deterministic reproduction from Codex CLI/TUI 0.144.1. This appears to narrow the model-switch behavior to the first submitted turn, rather than session creation, dropdown selection alone, or MCP initialization.

Environment

• Codex package: 26.623.19656.0 x64
• CLI/TUI: codex-cli 0.144.1, originator codex-tui
• OS: Windows 11 Home x64, build 26200
• Provider: openai
• Launch: codex --yolo (approval_policy=never, sandbox=danger-full-access in rollouts)
• Default config: model = gpt-5.6-sol, model_reasoning_effort = high
• No explicit multi-agent override in config.toml
• codex features list: multi_agent=true, multi_agent_v2=false
• Current catalog: Sol=v2, Terra=v2, Luna=v1, GPT-5.5 has no multi_agent_version

Personal TOML roles used as controls:

• cheap_explorer: gpt-5.6-terra, medium, read-only
• ticket_worker: gpt-5.6-sol, high, workspace-write

Session 1: first submitted turn on GPT-5.5

Session 019f4a75-8d31-7620-8be5-fae49ac41a39:

1. Launch codex --yolo, initially showing the default GPT-5.6-Sol.
2. Switch to GPT-5.5 before submitting a prompt.
3. First recorded turn_context: model=gpt-5.5, multi_agent_version=v1.
4. Custom agents are visible. cheap_explorer is dispatched through multi_agent_v1.spawn_agent(agent_type=cheap_explorer).
5. Child 019f4a77-1e18-7a90-a8a8-677e83512996 records agent_role=cheap_explorer, model=gpt-5.6-terra, effort=medium, matching its TOML.
6. Switch the parent to GPT-5.6-Sol. Subsequent parent turns record model=gpt-5.6-sol, but remain multi_agent_version=v1.
7. Custom agents remain visible. ticket_worker is dispatched through multi_agent_v1.spawn_agent(agent_type=ticket_worker).
8. Child 019f4a7b-0dda-7a90-bcf4-f86f938992e9 records agent_role=ticket_worker, model=gpt-5.6-sol, effort=high, also matching its TOML.

Session 2: no submitted turn while GPT-5.5 is selected

Session 019f4a7b-c48d-7e00-b0bd-32ccb4899ca2:

1. Launch on GPT-5.6-Sol.
2. Switch to GPT-5.5, then switch back to Sol without submitting a turn on GPT-5.5.
3. The dropdown-only changes produce no rollout turn/settings events.
4. First submitted turn records model=gpt-5.6-sol, multi_agent_version=v2, multi_agent_mode=explicitRequestOnly.
5. Custom agents are not exposed.

Session 3: commit one ordinary GPT-5.5 turn first

Session 019f4a7c-bc64-7163-aff8-62546ade4e0a:

1. Launch on GPT-5.6-Sol and switch to GPT-5.5.
2. Submit hi and receive the reply.
3. First recorded turn is model=gpt-5.5, multi_agent_version=v1.
4. There was no tool call or MCP event during this turn; it was an ordinary model response.
5. Switch to GPT-5.6-Sol.
6. Subsequent turns record Sol but remain multi_agent_version=v1.
7. cheap_explorer successfully dispatches through multi_agent_v1.spawn_agent; child 019f4a7e-7a95-7883-9f38-1932ad75be6e again records Terra/medium and the correct custom role.

Inference from the three controls

The reproducible rule appears to be:

first actual turn on GPT-5.5 -> thread selects/pins V1 -> custom TOML roles survive later switch to Sol
first actual turn on GPT-5.6-Sol -> thread selects/pins V2 -> custom role selector is hidden

So the apparently relevant hi is not initializing MCP. It commits the first GPT-5.5 turn and causes the thread to select V1. Model dropdown changes before any submitted turn do not appear to initialize or change the multi-agent version.

This also gives a stronger control for the custom-agent portion of this issue and the tool-backed mismatch in #15250: TOML discovery, role resolution, and role-specific child model configuration all work when the thread selects V1. The missing capability is specific to the Sol-selected V2 tool surface.

I can provide sanitized rollout excerpts if useful.

I can reproduce this on macOS arm64 with Codex CLI 0.144.1, and the impact also includes agent-scoped MCP configuration.

Environment

• Codex CLI: codex-cli 0.144.1
• Platform: Darwin 25.5.0 arm64
• Model: gpt-5.6-sol
• codex features list reports:
• multi_agent = true
• multi_agent_v2 = false

Reproduction

I have two valid personal custom agents under ~/.codex/agents/:

1. A documentation agent with a stdio Context7 MCP server.
2. An issue-tracking agent with an HTTP MCP server.

Sensitive command arguments, URLs, headers, and credentials are omitted.

Both custom agent TOML files parse successfully and declare name,
description, developer_instructions, and agent-specific mcp_servers.

The Context7 MCP server itself was tested independently using only
initialize and tools/list:

INIT_OK True
TOOLS_LIST_OK True
TOOL_NAMES ['query-docs', 'resolve-library-id']

However, when Codex delegates through the V2 subagent tool surface:

spawn_agent(task_name, message, fork_turns)

the resulting child is generic:

multi_agent_version = "v2"
agent_role = null

The child tool registry contains no Context7 MCP tools. The same behavior occurs
with the HTTP-backed custom agent: its agent-specific MCP tools are absent and
no request reaches that MCP server.

Using the custom agent name as task_name only changes the task path; it does
not resolve or apply the custom agent TOML.

Expected behavior

The current Subagents documentation says custom agent TOML files are loaded as
configuration layers for spawned sessions and may contain mcp_servers.

Selecting a custom agent should therefore apply:

• developer_instructions
• sandbox/model settings
• agent-specific mcp_servers
• non-null agent role metadata

Actual behavior

The V2 tool surface provides no custom-agent selector. The spawned child records
agent_role = null, inherits generic parent behavior, and does not load the
agent-specific MCP configuration.

This confirms the issue on macOS arm64 and shows that the regression affects
agent-specific tool isolation in addition to model/reasoning configuration.

Seems to be fixed for 5.5, but now Terra and Sol showing the same issue using v2, while Luna is using the v1.

Correction / scope update to my earlier diagnostic comment:

I have now run six fresh control experiments on a second machine with:

• Ubuntu 24.04
• codex-cli 0.144.1
• fresh sessions started directly on a GPT-5.6 model
• no initial GPT-5.5 turn or model-switch priming

In all six runs, the custom TOML subagents were exposed immediately and could be selected from the GPT-5.6 parent. The GPT-5.5-first workaround was not needed.

This was not simply a generally unaffected Codex installation: the same machine also reproduced the separate interactive-subagent problem.

Therefore my earlier inference — that the first submitted GPT-5.5 turn deterministically selects V1 and is required for custom-agent exposure before switching to GPT-5.6 — is not universal across Codex CLI 0.144.1 environments. The Windows reproduction and rollout evidence remain accurate for that machine, but they should not be generalized to the CLI as a whole.

At minimum, the behavior appears sensitive to another variable such as the delivered model catalog/runtime configuration, account rollout, tool-surface negotiation, or platform integration. On this Ubuntu CLI setup, direct GPT-5.6 entry did not reproduce the hidden-custom-agent bug across six attempts.

I do not yet have a V1/V2 turn_context comparison from the Ubuntu runs, so I cannot say which of those variables differs. The important correction is that GPT-5.5 priming is not inherently required in current Codex CLI 0.144.1.

Additional matched-model reproduction on Codex CLI 0.144.1. This rules out a simple parent/child model mismatch for the encrypted V2 handoff failure.

Environment

• Linux 6.18.33.2-microsoft-standard-WSL2 x86_64
• Provider: openai
• multi_agent=true
• multi_agent_v2=true
• V2 namespace explicitly set to agents
• Spawn metadata exposed
• Fresh non-resumed parent launched directly as gpt-5.6-sol, high

Matched control

Parent rollout metadata:

• model: gpt-5.6-sol
• reasoning effort: high
• provider: openai
• multi_agent_version=v2
• thread: 019f5d2a-8d53-7cf3-b843-5fd1b9d84c7d

Exactly one named child was dispatched:

• agent_type=k_reviewer
• fork_turns=none
• no direct model, reasoning, provider, or service-tier overrides
• child role metadata: k_reviewer
• child model: gpt-5.6-sol
• child reasoning effort: high
• child provider: openai
• child thread: 019f5d2b-80e8-7b51-8778-7d71a370b659

The child still terminated with:

stream disconnected before completion: Encrypted function output content could not be decrypted or decoded.

No child JSON or assistant response arrived, no retry was attempted, and the repository status was identical before and after.

Rollout clues

The child rollout contains the canonical task handoff as an encrypted_content item, then token-count events, but no assistant output before terminal completion. During that child turn, rate-limit metadata changes from the generic codex limit to:

limit_id=codex_bengalfox
limit_name=GPT-5.3-Codex-Spark

even though both parent and child turn_context records remain gpt-5.6-sol high. I do not know whether this represents a backend fallback, accounting-only metadata, or another routing layer, but it may be relevant to the encrypted-content failure. This resembles the model/provider transition mechanism discussed in #17541, while still reproducing with matched visible parent/child model metadata.

A separate configuration inconsistency was also visible: the named k_reviewer profile declares a read-only sandbox, but the child turn_context records danger-full-access, inherited from the parent. The role, model, reasoning effort, and developer instructions were applied; the sandbox setting was not.

The same encrypted transport error had already reproduced from a fresh Terra parent with the same named Sol reviewer. The Sol/Sol control above shows that merely matching the configured parent and child model is not a workaround.

Correction/escalation to my July 12 update: I now have rollout-level evidence that this is a more severe regression than simple model- or prompt-dependent behavior.

On a fresh Ubuntu 24.04.4 host, I invoked the exact retained Codex 0.144.1 executable by absolute path:

/home/antoine/.codex/packages/standalone/releases/0.144.1-x86_64-unknown-linux-musl/bin/codex

The resulting session metadata confirms cli_version: 0.144.1, so this is not contamination from the currently installed 0.144.4 CLI.

codex features list under that executable reports:

• multi_agent: stable, true
• multi_agent_mode: removed, false
• multi_agent_v2: under development, false

There are no multi_agent or hide_spawn_agent_metadata overrides in the user config, environment, or systemd user-manager environment.

Nevertheless, a fresh codex exec --json --yolo session recorded:

• model: gpt-5.6-sol
• multi_agent_version: "v2"
• multi_agent_mode: "explicitRequestOnly"

More importantly, the collaboration spawn_agent schema exposed to the model did not contain agent_type. The resulting call could only specify:

{
  "fork_turns": "none",
  "task_name": "outer_recon",
  "message": "..."
}

The requested custom role exists in ~/.codex/agents/outer_recon.toml and specifies:

• model: gpt-5.6-terra
• reasoning effort: high
• read-only sandbox
• custom developer instructions

But the spawned child recorded:

{
  "agent_role": null,
  "agent_path": "/root/outer_recon"
}

It ran on gpt-5.6-sol at xhigh, received none of the custom role’s developer instructions, and returned NO_CUSTOM_ROLE_INSTRUCTIONS.

This distinction matters: task_name: "outer_recon" creates a path that looks like a named agent, so a behavioral probe can produce a false positive. The reliable indicators are agent_role, the selected model/effort, and receipt of the role-specific developer instructions. All of those failed here.

I also launched a separate fresh session with:

codex exec --disable multi_agent_v2 ...

That session still recorded:

• multi_agent_version: "v2"
• multi_agent_mode: "explicitRequestOnly"

So the documented/local feature state and the explicit CLI disable are both being overridden by the effective per-thread runtime.

This is no longer plausibly a “the model chose the default spawn path” prompt issue. The tool schema itself omits agent_type; no prompt can select a custom role through a field that the runtime has removed.

For the affected rollout, documented custom subagents are therefore not merely degraded—they are unreachable. The only available operation creates generic task children, while silently ignoring the custom role’s model, effort, sandbox, and instructions.

Could the Codex team please:

1. Treat this as a current GPT-5.6/runtime regression rather than a stale GPT-5.5 report.
2. Identify which server/runtime layer is forcing V2 and hiding agent_type despite both configured and explicit CLI state.
3. Restore custom-role selection or make --disable multi_agent_v2 actually restore the legacy custom-agent surface.
4. Add a regression test verifying that a TOML custom role launched from codex exec receives its configured role, model, effort, sandbox, and developer instructions.
5. Make codex features list report the effective negotiated behavior, or otherwise clearly disclose when server-side state overrides it.

I can provide sanitized rollout excerpts if useful.

I reproduced this regression on Codex CLI 0.144.5 on Windows and found a working local model-catalog override.

Environment

• Codex CLI: 0.144.5
• OS: Windows
• Models tested: gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, and gpt-5.3-codex-spark

Observed behavior

codex features list reported:

multi_agent       stable             true
multi_agent_v2    under development  false

However, before applying any local catalog override, codex debug models reported:

gpt-5.6-sol    multi_agent_version: v2
gpt-5.6-terra  multi_agent_version: v2
gpt-5.6-luna   multi_agent_version: v1

Fresh Sol/Terra sessions exposed the V2 spawn schema:

• task_name
• message
• fork_turns

The callable schema did not expose agent_type, model, or reasoning_effort. Consequently, configured custom agents and their pinned model, reasoning effort, sandbox, and developer instructions could not be selected through the spawn call.

As an A/B test, I started a fresh gpt-5.3-codex-spark xhigh session. It used the V1 behavior and displayed a spawned agent as:

Spawned Aristotle [worker] (gpt-5.3-codex-spark xhigh)

This indicates that the effective multi-agent tool surface is selected from model/runtime metadata and is pinned when the thread is created. Switching the model inside an existing V2 thread was not sufficient to recover the V1 schema.

Working workaround

I generated a snapshot of the current model catalog and changed only these entries:

gpt-5.6-sol    multi_agent_version: v1
gpt-5.6-terra  multi_agent_version: v1

I then configured Codex to load that local catalog:

model_catalog_json = 'C:\Users\<username>\.codex\models-v1.json'

[features]
multi_agent = true
multi_agent_v2 = false

After fully restarting Codex and creating a fresh session, codex debug models reported V1 for Sol, Terra, and Luna, and the V1 subagent controls became available again.

The JSON file must be UTF-8 without a byte-order mark. Some Windows PowerShell versions add a BOM when using Set-Content -Encoding utf8, causing Codex to fail with:

failed to parse model_catalog_json ... expected value at line 1 column 1

I avoided this with:

[System.IO.File]::WriteAllText(
    $modelFile,
    $json,
    [System.Text.UTF8Encoding]::new($false)
)

Caveat

model_catalog_json freezes the entire model catalog, not only multi_agent_version. Users must temporarily remove the override and regenerate the snapshot to receive future model metadata updates.

There is also a potentially significant Ultra compatibility risk. Sol and Terra advertise Ultra support and were originally assigned MultiAgentV2. Forcing their tool surface to V1 may prevent proactive delegation, reduce orchestration quality, or produce a mismatch between Ultra runtime behavior and the available multi-agent tools. Users who rely on Ultra should not assume that a successful V1 spawn test proves that Ultra is fully functional.

Hypothesis, not a confirmed cause

In the original catalog, Sol and Terra were both assigned V2 and supported the new ultra reasoning level, while Luna was assigned V1 and did not support Ultra. The official Subagents documentation states that Ultra can proactively delegate suitable work to subagents.

This correlation suggests that MultiAgentV2 may be related to Ultra orchestration. I have not found source code or a maintainer statement confirming that MultiAgentV2 was created specifically for Ultra. It is also not yet verified whether every Ultra delegation behavior works correctly after forcing the V1 tool surface.

For that reason, this workaround should be considered experimental when model_reasoning_effort = "ultra" is used. A controlled V1/V2 comparison of proactive delegation, child creation, steering, waiting, and result collection is still needed.

---

Complete workaround guide

The full PowerShell procedure, validation steps, maintenance notes, and rollback instructions are available here:

• GitHub Gist: https://gist.github.com/occupty/f049819475e934803df98c04e279eee9