0.149.0 rejects symlinked custom-agent role files with misleading "agent type is currently not available"

What version of Codex is running?

• Failing CLI/app-server: codex-cli 0.149.0
• Working control: codex-cli 0.148.0

What platform and surface are affected?

• Remote Linux development host
• Interactive CLI and an unmanaged remote app-server
• The Desktop app itself was not downgraded
• ChatGPT-authenticated Codex session
• The installed custom-agent configuration was unchanged between the two tests

Summary

Codex 0.149.0 rejects configured custom-agent role files installed as symbolic links and returns only:

agent type is currently not available

The same symlink-based installation works after downgrading only the remote CLI/app-server to 0.148.0 and restarting it.

The affected installation intentionally links the individual role files from a version-controlled configuration repository into ~/.codex/agents/. All affected roles are symlinks, including implementer, code-mapper, and the other custom profiles.

Example sanitized layout:

~/.codex/agents/implementer.toml -> <configuration-repository>/codex-home/agents/implementer.toml
~/.codex/agents/code-mapper.toml -> <configuration-repository>/codex-home/agents/code-mapper.toml

No role contents, account secrets, or private repository paths are included here.

Likely root cause

This now appears directly related to #39299, merged into the 0.149.0 release:

• PR: https://github.com/openai/codex/pull/39299
• Commit: https://github.com/openai/codex/commit/1a6e07a4febcc0ecfa04464f5e95cb47144cd746

That change explicitly says it will "reject symlinked user role files". It also changed custom-role reading from ordinary tokio::fs::read_to_string() to read_sensitive_file_to_string() and added the test:

apply_role_rejects_symlinked_role_file

The test expects the public error:

agent type is currently not available

This matches the observed 0.149.0 behavior exactly. The symlink restriction may be an intentional security boundary, but it creates an undocumented compatibility break for installations that previously managed custom-agent files through symlinks. The generic error also hides the actionable cause.

A second, distinct 0.149.0 custom-role regression associated with the bounded-role work is tracked in #40042:

• https://github.com/openai/codex/issues/40042

#40042 concerns model_instructions_file being ignored and is not a duplicate of this report, but both appear related to the role-loading changes introduced by #39299.

Steps to reproduce

1. Create a valid custom-agent role file outside ~/.codex/agents/.

2. Symlink it into the normal custom-agent location:

   ln -s /absolute/path/to/implementer.toml ~/.codex/agents/implementer.toml
   

3. Register/use that role through the normal Codex custom-agent configuration.

4. Start a fresh Codex CLI or app-server-backed task on 0.149.0.

5. Attempt to spawn it:

   agent_type = "implementer"
   fork_turns = "none"
   

6. Observe:

   agent type is currently not available
   

7. Substitute Codex CLI/app-server 0.148.0 without changing the role symlink or configuration.

8. Fully restart the app-server and start a fresh task.

9. Repeat the same read-only spawn probe.

Expected behavior

At minimum, Codex should return an actionable error explaining that symlinked custom-agent role files are not permitted.

Preferably, one of these contracts should be explicit:

1. Safely allow role symlinks whose resolved targets satisfy the intended trust boundary; or
2. Document that custom-agent role files must be physical files and reject symlinks during configuration loading with a clear path-safe warning.

The current behavior makes a discovered/configured role look generically unavailable and gives no indication that copying the same TOML into place may resolve it.

Actual behavior

In 0.149.0, the configured role is rejected before the child starts:

agent type is currently not available

The underlying symlink rejection is only visible in source/tests, not in the user-facing error.

Controlled A/B evidence

Fresh task	cli_version recorded in rollout	Result
01a02a68-2edd-7d91-987b-acfd76e53f90	0.149.0	Four symlink-installed configured-role spawn attempts were rejected with the exact error above
01a02a6c-46a7-7101-9dc3-ba7f407ffb83	0.148.0	Successfully spawned custom implementer, custom implementation_lead, and a nested custom implementer using fork_turns = "none"
01a0250f-f83e-70e3-b2ee-f8a312e05999	0.148.0	Historical successful custom-role workflow using the same installation style

The 0.148.0 preflight was run only after both the CLI and the restarted remote app-server reported 0.148.0.

Sanitized rollout evidence:

fresh task 01a02a68-2edd-7d91-987b-acfd76e53f90
cli_version: 0.149.0
spawn result: agent type is currently not available

fresh task 01a02a6c-46a7-7101-9dc3-ba7f407ffb83
cli_version: 0.148.0
custom implementer: started
custom implementation_lead: started
nested custom implementer with fork_turns="none": started

All probes were read-only. No repository, release, configuration, or CODEX_HOME files were changed during the probes.

Related, but distinct reports

• #26408 has the same public error text, but concerns project-scoped .codex/agents discovery on 0.137.0.
• #20077 concerns full-history fork/override incompatibility. The successful nested control explicitly used fork_turns = "none".
• #26868 concerns a child being created without its profile being applied. Here, 0.149.0 rejects the role before a child starts.
• #40042 concerns a different bounded-role regression where model_instructions_file is silently ignored.

Suggested resolution

• Surface a specific privacy-safe error such as:

  custom agent role file must be a regular file; symbolic links are not supported
  

• Document the symlink restriction and the supported installation method in the custom-agent documentation.

• Consider allowing symlinks after resolving and validating the target against an explicit trust boundary.

• Add release-note coverage for the 0.149.0 compatibility change.

• Keep a regression test for both the security rule and the user-facing diagnostic.

Start with the apply_role_rejects_symlinked_role_file test and the custom-role loading change from PR #39299, especially the move to read_sensitive_file_to_string(). Compare the 0.149.0 behavior with the 0.148.0 control. Done means the symlink restriction has an explicit user-facing diagnostic, documentation or release-note coverage, and regression coverage for the security rule and diagnostic.