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/tools/src/tool_spec.rs

@@ -0,0 +1,105 @@
+use crate::FreeformTool;
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
+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;
+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 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 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 struct ResponsesApiWebSearchFilters {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub 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 struct ResponsesApiWebSearchUserLocation {
+    #[serde(rename = "type")]
+    pub r#type: WebSearchUserLocationType,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub country: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub region: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub city: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub 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,
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "tool_spec_tests.rs"]
+mod tests;