Allow Specifying [shell_environment_policy.set] for Subagents

What variant of Codex are you using?

CLI

What feature would you like to see?

Description

As a codex user with a custom workflow definition with various subagents that the root coordinator can spawn, I would like to be able to override shell environment variables that agents are provided with via their agent.toml configuration.

Use Cases

• Granular Access Control and Security
  • The root coordinator might have high-level administrative keys, while individual sub-agents are scoped to restricted API keys or tokens specific to their domain, like database access or third-party integrations. This enforces the principle of least privilege.
• Isolated Environments and Sandboxing
  • A code execution or testing sub-agent can be pointed to a staging or sandbox environment variable, preventing accidental changes to the root agent's production context.
• Context and Persona Customization
  • Overriding variables like output directories or log verbosity per agent allows you to run specialized agents without polluting the global environment settings.

Example

In this generic example, suppose we have either a script that switches behavior based on the value of a MACHINE_ACTOR environment variable or some sort of service with different machine user accounts that have different permissions.

~/.codex/config.toml

[shell_environment_policy.set]
MACHINE_ACTOR = "coordinator"
SOME_SERVICE_API_TOKEN = "<token with some elevated permissions>"

~/.codex/agents/reviewer.toml

[shell_environment_policy.set]
# Spawned reviewer agents should have a different profile for some service
MACHINE_ACTOR = "reviewer"
SOME_SERVICE_API_TOKEN = "<token with subset of coordinator permissions>"

Additional information

No response

Start by tracing how ~/.codex/config.toml and ~/.codex/agents/reviewer.toml are parsed and how shell_environment_policy is applied when a subagent is spawned. Implement per-agent values that override the coordinator's environment for that subagent without changing the coordinator's variables, then verify the example variables are scoped as described.