codex-tools: extract tool spec models (#16047)

## Why

This continues the `codex-tools` migration by moving another passive
tool-definition layer out of `codex-core`.

After `ResponsesApiTool` and the lower-level schema adapters moved into
`codex-tools`, `core/src/client_common.rs` was still owning `ToolSpec`
and the web-search request wire types even though they are serialized
data models rather than runtime orchestration. Keeping those types in
`codex-core` makes the crate boundary look smaller than it really is and
leaves non-runtime tool-shape code coupled to core.

## What changed

- moved `ToolSpec`, `ResponsesApiWebSearchFilters`, and
`ResponsesApiWebSearchUserLocation` into
`codex-rs/tools/src/tool_spec.rs`
- added focused unit tests in `codex-rs/tools/src/tool_spec_tests.rs`
for:
  - `ToolSpec::name()`
  - web-search config conversions
  - `ToolSpec` serialization for `web_search` and `tool_search`
- kept `codex-rs/tools/src/lib.rs` exports-only by re-exporting the new
module from `lib.rs`
- reduced `core/src/client_common.rs` to a compatibility shim that
re-exports the extracted tool-spec types for current core call sites
- updated `core/src/tools/spec_tests.rs` to consume the extracted
web-search types directly from `codex-tools`
- updated `codex-rs/tools/README.md` so the crate contract reflects that
`codex-tools` now owns the passive tool-spec request models in addition
to the lower-level Responses API structs

## Test plan

- `cargo test -p codex-tools`
- `cargo test -p codex-core --lib tools::spec::`
- `cargo test -p codex-core --lib client_common::`
- `just fix -p codex-tools -p codex-core`
- `just argument-comment-lint`

## References

- #15923
- #15928
- #15944
- #15953
- #16031

codex-rs/core/src/client_common.rs

@@ -1,10 +1,10 @@
-use crate::client_common::tools::ToolSpec;
 use crate::config::types::Personality;
 use crate::error::Result;
 pub use codex_api::common::ResponseEvent;
 use codex_protocol::models::BaseInstructions;
 use codex_protocol::models::FunctionCallOutputBody;
 use codex_protocol::models::ResponseItem;
+use codex_tools::ToolSpec;
 use futures::Stream;
 use serde::Deserialize;
 use serde_json::Value;
@@ -157,107 +157,11 @@ fn strip_total_output_header(output: &str) -> Option<(&str, u32)> {
 }
 
 pub(crate) mod tools {
-    use codex_protocol::config_types::WebSearchContextSize;
-    use codex_protocol::config_types::WebSearchFilters as ConfigWebSearchFilters;
-    use codex_protocol::config_types::WebSearchUserLocation as ConfigWebSearchUserLocation;
-    use codex_protocol::config_types::WebSearchUserLocationType;
     pub(crate) use codex_tools::FreeformTool;
     pub(crate) use codex_tools::FreeformToolFormat;
-    use codex_tools::JsonSchema;
     pub(crate) use codex_tools::ResponsesApiTool;
     pub(crate) use codex_tools::ToolSearchOutputTool;
-    use serde::Serialize;
-
-    /// When serialized as JSON, this produces a valid "Tool" in the OpenAI
-    /// Responses API.
-    #[derive(Debug, Clone, Serialize, PartialEq)]
-    #[serde(tag = "type")]
-    pub(crate) enum ToolSpec {
-        #[serde(rename = "function")]
-        Function(ResponsesApiTool),
-        #[serde(rename = "tool_search")]
-        ToolSearch {
-            execution: String,
-            description: String,
-            parameters: JsonSchema,
-        },
-        #[serde(rename = "local_shell")]
-        LocalShell {},
-        #[serde(rename = "image_generation")]
-        ImageGeneration { output_format: String },
-        // TODO: Understand why we get an error on web_search although the API docs say it's supported.
-        // https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses#:~:text=%7B%20type%3A%20%22web_search%22%20%7D%2C
-        // The `external_web_access` field determines whether the web search is over cached or live content.
-        // https://platform.openai.com/docs/guides/tools-web-search#live-internet-access
-        #[serde(rename = "web_search")]
-        WebSearch {
-            #[serde(skip_serializing_if = "Option::is_none")]
-            external_web_access: Option<bool>,
-            #[serde(skip_serializing_if = "Option::is_none")]
-            filters: Option<ResponsesApiWebSearchFilters>,
-            #[serde(skip_serializing_if = "Option::is_none")]
-            user_location: Option<ResponsesApiWebSearchUserLocation>,
-            #[serde(skip_serializing_if = "Option::is_none")]
-            search_context_size: Option<WebSearchContextSize>,
-            #[serde(skip_serializing_if = "Option::is_none")]
-            search_content_types: Option<Vec<String>>,
-        },
-        #[serde(rename = "custom")]
-        Freeform(FreeformTool),
-    }
-
-    impl ToolSpec {
-        pub(crate) fn name(&self) -> &str {
-            match self {
-                ToolSpec::Function(tool) => tool.name.as_str(),
-                ToolSpec::ToolSearch { .. } => "tool_search",
-                ToolSpec::LocalShell {} => "local_shell",
-                ToolSpec::ImageGeneration { .. } => "image_generation",
-                ToolSpec::WebSearch { .. } => "web_search",
-                ToolSpec::Freeform(tool) => tool.name.as_str(),
-            }
-        }
-    }
-
-    #[derive(Debug, Clone, Serialize, PartialEq)]
-    pub(crate) struct ResponsesApiWebSearchFilters {
-        #[serde(skip_serializing_if = "Option::is_none")]
-        pub(crate) allowed_domains: Option<Vec<String>>,
-    }
-
-    impl From<ConfigWebSearchFilters> for ResponsesApiWebSearchFilters {
-        fn from(filters: ConfigWebSearchFilters) -> Self {
-            Self {
-                allowed_domains: filters.allowed_domains,
-            }
-        }
-    }
-
-    #[derive(Debug, Clone, Serialize, PartialEq)]
-    pub(crate) struct ResponsesApiWebSearchUserLocation {
-        #[serde(rename = "type")]
-        pub(crate) r#type: WebSearchUserLocationType,
-        #[serde(skip_serializing_if = "Option::is_none")]
-        pub(crate) country: Option<String>,
-        #[serde(skip_serializing_if = "Option::is_none")]
-        pub(crate) region: Option<String>,
-        #[serde(skip_serializing_if = "Option::is_none")]
-        pub(crate) city: Option<String>,
-        #[serde(skip_serializing_if = "Option::is_none")]
-        pub(crate) timezone: Option<String>,
-    }
-
-    impl From<ConfigWebSearchUserLocation> for ResponsesApiWebSearchUserLocation {
-        fn from(user_location: ConfigWebSearchUserLocation) -> Self {
-            Self {
-                r#type: user_location.r#type,
-                country: user_location.country,
-                region: user_location.region,
-                city: user_location.city,
-                timezone: user_location.timezone,
-            }
-        }
-    }
+    pub(crate) use codex_tools::ToolSpec;
 }
 
 pub struct ResponseStream {