refactor(tools): typed deserialization for tool call params

crates/zeph-tools/src/executor.rs

@@ -146,10 +146,28 @@ pub enum ToolError {
     #[error("operation cancelled")]
     Cancelled,
 
+    #[error("invalid tool parameters: {message}")]
+    InvalidParams { message: String },
+
     #[error("execution failed: {0}")]
     Execution(#[from] std::io::Error),
 }
 
+/// Deserialize tool call params from a `HashMap<String, Value>` into a typed struct.
+///
+/// # Errors
+///
+/// Returns `ToolError::InvalidParams` when deserialization fails.
+pub fn deserialize_params<T: serde::de::DeserializeOwned, S: std::hash::BuildHasher>(
+    params: &HashMap<String, serde_json::Value, S>,
+) -> Result<T, ToolError> {
+    let obj =
+        serde_json::Value::Object(params.iter().map(|(k, v)| (k.clone(), v.clone())).collect());
+    serde_json::from_value(obj).map_err(|e| ToolError::InvalidParams {
+        message: e.to_string(),
+    })
+}
+
 /// Async trait for tool execution backends (shell, future MCP, A2A).
 ///
 /// Accepts the full LLM response and returns an optional output.
@@ -256,6 +274,91 @@ mod tests {
         assert_eq!(err.to_string(), "command timed out after 30s");
     }
 
+    #[test]
+    fn tool_error_invalid_params_display() {
+        let err = ToolError::InvalidParams {
+            message: "missing field `command`".to_owned(),
+        };
+        assert_eq!(
+            err.to_string(),
+            "invalid tool parameters: missing field `command`"
+        );
+    }
+
+    #[test]
+    fn deserialize_params_valid() {
+        #[derive(Debug, serde::Deserialize, PartialEq)]
+        struct P {
+            name: String,
+            count: u32,
+        }
+        let mut map = HashMap::new();
+        map.insert("name".to_owned(), serde_json::json!("test"));
+        map.insert("count".to_owned(), serde_json::json!(42));
+        let p: P = deserialize_params(&map).unwrap();
+        assert_eq!(
+            p,
+            P {
+                name: "test".to_owned(),
+                count: 42
+            }
+        );
+    }
+
+    #[test]
+    fn deserialize_params_missing_required_field() {
+        #[derive(Debug, serde::Deserialize)]
+        struct P {
+            #[allow(dead_code)]
+            name: String,
+        }
+        let map: HashMap<String, serde_json::Value> = HashMap::new();
+        let err = deserialize_params::<P, _>(&map).unwrap_err();
+        assert!(matches!(err, ToolError::InvalidParams { .. }));
+    }
+
+    #[test]
+    fn deserialize_params_wrong_type() {
+        #[derive(Debug, serde::Deserialize)]
+        struct P {
+            #[allow(dead_code)]
+            count: u32,
+        }
+        let mut map = HashMap::new();
+        map.insert("count".to_owned(), serde_json::json!("not a number"));
+        let err = deserialize_params::<P, _>(&map).unwrap_err();
+        assert!(matches!(err, ToolError::InvalidParams { .. }));
+    }
+
+    #[test]
+    fn deserialize_params_all_optional_empty() {
+        #[derive(Debug, serde::Deserialize, PartialEq)]
+        struct P {
+            name: Option<String>,
+        }
+        let map: HashMap<String, serde_json::Value> = HashMap::new();
+        let p: P = deserialize_params(&map).unwrap();
+        assert_eq!(p, P { name: None });
+    }
+
+    #[test]
+    fn deserialize_params_ignores_extra_fields() {
+        #[derive(Debug, serde::Deserialize, PartialEq)]
+        struct P {
+            name: String,
+        }
+        let mut map = HashMap::new();
+        map.insert("name".to_owned(), serde_json::json!("test"));
+        map.insert("extra".to_owned(), serde_json::json!(true));
+        let p: P = deserialize_params(&map).unwrap();
+        assert_eq!(
+            p,
+            P {
+                name: "test".to_owned()
+            }
+        );
+    }
+
     #[test]
     fn tool_error_execution_display() {
         let io_err = std::io::Error::new(std::io::ErrorKind::NotFound, "bash not found");