roomkit 0.78.0__tar.gz → 0.80.0__tar.gz

{roomkit-0.78.0 → roomkit-0.80.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: roomkit
-Version: 0.78.0
+Version: 0.80.0
 Summary: Pure async Python library for multi-channel conversations
 Project-URL: Homepage, https://roomkit.live
 Project-URL: Documentation, https://www.roomkit.live/docs/
@@ -39,8 +39,7 @@ Requires-Dist: botbuilder-core>=4.17; extra == 'all'
 Requires-Dist: deepgram-sdk>=6.0.0; extra == 'all'
 Requires-Dist: discord-py>=2.4; extra == 'all'
 Requires-Dist: elevenlabs>=2.40; extra == 'all'
-Requires-Dist: google-genai>=2.0.0; extra == 'all'
-Requires-Dist: google-genai>=2.18.0; extra == 'all'
+Requires-Dist: google-genai>=2.24.0; extra == 'all'
 Requires-Dist: gradium>=0.5.7; extra == 'all'
 Requires-Dist: httpx-sse>=0.4; extra == 'all'
 Requires-Dist: httpx>=0.27; extra == 'all'
@@ -96,7 +95,7 @@ Requires-Dist: asyncpg>=0.29; extra == 'dev'
 Requires-Dist: bandit>=1.7; extra == 'dev'
 Requires-Dist: botbuilder-core>=4.17; extra == 'dev'
 Requires-Dist: discord-py>=2.4; extra == 'dev'
-Requires-Dist: google-genai>=2.18.0; extra == 'dev'
+Requires-Dist: google-genai>=2.24.0; extra == 'dev'
 Requires-Dist: gradium>=0.5.7; extra == 'dev'
 Requires-Dist: httpx-sse>=0.4; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
@@ -139,7 +138,7 @@ Requires-Dist: librosa>=0.10; extra == 'fastrtc'
 Requires-Dist: numpy<2.5,>=1.26; extra == 'fastrtc'
 Requires-Dist: pydub>=0.25; extra == 'fastrtc'
 Provides-Extra: gemini
-Requires-Dist: google-genai>=2.18.0; extra == 'gemini'
+Requires-Dist: google-genai>=2.24.0; extra == 'gemini'
 Provides-Extra: gradium
 Requires-Dist: gradium>=0.5.7; extra == 'gradium'
 Provides-Extra: httpx
@@ -181,7 +180,7 @@ Provides-Extra: providers
 Requires-Dist: anthropic>=0.30; extra == 'providers'
 Requires-Dist: botbuilder-core>=4.17; extra == 'providers'
 Requires-Dist: discord-py>=2.4; extra == 'providers'
-Requires-Dist: google-genai>=2.18.0; extra == 'providers'
+Requires-Dist: google-genai>=2.24.0; extra == 'providers'
 Requires-Dist: gradium>=0.5.7; extra == 'providers'
 Requires-Dist: httpx>=0.27; extra == 'providers'
 Requires-Dist: mistralai<3,>=2.0; extra == 'providers'
@@ -205,7 +204,7 @@ Requires-Dist: websockets>=14.0; extra == 'realtime-deepgram'
 Provides-Extra: realtime-elevenlabs
 Requires-Dist: elevenlabs>=2.40; extra == 'realtime-elevenlabs'
 Provides-Extra: realtime-gemini
-Requires-Dist: google-genai>=2.0.0; extra == 'realtime-gemini'
+Requires-Dist: google-genai>=2.24.0; extra == 'realtime-gemini'
 Provides-Extra: realtime-openai
 Requires-Dist: openai>=2.28; extra == 'realtime-openai'
 Requires-Dist: websockets>=14.0; extra == 'realtime-openai'

{roomkit-0.78.0 → roomkit-0.80.0}/docs/c7/ai-channels.md

@@ -163,6 +163,26 @@ ai = AIChannel(
 )
 ```
 
+#### Refusing a call
+
+What the handler returns is the tool's answer, so a refusal returned as a body
+reads as work that was done: the tool-call event says `completed`, and an audit
+trail records a call that never ran. Raise `ToolRefusedError` instead.
+
+```python
+from roomkit import ToolRefusedError
+
+async def handle_tools(name: str, arguments: dict) -> str:
+    if name not in MY_TOOLS:
+        raise ToolRefusedError(f"Error: the tool '{name}' does not exist.")
+    ...
+```
+
+The message reaches the model verbatim, which is the point: a generic `raise`
+would replace it with `Error executing tool '<name>': <exc>`. The call is marked
+failed, `ON_TOOL_CALL` observers see `event.is_error`, and the stored
+`TOOL_CALL_END` carries the reason.
+
 ### Tool Protocol (Tool ABC)
 
 For structured tool definitions, use the `Tool` base class:

{roomkit-0.78.0 → roomkit-0.80.0}/llms-full.txt

@@ -1415,6 +1415,26 @@ ai = AIChannel(
 )
 ```
 
+#### Refusing a call
+
+What the handler returns is the tool's answer, so a refusal returned as a body
+reads as work that was done: the tool-call event says `completed`, and an audit
+trail records a call that never ran. Raise `ToolRefusedError` instead.
+
+```python
+from roomkit import ToolRefusedError
+
+async def handle_tools(name: str, arguments: dict) -> str:
+    if name not in MY_TOOLS:
+        raise ToolRefusedError(f"Error: the tool '{name}' does not exist.")
+    ...
+```
+
+The message reaches the model verbatim, which is the point: a generic `raise`
+would replace it with `Error executing tool '<name>': <exc>`. The call is marked
+failed, `ON_TOOL_CALL` observers see `event.is_error`, and the stored
+`TOOL_CALL_END` carries the reason.
+
 ### Tool Protocol (Tool ABC)
 
 For structured tool definitions, use the `Tool` base class:

{roomkit-0.78.0 → roomkit-0.80.0}/pyproject.toml

@@ -49,7 +49,7 @@ cerebras = ["openai>=2.28,<3"]
 # read like the family's umbrella install rather than the chat provider.
 qwen-ai = ["openai>=2.28,<3"]
 ollama = ["ollama>=0.4"]
-gemini = ["google-genai>=2.18.0"]
+gemini = ["google-genai>=2.24.0"]
 mistral = ["mistralai>=2.0,<3"]
 polargrid = ["polargrid-sdk>=0.10.0"]
 deepgram = ["deepgram-sdk>=6.0.0"]
@@ -88,7 +88,7 @@ twilio = ["twilio>=9.0"]
 phonenumbers = ["phonenumbers>=8.13"]
 pynacl = ["pynacl>=1.5"]
 realtime-openai = ["openai>=2.28", "websockets>=14.0"]
-realtime-gemini = ["google-genai>=2.0.0"]
+realtime-gemini = ["google-genai>=2.24.0"]
 realtime-elevenlabs = ["elevenlabs>=2.40"]
 realtime-deepgram = ["websockets>=14.0"]
 websocket = ["websockets>=14.0"]
@@ -252,6 +252,11 @@ filterwarnings = [
     "ignore:bind_voice_session\\(\\) is deprecated:DeprecationWarning",
     "ignore:connect_voice\\(auto_greet=True\\) is deprecated:DeprecationWarning",
     "ignore::ResourceWarning",
+    # google-genai builds a Union over typing._UnionGenericAlias at import
+    # time; Python 3.14 deprecates that internal (removal in 3.17). Nothing
+    # here can fix it, and without the ignore any test file that imports
+    # google.genai first fails to collect on 3.14.
+    "ignore:'_UnionGenericAlias' is deprecated:DeprecationWarning",
 ]
 
 [tool.ty.environment]

{roomkit-0.78.0 → roomkit-0.80.0}/src/roomkit/__init__.py

@@ -76,6 +76,7 @@ from roomkit.core.exceptions import (
     ParticipantNotAdmittedError,
     ProviderDeliveryError,
     RoomNotAttachedError,
+    ToolRefusedError,
     VoiceSessionEndedError,
 )
 from roomkit.core.framework import (
@@ -145,6 +146,7 @@ from roomkit.models.tool_call import (
     BeforeGenerationCallback,
     ToolCallCallback,
     ToolCallEvent,
+    ToolCallObserver,
     response_transcript,
 )
 from roomkit.models.voice_delivery import VoiceDeliveryRecord
@@ -273,6 +275,7 @@ __all__ = [
     "ConferenceCapabilityError",
     "ConferenceCloseError",
     "RoomNotAttachedError",
+    "ToolRefusedError",
     # Delivery
     "DeliveryBackend",
     "DeliveryItem",
@@ -463,6 +466,7 @@ __all__ = [
     "ThinkingEvent",
     "Tool",
     "ToolCallCallback",
+    "ToolCallObserver",
     "ToolCallContent",
     "ToolCallEvent",
     "ToolHandler",

roomkit-0.80.0/src/roomkit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.80.0"

{roomkit-0.78.0 → roomkit-0.80.0}/src/roomkit/channels/_ai_generation.py

@@ -392,9 +392,12 @@ class AIGenerationMixin(AIToolLoopRulesMixin):
             # Tool call start + end events
             for tc, rp in zip(rnd.tool_calls, rnd.results, strict=False):
                 result_val = getattr(rp, "result", None)
-                is_error = isinstance(result_val, str) and result_val.startswith(
-                    "Error executing tool"
-                )
+                # Read the outcome, never the body: the tool loop already knows
+                # whether this call failed. Matching the prose sentence it
+                # writes for a raised handler missed every other failure — a
+                # refused call, a multimodal result — and misread a tool whose
+                # own output happened to start that way.
+                is_error = bool(getattr(rp, "is_error", False))
                 events.append(
                     RoomEvent(
                         room_id=room_id,
@@ -423,7 +426,7 @@ class AIGenerationMixin(AIToolLoopRulesMixin):
                             result=result_val,
                             status="failed" if is_error else "completed",
                             duration_ms=rnd.duration_ms,
-                            error=result_val if is_error else None,
+                            error=rp.as_text() if is_error else None,
                             structured_content=getattr(rp, "structured_content", None),
                         ),
                         chain_depth=chain_depth,

{roomkit-0.78.0 → roomkit-0.80.0}/src/roomkit/channels/_ai_stream_external_tools.py

@@ -112,7 +112,10 @@ class _ExternalStreamTools:
             arguments = dict(call.arguments)
             already_executed = "_result" in arguments
             result = arguments.pop("_result", None)
-            arguments.pop("_is_error", None)
+            # The proxy's own verdict on a call it already ran. It travelled
+            # this far as a private argument; drop it from what the hook reads
+            # as arguments, keep it as the outcome it is.
+            is_error = bool(arguments.pop("_is_error", False))
             event = ToolCallEvent(
                 channel_id=self.channel_id,
                 channel_type=ChannelType.AI,
@@ -127,6 +130,7 @@ class _ExternalStreamTools:
                     else None
                 ),
                 room_id=self.room_id,
+                is_error=is_error,
             )
             if already_executed and self.after is not None:
                 await self.after(event)

{roomkit-0.78.0 → roomkit-0.80.0}/src/roomkit/channels/_ai_streaming.py

@@ -528,7 +528,7 @@ class AIStreamingMixin(AIToolLoopRulesMixin):
         turn.tool_rounds_count += 1
         for call, result in zip(calls, results, strict=False):
             value = result.result
-            is_error = isinstance(value, str) and value.startswith("Error executing tool")
+            is_error = result.is_error
             yield ToolCallEndMarker(
                 tool_name=call.name,
                 tool_id=call.id,
@@ -536,7 +536,9 @@ class AIStreamingMixin(AIToolLoopRulesMixin):
                 result=value,
                 status="failed" if is_error else "completed",
                 duration_ms=duration_ms,
-                error=value if is_error else None,
+                # ``error`` is text; a failure that answered with content parts
+                # flattens the way any text consumer of that result would.
+                error=result.as_text() if is_error else None,
                 structured_content=result.structured_content,
             )
         if turn.room_id:

{roomkit-0.78.0 → roomkit-0.80.0}/src/roomkit/channels/_ai_tools.py

@@ -36,6 +36,7 @@ from roomkit.channels._tool_search_constants import (
     TOOL_LIST_TOOLS,
     TOOL_SEARCH_INFRA_TOOL_NAMES,
 )
+from roomkit.core.exceptions import ToolRefusedError
 from roomkit.models.enums import ChannelType
 from roomkit.models.tool_call import ToolCallEvent
 from roomkit.providers.ai.base import (
@@ -59,7 +60,7 @@ if TYPE_CHECKING:
     from roomkit.channels._tool_eviction import ToolEviction
     from roomkit.channels._tool_usage import ToolUsageMemory
     from roomkit.channels.ai import _ContentPart, _ToolLoopContext
-    from roomkit.models.tool_call import ToolCallCallback
+    from roomkit.models.tool_call import ToolCallCallback, ToolCallObserver
     from roomkit.realtime.base import RealtimeBackend
     from roomkit.sandbox.executor import SandboxExecutor
     from roomkit.skills.executor import ScriptExecutor
@@ -88,6 +89,8 @@ class AIToolsHost(Protocol):
         _planner: Optional task planner.
         _realtime: Realtime backend for ephemeral events.
         _tool_call_hook: Optional unified ON_TOOL_CALL hook callback.
+        _tool_observer_hook: Optional ON_TOOL_CALL observer callback, fired for
+            a call that failed or was refused.
         channel_id: Unique identifier for this channel.
 
     Properties / methods provided by other mixins:
@@ -113,6 +116,7 @@ class AIToolsHost(Protocol):
     _realtime: RealtimeBackend | None
     _plan_updated_hook: Any  # ON_PLAN_UPDATED callback — injected by register_channel
     _tool_call_hook: ToolCallCallback | None
+    _tool_observer_hook: ToolCallObserver | None
     _before_tool_call_hook: Any
     _tool_search: bool | None
     _tool_search_pinned: set[str]
@@ -155,6 +159,7 @@ class AIToolsMixin:
     _realtime: RealtimeBackend | None
     _plan_updated_hook: Any  # ON_PLAN_UPDATED callback — injected by register_channel
     _tool_call_hook: ToolCallCallback | None
+    _tool_observer_hook: ToolCallObserver | None
     _before_tool_call_hook: Any
     _tool_search: bool | None
     _tool_search_pinned: set[str]
@@ -242,6 +247,47 @@ class AIToolsMixin:
             }
         return {"error": f"Unknown tool '{name}': it is not declared"}
 
+    async def _fire_tool_refusal(
+        self,
+        tc: Any,
+        arguments: dict[str, Any],
+        result: str,
+        room_id: str | None,
+    ) -> None:
+        """Fire ON_TOOL_CALL for a call that failed or was refused.
+
+        The refusal paths below return before the handler runs, and a handler
+        that raises jumps past the firing that follows it — so without this,
+        ON_TOOL_CALL only ever reported the calls that worked. A host auditing
+        tool use saw a denied tool as a tool that was never called, which reads
+        the same as an agent that never tried.
+
+        Observational by construction: it reaches the ASYNC observers of
+        ON_TOOL_CALL and no further. A SYNC hook is the one that can *serve* a
+        call, so a refused call must not reach one — otherwise the refusal
+        would hide the side effect instead of preventing it. A hook that raises
+        must not turn a refusal into a crash either: the refusal is already on
+        its way to the model.
+        """
+        if self._tool_observer_hook is None:
+            return
+        event = ToolCallEvent(
+            channel_id=self.channel_id,
+            channel_type=ChannelType.AI,
+            tool_call_id=tc.id,
+            name=tc.name,
+            arguments=arguments,
+            result=result,
+            room_id=room_id,
+            is_error=True,
+        )
+        try:
+            await self._tool_observer_hook(event)
+        except Exception:
+            logger.debug(
+                "ON_TOOL_CALL observation failed for refused tool %s", tc.name, exc_info=True
+            )
+
     async def _execute_tools_parallel(
         self,
         tool_calls: list[Any],
@@ -263,13 +309,15 @@ class AIToolsMixin:
         async def _run_one(tc: Any) -> AIToolResultPart:
             logger.info("Executing tool: %s(%s)", tc.name, tc.id)
 
-            def rejected(error: dict[str, Any]) -> AIToolResultPart:
+            async def rejected(error: dict[str, Any]) -> AIToolResultPart:
                 # Refusals never reach the handler's guard. Count their raw
                 # attempts here; successful calls are counted only by the
                 # handler, using the effective payload after folds and hooks.
                 guard = self._repeated_call_guard(tc.name, tc.arguments)
+                body = guard or json.dumps(error)
+                await self._fire_tool_refusal(tc, tc.arguments, body, room_id)
                 return AIToolResultPart(
-                    tool_call_id=tc.id, name=tc.name, result=guard or json.dumps(error)
+                    tool_call_id=tc.id, name=tc.name, result=body, is_error=True
                 )
 
             # Execution guard: argument validation against the declared schema
@@ -285,7 +333,7 @@ class AIToolsMixin:
                 recovered = self._recover_deferred_tool(tc.name)
                 if recovered is None:
                     logger.warning("Provider requested undeclared tool %s", tc.name)
-                    return rejected(self._undeclared_tool_error(tc.name))
+                    return await rejected(self._undeclared_tool_error(tc.name))
                 # The model skipped find_tools but named a real catalogue tool:
                 # the reveal happened at call time instead of ahead of it, and
                 # every guard below still applies.
@@ -299,7 +347,9 @@ class AIToolsMixin:
                 folded, fold_error = fold_hoisted_arguments(params, call_arguments)
                 if fold_error is not None:
                     logger.warning("Tool %s arguments ambiguous: %s", tc.name, fold_error)
-                    return rejected({"error": f"Invalid arguments for '{tc.name}': {fold_error}"})
+                    return await rejected(
+                        {"error": f"Invalid arguments for '{tc.name}': {fold_error}"}
+                    )
                 if folded is not None:
                     logger.info(
                         "Tool %s: folded hoisted arguments %s into its container (model=%s)",
@@ -311,7 +361,9 @@ class AIToolsMixin:
                 arg_error = validate_tool_arguments(params, call_arguments)
                 if arg_error is not None:
                     logger.warning("Tool %s arguments rejected: %s", tc.name, arg_error)
-                    return rejected({"error": f"Invalid arguments for '{tc.name}': {arg_error}"})
+                    return await rejected(
+                        {"error": f"Invalid arguments for '{tc.name}': {arg_error}"}
+                    )
 
             # Execution guard: policy deny (defense-in-depth, role-aware)
             # Sandbox tools are exempt — they are channel-managed, not user-managed.
@@ -324,7 +376,7 @@ class AIToolsMixin:
                 and not effective_policy.is_allowed(tc.name)
             ):
                 logger.warning("Tool %s blocked by policy", tc.name)
-                return rejected(
+                return await rejected(
                     {"error": f"Tool '{tc.name}' is not permitted by the agent's tool policy."}
                 )
 
@@ -339,7 +391,7 @@ class AIToolsMixin:
                 and matches_any_pattern(tc.name, self._gated_tool_names)
             ):
                 logger.warning("Tool %s blocked by skill gating", tc.name)
-                return rejected(
+                return await rejected(
                     {
                         "error": (
                             f"Tool '{tc.name}' is gated by a skill. "
@@ -368,7 +420,9 @@ class AIToolsMixin:
                 decision = await self._before_tool_call_hook(pre_event)
                 if not decision:
                     logger.info("Tool %s denied by BEFORE_TOOL_USE hook", tc.name)
-                    return rejected({"error": f"Tool '{tc.name}' denied by pre-execution hook."})
+                    return await rejected(
+                        {"error": f"Tool '{tc.name}' denied by pre-execution hook."}
+                    )
                 if decision.arguments is not None:
                     arguments = decision.arguments
                     arguments_rewritten = True
@@ -388,7 +442,7 @@ class AIToolsMixin:
                     logger.warning(
                         "Tool %s %sarguments rejected: %s", tc.name, qualifier, arg_error
                     )
-                    return rejected(
+                    return await rejected(
                         {"error": (f"Invalid {qualifier}arguments for '{tc.name}': {arg_error}")}
                     )
 
@@ -399,6 +453,7 @@ class AIToolsMixin:
                 attributes={"tool.name": tc.name, "tool.id": tc.id},
             )
             structured_content: dict[str, Any] | None = None
+            tool_failed = False
             if executed_arguments is not None:
                 # Snapshot the post-hook payload before handing it to user
                 # code. Streaming persistence can then distinguish what the
@@ -449,10 +504,25 @@ class AIToolsMixin:
             except asyncio.CancelledError:
                 telemetry.end_span(tool_span_id, status="cancelled")
                 raise
+            except ToolRefusedError as refusal:
+                # The branch below with the message kept. A handler that
+                # declines a call has words for the model — a host tunes them
+                # for a small one — and the generic wrapper would replace them
+                # with its own sentence, which is how the reason gets lost.
+                telemetry.end_span(tool_span_id, status="error", error_message=refusal.message)
+                logger.info("Tool %s refused: %s", tc.name, refusal.message)
+                result = refusal.message
+                tool_failed = True
+                await self._fire_tool_refusal(tc, arguments, result, room_id)
             except Exception as exc:
                 telemetry.end_span(tool_span_id, status="error", error_message=str(exc))
                 logger.warning("Tool %s raised %s: %s", tc.name, type(exc).__name__, exc)
                 result = f"Error executing tool '{tc.name}': {exc}"
+                tool_failed = True
+                # Fired here, on the raw sentence: the hook sees what the
+                # handler produced, before the repeated-result note annotates
+                # the model's copy of it — same as on the success path above.
+                await self._fire_tool_refusal(tc, arguments, result, room_id)
             # Remember this call (final result, success or error) so later turns
             # can show "tools you've already used" and re-reveal it under Tool
             # Search. Infra/discovery tools are filtered inside record().
@@ -469,6 +539,7 @@ class AIToolsMixin:
                 name=tc.name,
                 result=result,
                 structured_content=structured_content,
+                is_error=tool_failed,
             )
 
         tasks = [asyncio.create_task(_run_one(tc)) for tc in tool_calls]

{roomkit-0.78.0 → roomkit-0.80.0}/src/roomkit/channels/_conference_realtime.py

@@ -34,6 +34,7 @@ from typing import TYPE_CHECKING, Any
 
 from roomkit.channels._conference_mixer import ConferenceMixer
 from roomkit.channels._conference_operations import ConferenceResource
+from roomkit.core.exceptions import ToolRefusedError
 from roomkit.core.task_utils import log_task_exception
 from roomkit.models.event import TextContent
 from roomkit.voice.base import AudioChunk, VoiceSession
@@ -495,6 +496,17 @@ class ConferenceRealtime:
         else:
             try:
                 result = await config.tool_handler(session.room_id, name, arguments)
+            except ToolRefusedError as refusal:
+                # A declined call, in the handler's own words. Wrapping it the
+                # way the branch below wraps a crash would hand the model the
+                # exception's class name instead of the reason.
+                logger.info(
+                    "Conference channel %r: the tool handler refused %r in room %s",
+                    self._channel_id,
+                    name,
+                    session.room_id,
+                )
+                result = refusal.message
             except Exception as error:
                 logger.exception(
                     "Conference channel %r: the tool handler failed on %r in room %s",

{roomkit-0.78.0 → roomkit-0.80.0}/src/roomkit/channels/_realtime_delegation.py

@@ -20,6 +20,7 @@ import threading
 from typing import TYPE_CHECKING, Any, Literal, Protocol
 from uuid import uuid4
 
+from roomkit.core.exceptions import ToolRefusedError
 from roomkit.models.enums import HookTrigger
 from roomkit.telemetry.base import Attr, SpanKind
 from roomkit.telemetry.context import reset_span
@@ -111,6 +112,7 @@ class RealtimeDelegationMixin:
     _telemetry_provider: Any  # see RealtimeDelegationHost — cross-mixin
     _authorize_realtime_tool: Any  # see RealtimeToolsMixin
     _serve_gated_tool_call: Any  # see RealtimeToolsMixin
+    _fire_tool_refusal: Any  # see RealtimeToolsMixin
 
     # -----------------------------------------------------------------
     # Transcript ledger
@@ -376,9 +378,25 @@ class RealtimeDelegationMixin:
                 telemetry.end_span(span_id)
                 return denial
 
-            result_str = await self._serve_gated_tool_call(
-                session, call_id, name, arguments, room_id, gate_context
-            )
+            try:
+                result_str = await self._serve_gated_tool_call(
+                    session, call_id, name, arguments, room_id, gate_context
+                )
+            except ToolRefusedError as refusal:
+                # Same shape as the pre-execution denial above: the backend
+                # reads why it was refused, and the span does not report the
+                # call as one that ran.
+                telemetry.end_span(span_id, attributes={Attr.REALTIME_TOOL_DENIED: True})
+                logger.info(
+                    "Backend tool %s refused by its handler (delegation %s, session %s)",
+                    name,
+                    delegation_id,
+                    session.id,
+                )
+                await self._fire_tool_refusal(
+                    session, call_id, name, arguments, refusal.message, room_id
+                )
+                return refusal.message
             telemetry.end_span(span_id)
             logger.info(
                 "Backend tool %s handled (delegation %s, session %s)",

{roomkit-0.78.0 → roomkit-0.80.0}/src/roomkit/channels/_realtime_tool_recovery.py

@@ -25,6 +25,7 @@ from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 from uuid import uuid4
 
 from roomkit.channels._realtime_tools import result_text
+from roomkit.core.exceptions import ToolRefusedError
 from roomkit.models.enums import ChannelType
 from roomkit.telemetry.base import Attr, SpanKind
 from roomkit.voice.base import VoiceSessionState
@@ -112,6 +113,7 @@ class RealtimeToolRecoveryMixin:
     _track_task: Any  # cross-mixin
     _authorize_realtime_tool: Any  # cross-mixin (RealtimeToolsMixin)
     _fire_tool_hook: Any  # cross-mixin (RealtimeToolsMixin)
+    _fire_tool_refusal: Any  # cross-mixin (RealtimeToolsMixin)
     _truncate_tool_result: Any  # cross-mixin (RealtimeToolsMixin)
 
     # ------------------------------------------------------------------
@@ -289,6 +291,11 @@ class RealtimeToolRecoveryMixin:
                     call_id,
                     session.id,
                 )
+                # Observed like a denial on the function-calling path: an audit
+                # hook sees the refusal, and nothing that could serve it does.
+                await self._fire_tool_refusal(
+                    session, call_id, tool_name, arguments, denial, room_id
+                )
                 return
 
             # Run tool_handler.
@@ -297,10 +304,31 @@ class RealtimeToolRecoveryMixin:
                 from roomkit.channels._realtime_context import _current_voice_session
 
                 token = _current_voice_session.set(session)
+                refused: str | None = None
                 try:
                     raw = await self._tool_handler(tool_name, arguments)
+                except ToolRefusedError as refusal:
+                    refused = refusal.message
                 finally:
                     _current_voice_session.reset(token)
+                if refused is not None:
+                    # Ends the call the way the pre-execution denial above
+                    # does, and for the same reason: the model reads why it was
+                    # refused, in the handler's words, and can correct itself.
+                    await self._inject_recovered_result(
+                        session, tool_name, call_id, refused, denied=True
+                    )
+                    telemetry.end_span(span_id, attributes={Attr.REALTIME_TOOL_DENIED: True})
+                    logger.info(
+                        "Recovered tool %s(%s) refused by its handler for session %s",
+                        tool_name,
+                        call_id,
+                        session.id,
+                    )
+                    await self._fire_tool_refusal(
+                        session, call_id, tool_name, arguments, refused, room_id
+                    )
+                    return
                 handler_result = result_text(raw)
 
             # Fire ON_TOOL_CALL hook (for observability / overrides).