{"slug": "workaround-for-forcing-codex-multiagent-v1-on-gpt-5-6-sol-and-terra", "title": "Workaround for forcing Codex MultiAgent V1 on GPT-5.6 Sol and Terra", "summary": "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.", "body_md": "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.\n\nIt addresses the following behavior:\n\n`codex features list`\n\nreports`multi_agent_v2 = false`\n\n, but new sessions still use V2.`spawn_agent`\n\nexposes only`task_name`\n\n,`message`\n\n, and`fork_turns`\n\n.- V1 custom-agent, child-model, and reasoning-effort controls are unavailable.\n\nThis workaround was verified on Windows with Codex CLI `0.144.5`\n\n. The underlying regression is tracked in [openai/codex issue #31097](https://github.com/openai/codex/issues/31097).\n\nThis 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.\n\nUltra 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.\n\nSome model-catalog records contain:\n\n```\n\"multi_agent_version\": \"v2\"\n```\n\nThat model metadata can take precedence over:\n\n```\n[features]\nmulti_agent = true\nmulti_agent_v2 = false\n```\n\nThe workaround loads a local snapshot through `model_catalog_json`\n\nand changes the target models to `multi_agent_version: \"v1\"`\n\n.\n\nThe 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.\n\nForcing V1 may therefore cause one or more of the following:\n\n- Proactive delegation may not start.\n- Child agents may be created with incomplete or unexpected settings.\n- Steering, waiting, interruption, or result collection may behave differently.\n- The runtime may expect V2 capabilities that are absent from the V1 tool schema.\n- Ultra may appear selectable while only part of its intended orchestration behavior works.\n\nDo 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.\n\nRun in PowerShell:\n\n```\ncodex --version\ncodex features list | Select-String -Pattern '^multi_agent\\s|^multi_agent_v2\\s'\n\n$catalog = codex debug models | ConvertFrom-Json\n$catalog.models |\n    Where-Object { $_.slug -like 'gpt-5.6-*' } |\n    Select-Object slug, multi_agent_version\n```\n\nIf Sol or Terra reports `multi_agent_version`\n\nas `v2`\n\n, model metadata may be forcing the V2 tool surface.\n\n``` php\n$codexHome = Join-Path ([Environment]::GetFolderPath('UserProfile')) '.codex'\n$configFile = Join-Path $codexHome 'config.toml'\n$backupFile = Join-Path $codexHome (\"config.toml.backup-{0}\" -f (Get-Date -Format 'yyyyMMdd-HHmmss'))\n\nCopy-Item -LiteralPath $configFile -Destination $backupFile\nWrite-Host \"Backup: $backupFile\"\n```\n\nBefore running this script, ensure `config.toml`\n\ndoes not already define `model_catalog_json`\n\n. Otherwise, `codex debug models`\n\nmay read an older local snapshot instead of the current upstream catalog.\n\n``` php\n$codexHome = Join-Path ([Environment]::GetFolderPath('UserProfile')) '.codex'\n$modelFile = Join-Path $codexHome 'models-v1.json'\n$catalog = codex debug models | ConvertFrom-Json\n$targets = @('gpt-5.6-sol', 'gpt-5.6-terra')\n\nforeach ($model in $catalog.models) {\n    if ($model.slug -in $targets) {\n        $model.multi_agent_version = 'v1'\n    }\n}\n\n$missing = $targets | Where-Object { $_ -notin $catalog.models.slug }\nif ($missing) {\n    throw \"Models missing from catalog: $($missing -join ', ')\"\n}\n\n$json = $catalog | ConvertTo-Json -Depth 100\n$utf8WithoutBom = [System.Text.UTF8Encoding]::new($false)\n[System.IO.File]::WriteAllText($modelFile, $json, $utf8WithoutBom)\n\nWrite-Host \"Model catalog: $modelFile\"\n```\n\nThe JSON must be UTF-8 without BOM. Some Windows PowerShell versions add a BOM when using `Set-Content -Encoding utf8`\n\n, causing:\n\n```\nfailed to parse model_catalog_json ... expected value at line 1 column 1\n```\n\nThe `WriteAllText`\n\ncall above avoids that problem.\n\nIf Luna is already V1, it does not need to be changed. To pin it explicitly, add `gpt-5.6-luna`\n\nto `$targets`\n\n.\n\nOpen:\n\n```\nC:\\Users\\<username>\\.codex\\config.toml\n```\n\nAdd the model-catalog path at the TOML top level. An absolute path in a TOML literal string avoids escaping Windows backslashes:\n\n```\nmodel_catalog_json = 'C:\\Users\\<username>\\.codex\\models-v1.json'\n```\n\nFind the existing `[features]`\n\nsection and merge these settings into it:\n\n```\n[features]\nmulti_agent = true\nmulti_agent_v2 = false\n```\n\nDo not create a second `[features]`\n\nsection. For example, an existing section may become:\n\n```\n[features]\njs_repl = false\nmulti_agent = true\nmulti_agent_v2 = false\n```\n\nRun in a new PowerShell process:\n\n```\ncodex features list | Select-String -Pattern '^multi_agent\\s|^multi_agent_v2\\s'\n\n$catalog = codex debug models | ConvertFrom-Json\n$catalog.models |\n    Where-Object { $_.slug -like 'gpt-5.6-*' } |\n    Select-Object slug, multi_agent_version\n```\n\nExpected output:\n\n```\nmulti_agent       stable             true\nmulti_agent_v2    under development  false\n\nslug              multi_agent_version\n----              -------------------\ngpt-5.6-sol       v1\ngpt-5.6-terra     v1\ngpt-5.6-luna      v1\n```\n\nIf `codex debug models`\n\nfails, check:\n\n`models-v1.json`\n\nis valid UTF-8 JSON without BOM.- The\n`model_catalog_json`\n\npath is correct. - The TOML file does not contain duplicate top-level keys.\n`[features]`\n\nis not declared more than once.\n\nFully exit every existing Codex session, then launch:\n\n```\ncodex -m gpt-5.6-sol\n```\n\nAsk Codex to spawn a subagent and verify that:\n\n- The agent type is visible, for example\n`[worker]`\n\n. - The child model and reasoning effort are visible.\n- A configured custom agent or explicitly selected child model can be used.\n\nDo not rely on `/model`\n\ninside 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.\n\nIf Ultra will be used, perform a separate controlled test with `model_reasoning_effort = \"ultra\"`\n\n. 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.\n\n`model_catalog_json`\n\nfreezes the entire model catalog, not only `multi_agent_version`\n\n. New models and updates to model descriptions, capabilities, instructions, and other metadata will not be synchronized automatically.\n\nTo refresh the snapshot:\n\n- Temporarily remove or comment out\n`model_catalog_json`\n\nin`config.toml`\n\n. - Run the script in step 3 again to obtain the current upstream catalog.\n- Restore\n`model_catalog_json`\n\n. - Run the validation commands in step 5.\n- Start a fresh Codex session.\n\nAfter every Codex upgrade, temporarily remove the override and check whether the upstream regression has been fixed.\n\nRemove this top-level setting from `config.toml`\n\n:\n\n```\nmodel_catalog_json = 'C:\\Users\\<username>\\.codex\\models-v1.json'\n```\n\nThen remove or restore these feature settings as appropriate:\n\n```\nmulti_agent = true\nmulti_agent_v2 = false\n```\n\nAfter confirming that `config.toml`\n\nno longer references the snapshot, delete:\n\n```\nC:\\Users\\<username>\\.codex\\models-v1.json\n```\n\nFully 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.", "url": "https://wpnews.pro/news/workaround-for-forcing-codex-multiagent-v1-on-gpt-5-6-sol-and-terra", "canonical_source": "https://gist.github.com/occupty/f049819475e934803df98c04e279eee9", "published_at": "2026-07-16 07:05:59+00:00", "updated_at": "2026-07-22 09:57:30.454580+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-agents"], "entities": ["OpenAI", "Codex", "GPT-5.6 Sol", "GPT-5.6 Terra", "Codex CLI"], "alternates": {"html": "https://wpnews.pro/news/workaround-for-forcing-codex-multiagent-v1-on-gpt-5-6-sol-and-terra", "markdown": "https://wpnews.pro/news/workaround-for-forcing-codex-multiagent-v1-on-gpt-5-6-sol-and-terra.md", "text": "https://wpnews.pro/news/workaround-for-forcing-codex-multiagent-v1-on-gpt-5-6-sol-and-terra.txt", "jsonld": "https://wpnews.pro/news/workaround-for-forcing-codex-multiagent-v1-on-gpt-5-6-sol-and-terra.jsonld"}}