Codex spawn_agent Rejects GPT-5.6 Luna? Fix It Safely

If Codex lists gpt-5.6-luna as a top-level model but spawn_agent says it is unknown, use gpt-5.6-terra or gpt-5.6-sol for the child agent and keep Luna for work that does not require native V2 delegation. This is a model-catalog mismatch, not an authentication failure, so repeatedly signing in, editing cached model data, or forcing feature flags will not fix it safely.

The exact failure has been reproduced in Codex CLI 0.145.0 on macOS, Windows, and WSL. OpenAI's issue tracker still showed multiple open reports on July 31, 2026, including a fresh report that day. The typical error is:

Unknown model `gpt-5.6-luna` for spawn_agent.
Available models: gpt-5.6-sol, gpt-5.6-terra

The Short Fix

Ask Codex to use a supported child model explicitly:

Use one gpt-5.6-terra subagent with medium reasoning to inspect the current
diff for correctness. Do not edit files. Return the exact files checked and
one command I can run to verify the result

Expected result: the spawn_agent request names gpt-5.6-terra, a child task starts, and a separate result returns to the parent. If Terra is also rejected, use the models printed in your own error instead of copying a model name from this guide.

Why Luna Can Work in One Place but Fail in Another

OpenAI documents gpt-5.6-luna as a current model for cost-sensitive, high-volume workloads. That does not prove every Codex execution surface exposes it in the same role.

The open Codex reports distinguish two catalogs:

• the top-level model picker can list Luna;

• native MultiAgent V2 child creation can allow only Sol and Terra.

One report attributes the rejection to Luna being marked for MultiAgent V1 while the active spawn_agent path filters for V2. Treat that as the current repository diagnosis, not a permanent product contract. The important operational fact is the allowlist in your own error.

Prerequisites

You need:

• Codex CLI or the Codex app with native subagents available;

• a disposable, read-only task for the test;

• a parent session that can show the child model request;

• a clean understanding of your working tree before any agent runs commands.

Check the CLI and repository state:

codex --version
codex features list | grep multi_agent
git status --short

Expected result: Codex prints its version, the multi-agent feature state is visible, and every local change is accounted for. Do not enable an experimental flag solely to work around this model error.

Step 1: Confirm This Exact Failure

In the same parent session, ask for one bounded Luna child:

Spawn one gpt-5.6-luna subagent with medium reasoning. It must not edit files.
Have it return exactly LUNA_CHILD_OK and stop

If your interface exposes the native request payload, it should resemble:

{
  "task_name": "luna_probe",
  "fork_turns": "none",
  "model": "gpt-5.6-luna",
  "reasoning_effort": "medium",
  "message": "Return exactly LUNA_CHILD_OK. Do not use tools."
}

This guide applies when no child is created and the error specifically says Luna is unknown while listing Sol or Terra. Stop here and use a different diagnosis if you see a login error, rate limit, safety block, network failure, or a message that spawn_agent itself is unavailable.

Step 2: Route the Child to Terra or Sol

Repeat the same probe with a model printed by the error:

Spawn one gpt-5.6-terra subagent with medium reasoning. It must not edit files.
Have it return exactly TERRA_CHILD_OK and stop

The corresponding request is:

{
  "task_name": "terra_probe",
  "fork_turns": "none",
  "model": "gpt-5.6-terra",
  "reasoning_effort": "medium",
  "message": "Return exactly TERRA_CHILD_OK. Do not use tools."
}

Success requires all three checks:

1. the parent emits a spawn_agent call;

2. the tool accepts gpt-5.6-terra and creates a child;

3. a separate child result returns TERRA_CHILD_OK.

Do not count a parent-thread sentence such as "I delegated this" as proof. Check the actual tool receipt or task activity.

Step 3: Choose the Fallback Deliberately

Use Terra for most bounded research, review, or implementation subtasks when you want a balance of capability and cost. Use Sol when the child owns a difficult architecture decision, complex debugging, or another quality-first task.

Keep the task small enough to verify:

Use one gpt-5.6-terra subagent to inspect only src/auth/** and tests/auth/**.
Do not edit files. Return at most five findings, each with a file path, line
number, and reproduction command.

Expected result: one child owns one independent workstream, and the parent can check every claim. For more parallel-work boundaries, see Codex Runs Tool Calls One by One? Batch Them Safely.

Step 4: Keep Luna for Supported Workloads

The spawn_agent failure does not mean Luna is unavailable everywhere. OpenAI's model page still lists Luna for efficient, high-volume API workloads, with tool support through the Responses API. A top-level Codex session may also offer it even when native V2 child creation does not.

Separate those cases:

• use Luna where the active surface accepts it;

• use Terra or Sol for native child overrides;

• verify the selected model at the boundary where it runs;

• avoid assuming that API availability, the top-level picker, and the child allowlist are identical.

If Luna is missing from the top-level picker too, follow Codex Says "Model not found gpt-5.6-sol"? Triage It Safely and check account, rollout, client version, and provider configuration instead.

Common Failure Modes

Luna Still Appears in /model

That is consistent with the reported bug. The top-level picker and the child model allowlist are separate checks. Use the spawn_agent error as the source of truth for that child request.

You Updated Codex but the Error Remains

Record the new version, fully restart the app or CLI session, and run the read-only probe once. An update is not proof of a fix. The open reports span multiple clients and platforms.

The Child Model Override Is Not Exposed

Some Codex builds or hosts do not expose model and reasoning_effort on spawn_agent. Do not invent hidden parameters. Use the available default child behavior, update through the supported channel, or run the workload in a separate top-level task where you can select the model explicitly.

The Parent Retries the Same Rejected Request

Stop after the deterministic model error. Repeating an allowlist rejection wastes time and can consume usage without changing the catalog. Switch to a listed model or keep the task in the parent.

A Cached-Catalog Edit Seems to Work

Do not treat a hand-edited model cache as a durable fix. It can drift from the active backend, disappear on update, or route work differently from what the UI shows. Prefer the supported allowlist until OpenAI closes the issue and your own probe passes.

Why This Workaround Works

The failure occurs before the child starts: spawn_agent validates the requested child model against its active backend catalog. Sol and Terra pass that check in the published reproductions; Luna does not. Choosing a listed model changes the one input the validator rejects without weakening sandboxing, permissions, or authentication.

It also preserves a clean rollback. When OpenAI ships a fix, rerun the same no-tools Luna probe. If a real child starts and returns LUNA_CHILD_OK, you can reintroduce Luna for bounded child workloads and compare quality, latency, and cost on representative tasks.

Verify One External Action at the Same Boundary

Model routing and external integrations fail at different boundaries. Test them separately. Connect a read-only integration through Aident Loadout, then ask the working Terra child to discover one read-only Action, inspect its current schema, execute harmless input, and return the provider object ID or URL.

Success means the child actually starts, the integration call uses a schema inspected in the same run, and the parent can verify a stable provider identifier. For the broader setup, see How to Connect Claude Code and Codex to Real-World Tools.

Sources

• GPT-5.6 Luna model page, OpenAI, accessed July 31, 2026

• GPT-5.6 model guidance, OpenAI, accessed July 31, 2026

• gpt-5.6-luna is marked as MultiAgent V1, so V2 spawn_agent rejects it, GitHub, opened July 24, 2026

• Codex CLI 0.145.0 rejects Luna even though /model lists it, GitHub, opened July 23, 2026

• Sol and Terra threads cannot spawn Luna subagents, GitHub, opened July 20, 2026

• Codex app and CLI reproduction on Windows, GitHub, opened July 22, 2026

• Fresh July 31 Luna V2 filtering report, GitHub, opened July 31, 2026

• "5.6-sol unable to spawn 5.6-luna subagents?", Reddit, published July 21, 2026

• "How to use Luna 5.6 subagents", Reddit, published July 30, 2026

Refresh this guide when OpenAI closes the primary issue, changes the native child model allowlist, or documents a different Codex model-selection contract.