Detect or warn when TOML-backed subagent routing is unavailable in native Codex spawn_agent

[starobba]

Summary

LazyCodex / OMO guidance can imply that ULW-triggered or role-named subagents such as plan and reviewer are using the configured Codex agent TOML files, including model and reasoning effort. In the current native Codex spawn_agent surface observed on Windows, the parent can only pass task_name, fork_turns, and message, so the runtime does not provide an observable or enforceable way to confirm that the configured TOML-backed agent role was selected.

This creates a trust-boundary problem: users can believe LazyCodex routing policy was applied while the spawned child may simply be a generic/default native subagent named plan or reviewer.

Environment

• LazyCodex package checked: lazycodex-ai@4.7.5
• lazycodex-ai npm latest: 4.7.5, time.modified: 2026-06-03T05:03:30.285Z
• oh-my-openagent npm latest: 4.7.5, time.modified: 2026-06-03T05:02:33.262Z
• Codex CLI: codex-cli 0.137.0
• OS: Windows (codex doctor: windows-x86_64)
• Shell/workspace: PowerShell / Git Bash, <workspace>
• Install/config surface: LazyCodex / OMO plugin plus Codex native subagent tools

Reproduction

1. Configure Codex agent TOMLs under the user Codex home, for example:
   • ~/.codex/agents/plan.toml
   • ~/.codex/agents/reviewer.toml
2. Register them in ~/.codex/config.toml:

   [agents.plan]
   config_file = "./agents/plan.toml"
   
   [agents.codex-ultrawork-reviewer]
   config_file = "./agents/codex-ultrawork-reviewer.toml"

3. Start a normal Codex session with LazyCodex / OMO guidance active.
4. Trigger ULW-style work or spawn a role-named subagent through the native tool surface, for example spawn_agent with task_name = "plan".
5. Ask the child to report whether it can see its configured TOML-backed role instructions, model, or reasoning effort.

Expected Behavior

LazyCodex should either:

1. Ensure the intended TOML-backed role is actually selected for the child agent, including model and reasoning effort; or
2. Detect that the current Codex runtime only exposes generic native spawn_agent fields and clearly warn that TOML-backed routing cannot be guaranteed; or
3. Route through a supported LazyCodex/OMO adapter that preserves the intended model/reasoning tier.

A user invoking an ULW mode or LazyCodex role should not have to guess whether plan.toml, reviewer.toml, or codex-ultrawork-reviewer.toml actually controlled the spawned child.

Actual Behavior

The active native spawn_agent surface exposed to the parent session only accepts:

• task_name
• fork_turns
• message

It does not expose agent_type, model, or reasoning_effort fields to the parent. A child can be named plan, but that is not the same as proving the configured plan.toml was selected.

A minimal identity probe returned:

- Visible role/instructions: TOML-backed `plan-agent` dedicated instructions cannot be directly confirmed.
- Visible model: the current agent's actual model name cannot be directly confirmed.
- Visible reasoning effort: reasoning effort settings also cannot be directly confirmed.

The local config appears present and loadable, so this does not look like a simple broken-path case:

[agents.codex-ultrawork-reviewer]
config_file = "./agents/codex-ultrawork-reviewer.toml"

[agents.explorer]
config_file = "./agents/explorer.toml"

[agents.plan]
config_file = "./agents/plan.toml"

Relevant TOML files also exist and contain the expected model/reasoning policy:

--- plan
name = "plan"
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
service_tier = "fast"

--- reviewer
name = "reviewer"
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

--- codex-ultrawork-reviewer
name = "codex-ultrawork-reviewer"
model = "gpt-5.5"
model_reasoning_effort = "xhigh"

codex doctor --summary reports config loaded and no failures:

Codex Doctor v0.137.0 · windows-x86_64
Configuration
  ✓ config       loaded
  ✓ auth         auth is configured
...
15 ok · 1 idle · 2 notes · 2 warn · 0 fail degraded

Evidence

Commands used:

npm view lazycodex-ai version time.modified dist-tags --json
npm view oh-my-openagent version time.modified dist-tags --json
codex --version
codex doctor --summary
sed -n '145,178p' "$HOME/.codex/config.toml"
for f in plan reviewer codex-ultrawork-reviewer explorer; do
  test -f "$HOME/.codex/agents/$f.toml" && grep -nE '^(name|model|model_reasoning_effort|reasoning_effort|service_tier|sandbox_mode)' "$HOME/.codex/agents/$f.toml"
done

Related upstream issue in Codex itself:

• Subagent-specific TOML config no longer works on Codex Windows; named agents spawn with default config openai/codex#19399: Subagent-specific TOML config no longer works on Codex Windows; named agents spawn with default config

Related LazyCodex orchestration issue:

• Subagent orchestration can mark dependent work complete without waiting for spawned plan/review agents #30: Subagent orchestration can mark dependent work complete without waiting for spawned plan/review agents

Root Cause

Strongly evidenced cause: LazyCodex/OMO instructions and routing expectations assume role-specific agent routing, but the currently exposed native Codex spawn_agent tool surface does not let the parent specify or verify the TOML-backed agent role, model, or reasoning effort.

What appears ruled out locally:

• Missing config file: ruled out by ~/.codex/config.toml mappings and existing ~/.codex/agents/*.toml files.
• Config load failure: ruled out by codex doctor --summary reporting config loaded and 0 fail.
• NPM latest already fixing this: unlikely, because lazycodex-ai@4.7.5 is still the latest published package and predates the more recent June 5 LazyCodex GitHub activity.

What remains uncertain:

• Whether this should be fixed entirely in Codex native subagent support, or whether LazyCodex should add a compatibility adapter/warning while Codex issue #19399 remains open.

Proposed Fix

Add a LazyCodex/OMO compatibility guard for named/TOML-backed subagent routing.

Possible approaches:

• During SessionStart or first subagent orchestration, inspect the available Codex subagent tool schema or runtime capabilities.
• If spawn_agent does not support selecting a configured agent type/model/reasoning effort, inject an explicit warning into ULW/review-work guidance: role names are task names only and TOML routing is not guaranteed.
• Prefer a LazyCodex wrapper/adapter when available that can preserve the configured role routing.
• For important roles (plan, reviewer, codex-ultrawork-reviewer, explorer), require the parent to mark the result as routing-unverified unless runtime evidence confirms the TOML-backed role was selected.
• Document the fallback behavior while Subagent-specific TOML config no longer works on Codex Windows; named agents spawn with default config openai/codex#19399 is unresolved.

Verification Plan

• On Windows Codex CLI/Desktop with LazyCodex installed, configure plan.toml and reviewer.toml with distinct model/reasoning settings.
• Start a fresh Codex session and trigger a LazyCodex/ULW flow that spawns plan or reviewer.
• Verify LazyCodex either confirms TOML-backed routing or emits a clear compatibility warning.
• Verify the warning disappears only when the runtime can actually select/confirm the configured agent role.
• Regression check: normal generic spawn_agent usage should still work when no role-specific routing is required.

[tully-8888]

Additional macOS / Codex Desktop evidence: the live OMO agent TOMLs installed by LazyCodex still contain model/service-tier combinations that native Codex rejects when requested explicitly.

Environment:

• LazyCodex npm latest checked with npm view lazycodex-ai version: 4.7.5
• Codex CLI: codex-cli 0.136.0
• OS: macOS 26.5 build 25F71
• OMO plugin cache: /Users/tully/.codex/plugins/cache/sisyphuslabs/omo/0.1.0

Config evidence:

• /Users/tully/.codex/agents/plan.toml: model = \"gpt-5.5\", model_reasoning_effort = \"xhigh\", service_tier = \"fast\"
• /Users/tully/.codex/agents/metis.toml: model = \"gpt-5.5\", model_reasoning_effort = \"high\", service_tier = \"fast\"
• /Users/tully/.codex/agents/codex-ultrawork-reviewer.toml: model = \"gpt-5.5\", model_reasoning_effort = \"xhigh\", no service_tier
• These are symlinks into /Users/tully/.codex/.tmp/marketplaces/sisyphuslabs/plugins/omo/components/ultrawork/agents/....

Runtime evidence from the same stuck update-channel workflow: an explicit native spawn_agent(agent_type=\"plan\", service_tier=\"fast\") failed with:

Service tier fast is not supported for model gpt-5.5. Supported service tiers: priority

Impact:

• This is not only a routing-observability issue. On this account/runtime, the installed TOML value itself is a compatibility hazard if native Codex actually honors the TOML-backed service_tier for gpt-5.5 agents.
• It can interact badly with issue Subagent orchestration can mark dependent work complete without waiting for spawned plan/review agents #30 because the user sees stuck or degraded planning/reviewer behavior and there is no obvious warning that part of the agent config may be invalid for the selected model.

Suggested fix extension:

• Validate installed agent TOMLs against current Codex model/service-tier capabilities at install time or session start.
• For gpt-5.5, either omit unsupported service_tier or map to priority when the runtime says that is the only supported tier.
• Emit a clear warning when an installed marketplace agent config contains a service tier unsupported by the current Codex runtime/account.

[code-yeongyu]

[sisyphus-bot] 처리 완료했습니다.

TOML-backed subagent routing이 native Codex spawn_agent에서 검증되지 않은 상태일 때의 경고/폴백을 source-of-truth repo의 packages/omo-codex에 반영했습니다. 반영 PR은 code-yeongyu/oh-my-openagent#5031 이고, dev에 merge commit 0908f17980b27188b5ebabc1ae7907876564b619로 머지되었습니다.

커버된 내용:

• role/model/reasoning TOML routing은 runtime/schema evidence 없이는 routing-unverified로 취급
• prompt-carried role requirements를 binding fallback으로 명시
• subagent-guidance.test.mjs에서 TOML routing warning과 fallback 문구를 회귀 테스트로 고정

검증 완료되어 이 mirror issue는 닫습니다.