Custom agent roles from project .codex/config.toml are not available to spawn_agent #14579

Summary

Custom agent roles defined in a project-local .codex/config.toml are not available to spawn_agent, even though the same role works when injected via CLI -c config overrides.

This looks like a runtime/config-loading regression in Codex CLI rather than a role-definition problem.

Environment

• Codex CLI: 0.114.0
• OS: Linux (6.6.87.2-microsoft-standard-WSL2)
• multi_agent: enabled

What the docs say

The docs say custom agent roles can be defined either in:

• local user config: ~/.codex/config.toml
• project config: .codex/config.toml

Docs:

• https://developers.openai.com/codex/multi-agent
• https://developers.openai.com/codex/config-basic

Minimal repro

Create this project structure:

/tmp/repro/
  .codex/
    config.toml
    agents/
      lens.toml
      lens.md

/tmp/repro/.codex/config.toml

[features]
multi_agent = true

[agents.lens]
description = "Custom lens role"
config_file = "agents/lens.toml"

/tmp/repro/.codex/agents/lens.toml

model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
model_instructions_file = "/tmp/repro/.codex/agents/lens.md"

/tmp/repro/.codex/agents/lens.md

Reply with READY only.

Then run:

codex exec --skip-git-repo-check "Call spawn_agent with agent type lens. If it fails, print the exact failure message only."

Actual result

Codex reports:

unknown agent_type 'lens'

Expected result

spawn_agent(agent_type="lens") should succeed and start a child agent using the role defined in project .codex/config.toml.

Important control case

The role works if I inject the same config via CLI overrides instead of relying on project config.

This succeeds:

codex exec --skip-git-repo-check \
  --enable multi_agent \
  -c 'agents.lens.description="CLI lens"' \
  -c 'agents.lens.config_file="/tmp/repro/.codex/agents/lens.toml"' \
  "Call spawn_agent with agent type lens. If it fails, print the exact failure message only."

In that case, Codex successfully spawns the lens agent.

Why this seems like a bug

• The role files are valid enough for Codex to use when injected through -c.
• The docs say project-local .codex/config.toml should support custom roles.
• The failure is specifically in live spawn_agent role resolution from project config.

Extra note

Direct prompts like "use the lens role" are not a reliable test here, because Codex can inspect files on disk and answer without actually spawning a custom sub-agent. The failing path is an actual spawn_agent(agent_type="lens") call.