Python SDK: add ToolError exception to surface tool failures to the LLM

Tool handlers can now raise ToolError("message") to return a structured
failure result whose message is intentionally forwarded to the LLM as
text_result_for_llm.

This simplifies handler code: a tool that wants to signal a recoverable
failure to the LLM can simply 'raise ToolError("...")' instead of having
to construct and return a full ToolResult(result_type="failure", ...)
manually. The raise-and-return paths now look symmetric for success and
failure.

Other exception types continue to be caught and hidden behind the generic
'Invoking this tool produced an error' message for security.

Author: idryzhov

python/copilot/__init__.py

@@ -117,6 +117,7 @@
 from .tools import (
     Tool,
     ToolBinaryResult,
+    ToolError,
     ToolInvocation,
     ToolResult,
     ToolResultType,
@@ -223,6 +224,7 @@
     "TelemetryConfig",
     "Tool",
     "ToolBinaryResult",
+    "ToolError",
     "ToolInvocation",
     "ToolResult",
     "ToolResultType",

python/copilot/tools.py

@@ -18,6 +18,13 @@
 ToolResultType = Literal["success", "failure", "rejected", "denied", "timeout"]
 
 
+class ToolError(Exception):
+    """
+    Exception raised by tool handlers to return a failure result to the LLM.
+    Unlike other exceptions, the message is intentionally surfaced to the LLM.
+    """
+
+
 @dataclass
 class ToolBinaryResult:
     """Binary content returned by a tool."""
@@ -215,6 +222,14 @@ async def wrapped_handler(invocation: ToolInvocation) -> ToolResult:
 
                 return _normalize_result(result)
 
+            except ToolError as exc:
+                msg = str(exc)
+                return ToolResult(
+                    text_result_for_llm=msg,
+                    result_type="failure",
+                    error=msg,
+                )
+
             except Exception as exc:
                 # Don't expose detailed error information to the LLM for security reasons.
                 # The actual error is stored in the 'error' field for debugging.

python/test_tools.py

@@ -7,6 +7,7 @@
 
 from copilot import define_tool
 from copilot.tools import (
+    ToolError,
     ToolInvocation,
     ToolResult,
     _normalize_result,
@@ -197,6 +198,30 @@ def failing_tool(params: Params, invocation: ToolInvocation) -> str:
         # But the actual error is stored internally
         assert result.error == "secret error message"
 
+    async def test_tool_error_is_surfaced_to_llm(self):
+        class Params(BaseModel):
+            pass
+
+        @define_tool("failing", description="A failing tool")
+        def failing_tool(params: Params, invocation: ToolInvocation) -> str:
+            raise ToolError("public error message")
+
+        invocation = ToolInvocation(
+            session_id="s1",
+            tool_call_id="c1",
+            tool_name="failing",
+            arguments={},
+        )
+
+        result = await failing_tool.handler(invocation)
+
+        assert result.result_type == "failure"
+        assert result.text_result_for_llm == "public error message"
+        assert result.error == "public error message"
+        # ToolError must take the deliberate-failure path so the structured
+        # result reaches the LLM verbatim.
+        assert result._from_exception is False
+
     async def test_function_style_api(self):
         class Params(BaseModel):
             value: str