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

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

• #17598

Powered by Codex Action

This feels related to two different surfaces getting flattened together: selecting a named agent and forking full parent history. If the resolution path silently falls back to the default agent whenever those collide, users lose the exact thing named agents are for. I would want Codex to emit the resolved agent id, effective instructions hash, model, and reasoning effort at spawn time so the mismatch is obvious immediately instead of after a weird run. We have been treating that as a receipt problem in MartinLoop too. If useful, happy to compare notes against the fields we ended up needing.

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

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

1. 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.

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:
https://github.com/openai/codex/issues/14039#issuecomment-4878584124

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.

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.

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.