Workaround for forcing Codex MultiAgent V1 on GPT-5.6 Sol and Terra

A developer has published a workaround for forcing Codex MultiAgent V1 on GPT-5.6 Sol and Terra, addressing a regression where model metadata overrides local feature flags. The workaround involves modifying a local model-catalog snapshot to set multi_agent_version to 'v1', but warns that forcing V1 may disable Ultra's proactive delegation and other orchestration behaviors. The regression is tracked in openai/codex issue #31097.

This guide explains how to use a local model-catalog override to force the Codex MultiAgent V1 tool surface for GPT-5.6 Sol and Terra. It addresses the following behavior: codex features list reports multi agent v2 = false , but new sessions still use V2. spawn agent exposes only task name , message , and fork turns .- V1 custom-agent, child-model, and reasoning-effort controls are unavailable. This workaround was verified on Windows with Codex CLI 0.144.5 . The underlying regression is tracked in openai/codex issue 31097 https://github.com/openai/codex/issues/31097 . This is a temporary workaround for the current model-catalog precedence behavior. It is not an officially guaranteed long-term configuration. Recheck whether it is necessary after upgrading Codex. Ultra compatibility warning:Sol and Terra advertise Ultra support and were originally assigned MultiAgentV2. Forcing V1 may disable or degrade Ultra's proactive delegation, coordination, steering, waiting, or result-collection behavior. An ordinary V1 spawn test does not establish that Ultra is safe or fully functional under this override. Some model-catalog records contain: "multi agent version": "v2" That model metadata can take precedence over: features multi agent = true multi agent v2 = false The workaround loads a local snapshot through model catalog json and changes the target models to multi agent version: "v1" . The original catalog associated Sol and Terra with both MultiAgentV2 and Ultra support. The official Subagents documentation https://learn.chatgpt.com/docs/agent-configuration/subagents states that Ultra can proactively delegate suitable work to subagents. This creates a plausible, but unconfirmed, dependency between Ultra orchestration and MultiAgentV2. Forcing V1 may therefore cause one or more of the following: - Proactive delegation may not start. - Child agents may be created with incomplete or unexpected settings. - Steering, waiting, interruption, or result collection may behave differently. - The runtime may expect V2 capabilities that are absent from the V1 tool schema. - Ultra may appear selectable while only part of its intended orchestration behavior works. Do not use a successful ordinary V1 spawn as proof of Ultra compatibility. If Ultra is operationally important, keep V2 enabled or test the workaround in an isolated profile before adopting it broadly. Run in PowerShell: codex --version codex features list | Select-String -Pattern '^multi agent\s|^multi agent v2\s' $catalog = codex debug models | ConvertFrom-Json $catalog.models | Where-Object { $ .slug -like 'gpt-5.6- ' } | Select-Object slug, multi agent version If Sol or Terra reports multi agent version as v2 , model metadata may be forcing the V2 tool surface. php $codexHome = Join-Path Environment ::GetFolderPath 'UserProfile' '.codex' $configFile = Join-Path $codexHome 'config.toml' $backupFile = Join-Path $codexHome "config.toml.backup-{0}" -f Get-Date -Format 'yyyyMMdd-HHmmss' Copy-Item -LiteralPath $configFile -Destination $backupFile Write-Host "Backup: $backupFile" Before running this script, ensure config.toml does not already define model catalog json . Otherwise, codex debug models may read an older local snapshot instead of the current upstream catalog. php $codexHome = Join-Path Environment ::GetFolderPath 'UserProfile' '.codex' $modelFile = Join-Path $codexHome 'models-v1.json' $catalog = codex debug models | ConvertFrom-Json $targets = @ 'gpt-5.6-sol', 'gpt-5.6-terra' foreach $model in $catalog.models { if $model.slug -in $targets { $model.multi agent version = 'v1' } } $missing = $targets | Where-Object { $ -notin $catalog.models.slug } if $missing { throw "Models missing from catalog: $ $missing -join ', ' " } $json = $catalog | ConvertTo-Json -Depth 100 $utf8WithoutBom = System.Text.UTF8Encoding ::new $false System.IO.File ::WriteAllText $modelFile, $json, $utf8WithoutBom Write-Host "Model catalog: $modelFile" The JSON must be UTF-8 without BOM. Some Windows PowerShell versions add a BOM when using Set-Content -Encoding utf8 , causing: failed to parse model catalog json ... expected value at line 1 column 1 The WriteAllText call above avoids that problem. If Luna is already V1, it does not need to be changed. To pin it explicitly, add gpt-5.6-luna to $targets . Open: C:\Users\<username \.codex\config.toml Add the model-catalog path at the TOML top level. An absolute path in a TOML literal string avoids escaping Windows backslashes: model catalog json = 'C:\Users\<username \.codex\models-v1.json' Find the existing features section and merge these settings into it: features multi agent = true multi agent v2 = false Do not create a second features section. For example, an existing section may become: features js repl = false multi agent = true multi agent v2 = false Run in a new PowerShell process: codex features list | Select-String -Pattern '^multi agent\s|^multi agent v2\s' $catalog = codex debug models | ConvertFrom-Json $catalog.models | Where-Object { $ .slug -like 'gpt-5.6- ' } | Select-Object slug, multi agent version Expected output: multi agent stable true multi agent v2 under development false slug multi agent version ---- ------------------- gpt-5.6-sol v1 gpt-5.6-terra v1 gpt-5.6-luna v1 If codex debug models fails, check: models-v1.json is valid UTF-8 JSON without BOM.- The model catalog json path is correct. - The TOML file does not contain duplicate top-level keys. features is not declared more than once. Fully exit every existing Codex session, then launch: codex -m gpt-5.6-sol Ask Codex to spawn a subagent and verify that: - The agent type is visible, for example worker . - The child model and reasoning effort are visible. - A configured custom agent or explicitly selected child model can be used. Do not rely on /model inside an existing thread. The multi-agent tool version may be pinned when the thread is created, so an existing V2 thread may remain V2 after a model change. If Ultra will be used, perform a separate controlled test with model reasoning effort = "ultra" . Verify proactive delegation, multiple child creation, steering, waiting, interruption, completion collection, and final synthesis. Until those behaviors pass, treat Ultra as unsupported under the V1 override. model catalog json freezes the entire model catalog, not only multi agent version . New models and updates to model descriptions, capabilities, instructions, and other metadata will not be synchronized automatically. To refresh the snapshot: - Temporarily remove or comment out model catalog json in config.toml . - Run the script in step 3 again to obtain the current upstream catalog. - Restore model catalog json . - Run the validation commands in step 5. - Start a fresh Codex session. After every Codex upgrade, temporarily remove the override and check whether the upstream regression has been fixed. Remove this top-level setting from config.toml : model catalog json = 'C:\Users\<username \.codex\models-v1.json' Then remove or restore these feature settings as appropriate: multi agent = true multi agent v2 = false After confirming that config.toml no longer references the snapshot, delete: C:\Users\<username \.codex\models-v1.json Fully exit Codex and start a new session. Existing threads may retain their previously selected tool version and should not be used to validate the rollback.