Skip to content

feat(codex): support explicit model or custom role per spawned subagent #3886

Description

@skyerus

Motivation

Buzz-managed Codex agents cannot currently select a lower-cost model or a
model-pinned custom-agent profile for one delegated task without changing the
model resolution for every subagent.

The live spawn_agent interface exposes:

  • a task name and prompt;
  • gpt-5.6-sol and gpt-5.6-terra as explicit model overrides; and
  • no custom-agent role/profile selector.

This prevents a strong primary agent from delegating one bounded task to a
profile pinned to another available model such as gpt-5.6-luna, while leaving
ordinary subagent work unchanged.

Verified reproduction

Environment: Buzz ACP managed Codex session on macOS, Codex CLI 0.145.0.

  1. Create .codex/agents/luna-worker.toml:

    name = "luna_worker"
    description = "Bounded low-cost implementation worker."
    model = "gpt-5.6-luna"
    model_reasoning_effort = "max"
    developer_instructions = "Perform only the bounded task and return evidence."
  2. Spawn a child through the Buzz-provided collaboration tool using
    task_name = "luna_worker", no model override, and a fresh fork.

  3. Inspect the child rollout metadata.

Actual result: the child runs on gpt-5.6-sol. Its thread metadata records the
path /root/luna_worker but agent_role: null, so the profile name is treated
only as a task label.

The same result occurs in a fresh Codex process that loads the profile before
startup, ruling out profile-discovery caching: the spawned child still records
model: gpt-5.6-sol and agent_role: null.

Proposed solution

Expose an explicit custom-agent selector on Buzz's Codex spawn_agent tool
(agent_role, agent_type, or equivalent) and forward it to Codex when the
child thread is created.

The selected profile should apply its configured model, reasoning effort,
developer instructions, and other supported session settings. The explicit
model override should also be sourced from the runtime's available model
catalog rather than a fixed Sol/Terra allowlist, so supported models such as
Luna can be selected directly when no custom profile is needed.

Suggested acceptance criteria:

  1. task_name remains the human-readable task/path label.
  2. A separate optional role/profile field selects a loaded built-in or custom
    Codex agent.
  3. A custom profile pinned to Luna/max produces child rollout metadata with
    model: gpt-5.6-luna and the selected non-null agent role.
  4. An explicit available model and reasoning effort can be selected for a
    one-off child without changing global subagent defaults.
  5. Omitting both fields preserves current inheritance behavior.
  6. Unknown or unavailable profiles/models fail clearly before work begins.
  7. Add an ACP integration test covering profile selection, direct model
    selection, and the unchanged-default case.

Alternatives considered

  • Set agents.default_subagent_model to Luna: rejected because it silently
    changes unrelated subagent work.
  • Create a separate Luna-backed managed Buzz agent: works around model
    selection, but adds identity, routing, permissions, and closeout overhead for
    what should be an ephemeral worker.
  • Change the primary agent's model: solves a different problem and weakens the
    high-consequence owner rather than routing only bounded work.

Additional context

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions