Skip to content

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

Open
Open
Tool-backed Codex Desktop ignores prompt model steering and cannot select named custom agents#32291
Labels
appIssues related to the Codex desktop appapp-serverIssues involving app server protocol or interfacesbugSomething isn't workingsubagentIssues involving subagents or multi-agent features

Description

@LetTTGACO
LetTTGACO
opened on Jul 10, 2026

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:

  1. The custom agent TOML is valid and discoverable.
  2. gpt-5.6-terra is available on the account.
  3. The custom agent configuration is respected by the native CLI path.
  4. 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:

  1. Prompt steering should influence the spawned child's model and reasoning effort when no agent configuration is pinned.
  2. A named custom agent should be selectable through the tool-backed spawn_agent interface.
  3. The tool should expose structured agent_type, model, and model_reasoning_effort parameters.
  4. 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

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.

Activity

  1. github-actions
    added
    bugSomething isn't working
    appIssues related to the Codex desktop app
    subagentIssues involving subagents or multi-agent features
    app-serverIssues involving app server protocol or interfaces
    on Jul 10, 2026

  2. github-actions commented on Jul 10, 2026

    @github-actions
    github-actionsBot
    on Jul 10, 2026 – with GitHub Actions
    Contributor

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

    Powered by Codex Action

  3. LetTTGACO commented on Jul 10, 2026

    @LetTTGACO
    LetTTGACO
    on Jul 10, 2026 – with ChatGPT Codex Connector
    Author

    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:

    1. A complete Desktop restart
    2. A brand-new parent task
    3. A pre-existing, CLI-validated custom-agent TOML
    4. 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.

  4. dzshzx commented on Jul 11, 2026

    @dzshzx
    dzshzx
    on Jul 11, 2026 – with ChatGPT Codex Connector

    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.

  5. LetTTGACO commented on Jul 11, 2026

    @LetTTGACO
    LetTTGACO
    on Jul 11, 2026 – with ChatGPT Codex Connector
    Author

    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.

  6. backpropagation6 commented on Jul 16, 2026

    @backpropagation6
    backpropagation6
    on Jul 16, 2026 – with ChatGPT Codex Connector

    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.

  7. backpropagation6 commented on Jul 16, 2026

    @backpropagation6
    backpropagation6
    on Jul 16, 2026 – with ChatGPT Codex Connector

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    appIssues related to the Codex desktop appapp-serverIssues involving app server protocol or interfacesbugSomething isn't workingsubagentIssues involving subagents or multi-agent features

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions