Prepare selected environment plumbing (#20669)

## Why
This is a prep PR in the multi-environment process-tool stack. It
separates ownership/config cleanup from the behavior change that teaches
process tools to route by selected environment, so the follow-up PR can
focus on model-facing `environment_id` behavior.

## Stack
1. https://github.com/openai/codex/pull/20646 - `EnvironmentContext`
rendering for selected environments
2. https://github.com/openai/codex/pull/20669 - selected-environment
ownership and tool config prep (this PR)
3. https://github.com/openai/codex/pull/20647 - process-tool
`environment_id` routing

## What Changed
- keep the resolved turn environment list wrapped in
`ResolvedTurnEnvironments` through `TurnContext` instead of unwrapping
it back to a raw `Vec`
- add `TurnContext::resolve_path_against` so cwd-relative path
resolution has one shared helper
- replace the old tool config boolean with `ToolEnvironmentMode::{None,
Single, Multiple}`

## Testing
- Tests not run locally; this prep refactor is covered by GitHub CI for
the stack.

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

codex-rs/tools/src/lib.rs

@@ -109,6 +109,7 @@ pub use responses_api::mcp_tool_to_deferred_responses_api_tool;
 pub use responses_api::mcp_tool_to_responses_api_tool;
 pub use responses_api::tool_definition_to_responses_api_tool;
 pub use tool_config::ShellCommandBackendConfig;
+pub use tool_config::ToolEnvironmentMode;
 pub use tool_config::ToolUserShellType;
 pub use tool_config::ToolsConfig;
 pub use tool_config::ToolsConfigParams;

codex-rs/tools/src/tool_config.rs

@@ -88,7 +88,7 @@ pub struct ToolsConfig {
     pub shell_type: ConfigShellToolType,
     pub shell_command_backend: ShellCommandBackendConfig,
     pub unified_exec_shell_mode: UnifiedExecShellMode,
-    pub has_environment: bool,
+    pub environment_mode: ToolEnvironmentMode,
     pub allow_login_shell: bool,
     pub apply_patch_tool_type: Option<ApplyPatchToolType>,
     pub web_search_mode: Option<WebSearchMode>,
@@ -129,6 +129,27 @@ pub struct ToolsConfigParams<'a> {
     pub windows_sandbox_level: WindowsSandboxLevel,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ToolEnvironmentMode {
+    None,
+    Single,
+    Multiple,
+}
+
+impl ToolEnvironmentMode {
+    pub fn from_count(count: usize) -> Self {
+        match count {
+            0 => Self::None,
+            1 => Self::Single,
+            _ => Self::Multiple,
+        }
+    }
+
+    pub fn has_environment(self) -> bool {
+        !matches!(self, Self::None)
+    }
+}
+
 impl ToolsConfig {
     pub fn new(params: &ToolsConfigParams<'_>) -> Self {
         let ToolsConfigParams {
@@ -205,7 +226,7 @@ impl ToolsConfig {
             shell_type,
             shell_command_backend,
             unified_exec_shell_mode: UnifiedExecShellMode::Direct,
-            has_environment: true,
+            environment_mode: ToolEnvironmentMode::Single,
             allow_login_shell: true,
             apply_patch_tool_type,
             web_search_mode: *web_search_mode,
@@ -306,8 +327,8 @@ impl ToolsConfig {
         self
     }
 
-    pub fn with_has_environment(mut self, has_environment: bool) -> Self {
-        self.has_environment = has_environment;
+    pub fn with_environment_mode(mut self, environment_mode: ToolEnvironmentMode) -> Self {
+        self.environment_mode = environment_mode;
         self
     }
 

codex-rs/tools/src/tool_registry_plan.rs

@@ -135,7 +135,7 @@ pub fn build_tool_registry_plan(
         );
     }
 
-    if config.has_environment {
+    if config.environment_mode.has_environment() {
         match &config.shell_type {
             ConfigShellToolType::Default => {
                 plan.push_spec(
@@ -184,7 +184,9 @@ pub fn build_tool_registry_plan(
         }
     }
 
-    if config.has_environment && config.shell_type != ConfigShellToolType::Disabled {
+    if config.environment_mode.has_environment()
+        && config.shell_type != ConfigShellToolType::Disabled
+    {
         plan.register_handler("shell", ToolHandlerKind::Shell);
         plan.register_handler("container.exec", ToolHandlerKind::Shell);
         plan.register_handler("local_shell", ToolHandlerKind::Shell);
@@ -324,7 +326,7 @@ pub fn build_tool_registry_plan(
         );
     }
 
-    if config.has_environment
+    if config.environment_mode.has_environment()
         && let Some(apply_patch_tool_type) = &config.apply_patch_tool_type
     {
         match apply_patch_tool_type {
@@ -346,7 +348,7 @@ pub fn build_tool_registry_plan(
         plan.register_handler("apply_patch", ToolHandlerKind::ApplyPatch);
     }
 
-    if config.has_environment
+    if config.environment_mode.has_environment()
         && config
             .experimental_supported_tools
             .iter()
@@ -393,7 +395,7 @@ pub fn build_tool_registry_plan(
         );
     }
 
-    if config.has_environment {
+    if config.environment_mode.has_environment() {
         plan.push_spec(
             create_view_image_tool(ViewImageToolOptions {
                 can_request_original_image_detail: config.can_request_original_image_detail,

codex-rs/tools/src/tool_registry_plan_tests.rs

@@ -11,6 +11,7 @@ use crate::ResponsesApiNamespaceTool;
 use crate::ResponsesApiTool;
 use crate::ResponsesApiWebSearchFilters;
 use crate::ResponsesApiWebSearchUserLocation;
+use crate::ToolEnvironmentMode;
 use crate::ToolHandlerSpec;
 use crate::ToolName;
 use crate::ToolNamespace;
@@ -544,7 +545,7 @@ fn disabled_environment_omits_environment_backed_tools() {
         permission_profile: &PermissionProfile::Disabled,
         windows_sandbox_level: WindowsSandboxLevel::Disabled,
     })
-    .with_has_environment(/*has_environment*/ false);
+    .with_environment_mode(ToolEnvironmentMode::None);
     tools_config
         .experimental_supported_tools
         .push("list_dir".to_string());