Why

--profile-v2 lets runtime entry points run with a named user profile file while still inheriting the normal base user config. This supports launchers and workflows that need profile-specific defaults, MCP/plugin settings, or config write targets without duplicating the whole config.toml into a separate file.

The selected profile is intentionally a layer, not a replacement: --profile-v2 work loads $CODEX_HOME/config.toml first and then $CODEX_HOME/work.config.toml on top.

What Changed

• Added the shared --profile-v2 <name> CLI option and plain-name validation for $CODEX_HOME/<name>.config.toml.
• Threaded the selected profile config through the TUI, exec, review, resume, fork, and debug prompt-input runtime paths.
• Extended config loading so the base user config remains in the layer stack and the selected profile becomes the active writable user layer.
• Updated user-config writes from the TUI, config service, and MCP tool approval persistence to write to the selected profile config when one is active.
• Made plugin, marketplace, and MCP reads use the merged user config so base and profile layers both participate.
• Updated config hot reload to refresh both the base user config and selected profile layer.

Limits

--profile-v2 is still rejected for config-management subcommands such as feature, MCP, or marketplace edits. Those commands stay tied to the base config.toml for now.

A few background or adjacent write paths are still not fully profile-aware and may continue to update base config.toml or global state:

• configured marketplace auto-upgrade metadata
• automatic MCP dependency installs from skills
• remote plugin sync or uninstall config edits
• personality migration marker/default writes

Verification

• Added targeted unit coverage for resolve_profile_v2_config_path, user-layer merging, selected profile writes, config service writes, session hot reload, plugin config merging, and MCP tool approval persistence.