Skip to content

Subagent-specific TOML config no longer works on Codex Windows; named agents spawn with default config #19399

Open
Open
Subagent-specific TOML config no longer works on Codex Windows; named agents spawn with default config#19399
Labels
bugSomething isn't workingconfigIssues involving config.toml, config keys, config merging, or config updatesregressionBehaviors that worked in previous versions but were broken due to an updatesubagentIssues involving subagents or multi-agent features

Description

@syht1602
syht1602
opened on Apr 24, 2026

What variant of Codex are you using?

Codex desktop app on Windows.

What happened?

Subagent-specific configuration appears to no longer work on Codex Windows.

Previously, I could invoke a configured subagent by mentioning it, for example:

spawn [@developer](subagent://developer) and ask it to report status only

I expected Codex to spawn the developer subagent using that subagent's configured TOML settings: instructions, model, and reasoning level.

Instead, Codex only appears able to spawn the default agent configuration. The mention is accepted in the chat UI, and a subagent can be spawned, but the spawned agent does not behave like the configured named subagent. From the parent session/tooling side, I can only spawn generic/default-style agents, not the named subagent configuration.

Expected behavior

When I mention a configured subagent such as:

[@developer](subagent://developer)

Codex should resolve and spawn that exact configured subagent.

The spawned subagent should use the configured TOML values, including:

  • the configured instructions
  • the configured model
  • the configured reasoning level

Actual behavior

The subagent mention no longer seems to resolve to the configured subagent.

Observed behavior:

  • [@developer](subagent://developer) is accepted in the prompt.
  • A subagent can be spawned.
  • But the spawned subagent behaves like the default/generic agent config.
  • The configured TOML values do not appear to be applied.
  • instructions are not applied.
  • model is not applied.
  • reasoning_effort is not applied.
  • I cannot reliably spawn the configured developer subagent anymore.
  • The only working path appears to be spawning the default agent config with manually restated instructions.

Sanitized subagent config layout

My local subagent configs are TOML files in a Codex config folder similar to this:

<workspace>/
  .codex/
    agents/
      developer.toml
      reviewer.toml
      planner.toml

Example sanitized config:

# .codex/agents/developer.toml

name = "developer"
description = "Developer subagent for implementation/status work"
model = "gpt-5.3-codex"
reasoning_effort = "high"

instructions = """
You are the developer subagent.

Responsibilities:
- inspect the workspace state
- report factual status
- implement only when explicitly assigned
- do not modify protected files
- do not stage or commit unless explicitly asked
"""

Another example:

# .codex/agents/reviewer.toml

name = "reviewer"
description = "Reviewer subagent for post-implementation code review"
model = "gpt-5.4"
reasoning_effort = "medium"

instructions = """
You are the reviewer subagent.

Responsibilities:
- inspect the completed patch
- report bugs, regressions, missing tests, and risks
- do not implement fixes
- do not modify files
"""

Reproduction steps

  1. Run Codex desktop app on Windows.

  2. Create a local named subagent config such as:

    <workspace>/.codex/agents/developer.toml

  3. Include TOML fields for the named agent, including name, instructions, model, and reasoning_effort.

  4. In a Codex session, ask Codex:

    spawn [@developer](subagent://developer) and ask it to report status only

  5. Observe the spawned subagent.

  6. Compare the spawned agent behavior/config against the configured developer subagent.

Example from my session

I repeatedly asked:

spawn [@developer](subagent://developer) and ask it to report status only

Codex spawned subagents and they produced status reports, but the configured developer subagent config did not appear to be used. The behavior was equivalent to spawning a default/generic agent with manually supplied instructions.

One earlier spawn attempt also produced this error when trying to combine a forked context with an explicit agent type:

Full-history forked agents inherit the parent agent type, model, and reasoning effort; omit agent_type, model, and reasoning_effort, or spawn without a full-history fork.

That may or may not be related, but it shows that the current spawning path is constrained and does not seem to expose a working way to target the named subagent config.

Environment

  • OS: Windows
  • App: Codex desktop
  • Version: 26.422.21637
  • Workspace shell: PowerShell
  • Date observed: 2026-04-24

Impact

This breaks workflows that depend on named subagents with different responsibilities, models, and reasoning levels. For example:

  • a lightweight status/reporting agent
  • a high-reasoning reviewer
  • a coding-focused developer
  • a planner/debugger/test agent with specific guardrails

The workaround is to manually restate the intended role/instructions every time, but that defeats the purpose of reusable subagent configs and is error-prone. It also does not restore the configured model and reasoning level behavior.

Additional notes

This looks like a regression because the UI still allows subagent mentions such as subagent://developer, but the configured subagent does not appear to be selected at spawn time.

Please confirm whether named TOML subagent configs are still supported on Windows Codex desktop, and if so, what the current expected invocation path is.

Activity

  1. github-actions
    added
    bugSomething isn't working
    appIssues related to the Codex desktop app
    windows-osIssues related to Codex on Windows systems
    subagentIssues involving subagents or multi-agent features
    configIssues involving config.toml, config keys, config merging, or config updates
    on Apr 24, 2026

  2. github-actions commented on Apr 24, 2026

    @github-actions
    github-actionsBot
    on Apr 24, 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. etraut-openai
    added
    regressionBehaviors that worked in previous versions but were broken due to an update
    and removed
    windows-osIssues related to Codex on Windows systems
    appIssues related to the Codex desktop app
    on Apr 24, 2026
  4. firatcand
    added 4 commits that reference this issue on May 17, 2026

    feat(install): pure Codex subagent TOML renderer + platform shim (ROS…

    7929993

    feat(doctor): surface Codex Windows TOML workaround (ROS-33)

    69f8b8f

    [ROS-33] Codex subagent installer: TOML render + persona sidecar + Wi…

    cf49b31

    docs(scheduling): canonical reference for Phase 2.5 scheduling (ROS-3…

    d4ade7b

  5. Keesan12 commented on May 18, 2026

    @Keesan12
    Keesan12
    on May 18, 2026 · Hidden as spam

  6. etraut-openai commented on Jun 1, 2026

    @etraut-openai
    etraut-openai
    on Jun 1, 2026
    Contributor

    I don’t think this is confirmed as filed.

    A few things stand out:

    1. The sample standalone agent TOML uses keys Codex does not currently consume for agent roles:

      • use developer_instructions, not instructions
      • use model_reasoning_effort, not reasoning_effort

    2. A discovered .codex/agents/*.toml role file without developer_instructions is intentionally ignored with a startup warning.

    3. The error:

    Full-history forked agents inherit the parent agent type, model, and reasoning effort...

    is expected behavior. In multi-agent v2, fork_turns defaults to all, and full-history forks intentionally reject agent_type, model, and reasoning_effort. To select a named role, the spawn needs to avoid a full-history fork, e.g. fork_turns: "none" or a partial fork.

    I checked current code and there is test coverage for workspace .codex/agents/*.toml discovery and role application. I also validated:

    just test -p codex-core discovers_multiple_standalone_agent_role_files

    That passed.

    Could you retry with a standalone file shaped like this?

    name = "developer"
description = "Developer subagent for implementation/status work"
model = "gpt-5.3-codex"
model_reasoning_effort = "high"

developer_instructions = """
You are the developer subagent.

Responsibilities:
- inspect the workspace state
- report factual status
- implement only when explicitly assigned
"""

    And please include:

    • any startup warnings from Codex
    • the actual spawn_agent arguments used, especially agent_type and fork_turns
    • whether fork_turns = "none" or a partial fork still ignores the role
    • a thread/log ID if available

    Right now this looks more like invalid role TOML plus full-history fork semantics than a confirmed Windows regression.

  7. AnitaHailey0306 commented on Jul 10, 2026

    @AnitaHailey0306
    AnitaHailey0306
    on Jul 10, 2026 – with ChatGPT Codex Connector

    I can reproduce this on a current Windows Codex Desktop build, even with the corrected standalone-agent keys and with fork_turns: "none".

    Environment

    • Windows Codex Desktop: 26.707.31428
    • Bundled Codex CLI: 0.144.0-alpha.4
    • Observed: 2026-07-10
    • Shell: PowerShell

    Parent and named-agent configuration

    The parent/default config was:

    model = "gpt-5.6-terra"
model_reasoning_effort = "high"

    The personal named agent was ~/.codex/agents/reviewer.toml:

    name = "reviewer"
description = "Read-only reviewer for bugs, regressions, edge cases, and missing tests."
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

developer_instructions = """
Review only.
Focus on correctness, regressions, edge cases, performance risks, and missing tests.
Avoid style-only comments.
Do not edit files.
Return concise findings ordered by severity.
"""

    So this repro uses developer_instructions and model_reasoning_effort, not the older instructions / reasoning_effort keys.

    Blocking surface mismatch

    In this Desktop session, the model-visible spawn_agent tool schema exposes only:

    • task_name
    • message
    • fork_turns

    It does not expose agent_type, model, model_reasoning_effort, profile, provider, or a custom-agent selector.

    I spawned a minimal probe with:

    {
  "task_name": "reviewer",
  "fork_turns": "none",
  "message": "Diagnostic probe only. Do not call tools and do not inspect files. Reply with exactly: READY"
}

    Actual child metadata

    The child was created at agent path /root/reviewer, but its metadata showed:

    agent_role = null
model = gpt-5.6-terra
effort = high
collaboration_model = gpt-5.6-terra
collaboration_effort = high

    It therefore inherited the parent/default model and effort instead of applying the named reviewer role (gpt-5.6-sol + xhigh + read-only).

    Local child rollout/thread ID from this repro:

    019f4adb-79c0-76d1-b3f7-358aae516067

    Expected behavior

    The Desktop spawn surface should either:

    1. expose agent_type so the parent can select the discovered reviewer role, or
    2. provide another documented selector that resolves the custom agent by its name.

    Using task_name: "reviewer" currently changes only the agent path; it does not select the named role.

    This appears closely related to the narrower schema report in #14039:
    #14039 (comment)

    The practical impact is silent cost and quality drift: a strong/high-effort parent cannot reliably delegate to a cheaper agent, and a cheaper parent cannot invoke a stronger reviewer, even though the custom-agent TOML and current documentation support separate model settings.

  8. pcordon commented on Jul 11, 2026

    @pcordon
    pcordon
    on Jul 11, 2026

    Environment

    • OS: Windows 11 Professional
    • Codex runtime: 0.144.1
    • Authentication: ChatGPT
    • multi_agent: true
    • multi_agent_v2: false
    • Feedback/session ID: 019f52c8-65de-7a21-85cf-8e0fb5bb304d

    Custom agent

    C:\Users\windo\.codex\agents\coder56lunalow.toml

    Relevant settings:

    name = "coder56lunalow"
model = "gpt-5.6-luna"
model_reasoning_effort = "low"

    The file also contains custom developer_instructions and nickname candidates.

    Problem

    New conversations cannot correctly select this custom agent.

    In the desktop app, when instructed to spawn coder56lunalow without substituting a generic agent, the parent replied:

    I can’t select a custom subagent model with the available spawning interface, so I did not spawn anything.

    In a new CLI conversation, the spawn call was:

    {
  "task_name": "coder56lunalow",
  "fork_turns": "none",
  "message": "<encrypted>"
}

    The child then recorded:

    model = "gpt-5.6-terra"
reasoning_effort = "medium"

    Those are the parent settings, not the custom-agent settings.

    I also temporarily added a unique marker to the custom agent's developer_instructions. The child did not output it, confirming that the custom instructions were not applied.

    Because fork_turns was explicitly "none", this does not appear to be caused by full-history inheritance.

    Old-thread comparison

    A conversation created before the recent update still selects the same custom agent correctly when resumed after the update.

    That older thread used:

    tools.multi_agent_v1__spawn_agent({
  agent_type: "coder56lunalow",
  message: "..."
})

    The resulting child correctly recorded:

    model = "gpt-5.6-luna"
reasoning_effort = "low"

    It also received the custom developer instructions and one of the configured nicknames:

    LunaLowPop

    This suggests a per-thread tool-interface difference:

    • Older resumed thread: exposes agent_type and correctly loads the TOML agent.
    • Newly created thread: exposes task_name instead, so coder56lunalow becomes only a task name and the custom configuration is not applied.

    Impact

    The configured lower-cost model and reasoning settings are silently bypassed in new conversations, causing substantially higher usage than expected.

  9. usernameup commented on Jul 15, 2026

    @usernameup
    usernameup
    on Jul 15, 2026 – with ChatGPT Codex Connector

    Additional macOS Codex Desktop evidence (July 2026):

    This is not limited to the Windows path in the issue description. Before restoring our custom agent setup, we defined 11 named TOML roles with explicit instructions, model, and model_reasoning_effort.

    In a fresh-parent test set (5 parent threads and 4 spawned children), all observed V2 child runtime contexts instead showed:

    • agent_role = null
    • model = gpt-5.6-sol
    • model_reasoning_effort = high

    This remained true for roles configured to use a different model/effort. The child task could still complete, so the failure is silent: the requested named role/configuration is not reflected in runtime provenance.

    This appears related to #20077 as well: V2 full-history inheritance seems to prevent or bypass the role/model/reasoning overrides that the custom-agent documentation describes.

  10. abura2222v2 commented on Jul 28, 2026

    @abura2222v2
    abura2222v2
    on Jul 28, 2026

    Confirming the same issue on Windows.

    Environment: Codex Desktop, Windows 11, app version 26.721.41059, build flavor prod. Project has .codex/agents/*.toml files (e.g. explorer.toml, worker.toml) each setting a model field per the documented schema (name, description, developer_instructions, model, model_reasoning_effort, sandbox_mode).

    Symptom 1 — per-agent model ignored: Spawning a named subagent (e.g. worker, which has model = "gpt-5.6-luna" in its own .toml) does not use that model. Instead it falls through to whatever [agents].default_subagent_model is set in the global ~/.codex/config.toml. Same for model_reasoning_effort and sandbox_mode — none of the per-agent overrides appear to take effect.

    Symptom 2 — subagent spawn model allow-list is narrower than what the app exposes elsewhere: Regardless of what default_subagent_model is set to, only gpt-5.6-sol and gpt-5.6-terra actually launch a subagent. Setting it to gpt-5.4-mini or gpt-5.6-luna (both valid, selectable models elsewhere in the app/docs) throws at spawn time:

    Unknown model gpt-5.4-mini. Available models: gpt-5.6-sol, gpt-5.6-terra

    and the same for gpt-5.6-luna. This makes the subagent model-tiering feature (cheaper models for cheaper tasks) unusable as documented — every subagent effectively runs on the same model regardless of its own config.

    Workaround in use: setting default_subagent_model = "gpt-5.6-terra" globally, since it's the only cheaper-than-sol model that actually launches. This loses per-role model/effort differentiation entirely.

    Happy to provide more repro details if useful.

  11. abura2222v2 commented on Jul 28, 2026

    @abura2222v2
    abura2222v2
    on Jul 28, 2026

    Follow-up: found a working mitigation, and it's a partial fix.

    Per a suggestion from OpenAI support, I added explicit agents.<name>.config_file entries in ~/.codex/config.toml pointing at each project's .codex/agents/<name>.toml (instead of relying on directory auto-discovery):

    [agents.worker]
config_file = "D:\path\to\.codex\agents\worker.toml"

    Result, confirmed via the session rollout log (not just the agent's self-report):

    • model and model_reasoning_effort from the agent's own TOML file DO apply once registered this way — confirmed for two different roles/models (gpt-5.6-luna and gpt-5.4-mini, both low/medium effort as configured per-agent), instead of silently falling back to the global [agents].default_subagent_model.
    • sandbox_mode still does NOT apply. One agent's TOML sets sandbox_mode = "read-only", but the session log shows it actually ran with danger-full-access (inherited from the parent session) even with the config_file registration in place.

    So agents.<name>.config_file is a viable workaround for the model/effort half of this bug, but not for sandbox_mode — that part of the per-agent config is still being dropped. Wanted to record this in case it helps narrow down the fix, since it suggests the model/effort and sandbox resolution paths are handled by different code that only one of them got patched (or the config_file path never covered sandbox to begin with).

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

    bugSomething isn't workingconfigIssues involving config.toml, config keys, config merging, or config updatesregressionBehaviors that worked in previous versions but were broken due to an updatesubagentIssues 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