Custom subagent creation in codex

ChatGPT Apps SDK
1

Hi team,

I’m trying to create a non-forked custom Codex subagent using the documented configuration approach.

I created this file at ~/.codex/agents/luna_high.toml:

name = "luna_high"
description = "GPT-5.6 Luna agent for narrowly scoped, repeatable work that needs high reasoning effort."
model = "gpt-5.6-luna"
model_reasoning_effort = "high"

developer_instructions = """
Handle only the bounded task delegated by the parent agent.
Work independently, keep the scope narrow, and return a concise evidence-backed summary.
Do not delegate further work unless the parent explicitly asks.
"""

The Codex documentation says custom agents can define model and model_reasoning_effort, and that Codex identifies them by their name.

However, when I try to spawn this custom agent from the desktop app’s subagent workflow, the runtime rejects it with:

unknown agent_type 'luna_high'

The runtime currently appears to expose only built-in agent types such as default, worker, and explorer, and model overrides appear limited to gpt-5.6-sol and gpt-5.6-terra.

Could you clarify:

  1. Is gpt-5.6-luna currently supported for custom subagents in Codex desktop?
  2. Are custom agents from ~/.codex/agents/*.toml expected to be selectable in the desktop app’s subagent workflow?
  3. Does adding or changing a custom agent require restarting Codex or creating a new task?
  4. If the UI/runtime does not support custom agent names yet, what is the supported way to spawn a non-forked Luna High subagent?
  5. Is there an official runtime/status view that confirms the actual model and reasoning effort used by a spawned subagent, rather than only showing its requested configuration?

Environment: Codex desktop app, Codex CLI 0.146.0, ChatGPT sign-in.

2

had the same issue now. i was able to make luna available for subagents only when i went the path settings > workspace dependencies > reset and install workspace. in a new session, i was able to create luna agents, but in old ones it is still stuck with only terra and sol.

it was likely a bug caused in one of the updates.