chore: refactor tool handling (#4510)

# Tool System Refactor

- Centralizes tool definitions and execution in `core/src/tools/*`:
specs (`spec.rs`), handlers (`handlers/*`), router (`router.rs`),
registry/dispatch (`registry.rs`), and shared context (`context.rs`).
One registry now builds the model-visible tool list and binds handlers.
- Router converts model responses to tool calls; Registry dispatches
with consistent telemetry via `codex-rs/otel` and unified error
handling. Function, Local Shell, MCP, and experimental `unified_exec`
all flow through this path; legacy shell aliases still work.
- Rationale: reduce per‑tool boilerplate, keep spec/handler in sync, and
make adding tools predictable and testable.

Example: `read_file`
- Spec: `core/src/tools/spec.rs` (see `create_read_file_tool`,
registered by `build_specs`).
- Handler: `core/src/tools/handlers/read_file.rs` (absolute `file_path`,
1‑indexed `offset`, `limit`, `L#: ` prefixes, safe truncation).
- E2E test: `core/tests/suite/read_file.rs` validates the tool returns
the requested lines.

## Next steps:
- Decompose `handle_container_exec_with_params` 
- Add parallel tool calls

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

@@ -0,0 +1,121 @@
+use crate::client_common::tools::ResponsesApiTool;
+use crate::client_common::tools::ToolSpec;
+use crate::codex::Session;
+use crate::function_tool::FunctionCallError;
+use crate::openai_tools::JsonSchema;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+use crate::tools::registry::ToolHandler;
+use crate::tools::registry::ToolKind;
+use async_trait::async_trait;
+use codex_protocol::plan_tool::UpdatePlanArgs;
+use codex_protocol::protocol::Event;
+use codex_protocol::protocol::EventMsg;
+use std::collections::BTreeMap;
+use std::sync::LazyLock;
+
+pub struct PlanHandler;
+
+pub static PLAN_TOOL: LazyLock<ToolSpec> = LazyLock::new(|| {
+    let mut plan_item_props = BTreeMap::new();
+    plan_item_props.insert("step".to_string(), JsonSchema::String { description: None });
+    plan_item_props.insert(
+        "status".to_string(),
+        JsonSchema::String {
+            description: Some("One of: pending, in_progress, completed".to_string()),
+        },
+    );
+
+    let plan_items_schema = JsonSchema::Array {
+        description: Some("The list of steps".to_string()),
+        items: Box::new(JsonSchema::Object {
+            properties: plan_item_props,
+            required: Some(vec!["step".to_string(), "status".to_string()]),
+            additional_properties: Some(false.into()),
+        }),
+    };
+
+    let mut properties = BTreeMap::new();
+    properties.insert(
+        "explanation".to_string(),
+        JsonSchema::String { description: None },
+    );
+    properties.insert("plan".to_string(), plan_items_schema);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "update_plan".to_string(),
+        description: r#"Updates the task plan.
+Provide an optional explanation and a list of plan items, each with a step and status.
+At most one step can be in_progress at a time.
+"#
+        .to_string(),
+        strict: false,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["plan".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+    })
+});
+
+#[async_trait]
+impl ToolHandler for PlanHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    async fn handle(
+        &self,
+        invocation: ToolInvocation<'_>,
+    ) -> Result<ToolOutput, FunctionCallError> {
+        let ToolInvocation {
+            session,
+            sub_id,
+            call_id,
+            payload,
+            ..
+        } = invocation;
+
+        let arguments = match payload {
+            ToolPayload::Function { arguments } => arguments,
+            _ => {
+                return Err(FunctionCallError::RespondToModel(
+                    "update_plan handler received unsupported payload".to_string(),
+                ));
+            }
+        };
+
+        let content = handle_update_plan(session, arguments, sub_id.to_string(), call_id).await?;
+
+        Ok(ToolOutput::Function {
+            content,
+            success: Some(true),
+        })
+    }
+}
+
+/// This function doesn't do anything useful. However, it gives the model a structured way to record its plan that clients can read and render.
+/// So it's the _inputs_ to this function that are useful to clients, not the outputs and neither are actually useful for the model other
+/// than forcing it to come up and document a plan (TBD how that affects performance).
+pub(crate) async fn handle_update_plan(
+    session: &Session,
+    arguments: String,
+    sub_id: String,
+    _call_id: String,
+) -> Result<String, FunctionCallError> {
+    let args = parse_update_plan_arguments(&arguments)?;
+    session
+        .send_event(Event {
+            id: sub_id.to_string(),
+            msg: EventMsg::PlanUpdate(args),
+        })
+        .await;
+    Ok("Plan updated".to_string())
+}
+
+fn parse_update_plan_arguments(arguments: &str) -> Result<UpdatePlanArgs, FunctionCallError> {
+    serde_json::from_str::<UpdatePlanArgs>(arguments).map_err(|e| {
+        FunctionCallError::RespondToModel(format!("failed to parse function arguments: {e}"))
+    })
+}