Support symlinks for custom agent TOMLS

What version of Codex CLI is running?

codex-cli 0.116.0

What subscription do you have?

Pro

Which model were you using?

any

What platform is your computer?

Linux 6.18.16-1-lts x86_64

What terminal emulator and version are you using (if applicable)?

Kitty

What issue are you seeing?

Custom agent role files placed under ~/.codex/agents/ were not discovered when those files were symlinks, even though the same files worked once replaced with direct copies.

With symlinked files in ~/.codex/agents/, spawn_agent(agent_type="scout") behaved as if only the built-in roles existed and repeatedly refused with messages equivalent to:

• only default, explorer, and worker are available
• cannot spawn a custom subagent named scout

After replacing those same symlinked agent files with byte-for-byte copied files in the same directory, Codex immediately began recognizing the custom role and attempted to spawn it.

There was one separate follow-up issue in my specific setup: the scout role used gpt-5.3-codex-spark, and that required model_reasoning_summary = "none" plus model_supports_reasoning_summaries = false. Once those Spark-specific settings were added, the copied-file version of the role spawned successfully and returned the expected result.

So the likely bug is not custom-agent support in general, but that symlinked custom agent TOMLs under ~/.codex/agents/ are not treated the same as regular files.

What steps can reproduce the bug?

1. Create a valid custom agent file outside ~/.codex, for example /tmp/scout.toml:

``toml
name = "scout"
description = "Repro scout"
developer_instructions = "Reply with exactly: CUSTOM_SCOUT_OK"
model = "gpt-5.4"
model_reasoning_effort = "medium"
``

1. Symlink it into ~/.codex/agents/:

``bash
mkdir -p ~/.codex/agents
ln -sf /tmp/scout.toml ~/.codex/agents/scout.toml
``

1. Run:

``bash
codex exec --json "Spawn the custom subagent named scout. Ask it to reply with exactly: CUSTOM_SCOUT_OK. If that fails, say exactly why in one sentence."
``

1. Observe that Codex reports that only built-in roles are available, or otherwise behaves as if scout does not exist.

1. Replace the symlink with a direct copy of the exact same file contents:

``bash
rm ~/.codex/agents/scout.toml
cp /tmp/scout.toml ~/.codex/agents/scout.toml
``

1. Run the exact same codex exec command again.

1. Observe that the custom role is now recognized and used.

Control case from a real setup:

• ~/.codex/agents/scout.toml as a symlink to a repo-managed file was not recognized.
• The same file copied into ~/.codex/agents/scout.toml was recognized immediately.
• In that real setup, a separate Spark-model incompatibility had to be fixed after discovery started working, but that was independent of the symlink-vs-copy behavior.

What is the expected behavior?

If custom agent TOMLs under ~/.codex/agents/ are supported, symlinked files should be discovered and loaded the same way as regular files, assuming the symlink resolves to a valid readable TOML file.

If symlinked files are intentionally unsupported, the docs should say so explicitly and the CLI should ideally emit a direct startup warning instead of silently behaving as if the custom role does not exist.

Additional information

Relevant docs currently imply that custom agents are discovered from ~/.codex/agents/*.toml without calling out symlink restrictions:

• https://developers.openai.com/codex/subagents
• https://developers.openai.com/codex/config-reference

Related but different issues:

• #15250: tool-backed/runtime mismatch for custom agents
• #14579: custom agent roles from project .codex/config.toml not available to spawn_agent
• #14451: invalid agent role TOML loading/validation behavior

This report is specifically about the home-level ~/.codex/agents/ discovery path treating symlinked role files differently from copied files.