Clarifying Codex command environment contracts #26901

royenheart · 2026-06-07T18:39:13Z

royenheart
Jun 7, 2026

1. Problem Summary

I would like to collect several related Codex command-environment threads and
discuss what contract would make this behavior easier to reason about.

This area is currently split across many issue, PR, and Discussion threads:

Shell startup semantics. shell_environment_policy controls the
initial environment map passed to command subprocesses, but command
execution can still run through a login shell. That shell may read profile
files and rewrite PATH, activate a different Python, reintroduce filtered
variables, or otherwise mutate the environment after Codex has constructed
it. This is the common thread behind Bug Report: PATH ordering is mutated when Codex shells launch via bash -lc #4210, Codex runs commands via bash --login and drops per-project env #4843, Login shells override inherited PATH in curated environments; need configurable default #8922, Proposal: Add [shell] default_login config to fix PATH clobbering in curated environments #11952, feat: add config allow_login_shell #12312,
and Clarify the interaction between allow_login_shell and shell_environment_policy in documentation #14774.
Execution process provenance. The environment inherited by a command is
not always the environment of the terminal that just launched the visible UI.
It can come from the launcher process, a reused local app-server daemon, or a
remote exec server. Build remote exec env from exec-server policy #17216 fixed one remote case by deriving remote exec env
from the exec server; Fix: TUI starting in wrong CWD #23538 fixed an adjacent local daemon cwd issue; app-server local command execution lacks a cwd-scoped environment contract #24638
remains the open local env-provenance issue.
Local/worktree setup lifecycle. Codex local environments and setup
scripts are lifecycle mechanisms, not durable command-env providers. A setup
script can prepare files or run tools, but shell-local state such as
export FOO=bar does not automatically become part of later shell commands.
Set environment variable through Local environments #10543, New handoff to worktree doesn't use environments #18981, and Codex App Remote SSH new worktree does not run local environment setup script #23648 show related setup/worktree drift.
Remote SSH and worktree boundaries. In remote workflows, the relevant
filesystem, shell, setup script, skills, and dependency environment may live
on the remote host rather than the local Desktop/IDE client. Improve Codex Desktop support for SSH remote workspaces #21509 asks for
clearer Remote SSH workspace bootstrap; Codex App Remote SSH new worktree does not discover repo-local skills #22545 and Codex App Remote SSH new worktree does not run local environment setup script #23648 show that new
remote worktree flows can lose repo-local context/setup.
IDE-selected interpreters. IDEs can have their own notion of the active
project interpreter or virtual environment. Codex ignores VSCode selected Python interpreter / virtual environment #23642 reports that VS Code's
selected Python interpreter is not reflected in Codex command execution,
which is another example of "workspace looks right, command env is wrong."
SessionStart hook overlays. Hooks can currently contribute context,
but current main does not expose a supported structured env overlay
from SessionStart. Add CODEX_ENV_FILE env persistence #24468, Add CODEX_ENV_FILE hook persistence #24650, Add CODEX_ENV_FILE for SessionStart hooks #24805, and Add SessionStart hook environment overlays #25364 explored env-file and
structured-overlay designs, but none of those changes are merged into main.
First-class project command environment providers. Add first-class project command environments for agent shell execution #25452 is the
clearest open issue for declaring that commands in a workspace should run
inside a project environment. It intentionally frames tools such as direnv,
development shells, language version managers, and containers as examples of
a generic provider problem rather than one-off command-prefix instructions.

It would be useful to discuss a command-environment contract that can answer:

For this workspace/thread/turn, where do shell commands run, what environment
do they inherit, how was that environment produced, and is that visible to the
agent/user?

The common symptom is simple: the cwd is correct, but python, pytest,
cargo, pnpm, kubectl, or a repo-local helper resolves from the wrong
environment.

2. Motivating Examples

The examples below use anonymized local paths and environment names. They are
intended to show the shape of the failure.

2.1 Launcher environment vs login shell

A user starts Codex from a shell where the project Python environment is active:

source /path/to/miniconda3/etc/profile.d/conda.sh
conda activate project-env
printf 'launcher CONDA_DEFAULT_ENV=%s\nlauncher python=%s\n' \
  "$CONDA_DEFAULT_ENV" "$(command -v python)"

The launcher sees:

launcher CONDA_DEFAULT_ENV=project-env
launcher python=/path/to/miniconda3/envs/project-env/bin/python

With the default shell behavior observed in this repro, Codex command execution
used /bin/bash -lc .... On my machine that login shell initialized base,
so the command saw:

base
/path/to/miniconda3/bin/python

Running the same probe with -c allow_login_shell=false changed the command
shell to /bin/bash -c ... and preserved the launcher environment:

project-env
/path/to/miniconda3/envs/project-env/bin/python

This is not just a Python question. It is the same class of issue as PATH
ordering, profile startup, and inherited-env clobbering in #4210, #4843, and
#8922.

Reproduction script:

#!/usr/bin/env bash
set -euo pipefail

# Example:
#   CONDA_SH=/path/to/miniconda3/etc/profile.d/conda.sh \
#   CONDA_ENV=project-env \
#   ./codex-conda-login-shell-repro.sh

CONDA_SH="${CONDA_SH:-/path/to/miniconda3/etc/profile.d/conda.sh}"
CONDA_ENV="${CONDA_ENV:-project-env}"

if [ ! -f "$CONDA_SH" ]; then
  echo "CONDA_SH does not exist: $CONDA_SH" >&2
  echo "Set CONDA_SH=/path/to/conda.sh and CONDA_ENV=your-env-name." >&2
  exit 1
fi

source "$CONDA_SH"
conda activate "$CONDA_ENV"

printf 'launcher CONDA_DEFAULT_ENV=%s\nlauncher python=%s\n' \
  "${CONDA_DEFAULT_ENV:-}" "$(command -v python)"

PROMPT="$(cat <<'EOF'
Run exactly this shell command and report only its stdout:
python -c "import os,sys; print(os.environ.get('CONDA_DEFAULT_ENV')); print(sys.executable)"
EOF
)"

run_probe() {
  codex exec --json --dangerously-bypass-approvals-and-sandbox \
    --skip-git-repo-check --cd /tmp "$@" "$PROMPT" \
    | python3 -c '
import json
import sys

last_output = None
for line in sys.stdin:
    try:
        event = json.loads(line)
    except json.JSONDecodeError:
        continue
    item = event.get("item") or {}
    if event.get("type") == "item.completed" and item.get("type") == "command_execution":
        last_output = item.get("aggregated_output")
    elif event.get("type") == "item.completed" and item.get("type") == "agent_message":
        last_output = item.get("text")

if last_output is not None:
    print(last_output.rstrip())
'
}

printf '\n== default config(allow_login_shell=true) ==\n'
run_probe -c allow_login_shell=true

printf '\n== allow_login_shell=false ==\n'
run_probe -c allow_login_shell=false

2.2 Setup exports do not persist

In a two-command Codex probe, the first command exported a variable and the
second command printed it:

/bin/bash -lc 'export PROJECT_PYTHON=/tmp/from-setup'
/bin/bash -lc 'printf '\''PROJECT_PYTHON=%s\n'\'' "$PROJECT_PYTHON"'

The second command printed:

PROJECT_PYTHON=

This is expected if commands run as separate shell processes, but it means setup
scripts cannot be treated as implicit persistent command environments. If setup
is only setup, Codex needs a separate explicit contract for durable command env.

Reproduction script:

#!/usr/bin/env bash
set -euo pipefail

PROMPT="$(cat <<'EOF'
Use exactly two separate shell command executions.
First command: export PROJECT_PYTHON=/tmp/from-setup.
Second command: printf 'PROJECT_PYTHON=%s\n' "$PROJECT_PYTHON".
Then report only the second command stdout.
EOF
)"

codex exec --json --dangerously-bypass-approvals-and-sandbox \
  --skip-git-repo-check --cd /tmp "$PROMPT" \
  | python3 -c '
import json
import sys

last_output = None
for line in sys.stdin:
    try:
        event = json.loads(line)
    except json.JSONDecodeError:
        continue
    item = event.get("item") or {}
    if event.get("type") == "item.completed" and item.get("type") == "command_execution":
        last_output = item.get("aggregated_output")
    elif event.get("type") == "item.completed" and item.get("type") == "agent_message":
        last_output = item.get("text")

if last_output is not None:
    print(last_output.rstrip())
'

2.3 Workspace cwd is not a project command environment

Setting the cwd to a workspace does not automatically materialize that
workspace's development environment. For example, a project may have:

# .envrc
export CODEX_DIRENV_CASE=from-direnv
export PROJECT_BIN="$PWD/.tools/bin"
export PATH="$PROJECT_BIN:$PATH"

A bare Codex command in that cwd observed empty project variables and did not
find the repo-local helper. The same command wrapped in the provider did:

bare
CODEX_DIRENV_CASE=
PROJECT_BIN=
wrapped
direnv: loading /path/to/workspace/.envrc
CODEX_DIRENV_CASE=from-direnv
PROJECT_BIN=/path/to/workspace/.tools/bin
/path/to/workspace/.tools/bin/project-tool
project-tool-from-direnv

The gap is that the provider step is not represented in the command execution
contract. Today the model or user must remember provider-specific wrappers for
each command. A provider-level contract could make the active project command
environment visible to Codex instead of only appearing inside prompt
instructions.

Reproduction script:

#!/usr/bin/env bash
set -euo pipefail

DIRENV_BIN="${DIRENV_BIN:-$(command -v direnv || true)}"
if [ -z "$DIRENV_BIN" ]; then
  echo "direnv not found; set DIRENV_BIN=/path/to/direnv" >&2
  exit 1
fi

WORKSPACE="$(mktemp -d "${TMPDIR:-/tmp}/codex-direnv-case.XXXXXX")"
cleanup() {
  "$DIRENV_BIN" deny "$WORKSPACE" >/dev/null 2>&1 || true
  rm -rf "$WORKSPACE"
}
trap cleanup EXIT

mkdir -p "$WORKSPACE/.tools/bin"

cat >"$WORKSPACE/.envrc" <<'EOF'
export CODEX_DIRENV_CASE=from-direnv
export PROJECT_BIN="$PWD/.tools/bin"
export PATH="$PROJECT_BIN:$PATH"
EOF

cat >"$WORKSPACE/.tools/bin/project-tool" <<'EOF'
#!/usr/bin/env sh
printf 'project-tool-from-direnv\n'
EOF
chmod +x "$WORKSPACE/.tools/bin/project-tool"

"$DIRENV_BIN" allow "$WORKSPACE" >/dev/null

export DIRENV_BIN
export DIRENV_LOG_FORMAT='direnv: %s'
CODEX_STDERR="$WORKSPACE/codex-stderr.log"

PROMPT="$(cat <<'EOF'
Run exactly this shell command and report only its stdout:
printf 'bare\n'
printf 'CODEX_DIRENV_CASE=%s\n' "$CODEX_DIRENV_CASE"
printf 'PROJECT_BIN=%s\n' "$PROJECT_BIN"
command -v project-tool || true
printf 'wrapped\n'
"$DIRENV_BIN" exec . sh -c 'printf "CODEX_DIRENV_CASE=%s\n" "$CODEX_DIRENV_CASE"; printf "PROJECT_BIN=%s\n" "$PROJECT_BIN"; command -v project-tool; project-tool'
EOF
)"

if ! codex exec --json --dangerously-bypass-approvals-and-sandbox \
  --skip-git-repo-check --cd "$WORKSPACE" "$PROMPT" \
  2>"$CODEX_STDERR" \
  | python3 -c '
import json
import sys

last_output = None
for line in sys.stdin:
    try:
        event = json.loads(line)
    except json.JSONDecodeError:
        continue
    item = event.get("item") or {}
    if event.get("type") == "item.completed" and item.get("type") == "command_execution":
        last_output = item.get("aggregated_output")
    elif event.get("type") == "item.completed" and item.get("type") == "agent_message":
        last_output = item.get("text")

if last_output is not None:
    print(last_output.rstrip())
'
then
  echo "codex exec failed; stderr follows:" >&2
  cat "$CODEX_STDERR" >&2
  exit 1
fi

2.4 Local app-server env provenance

#24638 shows that visually similar local TUI launches can observe different env
sources:

# Shell 1
A=1 codex app-server --listen unix://

# Shell 2
A=2 codex
# In the TUI, !printenv A prints 1.

# Shell 3
A=2 codex -c model=gpt-5.5
# In the TUI, !printenv A prints 2.

The point is provenance. It would help if Codex made explicit whether command
env came from the launcher, a reused local daemon, a remote executor, or a
declared project provider.

Manual reproduction recipe:

# Shell 1: start or replace the local app-server daemon with A=1.
mkdir -p /tmp/codex-env-repro
cd /tmp/codex-env-repro
A=1 codex app-server --listen unix://

# Shell 2: launch the TUI with A=2, using the implicit local daemon path.
cd /tmp/codex-env-repro
A=2 codex

# In the TUI, run:
!pwd
!printenv A

# Observed in the repro: cwd is the selected local directory, but A prints 1
# because command execution reused the daemon process environment.

# Shell 3: launch with a config override, which prevents implicit daemon reuse.
cd /tmp/codex-env-repro
A=2 codex -c model=gpt-5.5

# In the TUI, run:
!pwd
!printenv A

# Observed in the repro: A prints 2 because this launch uses a different local
# execution topology.

2.5 No merged `SessionStart` env overlay

Current main has hook output support for context, but not a supported
SessionStart env overlay:

codex-rs/hooks/src/engine/output_parser.rs: SessionStartOutput contains
universal output plus additional_context.
codex-rs/hooks/src/schema.rs: hook output wire types use
deny_unknown_fields.
codex-rs/hooks/schema/generated/session-start.command.output.schema.json:
additionalProperties is false and hookSpecificOutput contains
hookEventName and optional additionalContext, but no env.

Question: should hooks have a supported structured way to publish env data to
later commands? If yes, it should be explicit in schema/runtime behavior and
should not require replaying hidden shell scripts after command approval.

Reproduction script:

#!/usr/bin/env bash
set -euo pipefail

WORKSPACE="$(mktemp -d "${TMPDIR:-/tmp}/codex-sessionstart-case.XXXXXX")"
cleanup() {
  rm -rf "$WORKSPACE"
}
trap cleanup EXIT

MARKER="$WORKSPACE/session-start-marker"
CODEX_STDERR="$WORKSPACE/codex-stderr.log"

mkdir -p "$WORKSPACE/.codex" "$WORKSPACE/.tools/bin"

cat >"$WORKSPACE/.tools/bin/project-tool" <<'EOF'
#!/usr/bin/env sh
printf 'project-tool-from-sessionstart\n'
EOF
chmod +x "$WORKSPACE/.tools/bin/project-tool"

cat >"$WORKSPACE/session_start_hook.py" <<'EOF'
import json
import os
from pathlib import Path

Path(os.environ["SESSIONSTART_MARKER"]).write_text("ran\n")
print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "SessionStart",
        "additionalContext": "SessionStart hook ran, but this output cannot publish env."
    }
}))
EOF

cat >"$WORKSPACE/.codex/config.toml" <<EOF
[features]
hooks = true

[hooks]

[[hooks.SessionStart]]
matcher = "startup"

[[hooks.SessionStart.hooks]]
type = "command"
command = "python3 $WORKSPACE/session_start_hook.py"
timeout = 5
EOF

export SESSIONSTART_MARKER="$MARKER"

PROMPT="$(cat <<'EOF'
Run exactly this shell command and report only its stdout:
printf 'PROJECT_BIN=%s\n' "$PROJECT_BIN"
command -v project-tool || true
printf 'marker='
if [ -f "$SESSIONSTART_MARKER" ]; then
  cat "$SESSIONSTART_MARKER"
else
  echo missing
fi
EOF
)"

if ! codex exec --json --dangerously-bypass-approvals-and-sandbox \
  --dangerously-bypass-hook-trust \
  --skip-git-repo-check --cd "$WORKSPACE" "$PROMPT" \
  2>"$CODEX_STDERR" \
  | python3 -c '
import json
import sys

last_output = None
for line in sys.stdin:
    try:
        event = json.loads(line)
    except json.JSONDecodeError:
        continue
    item = event.get("item") or {}
    if event.get("type") == "item.completed" and item.get("type") == "command_execution":
        last_output = item.get("aggregated_output")
    elif event.get("type") == "item.completed" and item.get("type") == "agent_message":
        last_output = item.get("text")

if last_output is not None:
    print(last_output.rstrip())
'
then
  echo "codex exec failed; stderr follows:" >&2
  cat "$CODEX_STDERR" >&2
  exit 1
fi

Expected output on the current codex exec path:

PROJECT_BIN=
marker=missing

3. Current State

The current behavior has four separable layers:

Shell startup semantics
- Shipped: shell_environment_policy, inherit = "all",
  allow_login_shell, and shell_command.login.
- Gap: these controls do not define project env providers and do not make all
  shell startup mutations obvious to users.
Execution process provenance
- Shipped: Build remote exec env from exec-server policy #17216 moved remote exec base env ownership to the executor; Fix: TUI starting in wrong CWD #23538
  fixed a local daemon cwd provenance regression.
- Gap: app-server local command execution lacks a cwd-scoped environment contract #24638 remains open, and command metadata does not clearly expose
  launcher-vs-daemon-vs-remote env ownership.
Local/worktree setup lifecycle
- Existing: local environments, setup scripts, and hooks.
- Gap: setup shell exports do not become durable command env; worktree and
  remote setup flows still have inconsistent behavior.
Project command environment providers
- Existing design thread: Add first-class project command environments for agent shell execution #25452.
- Gap: Codex does not yet have a declared provider that automatically applies
  a project environment to commands.

One possible way to keep the discussion scoped is to separate lower-level env
provenance from higher-level project providers: clarify provenance first, then
discuss whether a structured env overlay should exist, then decide whether
SessionStart hooks and project providers should produce that overlay.

3.1 State Map

flowchart LR
    user["Workspace expects a project command environment"] --> runner["Codex shell command runner"]

    runner --> startup["Layer 1<br/>shell startup semantics"]
    runner --> provenance["Layer 2<br/>execution process provenance"]
    runner --> lifecycle["Layer 3<br/>local/worktree setup lifecycle"]
    runner --> provider["Layer 4<br/>project command environment provider"]

    startup --> shipped_login["Shipped<br/>allow_login_shell<br/>#12312"]
    startup --> open_login["Open design/docs gap<br/>#4210 #4843 #8922 #11952 #14774"]

    provenance --> shipped_remote["Shipped<br/>remote executor env source<br/>#17216"]
    provenance --> shipped_cwd["Shipped<br/>local daemon cwd fix<br/>#23538"]
    provenance --> open_env_source["Open gap<br/>local daemon env source<br/>#24638"]

    lifecycle --> shipped_local_env["Existing feature<br/>local environments / setup scripts"]
    lifecycle --> open_lifecycle["Open gaps<br/>exports/setup/worktree drift<br/>#10543 #18981 #23648"]

    provider --> umbrella["Provider issue<br/>first-class command environments<br/>#25452"]
    provider --> overlay_prs["Prior overlay attempts<br/>#24468 #24650 #24805 #25364"]

    open_env_source --> provenance_question["Question<br/>make env provenance explicit"]
    overlay_prs --> overlay_question["Question<br/>structured ThreadShellEnvOverlay"]
    overlay_question --> sessionstart_question["Question<br/>SessionStart produces overlay"]
    overlay_question --> provider_question["Question<br/>provider adapters"]
    umbrella --> provider_question
    provider_question --> fallback_question["Question<br/>session/wrap modes when snapshot is insufficient"]

3.2 Code Mechanisms

Mechanism	Current code surface	Current behavior	Remaining gap
Shell env construction	`codex-rs/protocol/src/shell_environment.rs`; `codex-rs/core/src/spawn.rs`	`create_env()` builds command env from `std::env::vars()` in the process doing execution, applies `shell_environment_policy`, and adds `CODEX_THREAD_ID`. `spawn.rs` then uses `env_clear()` and `envs(env)`.	The source process can be the launcher, a reused local app-server daemon, or a remote executor. There is no project provider or thread overlay in this path today.
Login shell control	`codex-rs/core/src/tools/handlers/unified_exec.rs`; `codex-rs/core/src/tools/handlers/shell/shell_command.rs`	`allow_login_shell=false` rejects explicit `login=true`; omitted `login` defaults to the config value.	Prevents profile clobbering in the affected paths, but does not materialize project environments or fix app-server env provenance.
Local app-server reuse	`codex-rs/tui/src/lib.rs`	`can_reuse_implicit_local_daemon(...)` refuses reuse when the daemon cannot adopt launch state, such as non-empty `-c` overrides.	This can make `codex` and `codex -c ...` use different command env sources while the UI still looks local. #24638 is the open env-provenance version of the earlier cwd issue fixed by #23538.
Execution environment selection	`codex-rs/core/src/environment_selection.rs`; `codex-rs/app-server-protocol/src/protocol/v2/{thread,turn}.rs`; `codex-rs/app-server/README.md`	app-server supports experimental `thread/start.environments` and `turn/start.environments`; `EnvironmentManager` resolves environment ids and cwd.	This selects local/remote execution environments. It is not a project command environment provider and does not materialize shell env.
Local environments / setup scripts	Codex app local environment feature	Setup scripts run as lifecycle setup, commonly in a separate process/session.	`export FOO=bar` in setup does not become durable command env. Remote/worktree setup paths still have gaps.
Hooks / `SessionStart`	hooks runtime and generated hook schemas	`SessionStart` can inject context/system messages through supported output fields.	No merged `hookSpecificOutput.env` or `CODEX_ENV_FILE` support exists on `main`.
Shell snapshots	`codex-rs/core/src/shell_snapshot.rs`	Preserves selected shell startup state for command execution.	Can conflict with rc/provider state and is not a declarative project command environment.

3.3 Timeline

Active period (UTC)	Thread	Type	What changed or was proposed	Result	Design signal
2025-05-20 - 2025-05-22	#1061	PR	Introduced `shell_environment_policy`.	Merged to `main`.	Codex made subprocess env explicit and policy-controlled. The initial default was conservative (`inherit = "core"`).
2025-06-06 - 2025-11-05	#1249	Issue	Discussed finalizing `shell_environment_policy`.	Closed completed.	Env filtering and profile reintroduction were already known tensions.
2025-07-25 - 2025-07-25	#1678	PR	Added optional user profile support direction.	Merged to `main`.	Profile loading was useful, but did not define the command-env contract.
2025-08-07 - 2025-08-07	#1904	PR	Changed default `shell_environment_policy.inherit` to `all`.	Merged to `main`.	Launch-process env inheritance became the default expectation.
2025-09-25 - present	#4210	Issue	Reported `bash -lc` mutating `PATH` ordering.	Open.	Correctly inherited env can still be rewritten by shell startup.
2025-10-02 - 2025-10-02	#4612	PR	Split interactive and non-interactive sessions.	Merged to `main`.	Changed command execution topology around shell invocation.
2025-10-06 - present	#4843	Issue	Reported login shell dropping direnv/devenv project env.	Open.	Project envs need more than inherited shell behavior.
2025-11-11 - 2025-11-12	#6510	PR	Added the `shell_command` tool.	Merged to `main`.	Shell execution became a first-class tool surface with login behavior.
2025-11-18 - 2025-12-05	#6846	PR	Added a `login` parameter to `shell_command`.	Merged to `main`.	Single-command login control existed, but default policy remained needed.
2026-01-08 - present	#8922	Issue	Requested default non-login shell config.	Open.	Users needed session-level control, not per-command memory.
2026-01-08 - 2026-01-09	#8938	PR	Tried `[shell].default_login`.	Closed unmerged.	More granular than `allow_login_shell`, but did not land.
2026-02-03 - present	#10543	Issue	Local environment setup script `export` did not persist.	Open.	Setup lifecycle is not durable command env.
2026-02-09 - 2026-02-09	#11223	Issue	`shell_snapshot=true` broke rc/direnv handling.	Closed completed.	Historical example of snapshot/startup/provider interactions, not an open gap by itself.
2026-02-16 - present	#11952	Discussion	Proposed `[shell].default_login`.	Open, 0 comments as of verification.	Existing discussion covers login/PATH only.
2026-02-20 - 2026-02-20	#12312	PR	Added top-level `allow_login_shell`.	Merged to `main`.	Practical workaround for shell startup clobbering.
2026-03-16 - present	#14774	Issue	Asked docs to explain `allow_login_shell` and env policy interaction.	Open.	The current contract is still difficult to understand.
2026-04-09 - 2026-04-13	#17216	PR	Remote exec env now derives from exec-server policy.	Merged to `main`.	Remote env provenance was fixed by moving base env to the executor.
2026-04-22 - present	#18981	Issue	Handoff to new worktree does not use selected environments.	Open.	Environment lifecycle is inconsistent across worktree flows.
2026-05-07 - present	#21509	Issue	Remote SSH workflows need first-class remote workspace bootstrap.	Open.	Background context for remote execution boundaries and diagnostics, not a direct project env provider request.
2026-05-13 - present	#22545	Issue	Remote SSH new worktree does not discover repo-local skills.	Open.	Background context for remote worktree project-context discovery, not a shell env issue by itself.
2026-05-19 - 2026-05-19	#23538	PR	Fixed local app-server reuse causing wrong cwd.	Merged to `main`.	Cwd provenance was fixed; env provenance remains analogous.
2026-05-20 - present	#23642	Issue	VS Code selected Python interpreter / venv ignored.	Open.	IDE-selected env is not part of the command env contract.
2026-05-20 - present	#23648	Issue	Remote SSH new worktree does not run selected environment setup.	Open.	Remote worktree setup lifecycle is not consistently applied.
2026-05-25 - 2026-05-26	#24468	PR	Tried `CODEX_ENV_FILE` env persistence by parsing export-style updates.	Closed unmerged.	Shell export parsing and stale env state were problematic.
2026-05-26 - present	#24638	Issue	Local app-server command env lacks a cwd-scoped provenance contract.	Open.	`codex` can inherit old daemon env; `codex -c ...` can inherit launcher env.
2026-05-26 - 2026-05-27	#24650	PR	Tried sourcing `CODEX_ENV_FILE` before later commands.	Closed unmerged.	Sourcing hidden setup before commands raised approval/sandbox/correctness concerns.
2026-05-27 - 2026-06-01	#24805	PR	Restricted env file to `SessionStart`, sourced once, and captured an env diff.	Closed unmerged draft.	Safer than command-time sourcing, but still file/shell/platform heavy.
2026-05-29 - 2026-05-29	#25128	PR	Added cmd.exe env-file support stacked on #24805.	Merged into the stacked `abhinav/codex-env-file` branch, not `main`.	Windows support adds real complexity, but this is not evidence of mainline env-file support.
2026-05-31 - 2026-06-04	#25364	PR	Proposed structured `hookSpecificOutput.env` `SessionStart` overlay.	Closed unmerged.	Most structured prior overlay attempt: data, not shell replay.
2026-05-31 - present	#25452	Issue	Proposed first-class project command environments.	Open.	Closest provider issue for generic project command envs.

3.4 Prior Attempts

Several recent PRs explored ways for setup or hooks to publish environment
changes to later shell commands:

Add CODEX_ENV_FILE env persistence #24468 and Add CODEX_ENV_FILE hook persistence #24650 tried CODEX_ENV_FILE persistence, including parsing or
sourcing shell-written state.
Add CODEX_ENV_FILE for SessionStart hooks #24805 reduced risk by exposing the env file only to SessionStart, sourcing
once, and capturing an env diff.
[codex] Support cmd.exe session env files #25128 showed that Windows cmd.exe support adds additional shell-specific
complexity, but it landed only in the stacked env-file branch.
Add SessionStart hook environment overlays #25364 moved to structured hookSpecificOutput.env, treating environment
changes as data rather than hidden shell code.

Taken together, these attempts raise the question of whether Codex needs a
small structured data contract rather than hidden shell replay. Command-time
sourcing creates correctness, sandbox, cleanup, race, secret-handling, and
approval-boundary problems; a structured thread shell env overlay could make
those tradeoffs explicit.

4. What To Clarify

Where command environment provenance should be visible, so users and agents
can tell where the active env came from.
Whether a workspace should be able to declare its intended command
environment once, without relying on the model to remember provider-specific
wrappers for every command.
How to distinguish environment setup/materialization failures from failures
of commands run inside that environment.
How to preserve explicit sandbox and approval boundaries, so no hidden setup
runs after the user approved a visible command.
Which support boundaries should be shared or separate across CLI,
app-server, Desktop/IDE, worktrees, and remote execution.

5. Open Questions

Command env provenance. Should local command env follow the newly
launched client/session, the reused app-server daemon, or another explicit
rule? If daemon reuse remains visible to command execution, where should that
provenance be exposed to users and agents? Related: Build remote exec env from exec-server policy #17216, Fix: TUI starting in wrong CWD #23538, app-server local command execution lacks a cwd-scoped environment contract #24638.
A structured env overlay primitive. Is a thread-scoped shell env overlay
the right lower-level primitive for durable command env changes, or should
this be solved only at the provider layer? The key questions are precedence,
protected runtime variables, Windows env-name normalization, resume/clear
behavior, and subagent inheritance. Related: Add SessionStart hook environment overlays #25364.
SessionStart as an overlay producer. If a structured overlay exists,
should SessionStart hooks be allowed to publish env data to later commands?
The prior attempts suggest this should be structured data, not an env file
that is sourced before later approved commands. Related: Add CODEX_ENV_FILE env persistence #24468, Add CODEX_ENV_FILE hook persistence #24650,
Add CODEX_ENV_FILE for SessionStart hooks #24805, [codex] Support cmd.exe session env files #25128, Add SessionStart hook environment overlays #25364.
Project command environment providers. Should project command
environments live inside existing local environment/worktree configuration,
or should they be a new config concept? Should the first supported mode be an
env snapshot, a persistent session, command wrapping, or a combination?
Related: Add first-class project command environments for agent shell execution #25452.
Tracking and ownership. Should this broader discussion happen under
Add first-class project command environments for agent shell execution #25452, or would maintainers prefer a dedicated Discussion thread that
connects provenance, setup lifecycle, hooks, app-server, Desktop/IDE, and
remote execution?

6. Note and Thanks

I have run into several of the environment issues above in real work, and they
have been difficult to reason about because the related behavior is spread
across several execution paths and lifecycle boundaries.

Hope this discussion can provide a useful reference for contributors and help
improve related functions, to make Codex smoother for users. If anything here is
inaccurate, incomplete, or missing important prior context, please point it out directly.

7. References

Shell/login behavior:

Historical implementation context:

App-server / provenance:

Local/worktree/remote environments:

SessionStart env overlay attempts:

Project command environment provider issue:

Add first-class project command environments for agent shell execution #25452

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clarifying Codex command environment contracts #26901

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Clarifying Codex command environment contracts #26901

Uh oh!

royenheart Jun 7, 2026

1. Problem Summary

2. Motivating Examples

2.1 Launcher environment vs login shell

2.2 Setup exports do not persist

2.3 Workspace cwd is not a project command environment

2.4 Local app-server env provenance

2.5 No merged SessionStart env overlay

3. Current State

3.1 State Map

3.2 Code Mechanisms

3.3 Timeline

3.4 Prior Attempts

4. What To Clarify

5. Open Questions

6. Note and Thanks

7. References

Replies: 0 comments

royenheart
Jun 7, 2026

2.5 No merged `SessionStart` env overlay