[Feature]: ocx doctor should warn about opencodex-derived Codex role TOMLs ($CODEX_HOME/agents/ocx-*.toml) that lack a model pin #4790

Area

CLI

What are you trying to accomplish?

Run Codex sub-agents on the models featured in the opencodex roster (ocx agent subagents), with the Claude Code integration (claudeCode.injectAgents) enabled at the same time, and have ocx doctor tell me when the Codex-side role files silently defeat that.

What prevents this today?

When the Codex desktop app's external-agent import is enabled ([desktop] external-agent-import-sync-enabled = true, item types "all"), it converts the opencodex-generated Claude Code agents ~/.claude/agents/ocx-*.md into $CODEX_HOME/agents/ocx-*.toml. The conversion drops the model: frontmatter (a claude-ocx-native--gpt-5.5 id is not a Codex model) and keeps only developer_instructions, including the <!-- ocx-route: ... --> directive with "Claude Code" text-replaced to "Codex".

Result:

• The ocx-route directive is only honoured on the Claude /v1/messages path, so on /v1/responses it is inert.
• A Codex role TOML without model = inherits the parent model, so every ocx-gpt-5-5 / ocx-gpt-5-6-* spawn ran on the parent (gpt-6-astra) while the role file told the child it was Codex-ocx-native--gpt-5.5.
• ocx doctor reports ok no per-role model_fallback fields in $CODEX_HOME/agents/*.toml and nothing else about these files, so the misrouting is invisible until you diff session rollouts (session_meta.agent_role vs turn_context.model).

Verified on opencodex 2.54.0, Codex CLI 0.154.0, Codex desktop 26.908 (Windows 11).

Rollout evidence (before the fix):

role=ocx-gpt-5-6-terra  src=subagent  turn.model=gpt-6-astra high
role=ocx-gpt-5-6-luna   src=subagent  turn.model=gpt-6-astra medium

I understand opencodex does not generate Codex role TOMLs itself (sub-agent guide), so this is not an opencodex bug. But the files are recognisably opencodex-derived (generated-by: opencodex marker, ocx- prefix, ocx-route directive), and ocx doctor already scans $CODEX_HOME/agents/*.toml, so it is well placed to catch this.

What should OpenCodex do?

ocx doctor (section "Codex agent role files") should warn when a role file in $CODEX_HOME/agents/ looks opencodex-derived but has no effective model pin, for example:

• name starts with ocx- or the body contains generated-by: opencodex / <!-- ocx-route:, and
• the file has no model = key.

Suggested text:

warn   $CODEX_HOME/agents/ocx-gpt-5-5.toml carries an ocx-route directive but no `model` pin.
       Codex will run this role on the parent model; the ocx-route directive is only honoured
       on the Claude Code path. Add `model = "gpt-5.5"` or remove the file. This usually comes
       from the Codex desktop external-agent import of ~/.claude/agents/ocx-*.md.

Optional follow-ups (lower priority):

• Mention in the Claude Code guide that the Codex app import can copy ocx-*.md into Codex role files, and how to exclude it (external-agent-import-sync-item-types = { SUBAGENTS = false, ... }).
• Or, when the Claude Code integration is enabled and $CODEX_HOME/agents/ exists, offer to write matching role TOMLs with a real model = pin (roster model id) so both harnesses stay in sync.

Example usage or interface

Before (current 2.54.0):

Codex agent role files
  ok     no per-role model_fallback fields in $CODEX_HOME/agents/*.toml

After:

Codex agent role files
  ok     no per-role model_fallback fields in $CODEX_HOME/agents/*.toml
  warn   2 opencodex-derived role file(s) without a `model` pin: ocx-gpt-5-5.toml, ocx-gpt-5-6-luna.toml
         These roles inherit the parent model. Add `model = "<id>"` or remove them.

Alternatives or workarounds

What I did, which works:

1. Rewrote each $CODEX_HOME/agents/ocx-*.toml by hand with model = "gpt-5.5" etc. plus model_reasoning_effort, and a plain developer_instructions (no ocx-route text). Verified a spawned ocx-gpt-5-5 child now records turn.model=gpt-5.5 medium.
2. Changed [desktop] external-agent-import-sync-item-types from "all" to an inline table with SUBAGENTS = false so the import cannot recreate the broken files.

Additional context

• Sub-agent guide: https://opencodex.me/guides/sub-agent-surface/ (states fallback belongs in opencodex config, not role TOMLs; does not cover role files without model).
• Claude Code guide: https://opencodex.me/guides/claude-code/ (ocx-route directive).
• Related upstream (Codex app import mangling): Claude Code skill import rewrites .claude/ paths to .Codex/, producing directories that don't exist openai/codex#40147 — skill import rewrites .claude/ to .Codex/. The same text replacement shows up in the imported role files (Codex-ocx-native--gpt-5.5, Codex-api).

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.