mirror of https://github.com/openai/codex.git synced 2026-05-14 08:12:36 +00:00

Files

starr-openai 78421face0 Route process tools to selected environments (#20647 )

## 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`.

---------

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

2026-05-05 12:12:03 -07:00

src

Route process tools to selected environments (#20647 )

2026-05-05 12:12:03 -07:00

BUILD.bazel

Extract tool spec helpers into codex-tools (#16471 )

2026-04-01 14:06:04 -07:00

Cargo.toml

Extract tool config into codex-tools (#16379 )

2026-04-01 13:21:50 -07:00

README.md

tools: remove unused experimental list_dir tool (#21170 )

2026-05-05 13:11:07 +02:00

README.md

codex-tools

codex-tools is intended to become the home for tool-related code that is shared across multiple crates and does not need to stay coupled to codex-core.

Today this crate is intentionally small. It currently owns the shared tool schema and Responses API tool primitives that no longer need to live in core/src/tools/spec.rs or core/src/client_common.rs:

JsonSchema
AdditionalProperties
ToolDefinition
ToolSpec
ConfiguredToolSpec
ResponsesApiTool
FreeformTool
FreeformToolFormat
LoadableToolSpec
ResponsesApiWebSearchFilters
ResponsesApiWebSearchUserLocation
ResponsesApiNamespace
ResponsesApiNamespaceTool
code-mode ToolSpec adapters and exec / wait spec builders
MCP resource and test_sync_tool spec builders
local host tool spec builders for shell/exec/request-permissions/view-image
collaboration and agent-job ToolSpec builders for spawn/send/wait/close, request_user_input, and CSV fanout/reporting
discoverable-tool models, client filtering, and ToolSpec builders for tool_search and request_plugin_install
parse_tool_input_schema()
parse_dynamic_tool()
parse_mcp_tool()
create_tools_json_for_responses_api()
mcp_call_tool_result_output_schema()
tool_definition_to_responses_api_tool()
dynamic_tool_to_loadable_tool_spec()
dynamic_tool_to_responses_api_tool()
mcp_tool_to_responses_api_tool()
mcp_tool_to_deferred_responses_api_tool()
augment_tool_spec_for_code_mode()
tool_spec_to_code_mode_tool_definition()

That extraction is the first step in a longer migration. The goal is not to move all of core/src/tools into this crate in one shot. Instead, the plan is to peel off reusable pieces in reviewable increments while keeping compatibility-sensitive orchestration in codex-core until the surrounding boundaries are ready.

Vision

Over time, this crate should hold tool-facing primitives that are shared by multiple consumers, for example:

schema and spec data models
tool input/output parsing helpers
tool metadata and compatibility shims that do not depend on codex-core
other narrowly scoped utility code that multiple crates need

The corresponding non-goals are just as important:

do not move codex-core orchestration here prematurely
do not pull Session / TurnContext / approval flow / runtime execution logic into this crate unless those dependencies have first been split into stable shared interfaces
do not turn this crate into a grab-bag for unrelated helper code

Migration approach

The expected migration shape is:

Move low-coupling tool primitives here.
Switch non-core consumers to depend on codex-tools directly.
Leave compatibility-sensitive adapters in codex-core while downstream call sites are updated.
Only extract higher-level tool infrastructure after the crate boundaries are clear and independently testable.

That means it is normal for codex-core to temporarily re-export types or helpers from codex-tools during the transition.

Crate conventions

This crate should start with stricter structure than core/src/tools so it stays easy to grow:

src/lib.rs should remain exports-only.
Business logic should live in named module files such as foo.rs.
Unit tests for foo.rs should live in a sibling foo_tests.rs.
The implementation file should wire tests with:

#[cfg(test)]
#[path = "foo_tests.rs"]
mod tests;

If this crate starts accumulating code that needs runtime state from codex-core, that is a sign to revisit the extraction boundary before adding more here.