[Feature]: Expose named Codex custom-agent selection for native subagents

[lastobelus]

Before submitting

• I searched existing issues and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

apps/server

Problem or use case

T3 Code supports and displays native Codex subagents, but a Codex parent thread cannot deterministically select a named custom agent from ~/.codex/agents/ or .codex/agents/.

In T3 Code Nightly 0.0.29-nightly.20260709.769, the collaboration tool exposed to the parent has this shape:

spawn_agent(
  task_name,
  message,
  fork_turns
)

It has no named-agent, agent_type, model, or reasoning-effort selector. A parent can write "use the terra_high custom agent" in the delegated prompt, but that is only prompt guidance. It does not establish that Codex loaded the named TOML configuration or applied its model and reasoning settings.

For example, given:

# ~/.codex/agents/terra-high.toml
name = "terra_high"
description = "Fast, high-reasoning research and review agent."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
developer_instructions = """
Handle one bounded delegated task and return concise evidence.
"""

there is no deterministic way for a T3 Code Codex thread to request that specific profile when spawning a child.

Proposed solution

Preserve and expose Codex app-server's native named custom-agent selector when that capability is available.

The parent-facing delegation contract should accept the custom agent's name, using the upstream Codex field or mechanism rather than introducing a separate T3 Code agent format. Conceptually:

spawn_agent(
  agent_type: "terra_high",
  task_name: "research",
  fork_turns: "none",
  message: "Investigate the issue and return evidence."
)

If named selection is unsupported, the agent is missing or invalid, or the requested fork mode cannot apply the profile, return an explicit error. Do not silently replace an explicitly requested named agent with a generic child.

Where Codex exposes it, include the effective custom-agent name, model, and reasoning effort in child-thread metadata so the parent and user can verify that the requested configuration was applied.

Why this matters

Named custom agents are useful for assigning fast models to exploration, stronger reasoning to review, read-only permissions to research, and specialized instructions to repeatable roles.

Without deterministic selection, users cannot rely on those profiles from T3 Code. They can request a profile in prose, but cannot distinguish "the configured custom agent ran" from "a generic child received a similar prompt." This prevents predictable cost, latency, capability, and permission choices in multi-agent workflows.

Smallest useful scope

For Codex only:

1. Detect whether the active Codex app-server supports named custom-agent selection.
2. Allow a parent thread to select one agent by its configured name when spawning a direct child.
3. Support personal agents in ~/.codex/agents/ and project agents in .codex/agents/ through Codex's existing discovery behavior.
4. Report a clear error instead of silently substituting a generic child when the requested agent cannot be used.

A first version does not need a profile-management UI, cross-provider agent format, nested delegation, or per-spawn editing of the profile's model and reasoning settings.

Alternatives considered

• Put the desired profile in the child prompt. This communicates intent but does not load or verify the named custom-agent configuration.
• Make the parent use the desired model and reasoning level. Children may inherit those settings, but this prevents different roles from using different profiles.
• Add a T3 Code-specific agent configuration format. This would duplicate Codex's existing .codex/agents/*.toml authority and could drift from upstream behavior.
• Use ChatGPT desktop or Codex CLI for profile-dependent work. This loses the T3 Code workflow and does not address the missing integration surface.

Risks or tradeoffs

• Codex app-server capabilities and spawn schemas may vary by installed Codex version, so the integration should capability-detect rather than assume one fixed schema.
• Some full-history fork modes may require child model, reasoning, or agent settings to inherit from the parent. That state should be reported clearly rather than bypassed.
• Effective model or reasoning metadata may not be available in every Codex release; named selection is still useful without it, but the UI should not claim verification it cannot obtain.
• Personal and project agents with the same name must follow Codex's native precedence rules rather than introducing different T3 Code resolution behavior.

Examples or references

• Codex custom-agent documentation: https://learn.chatgpt.com/docs/agent-configuration/subagents
• T3 Code orchestration PR feat(orchestrator): introduce new orchestrator #2829: https://github.com/feat(orchestrator): introduce new orchestrator #2829

PR #2829 covers native child-thread tracking, subagent lifecycle events, replay, context transfer, and UI projection. This request concerns the earlier selection boundary: choosing the named Codex custom agent before Codex spawns the child.

Contribution

• I would be open to helping implement this.