From 4e119a3b38e4a4decfccb003acecabc4614142b6 Mon Sep 17 00:00:00 2001
From: Michael Bolin <mbolin@openai.com>
Date: Sat, 28 Mar 2026 16:33:58 -0700
Subject: [PATCH] codex-tools: extract local host tool specs (#16138)

## Why

`core/src/tools/spec.rs` still bundled a set of pure local-host tool
builders with the orchestration that actually decides when those tools
are exposed and which handlers back them. That made `codex-core`
responsible for JSON/tool-shape construction that does not depend on
session state, and it kept the `codex-tools` migration from taking a
meaningfully larger bite out of `spec.rs`.

This PR moves that reusable spec-building layer into `codex-tools` while
leaving feature gating, handler registration, and runtime-coupled
descriptions in `codex-core`.

## What changed

- added `codex-rs/tools/src/local_tool.rs` for the pure builders for
`exec_command`, `write_stdin`, `shell`, `shell_command`, and
`request_permissions`
- added `codex-rs/tools/src/view_image.rs` for the `view_image` tool
spec and output schema so the extracted modules stay right-sized
- rewired `codex-rs/core/src/tools/spec.rs` to call those extracted
builders instead of constructing these specs inline
- kept the `request_permissions` description source in `codex-core`,
with `codex-tools` taking the description as input so the crate boundary
does not grow a dependency on handler/runtime code
- moved the direct constructor coverage for this slice from
`codex-rs/core/src/tools/spec_tests.rs` into
`codex-rs/tools/src/local_tool_tests.rs` and
`codex-rs/tools/src/view_image_tests.rs`
- updated `codex-rs/tools/README.md` to reflect that `codex-tools` now
owns this local-host spec layer

## Test plan

- `CARGO_TARGET_DIR=/tmp/codex-tools-local-host cargo test -p
codex-tools`
- `CARGO_TARGET_DIR=/tmp/codex-core-local-tools cargo test -p codex-core
--lib tools::spec::`
- `just argument-comment-lint`

## References

- #15923
- #15928
- #15944
- #15953
- #16031
- #16047
- #16129
- #16132
---
 codex-rs/core/src/tools/spec.rs        | 544 +------------------------
 codex-rs/core/src/tools/spec_tests.rs  | 197 +--------
 codex-rs/tools/README.md               |   1 +
 codex-rs/tools/src/lib.rs              |  11 +
 codex-rs/tools/src/local_tool.rs       | 463 +++++++++++++++++++++
 codex-rs/tools/src/local_tool_tests.rs | 442 ++++++++++++++++++++
 codex-rs/tools/src/view_image.rs       |  67 +++
 codex-rs/tools/src/view_image_tests.rs |  67 +++
 8 files changed, 1089 insertions(+), 703 deletions(-)
 create mode 100644 codex-rs/tools/src/local_tool.rs
 create mode 100644 codex-rs/tools/src/local_tool_tests.rs
 create mode 100644 codex-rs/tools/src/view_image.rs
 create mode 100644 codex-rs/tools/src/view_image_tests.rs

diff --git a/codex-rs/core/src/tools/spec.rs b/codex-rs/core/src/tools/spec.rs
index e478c55e4..2e0dcf084 100644
--- a/codex-rs/core/src/tools/spec.rs
+++ b/codex-rs/core/src/tools/spec.rs
@@ -32,7 +32,6 @@ use codex_protocol::config_types::WebSearchConfig;
 use codex_protocol::config_types::WebSearchMode;
 use codex_protocol::config_types::WindowsSandboxLevel;
 use codex_protocol::dynamic_tools::DynamicToolSpec;
-use codex_protocol::models::VIEW_IMAGE_TOOL_NAME;
 use codex_protocol::openai_models::ApplyPatchToolType;
 use codex_protocol::openai_models::ConfigShellToolType;
 use codex_protocol::openai_models::InputModality;
@@ -42,10 +41,19 @@ use codex_protocol::openai_models::WebSearchToolType;
 use codex_protocol::protocol::SandboxPolicy;
 use codex_protocol::protocol::SessionSource;
 use codex_protocol::protocol::SubAgentSource;
+use codex_tools::CommandToolOptions;
 use codex_tools::FreeformTool;
 use codex_tools::FreeformToolFormat;
 use codex_tools::ResponsesApiTool;
+use codex_tools::ShellToolOptions;
+use codex_tools::ViewImageToolOptions;
 use codex_tools::augment_tool_spec_for_code_mode;
+use codex_tools::create_exec_command_tool;
+use codex_tools::create_request_permissions_tool;
+use codex_tools::create_shell_command_tool;
+use codex_tools::create_shell_tool;
+use codex_tools::create_view_image_tool;
+use codex_tools::create_write_stdin_tool;
 use codex_tools::dynamic_tool_to_responses_api_tool;
 use codex_tools::mcp_tool_to_responses_api_tool;
 use codex_tools::tool_spec_to_code_mode_tool_definition;
@@ -81,40 +89,6 @@ static TOOL_SUGGEST_DESCRIPTION_TEMPLATE: LazyLock<Template> = LazyLock::new(||
 });
 const WEB_SEARCH_CONTENT_TYPES: [&str; 2] = ["text", "image"];
 
-fn unified_exec_output_schema() -> JsonValue {
-    json!({
-        "type": "object",
-        "properties": {
-            "chunk_id": {
-                "type": "string",
-                "description": "Chunk identifier included when the response reports one."
-            },
-            "wall_time_seconds": {
-                "type": "number",
-                "description": "Elapsed wall time spent waiting for output in seconds."
-            },
-            "exit_code": {
-                "type": "number",
-                "description": "Process exit code when the command finished during this call."
-            },
-            "session_id": {
-                "type": "number",
-                "description": "Session identifier to pass to write_stdin when the process is still running."
-            },
-            "original_token_count": {
-                "type": "number",
-                "description": "Approximate token count before output truncation."
-            },
-            "output": {
-                "type": "string",
-                "description": "Command output text, possibly truncated."
-            }
-        },
-        "required": ["wall_time_seconds", "output"],
-        "additionalProperties": false
-    })
-}
-
 fn agent_status_output_schema() -> JsonValue {
     json!({
         "oneOf": [
@@ -559,267 +533,6 @@ fn supports_image_generation(model_info: &ModelInfo) -> bool {
     model_info.input_modalities.contains(&InputModality::Image)
 }
 
-fn create_network_permissions_schema() -> JsonSchema {
-    JsonSchema::Object {
-        properties: BTreeMap::from([(
-            "enabled".to_string(),
-            JsonSchema::Boolean {
-                description: Some("Set to true to request network access.".to_string()),
-            },
-        )]),
-        required: None,
-        additional_properties: Some(false.into()),
-    }
-}
-
-fn create_file_system_permissions_schema() -> JsonSchema {
-    JsonSchema::Object {
-        properties: BTreeMap::from([
-            (
-                "read".to_string(),
-                JsonSchema::Array {
-                    items: Box::new(JsonSchema::String { description: None }),
-                    description: Some("Absolute paths to grant read access to.".to_string()),
-                },
-            ),
-            (
-                "write".to_string(),
-                JsonSchema::Array {
-                    items: Box::new(JsonSchema::String { description: None }),
-                    description: Some("Absolute paths to grant write access to.".to_string()),
-                },
-            ),
-        ]),
-        required: None,
-        additional_properties: Some(false.into()),
-    }
-}
-
-fn create_additional_permissions_schema() -> JsonSchema {
-    JsonSchema::Object {
-        properties: BTreeMap::from([
-            ("network".to_string(), create_network_permissions_schema()),
-            (
-                "file_system".to_string(),
-                create_file_system_permissions_schema(),
-            ),
-        ]),
-        required: None,
-        additional_properties: Some(false.into()),
-    }
-}
-
-fn create_request_permissions_schema() -> JsonSchema {
-    JsonSchema::Object {
-        properties: BTreeMap::from([
-            ("network".to_string(), create_network_permissions_schema()),
-            (
-                "file_system".to_string(),
-                create_file_system_permissions_schema(),
-            ),
-        ]),
-        required: None,
-        additional_properties: Some(false.into()),
-    }
-}
-
-fn windows_destructive_filesystem_guidance() -> &'static str {
-    r#"Windows safety rules:
-- Do not compose destructive filesystem commands across shells. Do not enumerate paths in PowerShell and then pass them to `cmd /c`, batch builtins, or another shell for deletion or moving. Use one shell end-to-end, prefer native PowerShell cmdlets such as `Remove-Item` / `Move-Item` with `-LiteralPath`, and avoid string-built shell commands for file operations.
-- Before any recursive delete or move on Windows, verify the resolved absolute target paths stay within the intended workspace or explicitly named target directory. Never issue a recursive delete or move against a computed path if the final target has not been checked."#
-}
-
-fn create_approval_parameters(
-    exec_permission_approvals_enabled: bool,
-) -> BTreeMap<String, JsonSchema> {
-    let mut properties = BTreeMap::from([
-        (
-            "sandbox_permissions".to_string(),
-            JsonSchema::String {
-                description: Some(
-                    if exec_permission_approvals_enabled {
-                        "Sandbox permissions for the command. Use \"with_additional_permissions\" to request additional sandboxed filesystem or network permissions (preferred), or \"require_escalated\" to request running without sandbox restrictions; defaults to \"use_default\"."
-                    } else {
-                        "Sandbox permissions for the command. Set to \"require_escalated\" to request running without sandbox restrictions; defaults to \"use_default\"."
-                    }
-                    .to_string(),
-                ),
-            },
-        ),
-        (
-            "justification".to_string(),
-            JsonSchema::String {
-                description: Some(
-                    r#"Only set if sandbox_permissions is \"require_escalated\".
-                    Request approval from the user to run this command outside the sandbox.
-                    Phrased as a simple question that summarizes the purpose of the
-                    command as it relates to the task at hand - e.g. 'Do you want to
-                    fetch and pull the latest version of this git branch?'"#
-                    .to_string(),
-                ),
-            },
-        ),
-        (
-            "prefix_rule".to_string(),
-            JsonSchema::Array {
-                items: Box::new(JsonSchema::String { description: None }),
-                description: Some(
-                    r#"Only specify when sandbox_permissions is `require_escalated`.
-                        Suggest a prefix command pattern that will allow you to fulfill similar requests from the user in the future.
-                        Should be a short but reasonable prefix, e.g. [\"git\", \"pull\"] or [\"uv\", \"run\"] or [\"pytest\"]."#.to_string(),
-                ),
-            },
-        )
-    ]);
-
-    if exec_permission_approvals_enabled {
-        properties.insert(
-            "additional_permissions".to_string(),
-            create_additional_permissions_schema(),
-        );
-    }
-
-    properties
-}
-
-fn create_exec_command_tool(
-    allow_login_shell: bool,
-    exec_permission_approvals_enabled: bool,
-) -> ToolSpec {
-    let mut properties = BTreeMap::from([
-        (
-            "cmd".to_string(),
-            JsonSchema::String {
-                description: Some("Shell command to execute.".to_string()),
-            },
-        ),
-        (
-            "workdir".to_string(),
-            JsonSchema::String {
-                description: Some(
-                    "Optional working directory to run the command in; defaults to the turn cwd."
-                        .to_string(),
-                ),
-            },
-        ),
-        (
-            "shell".to_string(),
-            JsonSchema::String {
-                description: Some("Shell binary to launch. Defaults to the user's default shell.".to_string()),
-            },
-        ),
-        (
-            "tty".to_string(),
-            JsonSchema::Boolean {
-                description: Some(
-                    "Whether to allocate a TTY for the command. Defaults to false (plain pipes); set to true to open a PTY and access TTY process."
-                        .to_string(),
-                ),
-            }
-        ),
-        (
-            "yield_time_ms".to_string(),
-            JsonSchema::Number {
-                description: Some(
-                    "How long to wait (in milliseconds) for output before yielding.".to_string(),
-                ),
-            },
-        ),
-        (
-            "max_output_tokens".to_string(),
-            JsonSchema::Number {
-                description: Some(
-                    "Maximum number of tokens to return. Excess output will be truncated."
-                        .to_string(),
-                ),
-            },
-        ),
-    ]);
-    if allow_login_shell {
-        properties.insert(
-            "login".to_string(),
-            JsonSchema::Boolean {
-                description: Some(
-                    "Whether to run the shell with -l/-i semantics. Defaults to true.".to_string(),
-                ),
-            },
-        );
-    }
-    properties.extend(create_approval_parameters(
-        exec_permission_approvals_enabled,
-    ));
-
-    ToolSpec::Function(ResponsesApiTool {
-        name: "exec_command".to_string(),
-        description: if cfg!(windows) {
-            format!(
-                "Runs a command in a PTY, returning output or a session ID for ongoing interaction.\n\n{}",
-                windows_destructive_filesystem_guidance()
-            )
-        } else {
-            "Runs a command in a PTY, returning output or a session ID for ongoing interaction."
-                .to_string()
-        },
-        strict: false,
-        defer_loading: None,
-        parameters: JsonSchema::Object {
-            properties,
-            required: Some(vec!["cmd".to_string()]),
-            additional_properties: Some(false.into()),
-        },
-        output_schema: Some(unified_exec_output_schema()),
-    })
-}
-
-fn create_write_stdin_tool() -> ToolSpec {
-    let properties = BTreeMap::from([
-        (
-            "session_id".to_string(),
-            JsonSchema::Number {
-                description: Some("Identifier of the running unified exec session.".to_string()),
-            },
-        ),
-        (
-            "chars".to_string(),
-            JsonSchema::String {
-                description: Some("Bytes to write to stdin (may be empty to poll).".to_string()),
-            },
-        ),
-        (
-            "yield_time_ms".to_string(),
-            JsonSchema::Number {
-                description: Some(
-                    "How long to wait (in milliseconds) for output before yielding.".to_string(),
-                ),
-            },
-        ),
-        (
-            "max_output_tokens".to_string(),
-            JsonSchema::Number {
-                description: Some(
-                    "Maximum number of tokens to return. Excess output will be truncated."
-                        .to_string(),
-                ),
-            },
-        ),
-    ]);
-
-    ToolSpec::Function(ResponsesApiTool {
-        name: "write_stdin".to_string(),
-        description:
-            "Writes characters to an existing unified exec session and returns recent output."
-                .to_string(),
-        strict: false,
-        defer_loading: None,
-        parameters: JsonSchema::Object {
-            properties,
-            required: Some(vec!["session_id".to_string()]),
-            additional_properties: Some(false.into()),
-        },
-        output_schema: Some(unified_exec_output_schema()),
-    })
-}
-
 fn create_wait_tool() -> ToolSpec {
     let properties = BTreeMap::from([
         (
@@ -870,194 +583,6 @@ fn create_wait_tool() -> ToolSpec {
     })
 }
 
-fn create_shell_tool(exec_permission_approvals_enabled: bool) -> ToolSpec {
-    let mut properties = BTreeMap::from([
-        (
-            "command".to_string(),
-            JsonSchema::Array {
-                items: Box::new(JsonSchema::String { description: None }),
-                description: Some("The command to execute".to_string()),
-            },
-        ),
-        (
-            "workdir".to_string(),
-            JsonSchema::String {
-                description: Some("The working directory to execute the command in".to_string()),
-            },
-        ),
-        (
-            "timeout_ms".to_string(),
-            JsonSchema::Number {
-                description: Some("The timeout for the command in milliseconds".to_string()),
-            },
-        ),
-    ]);
-    properties.extend(create_approval_parameters(
-        exec_permission_approvals_enabled,
-    ));
-
-    let description = if cfg!(windows) {
-        format!(
-            r#"Runs a Powershell command (Windows) and returns its output. Arguments to `shell` will be passed to CreateProcessW(). Most commands should be prefixed with ["powershell.exe", "-Command"].
-
-Examples of valid command strings:
-
-- ls -a (show hidden): ["powershell.exe", "-Command", "Get-ChildItem -Force"]
-- recursive find by name: ["powershell.exe", "-Command", "Get-ChildItem -Recurse -Filter *.py"]
-- recursive grep: ["powershell.exe", "-Command", "Get-ChildItem -Path C:\\myrepo -Recurse | Select-String -Pattern 'TODO' -CaseSensitive"]
-- ps aux | grep python: ["powershell.exe", "-Command", "Get-Process | Where-Object {{ $_.ProcessName -like '*python*' }}"]
-- setting an env var: ["powershell.exe", "-Command", "$env:FOO='bar'; echo $env:FOO"]
-- running an inline Python script: ["powershell.exe", "-Command", "@'\\nprint('Hello, world!')\\n'@ | python -"]
-
-{}"#,
-            windows_destructive_filesystem_guidance()
-        )
-    } else {
-        r#"Runs a shell command and returns its output.
-- The arguments to `shell` will be passed to execvp(). Most terminal commands should be prefixed with ["bash", "-lc"].
-- Always set the `workdir` param when using the shell function. Do not use `cd` unless absolutely necessary."#
-            .to_string()
-    };
-
-    ToolSpec::Function(ResponsesApiTool {
-        name: "shell".to_string(),
-        description,
-        strict: false,
-        defer_loading: None,
-        parameters: JsonSchema::Object {
-            properties,
-            required: Some(vec!["command".to_string()]),
-            additional_properties: Some(false.into()),
-        },
-        output_schema: None,
-    })
-}
-
-fn create_shell_command_tool(
-    allow_login_shell: bool,
-    exec_permission_approvals_enabled: bool,
-) -> ToolSpec {
-    let mut properties = BTreeMap::from([
-        (
-            "command".to_string(),
-            JsonSchema::String {
-                description: Some(
-                    "The shell script to execute in the user's default shell".to_string(),
-                ),
-            },
-        ),
-        (
-            "workdir".to_string(),
-            JsonSchema::String {
-                description: Some("The working directory to execute the command in".to_string()),
-            },
-        ),
-        (
-            "timeout_ms".to_string(),
-            JsonSchema::Number {
-                description: Some("The timeout for the command in milliseconds".to_string()),
-            },
-        ),
-    ]);
-    if allow_login_shell {
-        properties.insert(
-            "login".to_string(),
-            JsonSchema::Boolean {
-                description: Some(
-                    "Whether to run the shell with login shell semantics. Defaults to true."
-                        .to_string(),
-                ),
-            },
-        );
-    }
-    properties.extend(create_approval_parameters(
-        exec_permission_approvals_enabled,
-    ));
-
-    let description = if cfg!(windows) {
-        format!(
-            r#"Runs a Powershell command (Windows) and returns its output.
-
-Examples of valid command strings:
-
-- ls -a (show hidden): "Get-ChildItem -Force"
-- recursive find by name: "Get-ChildItem -Recurse -Filter *.py"
-- recursive grep: "Get-ChildItem -Path C:\\myrepo -Recurse | Select-String -Pattern 'TODO' -CaseSensitive"
-- ps aux | grep python: "Get-Process | Where-Object {{ $_.ProcessName -like '*python*' }}"
-- setting an env var: "$env:FOO='bar'; echo $env:FOO"
-- running an inline Python script: "@'\\nprint('Hello, world!')\\n'@ | python -"
-
-{}"#,
-            windows_destructive_filesystem_guidance()
-        )
-    } else {
-        r#"Runs a shell command and returns its output.
-- Always set the `workdir` param when using the shell_command function. Do not use `cd` unless absolutely necessary."#
-            .to_string()
-    };
-
-    ToolSpec::Function(ResponsesApiTool {
-        name: "shell_command".to_string(),
-        description,
-        strict: false,
-        defer_loading: None,
-        parameters: JsonSchema::Object {
-            properties,
-            required: Some(vec!["command".to_string()]),
-            additional_properties: Some(false.into()),
-        },
-        output_schema: None,
-    })
-}
-
-fn create_view_image_tool(can_request_original_image_detail: bool) -> ToolSpec {
-    // Support only local filesystem path.
-    let mut properties = BTreeMap::from([(
-        "path".to_string(),
-        JsonSchema::String {
-            description: Some("Local filesystem path to an image file".to_string()),
-        },
-    )]);
-    if can_request_original_image_detail {
-        properties.insert(
-            "detail".to_string(),
-            JsonSchema::String {
-                description: Some(
-                    "Optional detail override. The only supported value is `original`; omit this field for default resized behavior. Use `original` to preserve the file's original resolution instead of resizing to fit. This is important when high-fidelity image perception or precise localization is needed, especially for CUA agents.".to_string(),
-                ),
-            },
-        );
-    }
-
-    ToolSpec::Function(ResponsesApiTool {
-        name: VIEW_IMAGE_TOOL_NAME.to_string(),
-        description: "View a local image from the filesystem (only use if given a full filepath by the user, and the image isn't already attached to the thread context within <image ...> tags)."
-            .to_string(),
-        strict: false,
-        defer_loading: None,
-        parameters: JsonSchema::Object {
-            properties,
-            required: Some(vec!["path".to_string()]),
-            additional_properties: Some(false.into()),
-        },
-        output_schema: Some(serde_json::json!({
-            "type": "object",
-            "properties": {
-                "image_url": {
-                    "type": "string",
-                    "description": "Data URL for the loaded image."
-                },
-                "detail": {
-                    "type": ["string", "null"],
-                    "description": "Image detail hint returned by view_image. Returns `original` when original resolution is preserved, otherwise `null`."
-                }
-            },
-            "required": ["image_url", "detail"],
-            "additionalProperties": false
-        })),
-    })
-}
-
 fn create_collab_input_items_schema() -> JsonSchema {
     let properties = BTreeMap::from([
         (
@@ -1751,35 +1276,6 @@ fn create_request_user_input_tool(
     })
 }
 
-fn create_request_permissions_tool() -> ToolSpec {
-    let mut properties = BTreeMap::new();
-    properties.insert(
-        "reason".to_string(),
-        JsonSchema::String {
-            description: Some(
-                "Optional short explanation for why additional permissions are needed.".to_string(),
-            ),
-        },
-    );
-    properties.insert(
-        "permissions".to_string(),
-        create_request_permissions_schema(),
-    );
-
-    ToolSpec::Function(ResponsesApiTool {
-        name: "request_permissions".to_string(),
-        description: request_permissions_tool_description(),
-        strict: false,
-        defer_loading: None,
-        parameters: JsonSchema::Object {
-            properties,
-            required: Some(vec!["permissions".to_string()]),
-            additional_properties: Some(false.into()),
-        },
-        output_schema: None,
-    })
-}
-
 fn create_close_agent_tool_v1() -> ToolSpec {
     let mut properties = BTreeMap::new();
     properties.insert(
@@ -2485,7 +1981,9 @@ pub(crate) fn build_specs_with_discoverable_tools(
         ConfigShellToolType::Default => {
             push_tool_spec(
                 &mut builder,
-                create_shell_tool(exec_permission_approvals_enabled),
+                create_shell_tool(ShellToolOptions {
+                    exec_permission_approvals_enabled,
+                }),
                 /*supports_parallel_tool_calls*/ true,
                 config.code_mode_enabled,
             );
@@ -2501,10 +1999,10 @@ pub(crate) fn build_specs_with_discoverable_tools(
         ConfigShellToolType::UnifiedExec => {
             push_tool_spec(
                 &mut builder,
-                create_exec_command_tool(
-                    config.allow_login_shell,
+                create_exec_command_tool(CommandToolOptions {
+                    allow_login_shell: config.allow_login_shell,
                     exec_permission_approvals_enabled,
-                ),
+                }),
                 /*supports_parallel_tool_calls*/ true,
                 config.code_mode_enabled,
             );
@@ -2523,10 +2021,10 @@ pub(crate) fn build_specs_with_discoverable_tools(
         ConfigShellToolType::ShellCommand => {
             push_tool_spec(
                 &mut builder,
-                create_shell_command_tool(
-                    config.allow_login_shell,
+                create_shell_command_tool(CommandToolOptions {
+                    allow_login_shell: config.allow_login_shell,
                     exec_permission_approvals_enabled,
-                ),
+                }),
                 /*supports_parallel_tool_calls*/ true,
                 config.code_mode_enabled,
             );
@@ -2605,7 +2103,7 @@ pub(crate) fn build_specs_with_discoverable_tools(
     if config.request_permissions_tool_enabled {
         push_tool_spec(
             &mut builder,
-            create_request_permissions_tool(),
+            create_request_permissions_tool(request_permissions_tool_description()),
             /*supports_parallel_tool_calls*/ false,
             config.code_mode_enabled,
         );
@@ -2748,7 +2246,9 @@ pub(crate) fn build_specs_with_discoverable_tools(
 
     push_tool_spec(
         &mut builder,
-        create_view_image_tool(config.can_request_original_image_detail),
+        create_view_image_tool(ViewImageToolOptions {
+            can_request_original_image_detail: config.can_request_original_image_detail,
+        }),
         /*supports_parallel_tool_calls*/ true,
         config.code_mode_enabled,
     );
diff --git a/codex-rs/core/src/tools/spec_tests.rs b/codex-rs/core/src/tools/spec_tests.rs
index 2a7644eec..62c6009bd 100644
--- a/codex-rs/core/src/tools/spec_tests.rs
+++ b/codex-rs/core/src/tools/spec_tests.rs
@@ -6,14 +6,21 @@ use crate::shell::ShellType;
 use crate::tools::ToolRouter;
 use crate::tools::router::ToolRouterParams;
 use codex_app_server_protocol::AppInfo;
+use codex_protocol::models::VIEW_IMAGE_TOOL_NAME;
 use codex_protocol::openai_models::InputModality;
 use codex_protocol::openai_models::ModelInfo;
 use codex_protocol::openai_models::ModelsResponse;
 use codex_tools::AdditionalProperties;
+use codex_tools::CommandToolOptions;
 use codex_tools::ConfiguredToolSpec;
 use codex_tools::FreeformTool;
 use codex_tools::ResponsesApiWebSearchFilters;
 use codex_tools::ResponsesApiWebSearchUserLocation;
+use codex_tools::ViewImageToolOptions;
+use codex_tools::create_exec_command_tool;
+use codex_tools::create_request_permissions_tool;
+use codex_tools::create_view_image_tool;
+use codex_tools::create_write_stdin_tool;
 use codex_tools::mcp_tool_to_deferred_responses_api_tool;
 use codex_utils_absolute_path::AbsolutePathBuf;
 use pretty_assertions::assert_eq;
@@ -54,10 +61,6 @@ fn discoverable_connector(id: &str, name: &str, description: &str) -> Discoverab
     }))
 }
 
-fn windows_shell_safety_description() -> String {
-    format!("\n\n{}", super::windows_destructive_filesystem_guidance())
-}
-
 fn search_capable_model_info() -> ModelInfo {
     let config = test_config();
     let mut model_info =
@@ -298,9 +301,10 @@ fn test_full_toolset_specs_for_gpt5_codex_unified_exec_web_search() {
     // Build expected from the same helpers used by the builder.
     let mut expected: BTreeMap<String, ToolSpec> = BTreeMap::from([]);
     for spec in [
-        create_exec_command_tool(
-            /*allow_login_shell*/ true, /*exec_permission_approvals_enabled*/ false,
-        ),
+        create_exec_command_tool(CommandToolOptions {
+            allow_login_shell: true,
+            exec_permission_approvals_enabled: false,
+        }),
         create_write_stdin_tool(),
         PLAN_TOOL.clone(),
         create_request_user_input_tool(CollaborationModesConfig::default()),
@@ -312,7 +316,9 @@ fn test_full_toolset_specs_for_gpt5_codex_unified_exec_web_search() {
             search_context_size: None,
             search_content_types: None,
         },
-        create_view_image_tool(config.can_request_original_image_detail),
+        create_view_image_tool(ViewImageToolOptions {
+            can_request_original_image_detail: config.can_request_original_image_detail,
+        }),
     ] {
         expected.insert(spec.name().to_string(), spec);
     }
@@ -340,7 +346,7 @@ fn test_full_toolset_specs_for_gpt5_codex_unified_exec_web_search() {
     }
 
     if config.exec_permission_approvals_enabled {
-        let spec = create_request_permissions_tool();
+        let spec = create_request_permissions_tool(request_permissions_tool_description());
         expected.insert(spec.name().to_string(), spec);
     }
 
@@ -804,7 +810,7 @@ fn request_permissions_requires_feature_flag() {
     let request_permissions_tool = find_tool(&tools, "request_permissions");
     assert_eq!(
         request_permissions_tool.spec,
-        create_request_permissions_tool()
+        create_request_permissions_tool(request_permissions_tool_description())
     );
 }
 
@@ -2640,177 +2646,6 @@ fn test_mcp_tool_anyof_defaults_to_string() {
     );
 }
 
-#[test]
-fn test_shell_tool() {
-    let tool = super::create_shell_tool(/*exec_permission_approvals_enabled*/ false);
-    let ToolSpec::Function(ResponsesApiTool {
-        description, name, ..
-    }) = &tool
-    else {
-        panic!("expected function tool");
-    };
-    assert_eq!(name, "shell");
-
-    let expected = if cfg!(windows) {
-        r#"Runs a Powershell command (Windows) and returns its output. Arguments to `shell` will be passed to CreateProcessW(). Most commands should be prefixed with ["powershell.exe", "-Command"].
-
-Examples of valid command strings:
-
-- ls -a (show hidden): ["powershell.exe", "-Command", "Get-ChildItem -Force"]
-- recursive find by name: ["powershell.exe", "-Command", "Get-ChildItem -Recurse -Filter *.py"]
-- recursive grep: ["powershell.exe", "-Command", "Get-ChildItem -Path C:\\myrepo -Recurse | Select-String -Pattern 'TODO' -CaseSensitive"]
-- ps aux | grep python: ["powershell.exe", "-Command", "Get-Process | Where-Object { $_.ProcessName -like '*python*' }"]
-- setting an env var: ["powershell.exe", "-Command", "$env:FOO='bar'; echo $env:FOO"]
-- running an inline Python script: ["powershell.exe", "-Command", "@'\\nprint('Hello, world!')\\n'@ | python -"]"#
-                .to_string()
-                + &windows_shell_safety_description()
-    } else {
-        r#"Runs a shell command and returns its output.
-- The arguments to `shell` will be passed to execvp(). Most terminal commands should be prefixed with ["bash", "-lc"].
-- Always set the `workdir` param when using the shell function. Do not use `cd` unless absolutely necessary."#
-                .to_string()
-    };
-    assert_eq!(description, &expected);
-}
-
-#[test]
-fn test_exec_command_tool_windows_description_includes_shell_safety_guidance() {
-    let tool = super::create_exec_command_tool(
-        /*allow_login_shell*/ true, /*exec_permission_approvals_enabled*/ false,
-    );
-    let ToolSpec::Function(ResponsesApiTool {
-        description, name, ..
-    }) = &tool
-    else {
-        panic!("expected function tool");
-    };
-    assert_eq!(name, "exec_command");
-
-    let expected = if cfg!(windows) {
-        format!(
-            "Runs a command in a PTY, returning output or a session ID for ongoing interaction.{}",
-            windows_shell_safety_description()
-        )
-    } else {
-        "Runs a command in a PTY, returning output or a session ID for ongoing interaction."
-            .to_string()
-    };
-    assert_eq!(description, &expected);
-}
-
-#[test]
-fn shell_tool_with_request_permission_includes_additional_permissions() {
-    let tool = super::create_shell_tool(/*exec_permission_approvals_enabled*/ true);
-    let ToolSpec::Function(ResponsesApiTool { parameters, .. }) = tool else {
-        panic!("expected function tool");
-    };
-    let JsonSchema::Object { properties, .. } = parameters else {
-        panic!("expected object parameters");
-    };
-
-    assert!(properties.contains_key("additional_permissions"));
-
-    let Some(JsonSchema::String {
-        description: Some(description),
-    }) = properties.get("sandbox_permissions")
-    else {
-        panic!("expected sandbox_permissions description");
-    };
-    assert!(description.contains("with_additional_permissions"));
-    assert!(description.contains("filesystem or network permissions"));
-
-    let Some(JsonSchema::Object {
-        properties: additional_properties,
-        ..
-    }) = properties.get("additional_permissions")
-    else {
-        panic!("expected additional_permissions schema");
-    };
-    assert!(additional_properties.contains_key("network"));
-    assert!(additional_properties.contains_key("file_system"));
-    assert!(!additional_properties.contains_key("macos"));
-}
-
-#[test]
-fn request_permissions_tool_includes_full_permission_schema() {
-    let tool = super::create_request_permissions_tool();
-    let ToolSpec::Function(ResponsesApiTool { parameters, .. }) = tool else {
-        panic!("expected function tool");
-    };
-    let JsonSchema::Object { properties, .. } = parameters else {
-        panic!("expected object parameters");
-    };
-    let Some(JsonSchema::Object {
-        properties: permission_properties,
-        additional_properties,
-        ..
-    }) = properties.get("permissions")
-    else {
-        panic!("expected permissions object");
-    };
-
-    assert_eq!(additional_properties, &Some(false.into()));
-    assert!(permission_properties.contains_key("network"));
-    assert!(permission_properties.contains_key("file_system"));
-    assert!(!permission_properties.contains_key("macos"));
-
-    let Some(JsonSchema::Object {
-        properties: network_properties,
-        additional_properties,
-        ..
-    }) = permission_properties.get("network")
-    else {
-        panic!("expected network object");
-    };
-    assert_eq!(additional_properties, &Some(false.into()));
-    assert!(network_properties.contains_key("enabled"));
-
-    let Some(JsonSchema::Object {
-        properties: file_system_properties,
-        additional_properties,
-        ..
-    }) = permission_properties.get("file_system")
-    else {
-        panic!("expected file_system object");
-    };
-    assert_eq!(additional_properties, &Some(false.into()));
-    assert!(file_system_properties.contains_key("read"));
-    assert!(file_system_properties.contains_key("write"));
-}
-
-#[test]
-fn test_shell_command_tool() {
-    let tool = super::create_shell_command_tool(
-        /*allow_login_shell*/ true, /*exec_permission_approvals_enabled*/ false,
-    );
-    let ToolSpec::Function(ResponsesApiTool {
-        description, name, ..
-    }) = &tool
-    else {
-        panic!("expected function tool");
-    };
-    assert_eq!(name, "shell_command");
-
-    let expected = if cfg!(windows) {
-        r#"Runs a Powershell command (Windows) and returns its output.
-
-Examples of valid command strings:
-
-- ls -a (show hidden): "Get-ChildItem -Force"
-- recursive find by name: "Get-ChildItem -Recurse -Filter *.py"
-- recursive grep: "Get-ChildItem -Path C:\\myrepo -Recurse | Select-String -Pattern 'TODO' -CaseSensitive"
-- ps aux | grep python: "Get-Process | Where-Object { $_.ProcessName -like '*python*' }"
-- setting an env var: "$env:FOO='bar'; echo $env:FOO"
-- running an inline Python script: "@'\\nprint('Hello, world!')\\n'@ | python -""#
-            .to_string()
-            + &windows_shell_safety_description()
-    } else {
-        r#"Runs a shell command and returns its output.
-- Always set the `workdir` param when using the shell_command function. Do not use `cd` unless absolutely necessary."#.to_string()
-    };
-    assert_eq!(description, &expected);
-}
-
 #[test]
 fn test_get_openai_tools_mcp_tools_with_additional_properties_schema() {
     let config = test_config();
diff --git a/codex-rs/tools/README.md b/codex-rs/tools/README.md
index 29eeea266..f8eec8ac6 100644
--- a/codex-rs/tools/README.md
+++ b/codex-rs/tools/README.md
@@ -22,6 +22,7 @@ schema and Responses API tool primitives that no longer need to live in
 - `ResponsesApiNamespace`
 - `ResponsesApiNamespaceTool`
 - code-mode `ToolSpec` adapters
+- local host tool spec builders for shell/exec/request-permissions/view-image
 - `parse_tool_input_schema()`
 - `parse_dynamic_tool()`
 - `parse_mcp_tool()`
diff --git a/codex-rs/tools/src/lib.rs b/codex-rs/tools/src/lib.rs
index 08352704c..b806e0538 100644
--- a/codex-rs/tools/src/lib.rs
+++ b/codex-rs/tools/src/lib.rs
@@ -4,10 +4,12 @@
 mod code_mode;
 mod dynamic_tool;
 mod json_schema;
+mod local_tool;
 mod mcp_tool;
 mod responses_api;
 mod tool_definition;
 mod tool_spec;
+mod view_image;
 
 pub use code_mode::augment_tool_spec_for_code_mode;
 pub use code_mode::tool_spec_to_code_mode_tool_definition;
@@ -15,6 +17,13 @@ pub use dynamic_tool::parse_dynamic_tool;
 pub use json_schema::AdditionalProperties;
 pub use json_schema::JsonSchema;
 pub use json_schema::parse_tool_input_schema;
+pub use local_tool::CommandToolOptions;
+pub use local_tool::ShellToolOptions;
+pub use local_tool::create_exec_command_tool;
+pub use local_tool::create_request_permissions_tool;
+pub use local_tool::create_shell_command_tool;
+pub use local_tool::create_shell_tool;
+pub use local_tool::create_write_stdin_tool;
 pub use mcp_tool::mcp_call_tool_result_output_schema;
 pub use mcp_tool::parse_mcp_tool;
 pub use responses_api::FreeformTool;
@@ -33,3 +42,5 @@ pub use tool_spec::ResponsesApiWebSearchFilters;
 pub use tool_spec::ResponsesApiWebSearchUserLocation;
 pub use tool_spec::ToolSpec;
 pub use tool_spec::create_tools_json_for_responses_api;
+pub use view_image::ViewImageToolOptions;
+pub use view_image::create_view_image_tool;
diff --git a/codex-rs/tools/src/local_tool.rs b/codex-rs/tools/src/local_tool.rs
new file mode 100644
index 000000000..4b29264ec
--- /dev/null
+++ b/codex-rs/tools/src/local_tool.rs
@@ -0,0 +1,463 @@
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
+use crate::ToolSpec;
+use serde_json::Value;
+use serde_json::json;
+use std::collections::BTreeMap;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct CommandToolOptions {
+    pub allow_login_shell: bool,
+    pub exec_permission_approvals_enabled: bool,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ShellToolOptions {
+    pub exec_permission_approvals_enabled: bool,
+}
+
+pub fn create_exec_command_tool(options: CommandToolOptions) -> ToolSpec {
+    let mut properties = BTreeMap::from([
+        (
+            "cmd".to_string(),
+            JsonSchema::String {
+                description: Some("Shell command to execute.".to_string()),
+            },
+        ),
+        (
+            "workdir".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Optional working directory to run the command in; defaults to the turn cwd."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "shell".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Shell binary to launch. Defaults to the user's default shell.".to_string(),
+                ),
+            },
+        ),
+        (
+            "tty".to_string(),
+            JsonSchema::Boolean {
+                description: Some(
+                    "Whether to allocate a TTY for the command. Defaults to false (plain pipes); set to true to open a PTY and access TTY process."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "yield_time_ms".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "How long to wait (in milliseconds) for output before yielding.".to_string(),
+                ),
+            },
+        ),
+        (
+            "max_output_tokens".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "Maximum number of tokens to return. Excess output will be truncated."
+                        .to_string(),
+                ),
+            },
+        ),
+    ]);
+    if options.allow_login_shell {
+        properties.insert(
+            "login".to_string(),
+            JsonSchema::Boolean {
+                description: Some(
+                    "Whether to run the shell with -l/-i semantics. Defaults to true.".to_string(),
+                ),
+            },
+        );
+    }
+    properties.extend(create_approval_parameters(
+        options.exec_permission_approvals_enabled,
+    ));
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "exec_command".to_string(),
+        description: if cfg!(windows) {
+            format!(
+                "Runs a command in a PTY, returning output or a session ID for ongoing interaction.\n\n{}",
+                windows_destructive_filesystem_guidance()
+            )
+        } else {
+            "Runs a command in a PTY, returning output or a session ID for ongoing interaction."
+                .to_string()
+        },
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["cmd".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: Some(unified_exec_output_schema()),
+    })
+}
+
+pub fn create_write_stdin_tool() -> ToolSpec {
+    let properties = BTreeMap::from([
+        (
+            "session_id".to_string(),
+            JsonSchema::Number {
+                description: Some("Identifier of the running unified exec session.".to_string()),
+            },
+        ),
+        (
+            "chars".to_string(),
+            JsonSchema::String {
+                description: Some("Bytes to write to stdin (may be empty to poll).".to_string()),
+            },
+        ),
+        (
+            "yield_time_ms".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "How long to wait (in milliseconds) for output before yielding.".to_string(),
+                ),
+            },
+        ),
+        (
+            "max_output_tokens".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "Maximum number of tokens to return. Excess output will be truncated."
+                        .to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "write_stdin".to_string(),
+        description:
+            "Writes characters to an existing unified exec session and returns recent output."
+                .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["session_id".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: Some(unified_exec_output_schema()),
+    })
+}
+
+pub fn create_shell_tool(options: ShellToolOptions) -> ToolSpec {
+    let mut properties = BTreeMap::from([
+        (
+            "command".to_string(),
+            JsonSchema::Array {
+                items: Box::new(JsonSchema::String { description: None }),
+                description: Some("The command to execute".to_string()),
+            },
+        ),
+        (
+            "workdir".to_string(),
+            JsonSchema::String {
+                description: Some("The working directory to execute the command in".to_string()),
+            },
+        ),
+        (
+            "timeout_ms".to_string(),
+            JsonSchema::Number {
+                description: Some("The timeout for the command in milliseconds".to_string()),
+            },
+        ),
+    ]);
+    properties.extend(create_approval_parameters(
+        options.exec_permission_approvals_enabled,
+    ));
+
+    let description = if cfg!(windows) {
+        format!(
+            r#"Runs a Powershell command (Windows) and returns its output. Arguments to `shell` will be passed to CreateProcessW(). Most commands should be prefixed with ["powershell.exe", "-Command"].
+
+Examples of valid command strings:
+
+- ls -a (show hidden): ["powershell.exe", "-Command", "Get-ChildItem -Force"]
+- recursive find by name: ["powershell.exe", "-Command", "Get-ChildItem -Recurse -Filter *.py"]
+- recursive grep: ["powershell.exe", "-Command", "Get-ChildItem -Path C:\\myrepo -Recurse | Select-String -Pattern 'TODO' -CaseSensitive"]
+- ps aux | grep python: ["powershell.exe", "-Command", "Get-Process | Where-Object {{ $_.ProcessName -like '*python*' }}"]
+- setting an env var: ["powershell.exe", "-Command", "$env:FOO='bar'; echo $env:FOO"]
+- running an inline Python script: ["powershell.exe", "-Command", "@'\\nprint('Hello, world!')\\n'@ | python -"]
+
+{}"#,
+            windows_destructive_filesystem_guidance()
+        )
+    } else {
+        r#"Runs a shell command and returns its output.
+- The arguments to `shell` will be passed to execvp(). Most terminal commands should be prefixed with ["bash", "-lc"].
+- Always set the `workdir` param when using the shell function. Do not use `cd` unless absolutely necessary."#
+            .to_string()
+    };
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "shell".to_string(),
+        description,
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["command".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}
+
+pub fn create_shell_command_tool(options: CommandToolOptions) -> ToolSpec {
+    let mut properties = BTreeMap::from([
+        (
+            "command".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "The shell script to execute in the user's default shell".to_string(),
+                ),
+            },
+        ),
+        (
+            "workdir".to_string(),
+            JsonSchema::String {
+                description: Some("The working directory to execute the command in".to_string()),
+            },
+        ),
+        (
+            "timeout_ms".to_string(),
+            JsonSchema::Number {
+                description: Some("The timeout for the command in milliseconds".to_string()),
+            },
+        ),
+    ]);
+    if options.allow_login_shell {
+        properties.insert(
+            "login".to_string(),
+            JsonSchema::Boolean {
+                description: Some(
+                    "Whether to run the shell with login shell semantics. Defaults to true."
+                        .to_string(),
+                ),
+            },
+        );
+    }
+    properties.extend(create_approval_parameters(
+        options.exec_permission_approvals_enabled,
+    ));
+
+    let description = if cfg!(windows) {
+        format!(
+            r#"Runs a Powershell command (Windows) and returns its output.
+
+Examples of valid command strings:
+
+- ls -a (show hidden): "Get-ChildItem -Force"
+- recursive find by name: "Get-ChildItem -Recurse -Filter *.py"
+- recursive grep: "Get-ChildItem -Path C:\\myrepo -Recurse | Select-String -Pattern 'TODO' -CaseSensitive"
+- ps aux | grep python: "Get-Process | Where-Object {{ $_.ProcessName -like '*python*' }}"
+- setting an env var: "$env:FOO='bar'; echo $env:FOO"
+- running an inline Python script: "@'\\nprint('Hello, world!')\\n'@ | python -"
+
+{}"#,
+            windows_destructive_filesystem_guidance()
+        )
+    } else {
+        r#"Runs a shell command and returns its output.
+- Always set the `workdir` param when using the shell_command function. Do not use `cd` unless absolutely necessary."#
+            .to_string()
+    };
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "shell_command".to_string(),
+        description,
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["command".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}
+
+pub fn create_request_permissions_tool(description: String) -> ToolSpec {
+    let properties = BTreeMap::from([
+        (
+            "reason".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Optional short explanation for why additional permissions are needed."
+                        .to_string(),
+                ),
+            },
+        ),
+        ("permissions".to_string(), permission_profile_schema()),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "request_permissions".to_string(),
+        description,
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["permissions".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}
+
+fn unified_exec_output_schema() -> Value {
+    json!({
+        "type": "object",
+        "properties": {
+            "chunk_id": {
+                "type": "string",
+                "description": "Chunk identifier included when the response reports one."
+            },
+            "wall_time_seconds": {
+                "type": "number",
+                "description": "Elapsed wall time spent waiting for output in seconds."
+            },
+            "exit_code": {
+                "type": "number",
+                "description": "Process exit code when the command finished during this call."
+            },
+            "session_id": {
+                "type": "number",
+                "description": "Session identifier to pass to write_stdin when the process is still running."
+            },
+            "original_token_count": {
+                "type": "number",
+                "description": "Approximate token count before output truncation."
+            },
+            "output": {
+                "type": "string",
+                "description": "Command output text, possibly truncated."
+            }
+        },
+        "required": ["wall_time_seconds", "output"],
+        "additionalProperties": false
+    })
+}
+
+fn create_approval_parameters(
+    exec_permission_approvals_enabled: bool,
+) -> BTreeMap<String, JsonSchema> {
+    let mut properties = BTreeMap::from([
+        (
+            "sandbox_permissions".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    if exec_permission_approvals_enabled {
+                        "Sandbox permissions for the command. Use \"with_additional_permissions\" to request additional sandboxed filesystem or network permissions (preferred), or \"require_escalated\" to request running without sandbox restrictions; defaults to \"use_default\"."
+                    } else {
+                        "Sandbox permissions for the command. Set to \"require_escalated\" to request running without sandbox restrictions; defaults to \"use_default\"."
+                    }
+                    .to_string(),
+                ),
+            },
+        ),
+        (
+            "justification".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    r#"Only set if sandbox_permissions is \"require_escalated\".
+                    Request approval from the user to run this command outside the sandbox.
+                    Phrased as a simple question that summarizes the purpose of the
+                    command as it relates to the task at hand - e.g. 'Do you want to
+                    fetch and pull the latest version of this git branch?'"#
+                    .to_string(),
+                ),
+            },
+        ),
+        (
+            "prefix_rule".to_string(),
+            JsonSchema::Array {
+                items: Box::new(JsonSchema::String { description: None }),
+                description: Some(
+                    r#"Only specify when sandbox_permissions is `require_escalated`.
+                        Suggest a prefix command pattern that will allow you to fulfill similar requests from the user in the future.
+                        Should be a short but reasonable prefix, e.g. [\"git\", \"pull\"] or [\"uv\", \"run\"] or [\"pytest\"]."#.to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    if exec_permission_approvals_enabled {
+        properties.insert(
+            "additional_permissions".to_string(),
+            permission_profile_schema(),
+        );
+    }
+
+    properties
+}
+
+fn permission_profile_schema() -> JsonSchema {
+    JsonSchema::Object {
+        properties: BTreeMap::from([
+            ("network".to_string(), network_permissions_schema()),
+            ("file_system".to_string(), file_system_permissions_schema()),
+        ]),
+        required: None,
+        additional_properties: Some(false.into()),
+    }
+}
+
+fn network_permissions_schema() -> JsonSchema {
+    JsonSchema::Object {
+        properties: BTreeMap::from([(
+            "enabled".to_string(),
+            JsonSchema::Boolean {
+                description: Some("Set to true to request network access.".to_string()),
+            },
+        )]),
+        required: None,
+        additional_properties: Some(false.into()),
+    }
+}
+
+fn file_system_permissions_schema() -> JsonSchema {
+    JsonSchema::Object {
+        properties: BTreeMap::from([
+            (
+                "read".to_string(),
+                JsonSchema::Array {
+                    items: Box::new(JsonSchema::String { description: None }),
+                    description: Some("Absolute paths to grant read access to.".to_string()),
+                },
+            ),
+            (
+                "write".to_string(),
+                JsonSchema::Array {
+                    items: Box::new(JsonSchema::String { description: None }),
+                    description: Some("Absolute paths to grant write access to.".to_string()),
+                },
+            ),
+        ]),
+        required: None,
+        additional_properties: Some(false.into()),
+    }
+}
+
+fn windows_destructive_filesystem_guidance() -> &'static str {
+    r#"Windows safety rules:
+- Do not compose destructive filesystem commands across shells. Do not enumerate paths in PowerShell and then pass them to `cmd /c`, batch builtins, or another shell for deletion or moving. Use one shell end-to-end, prefer native PowerShell cmdlets such as `Remove-Item` / `Move-Item` with `-LiteralPath`, and avoid string-built shell commands for file operations.
+- Before any recursive delete or move on Windows, verify the resolved absolute target paths stay within the intended workspace or explicitly named target directory. Never issue a recursive delete or move against a computed path if the final target has not been checked."#
+}
+
+#[cfg(test)]
+#[path = "local_tool_tests.rs"]
+mod tests;
diff --git a/codex-rs/tools/src/local_tool_tests.rs b/codex-rs/tools/src/local_tool_tests.rs
new file mode 100644
index 000000000..a8a914001
--- /dev/null
+++ b/codex-rs/tools/src/local_tool_tests.rs
@@ -0,0 +1,442 @@
+use super::*;
+use pretty_assertions::assert_eq;
+use std::collections::BTreeMap;
+
+fn windows_shell_safety_description() -> String {
+    format!("\n\n{}", windows_destructive_filesystem_guidance())
+}
+
+#[test]
+fn shell_tool_matches_expected_spec() {
+    let tool = create_shell_tool(ShellToolOptions {
+        exec_permission_approvals_enabled: false,
+    });
+
+    let description = if cfg!(windows) {
+        r#"Runs a Powershell command (Windows) and returns its output. Arguments to `shell` will be passed to CreateProcessW(). Most commands should be prefixed with ["powershell.exe", "-Command"].
+
+Examples of valid command strings:
+
+- ls -a (show hidden): ["powershell.exe", "-Command", "Get-ChildItem -Force"]
+- recursive find by name: ["powershell.exe", "-Command", "Get-ChildItem -Recurse -Filter *.py"]
+- recursive grep: ["powershell.exe", "-Command", "Get-ChildItem -Path C:\\myrepo -Recurse | Select-String -Pattern 'TODO' -CaseSensitive"]
+- ps aux | grep python: ["powershell.exe", "-Command", "Get-Process | Where-Object { $_.ProcessName -like '*python*' }"]
+- setting an env var: ["powershell.exe", "-Command", "$env:FOO='bar'; echo $env:FOO"]
+- running an inline Python script: ["powershell.exe", "-Command", "@'\\nprint('Hello, world!')\\n'@ | python -"]"#
+            .to_string()
+            + &windows_shell_safety_description()
+    } else {
+        r#"Runs a shell command and returns its output.
+- The arguments to `shell` will be passed to execvp(). Most terminal commands should be prefixed with ["bash", "-lc"].
+- Always set the `workdir` param when using the shell function. Do not use `cd` unless absolutely necessary."#
+            .to_string()
+    };
+
+    let properties = BTreeMap::from([
+        (
+            "command".to_string(),
+            JsonSchema::Array {
+                items: Box::new(JsonSchema::String { description: None }),
+                description: Some("The command to execute".to_string()),
+            },
+        ),
+        (
+            "workdir".to_string(),
+            JsonSchema::String {
+                description: Some("The working directory to execute the command in".to_string()),
+            },
+        ),
+        (
+            "timeout_ms".to_string(),
+            JsonSchema::Number {
+                description: Some("The timeout for the command in milliseconds".to_string()),
+            },
+        ),
+        (
+            "sandbox_permissions".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Sandbox permissions for the command. Set to \"require_escalated\" to request running without sandbox restrictions; defaults to \"use_default\"."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "justification".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    r#"Only set if sandbox_permissions is \"require_escalated\".
+                    Request approval from the user to run this command outside the sandbox.
+                    Phrased as a simple question that summarizes the purpose of the
+                    command as it relates to the task at hand - e.g. 'Do you want to
+                    fetch and pull the latest version of this git branch?'"#
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "prefix_rule".to_string(),
+            JsonSchema::Array {
+                items: Box::new(JsonSchema::String { description: None }),
+                description: Some(
+                    r#"Only specify when sandbox_permissions is `require_escalated`.
+                        Suggest a prefix command pattern that will allow you to fulfill similar requests from the user in the future.
+                        Should be a short but reasonable prefix, e.g. [\"git\", \"pull\"] or [\"uv\", \"run\"] or [\"pytest\"]."#
+                        .to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    assert_eq!(
+        tool,
+        ToolSpec::Function(ResponsesApiTool {
+            name: "shell".to_string(),
+            description,
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties,
+                required: Some(vec!["command".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}
+
+#[test]
+fn exec_command_tool_matches_expected_spec() {
+    let tool = create_exec_command_tool(CommandToolOptions {
+        allow_login_shell: true,
+        exec_permission_approvals_enabled: false,
+    });
+
+    let description = if cfg!(windows) {
+        format!(
+            "Runs a command in a PTY, returning output or a session ID for ongoing interaction.{}",
+            windows_shell_safety_description()
+        )
+    } else {
+        "Runs a command in a PTY, returning output or a session ID for ongoing interaction."
+            .to_string()
+    };
+
+    let mut properties = BTreeMap::from([
+        (
+            "cmd".to_string(),
+            JsonSchema::String {
+                description: Some("Shell command to execute.".to_string()),
+            },
+        ),
+        (
+            "workdir".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Optional working directory to run the command in; defaults to the turn cwd."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "shell".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Shell binary to launch. Defaults to the user's default shell.".to_string(),
+                ),
+            },
+        ),
+        (
+            "tty".to_string(),
+            JsonSchema::Boolean {
+                description: Some(
+                    "Whether to allocate a TTY for the command. Defaults to false (plain pipes); set to true to open a PTY and access TTY process."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "yield_time_ms".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "How long to wait (in milliseconds) for output before yielding.".to_string(),
+                ),
+            },
+        ),
+        (
+            "max_output_tokens".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "Maximum number of tokens to return. Excess output will be truncated."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "login".to_string(),
+            JsonSchema::Boolean {
+                description: Some(
+                    "Whether to run the shell with -l/-i semantics. Defaults to true.".to_string(),
+                ),
+            },
+        ),
+    ]);
+    properties.extend(create_approval_parameters(
+        /*exec_permission_approvals_enabled*/ false,
+    ));
+
+    assert_eq!(
+        tool,
+        ToolSpec::Function(ResponsesApiTool {
+            name: "exec_command".to_string(),
+            description,
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties,
+                required: Some(vec!["cmd".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: Some(unified_exec_output_schema()),
+        })
+    );
+}
+
+#[test]
+fn write_stdin_tool_matches_expected_spec() {
+    let tool = create_write_stdin_tool();
+
+    let properties = BTreeMap::from([
+        (
+            "session_id".to_string(),
+            JsonSchema::Number {
+                description: Some("Identifier of the running unified exec session.".to_string()),
+            },
+        ),
+        (
+            "chars".to_string(),
+            JsonSchema::String {
+                description: Some("Bytes to write to stdin (may be empty to poll).".to_string()),
+            },
+        ),
+        (
+            "yield_time_ms".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "How long to wait (in milliseconds) for output before yielding.".to_string(),
+                ),
+            },
+        ),
+        (
+            "max_output_tokens".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "Maximum number of tokens to return. Excess output will be truncated."
+                        .to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    assert_eq!(
+        tool,
+        ToolSpec::Function(ResponsesApiTool {
+            name: "write_stdin".to_string(),
+            description:
+                "Writes characters to an existing unified exec session and returns recent output."
+                    .to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties,
+                required: Some(vec!["session_id".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: Some(unified_exec_output_schema()),
+        })
+    );
+}
+
+#[test]
+fn shell_tool_with_request_permission_includes_additional_permissions() {
+    let tool = create_shell_tool(ShellToolOptions {
+        exec_permission_approvals_enabled: true,
+    });
+
+    let mut properties = BTreeMap::from([
+        (
+            "command".to_string(),
+            JsonSchema::Array {
+                items: Box::new(JsonSchema::String { description: None }),
+                description: Some("The command to execute".to_string()),
+            },
+        ),
+        (
+            "workdir".to_string(),
+            JsonSchema::String {
+                description: Some("The working directory to execute the command in".to_string()),
+            },
+        ),
+        (
+            "timeout_ms".to_string(),
+            JsonSchema::Number {
+                description: Some("The timeout for the command in milliseconds".to_string()),
+            },
+        ),
+    ]);
+    properties.extend(create_approval_parameters(
+        /*exec_permission_approvals_enabled*/ true,
+    ));
+
+    let description = if cfg!(windows) {
+        format!(
+            r#"Runs a Powershell command (Windows) and returns its output. Arguments to `shell` will be passed to CreateProcessW(). Most commands should be prefixed with ["powershell.exe", "-Command"].
+
+Examples of valid command strings:
+
+- ls -a (show hidden): ["powershell.exe", "-Command", "Get-ChildItem -Force"]
+- recursive find by name: ["powershell.exe", "-Command", "Get-ChildItem -Recurse -Filter *.py"]
+- recursive grep: ["powershell.exe", "-Command", "Get-ChildItem -Path C:\\myrepo -Recurse | Select-String -Pattern 'TODO' -CaseSensitive"]
+- ps aux | grep python: ["powershell.exe", "-Command", "Get-Process | Where-Object {{ $_.ProcessName -like '*python*' }}"]
+- setting an env var: ["powershell.exe", "-Command", "$env:FOO='bar'; echo $env:FOO"]
+- running an inline Python script: ["powershell.exe", "-Command", "@'\\nprint('Hello, world!')\\n'@ | python -"]
+
+{}"#,
+            windows_destructive_filesystem_guidance()
+        )
+    } else {
+        r#"Runs a shell command and returns its output.
+- The arguments to `shell` will be passed to execvp(). Most terminal commands should be prefixed with ["bash", "-lc"].
+- Always set the `workdir` param when using the shell function. Do not use `cd` unless absolutely necessary."#
+            .to_string()
+    };
+
+    assert_eq!(
+        tool,
+        ToolSpec::Function(ResponsesApiTool {
+            name: "shell".to_string(),
+            description,
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties,
+                required: Some(vec!["command".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}
+
+#[test]
+fn request_permissions_tool_includes_full_permission_schema() {
+    let tool =
+        create_request_permissions_tool("Request extra permissions for this turn.".to_string());
+
+    let properties = BTreeMap::from([
+        (
+            "reason".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Optional short explanation for why additional permissions are needed."
+                        .to_string(),
+                ),
+            },
+        ),
+        ("permissions".to_string(), permission_profile_schema()),
+    ]);
+
+    assert_eq!(
+        tool,
+        ToolSpec::Function(ResponsesApiTool {
+            name: "request_permissions".to_string(),
+            description: "Request extra permissions for this turn.".to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties,
+                required: Some(vec!["permissions".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}
+
+#[test]
+fn shell_command_tool_matches_expected_spec() {
+    let tool = create_shell_command_tool(CommandToolOptions {
+        allow_login_shell: true,
+        exec_permission_approvals_enabled: false,
+    });
+
+    let description = if cfg!(windows) {
+        r#"Runs a Powershell command (Windows) and returns its output.
+
+Examples of valid command strings:
+
+- ls -a (show hidden): "Get-ChildItem -Force"
+- recursive find by name: "Get-ChildItem -Recurse -Filter *.py"
+- recursive grep: "Get-ChildItem -Path C:\\myrepo -Recurse | Select-String -Pattern 'TODO' -CaseSensitive"
+- ps aux | grep python: "Get-Process | Where-Object { $_.ProcessName -like '*python*' }"
+- setting an env var: "$env:FOO='bar'; echo $env:FOO"
+- running an inline Python script: "@'\\nprint('Hello, world!')\\n'@ | python -""#
+            .to_string()
+            + &windows_shell_safety_description()
+    } else {
+        r#"Runs a shell command and returns its output.
+- Always set the `workdir` param when using the shell_command function. Do not use `cd` unless absolutely necessary."#
+            .to_string()
+    };
+
+    let mut properties = BTreeMap::from([
+        (
+            "command".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "The shell script to execute in the user's default shell".to_string(),
+                ),
+            },
+        ),
+        (
+            "workdir".to_string(),
+            JsonSchema::String {
+                description: Some("The working directory to execute the command in".to_string()),
+            },
+        ),
+        (
+            "timeout_ms".to_string(),
+            JsonSchema::Number {
+                description: Some("The timeout for the command in milliseconds".to_string()),
+            },
+        ),
+        (
+            "login".to_string(),
+            JsonSchema::Boolean {
+                description: Some(
+                    "Whether to run the shell with login shell semantics. Defaults to true."
+                        .to_string(),
+                ),
+            },
+        ),
+    ]);
+    properties.extend(create_approval_parameters(
+        /*exec_permission_approvals_enabled*/ false,
+    ));
+
+    assert_eq!(
+        tool,
+        ToolSpec::Function(ResponsesApiTool {
+            name: "shell_command".to_string(),
+            description,
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties,
+                required: Some(vec!["command".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}
diff --git a/codex-rs/tools/src/view_image.rs b/codex-rs/tools/src/view_image.rs
new file mode 100644
index 000000000..a6881674b
--- /dev/null
+++ b/codex-rs/tools/src/view_image.rs
@@ -0,0 +1,67 @@
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
+use crate::ToolSpec;
+use codex_protocol::models::VIEW_IMAGE_TOOL_NAME;
+use serde_json::Value;
+use serde_json::json;
+use std::collections::BTreeMap;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ViewImageToolOptions {
+    pub can_request_original_image_detail: bool,
+}
+
+pub fn create_view_image_tool(options: ViewImageToolOptions) -> ToolSpec {
+    let mut properties = BTreeMap::from([(
+        "path".to_string(),
+        JsonSchema::String {
+            description: Some("Local filesystem path to an image file".to_string()),
+        },
+    )]);
+    if options.can_request_original_image_detail {
+        properties.insert(
+            "detail".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Optional detail override. The only supported value is `original`; omit this field for default resized behavior. Use `original` to preserve the file's original resolution instead of resizing to fit. This is important when high-fidelity image perception or precise localization is needed, especially for CUA agents.".to_string(),
+                ),
+            },
+        );
+    }
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: VIEW_IMAGE_TOOL_NAME.to_string(),
+        description: "View a local image from the filesystem (only use if given a full filepath by the user, and the image isn't already attached to the thread context within <image ...> tags)."
+            .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["path".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: Some(view_image_output_schema()),
+    })
+}
+
+fn view_image_output_schema() -> Value {
+    json!({
+        "type": "object",
+        "properties": {
+            "image_url": {
+                "type": "string",
+                "description": "Data URL for the loaded image."
+            },
+            "detail": {
+                "type": ["string", "null"],
+                "description": "Image detail hint returned by view_image. Returns `original` when original resolution is preserved, otherwise `null`."
+            }
+        },
+        "required": ["image_url", "detail"],
+        "additionalProperties": false
+    })
+}
+
+#[cfg(test)]
+#[path = "view_image_tests.rs"]
+mod tests;
diff --git a/codex-rs/tools/src/view_image_tests.rs b/codex-rs/tools/src/view_image_tests.rs
new file mode 100644
index 000000000..75be84a6a
--- /dev/null
+++ b/codex-rs/tools/src/view_image_tests.rs
@@ -0,0 +1,67 @@
+use super::*;
+use pretty_assertions::assert_eq;
+use std::collections::BTreeMap;
+
+#[test]
+fn view_image_tool_omits_detail_without_original_detail_feature() {
+    assert_eq!(
+        create_view_image_tool(ViewImageToolOptions {
+            can_request_original_image_detail: false,
+        }),
+        ToolSpec::Function(ResponsesApiTool {
+            name: "view_image".to_string(),
+            description: "View a local image from the filesystem (only use if given a full filepath by the user, and the image isn't already attached to the thread context within <image ...> tags)."
+                .to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::from([(
+                    "path".to_string(),
+                    JsonSchema::String {
+                        description: Some("Local filesystem path to an image file".to_string()),
+                    },
+                )]),
+                required: Some(vec!["path".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: Some(view_image_output_schema()),
+        })
+    );
+}
+
+#[test]
+fn view_image_tool_includes_detail_with_original_detail_feature() {
+    assert_eq!(
+        create_view_image_tool(ViewImageToolOptions {
+            can_request_original_image_detail: true,
+        }),
+        ToolSpec::Function(ResponsesApiTool {
+            name: "view_image".to_string(),
+            description: "View a local image from the filesystem (only use if given a full filepath by the user, and the image isn't already attached to the thread context within <image ...> tags)."
+                .to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::from([
+                    (
+                        "detail".to_string(),
+                        JsonSchema::String {
+                            description: Some(
+                                "Optional detail override. The only supported value is `original`; omit this field for default resized behavior. Use `original` to preserve the file's original resolution instead of resizing to fit. This is important when high-fidelity image perception or precise localization is needed, especially for CUA agents.".to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "path".to_string(),
+                        JsonSchema::String {
+                            description: Some("Local filesystem path to an image file".to_string()),
+                        },
+                    ),
+                ]),
+                required: Some(vec!["path".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: Some(view_image_output_schema()),
+        })
+    );
+}