Tool-backed Codex Desktop ignores prompt model steering and cannot select named custom agents

Open 💬 6 comments Opened Jul 10, 2026 by LetTTGACO

💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

Summary

The Codex subagents documentation says:

When you want finer control, steer that choice in your prompt or set model and model_reasoning_effort directly in the agent file.

In a tool-backed Codex Desktop session, neither path appears to work through the exposed collaboration.spawn_agent interface.

Prompt steering is ignored, and a valid named custom agent cannot be selected. The spawned child instead inherits the parent model and reasoning effort.

The same custom agent works correctly through native codex exec when the CLI calls spawn_agent with an explicit agent_type.

Environment

Surface: Codex Desktop, tool-backed collaboration session
Desktop runtime CLI version: 0.144.0-alpha.4
Installed CLI version: codex-cli 0.144.1
OS: macOS 26.5.2
Architecture: arm64
Parent model: gpt-5.6-sol
Parent reasoning effort: high

The exposed collaboration.spawn_agent interface only accepts:

task_name
message
fork_turns

It does not expose:

agent_type
model
model_reasoning_effort
profile

Reproduction 1: prompt steering

Spawn a child without inherited conversation history:

{
  "task_name": "no_fork_steering_probe",
  "fork_turns": "none",
  "message": "Steer the child setup to model gpt-5.6-terra with reasoning effort medium. Perform a read-only git status task."
}

Expected:

model = gpt-5.6-terra
effort = medium

Actual child runtime metadata:

agent_role = null
model = gpt-5.6-sol
effort = high

The child inherited the parent configuration despite the explicit prompt steering.

Reproduction 2: named custom agent

Create:

# ~/.codex/agents/sdd_review_standard.toml

name = "sdd_review_standard"
description = "Standard read-only reviewer for routine task reviews."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
Review the assigned change as a skeptical code owner.
Do not edit files.
"""

Spawn another child without inherited conversation history:

{
  "task_name": "no_fork_custom_agent_probe",
  "fork_turns": "none",
  "message": "Use the installed custom agent named sdd_review_standard and perform a read-only git status task."
}

Expected:

agent_role = sdd_review_standard
model = gpt-5.6-terra
effort = high
sandbox = read-only

Actual:

agent_role = null
model = gpt-5.6-sol
effort = high
sandbox = workspace-write

None of the custom agent settings were applied.

Control experiment: native CLI path

Run:

codex exec --json -s read-only \
  "Call the native spawn_agent tool with agent_type sdd_review_standard
   and no full-history fork. Ask it to perform a read-only git status task.
   Wait for it and return the result."

Actual child runtime metadata:

agent_role = sdd_review_standard
model = gpt-5.6-terra
effort = high
sandbox = read-only

This confirms that:

The custom agent TOML is valid and discoverable.
gpt-5.6-terra is available on the account.
The custom agent configuration is respected by the native CLI path.
The failure is specific to the tool-backed Codex Desktop collaboration.spawn_agent surface.

Expected behavior

At least one of the following should be supported:

Prompt steering should influence the spawned child's model and reasoning effort when no agent configuration is pinned.
A named custom agent should be selectable through the tool-backed spawn_agent interface.
The tool should expose structured agent_type, model, and model_reasoning_effort parameters.
If prompt steering is only best-effort, the documentation should state that clearly and explain which spawning surfaces support it.

The child thread metadata should also expose the resolved agent type, model, and reasoning effort to the parent without requiring inspection of local JSONL session files.

Related issues

#15250 — Custom subagents are not accessible from tool-backed Codex sessions
#14039 — Allow per-subagent model/provider/profile selection
#14671 — Custom-agent model/reasoning config was overridden by parent config
#14807 — Previous fix making agent config override project profiles

This may be another instance of #15250, but the additional prompt-steering failure and the successful native CLI control case may help narrow down the affected runtime path.

View original on GitHub ↗

6 Comments

github-actions[bot] contributor · 10 days ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

#31893
#32031
#31814
#31097

Powered by Codex Action

LetTTGACO · 10 days ago

Retest after a full Codex Desktop restart

I fully quit and relaunched Codex Desktop, then repeated Reproduction 2 in a brand-new task. This removes the earlier possibility that the custom-agent registry was only loaded at app or task initialization.

Preconditions

Retest started: 2026-07-11 07:49:22 +0800
The new parent task was created after the Desktop restart.
~/.codex/agents/sdd_review_standard.toml already existed before the task started and still specified:
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
The first child was spawned with fork_turns = "none".
The prompt explicitly requested the installed custom agent named sdd_review_standard.

First child: clean no-history retest

Child thread ID:

019f4e6f-a697-7341-8558-4681b4f3686c

Runtime metadata:

agent_role = null
model = gpt-5.6-sol
effort = high
sandbox = workspace-write

This is the same failure as Reproduction 2: none of the named custom-agent settings were applied after the full app restart and new-task initialization.

Additional nested spawn observation

The first child interpreted the request to use sdd_review_standard by calling its own exposed collaboration.spawn_agent tool with:

{
  "task_name": "sdd_review_standard",
  "fork_turns": "all"
}

That produced a second-level child:

019f4e6f-cd45-71b2-b52f-6131dcc1ee17

Its runtime metadata was also:

agent_role = null
model = gpt-5.6-sol
effort = high
sandbox = workspace-write

This nested child is not a second no-history control because it used fork_turns = "all". However, it demonstrates the interface problem directly: even when the agent tries to honor the named-agent request by spawning a task named sdd_review_standard, the tool has no agent_type parameter, so the name is treated only as a task path and the custom agent is not selected.

Updated conclusion

Reproduction 2 still reproduces after:

A complete Desktop restart
A brand-new parent task
A pre-existing, CLI-validated custom-agent TOML
A first-level child with no inherited conversation history

The restart/registry-refresh confounding variable is therefore ruled out for this tool-backed path. I have not yet tested a Desktop UI agent picker or subagent:// mention path, if either is available.

dzshzx · 9 days ago

I reproduced the same underlying failure mode independently on Linux/WSL with codex-cli 0.144.1, ChatGPT auth, and parent model gpt-5.6-sol.

More importantly, I confirmed the two-setting workaround mentioned in #31814 and collected child-runtime evidence showing that it really selects and applies the named custom agent.

Default behavior

codex features list reported:

multi_agent       stable             true
multi_agent_v2    under development  false

Despite that listing, the active thread used MultiAgentV2 because of the model metadata. The default model-visible spawn schema contained only:

task_name
message
fork_turns

A prompt that named the custom agent did not select it. Setting only:

[features.multi_agent_v2]
hide_spawn_agent_metadata = false

caused the backend to reject the turn before execution:

Invalid Value: 'tools'.
Function 'collaboration.spawn_agent' is reserved for use by this model
and must match the configured schema.

Successful control

I then started a fresh session with both overrides:

[features.multi_agent_v2]
hide_spawn_agent_metadata = false
tool_namespace = "agents"

The parent was deliberately set to gpt-5.6-sol / low. It called:

{
  "agent_type": "reviewer",
  "fork_turns": "none",
  "task_name": "reviewer_namespace_probe"
}

The spawned child's persisted runtime metadata was:

agent_role = reviewer
model = gpt-5.6-sol
reasoning effort = high
sandbox = read-only

The reviewer role's developer_instructions were also present in the child's developer context. This proves that the custom-agent TOML was discovered and fully applied: role, effort, sandbox, and base instructions all changed from the parent/default setup.

Inference

This narrows the failure substantially:

Custom-agent discovery and role application work in 0.144.1.
hide_spawn_agent_metadata = true prevents the model from expressing the role selection.
Exposing the fields under the reserved collaboration namespace causes the backend schema mismatch.
Exposing them under a non-reserved namespace such as agents restores working agent_type selection.

This is a usable official-config workaround for CLI users, but it is not documented in the Subagents page and the default behavior still contradicts the documented “Have reviewer …” invocation pattern. I have not yet confirmed whether Codex Desktop honors the same two settings after a full restart; that would be the next useful control for this issue.

LetTTGACO · 9 days ago

One additional control helps narrow this down.

With GPT-5.5, Codex Desktop uses multi_agent_v1.spawn_agent, whose schema explicitly exposes:

model
reasoning_effort

Passing those fields successfully created a child with the requested model and reasoning effort.

GPT-5.6 instead uses MultiAgentV2 and exposes collaboration.spawn_agent, whose current schema only contains:

task_name
message
fork_turns

It does not expose model or reasoning_effort, so GPT-5.6 has no structured way to request a different child configuration.

This suggests the underlying capability works, but the required parameters have not yet been exposed by the GPT-5.6 / MultiAgentV2 tool interface.

backpropagation6 · 4 days ago

Reproduced again on a newer Codex Desktop runtime, with project-local custom agents.

Environment

Surface: Codex Desktop, tool-backed collaboration session
Source recorded by the parent rollout: vscode
Embedded CLI: 0.144.5
OS: macOS 26.5.2, arm64
Parent: gpt-5.6-sol / high
Intended child: gpt-5.6-terra / medium, read-only

Configuration

The trusted project contained a valid .codex/agents/esploratore.toml before Codex Desktop was launched:

name = "esploratore"
description = "Read-only explorer for bounded investigations."
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"

developer_instructions = """
Perform bounded read-only exploration and return evidence.
Do not modify files.
"""

The project .codex/config.toml also configured:

[agents]
max_threads = 4
max_depth = 1
interrupt_message = true

Checks performed before reproduction:

project trust entry present;
all TOML files parsed successfully;
both gpt-5.6-sol and gpt-5.6-terra were present in the bundled model catalog;
multi_agent was enabled;
Codex Desktop was launched after the agent files already existed.

Actual result

Four child launches were inspected: three normal task names and one retry whose task_name exactly matched esploratore.

All four recorded:

agent_role = null
model = gpt-5.6-sol
effort = high

The intended custom-agent model, effort, role, and read-only profile were not applied. The exposed collaboration.spawn_agent schema still only provided:

task_name
message
fork_turns

There was no agent_type, agent_name, model, effort, or profile selector.

Expected result

An exact registered custom-agent request should resolve to:

agent_role = esploratore
model = gpt-5.6-terra
effort = medium
sandbox = read-only

If the Desktop surface cannot resolve the requested custom agent, it should fail before inference instead of silently launching a generic child that inherits the expensive parent configuration.

Impact

This was the user's third occurrence of this failure mode. The silent fallback caused substantial avoidable token usage across repeated orchestration attempts and forced a fail-closed stop before useful work could begin.

The current documentation says custom agents can be configured under project-local .codex/agents/ and selected by name, so the observed Desktop behavior also conflicts with the documented contract: https://developers.openai.com/codex/subagents

Please expose a structured custom-agent selector in the tool-backed Desktop spawn interface, surface the effective child role/model/effort in the UI, and make unresolved role requests fail loudly.

backpropagation6 · 4 days ago

Additional scope clarification from the affected user:

The same custom-agent routing failure has been encountered from all three surfaces they tested:

Codex CLI
Codex Desktop
Codex mobile

The detailed runtime metadata in my previous comment was captured from the Desktop reproduction. The CLI and mobile occurrences are user-observed reproductions; I am not claiming equivalent rollout metadata was captured from those two surfaces.

This means the user impact is not limited to one entry point: repeated attempts across CLI, Desktop, and mobile have all failed to reliably apply the requested custom-agent profile, contributing to the reported avoidable token usage.