Codex sub-agent spawn supports per-launch reasoning_effort, but tool schema/docs make agents think it cannot be changed

What version of Codex CLI is running?

codex-cli 0.137.0

What subscription do you have?

Pro x20

Which model were you using?

gpt-5.5 Sub-agent probes tested: - gpt-5.5 medium - gpt-5.5 high - gpt-5.5 xhigh

What platform is your computer?

Linux 5.15.167.4-microsoft-standard-WSL2 x86_64 x86_64 Ubuntu 24.04 on WSL2 Windows Terminal host

What terminal emulator and version are you using (if applicable)?

Windows Terminal 1.24.11321.0 WSL_DISTRO_NAME=Ubuntu-24.04 TERM=xterm-256color No tmux/zellij detected

Codex doctor report

codex doctor --json status: ok
  codexVersion: 0.137.0
  auth: ChatGPT tokens configured
  config model: gpt-5.5
  model provider: openai
  install method: npm
  platform: linux-x86_64
  terminal: Windows Terminal
  sandbox: filesystem unrestricted, network enabled, approval policy Never
  latest version: 0.137.0, current version is not older

What issue are you seeing?

The native sub-agent launch tool appears to support per-spawn model and reasoning settings, but the exposed tool
schema/documentation visible to agents does not advertise the working fields clearly.

Observed behavior:

• The visible spawn_agent schema shown to the parent agent only listed message, items, and fork_context.
• Because of that schema, an agent concluded that sub-agent reasoning level could not be changed and that children

were pinned to/inherited from the parent setting.

• Passing the requested level only in prompt text, e.g. “launch gpt-5.5 xhigh”, did not prove a runtime change.
• Passing model_reasoning_effort also caused confusion; it appears to be the TOML/custom-agent config key, not the

live per-spawn key.

• The live per-spawn field that actually worked was reasoning_effort.

Verified working launches from parent UI:

• spawn_agent with model: "gpt-5.5", reasoning_effort: "medium" showed (gpt-5.5 medium).
• spawn_agent with model: "gpt-5.5", reasoning_effort: "high" showed (gpt-5.5 high).
• spawn_agent with model: "gpt-5.5", reasoning_effort: "xhigh" showed (gpt-5.5 xhigh).

The child agents themselves could not introspect their actual runtime model or reasoning effort, so their self-report
was unknown. The reliable confirmation was the parent UI spawn label.

What steps can reproduce the bug?

Uploaded thread: 019ea57a-efb1-7cc3-9429-d82d4c366272

1. Ask Codex whether native sub-agents can be launched with different reasoning levels.
2. Inspect the exposed spawn_agent tool schema available to the agent.
3. Notice the schema only documents message, items, and fork_context, not model or reasoning_effort.
4. Try launching a sub-agent by putting “gpt-5.5 xhigh” or similar only in the prompt text.
5. The child agent cannot confirm any runtime setting and reports that it cannot observe model/reasoning effort.
6. Try live launch with this payload shape:

{
"message": "XHIGH runtime probe. Do not do external work. Reply only: xhigh probe completed.",
"model": "gpt-5.5",
"reasoning_effort": "xhigh"
}

1. Parent UI correctly shows the spawn as (gpt-5.5 xhigh).
2. Repeat with "reasoning_effort": "medium" and "reasoning_effort": "high"; parent UI correctly shows `(gpt-5.5

medium) and (gpt-5.5 high)`.

What is the expected behavior?

The sub-agent launch schema and documentation should clearly expose the supported per-spawn fields:

• model
• reasoning_effort

It should also clarify that:

• reasoning_effort is the live per-spawn tool field.
• model_reasoning_effort is the config/custom-agent TOML field.
• Child agents may not be able to introspect their actual runtime model/effort.
• The parent spawn label is the reliable confirmation.

Alternatively, if model and reasoning_effort are intentionally unsupported public fields, the runtime should
reject them rather than silently accepting hidden fields that work.

Additional information

This appears to be a schema/documentation mismatch, not a model capability issue.

The functionality works when using:
{
"model": "gpt-5.5",
"reasoning_effort": "xhigh"
}

But the exposed schema led the agent to believe it could not change sub-agent reasoning settings. This is likely to
cause incorrect guidance and unnecessary workarounds.