cli2api 0.2.1__tar.gz → 0.2.2__tar.gz

{cli2api-0.2.1 → cli2api-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli2api
-Version: 0.2.1
+Version: 0.2.2
 Summary: OpenAI-compatible API over Claude Code CLI
 Requires-Python: >=3.11
 Requires-Dist: fastapi>=0.115.0

{cli2api-0.2.1 → cli2api-0.2.2}/cli2api/__init__.py

@@ -1,3 +1,3 @@
 """CLI2API - OpenAI-compatible API over CLI tools."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.2"

cli2api-0.2.2/cli2api/prompts/tools_instruction.txt

@@ -0,0 +1,58 @@
+You have access to the following tools:
+
+{tool_definitions}
+
+---
+RESPONSE FORMAT:
+
+When calling tools, wrap EACH tool call in <tool_call> tags.
+You may include explanatory text before or after the tags.
+
+For a SINGLE tool call:
+<tool_call>
+{{"name": "TOOL_NAME", "arguments": {{...}}}}
+</tool_call>
+
+For MULTIPLE tool calls, use SEPARATE tags for each:
+<tool_call>
+{{"name": "read_file", "arguments": {{"path": "file1.py"}}}}
+</tool_call>
+<tool_call>
+{{"name": "read_file", "arguments": {{"path": "file2.py"}}}}
+</tool_call>
+
+CRITICAL RULES:
+- ALWAYS wrap tool calls in <tool_call>...</tool_call> tags
+- Each tool call must be in its own tag pair
+- ALWAYS include the "arguments" key with ALL required parameters filled in
+- NEVER output {{"name": "tool_name"}} without "arguments" — this is INVALID
+- NEVER output empty arguments {{}} when the tool has required parameters
+- You CAN include text explanation before/after tags
+- Do NOT execute tools yourself — just output the tags
+- If user wants to read a file -> use read_file tool
+- If user wants to list files -> use list_files tool
+
+WRONG — missing arguments:
+<tool_call>
+{{"name": "execute_command"}}
+</tool_call>
+
+WRONG — empty arguments when tool requires parameters:
+<tool_call>
+{{"name": "execute_command", "arguments": {{}}}}
+</tool_call>
+
+CORRECT:
+<tool_call>
+{{"name": "execute_command", "arguments": {{"command": "ls -la"}}}}
+</tool_call>
+
+{tool_examples}
+
+ATTEMPT_COMPLETION USAGE:
+When using attempt_completion, ALWAYS include the 'result' parameter:
+<tool_call>
+{{"name": "attempt_completion", "arguments": {{"result": "Your response text here"}}}}
+</tool_call>
+- The 'result' parameter is REQUIRED and must contain your final response
+- Use attempt_completion ONLY after you have gathered all needed information

{cli2api-0.2.1 → cli2api-0.2.2}/cli2api/providers/claude.py

@@ -2,13 +2,16 @@
 
 import asyncio
 import json
+import uuid
 from pathlib import Path
 from typing import Any, AsyncIterator, Optional
 
+from cli2api.constants import ID_HEX_LENGTH, TOOL_CALL_ID_PREFIX
 from cli2api.schemas.internal import ProviderChunk, ProviderResult
 from cli2api.schemas.openai import ChatMessage
 from cli2api.streaming.tool_parser import StreamingToolParser
 from cli2api.tools.handler import ToolHandler
+from cli2api.tools.validator import filter_valid_tool_calls
 from cli2api.utils.logging import get_logger
 
 logger = get_logger(__name__)
@@ -221,7 +224,9 @@ class ClaudeCodeProvider:
     ) -> tuple[str, Optional[list[dict]]]:
         """Parse content for tool calls if tools are provided."""
         if tools and content:
-            return ToolHandler.parse_tool_calls(content)
+            remaining, tool_calls = ToolHandler.parse_tool_calls(content)
+            tool_calls = filter_valid_tool_calls(tool_calls, tools)
+            return remaining, tool_calls
         return content, None
 
     def _create_final_chunk(
@@ -237,12 +242,27 @@ class ClaudeCodeProvider:
             usage=usage,
         )
 
+    @staticmethod
+    def _deserialize_string_values(obj: dict) -> dict:
+        """Deserialize JSON-encoded string values in tool arguments.
+
+        Claude sometimes returns structured data (arrays, objects) as
+        JSON-encoded strings. Kilo Code expects native types, so we
+        parse them back. E.g. follow_up: '[{"text":"Yes"}]' -> [{"text":"Yes"}]
+        """
+        result = {}
+        for key, value in obj.items():
+            if isinstance(value, str) and value and value[0] in ('[', '{'):
+                try:
+                    result[key] = json.loads(value)
+                except (json.JSONDecodeError, ValueError):
+                    result[key] = value
+            else:
+                result[key] = value
+        return result
+
     def _extract_native_tool_call(self, block: dict) -> Optional[dict]:
         """Extract tool call from Claude native tool_use block."""
-        import json
-        import uuid
-        from cli2api.constants import ID_HEX_LENGTH, TOOL_CALL_ID_PREFIX
-
         tool_name = block.get("name")
         tool_input = block.get("input", {})
         tool_id = block.get("id", f"{TOOL_CALL_ID_PREFIX}{uuid.uuid4().hex[:ID_HEX_LENGTH]}")
@@ -250,6 +270,9 @@ class ClaudeCodeProvider:
         if not tool_name:
             return None
 
+        if isinstance(tool_input, dict):
+            tool_input = self._deserialize_string_values(tool_input)
+
         return {
             "id": tool_id,
             "type": "function",
@@ -391,12 +414,14 @@ class ClaudeCodeProvider:
                             # Native tool calling (stop_reason=tool_use)
                             if stop_reason == "tool_use":
                                 tool_calls = native_tool_calls if native_tool_calls else None
+                                tool_calls = filter_valid_tool_calls(tool_calls, tools)
                                 logger.info(f"[STREAM] Native tool_calls: {len(tool_calls) if tool_calls else 0}")
                             elif tool_parser:
                                 final_result = tool_parser.finalize()
                                 if final_result.text:
                                     yield ProviderChunk(content=final_result.text)
                                 tool_calls = tool_parser.get_all_tool_calls()
+                                tool_calls = filter_valid_tool_calls(tool_calls, tools)
                             else:
                                 _, tool_calls = self._handle_tool_calls_in_content(
                                     accumulated_content, tools
@@ -433,6 +458,7 @@ class ClaudeCodeProvider:
                         if final_result.text:
                             yield ProviderChunk(content=final_result.text)
                         tool_calls = tool_parser.get_all_tool_calls()
+                        tool_calls = filter_valid_tool_calls(tool_calls, tools)
                     else:
                         _, tool_calls = self._handle_tool_calls_in_content(
                             accumulated_content, tools
@@ -476,6 +502,7 @@ class ClaudeCodeProvider:
                         if final_result.text:
                             yield ProviderChunk(content=final_result.text)
                         tool_calls = tool_parser.get_all_tool_calls()
+                        tool_calls = filter_valid_tool_calls(tool_calls, tools)
                     else:
                         _, tool_calls = self._handle_tool_calls_in_content(
                             accumulated_content, tools
@@ -489,6 +516,7 @@ class ClaudeCodeProvider:
                 if final_result.text:
                     yield ProviderChunk(content=final_result.text)
                 tool_calls = tool_parser.get_all_tool_calls()
+                tool_calls = filter_valid_tool_calls(tool_calls, tools)
             else:
                 _, tool_calls = self._handle_tool_calls_in_content(accumulated_content, tools)
 

{cli2api-0.2.1 → cli2api-0.2.2}/cli2api/tools/handler.py

@@ -3,6 +3,8 @@
 import json
 import re
 import uuid
+from functools import lru_cache
+from pathlib import Path
 from typing import Any, Optional
 
 from cli2api.constants import (
@@ -14,6 +16,13 @@ from cli2api.constants import (
 from cli2api.schemas.openai import ChatMessage
 
 
+@lru_cache(maxsize=4)
+def _load_prompt_template(filename: str) -> str:
+    """Load prompt template from cli2api/prompts/ directory."""
+    path = Path(__file__).parent.parent / "prompts" / filename
+    return path.read_text()
+
+
 # ==================== Message Helpers ====================
 
 
@@ -86,9 +95,8 @@ class ToolHandler:
             key=lambda t: t.get("function", {}).get("name", "")
         )
 
-        lines = [
-            "You have access to the following tools:\n",
-        ]
+        tool_definitions = []
+        tool_examples = []
 
         for tool in tools:
             if tool.get("type") != "function":
@@ -98,14 +106,10 @@ class ToolHandler:
             name = func.get("name", "unknown")
             description = func.get("description", "No description")
             params = func.get("parameters", {})
-
-            lines.append(f"## {name}")
-            lines.append(f"{description}\n")
-
-            # Format parameters
             properties = params.get("properties", {})
             required = params.get("required", [])
 
+            lines = [f"## {name}", f"{description}\n"]
             if properties:
                 lines.append("Parameters:")
                 for pname, pinfo in properties.items():
@@ -114,45 +118,23 @@ class ToolHandler:
                     req = " (required)" if pname in required else " (optional)"
                     lines.append(f"- {pname} ({ptype}{req}): {pdesc}")
                 lines.append("")
-
-        lines.append("\n---")
-        lines.append("RESPONSE FORMAT:")
-        lines.append("")
-        lines.append("When calling tools, wrap EACH tool call in <tool_call> tags.")
-        lines.append("You may include explanatory text before or after the tags.")
-        lines.append("")
-        lines.append("For a SINGLE tool call:")
-        lines.append("<tool_call>")
-        lines.append('{"name": "TOOL_NAME", "arguments": {...}}')
-        lines.append("</tool_call>")
-        lines.append("")
-        lines.append("For MULTIPLE tool calls, use SEPARATE tags for each:")
-        lines.append("<tool_call>")
-        lines.append('{"name": "read_file", "arguments": {"path": "file1.py"}}')
-        lines.append("</tool_call>")
-        lines.append("<tool_call>")
-        lines.append('{"name": "read_file", "arguments": {"path": "file2.py"}}')
-        lines.append("</tool_call>")
-        lines.append("")
-        lines.append("CRITICAL RULES:")
-        lines.append("- ALWAYS wrap tool calls in <tool_call>...</tool_call> tags")
-        lines.append("- Each tool call must be in its own tag pair")
-        lines.append("- When reading multiple files, include multiple <tool_call> tags")
-        lines.append("- You CAN include text explanation before/after tags")
-        lines.append("- Do NOT execute tools yourself - just output the tags")
-        lines.append("- If user wants to read a file -> use read_file tool")
-        lines.append("- If user wants to list files -> use list_files tool")
-        lines.append("- ALWAYS include ALL required parameters for each tool")
-        lines.append("")
-        lines.append("ATTEMPT_COMPLETION USAGE:")
-        lines.append("When using attempt_completion, ALWAYS include the 'result' parameter:")
-        lines.append("<tool_call>")
-        lines.append('{"name": "attempt_completion", "arguments": {"result": "Your response text here"}}')
-        lines.append("</tool_call>")
-        lines.append("- The 'result' parameter is REQUIRED and must contain your final response")
-        lines.append("- Use attempt_completion ONLY after you have gathered all needed information")
-
-        return "\n".join(lines)
+            tool_definitions.append("\n".join(lines))
+
+            # Generate example call for tools with required parameters
+            if required:
+                example_args = {p: "<value>" for p in required}
+                example_json = json.dumps({"name": name, "arguments": example_args})
+                tool_examples.append(f"<tool_call>\n{example_json}\n</tool_call>")
+
+        template = _load_prompt_template("tools_instruction.txt")
+        examples_section = ""
+        if tool_examples:
+            examples_section = "Required parameter examples:\n" + "\n".join(tool_examples)
+
+        return template.format(
+            tool_definitions="\n".join(tool_definitions),
+            tool_examples=examples_section,
+        )
 
     @staticmethod
     def generate_tool_call_id() -> str:

cli2api-0.2.2/cli2api/tools/validator.py

@@ -0,0 +1,105 @@
+"""Tool call argument validation against OpenAI tool schemas."""
+
+import json
+from typing import Optional
+
+from cli2api.utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def build_required_params_index(tools: list[dict]) -> dict[str, list[str]]:
+    """Build a lookup: tool_name -> list of required parameter names.
+
+    Args:
+        tools: OpenAI-format tool definitions.
+
+    Returns:
+        Dict mapping tool name to list of required param names.
+    """
+    index = {}
+    for tool in tools:
+        if tool.get("type") != "function":
+            continue
+        func = tool.get("function", {})
+        name = func.get("name")
+        if not name:
+            continue
+        params = func.get("parameters", {})
+        index[name] = params.get("required", [])
+    return index
+
+
+def validate_tool_call(
+    tool_call: dict,
+    required_params_index: dict[str, list[str]],
+) -> bool:
+    """Validate a single tool call has all required arguments.
+
+    Args:
+        tool_call: Parsed tool call in OpenAI format.
+        required_params_index: From build_required_params_index().
+
+    Returns:
+        True if valid (all required params present), False otherwise.
+    """
+    func = tool_call.get("function", {})
+    name = func.get("name", "")
+    arguments_str = func.get("arguments", "{}")
+
+    required = required_params_index.get(name)
+    if required is None:
+        # Unknown tool — can't validate, let it pass
+        return True
+
+    if not required:
+        # Tool has no required params — always valid
+        return True
+
+    try:
+        arguments = json.loads(arguments_str)
+    except (json.JSONDecodeError, TypeError):
+        logger.warning(f"Tool call '{name}' has unparseable arguments: {arguments_str!r}")
+        return False
+
+    if not isinstance(arguments, dict):
+        logger.warning(f"Tool call '{name}' arguments is not a dict: {type(arguments)}")
+        return False
+
+    missing = [p for p in required if p not in arguments]
+    if missing:
+        logger.warning(
+            f"Tool call '{name}' missing required params: {missing}. "
+            f"Got: {list(arguments.keys())}"
+        )
+        return False
+
+    return True
+
+
+def filter_valid_tool_calls(
+    tool_calls: Optional[list[dict]],
+    tools: Optional[list[dict]],
+) -> Optional[list[dict]]:
+    """Filter tool calls, removing those with missing required params.
+
+    Invalid tool calls are dropped with a WARNING log.
+
+    Args:
+        tool_calls: Parsed tool calls (may be None).
+        tools: Original tool definitions (may be None).
+
+    Returns:
+        Filtered list, or None if empty/input was None.
+    """
+    if not tool_calls or not tools:
+        return tool_calls
+
+    index = build_required_params_index(tools)
+    valid = [tc for tc in tool_calls if validate_tool_call(tc, index)]
+
+    if len(valid) < len(tool_calls):
+        dropped = len(tool_calls) - len(valid)
+        logger.warning(f"Dropped {dropped} invalid tool call(s) with missing required params")
+
+    return valid if valid else None

{cli2api-0.2.1 → cli2api-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cli2api"
-version = "0.2.1"
+version = "0.2.2"
 description = "OpenAI-compatible API over Claude Code CLI"
 readme = "README.md"
 requires-python = ">=3.11"

{cli2api-0.2.1 → cli2api-0.2.2}/tests/test_providers.py

@@ -195,3 +195,176 @@ class TestMockProvider:
 
         content = "".join(c.content for c in chunks if c.content)
         assert content == "ABC"
+
+
+class TestDeserializeStringValues:
+    """Tests for _deserialize_string_values in ClaudeCodeProvider."""
+
+    @pytest.fixture
+    def provider(self):
+        return ClaudeCodeProvider(
+            executable_path=Path("/usr/bin/claude"),
+            default_timeout=300,
+        )
+
+    def test_json_array_string_is_deserialized(self, provider):
+        """JSON array encoded as string should be parsed to native array."""
+        obj = {"follow_up": '[{"text":"Yes","mode":null}]'}
+        result = provider._deserialize_string_values(obj)
+        assert isinstance(result["follow_up"], list)
+        assert result["follow_up"][0]["text"] == "Yes"
+
+    def test_json_object_string_is_deserialized(self, provider):
+        """JSON object encoded as string should be parsed to native dict."""
+        obj = {"data": '{"key": "value"}'}
+        result = provider._deserialize_string_values(obj)
+        assert isinstance(result["data"], dict)
+        assert result["data"]["key"] == "value"
+
+    def test_plain_string_is_unchanged(self, provider):
+        """Non-JSON strings should pass through unchanged."""
+        obj = {"question": "What do you want?", "command": "ls -la"}
+        result = provider._deserialize_string_values(obj)
+        assert result["question"] == "What do you want?"
+        assert result["command"] == "ls -la"
+
+    def test_non_string_values_are_unchanged(self, provider):
+        """Non-string values (int, bool, list, dict) should pass through."""
+        obj = {"count": 5, "active": True, "items": [1, 2], "meta": {"k": "v"}}
+        result = provider._deserialize_string_values(obj)
+        assert result == obj
+
+    def test_invalid_json_starting_with_bracket_is_unchanged(self, provider):
+        """Strings starting with [ or { but not valid JSON should pass through."""
+        obj = {"note": "[not valid json", "other": "{also not valid"}
+        result = provider._deserialize_string_values(obj)
+        assert result["note"] == "[not valid json"
+        assert result["other"] == "{also not valid"
+
+    def test_empty_string_is_unchanged(self, provider):
+        """Empty strings should pass through."""
+        obj = {"empty": ""}
+        result = provider._deserialize_string_values(obj)
+        assert result["empty"] == ""
+
+    def test_real_kilo_code_follow_up(self, provider):
+        """Reproduce exact Kilo Code ask_followup_question scenario."""
+        obj = {
+            "question": "Согласны с планом?",
+            "follow_up": '[{"text":"Y — Да","mode":null},{"text":"N — Нет","mode":null}]',
+        }
+        result = provider._deserialize_string_values(obj)
+        assert isinstance(result["follow_up"], list)
+        assert len(result["follow_up"]) == 2
+        assert result["follow_up"][0]["text"] == "Y — Да"
+        assert result["question"] == "Согласны с планом?"
+
+
+class TestExtractNativeToolCall:
+    """Tests for _extract_native_tool_call — the full path that caused 'o.map is not a function'.
+
+    Claude Opus returns native tool_use blocks. When tool arguments contain
+    JSON-encoded strings (e.g. follow_up as "[{...}]"), Kilo Code receives
+    a string instead of an array and crashes on .map().
+
+    These tests verify that _extract_native_tool_call deserializes such
+    strings so the final 'arguments' JSON contains native arrays/objects.
+    """
+
+    @pytest.fixture
+    def provider(self):
+        return ClaudeCodeProvider(
+            executable_path=Path("/usr/bin/claude"),
+            default_timeout=300,
+        )
+
+    def test_ask_followup_question_follow_up_is_array(self, provider):
+        """Exact reproduction of the o.map crash: follow_up must be array, not string."""
+        block = {
+            "type": "tool_use",
+            "id": "toolu_01ABC",
+            "name": "ask_followup_question",
+            "input": {
+                "question": "Согласны с включением шагов 2.4 и 2.5?",
+                "follow_up": '[{"text":"Y — Да, включить","mode":null},{"text":"N — Нужно обсудить","mode":null}]',
+            },
+        }
+
+        result = provider._extract_native_tool_call(block)
+
+        assert result is not None
+        assert result["function"]["name"] == "ask_followup_question"
+        assert result["id"] == "toolu_01ABC"
+
+        # Parse the arguments JSON that Kilo Code will receive
+        args = json.loads(result["function"]["arguments"])
+        assert args["question"] == "Согласны с включением шагов 2.4 и 2.5?"
+
+        # THIS is the critical assertion — follow_up must be a list, not a string
+        assert isinstance(args["follow_up"], list), (
+            f"follow_up should be list but got {type(args['follow_up']).__name__}: "
+            f"{args['follow_up']!r}"
+        )
+        assert len(args["follow_up"]) == 2
+        assert args["follow_up"][0]["text"] == "Y — Да, включить"
+
+    def test_simple_tool_call_unchanged(self, provider):
+        """Tool calls with plain string arguments should not be affected."""
+        block = {
+            "type": "tool_use",
+            "id": "toolu_02DEF",
+            "name": "execute_command",
+            "input": {"command": "ls -la"},
+        }
+
+        result = provider._extract_native_tool_call(block)
+        args = json.loads(result["function"]["arguments"])
+
+        assert args["command"] == "ls -la"
+        assert isinstance(args["command"], str)
+
+    def test_tool_call_with_nested_json_object_string(self, provider):
+        """JSON object encoded as string in arguments should be deserialized."""
+        block = {
+            "type": "tool_use",
+            "id": "toolu_03GHI",
+            "name": "some_tool",
+            "input": {
+                "config": '{"key": "value", "nested": true}',
+            },
+        }
+
+        result = provider._extract_native_tool_call(block)
+        args = json.loads(result["function"]["arguments"])
+
+        assert isinstance(args["config"], dict)
+        assert args["config"]["key"] == "value"
+
+    def test_missing_tool_name_returns_none(self, provider):
+        """Block without tool name should return None."""
+        block = {"type": "tool_use", "input": {"x": 1}}
+
+        assert provider._extract_native_tool_call(block) is None
+
+    def test_empty_input_returns_empty_args(self, provider):
+        """Block with empty input should produce empty arguments."""
+        block = {
+            "type": "tool_use",
+            "name": "list_files",
+            "input": {},
+        }
+
+        result = provider._extract_native_tool_call(block)
+        args = json.loads(result["function"]["arguments"])
+        assert args == {}
+
+    def test_generates_id_when_missing(self, provider):
+        """Should generate a call_ prefixed ID when block has no id."""
+        block = {
+            "type": "tool_use",
+            "name": "test_tool",
+            "input": {},
+        }
+
+        result = provider._extract_native_tool_call(block)
+        assert result["id"].startswith("call_")

{cli2api-0.2.1 → cli2api-0.2.2}/tests/test_streaming_tool_parser.py

@@ -298,3 +298,22 @@ class TestParseResultDataclass:
         result = ParseResult(text="hello", tool_calls=[{"id": "test"}])
         assert result.text == "hello"
         assert result.tool_calls == [{"id": "test"}]
+
+
+class TestToolCallEdgeCases:
+    """Tests for tool call edge cases (missing arguments, etc)."""
+
+    def test_tool_call_without_arguments_key(self):
+        """Tool call JSON without 'arguments' key produces empty args dict.
+
+        This documents current parser behavior — validation happens downstream.
+        """
+        parser = StreamingToolParser()
+
+        text = '<tool_call>{"name": "execute_command"}</tool_call>'
+        result = parser.feed(text)
+
+        assert len(result.tool_calls) == 1
+        assert result.tool_calls[0]["function"]["name"] == "execute_command"
+        args = json.loads(result.tool_calls[0]["function"]["arguments"])
+        assert args == {}

cli2api-0.2.2/tests/test_tool_validator.py

@@ -0,0 +1,201 @@
+"""Tests for tool call argument validation."""
+
+import json
+
+import pytest
+
+from cli2api.tools.validator import (
+    build_required_params_index,
+    filter_valid_tool_calls,
+    validate_tool_call,
+)
+
+
+# === Fixtures ===
+
+SAMPLE_TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "execute_command",
+            "description": "Execute a shell command",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "command": {"type": "string", "description": "The command"},
+                },
+                "required": ["command"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "read_file",
+            "description": "Read a file",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "File path"},
+                    "encoding": {"type": "string", "description": "Encoding"},
+                },
+                "required": ["path"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "attempt_completion",
+            "description": "Complete the task",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "result": {"type": "string", "description": "Result text"},
+                },
+                "required": ["result"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "list_files",
+            "description": "List directory contents",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Directory path"},
+                },
+                "required": [],
+            },
+        },
+    },
+]
+
+
+def _make_tool_call(name: str, arguments: dict) -> dict:
+    return {
+        "id": "call_test123",
+        "type": "function",
+        "function": {
+            "name": name,
+            "arguments": json.dumps(arguments),
+        },
+    }
+
+
+def _make_tool_call_raw(name: str, arguments_str: str) -> dict:
+    return {
+        "id": "call_test123",
+        "type": "function",
+        "function": {
+            "name": name,
+            "arguments": arguments_str,
+        },
+    }
+
+
+# === Tests for build_required_params_index ===
+
+
+class TestBuildRequiredParamsIndex:
+    def test_builds_index(self):
+        index = build_required_params_index(SAMPLE_TOOLS)
+        assert index["execute_command"] == ["command"]
+        assert index["read_file"] == ["path"]
+        assert index["attempt_completion"] == ["result"]
+        assert index["list_files"] == []
+
+    def test_empty_tools(self):
+        assert build_required_params_index([]) == {}
+
+    def test_skips_non_function_tools(self):
+        tools = [{"type": "code_interpreter"}]
+        assert build_required_params_index(tools) == {}
+
+
+# === Tests for validate_tool_call ===
+
+
+class TestValidateToolCall:
+    def setup_method(self):
+        self.index = build_required_params_index(SAMPLE_TOOLS)
+
+    def test_valid_tool_call_passes(self):
+        tc = _make_tool_call("execute_command", {"command": "ls -la"})
+        assert validate_tool_call(tc, self.index) is True
+
+    def test_valid_with_extra_params(self):
+        tc = _make_tool_call("read_file", {"path": "test.py", "encoding": "utf-8"})
+        assert validate_tool_call(tc, self.index) is True
+
+    def test_missing_required_param_fails(self):
+        tc = _make_tool_call("execute_command", {})
+        assert validate_tool_call(tc, self.index) is False
+
+    def test_empty_arguments_with_required_params_fails(self):
+        tc = _make_tool_call_raw("execute_command", "{}")
+        assert validate_tool_call(tc, self.index) is False
+
+    def test_no_required_params_always_passes(self):
+        tc = _make_tool_call("list_files", {})
+        assert validate_tool_call(tc, self.index) is True
+
+    def test_unknown_tool_passes(self):
+        tc = _make_tool_call("unknown_tool", {})
+        assert validate_tool_call(tc, self.index) is True
+
+    def test_unparseable_arguments_fails(self):
+        tc = _make_tool_call_raw("execute_command", "not-json")
+        assert validate_tool_call(tc, self.index) is False
+
+    def test_non_dict_arguments_fails(self):
+        tc = _make_tool_call_raw("execute_command", '"just a string"')
+        assert validate_tool_call(tc, self.index) is False
+
+
+# === Tests for filter_valid_tool_calls ===
+
+
+class TestFilterValidToolCalls:
+    def test_all_valid_passes_through(self):
+        tool_calls = [
+            _make_tool_call("execute_command", {"command": "ls"}),
+            _make_tool_call("read_file", {"path": "test.py"}),
+        ]
+        result = filter_valid_tool_calls(tool_calls, SAMPLE_TOOLS)
+        assert len(result) == 2
+
+    def test_filters_invalid_keeps_valid(self):
+        tool_calls = [
+            _make_tool_call("execute_command", {"command": "ls"}),  # valid
+            _make_tool_call("read_file", {}),  # invalid — missing path
+        ]
+        result = filter_valid_tool_calls(tool_calls, SAMPLE_TOOLS)
+        assert len(result) == 1
+        assert result[0]["function"]["name"] == "execute_command"
+
+    def test_all_invalid_returns_none(self):
+        tool_calls = [
+            _make_tool_call("execute_command", {}),
+            _make_tool_call("read_file", {}),
+        ]
+        result = filter_valid_tool_calls(tool_calls, SAMPLE_TOOLS)
+        assert result is None
+
+    def test_none_tool_calls_returns_none(self):
+        assert filter_valid_tool_calls(None, SAMPLE_TOOLS) is None
+
+    def test_empty_tool_calls_returns_empty(self):
+        assert filter_valid_tool_calls([], SAMPLE_TOOLS) == []
+
+    def test_none_tools_returns_tool_calls_unchanged(self):
+        tool_calls = [_make_tool_call("execute_command", {})]
+        result = filter_valid_tool_calls(tool_calls, None)
+        assert result == tool_calls
+
+    def test_no_required_params_tool_always_passes(self):
+        tool_calls = [_make_tool_call("list_files", {})]
+        result = filter_valid_tool_calls(tool_calls, SAMPLE_TOOLS)
+        assert len(result) == 1