Distinguish exception-originated failures from deliberate ones

The previous commit broke test_handles_tool_calling_errors because
define_tool's exception handler wraps exceptions as ToolResult(failure),
which was then sent as a structured result instead of a top-level error.

Fix: introduce TOOL_EXCEPTION_TEXT constant shared between define_tool's
exception handler and _execute_tool_and_respond. When the failure's
textResultForLlm matches the known exception wrapper message, send via
the top-level error param (CLI formats as 'Failed to execute...');
otherwise send the full structured result to preserve metadata.

This preserves backward compatibility for thrown exceptions while
allowing user-returned ToolResult(failure) to carry toolTelemetry.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Morabbin

python/copilot/session.py

@@ -38,7 +38,7 @@
     SessionEventType,
     session_event_from_dict,
 )
-from .tools import Tool, ToolHandler, ToolInvocation, ToolResult
+from .tools import TOOL_EXCEPTION_TEXT, Tool, ToolHandler, ToolInvocation, ToolResult
 
 # Re-export SessionEvent under an alias used internally
 SessionEventTypeAlias = SessionEvent
@@ -944,17 +944,33 @@ async def _execute_tool_and_respond(
             else:
                 tool_result = result  # type: ignore[assignment]
 
-            await self.rpc.tools.handle_pending_tool_call(
-                SessionToolsHandlePendingToolCallParams(
-                    request_id=request_id,
-                    result=ResultResult(
-                        text_result_for_llm=tool_result.text_result_for_llm,
-                        result_type=tool_result.result_type,
+            # Exception-originated failures (from define_tool's exception handler) are
+            # sent via the top-level error param so the CLI formats them with its
+            # standard "Failed to execute..." message. Deliberate user-returned
+            # failures send the full structured result to preserve metadata.
+            if (
+                tool_result.result_type == "failure"
+                and tool_result.error
+                and tool_result.text_result_for_llm == TOOL_EXCEPTION_TEXT
+            ):
+                await self.rpc.tools.handle_pending_tool_call(
+                    SessionToolsHandlePendingToolCallParams(
+                        request_id=request_id,
                         error=tool_result.error,
-                        tool_telemetry=tool_result.tool_telemetry,
-                    ),
+                    )
+                )
+            else:
+                await self.rpc.tools.handle_pending_tool_call(
+                    SessionToolsHandlePendingToolCallParams(
+                        request_id=request_id,
+                        result=ResultResult(
+                            text_result_for_llm=tool_result.text_result_for_llm,
+                            result_type=tool_result.result_type,
+                            error=tool_result.error,
+                            tool_telemetry=tool_result.tool_telemetry,
+                        ),
+                    )
                 )
-            )
         except Exception as exc:
             try:
                 await self.rpc.tools.handle_pending_tool_call(

python/copilot/tools.py

@@ -17,6 +17,11 @@
 
 ToolResultType = Literal["success", "failure", "rejected", "denied"]
 
+# Constant used by define_tool's exception handler so that
+# _execute_tool_and_respond can detect exception-originated failures
+# and send them via the top-level error param (matching CLI formatting).
+TOOL_EXCEPTION_TEXT = "Invoking this tool produced an error. Detailed information is not available."
+
 
 @dataclass
 class ToolBinaryResult:
@@ -195,8 +200,7 @@ async def wrapped_handler(invocation: ToolInvocation) -> ToolResult:
                 # Don't expose detailed error information to the LLM for security reasons.
                 # The actual error is stored in the 'error' field for debugging.
                 return ToolResult(
-                    text_result_for_llm="Invoking this tool produced an error. "
-                    "Detailed information is not available.",
+                    text_result_for_llm=TOOL_EXCEPTION_TEXT,
                     result_type="failure",
                     error=str(exc),
                     tool_telemetry={},