Custom subagents in .codex/agents are not accessible from tool-backed Codex sessions as docs imply

+1, this gap matters for tool-backed Codex sessions.

If project-scoped and global custom agents are documented as first-class .codex/agents/*.toml definitions, they should be invokable consistently from all Codex surfaces that expose subagent spawning. Otherwise the same repository setup works in one Codex surface but fails in another, which makes custom-agent workflows hard to trust.

Expected behavior from my point of view:

• custom agents from .codex/agents/ and ~/.codex/agents/ are discoverable in tool-backed sessions
• spawn_agent can target them by their declared name or stable identifier
• errors clearly distinguish "agent not found" from "agent file invalid" or "surface does not support custom agents"

This would make project-local agent definitions usable as shared workflow infrastructure rather than only as documentation-adjacent config.

This feels like a docs and runtime contract gap. If tool-backed sessions cannot resolve repo-local agents by name, Codex should either expose a custom_agent or
ame field on spawn_agent or emit a first-class capability flag saying named agents are unavailable in this runtime. Right now users end up manually parsing TOML just to rehydrate something the platform already understands. We hit a similar problem in MartinLoop when trying to keep role intent portable across tool-backed and app-backed runs. The receipt should say not only what spawned, but which resolution path was used: named agent, generic role, or fallback.

I can reproduce a related and possibly stronger version of this on Codex CLI 0.137.0 on Linux in standalone Codex sessions.

Setup

User config registers custom agents:

[features]
multi_agent_v2 = false

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

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

Agent TOML example:

name = "plan-reviewer"
description = "Plan reviewer delegated agent override."
model = "gpt-5.4-mini"
model_reasoning_effort = "xhigh"
developer_instructions = """
Review implementation plans before handoff.
Do not edit files.
"""

What happened

In a standalone Codex session, the exposed multi_agent_v1.spawn_agent schema only accepted:

• message
• items
• fork_context

It did not expose agent_type, model, reasoning_effort, agent_path, or another role selector.

Prompting the parent to "use the native plan-reviewer role" caused the parent to call:

{
  "message": "Use the native plan-reviewer reviewer role.\n\nTask: Review this tiny fake implementation plan for structure only. Do not edit files. Return one sentence.",
  "fork_context": false
}

The child spawned as a generic agent, not as the registered custom agent.

Child session metadata:

{
  "model": "gpt-5.5",
  "effort": "medium",
  "agent_role": null,
  "agent_path": null,
  "developer_instructions": null
}

MultiAgentV2 check

With multi_agent_v2 = true, the exposed spawn path accepted task_name, but task_name = "plan_reviewer" produced a child with:

{
  "agent_path": "/root/plan_reviewer",
  "model": "gpt-5.5",
  "effort": "medium",
  "developer_instructions": null
}

So v2 task_name behaved like an agent path/name label, not a custom-agent TOML resolver.

Expected behavior

A registered custom agent should be invocable from the native subagent tool surface by declared name/role, and its TOML should apply:

• model = "gpt-5.4-mini"
• model_reasoning_effort = "xhigh"
• developer_instructions
• persisted child metadata showing the resolved agent_role or agent_path

Actual behavior

The custom agent TOMLs are present and registered, but current native spawning cannot bind them. The role name can only be embedded as text in the child prompt, which produces a generic inherited-model subagent.

This appears to be a docs/runtime mismatch plus a regression from older sessions where spawn_agent calls included agent_type: "plan-reviewer" and the child metadata showed the specialized role/model.

Tried in v2 with following arguments:

{
"task_name": "search_docs",
"agent_type": "search-specialist",
"model": "gpt-5.4-mini",
"reasoning_effort": "medium",
"fork_turns": "none",
"message": "..."
}

And its working. I guess these arguments are not documented but somehow inside of the tool.

Created a plugin to enforthis such behaviour: https://github.com/eiphy/codex-subagent-guard/tree/main

Additional privacy-safe reproduction from a Windows Codex CLI session:

• Codex CLI: 0.137.0
• GSD Core: 1.3.1
• OS: Windows
• Config scope: user-global ~/.codex/config.toml
• Custom agents: user-global ~/.codex/agents/*.toml

Observed state:

• codex features list reports multi_agent as stable/true and multi_agent_v2 as false.
• ~/.codex/config.toml parses successfully and contains 33 [agents.gsd-*] entries.
• The referenced ~/.codex/agents/gsd-planner.toml and gsd-executor.toml files exist and parse.
• The upstream workflow tool (gsd-tools query init.quick) reports agents_installed: true, missing_agents: [], agent_runtime: codex.
• Generic subagent spawning works: multi_agent_v1.spawn_agent(message=..., fork_context=false) returns an agent id and the child replies.

Actual exposed tool schema in the model-visible session:

multi_agent_v1.spawn_agent(message?, items?, fork_context?)

There is no agent_type / subagent_type parameter exposed to the model, so an orchestrator cannot invoke a configured named agent such as gsd-planner or gsd-executor directly, despite those agents being installed and registered.

Expected behavior:

If user-global custom agents are registered in ~/.codex/config.toml, the tool-backed session should expose a way to select them, for example agent_type, or documentation should explicitly state that multi_agent_v1 tool-backed sessions only support generic child agents.

Privacy note: local usernames, project names, and absolute private workspace paths are intentionally redacted here.

I can reproduce a model-dependent version of this in Codex CLI 0.142.5.

With multi_agent = true and multi_agent_v2 = false, a fresh GPT-5.4 thread exposes V1 with agent_type, model, and reasoning_effort; spawning a GPT-5.4-mini child with an explicit effort succeeds. I also spawned agent_type: "harness_reviewer" from a personal ~/.codex/agents/ profile. The result reported role harness_reviewer, displayed model gpt-5.4, displayed reasoning effort medium, and the expected child response.

A fresh GPT-5.5 thread behaves differently. The current model catalog sets multi_agent_version: v2 for GPT-5.5, and the runtime gives that model value precedence over the local multi_agent_v2 = false setting. Its exposed schema contains only task_name, message, and fork_turns. It has no agent_type, model, or reasoning_effort, so configured profiles such as reviewer and harness_reviewer cannot be selected. Naming the task reviewer creates only a generic task path and does not resolve the TOML profile.

Changing an existing GPT-5.5 thread to GPT-5.4 leaves it on V2 because the multi-agent version is pinned to the thread; starting a fresh GPT-5.4 thread restores V1.

This makes the documented custom-agent capability model-dependent in a way that is neither visible in features list nor disclosed on the Subagents page. I filed the model-metadata/configuration-precedence reproduction here: https://github.com/openai/codex/issues/31097

I can reproduce this in Codex Desktop on macOS.

Environment:

Codex Desktop

Codex CLI bundled version: 0.144.0-alpha.4

Root model: gpt-5.6-sol

Custom agents under ~/.codex/agents/:

economy_worker: gpt-5.6-luna, medium reasoning

economy_reviewer: gpt-5.6-terra, high reasoning

The custom TOML files load without configuration errors. However, the spawn_agent tool exposed to the root agent accepts only task_name, message, and fork_turns. It provides no custom-agent role or model parameter.

Spawning with task_name = "economy_worker" only names the child thread. Runtime metadata records:

agent_role: null

model: gpt-5.6-sol

The child therefore inherits Sol instead of loading the economy_worker TOML and running Luna. The same problem occurs with the Terra reviewer.

This caused unexpectedly slow and expensive delegation because multiple supposed “economy” workers were actually full Sol agents. Observed worker durations included approximately 3.5, 6, and 8 minutes.

Expected behavior:

spawn_agent should allow the root agent to explicitly select a named custom-agent role loaded from ~/.codex/agents/; or

Codex should automatically resolve an explicitly requested registered role; and

spawned-agent metadata/UI should clearly show the selected role, model, and reasoning effort.

As a temporary safeguard, I changed my global AGENTS.md to prohibit delegation unless the custom role and model can be explicitly selected and verified.

I can reproduce a closely related—and potentially more serious—variant on Codex CLI 0.144.1 on macOS.

In my case, named project-scoped agents appear to spawn successfully, but the requested profiles are not applied. The requested name becomes the child thread’s agent-path label while the child silently inherits the coordinator’s model and reasoning effort.

Configuration

I created five valid profiles under .codex/agents/:

• v2_terra_executor_medium — gpt-5.6-terra / medium
• v2_terra_executor_high — gpt-5.6-terra / high
• v2_terra_validator_high — gpt-5.6-terra / high
• v2_luna_evidence_low — gpt-5.6-luna / low
• v2_luna_archivist_medium — gpt-5.6-luna / medium

The files also specify role-specific instructions and sandbox modes.

Observed result

I spawned five children using those profile names and inspected the persisted rollout records under:

~/.codex/sessions/2026/07/11/

For every child:

• session_meta.agent_path matched the requested profile/task name.
• The first turn_context showed the actual model, reasoning effort and sandbox.

| Requested profile | Actual model | Actual effort | Actual sandbox |
| --- | --- | --- | --- |
| v2_terra_executor_medium | gpt-5.6-sol | high | workspace-write |
| v2_terra_executor_high | gpt-5.6-sol | high | workspace-write |
| v2_terra_validator_high | gpt-5.6-sol | high | workspace-write |
| v2_luna_evidence_low | gpt-5.6-sol | high | workspace-write |
| v2_luna_archivist_medium | gpt-5.6-sol | high | workspace-write |

This indicates that task_name labels the spawned agent path but does not select the corresponding custom profile through the collaboration surface exposed in this build.

Why this is especially concerning

This does not fail visibly.

The requested custom-agent name is accepted, and the child appears under that name. A user can therefore reasonably believe that a lower-cost Terra/Luna profile with low or medium reasoning was selected, while the child actually runs using the coordinator’s Sol/high allocation.

Because each spawned child consumes its own tokens, silent substitution can materially increase usage during multi-agent fan-out. The user receives no clear warning that the requested cost/quality profile was ignored.

This creates both a configuration-integrity problem and a usage-transparency problem.

Expected behavior

One of the following should happen:

1. spawn_agent exposes an explicit agent_type or equivalent parameter that resolves a named .codex/agents/*.toml profile.
2. Codex rejects the spawn if the requested profile cannot be selected.
3. The spawn result prominently reports the actual model, reasoning effort and applied profile before substantive work begins.

Silently falling back to the coordinator configuration should not be considered successful profile selection.

Related reports

This also appears related to:

• #19399 — named agents spawning with the default configuration
• #15177 — requested child model differing from persisted child metadata
• #20077 — agent_type overrides conflicting with full-history forks

The distinguishing evidence here is that five differently configured profile names were accepted, but all five persisted child contexts showed the same actual gpt-5.6-sol / high allocation.

workaround:
Pushing sol I got the following solution working. It requires permission to work outside the sandbox wired into governance.

Try feeding this to sol as a workaround that it can implement itself

Workaround: make Codex 0.144.1 actually run Terra/Sol workers at the requested reasoning level

  ## 1. Run a no-repository canary
  Do not use --ephemeral: you need the persisted rollout to verify the actual allocation.
  codex exec \
    --strict-config \
    --model gpt-5.6-terra \
    -c 'model_reasoning_effort="high"' \
    -c 'sqlite_home="/tmp/codex-terra-canary-state"' \
    --sandbox read-only \
    --cd /tmp \
    --skip-git-repo-check \
    --json \
    'Read no files and run no tools. Reply exactly CANARY_OK.'
  An isolated sqlite_home avoids conflicts with an active Codex CLI/App state database.
  For a Sol xhigh worker:

  codex exec \
    --strict-config \
    --model gpt-5.6-sol \
    -c 'model_reasoning_effort="xhigh"' \
    -c 'sqlite_home="/tmp/codex-sol-xhigh-canary-state"' \
    --sandbox read-only \
    --cd /tmp \
    --skip-git-repo-check \
    --json \
    'Read no files and run no tools. Reply exactly CANARY_OK.'

  ## 2. Verify the actual allocation
  Find the new rollout under:
  find ~/.codex/sessions -name 'rollout-*.jsonl' -type f -print0 |
    xargs -0 ls -t |
    head
  Then inspect its first turn_context:
  jq -c '
    select(.type == "turn_context") |
    {
      model: .payload.model,
      effort: .payload.effort,
      sandbox: .payload.sandbox_policy
    }
  ' /path/to/rollout.jsonl | head -n 1

  Expected evidence:

  {
    "model": "gpt-5.6-terra",
    "effort": "high",
    "sandbox": {"type": "read-only"}
  }

  Do not trust:

• The task or agent name
• The custom profile file
• The worker’s self-reported model
• The coordinator’s telemetry
• Pricing alone

  Persisted turn_context is the decisive control-plane evidence. In my case, Tokenscale subsequently showed Terra’s lower price as
  independent billing confirmation.

  ## 3. Run the real bounded worker

  Put the worker’s instructions in a task packet:

  codex exec \
    --strict-config \
    --model gpt-5.6-terra \
    -c 'model_reasoning_effort="high"' \
    -c 'sqlite_home="/tmp/codex-terra-worker-state"' \
    --sandbox workspace-write \
    --cd /path/to/repository \
    --output-last-message /tmp/terra-worker-result.md \

• < /tmp/terra-worker-task.md

  The task packet should specify:

• Exact read and write scope
• Files or owners it may change
• Required tests and proof
• Explicit exclusions
• Stop conditions
• No commit/push unless deliberately authorized
• No recursive delegation unless intended

  ## 4. Reuse the worker’s warmed context

  Once a Terra worker has learned a bounded subsystem, resume it instead of repeatedly creating cold workers:

  codex exec resume \
    --strict-config \
    --model gpt-5.6-terra \
    -c 'model_reasoning_effort="high"' \
    -c 'sqlite_home="/tmp/codex-terra-worker-state"' \
    --output-last-message /tmp/terra-followup-result.md \
    THREAD_ID \

• < /tmp/terra-followup-task.md

  The resumed turn should again produce a matching persisted turn_context.

  ## Important boundaries

• This is a workaround, not a repair for .codex/agents profile selection.
• Canary every model/effort combination before relying on it.
• If the requested allocation is unavailable or telemetry differs, wait—do not silently fall back.
• A managed environment may require approval to initialize the nested Codex client. Do not bypass its security policy.
• Keep Sol xhigh for genuinely difficult architecture, security, schema, contradiction, or final-review checkpoints. Terra is

    better suited to bounded execution and validation.

• Each worker consumes its own tokens, but explicit selection prevents every lightweight task from silently running as Sol High

I can reproduce this with a user-global custom agent on Codex CLI 0.144.1, macOS arm64. A fresh process does not fix it, and the custom agent's instructions and context restrictions are not applied.

Global agent configuration

I created a regular, non-symlinked file at ~/.codex/agents/scout.toml with:

name = "scout"
description = "Read-only evidence scout for repository mapping and primary-source collection."
model = "gpt-5.6-terra"
model_reasoning_effort = "low"
sandbox_mode = "read-only"
mcp_servers = {}
skills.config = []

developer_instructions = """
You are Scout, a read-only evidence specialist working for a parent Codex agent.
# Detailed mission, boundaries, evidence workflow, stop conditions and receipt contract followed
"""

The TOML parses successfully and codex doctor reports zero configuration failures.

Reproduction

I started a new parent process after the agent file existed:

codex exec \
  --json \
  --model gpt-5.6-terra \
  -c 'model_reasoning_effort="low"' \
  --sandbox read-only \
  --cd /tmp/codex-scout-discovery-test \
  --skip-git-repo-check \
  'Use the custom agent named scout. Spawn exactly one scout with no inherited conversation. Do not use another agent type.'

I repeated the test three ways:

1. Stable default runtime
2. --enable use_agent_identity
3. --ignore-user-config --enable multi_agent_v2 --enable use_agent_identity

The third variant required --ignore-user-config because multi_agent_v2 otherwise rejected the existing [agents] max_threads setting with:

agents.max_threads cannot be set when features.multi_agent_v2 is enabled

Actual result

All three runs spawned a child whose path was named /root/scout, but all three persisted child transcripts recorded:

agent_role: null

In every child:

• Scout's unique developer_instructions were absent
• the full global skill catalog was still present despite skills.config = []
• the requested custom context restrictions were therefore not applied
• the child used gpt-5.6-terra / low only because the parent was deliberately pinned to those settings

The stable spawn_agent call recorded in the parent transcript accepts only:

task_name
message
fork_turns

There is no agent_type, role, profile or custom-agent identifier. task_name = "scout" labels the child path; it does not select ~/.codex/agents/scout.toml.

This also proves that restarting Codex is not a workaround: every test used a newly started process created after the global agent file existed.

Impact

This is not a cosmetic role-selection issue. It makes model and cost routing impossible and silently defeats context isolation.

Before identifying the failure, three children intended for cheaper read-heavy work silently ran as gpt-5.6-sol / high. Their persisted cumulative totals were:

619,281
964,829
459,427
---------
2,043,537 total tokens
1,818,624 cached input tokens

Those transcript totals are not necessarily billable-token totals, but they demonstrate the scale of the silent substitution. The child names looked correct while the actual runtime configuration was wrong.

Required behavior

1. spawn_agent must expose an explicit custom-agent identifier such as agent_type
2. The runtime must apply the selected agent's model, effort, sandbox, developer instructions, MCP configuration and skill configuration
3. An unknown or unavailable agent must fail closed instead of silently spawning an inherited default child
4. Spawn metadata and UI must show the actual role, model and reasoning effort before substantive work begins
5. Regression coverage must include user-global ~/.codex/agents/*.toml from tool-backed CLI and app sessions

The current behavior makes documented custom agents unusable as reliable workflow infrastructure.

I can reproduce this on macOS with Codex Desktop using multi_agent_version = v2 and Codex CLI 0.144.1.

I tested all currently documented and previously suggested configuration paths:

• a project-scoped agent under .codex/agents/
• a user-global agent under ~/.codex/agents/
• the older user-global [agents.<name>] registry with config_file
• a completely fresh codex exec --strict-config process started after the global files existed
• fork_turns: "none" to rule out full-history inheritance conflicts

The global registry configuration was accepted by --strict-config, but the exposed spawn_agent schema still contained only:

task_name
message
fork_turns

A direct request to use agent_type failed with:

spawn_agent does not support an agent_type parameter

Using the configured agent name as task_name spawned a generic child. Persisted child metadata showed:

{
  "agent_role": null,
  "agent_path": "/root/<requested-name>",
  "model": "gpt-5.6-sol",
  "effort": "medium",
  "sandbox": {"type": "danger-full-access"},
  "developer_instructions": null
}

The requested custom profile specified gpt-5.6-terra, a different reasoning effort, read-only sandboxing, and unique developer instructions. None of these settings were applied.

As a control, I started a fresh parent explicitly pinned to gpt-5.6-terra, medium reasoning, and read-only sandboxing. A generic child spawned with fork_turns: "none" inherited exactly those parent settings. This confirms that the current behavior is silent parent inheritance, not custom-agent resolution.

This also rules out restarting Codex or moving the agent to the global registry as a workaround in the current V2 tool surface. task_name only labels the child path.

It would help if spawn_agent either:

1. exposed an explicit agent_type or custom-agent identifier,
2. resolved a registered custom agent from the requested name, or
3. failed closed instead of silently spawning an inherited generic child.

The spawn result and UI should also report the effective role, model, reasoning effort, and sandbox before the child starts substantive work.

I am seeing this regression in the Codex desktop app as well, with additional before/after evidence.

Previously, the spawned-agent tool exposed an agent_type parameter. A call with agent_type="atlassian" successfully selected my project-local .codex/agents/atlassian.toml, started the MCP server configured under mcp_servers.alm-jira, and exposed jira_add_comment to that child agent.

In the current desktop runtime, the collaboration spawn_agent interface no longer exposes agent_type or another custom-agent selector. It exposes only a task_name used to name the spawned task. Spawning a worker and instructing it to read .codex/agents/atlassian.toml does not apply that file as a configuration layer, so its agent-scoped MCP server is absent from the child tool catalog.

I verified that this is not an invalid TOML, missing executable, authentication, or MCP-server problem: /Users/kmizuta/.local/bin/mcp-atlassian exists, and manually starting it with the arguments from atlassian.toml successfully advertises and executes jira_add_comment. The failure is specifically that the current spawn interface cannot select the named custom agent and therefore never loads its MCP configuration.

Moving these MCP servers into the parent project config is not a viable workaround for users with many specialist MCP servers: loading all servers globally causes startup overhead, performance problems, disconnects, and removes the intended per-agent tool isolation.

Expected behavior: restore a custom-agent selector equivalent to agent_type="atlassian" so project-local .codex/agents/*.toml files are applied as configuration layers, including their agent-specific mcp_servers.

Confirming this on Codex Desktop for Windows in a tool-backed session.

Valid custom-agent TOML files exist under ~/.codex/agents/, but the exposed spawn_agent tool accepts only task_name, message, and fork_turns. It provides no agent_type, custom-agent name, model, or reasoning parameters.

This means a skill can require a named custom agent, but the runtime cannot verifiably select it. Prompting a generic subagent to imitate that role is not equivalent (and the expensive solution sol will silently select).

I can reproduce a more severe variant on Codex Desktop for Windows.

Environment

• Codex Desktop 26.715.2305.0
• Windows x64
• Selected model: gpt-5.6-sol
• Fresh task in a trusted local workspace
• Multiple valid project-scoped .codex/agents/*.toml role files. The TOML files parse successfully and each role has a non-empty name, description, role-specific model/reasoning settings, and developer instructions.

Actual result

In the affected fresh Desktop task, the collaboration spawn surface is missing entirely. This is not only a missing agent_type parameter: neither spawn_agent nor wait_agent exists in the runtime tool registry.

I ran this capability canary:

Do not perform project work. Call the real direct spawn_agent with a configured project-local agent type and fork_turns="none", then call the real wait_agent. Report the effective role, model, and reasoning effort from runtime metadata. If the tools or agent_type are unavailable, stop and report the exact available schema/error.

The task inspected the complete available tool registry. Searching it for /spawn_agent|wait_agent/ returned:

[]

Therefore:

• no spawn_agent call event was emitted;
• no child task was created;
• wait_agent could not be called;
• no effective role/model/reasoning metadata existed.

This differs from reports where spawn_agent is present but only exposes task_name, message, and fork_turns. In this Windows Desktop case, the whole direct collaboration tool family is absent.

Reproduction

1. Create a trusted workspace with one or more valid project-local roles under .codex/agents/.
2. Fully restart Codex Desktop.
3. Open the workspace and create a fresh task with GPT-5.6 Sol.
4. Ask the task to call the real direct spawn_agent for a configured role using fork_turns="none", then call wait_agent.
5. Ask it to stop and inspect the full tool registry if the call cannot be made.
6. Observe that both direct tools are absent and the registry search returns an empty result.

I repeated this with fresh tasks after restarting the app.

Expected result

• spawn_agent and wait_agent should be available in a tool-backed Desktop task when project-local roles are configured.
• spawn_agent should expose agent_type and apply the selected .codex/agents/*.toml profile.
• The child metadata/UI should show the effective role, model, reasoning effort, and sandbox.
• If the runtime cannot load the requested role, it should fail closed with an explicit diagnostic rather than silently omitting the complete tool family.

PR #33572 is already merged and its commit is included in Codex CLI 0.145.0-alpha.18, but the direct collaboration surface is still absent in this Desktop runtime.

I can reproduce a named custom-agent selection gap in the VS Code extension with its bundled stable Codex build.

Environment

• VS Code extension: openai.chatgpt 26.707.91948
• Bundled Codex: codex-cli 0.144.5
• Surface: VS Code Server on Linux x86_64
• Selected parent model: gpt-5.6-sol

Project setup

• .codex/agents/researcher.toml defines a researcher agent with its own model, reasoning effort, read-only sandbox, and developer instructions.
• .codex/agents/reviewer.toml defines a reviewer agent with its own model, reasoning effort, and developer instructions.
• The project orchestrator explicitly requires delegating research to researcher and independent confirmation to reviewer.
• .codex/config.toml enables multi-agent support. The researcher and reviewer are intentionally standalone project-agent files.

This setup follows the current Subagents documentation, which documents project agents as standalone TOML files under .codex/agents/ and says Codex automatically discovers them. A separate [agents.<name>] registration is not documented as required for these project-scoped files.

Reproduction

1. Start a fresh Codex task in the trusted project workspace.
2. Ask the orchestrator:

> Diagnostic only. Delegate to the researcher reading package.json and reporting the package name. Then delegate to the reviewer independently confirming that result. Wait for both agents and report which agent types were used.

1. Inspect the exposed spawn_agent interface and the resulting child task metadata.

Actual behavior

The exposed spawn_agent schema accepts only:

task_name
message
fork_turns

There is no agent_type, custom-agent identifier, model, or reasoning-effort parameter.

The run created generic canonical task names such as /root/researcher_package_name and /root/reviewer_package_name. The parent later clarified that these were generic child agents prompted to act as researcher and reviewer, not verified invocations of .codex/agents/researcher.toml and .codex/agents/reviewer.toml.

The available runtime metadata therefore did not establish that either child's configured model, reasoning effort, sandbox, or developer instructions had been applied. This report does not claim that those effective child settings were captured; the problem is that the configured role could neither be explicitly selected through the exposed tool schema nor verified afterward.

Expected behavior

• Standalone project agents under .codex/agents/*.toml are discovered as documented.
• spawn_agent can explicitly select a named custom agent.
• The child applies that agent's TOML configuration.
• Runtime metadata or the UI reports the effective agent type and configuration.
• If a requested role cannot be resolved, spawning fails explicitly instead of silently substituting a generic inherited child.

This appears related to the MultiAgentV2/tool-schema behavior discussed in #31097.

PR #33572 also appears relevant because it adds agent_type when configured roles are available. It was merged after stable 0.144.5. I have not tested a VS Code extension build containing that change, so I cannot confirm whether it fixes standalone project-agent discovery and selection in the extension.