codex-subagents

Spawning subagents through codex-router

Codex can delegate a task to a subagent running on a different model. codex-router decides which models Codex is allowed to pick. This skill covers getting the right models offered, proving they actually work, and fixing it when they don't.

Run every command from the codex-router checkout.

Start here, always

node .claude/skills/codex-subagents/subagent-report.mjs

This answers the only question that matters — if I ask Codex to spawn a subagent right now, what can it pick? — and it is the one question control subagents status does not answer. That command reports your intent. The merged catalog is what Codex actually reads. They drift apart silently, and the report catches the drift.

If the report says a model is spawnable, it is offered to Codex. If it doesn't appear there, nothing else you do in Codex will surface it.

How a model becomes spawnable

A model carries multiAgentVersion: "v2" in the catalog. Three modes decide who gets it:

Mode	Effect
`proven`	Only models the registry ships as verified. Conservative default.
`selected`	Proven models plus ones you explicitly turn on. Use this.
`all`	Every non-hidden model, regardless of whether it works.

./bin/control subagents status                    # current mode, enabled, disabled
./bin/control subagents mode selected
./bin/control subagents set opencode-go/glm-5.2 on
./bin/control subagents set qwen-plan/qwen3.6-flash off
./bin/control subagents select-all                # turn every model on
./bin/control subagents unselect-all              # clear the list, back to a clean slate

An explicit off beats every mode, including all. That is how you keep a model out without leaving all — verified: under mode: all, a model in disabled still resolves to v1.

unselect-all is the fastest way out of a crowded list when the models you want have been pushed past what Codex advertises.

After any change:

node src/catalog.mjs

then fully quit and reopen Codex. Not a new window — the whole app. Codex reads the catalog at startup and caches it. Skipping this is the single most common reason a change appears to do nothing, and the report flags it as STALE.

Two traps that waste the most time

Codex advertises only a small priority-ordered subset. Turning on twelve models does not give you twelve choices — it buries the ones you wanted behind ones you didn't. The report prints models in Codex's ranking order and marks where the cut probably falls. If a model you want sits far down that list, turn off the ones above it rather than adding more.

mode all is not "make everything work". It advertises every model as capable, including models that cannot drive Codex at all. A model that emits tool calls as prose will be offered, accepted, and then fail mid-task with nothing useful in the log. Prefer selected plus a real check.

Proving a model actually works

Capability is not predictable from size, a tool-support flag, or a hand-written probe. A 3B model that emits perfect tool calls on a short prompt answers about its instructions when Codex's real ~24K-token prompt is in front of it. The only honest test runs the real client:

./bin/control local-models agent-check <model-tag>     # local models

For a routed (non-local) model, call the same checker directly:

node --input-type=module -e '
import { checkAgentCapability } from "./src/agent-check.mjs";
console.log(JSON.stringify(checkAgentCapability(process.argv[1]), null, 2));
' "opencode-go/glm-5.2"

This runs codex exec through the router with the real prompt and tools, twice — one run is luck, not a verdict. Verdicts:

Verdict	Meaning
`agent`	Ran a tool, read real output. Safe to enable.
`text-tool-calls`	Emitted a tool call as prose. No client can dispatch it.
`invents-tools`	Called a tool that was never offered.
`no-tool-use`	Answered without using a tool.
`flaky`	Mixed across runs. Do not rely on it.

This spends provider quota — it is a real turn against a real model. Get the user's approval before running it, and say which provider it will bill.

Spawning, once a model is offered

Ask Codex in plain language: "spawn a subagent on glm-5.2 to audit src/router.mjs for unhandled promise rejections." Codex picks from the models the report listed. There is no router-side command that spawns an agent — the router only controls what Codex is allowed to choose.

For parallel work, ask for several in one message so they run concurrently rather than in sequence.

Delegating from a routed parent to a native OpenAI model

The router writes expose_spawn_agent_model_overrides = true into the managed multi_agent_v2 block, so Codex offers a model override on spawn_agent for every session, routed parent included. Name the child model when you ask:

spawn a subagent on gpt-6-astra to audit src/router.mjs

Codex checks the name against its own override list and rejects anything it does not offer, so an unavailable model fails before a turn is spent. The router keeps the override instead of pinning the child back to the parent's model; only a spawn call that omits the model inherits the parent.

When it goes wrong

Model not offered in Codex. Run the report. Not listed → subagents set <slug> on, rebuild, restart. Listed but far down → crowded out; turn off higher-priority models.

Subagent starts, then fails or stalls. Run the agent check. A text-tool-calls or invents-tools verdict means the model cannot do this job; turn it off rather than retrying.

Change had no effect. Almost always a missed node src/catalog.mjs or a Codex that was never fully quit. The report's STALE line catches the first.

Everything fails at once, on every model. Not a subagent problem. Check the router itself:

./bin/model-router codex doctor

A provider named in enabled-providers.json that this build doesn't know used to 502 every request while the process stayed alive and looked healthy. doctor now reports it as a warning naming the ignored ids.

Rules worth keeping

Never set multiAgentVersion: "v2" in the checked-in registry to make something work locally. That claims support for every user. Local opt-in is ./bin/control subagents set, which only changes this machine's catalog.
The registry uses camelCase (multiAgentVersion); the merged catalog is Codex's wire format and uses snake_case (multi_agent_version). Reading the wrong key reports zero capable models on a healthy install.
Curated models from bin/curate-models are not implicitly approved as subagents. They need an explicit subagents set <slug> on.