›_ Codex Issues
Codex Issues / #26408

Project-scoped custom subagent in `.codex/agents` is advertised but cannot be spawned

Open 💬 2 comments Opened Jun 4, 2026 by kmizuta
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What version of the Codex App are you using (From “About Codex” dialog)?

CLI: codex-cli 0.137.0 Codex app bundled CLI: codex-cli 0.136.0-alpha.2

What subscription do you have?

Plan through my company - oracle Corporation

What platform is your computer?

macOS 26.5.0, Apple Silicon / aarch64

What issue are you seeing?

A trusted project-scoped custom agent under .codex/agents/ is visible/advertised as an available spawn_agent role, but attempting to spawn it fails with:

agent type is currently not available

The same TOML agent definition works when copied to ~/.codex/agents/ and renamed, so the TOML appears valid. The failure seems specific to project-scoped custom agent loading/spawning.

What steps can reproduce the bug?

Feedback ID: 019e9295-9d3b-74a2-81d4-7093d8cf9796

  1. In a trusted project, create .codex/agents/oracle-devtools.toml.
  1. Use a valid custom-agent TOML, for example:

name = "oracle-devtools"
description = "Specialist for BugDB and OraReview workflows backed by devvm-hosted MCP servers."
developer_instructions = """
You are the Oracle internal development-tools specialist.
"""

  1. Confirm the project is trusted in ~/.codex/config.toml:

[projects."/Users/kmizuta/Personal Assistant"]
trust_level = "trusted"

  1. Start Codex from the project root:

cd "/Users/kmizuta/Personal Assistant"
codex

  1. Ask Codex to spawn the project-scoped custom agent:

spawn_agent(agent_type="oracle-devtools")

  1. Observe the failure:

agent type is currently not available

  1. Copy the same TOML to ~/.codex/agents/, rename the file and name property, then start Codex again.
  1. The global custom agent can be launched successfully from both ~ and /Users/kmizuta/Personal Assistant.

What is the expected behavior?

A trusted project-scoped custom agent defined under .codex/agents/*.toml should be spawnable from that trusted project, the same way a global custom agent under ~/.codex/agents/*.toml is spawnable.

Additional information

Project root:

/Users/kmizuta/Personal Assistant

Project agent file:

/Users/kmizuta/Personal Assistant/.codex/agents/oracle-devtools.toml

Relevant local config:

/Users/kmizuta/Personal Assistant/.codex/config.toml
/Users/kmizuta/.codex/config.toml

The project AGENTS.md is loaded in the session, and project skills are visible, but the project-scoped custom agent cannot be spawned.

codex doctor also reports the project as detected and trusted, but only lists ~/.codex/config.toml as the loaded config file. There may be a mismatch between project context loading and project .codex/agents loading in the app/runtime surface.

View original on GitHub ↗

2 Comments

github-actions[bot] contributor · 2 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #26363

Powered by Codex Action

umiskky · 2 months ago

I investigated this locally while debugging the v0.137.0 subagent regression and wanted to add a narrower root-cause/patch outline.

There seem to be two related but distinct behaviors:

  1. The v1 spawn_agent schema missing agent_type in v0.137.0 is covered by #26363 / #26599. In current main, the v1 path no longer hides agent_type, model, and reasoning_effort.
  1. Project-scoped role availability can still be stale because Config.agent_roles is loaded when the session config is created, while spawn_agent later validates agent_type against that in-memory map. If a trusted project .codex/config.toml or .codex/agents/*.toml changes after the session starts, or if the app/runtime path advertises project agents from a fresher project context than the spawn handler config, the spawn handler can still reject the role with agent type is currently not available.

A minimal patch that worked locally was:

  • add a Config helper that reloads non-session config layers from the current codex_home + cwd, preserving the active session override layers;
  • call agent_roles::load_agent_roles(...) on that fresh layer stack;
  • in both v1 and v2 spawn_agent handlers, refresh config.agent_roles immediately before apply_role_to_config(...);
  • keep failures non-fatal and log a warning, so transient config-read errors do not break generic spawn.

Regression coverage that was useful:

  • create a temp trusted project with no role in the initial session config;
  • write a new project-scoped custom agent/config after session config creation;
  • call spawn_agent(agent_type=...);
  • assert the spawn resolves the new role and applies its model/reasoning config.

This is separate from the already-merged v1 schema visibility fix in #26599. That PR makes agent_type callable again; the refresh-before-spawn behavior makes project-scoped role changes and app/runtime project-role discovery line up with the actual spawn handler.