codex - 💡(How to fix) Fix Breaking config change: `:project_roots` no longer works in recent Codex releases

What version of Codex CLI is running?

codex-cli 0.132.0

What subscription do you have?

Business

Which model were you using?

gpt-5.4

What platform is your computer?

Darwin 25.4.0 arm64 arm

What issue are you seeing?

A recent Codex release appears to have made a breaking change to the config permission token for project-scoped filesystem access.

Previously, configs and docs used :project_roots, but recent Codex behavior now rejects that token and expects :workspace_roots instead.

Observed behavior

The Codex TUI warns:

Configured filesystem path `:project_roots` is not recognized by this version of Codex and will be ignored.

The desktop app does not seem to warn at all.

In either case, the intended project-root write access is not granted.

What steps can reproduce the bug?

A config like this no longer works in current releases:

[permissions.default-dev.filesystem]
":project_roots" = "write"

What is the expected behavior?

This should not have been a breaking config change without a compatibility path.

At minimum, one of these should happen:

1. Preserve :project_roots as a supported alias for backward compatibility.
2. Emit a direct migration error/warning that explicitly says to replace :project_roots with :workspace_roots.
3. Call out the breaking change prominently in release notes and migration guidance.

Additional information

Why this matters This can break existing Codex setups that were previously valid. A config may continue to load, but the relevant filesystem permission is ignored, leading to unrelated-looking failures later when commands no longer have the expected project-root access.

Because the old key is ignored rather than rejected with a clear migration message, this is harder to understand than it should be.

Related context

• PR #22624 renamed the config-facing key from :project_roots to :workspace_roots.
• Current docs now appear to match the new behavior, but that still leaves existing user configs broken.

Suggested resolution

• Restore :project_roots as a compatibility alias, or
• add an explicit migration diagnostic that names :workspace_roots as the replacement, and
• document the breaking change prominently for users upgrading Codex.