codex-tools: extract utility tool specs

codex-rs/core/src/tools/spec.rs

@@ -41,8 +41,6 @@ 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::SpawnAgentToolOptions;
@@ -52,8 +50,15 @@ use codex_tools::augment_tool_spec_for_code_mode;
 use codex_tools::create_assign_task_tool;
 use codex_tools::create_close_agent_tool_v1;
 use codex_tools::create_close_agent_tool_v2;
+use codex_tools::create_code_mode_tool;
 use codex_tools::create_exec_command_tool;
+use codex_tools::create_js_repl_reset_tool;
+use codex_tools::create_js_repl_tool;
 use codex_tools::create_list_agents_tool;
+use codex_tools::create_list_dir_tool;
+use codex_tools::create_list_mcp_resource_templates_tool;
+use codex_tools::create_list_mcp_resources_tool;
+use codex_tools::create_read_mcp_resource_tool;
 use codex_tools::create_report_agent_job_result_tool;
 use codex_tools::create_request_permissions_tool;
 use codex_tools::create_request_user_input_tool;
@@ -65,9 +70,11 @@ use codex_tools::create_shell_tool;
 use codex_tools::create_spawn_agent_tool_v1;
 use codex_tools::create_spawn_agent_tool_v2;
 use codex_tools::create_spawn_agents_on_csv_tool;
+use codex_tools::create_test_sync_tool;
 use codex_tools::create_view_image_tool;
 use codex_tools::create_wait_agent_tool_v1;
 use codex_tools::create_wait_agent_tool_v2;
+use codex_tools::create_wait_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;
@@ -366,125 +373,6 @@ fn supports_image_generation(model_info: &ModelInfo) -> bool {
     model_info.input_modalities.contains(&InputModality::Image)
 }
 
-fn create_wait_tool() -> ToolSpec {
-    let properties = BTreeMap::from([
-        (
-            "cell_id".to_string(),
-            JsonSchema::String {
-                description: Some("Identifier of the running exec cell.".to_string()),
-            },
-        ),
-        (
-            "yield_time_ms".to_string(),
-            JsonSchema::Number {
-                description: Some(
-                    "How long to wait (in milliseconds) for more output before yielding again."
-                        .to_string(),
-                ),
-            },
-        ),
-        (
-            "max_tokens".to_string(),
-            JsonSchema::Number {
-                description: Some(
-                    "Maximum number of output tokens to return for this wait call.".to_string(),
-                ),
-            },
-        ),
-        (
-            "terminate".to_string(),
-            JsonSchema::Boolean {
-                description: Some("Whether to terminate the running exec cell.".to_string()),
-            },
-        ),
-    ]);
-
-    ToolSpec::Function(ResponsesApiTool {
-        name: WAIT_TOOL_NAME.to_string(),
-        description: format!(
-            "Waits on a yielded `{PUBLIC_TOOL_NAME}` cell and returns new output or completion.\n{}",
-            codex_code_mode::build_wait_tool_description().trim()
-        ),
-        strict: false,
-        parameters: JsonSchema::Object {
-            properties,
-            required: Some(vec!["cell_id".to_string()]),
-            additional_properties: Some(false.into()),
-        },
-        output_schema: None,
-        defer_loading: None,
-    })
-}
-
-fn create_test_sync_tool() -> ToolSpec {
-    let barrier_properties = BTreeMap::from([
-        (
-            "id".to_string(),
-            JsonSchema::String {
-                description: Some(
-                    "Identifier shared by concurrent calls that should rendezvous".to_string(),
-                ),
-            },
-        ),
-        (
-            "participants".to_string(),
-            JsonSchema::Number {
-                description: Some(
-                    "Number of tool calls that must arrive before the barrier opens".to_string(),
-                ),
-            },
-        ),
-        (
-            "timeout_ms".to_string(),
-            JsonSchema::Number {
-                description: Some(
-                    "Maximum time in milliseconds to wait at the barrier".to_string(),
-                ),
-            },
-        ),
-    ]);
-
-    let properties = BTreeMap::from([
-        (
-            "sleep_before_ms".to_string(),
-            JsonSchema::Number {
-                description: Some(
-                    "Optional delay in milliseconds before any other action".to_string(),
-                ),
-            },
-        ),
-        (
-            "sleep_after_ms".to_string(),
-            JsonSchema::Number {
-                description: Some(
-                    "Optional delay in milliseconds after completing the barrier".to_string(),
-                ),
-            },
-        ),
-        (
-            "barrier".to_string(),
-            JsonSchema::Object {
-                properties: barrier_properties,
-                required: Some(vec!["id".to_string(), "participants".to_string()]),
-                additional_properties: Some(false.into()),
-            },
-        ),
-    ]);
-
-    ToolSpec::Function(ResponsesApiTool {
-        name: "test_sync_tool".to_string(),
-        description: "Internal synchronization helper used by Codex integration tests.".to_string(),
-        strict: false,
-        defer_loading: None,
-        parameters: JsonSchema::Object {
-            properties,
-            required: None,
-            additional_properties: Some(false.into()),
-        },
-        output_schema: None,
-    })
-}
-
 fn create_tool_search_tool(app_tools: &HashMap<String, ToolInfo>) -> ToolSpec {
     let properties = BTreeMap::from([
         (
@@ -699,241 +587,6 @@ fn format_plugin_summary(plugin: &DiscoverablePluginInfo) -> String {
     }
 }
 
-fn create_list_dir_tool() -> ToolSpec {
-    let properties = BTreeMap::from([
-        (
-            "dir_path".to_string(),
-            JsonSchema::String {
-                description: Some("Absolute path to the directory to list.".to_string()),
-            },
-        ),
-        (
-            "offset".to_string(),
-            JsonSchema::Number {
-                description: Some(
-                    "The entry number to start listing from. Must be 1 or greater.".to_string(),
-                ),
-            },
-        ),
-        (
-            "limit".to_string(),
-            JsonSchema::Number {
-                description: Some("The maximum number of entries to return.".to_string()),
-            },
-        ),
-        (
-            "depth".to_string(),
-            JsonSchema::Number {
-                description: Some(
-                    "The maximum directory depth to traverse. Must be 1 or greater.".to_string(),
-                ),
-            },
-        ),
-    ]);
-
-    ToolSpec::Function(ResponsesApiTool {
-        name: "list_dir".to_string(),
-        description:
-            "Lists entries in a local directory with 1-indexed entry numbers and simple type labels."
-                .to_string(),
-        strict: false,
-        defer_loading: None,
-        parameters: JsonSchema::Object {
-            properties,
-            required: Some(vec!["dir_path".to_string()]),
-            additional_properties: Some(false.into()),
-        },
-        output_schema: None,
-    })
-}
-
-fn create_js_repl_tool() -> ToolSpec {
-    // Keep JS input freeform, but block the most common malformed payload shapes
-    // (JSON wrappers, quoted strings, and markdown fences) before they reach the
-    // runtime `reject_json_or_quoted_source` validation. The API's regex engine
-    // does not support look-around, so this uses a "first significant token"
-    // pattern rather than negative lookaheads.
-    const JS_REPL_FREEFORM_GRAMMAR: &str = r#"
-start: pragma_source | plain_source
-
-pragma_source: PRAGMA_LINE NEWLINE js_source
-plain_source: PLAIN_JS_SOURCE
-
-js_source: JS_SOURCE
-
-PRAGMA_LINE: /[ \t]*\/\/ codex-js-repl:[^\r\n]*/
-NEWLINE: /\r?\n/
-PLAIN_JS_SOURCE: /(?:\s*)(?:[^\s{\"`]|`[^`]|``[^`])[\s\S]*/
-JS_SOURCE: /(?:\s*)(?:[^\s{\"`]|`[^`]|``[^`])[\s\S]*/
-"#;
-
-    ToolSpec::Freeform(FreeformTool {
-        name: "js_repl".to_string(),
-        description: "Runs JavaScript in a persistent Node kernel with top-level await. This is a freeform tool: send raw JavaScript source text, optionally with a first-line pragma like `// codex-js-repl: timeout_ms=15000`; do not send JSON/quotes/markdown fences."
-            .to_string(),
-        format: FreeformToolFormat {
-            r#type: "grammar".to_string(),
-            syntax: "lark".to_string(),
-            definition: JS_REPL_FREEFORM_GRAMMAR.to_string(),
-        },
-    })
-}
-
-fn create_js_repl_reset_tool() -> ToolSpec {
-    ToolSpec::Function(ResponsesApiTool {
-        name: "js_repl_reset".to_string(),
-        description:
-            "Restarts the js_repl kernel for this run and clears persisted top-level bindings."
-                .to_string(),
-        strict: false,
-        defer_loading: None,
-        parameters: JsonSchema::Object {
-            properties: BTreeMap::new(),
-            required: None,
-            additional_properties: Some(false.into()),
-        },
-        output_schema: None,
-    })
-}
-
-fn create_code_mode_tool(
-    enabled_tools: &[(String, String)],
-    code_mode_only_enabled: bool,
-) -> ToolSpec {
-    const CODE_MODE_FREEFORM_GRAMMAR: &str = r#"
-start: pragma_source | plain_source
-pragma_source: PRAGMA_LINE NEWLINE SOURCE
-plain_source: SOURCE
-
-PRAGMA_LINE: /[ \t]*\/\/ @exec:[^\r\n]*/
-NEWLINE: /\r?\n/
-SOURCE: /[\s\S]+/
-"#;
-
-    ToolSpec::Freeform(FreeformTool {
-        name: PUBLIC_TOOL_NAME.to_string(),
-        description: codex_code_mode::build_exec_tool_description(
-            enabled_tools,
-            code_mode_only_enabled,
-        ),
-        format: FreeformToolFormat {
-            r#type: "grammar".to_string(),
-            syntax: "lark".to_string(),
-            definition: CODE_MODE_FREEFORM_GRAMMAR.to_string(),
-        },
-    })
-}
-
-fn create_list_mcp_resources_tool() -> ToolSpec {
-    let properties = BTreeMap::from([
-        (
-            "server".to_string(),
-            JsonSchema::String {
-                description: Some(
-                    "Optional MCP server name. When omitted, lists resources from every configured server."
-                        .to_string(),
-                ),
-            },
-        ),
-        (
-            "cursor".to_string(),
-            JsonSchema::String {
-                description: Some(
-                    "Opaque cursor returned by a previous list_mcp_resources call for the same server."
-                        .to_string(),
-                ),
-            },
-        ),
-    ]);
-
-    ToolSpec::Function(ResponsesApiTool {
-        name: "list_mcp_resources".to_string(),
-        description: "Lists resources provided by MCP servers. Resources allow servers to share data that provides context to language models, such as files, database schemas, or application-specific information. Prefer resources over web search when possible.".to_string(),
-        strict: false,
-        defer_loading: None,
-        parameters: JsonSchema::Object {
-            properties,
-            required: None,
-            additional_properties: Some(false.into()),
-        },
-        output_schema: None,
-    })
-}
-
-fn create_list_mcp_resource_templates_tool() -> ToolSpec {
-    let properties = BTreeMap::from([
-        (
-            "server".to_string(),
-            JsonSchema::String {
-                description: Some(
-                    "Optional MCP server name. When omitted, lists resource templates from all configured servers."
-                        .to_string(),
-                ),
-            },
-        ),
-        (
-            "cursor".to_string(),
-            JsonSchema::String {
-                description: Some(
-                    "Opaque cursor returned by a previous list_mcp_resource_templates call for the same server."
-                        .to_string(),
-                ),
-            },
-        ),
-    ]);
-
-    ToolSpec::Function(ResponsesApiTool {
-        name: "list_mcp_resource_templates".to_string(),
-        description: "Lists resource templates provided by MCP servers. Parameterized resource templates allow servers to share data that takes parameters and provides context to language models, such as files, database schemas, or application-specific information. Prefer resource templates over web search when possible.".to_string(),
-        strict: false,
-        defer_loading: None,
-        parameters: JsonSchema::Object {
-            properties,
-            required: None,
-            additional_properties: Some(false.into()),
-        },
-        output_schema: None,
-    })
-}
-
-fn create_read_mcp_resource_tool() -> ToolSpec {
-    let properties = BTreeMap::from([
-        (
-            "server".to_string(),
-            JsonSchema::String {
-                description: Some(
-                    "MCP server name exactly as configured. Must match the 'server' field returned by list_mcp_resources."
-                        .to_string(),
-                ),
-            },
-        ),
-        (
-            "uri".to_string(),
-            JsonSchema::String {
-                description: Some(
-                    "Resource URI to read. Must be one of the URIs returned by list_mcp_resources."
-                        .to_string(),
-                ),
-            },
-        ),
-    ]);
-
-    ToolSpec::Function(ResponsesApiTool {
-        name: "read_mcp_resource".to_string(),
-        description:
-            "Read a specific resource from an MCP server given the server name and resource URI."
-                .to_string(),
-        strict: false,
-        defer_loading: None,
-        parameters: JsonSchema::Object {
-            properties,
-            required: Some(vec!["server".to_string(), "uri".to_string()]),
-            additional_properties: Some(false.into()),
-        },
-        output_schema: None,
-    })
-}
-
 /// TODO(dylan): deprecate once we get rid of json tool
 #[derive(Serialize, Deserialize)]
 pub(crate) struct ApplyPatchToolArgs {

codex-rs/core/src/tools/spec_tests.rs

@@ -1049,21 +1049,6 @@ fn image_generation_tools_require_feature_and_supported_model() {
     );
 }
 
-#[test]
-fn js_repl_freeform_grammar_blocks_common_non_js_prefixes() {
-    let ToolSpec::Freeform(FreeformTool { format, .. }) = create_js_repl_tool() else {
-        panic!("js_repl should use a freeform tool spec");
-    };
-
-    assert_eq!(format.syntax, "lark");
-    assert!(format.definition.contains("PRAGMA_LINE"));
-    assert!(format.definition.contains("`[^`]"));
-    assert!(format.definition.contains("``[^`]"));
-    assert!(format.definition.contains("PLAIN_JS_SOURCE"));
-    assert!(format.definition.contains("codex-js-repl:"));
-    assert!(!format.definition.contains("(?!"));
-}
-
 fn assert_model_tools(
     model_slug: &str,
     features: &Features,

codex-rs/tools/README.md

@@ -21,7 +21,9 @@ schema and Responses API tool primitives that no longer need to live in
 - `ResponsesApiWebSearchUserLocation`
 - `ResponsesApiNamespace`
 - `ResponsesApiNamespaceTool`
-- code-mode `ToolSpec` adapters
+- code-mode `ToolSpec` adapters and `exec` / `wait` spec builders
+- JS REPL spec builders
+- MCP resource, `list_dir`, 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

codex-rs/tools/src/code_mode.rs

@@ -1,6 +1,11 @@
+use crate::FreeformTool;
+use crate::FreeformToolFormat;
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
 use crate::ToolSpec;
 use codex_code_mode::CodeModeToolKind;
 use codex_code_mode::ToolDefinition as CodeModeToolDefinition;
+use std::collections::BTreeMap;
 
 /// Augment tool descriptions with code-mode-specific exec samples.
 pub fn augment_tool_spec_for_code_mode(spec: ToolSpec) -> ToolSpec {
@@ -32,6 +37,85 @@ pub fn tool_spec_to_code_mode_tool_definition(spec: &ToolSpec) -> Option<CodeMod
         .then(|| codex_code_mode::augment_tool_definition(definition))
 }
 
+pub fn create_wait_tool() -> ToolSpec {
+    let properties = BTreeMap::from([
+        (
+            "cell_id".to_string(),
+            JsonSchema::String {
+                description: Some("Identifier of the running exec cell.".to_string()),
+            },
+        ),
+        (
+            "yield_time_ms".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "How long to wait (in milliseconds) for more output before yielding again."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "max_tokens".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "Maximum number of output tokens to return for this wait call.".to_string(),
+                ),
+            },
+        ),
+        (
+            "terminate".to_string(),
+            JsonSchema::Boolean {
+                description: Some("Whether to terminate the running exec cell.".to_string()),
+            },
+        ),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: codex_code_mode::WAIT_TOOL_NAME.to_string(),
+        description: format!(
+            "Waits on a yielded `{}` cell and returns new output or completion.\n{}",
+            codex_code_mode::PUBLIC_TOOL_NAME,
+            codex_code_mode::build_wait_tool_description().trim()
+        ),
+        strict: false,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["cell_id".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+        defer_loading: None,
+    })
+}
+
+pub fn create_code_mode_tool(
+    enabled_tools: &[(String, String)],
+    code_mode_only_enabled: bool,
+) -> ToolSpec {
+    const CODE_MODE_FREEFORM_GRAMMAR: &str = r#"
+start: pragma_source | plain_source
+pragma_source: PRAGMA_LINE NEWLINE SOURCE
+plain_source: SOURCE
+
+PRAGMA_LINE: /[ \t]*\/\/ @exec:[^\r\n]*/
+NEWLINE: /\r?\n/
+SOURCE: /[\s\S]+/
+"#;
+
+    ToolSpec::Freeform(FreeformTool {
+        name: codex_code_mode::PUBLIC_TOOL_NAME.to_string(),
+        description: codex_code_mode::build_exec_tool_description(
+            enabled_tools,
+            code_mode_only_enabled,
+        ),
+        format: FreeformToolFormat {
+            r#type: "grammar".to_string(),
+            syntax: "lark".to_string(),
+            definition: CODE_MODE_FREEFORM_GRAMMAR.to_string(),
+        },
+    })
+}
+
 fn code_mode_tool_definition_for_spec(spec: &ToolSpec) -> Option<CodeModeToolDefinition> {
     match spec {
         ToolSpec::Function(tool) => Some(CodeModeToolDefinition {

codex-rs/tools/src/code_mode_tests.rs

@@ -1,4 +1,6 @@
 use super::augment_tool_spec_for_code_mode;
+use super::create_code_mode_tool;
+use super::create_wait_tool;
 use super::tool_spec_to_code_mode_tool_definition;
 use crate::AdditionalProperties;
 use crate::FreeformTool;
@@ -121,3 +123,89 @@ fn tool_spec_to_code_mode_tool_definition_skips_unsupported_variants() {
         None
     );
 }
+
+#[test]
+fn create_wait_tool_matches_expected_spec() {
+    assert_eq!(
+        create_wait_tool(),
+        ToolSpec::Function(ResponsesApiTool {
+            name: codex_code_mode::WAIT_TOOL_NAME.to_string(),
+            description: format!(
+                "Waits on a yielded `{}` cell and returns new output or completion.\n{}",
+                codex_code_mode::PUBLIC_TOOL_NAME,
+                codex_code_mode::build_wait_tool_description().trim()
+            ),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::from([
+                    (
+                        "cell_id".to_string(),
+                        JsonSchema::String {
+                            description: Some("Identifier of the running exec cell.".to_string()),
+                        },
+                    ),
+                    (
+                        "max_tokens".to_string(),
+                        JsonSchema::Number {
+                            description: Some(
+                                "Maximum number of output tokens to return for this wait call."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "terminate".to_string(),
+                        JsonSchema::Boolean {
+                            description: Some(
+                                "Whether to terminate the running exec cell.".to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "yield_time_ms".to_string(),
+                        JsonSchema::Number {
+                            description: Some(
+                                "How long to wait (in milliseconds) for more output before yielding again."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                ]),
+                required: Some(vec!["cell_id".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}
+
+#[test]
+fn create_code_mode_tool_matches_expected_spec() {
+    let enabled_tools = vec![("update_plan".to_string(), "Update the plan".to_string())];
+
+    assert_eq!(
+        create_code_mode_tool(&enabled_tools, /*code_mode_only_enabled*/ true),
+        ToolSpec::Freeform(FreeformTool {
+            name: codex_code_mode::PUBLIC_TOOL_NAME.to_string(),
+            description: codex_code_mode::build_exec_tool_description(
+                &enabled_tools,
+                /*code_mode_only*/ true
+            ),
+            format: FreeformToolFormat {
+                r#type: "grammar".to_string(),
+                syntax: "lark".to_string(),
+                definition: r#"
+start: pragma_source | plain_source
+pragma_source: PRAGMA_LINE NEWLINE SOURCE
+plain_source: SOURCE
+
+PRAGMA_LINE: /[ \t]*\/\/ @exec:[^\r\n]*/
+NEWLINE: /\r?\n/
+SOURCE: /[\s\S]+/
+"#
+                .to_string(),
+            },
+        })
+    );
+}

codex-rs/tools/src/js_repl_tool.rs

@@ -0,0 +1,59 @@
+use crate::FreeformTool;
+use crate::FreeformToolFormat;
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
+use crate::ToolSpec;
+use std::collections::BTreeMap;
+
+pub fn create_js_repl_tool() -> ToolSpec {
+    // Keep JS input freeform, but block the most common malformed payload shapes
+    // (JSON wrappers, quoted strings, and markdown fences) before they reach the
+    // runtime `reject_json_or_quoted_source` validation. The API's regex engine
+    // does not support look-around, so this uses a "first significant token"
+    // pattern rather than negative lookaheads.
+    const JS_REPL_FREEFORM_GRAMMAR: &str = r#"
+start: pragma_source | plain_source
+
+pragma_source: PRAGMA_LINE NEWLINE js_source
+plain_source: PLAIN_JS_SOURCE
+
+js_source: JS_SOURCE
+
+PRAGMA_LINE: /[ \t]*\/\/ codex-js-repl:[^\r\n]*/
+NEWLINE: /\r?\n/
+PLAIN_JS_SOURCE: /(?:\s*)(?:[^\s{\"`]|`[^`]|``[^`])[\s\S]*/
+JS_SOURCE: /(?:\s*)(?:[^\s{\"`]|`[^`]|``[^`])[\s\S]*/
+"#;
+
+    ToolSpec::Freeform(FreeformTool {
+        name: "js_repl".to_string(),
+        description: "Runs JavaScript in a persistent Node kernel with top-level await. This is a freeform tool: send raw JavaScript source text, optionally with a first-line pragma like `// codex-js-repl: timeout_ms=15000`; do not send JSON/quotes/markdown fences."
+            .to_string(),
+        format: FreeformToolFormat {
+            r#type: "grammar".to_string(),
+            syntax: "lark".to_string(),
+            definition: JS_REPL_FREEFORM_GRAMMAR.to_string(),
+        },
+    })
+}
+
+pub fn create_js_repl_reset_tool() -> ToolSpec {
+    ToolSpec::Function(ResponsesApiTool {
+        name: "js_repl_reset".to_string(),
+        description:
+            "Restarts the js_repl kernel for this run and clears persisted top-level bindings."
+                .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties: BTreeMap::new(),
+            required: None,
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}
+
+#[cfg(test)]
+#[path = "js_repl_tool_tests.rs"]
+mod tests;

codex-rs/tools/src/js_repl_tool_tests.rs

@@ -0,0 +1,40 @@
+use super::*;
+use crate::ToolSpec;
+use pretty_assertions::assert_eq;
+use std::collections::BTreeMap;
+
+#[test]
+fn js_repl_tool_uses_expected_freeform_grammar() {
+    let ToolSpec::Freeform(FreeformTool { format, .. }) = create_js_repl_tool() else {
+        panic!("js_repl should use a freeform tool spec");
+    };
+
+    assert_eq!(format.syntax, "lark");
+    assert!(format.definition.contains("PRAGMA_LINE"));
+    assert!(format.definition.contains("`[^`]"));
+    assert!(format.definition.contains("``[^`]"));
+    assert!(format.definition.contains("PLAIN_JS_SOURCE"));
+    assert!(format.definition.contains("codex-js-repl:"));
+    assert!(!format.definition.contains("(?!"));
+}
+
+#[test]
+fn js_repl_reset_tool_matches_expected_spec() {
+    assert_eq!(
+        create_js_repl_reset_tool(),
+        ToolSpec::Function(ResponsesApiTool {
+            name: "js_repl_reset".to_string(),
+            description:
+                "Restarts the js_repl kernel for this run and clears persisted top-level bindings."
+                    .to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::new(),
+                required: None,
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}

codex-rs/tools/src/lib.rs

@@ -5,13 +5,16 @@ mod agent_job_tool;
 mod agent_tool;
 mod code_mode;
 mod dynamic_tool;
+mod js_repl_tool;
 mod json_schema;
 mod local_tool;
+mod mcp_resource_tool;
 mod mcp_tool;
 mod request_user_input_tool;
 mod responses_api;
 mod tool_definition;
 mod tool_spec;
+mod utility_tool;
 mod view_image;
 
 pub use agent_job_tool::create_report_agent_job_result_tool;
@@ -30,8 +33,12 @@ pub use agent_tool::create_spawn_agent_tool_v2;
 pub use agent_tool::create_wait_agent_tool_v1;
 pub use agent_tool::create_wait_agent_tool_v2;
 pub use code_mode::augment_tool_spec_for_code_mode;
+pub use code_mode::create_code_mode_tool;
+pub use code_mode::create_wait_tool;
 pub use code_mode::tool_spec_to_code_mode_tool_definition;
 pub use dynamic_tool::parse_dynamic_tool;
+pub use js_repl_tool::create_js_repl_reset_tool;
+pub use js_repl_tool::create_js_repl_tool;
 pub use json_schema::AdditionalProperties;
 pub use json_schema::JsonSchema;
 pub use json_schema::parse_tool_input_schema;
@@ -42,6 +49,9 @@ 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_resource_tool::create_list_mcp_resource_templates_tool;
+pub use mcp_resource_tool::create_list_mcp_resources_tool;
+pub use mcp_resource_tool::create_read_mcp_resource_tool;
 pub use mcp_tool::mcp_call_tool_result_output_schema;
 pub use mcp_tool::parse_mcp_tool;
 pub use request_user_input_tool::create_request_user_input_tool;
@@ -61,5 +71,7 @@ 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 utility_tool::create_list_dir_tool;
+pub use utility_tool::create_test_sync_tool;
 pub use view_image::ViewImageToolOptions;
 pub use view_image::create_view_image_tool;

codex-rs/tools/src/mcp_resource_tool.rs

@@ -0,0 +1,118 @@
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
+use crate::ToolSpec;
+use std::collections::BTreeMap;
+
+pub fn create_list_mcp_resources_tool() -> ToolSpec {
+    let properties = BTreeMap::from([
+        (
+            "server".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Optional MCP server name. When omitted, lists resources from every configured server."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "cursor".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Opaque cursor returned by a previous list_mcp_resources call for the same server."
+                        .to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "list_mcp_resources".to_string(),
+        description: "Lists resources provided by MCP servers. Resources allow servers to share data that provides context to language models, such as files, database schemas, or application-specific information. Prefer resources over web search when possible.".to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: None,
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}
+
+pub fn create_list_mcp_resource_templates_tool() -> ToolSpec {
+    let properties = BTreeMap::from([
+        (
+            "server".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Optional MCP server name. When omitted, lists resource templates from all configured servers."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "cursor".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Opaque cursor returned by a previous list_mcp_resource_templates call for the same server."
+                        .to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "list_mcp_resource_templates".to_string(),
+        description: "Lists resource templates provided by MCP servers. Parameterized resource templates allow servers to share data that takes parameters and provides context to language models, such as files, database schemas, or application-specific information. Prefer resource templates over web search when possible.".to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: None,
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}
+
+pub fn create_read_mcp_resource_tool() -> ToolSpec {
+    let properties = BTreeMap::from([
+        (
+            "server".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "MCP server name exactly as configured. Must match the 'server' field returned by list_mcp_resources."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "uri".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Resource URI to read. Must be one of the URIs returned by list_mcp_resources."
+                        .to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "read_mcp_resource".to_string(),
+        description:
+            "Read a specific resource from an MCP server given the server name and resource URI."
+                .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["server".to_string(), "uri".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}
+
+#[cfg(test)]
+#[path = "mcp_resource_tool_tests.rs"]
+mod tests;

codex-rs/tools/src/mcp_resource_tool_tests.rs

@@ -0,0 +1,119 @@
+use super::*;
+use pretty_assertions::assert_eq;
+use std::collections::BTreeMap;
+
+#[test]
+fn list_mcp_resources_tool_matches_expected_spec() {
+    assert_eq!(
+        create_list_mcp_resources_tool(),
+        ToolSpec::Function(ResponsesApiTool {
+            name: "list_mcp_resources".to_string(),
+            description: "Lists resources provided by MCP servers. Resources allow servers to share data that provides context to language models, such as files, database schemas, or application-specific information. Prefer resources over web search when possible.".to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::from([
+                    (
+                        "server".to_string(),
+                        JsonSchema::String {
+                            description: Some(
+                                "Optional MCP server name. When omitted, lists resources from every configured server."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "cursor".to_string(),
+                        JsonSchema::String {
+                            description: Some(
+                                "Opaque cursor returned by a previous list_mcp_resources call for the same server."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                ]),
+                required: None,
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}
+
+#[test]
+fn list_mcp_resource_templates_tool_matches_expected_spec() {
+    assert_eq!(
+        create_list_mcp_resource_templates_tool(),
+        ToolSpec::Function(ResponsesApiTool {
+            name: "list_mcp_resource_templates".to_string(),
+            description: "Lists resource templates provided by MCP servers. Parameterized resource templates allow servers to share data that takes parameters and provides context to language models, such as files, database schemas, or application-specific information. Prefer resource templates over web search when possible.".to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::from([
+                    (
+                        "server".to_string(),
+                        JsonSchema::String {
+                            description: Some(
+                                "Optional MCP server name. When omitted, lists resource templates from all configured servers."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "cursor".to_string(),
+                        JsonSchema::String {
+                            description: Some(
+                                "Opaque cursor returned by a previous list_mcp_resource_templates call for the same server."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                ]),
+                required: None,
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}
+
+#[test]
+fn read_mcp_resource_tool_matches_expected_spec() {
+    assert_eq!(
+        create_read_mcp_resource_tool(),
+        ToolSpec::Function(ResponsesApiTool {
+            name: "read_mcp_resource".to_string(),
+            description:
+                "Read a specific resource from an MCP server given the server name and resource URI."
+                    .to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::from([
+                    (
+                        "server".to_string(),
+                        JsonSchema::String {
+                            description: Some(
+                                "MCP server name exactly as configured. Must match the 'server' field returned by list_mcp_resources."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "uri".to_string(),
+                        JsonSchema::String {
+                            description: Some(
+                                "Resource URI to read. Must be one of the URIs returned by list_mcp_resources."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                ]),
+                required: Some(vec!["server".to_string(), "uri".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}

codex-rs/tools/src/utility_tool.rs

@@ -0,0 +1,125 @@
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
+use crate::ToolSpec;
+use std::collections::BTreeMap;
+
+pub fn create_list_dir_tool() -> ToolSpec {
+    let properties = BTreeMap::from([
+        (
+            "dir_path".to_string(),
+            JsonSchema::String {
+                description: Some("Absolute path to the directory to list.".to_string()),
+            },
+        ),
+        (
+            "offset".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "The entry number to start listing from. Must be 1 or greater.".to_string(),
+                ),
+            },
+        ),
+        (
+            "limit".to_string(),
+            JsonSchema::Number {
+                description: Some("The maximum number of entries to return.".to_string()),
+            },
+        ),
+        (
+            "depth".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "The maximum directory depth to traverse. Must be 1 or greater.".to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "list_dir".to_string(),
+        description:
+            "Lists entries in a local directory with 1-indexed entry numbers and simple type labels."
+                .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["dir_path".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}
+
+pub fn create_test_sync_tool() -> ToolSpec {
+    let barrier_properties = BTreeMap::from([
+        (
+            "id".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Identifier shared by concurrent calls that should rendezvous".to_string(),
+                ),
+            },
+        ),
+        (
+            "participants".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "Number of tool calls that must arrive before the barrier opens".to_string(),
+                ),
+            },
+        ),
+        (
+            "timeout_ms".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "Maximum time in milliseconds to wait at the barrier".to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    let properties = BTreeMap::from([
+        (
+            "sleep_before_ms".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "Optional delay in milliseconds before any other action".to_string(),
+                ),
+            },
+        ),
+        (
+            "sleep_after_ms".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "Optional delay in milliseconds after completing the barrier".to_string(),
+                ),
+            },
+        ),
+        (
+            "barrier".to_string(),
+            JsonSchema::Object {
+                properties: barrier_properties,
+                required: Some(vec!["id".to_string(), "participants".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+        ),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "test_sync_tool".to_string(),
+        description: "Internal synchronization helper used by Codex integration tests.".to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: None,
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}
+
+#[cfg(test)]
+#[path = "utility_tool_tests.rs"]
+mod tests;

codex-rs/tools/src/utility_tool_tests.rs

@@ -0,0 +1,137 @@
+use super::*;
+use pretty_assertions::assert_eq;
+use std::collections::BTreeMap;
+
+#[test]
+fn list_dir_tool_matches_expected_spec() {
+    assert_eq!(
+        create_list_dir_tool(),
+        ToolSpec::Function(ResponsesApiTool {
+            name: "list_dir".to_string(),
+            description:
+                "Lists entries in a local directory with 1-indexed entry numbers and simple type labels."
+                    .to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::from([
+                    (
+                        "depth".to_string(),
+                        JsonSchema::Number {
+                            description: Some(
+                                "The maximum directory depth to traverse. Must be 1 or greater."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "dir_path".to_string(),
+                        JsonSchema::String {
+                            description: Some(
+                                "Absolute path to the directory to list.".to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "limit".to_string(),
+                        JsonSchema::Number {
+                            description: Some(
+                                "The maximum number of entries to return.".to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "offset".to_string(),
+                        JsonSchema::Number {
+                            description: Some(
+                                "The entry number to start listing from. Must be 1 or greater."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                ]),
+                required: Some(vec!["dir_path".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}
+
+#[test]
+fn test_sync_tool_matches_expected_spec() {
+    assert_eq!(
+        create_test_sync_tool(),
+        ToolSpec::Function(ResponsesApiTool {
+            name: "test_sync_tool".to_string(),
+            description: "Internal synchronization helper used by Codex integration tests."
+                .to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::from([
+                    (
+                        "barrier".to_string(),
+                        JsonSchema::Object {
+                            properties: BTreeMap::from([
+                                (
+                                    "id".to_string(),
+                                    JsonSchema::String {
+                                        description: Some(
+                                            "Identifier shared by concurrent calls that should rendezvous"
+                                                .to_string(),
+                                        ),
+                                    },
+                                ),
+                                (
+                                    "participants".to_string(),
+                                    JsonSchema::Number {
+                                        description: Some(
+                                            "Number of tool calls that must arrive before the barrier opens"
+                                                .to_string(),
+                                        ),
+                                    },
+                                ),
+                                (
+                                    "timeout_ms".to_string(),
+                                    JsonSchema::Number {
+                                        description: Some(
+                                            "Maximum time in milliseconds to wait at the barrier"
+                                                .to_string(),
+                                        ),
+                                    },
+                                ),
+                            ]),
+                            required: Some(vec![
+                                "id".to_string(),
+                                "participants".to_string(),
+                            ]),
+                            additional_properties: Some(false.into()),
+                        },
+                    ),
+                    (
+                        "sleep_after_ms".to_string(),
+                        JsonSchema::Number {
+                            description: Some(
+                                "Optional delay in milliseconds after completing the barrier"
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "sleep_before_ms".to_string(),
+                        JsonSchema::Number {
+                            description: Some(
+                                "Optional delay in milliseconds before any other action"
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                ]),
+                required: None,
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}