Clarify the interaction between `allow_login_shell` and `shell_environment_policy` in documentation

What is the type of issue?

Documentation is confusing

What is the issue?

Description

While configuring shell_environment_policy, I noticed a potentially confusing interaction with allow_login_shell.

shell_environment_policy is documented as controlling the environment variables passed to subprocesses (for example through inherit, exclude, include_only, and set). However, when allow_login_shell = true — which appears to be the default — commands may be executed through a login shell

In that case, the shell will load user profile files such as:

• ~/.bash_profile
• ~/.profile
• ~/.zprofile
• ~/.zshrc

These files often contain export statements that modify or introduce additional environment variables. As a result, environment variables that were intentionally filtered out by shell_environment_policy can be reintroduced by the shell profile after the process starts.

For example, even with a restrictive configuration like:

[shell_environment_policy]
inherit = "core"
include_only = [xxx]

users may still observe many additional variables inside the executed shell environment because they are added by the login shell initialization scripts.

Since allow_login_shell = true is the default, this behavior may cause users to believe that shell_environment_policy is not working as expected.

Suggested documentation improvement

It would be helpful if the documentation explicitly described that:

• shell_environment_policy controls the initial environment passed to the subprocess.
• When allow_login_shell = true, the login shell may modify the environment by loading profile scripts.
• Therefore, some environment restrictions configured in shell_environment_policy may appear ineffective if the login shell reintroduces variables.
• The above information could be documented to make this behavior clearer to users on https://developers.openai.com/codex/config-advanced#shell-environment-policy

A short note explaining this interaction would help users better understand and correctly configure environment isolation.

Where did you find it?

_No response_