Support deferred loading for freeform tools (#36856)

## What changed

- Add optional `defer_loading` support to freeform Responses API tool definitions.
- Omit the field when it is unset so existing eager tool definitions retain their wire shape.

## Testing

- Verify legacy freeform tool deserialization and eager and deferred serialization shapes.

GitOrigin-RevId: 50e8658a54ac5b6ae0c1dbfe65f7bb62efef561d

codex-rs/core/src/tools/code_mode/execute_spec.rs

@@ -30,6 +30,7 @@ SOURCE: /[\s\S]+/
             default_exec_yield_time_ms,
             code_mode_only,
         ),
+        defer_loading: None,
         format: FreeformToolFormat {
             r#type: "grammar".to_string(),
             syntax: "lark".to_string(),
@@ -72,6 +73,7 @@ mod tests {
                     codex_code_mode::DEFAULT_EXEC_YIELD_TIME_MS,
                     /*code_mode_only*/ true,
                 ),
+                defer_loading: None,
                 format: FreeformToolFormat {
                     r#type: "grammar".to_string(),
                     syntax: "lark".to_string(),

codex-rs/core/src/tools/handlers/apply_patch_spec.rs

@@ -18,6 +18,7 @@ pub fn create_apply_patch_freeform_tool(include_environment_id: bool) -> ToolSpe
     ToolSpec::Freeform(FreeformTool {
         name: "apply_patch".to_string(),
         description: "The `apply_patch` tool can be used to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.".to_string(),
+        defer_loading: None,
         format: FreeformToolFormat {
             r#type: "grammar".to_string(),
             syntax: "lark".to_string(),

codex-rs/core/src/tools/handlers/apply_patch_spec_tests.rs

@@ -10,6 +10,7 @@ fn create_apply_patch_freeform_tool_matches_expected_spec() {
             description:
                 "The `apply_patch` tool can be used to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON."
                     .to_string(),
+            defer_loading: None,
             format: FreeformToolFormat {
                 r#type: "grammar".to_string(),
                 syntax: "lark".to_string(),

codex-rs/tools/src/code_mode_tests.rs

@@ -71,6 +71,7 @@ fn augment_tool_spec_for_code_mode_preserves_exec_tool_description() {
         augment_tool_spec_for_code_mode(ToolSpec::Freeform(FreeformTool {
             name: codex_code_mode::PUBLIC_TOOL_NAME.to_string(),
             description: "Run code".to_string(),
+            defer_loading: None,
             format: FreeformToolFormat {
                 r#type: "grammar".to_string(),
                 syntax: "lark".to_string(),
@@ -80,6 +81,7 @@ fn augment_tool_spec_for_code_mode_preserves_exec_tool_description() {
         ToolSpec::Freeform(FreeformTool {
             name: codex_code_mode::PUBLIC_TOOL_NAME.to_string(),
             description: "Run code".to_string(),
+            defer_loading: None,
             format: FreeformToolFormat {
                 r#type: "grammar".to_string(),
                 syntax: "lark".to_string(),
@@ -94,6 +96,7 @@ fn tool_spec_to_code_mode_tool_definition_returns_augmented_nested_tools() {
     let spec = ToolSpec::Freeform(FreeformTool {
         name: "apply_patch".to_string(),
         description: "Apply a patch".to_string(),
+        defer_loading: None,
         format: FreeformToolFormat {
             r#type: "grammar".to_string(),
             syntax: "lark".to_string(),

codex-rs/tools/src/responses_api.rs

@@ -12,6 +12,8 @@ use serde_json::Value;
 pub struct FreeformTool {
     pub name: String,
     pub description: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub defer_loading: Option<bool>,
     pub format: FreeformToolFormat,
 }
 

codex-rs/tools/src/responses_api_tests.rs

@@ -1,3 +1,4 @@
+use super::FreeformTool;
 use super::LoadableToolSpec;
 use super::ResponsesApiNamespace;
 use super::ResponsesApiNamespaceTool;
@@ -13,6 +14,35 @@ use pretty_assertions::assert_eq;
 use serde_json::json;
 use std::collections::BTreeMap;
 
+#[test]
+fn freeform_tool_deferral_matches_function_tool_wire_shape() {
+    let mut expected_wire_shape = json!({
+        "name": "apply_patch",
+        "description": "Apply a patch",
+        "format": {
+            "type": "grammar",
+            "syntax": "lark",
+            "definition": "start: \"patch\"",
+        },
+    });
+
+    let mut tool: FreeformTool = serde_json::from_value(expected_wire_shape.clone())
+        .expect("deserialize legacy freeform tool");
+
+    assert_eq!(tool.defer_loading, None);
+    assert_eq!(
+        serde_json::to_value(&tool).expect("serialize eager freeform tool"),
+        expected_wire_shape
+    );
+
+    tool.defer_loading = Some(true);
+    expected_wire_shape["defer_loading"] = json!(true);
+    assert_eq!(
+        serde_json::to_value(tool).expect("serialize deferred freeform tool"),
+        expected_wire_shape
+    );
+}
+
 #[test]
 fn tool_definition_to_responses_api_tool_omits_false_defer_loading() {
     assert_eq!(

codex-rs/tools/src/tool_spec_tests.rs

@@ -74,6 +74,7 @@ fn tool_spec_name_covers_all_variants() {
         ToolSpec::Freeform(FreeformTool {
             name: "exec".to_string(),
             description: "Run a command".to_string(),
+            defer_loading: None,
             format: FreeformToolFormat {
                 r#type: "grammar".to_string(),
                 syntax: "lark".to_string(),