Route process tools to selected environments by starr-openai · Pull Request #20647 · openai/codex

starr-openai · 2026-05-01T18:01:03Z

Why

When a turn exposes multiple selected environments, shell-style tools need a model-facing way to identify the intended target environment and handlers need to resolve that target before parsing cwd-relative permission fields or launching processes.

This PR scopes that rollout to process tools. Filesystem-oriented tools such as apply_patch, view_image, and list_dir are intentionally left for follow-up slices.

What Changed

Adds an include_environment_id option to shell-style tool schema builders.
Exposes optional environment_id on shell, shell_command, and exec_command only when ToolEnvironmentMode::Multiple is active.
Adds a shared handler helper that parses environment_id and workdir from JSON function-call arguments and returns the selected Environment plus effective absolute cwd.
Uses that helper in shell, shell_command, and exec_command handling so process execution uses the selected environment filesystem and cwd.
Changes ExecCommandRequest to carry a required resolved cwd, removing the process-manager fallback to the primary turn cwd for new exec commands.
Leaves write_stdin unchanged because it targets an existing process id, not a new environment.

Testing

Added unit coverage for process-tool schema exposure, selected environment resolution, primary fallback, no-environment handling, unknown environment ids, and resolving cwd-relative permission paths against the selected environment cwd.
Added a remote-suite e2e coverage case for exec_command routing across explicit zero environments, one local environment, and local+remote environments.
Ran just fmt and git diff --check.

Allow the remote exec routing e2e to wait longer for the first remote unified exec turn, which can include container startup overhead on devboxes. Co-authored-by: Codex <noreply@openai.com>

Allow apply_patch freeform calls to include optional environment metadata immediately after the begin marker. The handler strips that metadata before invoking the existing patch parser, resolves the selected turn environment, and carries the selected environment filesystem into the apply_patch runtime. Co-authored-by: Codex <noreply@openai.com>

Cover the no-environment e2e case by asserting exec_command is omitted from the model tool surface instead of sending an unavailable tool call. Keep the local/remote cases as actual routing executions. Co-authored-by: Codex <noreply@openai.com>

Allow apply_patch freeform calls to include optional environment metadata immediately after the begin marker. The handler strips that metadata before invoking the existing patch parser, resolves the selected turn environment, and carries the selected environment filesystem into the apply_patch runtime. Co-authored-by: Codex <noreply@openai.com>

Ensure the remote exec routing e2e drains the no-env turn before submitting the single-env routing case. Without this wait, the next turn can time out even though the routing logic is correct. Co-authored-by: Codex <noreply@openai.com>

Allow apply_patch freeform calls to include optional environment metadata immediately after the begin marker. The handler strips that metadata before invoking the existing patch parser, resolves the selected turn environment, and carries the selected environment filesystem into the apply_patch runtime. Co-authored-by: Codex <noreply@openai.com>

Use a fresh TestCodex session for each no-env, single-env, and multi-env remote exec routing scenario so the e2e validates routing rather than cross-turn sequencing. Co-authored-by: Codex <noreply@openai.com>

Allow apply_patch freeform calls to include optional environment metadata immediately after the begin marker. The handler strips that metadata before invoking the existing patch parser, resolves the selected turn environment, and carries the selected environment filesystem into the apply_patch runtime. Co-authored-by: Codex <noreply@openai.com>

Give each remote exec routing scenario its own mock responses server so broad response matchers cannot intercept requests from a later scenario. Co-authored-by: Codex <noreply@openai.com>

Allow apply_patch freeform calls to include optional environment metadata immediately after the begin marker. The handler strips that metadata before invoking the existing patch parser, resolves the selected turn environment, and carries the selected environment filesystem into the apply_patch runtime. Co-authored-by: Codex <noreply@openai.com>

Use an explicit bash non-login command and short yield timeout in the remote routing e2e so the test varies only environment selection. Co-authored-by: Codex <noreply@openai.com>

Allow apply_patch freeform calls to include optional environment metadata immediately after the begin marker. The handler strips that metadata before invoking the existing patch parser, resolves the selected turn environment, and carries the selected environment filesystem into the apply_patch runtime. Co-authored-by: Codex <noreply@openai.com>

Use the resolved exec cwd when applying granted shell permissions and building sandbox approval metadata so selected turn environments do not fall back to turn.cwd. Also remove an extra remote-env test wait; submit_turn_with_environments already waits for TurnComplete. Co-authored-by: Codex <noreply@openai.com>

Allow apply_patch freeform calls to include optional environment metadata immediately after the begin marker. The handler strips that metadata before invoking the existing patch parser, resolves the selected turn environment, and carries the selected environment filesystem into the apply_patch runtime. Co-authored-by: Codex <noreply@openai.com>

Bazel clippy denies expect_used for the core integration test binary, so keep the helper assertion explicit instead of using expect. Co-authored-by: Codex <noreply@openai.com>

Allow apply_patch freeform calls to include optional environment metadata immediately after the begin marker. The handler strips that metadata before invoking the existing patch parser, resolves the selected turn environment, and carries the selected environment filesystem into the apply_patch runtime. Co-authored-by: Codex <noreply@openai.com>

The remote test container does not guarantee the host shell path exists. Request /bin/sh in the routing e2e so the same command can run locally and remotely. Co-authored-by: Codex <noreply@openai.com>

Run the remote exec routing assertion from /tmp with a unique marker file so the test focuses on selected-environment routing instead of the remote-aware test cwd. Co-authored-by: Codex <noreply@openai.com>

Co-authored-by: Codex <noreply@openai.com>

pakrym-oai · 2026-05-05T17:05:15Z

@@ -17,6 +17,13 @@ pub struct ShellToolOptions {
 }

 pub fn create_exec_command_tool(options: CommandToolOptions) -> ToolSpec {


nit: ideally we delete this one. nobody should be creating exec without knowing whether to add env or not.

pakrym-oai · 2026-05-05T17:07:10Z

+        environment_id: REMOTE_ENVIRONMENT_ID.to_string(),
+        cwd: remote_cwd.clone(),
+    };
+    let multi_env_output = exec_command_routing_output(


can we inline, nobody else uses exec_command_routing_output

pakrym-oai · 2026-05-05T17:07:21Z

+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn exec_command_routes_to_selected_remote_environment() -> Result<()> {


should this go into exec tests?

pakrym-oai · 2026-05-05T17:07:32Z

 use std::time::SystemTime;
 use std::time::UNIX_EPOCH;
+use tempfile::TempDir;
+async fn unified_exec_test(server: &wiremock::MockServer) -> Result<TestCodex> {


should we inline?

pakrym-oai · 2026-05-05T17:11:12Z

    pub cwd: AbsolutePathBuf,
+    pub environment: Arc<Environment>,


supernit for the future: might be good to start using TurnEnvironment in places like this where we already store cwd+evn

Co-authored-by: Codex <noreply@openai.com>

starr-openai force-pushed the pr20314-process-tools-on-pr20281 branch 4 times, most recently from 765736f to f1b873f Compare May 1, 2026 18:20

starr-openai force-pushed the pr20314-envctx-on-pr20281 branch from db43360 to 3acd99c Compare May 1, 2026 18:23

starr-openai force-pushed the pr20314-process-tools-on-pr20281 branch 5 times, most recently from 7b87996 to 625359a Compare May 1, 2026 18:53

bkutasi mentioned this pull request May 1, 2026

📊 AI CLI Tools Digest 2026-05-02 bkutasi/big_model_radar#1

Open

starr-openai force-pushed the pr20314-process-tools-on-pr20281 branch from cc4be64 to a477948 Compare May 1, 2026 19:09

starr-openai mentioned this pull request May 1, 2026

Prepare selected environment plumbing #20669

Merged

starr-openai changed the base branch from pr20314-envctx-on-pr20281 to pr20314-env-selection-prep-on-20646 May 1, 2026 19:24

starr-openai force-pushed the pr20314-process-tools-on-pr20281 branch from a477948 to 79874e0 Compare May 1, 2026 19:24

starr-openai mentioned this pull request May 1, 2026

Surface multi-environment choices in environment context #20646

Merged

starr-openai changed the title ~~Gate process tools on selected environments~~ Route process tools to selected environments May 1, 2026

starr-openai force-pushed the pr20314-env-selection-prep-on-20646 branch from 326f101 to 0888b48 Compare May 1, 2026 19:29

starr-openai force-pushed the pr20314-process-tools-on-pr20281 branch from 79874e0 to 508399c Compare May 1, 2026 19:31

starr-openai force-pushed the pr20314-env-selection-prep-on-20646 branch from 0888b48 to 281edbc Compare May 1, 2026 19:32

starr-openai force-pushed the pr20314-process-tools-on-pr20281 branch 2 times, most recently from ba48976 to 2d15bcb Compare May 1, 2026 19:43

starr-openai force-pushed the pr20314-env-selection-prep-on-20646 branch from 281edbc to d57209c Compare May 1, 2026 20:01

starr-openai force-pushed the pr20314-process-tools-on-pr20281 branch from 2d15bcb to 68ecaca Compare May 1, 2026 20:03

starr-openai force-pushed the pr20314-env-selection-prep-on-20646 branch from d57209c to b6984c4 Compare May 1, 2026 20:06

starr-openai force-pushed the pr20314-process-tools-on-pr20281 branch 2 times, most recently from 4749c07 to 642d669 Compare May 1, 2026 20:14

starr-openai force-pushed the pr20314-env-selection-prep-on-20646 branch from 6ae16cb to 5ee157f Compare May 1, 2026 21:25

starr-openai force-pushed the pr20314-process-tools-on-pr20281 branch from 642d669 to 3fa2aba Compare May 1, 2026 21:27

starr-openai mentioned this pull request May 1, 2026

Support multi-env list_dir routing #20530

Closed

test: relax remote exec routing timeout

f93e763

Allow the remote exec routing e2e to wait longer for the first remote unified exec turn, which can include container startup overhead on devboxes. Co-authored-by: Codex <noreply@openai.com>

test: avoid invalid no-env exec routing

3e3a7be

Cover the no-environment e2e case by asserting exec_command is omitted from the model tool surface instead of sending an unavailable tool call. Keep the local/remote cases as actual routing executions. Co-authored-by: Codex <noreply@openai.com>

test: wait for no-env routing turn

4cb623d

Ensure the remote exec routing e2e drains the no-env turn before submitting the single-env routing case. Without this wait, the next turn can time out even though the routing logic is correct. Co-authored-by: Codex <noreply@openai.com>

test: isolate remote exec routing scenarios

2e656dc

Use a fresh TestCodex session for each no-env, single-env, and multi-env remote exec routing scenario so the e2e validates routing rather than cross-turn sequencing. Co-authored-by: Codex <noreply@openai.com>

test: isolate remote routing response mocks

c357ca2

Give each remote exec routing scenario its own mock responses server so broad response matchers cannot intercept requests from a later scenario. Co-authored-by: Codex <noreply@openai.com>

test: pin remote routing exec command shape

20d04bf

Use an explicit bash non-login command and short yield timeout in the remote routing e2e so the test varies only environment selection. Co-authored-by: Codex <noreply@openai.com>

codex: avoid expect in remote env test

f301e40

Bazel clippy denies expect_used for the core integration test binary, so keep the helper assertion explicit instead of using expect. Co-authored-by: Codex <noreply@openai.com>

starr-openai and others added 2 commits May 4, 2026 16:26

codex: use portable shell in remote env test

8eeba44

The remote test container does not guarantee the host shell path exists. Request /bin/sh in the routing e2e so the same command can run locally and remotely. Co-authored-by: Codex <noreply@openai.com>

codex: use stable remote cwd in routing test

146073c

Run the remote exec routing assertion from /tmp with a unique marker file so the test focuses on selected-environment routing instead of the remote-aware test cwd. Co-authored-by: Codex <noreply@openai.com>

This was referenced May 5, 2026

Route shell_command through selected environments #21142

Closed

Route view_image through selected environments #21143

Merged

codex: route exec_command through selected environment

dea874f

Co-authored-by: Codex <noreply@openai.com>

pakrym-oai reviewed May 5, 2026

View reviewed changes

pakrym-oai approved these changes May 5, 2026

View reviewed changes

codex: fix CI failures on PR #20647

b07124f

Co-authored-by: Codex <noreply@openai.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Route process tools to selected environments#20647

Route process tools to selected environments#20647
starr-openai merged 17 commits into
mainfrom
pr20314-process-tools-on-pr20281

starr-openai commented May 1, 2026 •

edited

Loading

pakrym-oai May 5, 2026

pakrym-oai May 5, 2026

pakrym-oai May 5, 2026

pakrym-oai May 5, 2026

pakrym-oai May 5, 2026

Labels

2 participants

		@@ -17,6 +17,13 @@ pub struct ShellToolOptions {
		}

		pub fn create_exec_command_tool(options: CommandToolOptions) -> ToolSpec {

Conversation

starr-openai commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What Changed

Testing

pakrym-oai May 5, 2026

Choose a reason for hiding this comment

pakrym-oai May 5, 2026

Choose a reason for hiding this comment

pakrym-oai May 5, 2026

Choose a reason for hiding this comment

pakrym-oai May 5, 2026

Choose a reason for hiding this comment

pakrym-oai May 5, 2026

Choose a reason for hiding this comment

Labels

2 participants

starr-openai commented May 1, 2026 •

edited

Loading