From 739ff2f2da8499ed8320699f6d0892ab8eff3802 Mon Sep 17 00:00:00 2001 From: Meryem Sakin Date: Sun, 13 Sep 2026 18:14:49 +0300 Subject: [PATCH 01/39] fix(guardrails): check Anthropic-format request tools in tool_permission pre_call The pre_call hook only collected tools shaped as {"type": "function", "function": {...}}, so flat tools from /v1/messages ({"name", "input_schema"}) and /v1/responses ({"type": "function", "name"}) were never checked and deny rules silently passed. Reuse the shared anthropic_tool_names helper so every request tool name is checked, and handle Anthropic tool_choice {"type": "tool"} in both block and rewrite modes. Fixes #40583 --- .../guardrail_hooks/tool_permission.py | 41 ++++++++-------- .../guardrail_hooks/test_tool_permission.py | 48 +++++++++++++++++++ 2 files changed, 69 insertions(+), 20 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index e20f0b320b9..74065522761 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -14,6 +14,7 @@ from litellm.integrations.custom_guardrail import ( CustomGuardrail, log_guardrail_information, ) +from litellm.llms.base_llm.guardrail_translation.utils import anthropic_tool_names from litellm.proxy._types import UserAPIKeyAuth from litellm.proxy.common_utils.callback_utils import ( add_guardrail_to_applied_guardrails_header, @@ -605,28 +606,32 @@ class ToolPermissionGuardrail(CustomGuardrail): if not any(_is_tool_use_block(block) for block in kept_blocks): response["stop_reason"] = "end_turn" # rebind-ok: dropping every tool_use ends the turn - def _get_request_tool_name(self, tool: object) -> tuple[str | None, str | None]: + def _get_request_tool_targets(self, tool: object) -> tuple[tuple[str, str | None], ...]: tool_type: Final = self._get_mapping_value(tool, "type") - if tool_type != "function": - return None, tool_type - - function: Final = self._get_mapping_value(tool, "function") - tool_name: Final = self._get_mapping_value(function, "name") - return tool_name, tool_type + normalized_type: Final = "function" if tool_type in (None, "custom") else tool_type + return tuple((name, normalized_type) for name in anthropic_tool_names(tool)) def _get_legacy_function_name(self, function: object) -> str | None: return self._get_mapping_value(function, "name") - def _get_named_tool_choice(self, data: dict) -> str | None: + def _get_named_tool_choice(self, data: Mapping[str, object]) -> str | None: tool_choice: Final = data.get("tool_choice") if not tool_choice or tool_choice in ("auto", "none", "required"): return None if isinstance(tool_choice, str): return tool_choice - if self._get_mapping_value(tool_choice, "type") != "function": + choice_type: Final[object] = self._get_mapping_value(tool_choice, "type") + if choice_type == "tool": + return self._get_mapping_value(tool_choice, "name") + if choice_type != "function": return None return self._get_mapping_value(self._get_mapping_value(tool_choice, "function"), "name") + @staticmethod + def _is_anthropic_tool_choice(data: Mapping[str, object]) -> bool: + tool_choice: Final = _object_mapping(data.get("tool_choice")) + return tool_choice is not None and tool_choice.get("type") == "tool" + def _get_named_function_call(self, data: dict) -> str | None: function_call: Final = data.get("function_call") if not function_call or function_call in ("auto", "none"): @@ -639,9 +644,7 @@ class ToolPermissionGuardrail(CustomGuardrail): request_tools: Final[list[tuple[str, str | None]]] = [] for tool in data.get("tools") or []: - tool_name, tool_type = self._get_request_tool_name(tool) - if tool_name is not None: - request_tools.append((tool_name, tool_type)) + request_tools.extend(self._get_request_tool_targets(tool)) for function in data.get("functions") or []: function_name = self._get_legacy_function_name(function) @@ -681,13 +684,11 @@ class ToolPermissionGuardrail(CustomGuardrail): tools: Final[list[ChatCompletionToolParam] | None] = data.get("tools") if tools is not None: - new_tools: Final = [] - for tool in tools: - tool_name, tool_type = self._get_request_tool_name(tool) - if tool_type == "function" and tool_name in error_tool_names: - continue - new_tools.append(tool) - data["tools"] = new_tools + data["tools"] = [ + tool + for tool in tools + if not any(name in error_tool_names for name, _ in self._get_request_tool_targets(tool)) + ] functions: Final = data.get("functions") if functions is not None: @@ -697,7 +698,7 @@ class ToolPermissionGuardrail(CustomGuardrail): named_tool_choice: Final = self._get_named_tool_choice(data) if named_tool_choice in error_tool_names: - data["tool_choice"] = "none" + data["tool_choice"] = {"type": "none"} if self._is_anthropic_tool_choice(data) else "none" named_function_call: Final = self._get_named_function_call(data) if named_function_call in error_tool_names: diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 87a1b84acc5..7e8b89c8833 100644 --- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -1177,6 +1177,54 @@ class TestToolPermissionGuardrailAnthropicMessages: def _tool_use(self, name, tool_id="tu_1"): return {"type": "tool_use", "id": tool_id, "name": name, "input": {"command": "ls"}} + @pytest.mark.asyncio + @pytest.mark.parametrize( + "denied_tool", + [ + {"name": "Read", "input_schema": {"type": "object", "properties": {}}}, + {"type": "custom", "name": "Read", "input_schema": {"type": "object", "properties": {}}}, + {"type": "function", "name": "Read", "parameters": {"type": "object", "properties": {}}}, + ], + ids=["anthropic", "anthropic_custom_type", "responses_api_flat_function"], + ) + async def test_pre_call_blocks_denied_request_tool_in_flat_format(self, denied_tool): + data = {"model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "hi"}], "tools": [denied_tool]} + + with patch.object(self.blocking, "should_run_guardrail", return_value=True): + with pytest.raises(HTTPException) as excinfo: + await self.blocking.async_pre_call_hook( + user_api_key_dict=UserAPIKeyAuth(), + cache=DualCache(default_in_memory_ttl=1), + data=data, + call_type="anthropic_messages", + ) + + assert excinfo.value.status_code == 400 + assert excinfo.value.detail["detection_message"] == "Tool 'Read' denied by rule 'deny_read'" + + @pytest.mark.asyncio + async def test_pre_call_rewrite_strips_denied_anthropic_tool_and_forced_choice(self): + data = { + "model": "claude-sonnet-4-5", + "messages": [{"role": "user", "content": "hi"}], + "tools": [ + {"name": "Bash", "input_schema": {"type": "object", "properties": {}}}, + {"name": "Read", "input_schema": {"type": "object", "properties": {}}}, + ], + "tool_choice": {"type": "tool", "name": "Read"}, + } + + with patch.object(self.rewriting, "should_run_guardrail", return_value=True): + result = await self.rewriting.async_pre_call_hook( + user_api_key_dict=UserAPIKeyAuth(), + cache=DualCache(default_in_memory_ttl=1), + data=data, + call_type="anthropic_messages", + ) + + assert [tool["name"] for tool in result["tools"]] == ["Bash"] + assert result["tool_choice"] == {"type": "none"} + @pytest.mark.asyncio async def test_denied_anthropic_tool_use_is_blocked(self): response = self._response({"type": "text", "text": "reading"}, self._tool_use("Read")) From 1a346a20695911a9399026d1a212b98b1831b732 Mon Sep 17 00:00:00 2001 From: Meryem Sakin Date: Sun, 13 Sep 2026 19:41:38 +0300 Subject: [PATCH 02/39] fix(guardrails): detect Responses API named tool_choice in tool_permission Responses API named choices put the name at the top level ({"type": "function", "name": ...}), so rewrite mode removed the denied tool but left a tool_choice pointing at it. --- .../guardrail_hooks/tool_permission.py | 8 ++--- .../guardrail_hooks/test_tool_permission.py | 33 ++++++++++++++----- 2 files changed, 28 insertions(+), 13 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 74065522761..3cc46690b57 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -620,12 +620,10 @@ class ToolPermissionGuardrail(CustomGuardrail): return None if isinstance(tool_choice, str): return tool_choice - choice_type: Final[object] = self._get_mapping_value(tool_choice, "type") - if choice_type == "tool": - return self._get_mapping_value(tool_choice, "name") - if choice_type != "function": + if self._get_mapping_value(tool_choice, "type") not in ("tool", "function"): return None - return self._get_mapping_value(self._get_mapping_value(tool_choice, "function"), "name") + function_name: Final = self._get_mapping_value(self._get_mapping_value(tool_choice, "function"), "name") + return function_name or self._get_mapping_value(tool_choice, "name") @staticmethod def _is_anthropic_tool_choice(data: Mapping[str, object]) -> bool: diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 7e8b89c8833..bc43f35ef47 100644 --- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -1203,15 +1203,32 @@ class TestToolPermissionGuardrailAnthropicMessages: assert excinfo.value.detail["detection_message"] == "Tool 'Read' denied by rule 'deny_read'" @pytest.mark.asyncio - async def test_pre_call_rewrite_strips_denied_anthropic_tool_and_forced_choice(self): + @pytest.mark.parametrize( + ("tool_shape", "tool_choice", "call_type", "expected_tool_choice"), + [ + ( + {"input_schema": {"type": "object", "properties": {}}}, + {"type": "tool", "name": "Read"}, + "anthropic_messages", + {"type": "none"}, + ), + ( + {"type": "function", "parameters": {"type": "object", "properties": {}}}, + {"type": "function", "name": "Read"}, + "responses", + "none", + ), + ], + ids=["anthropic", "responses_api"], + ) + async def test_pre_call_rewrite_strips_denied_flat_tool_and_forced_choice( + self, tool_shape, tool_choice, call_type, expected_tool_choice + ): data = { "model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "hi"}], - "tools": [ - {"name": "Bash", "input_schema": {"type": "object", "properties": {}}}, - {"name": "Read", "input_schema": {"type": "object", "properties": {}}}, - ], - "tool_choice": {"type": "tool", "name": "Read"}, + "tools": [{"name": "Bash", **tool_shape}, {"name": "Read", **tool_shape}], + "tool_choice": tool_choice, } with patch.object(self.rewriting, "should_run_guardrail", return_value=True): @@ -1219,11 +1236,11 @@ class TestToolPermissionGuardrailAnthropicMessages: user_api_key_dict=UserAPIKeyAuth(), cache=DualCache(default_in_memory_ttl=1), data=data, - call_type="anthropic_messages", + call_type=call_type, ) assert [tool["name"] for tool in result["tools"]] == ["Bash"] - assert result["tool_choice"] == {"type": "none"} + assert result["tool_choice"] == expected_tool_choice @pytest.mark.asyncio async def test_denied_anthropic_tool_use_is_blocked(self): From 9d23a8ad033b272eeab0409914073a0a8453c574 Mon Sep 17 00:00:00 2001 From: Meryem Sakin Date: Sun, 13 Sep 2026 19:49:22 +0300 Subject: [PATCH 03/39] test(guardrails): run tool_permission pre_call tests through real default_on gating Build the guardrail as an always-on pre_call guardrail instead of patching should_run_guardrail. --- .../guardrail_hooks/test_tool_permission.py | 38 +++++++++++-------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py index bc43f35ef47..bea75cb4987 100644 --- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -1177,6 +1177,16 @@ class TestToolPermissionGuardrailAnthropicMessages: def _tool_use(self, name, tool_id="tu_1"): return {"type": "tool_use", "id": tool_id, "name": name, "input": {"command": "ls"}} + def _always_on_pre_call(self, on_disallowed_action): + return ToolPermissionGuardrail( + guardrail_name=f"anthropic-pre-call-{on_disallowed_action}", + rules=self.rules, + default_action="deny", + on_disallowed_action=on_disallowed_action, + event_hook=GuardrailEventHooks.pre_call, + default_on=True, + ) + @pytest.mark.asyncio @pytest.mark.parametrize( "denied_tool", @@ -1190,14 +1200,13 @@ class TestToolPermissionGuardrailAnthropicMessages: async def test_pre_call_blocks_denied_request_tool_in_flat_format(self, denied_tool): data = {"model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "hi"}], "tools": [denied_tool]} - with patch.object(self.blocking, "should_run_guardrail", return_value=True): - with pytest.raises(HTTPException) as excinfo: - await self.blocking.async_pre_call_hook( - user_api_key_dict=UserAPIKeyAuth(), - cache=DualCache(default_in_memory_ttl=1), - data=data, - call_type="anthropic_messages", - ) + with pytest.raises(HTTPException) as excinfo: + await self._always_on_pre_call("block").async_pre_call_hook( + user_api_key_dict=UserAPIKeyAuth(), + cache=DualCache(default_in_memory_ttl=1), + data=data, + call_type="anthropic_messages", + ) assert excinfo.value.status_code == 400 assert excinfo.value.detail["detection_message"] == "Tool 'Read' denied by rule 'deny_read'" @@ -1231,13 +1240,12 @@ class TestToolPermissionGuardrailAnthropicMessages: "tool_choice": tool_choice, } - with patch.object(self.rewriting, "should_run_guardrail", return_value=True): - result = await self.rewriting.async_pre_call_hook( - user_api_key_dict=UserAPIKeyAuth(), - cache=DualCache(default_in_memory_ttl=1), - data=data, - call_type=call_type, - ) + result = await self._always_on_pre_call("rewrite").async_pre_call_hook( + user_api_key_dict=UserAPIKeyAuth(), + cache=DualCache(default_in_memory_ttl=1), + data=data, + call_type=call_type, + ) assert [tool["name"] for tool in result["tools"]] == ["Bash"] assert result["tool_choice"] == expected_tool_choice From c25cee4e92085ee0866f5fee0263a81fc94a8048 Mon Sep 17 00:00:00 2001 From: Meryem Sakin Date: Sun, 13 Sep 2026 19:55:27 +0300 Subject: [PATCH 04/39] test(guardrails): type the new tool_permission pre_call test parameters --- .../guardrail_hooks/test_tool_permission.py | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py index bea75cb4987..0bd27e5c9e9 100644 --- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -5,6 +5,7 @@ Unit tests for Tool Permission Guardrail (OpenAI tool_calls semantics) import json import logging import re +from typing import Literal from unittest.mock import patch import pytest @@ -24,6 +25,7 @@ from litellm.types.proxy.guardrails.guardrail_hooks.tool_permission import ( PermissionError, ) from litellm.types.utils import ( + CallTypesLiteral, ChatCompletionMessageToolCall, Choices, ModelResponse, @@ -1177,7 +1179,7 @@ class TestToolPermissionGuardrailAnthropicMessages: def _tool_use(self, name, tool_id="tu_1"): return {"type": "tool_use", "id": tool_id, "name": name, "input": {"command": "ls"}} - def _always_on_pre_call(self, on_disallowed_action): + def _always_on_pre_call(self, on_disallowed_action: Literal["block", "rewrite"]) -> ToolPermissionGuardrail: return ToolPermissionGuardrail( guardrail_name=f"anthropic-pre-call-{on_disallowed_action}", rules=self.rules, @@ -1197,7 +1199,7 @@ class TestToolPermissionGuardrailAnthropicMessages: ], ids=["anthropic", "anthropic_custom_type", "responses_api_flat_function"], ) - async def test_pre_call_blocks_denied_request_tool_in_flat_format(self, denied_tool): + async def test_pre_call_blocks_denied_request_tool_in_flat_format(self, denied_tool: dict[str, object]) -> None: data = {"model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "hi"}], "tools": [denied_tool]} with pytest.raises(HTTPException) as excinfo: @@ -1231,8 +1233,12 @@ class TestToolPermissionGuardrailAnthropicMessages: ids=["anthropic", "responses_api"], ) async def test_pre_call_rewrite_strips_denied_flat_tool_and_forced_choice( - self, tool_shape, tool_choice, call_type, expected_tool_choice - ): + self, + tool_shape: dict[str, object], + tool_choice: dict[str, str], + call_type: CallTypesLiteral, + expected_tool_choice: dict[str, str] | str, + ) -> None: data = { "model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "hi"}], From b4b66e6bf55ef43123cae8b14aae9624f732f3af Mon Sep 17 00:00:00 2001 From: Meryem Sakin Date: Tue, 15 Sep 2026 16:57:47 +0300 Subject: [PATCH 05/39] fix(guardrails): keep the Responses API custom tool type distinct Anthropic's user-defined tools carry type "custom", so pre_call mapped that to "function" for tool_type rules. The Responses API has its own custom tool type, and mapping it let a custom tool slip past a tool_type deny rule when the default action is allow. Normalize only for the formats where custom means a plain function, and read tool names directly in the rewrite path, which never needed a type. --- .../guardrail_hooks/tool_permission.py | 19 ++++++----- .../guardrail_hooks/test_tool_permission.py | 34 +++++++++++++++++++ 2 files changed, 45 insertions(+), 8 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 3cc46690b57..819e743c209 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -41,6 +41,7 @@ from litellm.types.utils import ( ) GUARDRAIL_NAME: Final = "tool_permission" +_RESPONSES_CALL_TYPES: Final = frozenset({"responses", "aresponses", "_aresponses_websocket"}) def _object_mapping(value: object) -> Mapping[str, object] | None: @@ -606,9 +607,13 @@ class ToolPermissionGuardrail(CustomGuardrail): if not any(_is_tool_use_block(block) for block in kept_blocks): response["stop_reason"] = "end_turn" # rebind-ok: dropping every tool_use ends the turn - def _get_request_tool_targets(self, tool: object) -> tuple[tuple[str, str | None], ...]: + def _get_request_tool_targets( + self, tool: object, call_type: CallTypesLiteral + ) -> tuple[tuple[str, str | None], ...]: tool_type: Final = self._get_mapping_value(tool, "type") - normalized_type: Final = "function" if tool_type in (None, "custom") else tool_type + normalized_type: Final = ( + tool_type if call_type in _RESPONSES_CALL_TYPES or tool_type not in (None, "custom") else "function" + ) return tuple((name, normalized_type) for name in anthropic_tool_names(tool)) def _get_legacy_function_name(self, function: object) -> str | None: @@ -638,11 +643,11 @@ class ToolPermissionGuardrail(CustomGuardrail): return function_call return self._get_mapping_value(function_call, "name") - def _collect_request_tools(self, data: dict) -> list[tuple[str, str | None]]: + def _collect_request_tools(self, data: dict, call_type: CallTypesLiteral) -> list[tuple[str, str | None]]: request_tools: Final[list[tuple[str, str | None]]] = [] for tool in data.get("tools") or []: - request_tools.extend(self._get_request_tool_targets(tool)) + request_tools.extend(self._get_request_tool_targets(tool, call_type)) for function in data.get("functions") or []: function_name = self._get_legacy_function_name(function) @@ -683,9 +688,7 @@ class ToolPermissionGuardrail(CustomGuardrail): tools: Final[list[ChatCompletionToolParam] | None] = data.get("tools") if tools is not None: data["tools"] = [ - tool - for tool in tools - if not any(name in error_tool_names for name, _ in self._get_request_tool_targets(tool)) + tool for tool in tools if not any(name in error_tool_names for name in anthropic_tool_names(tool)) ] functions: Final = data.get("functions") @@ -806,7 +809,7 @@ class ToolPermissionGuardrail(CustomGuardrail): if self.should_run_guardrail(data=data, event_type=event_type) is not True: return data - new_tools: Final = self._collect_request_tools(data) + new_tools: Final = self._collect_request_tools(data, call_type) if not new_tools: verbose_proxy_logger.debug( "Tool Permission Guardrail: not running guardrail. No tools or functions in data" diff --git a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 0bd27e5c9e9..c0d17e0428c 100644 --- a/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/test_litellm/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -1213,6 +1213,40 @@ class TestToolPermissionGuardrailAnthropicMessages: assert excinfo.value.status_code == 400 assert excinfo.value.detail["detection_message"] == "Tool 'Read' denied by rule 'deny_read'" + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("rule_tool_type", "call_type"), + [(r"^custom$", "responses"), (r"^function$", "anthropic_messages")], + ids=["responses_custom_stays_custom", "anthropic_custom_reads_as_function"], + ) + async def test_pre_call_tool_type_rules_follow_the_request_format( + self, rule_tool_type: str, call_type: CallTypesLiteral + ) -> None: + guardrail = ToolPermissionGuardrail( + guardrail_name=f"tool-type-{call_type}", + rules=[{"id": "deny_type", "tool_type": rule_tool_type, "decision": "deny"}], + default_action="allow", + on_disallowed_action="block", + event_hook=GuardrailEventHooks.pre_call, + default_on=True, + ) + data = { + "model": "claude-sonnet-4-5", + "messages": [{"role": "user", "content": "hi"}], + "tools": [{"type": "custom", "name": "apply_patch", "input_schema": {"type": "object", "properties": {}}}], + } + + with pytest.raises(HTTPException) as excinfo: + await guardrail.async_pre_call_hook( + user_api_key_dict=UserAPIKeyAuth(), + cache=DualCache(default_in_memory_ttl=1), + data=data, + call_type=call_type, + ) + + assert excinfo.value.status_code == 400 + assert excinfo.value.detail["detection_message"] == "Tool 'apply_patch' denied by rule 'deny_type'" + @pytest.mark.asyncio @pytest.mark.parametrize( ("tool_shape", "tool_choice", "call_type", "expected_tool_choice"), From c55c340437fd5d52cb7d957d9e3d07bc2878b7e7 Mon Sep 17 00:00:00 2001 From: Meryem Sakin Date: Sat, 10 Oct 2026 14:22:52 +0300 Subject: [PATCH 06/39] test(guardrails): cover flat tools through Messages and Responses Add blocked and permitted flat-tool cases through the running proxy, with endpoint coverage and metadata for the current e2e harness Require a guardrail policy verdict when checking denied tools so an unrelated provider error cannot satisfy the regression test Co-authored-by: Christopher Krah --- tests/e2e/coverage_registry/guardrail.yaml | 4 +- .../test_tool_permission_guardrail_e2e.py | 197 ++++++++++++++++-- tests/e2e/models.py | 29 +++ 3 files changed, 216 insertions(+), 14 deletions(-) diff --git a/tests/e2e/coverage_registry/guardrail.yaml b/tests/e2e/coverage_registry/guardrail.yaml index 99cffa8fc3d..a5ede2c8775 100644 --- a/tests/e2e/coverage_registry/guardrail.yaml +++ b/tests/e2e/coverage_registry/guardrail.yaml @@ -25,8 +25,8 @@ - {id: guardrail.ibm_guardrails.post_call.blocks, module: guardrail, tier: P1, hook_point: post_call, assertions: [blocks], exercised_on: [chat_completions], source: "guardrail_hooks/ibm_guardrails/ibm_detector.py", rationale: "Output policy validation"} - {id: guardrail.semantic_guard.pre_call.blocks, module: guardrail, tier: P1, hook_point: pre_call, assertions: [blocks], exercised_on: [chat_completions], source: "guardrail_hooks/semantic_guard", rationale: "Semantic policy compliance"} - {id: guardrail.block_code_execution.pre_call.blocks, module: guardrail, tier: P1, hook_point: pre_call, assertions: [blocks], exercised_on: [chat_completions], source: "guardrail_hooks/block_code_execution", rationale: "Code-injection prevention"} -- {id: guardrail.tool_permission.pre_call.allows, module: guardrail, tier: P1, hook_point: pre_call, assertions: [allows], exercised_on: [chat_completions], source: "guardrail_hooks/tool_permission.py", rationale: "Grant allowed tools"} -- {id: guardrail.tool_permission.pre_call.blocks, module: guardrail, tier: P1, hook_point: pre_call, assertions: [blocks], exercised_on: [chat_completions], source: "guardrail_hooks/tool_permission.py", rationale: "Block unauthorized tools"} +- {id: guardrail.tool_permission.pre_call.allows, module: guardrail, tier: P1, hook_point: pre_call, assertions: [allows], exercised_on: [chat_completions, messages, responses], source: "guardrail_hooks/tool_permission.py", rationale: "Grant allowed tools"} +- {id: guardrail.tool_permission.pre_call.blocks, module: guardrail, tier: P1, hook_point: pre_call, assertions: [blocks], exercised_on: [chat_completions, messages, responses], source: "guardrail_hooks/tool_permission.py", rationale: "Block unauthorized tools"} - {id: guardrail.microsoft_purview.pre_call.blocks, module: guardrail, tier: P1, hook_point: pre_call, assertions: [blocks], exercised_on: [chat_completions], source: "guardrail_hooks/microsoft_purview/purview_dlp.py", rationale: "DLP sensitive-data disclosure"} - {id: guardrail.headroom.pre_call.blocks, module: guardrail, tier: P1, hook_point: pre_call, assertions: [blocks], exercised_on: [chat_completions], source: "guardrail_hooks/headroom/headroom.py", rationale: "Anomaly detection threshold"} - {id: guardrail.generic_guardrail_api.pre_call.blocks, module: guardrail, tier: P1, hook_point: pre_call, assertions: [blocks], exercised_on: [chat_completions], source: "guardrail_hooks/generic_guardrail_api/generic_guardrail_api.py", rationale: "Vendor-agnostic custom API"} diff --git a/tests/e2e/guardrails/test_tool_permission_guardrail_e2e.py b/tests/e2e/guardrails/test_tool_permission_guardrail_e2e.py index d5a6a9d9866..87545299169 100644 --- a/tests/e2e/guardrails/test_tool_permission_guardrail_e2e.py +++ b/tests/e2e/guardrails/test_tool_permission_guardrail_e2e.py @@ -19,10 +19,9 @@ verdict comes from the proxy itself. from __future__ import annotations -from typing import Final +from typing import Final, Literal import pytest - from e2e_config import unique_marker from e2e_http import StreamingResponse, UnknownApiError from e2e_metadata import Capability, Domain, Mode, Provider, Subject, meta @@ -31,14 +30,29 @@ from guardrails_client import ( ToolPermissionParamsBody, ToolPermissionRuleBody, poll_until_blocked, + poll_until_blocked_stream, poll_until_guardrail_applied, ) from lifecycle import ResourceManager -from models import ChatResponse, ChatTool, ChatToolFunction +from models import ( + AnthropicCustomTool, + AnthropicMessagesBody, + AnthropicMessagesResponse, + AnthropicToolChoice, + ChatMessage, + ChatResponse, + ChatTool, + ChatToolFunction, + JsonSchemaProperty, + ResponsesFunctionTool, + ResponsesToolBody, + ResponsesToolOutput, + ToolInputSchema, +) -pytestmark = pytest.mark.e2e +pytestmark: Final = pytest.mark.e2e -MODEL = "gemini-2.5-flash" +MODEL: Final = "gemini-2.5-flash" #: The one tool the guardrail permits, and one it does not. Both are declared by #: the caller in the request body; the guardrail reads them there. @@ -63,11 +77,15 @@ DENIED_TOOL: Final = ChatTool( TOOL_PROMPT: Final = "What is the weather in Paris right now?" +type FlatToolEndpoint = Literal["messages", "responses"] +ALLOWED_TOOL_SCHEMA: Final = ToolInputSchema(properties={"city": JsonSchemaProperty(type="string")}, required=["city"]) +DENIED_TOOL_SCHEMA: Final = ToolInputSchema() + def _register_tool_permission(client: GuardrailsClient, resources: ResourceManager, *, name: str) -> None: """Allow-list exactly one tool: everything else falls to `default_action=deny` and, with `on_disallowed_action=block`, is rejected outright.""" - guardrail_id = client.register( + guardrail_id: Final = client.register( name, ToolPermissionParamsBody( mode="pre_call", @@ -100,6 +118,57 @@ def _tool_call_names(response: ChatResponse) -> tuple[str, ...]: ) +def _send_flat_tool( + client: GuardrailsClient, + key: str, + endpoint: FlatToolEndpoint, + *, + guardrail: str, + tool: ChatTool, + schema: ToolInputSchema, + require_tool: bool = False, +) -> StreamingResponse: + name: Final = tool.function.name + match endpoint: + case "messages": + return client.proxy.transport.send( + "/v1/messages", + headers=client.proxy.transport.bearer(key), + json=AnthropicMessagesBody( + model=MODEL, + messages=[ChatMessage(role="user", content=TOOL_PROMPT)], + max_tokens=128, + tools=[ + AnthropicCustomTool(name=name, description=tool.function.description or "", input_schema=schema) + ], + tool_choice=AnthropicToolChoice(type="any") if require_tool else None, + guardrails=[guardrail], + ), + ) + case "responses": + return client.proxy.transport.send( + "/v1/responses", + headers=client.proxy.transport.bearer(key), + json=ResponsesToolBody( + model=MODEL, + input=TOOL_PROMPT, + tools=[ResponsesFunctionTool(name=name, description=tool.function.description, parameters=schema)], + tool_choice="required" if require_tool else None, + guardrails=[guardrail], + ), + ) + + +def _flat_tool_call_names(endpoint: FlatToolEndpoint, body: str) -> tuple[str, ...]: + match endpoint: + case "messages": + content: Final = AnthropicMessagesResponse.model_validate_json(body).content or [] + return tuple(block.name for block in content if block.type == "tool_use" and block.name) + case "responses": + output: Final = ResponsesToolOutput.model_validate_json(body).output + return tuple(item.name for item in output if item.type == "function_call" and item.name) + + class TestToolPermissionPreCall: @pytest.mark.covers("guardrail.tool_permission.pre_call.blocks", exercised_on=["chat_completions"]) @meta( @@ -118,10 +187,10 @@ class TestToolPermissionPreCall: rejected with a 400 that names the denied tool. An unauthorized tool that merely reaches the model is the whole failure mode this guardrail exists to prevent, so a 200 here is a hard failure.""" - name = f"e2e-toolperm-block-{unique_marker()}" + name: Final = f"e2e-toolperm-block-{unique_marker()}" _register_tool_permission(client, resources, name=name) - result = poll_until_blocked( + result: Final = poll_until_blocked( lambda: client.chat( scoped_key, MODEL, @@ -161,10 +230,10 @@ class TestToolPermissionPreCall: and the model calls it. Without the header check a guardrail that never attached would pass this test for the wrong reason, so the 200 alone is not the contract.""" - name = f"e2e-toolperm-allow-{unique_marker()}" + name: Final = f"e2e-toolperm-allow-{unique_marker()}" _register_tool_permission(client, resources, name=name) - outcome = poll_until_guardrail_applied( + outcome: Final = poll_until_guardrail_applied( lambda: client.chat_raw( scoped_key, MODEL, @@ -178,13 +247,117 @@ class TestToolPermissionPreCall: ) assert outcome.ok, f"the permitted tool must be served, got {outcome.status_code}: {outcome.body[:400]}" - applied = _applied_guardrails(outcome) + applied: Final = _applied_guardrails(outcome) assert name in applied, ( "the allowed call must carry x-litellm-applied-guardrails naming the guardrail; " f"without it the 200 only proves the guardrail never ran. Got {applied!r}" ) - called = _tool_call_names(ChatResponse.model_validate_json(outcome.body)) + called: Final = _tool_call_names(ChatResponse.model_validate_json(outcome.body)) + assert called == (ALLOWED_TOOL.function.name,), ( + f"the served call must carry one tool call for the permitted tool, got {called!r}: {outcome.body[:400]}" + ) + + @pytest.mark.parametrize( + "endpoint", + [ + pytest.param( + "messages", + marks=pytest.mark.covers("guardrail.tool_permission.pre_call.blocks", exercised_on=["messages"]), + ), + pytest.param( + "responses", + marks=pytest.mark.covers("guardrail.tool_permission.pre_call.blocks", exercised_on=["responses"]), + ), + ], + ) + @meta( + Subject( + domain=Domain.GUARDRAILS, + providers=(Provider.GEMINI,), + models=(MODEL,), + capabilities=(Capability.FUNCTION_CALLING,), + mode=Mode.NONSTREAM, + ) + ) + def test_pre_call_blocks_flat_tool_outside_the_allow_list( + self, + client: GuardrailsClient, + resources: ResourceManager, + scoped_key: str, + endpoint: FlatToolEndpoint, + ) -> None: + name: Final = f"e2e-toolperm-block-{endpoint}-{unique_marker()}" + _register_tool_permission(client, resources, name=name) + + outcome: Final = poll_until_blocked_stream( + lambda: _send_flat_tool( + client, scoped_key, endpoint, guardrail=name, tool=DENIED_TOOL, schema=DENIED_TOOL_SCHEMA + ) + ) + + assert outcome.status_code == 400, ( + f"tool_permission let a tool outside the allow-list through /{endpoint}; " + f"got {outcome.status_code}: {outcome.body[:400]}" + ) + assert DENIED_TOOL.function.name in outcome.body, ( + f"the block must name the denied tool so the caller can fix the request; got: {outcome.body[:400]}" + ) + assert "Violated guardrail policy" in outcome.body, ( + f"the block must be a guardrail verdict, got: {outcome.body[:400]}" + ) + + @pytest.mark.parametrize( + "endpoint", + [ + pytest.param( + "messages", + marks=pytest.mark.covers("guardrail.tool_permission.pre_call.allows", exercised_on=["messages"]), + ), + pytest.param( + "responses", + marks=pytest.mark.covers("guardrail.tool_permission.pre_call.allows", exercised_on=["responses"]), + ), + ], + ) + @meta( + Subject( + domain=Domain.GUARDRAILS, + providers=(Provider.GEMINI,), + models=(MODEL,), + capabilities=(Capability.FUNCTION_CALLING,), + mode=Mode.NONSTREAM, + ) + ) + def test_pre_call_allows_permitted_flat_tool( + self, + client: GuardrailsClient, + resources: ResourceManager, + scoped_key: str, + endpoint: FlatToolEndpoint, + ) -> None: + name: Final = f"e2e-toolperm-allow-{endpoint}-{unique_marker()}" + _register_tool_permission(client, resources, name=name) + + outcome: Final = poll_until_guardrail_applied( + lambda: _send_flat_tool( + client, + scoped_key, + endpoint, + guardrail=name, + tool=ALLOWED_TOOL, + schema=ALLOWED_TOOL_SCHEMA, + require_tool=True, + ), + name, + ) + + assert outcome.ok, f"the permitted tool must be served, got {outcome.status_code}: {outcome.body[:400]}" + applied: Final = _applied_guardrails(outcome) + assert name in applied, ( + f"the allowed call must carry x-litellm-applied-guardrails naming the guardrail; got {applied!r}" + ) + called: Final = _flat_tool_call_names(endpoint, outcome.body) assert called == (ALLOWED_TOOL.function.name,), ( f"the served call must carry one tool call for the permitted tool, got {called!r}: {outcome.body[:400]}" ) diff --git a/tests/e2e/models.py b/tests/e2e/models.py index 3ae200ff5e7..581b924a4b7 100644 --- a/tests/e2e/models.py +++ b/tests/e2e/models.py @@ -589,6 +589,35 @@ class ResponsesStreamBody(BaseModel): cache: dict[str, bool] | None = {"no-cache": True} +class ResponsesFunctionTool(BaseModel): + model_config = ConfigDict(frozen=True) + type: Literal["function"] = "function" + name: str + description: str | None = None + parameters: ToolInputSchema + + +class ResponsesToolBody(BaseModel): + model_config = ConfigDict(frozen=True) + model: str + input: str + tools: list[ResponsesFunctionTool] + tool_choice: Literal["required"] | None = None + guardrails: list[str] + max_output_tokens: int = 128 + + +class ResponsesOutputItem(BaseModel): + model_config = ConfigDict(frozen=True) + type: str + name: str | None = None + + +class ResponsesToolOutput(BaseModel): + model_config = ConfigDict(frozen=True) + output: list[ResponsesOutputItem] + + class CountTokensBody(BaseModel): """POST /v1/messages/count_tokens body: the /v1/messages shape minus max_tokens (the endpoint only counts the prompt).""" From 69dae9682e4841c43e1bb496ab4ca8d8278a8fa2 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 18:51:24 -0700 Subject: [PATCH 07/39] fix(guardrails): check namespace and nameless tools and relax tool_choice in tool permission rewrite --- .../guardrail_hooks/tool_permission.py | 243 +++++++++++++----- .../proxy/response_api_endpoints/endpoints.py | 4 +- .../guardrail_hooks/test_tool_permission.py | 196 ++++++++++++++ .../response_api_endpoints/test_endpoints.py | 25 ++ 4 files changed, 401 insertions(+), 67 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 2b6d361fd95..78a7c662b6a 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -1,13 +1,13 @@ import json import re from collections.abc import AsyncGenerator, AsyncIterable, Mapping, Sequence -from typing import Any, Final, Literal, TypedDict +from itertools import chain +from typing import Any, Final, Literal, TypeAlias, TypedDict from fastapi import HTTPException from pydantic import TypeAdapter from typing_extensions import ReadOnly, Required -from litellm import ChatCompletionToolParam from litellm._logging import verbose_proxy_logger from litellm.caching.dual_cache import DualCache from litellm.completion_extras.litellm_responses_transformation.transformation import ( @@ -49,6 +49,8 @@ GUARDRAIL_NAME: Final = "tool_permission" _RESPONSES_CALL_TYPES: Final = frozenset({"responses", "aresponses", "_aresponses_websocket"}) _DECODED_ARGUMENTS: Final = TypeAdapter(object) _REQUEST_DATA: Final = TypeAdapter(object) +_OPTIONAL_REQUEST_LIST: Final = TypeAdapter(list[object] | None) +_ToolTarget: TypeAlias = tuple[str | None, str | None] def _object_mapping(value: object) -> Mapping[str, object] | None: @@ -67,6 +69,67 @@ def _function_tool_name(tool: object) -> str | None: return name if isinstance(name, str) else None +def _non_empty_string(value: object) -> str | None: + return value if isinstance(value, str) and value else None + + +def _request_tool_names(tool: object) -> tuple[str, ...]: + fields: Final = _object_mapping(tool) + custom: Final = ( + _object_mapping(fields.get("custom")) if fields is not None and fields.get("type") == "custom" else None + ) + custom_name: Final = _non_empty_string(custom.get("name")) if custom is not None else None + return anthropic_tool_names(tool) + ((custom_name,) if custom_name is not None else ()) + + +def _namespace_members(tool: object) -> Sequence[object]: + fields: Final = _object_mapping(tool) + members: Final = ( + _object_list(fields.get("tools")) if fields is not None and fields.get("type") == "namespace" else None + ) + return members or () + + +def _namespace_member_target(namespace: str | None, member: object) -> _ToolTarget | None: + fields: Final = _object_mapping(member) + if fields is None: + return None + member_type: Final = _non_empty_string(fields.get("type")) + name: Final = _non_empty_string(fields.get("name")) + qualified: Final = name is not None and namespace is not None and member_type != "custom" + return (f"{namespace}__{name}" if qualified else name, member_type) + + +def _allowed_tool_entries(tool_choice: Mapping[str, object]) -> Sequence[object] | None: + if tool_choice.get("type") != "allowed_tools": + return None + nested: Final = _object_mapping(tool_choice.get("allowed_tools")) + return _object_list((nested if nested is not None else tool_choice).get("tools")) + + +def _with_allowed_tool_entries(tool_choice: Mapping[str, object], entries: list[object]) -> dict[str, object]: + nested: Final = _object_mapping(tool_choice.get("allowed_tools")) + if nested is None: + return {**tool_choice, "tools": entries} + return {**tool_choice, "allowed_tools": {**nested, "tools": entries}} + + +def _is_denied_target( + target: _ToolTarget, denied_targets: frozenset[_ToolTarget], denied_names: frozenset[str] +) -> bool: + return target in denied_targets or target[0] in denied_names + + +def _none_tool_choice(tool_choice: object) -> object: + choice: Final = _object_mapping(tool_choice) + return {"type": "none"} if choice is not None and choice.get("type") in ("tool", "any") else "none" + + +def _requires_a_tool(tool_choice: object) -> bool: + choice: Final = _object_mapping(tool_choice) + return tool_choice == "required" or (choice is not None and choice.get("type") == "any") + + class _ToolPermissionRuleFields(TypedDict, total=False): """The config-file shape a :class:`ToolPermissionRule` is built from.""" @@ -618,34 +681,34 @@ class ToolPermissionGuardrail(CustomGuardrail): if not any(_is_tool_use_block(block) for block in kept_blocks): response["stop_reason"] = "end_turn" # rebind-ok: dropping every tool_use ends the turn - def _get_request_tool_targets( - self, tool: object, call_type: CallTypesLiteral - ) -> tuple[tuple[str, str | None], ...]: + def _get_request_tool_targets(self, tool: object, call_type: CallTypesLiteral) -> tuple[_ToolTarget, ...]: + members: Final = _namespace_members(tool) + if members: + namespace: Final = _non_empty_string(self._get_mapping_value(tool, "name")) + member_targets: Final = (_namespace_member_target(namespace, member) for member in members) + return tuple(target for target in member_targets if target is not None) tool_type: Final = self._get_mapping_value(tool, "type") normalized_type: Final = ( tool_type if call_type in _RESPONSES_CALL_TYPES or tool_type not in (None, "custom") else "function" ) - return tuple((name, normalized_type) for name in anthropic_tool_names(tool)) + names: Final = _request_tool_names(tool) + if names: + return tuple((name, normalized_type) for name in names) + return ((None, normalized_type),) if isinstance(tool_type, str) else () def _get_legacy_function_name(self, function: object) -> str | None: return self._get_mapping_value(function, "name") - def _get_named_tool_choice(self, data: Mapping[str, object]) -> str | None: - tool_choice: Final = data.get("tool_choice") + def _get_named_tool_choice(self, tool_choice: object) -> str | None: if not tool_choice or tool_choice in ("auto", "none", "required"): return None if isinstance(tool_choice, str): return tool_choice - if self._get_mapping_value(tool_choice, "type") not in ("tool", "function"): + if self._get_mapping_value(tool_choice, "type") not in ("tool", "function", "custom"): return None function_name: Final = self._get_mapping_value(self._get_mapping_value(tool_choice, "function"), "name") return function_name or self._get_mapping_value(tool_choice, "name") - @staticmethod - def _is_anthropic_tool_choice(data: Mapping[str, object]) -> bool: - tool_choice: Final = _object_mapping(data.get("tool_choice")) - return tool_choice is not None and tool_choice.get("type") == "tool" - def _get_named_function_call(self, data: dict) -> str | None: function_call: Final = data.get("function_call") if not function_call or function_call in ("auto", "none"): @@ -654,8 +717,8 @@ class ToolPermissionGuardrail(CustomGuardrail): return function_call return self._get_mapping_value(function_call, "name") - def _collect_request_tools(self, data: dict, call_type: CallTypesLiteral) -> list[tuple[str, str | None]]: - request_tools: Final[list[tuple[str, str | None]]] = [] + def _collect_request_tools(self, data: dict, call_type: CallTypesLiteral) -> list[_ToolTarget]: + request_tools: Final[list[_ToolTarget]] = [] for tool in data.get("tools") or []: request_tools.extend(self._get_request_tool_targets(tool, call_type)) @@ -666,7 +729,7 @@ class ToolPermissionGuardrail(CustomGuardrail): request_tools.append((function_name, "function")) for forced_tool_name in ( - self._get_named_tool_choice(data), + self._get_named_tool_choice(_REQUEST_DATA.validate_python(data.get("tool_choice"))), self._get_named_function_call(data), ): if forced_tool_name is not None: @@ -677,51 +740,101 @@ class ToolPermissionGuardrail(CustomGuardrail): return request_tools + def _tool_names_in(self, tools: Sequence[object], call_type: CallTypesLiteral) -> frozenset[str]: + targets: Final = chain.from_iterable(self._get_request_tool_targets(tool, call_type) for tool in tools) + return frozenset(name for name, _ in targets if name is not None) + + def _kept_tools( + self, + tool: object, + denied_targets: frozenset[_ToolTarget], + denied_names: frozenset[str], + call_type: CallTypesLiteral, + ) -> tuple[object, ...]: + members: Final = _namespace_members(tool) + fields: Final = _object_mapping(tool) + if not members or fields is None: + targets: Final = self._get_request_tool_targets(tool, call_type) + denied: Final = any(_is_denied_target(target, denied_targets, denied_names) for target in targets) + return () if denied else (tool,) + namespace: Final = _non_empty_string(fields.get("name")) + kept_members: Final = [ + member + for member in members + if not _is_denied_target( + _namespace_member_target(namespace, member) or (None, None), denied_targets, denied_names + ) + ] + if not kept_members: + return () + return (tool,) if len(kept_members) == len(members) else ({**fields, "tools": kept_members},) + + def _rewritten_tool_choice(self, tool_choice: object, removed_names: frozenset[str], tools_remain: bool) -> object: + named: Final = self._get_named_tool_choice(tool_choice) + if named is not None and named in removed_names: + return _none_tool_choice(tool_choice) + choice: Final = _object_mapping(tool_choice) + allowed: Final = _allowed_tool_entries(choice) if choice is not None else None + if choice is not None and allowed is not None: + kept: Final = [ + entry for entry in allowed if not any(name in removed_names for name in _request_tool_names(entry)) + ] + return _with_allowed_tool_entries(choice, kept) if kept and tools_remain else _none_tool_choice(choice) + if not tools_remain and (named is not None or _requires_a_tool(tool_choice)): + return _none_tool_choice(tool_choice) + return tool_choice + def _modify_request_with_permission_errors( self, data: dict, - denied_tool_names: list[str], + denied_targets: frozenset[_ToolTarget], + call_type: CallTypesLiteral, ): """ - Modify the request to replace denied tool_calls blocks with error results - - Args: - data: The model request to modify - denied_tools: List of (tool_use, error) tuples for denied tools + Remove denied tools from the request, and relax any tool_choice that would still require one """ - if not denied_tool_names: + if not denied_targets: return data - verbose_proxy_logger.info("Blocking %s unauthorized tool uses", len(denied_tool_names)) + verbose_proxy_logger.info("Blocking %s unauthorized tool uses", len(denied_targets)) - # Create a mapping of tool_use_id to error result - error_tool_names: Final = set() - for tool_use in denied_tool_names: - error_tool_names.add(tool_use) + denied_names: Final = frozenset(name for name, _ in denied_targets if name is not None) + tools: Final = _OPTIONAL_REQUEST_LIST.validate_python(data.get("tools")) + kept_tools: Final = ( + None + if tools is None + else list( + chain.from_iterable(self._kept_tools(tool, denied_targets, denied_names, call_type) for tool in tools) + ) + ) + if kept_tools is not None: + data["tools"] = kept_tools - tools: Final[list[ChatCompletionToolParam] | None] = data.get("tools") - if tools is not None: - data["tools"] = [ - tool for tool in tools if not any(name in error_tool_names for name in anthropic_tool_names(tool)) - ] + functions: Final = _OPTIONAL_REQUEST_LIST.validate_python(data.get("functions")) + kept_functions: Final = ( + None + if functions is None + else [function for function in functions if self._get_legacy_function_name(function) not in denied_names] + ) + if kept_functions is not None: + data["functions"] = kept_functions - functions: Final = data.get("functions") - if functions is not None: - data["functions"] = [ - function for function in functions if self._get_legacy_function_name(function) not in error_tool_names - ] - - named_tool_choice: Final = self._get_named_tool_choice(data) - if named_tool_choice in error_tool_names: - data["tool_choice"] = {"type": "none"} if self._is_anthropic_tool_choice(data) else "none" + removed_names: Final = denied_names | ( + self._tool_names_in(tools, call_type) - self._tool_names_in(kept_tools, call_type) + if tools is not None and kept_tools is not None + else frozenset() + ) + tool_choice: Final = _REQUEST_DATA.validate_python(data.get("tool_choice")) + if tool_choice is not None: + data["tool_choice"] = self._rewritten_tool_choice( + tool_choice, removed_names, bool(kept_tools) or bool(kept_functions) + ) named_function_call: Final = self._get_named_function_call(data) - if named_function_call in error_tool_names: + if named_function_call in denied_names: data["function_call"] = "none" - messages: Final = without_tool_search_items_loading( - _REQUEST_DATA.validate_python(data), frozenset(denied_tool_names) - ) + messages: Final = without_tool_search_items_loading(_REQUEST_DATA.validate_python(data), denied_names) if messages is not None: data["messages"] = messages # rebind-ok: rewrite mode edits the request in place @@ -836,25 +949,25 @@ class ToolPermissionGuardrail(CustomGuardrail): ) return data - # Check permissions for each tool - denied_tool_names: Final = [] - for tool_name, tool_type in new_tools: - is_allowed, _, message = self._check_tool_permission(tool_name, tool_type) + decisions: Final = tuple((target, self._check_tool_permission(*target)) for target in new_tools) + denied: Final = tuple( + (target, message) + for target, (is_allowed, _, message) in decisions + if not is_allowed and message is not None + ) + for _, message in denied: + verbose_proxy_logger.info("Tool Permission Guardrail: %s", message) + if denied and self.on_disallowed_action == "block": + raise HTTPException( + status_code=400, + detail={ + "error": "Violated guardrail policy", + "detection_message": denied[0][1], + }, + ) - if not is_allowed and message is not None: - verbose_proxy_logger.info("Tool Permission Guardrail: %s", message) - if self.on_disallowed_action == "block": - raise HTTPException( - status_code=400, - detail={ - "error": "Violated guardrail policy", - "detection_message": message, - }, - ) - denied_tool_names.append(tool_name) - - if denied_tool_names: - data = self._modify_request_with_permission_errors(data, denied_tool_names) + if denied: + self._modify_request_with_permission_errors(data, frozenset(target for target, _ in denied), call_type) verbose_proxy_logger.debug("Tool Permission Guardrail Pre-Call Hook: All tools allowed") diff --git a/litellm/proxy/response_api_endpoints/endpoints.py b/litellm/proxy/response_api_endpoints/endpoints.py index 4f8b1697f7e..9f4955d7181 100644 --- a/litellm/proxy/response_api_endpoints/endpoints.py +++ b/litellm/proxy/response_api_endpoints/endpoints.py @@ -2048,7 +2048,7 @@ _WS_FRAME: Final = TypeAdapter(dict[str, object]) _GUARDRAIL_INFORMATION: Final = TypeAdapter(list[dict[str, object]]) _PII_TOKENS: Final = TypeAdapter(dict[str, str]) _GUARDRAIL_INFORMATION_KEY: Final = "standard_logging_guardrail_information" -_GUARDED_FRAME_FIELDS: Final = ("input", "instructions", "tools") +_GUARDED_FRAME_FIELDS: Final = ("input", "instructions", "tools", "tool_choice") _CLIENT_METADATA_KEYS: Final = ("metadata", "litellm_metadata") # the guardrail list is merged from key, team and the admission frame; a later frame cannot shrink it _CLIENT_GUARDRAIL_SELECTORS: Final = ("guardrails", "guardrail_config", "policies") @@ -2092,7 +2092,7 @@ def _responses_ws_frame_guard( nested: Final = frame_obj.get("response") if isinstance(nested, dict) and any(key in frame_obj for key in _GUARDED_FRAME_FIELDS): raise ValueError( - "response.create carries input, instructions or tools both at the top level and under response" + "response.create carries input, instructions, tools or tool_choice both at the top level and under response" ) body: Final = _WS_FRAME.validate_python(nested) if isinstance(nested, dict) else frame_obj frame_data: Final = { diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 6847e9b133f..3467feb6fac 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -1362,6 +1362,202 @@ class TestToolPermissionGuardrailAnthropicMessages: assert [tool["name"] for tool in result["tools"]] == ["Bash"] assert result["tool_choice"] == expected_tool_choice + def _pre_call( + self, + rules: list[dict[str, str]], + on_disallowed_action: Literal["block", "rewrite"], + default_action: Literal["allow", "deny"] = "allow", + ) -> ToolPermissionGuardrail: + return ToolPermissionGuardrail( + guardrail_name=f"request-shapes-{on_disallowed_action}", + rules=rules, + default_action=default_action, + on_disallowed_action=on_disallowed_action, + event_hook=GuardrailEventHooks.pre_call, + default_on=True, + ) + + async def _run_pre_call( + self, guardrail: ToolPermissionGuardrail, data: dict[str, object], call_type: CallTypesLiteral + ) -> dict[str, object]: + return await guardrail.async_pre_call_hook( + user_api_key_dict=UserAPIKeyAuth(), + cache=DualCache(default_in_memory_ttl=1), + data=data, + call_type=call_type, + ) + + def _namespace(self, *member_names: str) -> dict[str, object]: + return { + "type": "namespace", + "name": "mcp__everything", + "tools": [{"type": "function", "name": name, "parameters": {"type": "object"}} for name in member_names], + } + + @pytest.mark.asyncio + async def test_pre_call_blocks_a_denied_tool_inside_a_responses_namespace(self) -> None: + guardrail = self._pre_call( + [{"id": "deny_sum", "tool_name": r"^mcp__everything__get_sum$", "decision": "deny"}], "block" + ) + data = {"model": "gpt-5", "input": "add 2 and 3", "tools": [self._namespace("echo", "get_sum")]} + + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, "responses") + + assert excinfo.value.detail["detection_message"] == "Tool 'mcp__everything__get_sum' denied by rule 'deny_sum'" + + @pytest.mark.asyncio + async def test_pre_call_rewrite_drops_denied_namespace_members_and_empty_namespaces(self) -> None: + guardrail = self._pre_call([{"id": "deny_sum", "tool_name": r"^.*get_sum$", "decision": "deny"}], "rewrite") + partly_denied = {**self._namespace("echo", "get_sum"), "name": "mcp__kept"} + data = {"model": "gpt-5", "input": "add", "tools": [partly_denied, self._namespace("get_sum")]} + + result = await self._run_pre_call(guardrail, data, "responses") + + assert result["tools"] == [{**partly_denied, "tools": partly_denied["tools"][:1]}] + + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("rule", "tool", "call_type", "detection_message"), + [ + ( + {"id": "deny_mcp", "tool_type": r"^mcp$", "decision": "deny"}, + {"type": "mcp", "server_label": "weather", "server_url": "https://mcp.example.com"}, + "responses", + "Tool 'mcp' denied by rule 'deny_mcp'", + ), + ( + {"id": "allow_bash", "tool_name": r"^Bash$", "decision": "allow"}, + {"type": "mcp_toolset", "mcp_server_name": "weather"}, + "anthropic_messages", + "Tool 'mcp_toolset' denied by default action", + ), + ( + {"id": "deny_read", "tool_name": r"^Read$", "decision": "deny"}, + {"type": "custom", "custom": {"name": "Read"}}, + "acompletion", + "Tool 'Read' denied by rule 'deny_read'", + ), + ], + ids=["responses_mcp_by_type", "anthropic_mcp_toolset_by_default", "chat_custom_nested_name"], + ) + async def test_pre_call_checks_tools_that_carry_no_top_level_name( + self, rule: dict[str, str], tool: dict[str, object], call_type: CallTypesLiteral, detection_message: str + ) -> None: + guardrail = self._pre_call([rule], "block", default_action="deny") + data = {"model": "m", "messages": [{"role": "user", "content": "hi"}], "input": "hi", "tools": [tool]} + + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, call_type) + + assert excinfo.value.detail["detection_message"] == detection_message + + @pytest.mark.asyncio + async def test_pre_call_passes_a_tool_no_rule_could_ever_match(self) -> None: + guardrail = self._pre_call(self.rules, "block", default_action="deny") + data = {"model": "gemini-3", "messages": [{"role": "user", "content": "hi"}], "tools": [{"googleSearch": {}}]} + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [{"googleSearch": {}}] + + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("tools", "tool_choice", "call_type", "expected_tool_choice"), + [ + ( + [{"type": "custom", "name": "Bash"}, {"type": "custom", "name": "Read"}], + {"type": "custom", "name": "Read"}, + "responses", + "none", + ), + ( + [{"type": "function", "name": "Bash"}, {"type": "function", "name": "Read"}], + { + "type": "allowed_tools", + "mode": "required", + "tools": [{"type": "function", "name": "Read"}, {"type": "function", "name": "Bash"}], + }, + "responses", + {"type": "allowed_tools", "mode": "required", "tools": [{"type": "function", "name": "Bash"}]}, + ), + ( + [{"type": "function", "name": "Bash"}, {"type": "function", "name": "Read"}], + {"type": "allowed_tools", "mode": "required", "tools": [{"type": "function", "name": "Read"}]}, + "responses", + "none", + ), + ( + [ + {"type": "function", "function": {"name": "Bash"}}, + {"type": "function", "function": {"name": "Read"}}, + ], + { + "type": "allowed_tools", + "allowed_tools": {"mode": "auto", "tools": [{"type": "function", "function": {"name": "Read"}}]}, + }, + "acompletion", + "none", + ), + ( + [{"name": "Read", "input_schema": {"type": "object"}}], + {"type": "any"}, + "anthropic_messages", + {"type": "none"}, + ), + ( + [ + {"name": "Bash", "input_schema": {"type": "object"}}, + {"name": "Read", "input_schema": {"type": "object"}}, + ], + {"type": "any"}, + "anthropic_messages", + {"type": "any"}, + ), + ], + ids=[ + "responses_custom_choice", + "responses_allowed_tools_keeps_the_rest", + "responses_allowed_tools_all_denied", + "chat_allowed_tools_all_denied", + "anthropic_any_with_no_tools_left", + "anthropic_any_with_a_tool_left", + ], + ) + async def test_pre_call_rewrite_leaves_no_tool_choice_that_needs_a_removed_tool( + self, + tools: list[dict[str, object]], + tool_choice: dict[str, object], + call_type: CallTypesLiteral, + expected_tool_choice: dict[str, object] | str, + ) -> None: + guardrail = self._pre_call(self.rules, "rewrite") + data = { + "model": "m", + "messages": [{"role": "user", "content": "hi"}], + "tools": tools, + "tool_choice": tool_choice, + } + + result = await self._run_pre_call(guardrail, data, call_type) + + assert result["tool_choice"] == expected_tool_choice + + @pytest.mark.asyncio + async def test_pre_call_rewrite_relaxes_a_choice_for_a_tool_a_type_rule_removed(self) -> None: + guardrail = self._pre_call([{"id": "deny_custom", "tool_type": r"^custom$", "decision": "deny"}], "rewrite") + data = { + "model": "gpt-5", + "input": "patch it", + "tools": [{"type": "function", "name": "Bash"}, {"type": "custom", "name": "apply_patch"}], + "tool_choice": {"type": "custom", "name": "apply_patch"}, + } + + result = await self._run_pre_call(guardrail, data, "responses") + + assert result["tools"] == [{"type": "function", "name": "Bash"}] + assert result["tool_choice"] == "none" + @pytest.mark.asyncio async def test_denied_anthropic_tool_use_is_blocked(self): response = self._response({"type": "text", "text": "reading"}, self._tool_use("Read")) diff --git a/tests/unit/proxy/response_api_endpoints/test_endpoints.py b/tests/unit/proxy/response_api_endpoints/test_endpoints.py index 7760b6b7fcc..63d019c6b03 100644 --- a/tests/unit/proxy/response_api_endpoints/test_endpoints.py +++ b/tests/unit/proxy/response_api_endpoints/test_endpoints.py @@ -2179,6 +2179,31 @@ class TestResponsesWSFirstFrameModelAuth: "response": {"input": "hi [guarded]", "tools": tools[:1]}, } + @pytest.mark.asyncio + @pytest.mark.parametrize("nested", [True, False]) + async def test_frame_guard_forwards_the_tool_choice_a_guardrail_rewrote(self, nested: bool): + from litellm.proxy.response_api_endpoints.endpoints import _responses_ws_frame_guard + + async def pre_call_hook(user_api_key_dict, data, call_type, guardrails_only): + return {**data, "tools": [], "tool_choice": "none"} + + proxy_logging_obj = MagicMock() + proxy_logging_obj.pre_call_hook = AsyncMock(side_effect=pre_call_hook) + guard = _responses_ws_frame_guard( + {"model": "gpt-4o-mini", "litellm_metadata": {}}, MagicMock(), proxy_logging_obj, MagicMock() + ) + body = { + "input": "hi", + "tools": [{"type": "function", "name": "a"}], + "tool_choice": {"type": "function", "name": "a"}, + } + frame = {"type": "response.create", "response": body} if nested else {"type": "response.create", **body} + + guarded = json.loads((await guard(json.dumps(frame))).frame) + + sent = guarded["response"] if nested else guarded + assert (sent["tools"], sent["tool_choice"]) == ([], "none") + @pytest.mark.asyncio async def test_frame_guard_strips_the_proxy_owned_metadata_keys_a_client_sends(self): from litellm.proxy.response_api_endpoints.endpoints import _responses_ws_frame_guard From 14bf22f3943432bc08fe51b8a7591d65223a96fe Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 23:53:49 -0700 Subject: [PATCH 08/39] fix(guardrails): check forced, grouped, loaded, and hosted tools by their real type --- .../guardrail_hooks/tool_permission.py | 156 +++++++++++++++--- .../guardrail_hooks/test_tool_permission.py | 150 ++++++++++++++++- 2 files changed, 274 insertions(+), 32 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 78a7c662b6a..fe7f8d8dc17 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -1,7 +1,10 @@ import json import re -from collections.abc import AsyncGenerator, AsyncIterable, Mapping, Sequence +from collections.abc import AsyncGenerator, AsyncIterable, Callable, Mapping, Sequence +from dataclasses import dataclass +from functools import partial from itertools import chain +from types import MappingProxyType from typing import Any, Final, Literal, TypeAlias, TypedDict from fastapi import HTTPException @@ -47,9 +50,13 @@ from litellm.types.utils import ( GUARDRAIL_NAME: Final = "tool_permission" _RESPONSES_CALL_TYPES: Final = frozenset({"responses", "aresponses", "_aresponses_websocket"}) +_ANTHROPIC_CALL_TYPES: Final = frozenset({"anthropic_messages", "aanthropic_messages"}) +_HOSTED_SERVER_NAME_FIELDS: Final = MappingProxyType({"mcp": "server_label", "mcp_toolset": "mcp_server_name"}) +_DECLARATION_KEYS: Final = ("functionDeclarations", "function_declarations") +_NAMED_CHOICE_TYPES: Final = frozenset({"tool", "function", "custom", "allowed_tools", "any", "auto", "none"}) _DECODED_ARGUMENTS: Final = TypeAdapter(object) _REQUEST_DATA: Final = TypeAdapter(object) -_OPTIONAL_REQUEST_LIST: Final = TypeAdapter(list[object] | None) +_OPTIONAL_REQUEST_LIST: Final[TypeAdapter[list[object] | None]] = TypeAdapter(list[object] | None) _ToolTarget: TypeAlias = tuple[str | None, str | None] @@ -79,7 +86,11 @@ def _request_tool_names(tool: object) -> tuple[str, ...]: _object_mapping(fields.get("custom")) if fields is not None and fields.get("type") == "custom" else None ) custom_name: Final = _non_empty_string(custom.get("name")) if custom is not None else None - return anthropic_tool_names(tool) + ((custom_name,) if custom_name is not None else ()) + server_field: Final = _HOSTED_SERVER_NAME_FIELDS.get(str(fields.get("type"))) if fields is not None else None + server_name: Final = ( + _non_empty_string(fields.get(server_field)) if fields is not None and server_field is not None else None + ) + return anthropic_tool_names(tool) + tuple(name for name in (custom_name, server_name) if name is not None) def _namespace_members(tool: object) -> Sequence[object]: @@ -96,10 +107,57 @@ def _namespace_member_target(namespace: str | None, member: object) -> _ToolTarg return None member_type: Final = _non_empty_string(fields.get("type")) name: Final = _non_empty_string(fields.get("name")) - qualified: Final = name is not None and namespace is not None and member_type != "custom" + qualified: Final = name is not None and namespace is not None return (f"{namespace}__{name}" if qualified else name, member_type) +def _declaration_target(declaration: object) -> _ToolTarget | None: + fields: Final = _object_mapping(declaration) + name: Final = _non_empty_string(fields.get("name")) if fields is not None else None + return (name, "function") if name is not None else None + + +@dataclass(frozen=True, slots=True) +class _MemberGroup: + key: str + members: Sequence[object] + target_of: Callable[[object], _ToolTarget | None] + + +def _member_group(tool: object) -> _MemberGroup | None: + fields: Final = _object_mapping(tool) + if fields is None: + return None + members: Final = _namespace_members(tool) + if members: + return _MemberGroup("tools", members, partial(_namespace_member_target, _non_empty_string(fields.get("name")))) + key: Final = next((key for key in _DECLARATION_KEYS if _object_list(fields.get(key))), None) + declarations: Final = _object_list(fields.get(key)) if key is not None else None + return _MemberGroup(key, declarations, _declaration_target) if key is not None and declarations else None + + +def _sole_key(tool: object) -> str | None: + fields: Final = _object_mapping(tool) + keys: Final = tuple(fields) if fields is not None else () + return keys[0] if len(keys) == 1 and keys[0] not in _DECLARATION_KEYS else None + + +def _tool_search_output_tools(item: object) -> Sequence[object] | None: + fields: Final = _object_mapping(item) + return ( + _object_list(fields.get("tools")) if fields is not None and fields.get("type") == "tool_search_output" else None + ) + + +def _input_items(data: object) -> Sequence[object]: + fields: Final = _object_mapping(data) + return (_object_list(fields.get("input")) if fields is not None else None) or () + + +def _loaded_input_tools(data: object) -> tuple[object, ...]: + return tuple(chain.from_iterable(_tool_search_output_tools(item) or () for item in _input_items(data))) + + def _allowed_tool_entries(tool_choice: Mapping[str, object]) -> Sequence[object] | None: if tool_choice.get("type") != "allowed_tools": return None @@ -682,19 +740,19 @@ class ToolPermissionGuardrail(CustomGuardrail): response["stop_reason"] = "end_turn" # rebind-ok: dropping every tool_use ends the turn def _get_request_tool_targets(self, tool: object, call_type: CallTypesLiteral) -> tuple[_ToolTarget, ...]: - members: Final = _namespace_members(tool) - if members: - namespace: Final = _non_empty_string(self._get_mapping_value(tool, "name")) - member_targets: Final = (_namespace_member_target(namespace, member) for member in members) - return tuple(target for target in member_targets if target is not None) + group: Final = _member_group(tool) + if group is not None: + return tuple(target for target in map(group.target_of, group.members) if target is not None) tool_type: Final = self._get_mapping_value(tool, "type") - normalized_type: Final = ( - tool_type if call_type in _RESPONSES_CALL_TYPES or tool_type not in (None, "custom") else "function" - ) + reads_as_function: Final = tool_type is None or (tool_type == "custom" and call_type in _ANTHROPIC_CALL_TYPES) + normalized_type: Final = "function" if reads_as_function else tool_type names: Final = _request_tool_names(tool) if names: return tuple((name, normalized_type) for name in names) - return ((None, normalized_type),) if isinstance(tool_type, str) else () + if isinstance(tool_type, str): + return ((None, tool_type),) + sole_key: Final = _sole_key(tool) + return ((None, sole_key),) if sole_key is not None else () def _get_legacy_function_name(self, function: object) -> str | None: return self._get_mapping_value(function, "name") @@ -704,10 +762,18 @@ class ToolPermissionGuardrail(CustomGuardrail): return None if isinstance(tool_choice, str): return tool_choice - if self._get_mapping_value(tool_choice, "type") not in ("tool", "function", "custom"): + choice: Final = _object_mapping(tool_choice) + if choice is None: return None - function_name: Final = self._get_mapping_value(self._get_mapping_value(tool_choice, "function"), "name") - return function_name or self._get_mapping_value(tool_choice, "name") + choice_type: Final = choice.get("type") + server_field: Final = _HOSTED_SERVER_NAME_FIELDS.get(str(choice_type)) + if server_field is not None: + return _non_empty_string(choice.get(server_field)) + if choice_type not in ("tool", "function", "custom"): + return None + nested: Final = _object_mapping(choice.get(str(choice_type))) + nested_name: Final = _non_empty_string(nested.get("name")) if nested is not None else None + return nested_name or _non_empty_string(choice.get("name")) def _get_named_function_call(self, data: dict) -> str | None: function_call: Final = data.get("function_call") @@ -728,15 +794,18 @@ class ToolPermissionGuardrail(CustomGuardrail): if function_name is not None: request_tools.append((function_name, "function")) + listed_names: Final = frozenset(name for name, _ in request_tools) for forced_tool_name in ( self._get_named_tool_choice(_REQUEST_DATA.validate_python(data.get("tool_choice"))), self._get_named_function_call(data), ): - if forced_tool_name is not None: + if forced_tool_name is not None and forced_tool_name not in listed_names: request_tools.append((forced_tool_name, "function")) replayed: Final = map(_function_tool_name, replayed_tool_search_tools(_REQUEST_DATA.validate_python(data))) request_tools.extend((name, "function") for name in replayed if name is not None) + for loaded_tool in _loaded_input_tools(data): + request_tools.extend(self._get_request_tool_targets(loaded_tool, call_type)) return request_tools @@ -751,29 +820,51 @@ class ToolPermissionGuardrail(CustomGuardrail): denied_names: frozenset[str], call_type: CallTypesLiteral, ) -> tuple[object, ...]: - members: Final = _namespace_members(tool) + group: Final = _member_group(tool) fields: Final = _object_mapping(tool) - if not members or fields is None: + if group is None or fields is None: targets: Final = self._get_request_tool_targets(tool, call_type) denied: Final = any(_is_denied_target(target, denied_targets, denied_names) for target in targets) return () if denied else (tool,) - namespace: Final = _non_empty_string(fields.get("name")) kept_members: Final = [ member - for member in members - if not _is_denied_target( - _namespace_member_target(namespace, member) or (None, None), denied_targets, denied_names - ) + for member in group.members + if not _is_denied_target(group.target_of(member) or (None, None), denied_targets, denied_names) ] if not kept_members: return () - return (tool,) if len(kept_members) == len(members) else ({**fields, "tools": kept_members},) + return (tool,) if len(kept_members) == len(group.members) else ({**fields, group.key: kept_members},) - def _rewritten_tool_choice(self, tool_choice: object, removed_names: frozenset[str], tools_remain: bool) -> object: + def _with_kept_loaded_tools( + self, + item: object, + denied_targets: frozenset[_ToolTarget], + denied_names: frozenset[str], + call_type: CallTypesLiteral, + ) -> object: + fields: Final = _object_mapping(item) + loaded: Final = _tool_search_output_tools(item) + if fields is None or loaded is None: + return item + kept: Final = chain.from_iterable( + self._kept_tools(tool, denied_targets, denied_names, call_type) for tool in loaded + ) + return {**fields, "tools": list(kept)} + + def _tool_types_in(self, tools: Sequence[object], call_type: CallTypesLiteral) -> frozenset[str]: + targets: Final = chain.from_iterable(self._get_request_tool_targets(tool, call_type) for tool in tools) + return frozenset(tool_type for _, tool_type in targets if tool_type is not None) + + def _rewritten_tool_choice( + self, tool_choice: object, removed_names: frozenset[str], removed_types: frozenset[str], tools_remain: bool + ) -> object: named: Final = self._get_named_tool_choice(tool_choice) if named is not None and named in removed_names: return _none_tool_choice(tool_choice) choice: Final = _object_mapping(tool_choice) + hosted_type: Final = choice.get("type") if choice is not None else None + if hosted_type not in _NAMED_CHOICE_TYPES and hosted_type in removed_types: + return _none_tool_choice(tool_choice) allowed: Final = _allowed_tool_entries(choice) if choice is not None else None if choice is not None and allowed is not None: kept: Final = [ @@ -824,12 +915,23 @@ class ToolPermissionGuardrail(CustomGuardrail): if tools is not None and kept_tools is not None else frozenset() ) + removed_types: Final = ( + self._tool_types_in(tools, call_type) - self._tool_types_in(kept_tools, call_type) + if tools is not None and kept_tools is not None + else frozenset() + ) tool_choice: Final = _REQUEST_DATA.validate_python(data.get("tool_choice")) if tool_choice is not None: data["tool_choice"] = self._rewritten_tool_choice( - tool_choice, removed_names, bool(kept_tools) or bool(kept_functions) + tool_choice, removed_names, removed_types, bool(kept_tools) or bool(kept_functions) ) + input_items: Final = _input_items(data) + if any(_tool_search_output_tools(item) is not None for item in input_items): + data["input"] = [ + self._with_kept_loaded_tools(item, denied_targets, denied_names, call_type) for item in input_items + ] + named_function_call: Final = self._get_named_function_call(data) if named_function_call in denied_names: data["function_call"] = "none" diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 3467feb6fac..bf26bbb62a9 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -1424,13 +1424,43 @@ class TestToolPermissionGuardrailAnthropicMessages: {"id": "deny_mcp", "tool_type": r"^mcp$", "decision": "deny"}, {"type": "mcp", "server_label": "weather", "server_url": "https://mcp.example.com"}, "responses", - "Tool 'mcp' denied by rule 'deny_mcp'", + "Tool 'weather' denied by rule 'deny_mcp'", ), ( {"id": "allow_bash", "tool_name": r"^Bash$", "decision": "allow"}, {"type": "mcp_toolset", "mcp_server_name": "weather"}, "anthropic_messages", - "Tool 'mcp_toolset' denied by default action", + "Tool 'weather' denied by default action", + ), + ( + {"id": "deny_weather", "tool_name": r"^weather$", "decision": "deny"}, + {"type": "mcp", "server_label": "weather", "server_url": "https://mcp.example.com"}, + "responses", + "Tool 'weather' denied by rule 'deny_weather'", + ), + ( + {"id": "deny_lookup", "tool_name": r"^mcp__weather__lookup$", "decision": "deny"}, + {"type": "namespace", "name": "mcp__weather", "tools": [{"type": "custom", "name": "lookup"}]}, + "responses", + "Tool 'mcp__weather__lookup' denied by rule 'deny_lookup'", + ), + ( + {"id": "deny_lookup", "tool_name": r"^mcp__weather__lookup$", "decision": "deny"}, + {"functionDeclarations": [{"name": "mcp__weather__lookup"}, {"name": "get_weather"}]}, + "agenerate_content", + "Tool 'mcp__weather__lookup' denied by rule 'deny_lookup'", + ), + ( + {"id": "allow_bash", "tool_name": r"^Bash$", "decision": "allow"}, + {"googleSearch": {}}, + "acompletion", + "Tool 'googleSearch' denied by default action", + ), + ( + {"id": "deny_custom", "tool_type": r"^custom$", "decision": "deny"}, + {"type": "custom", "custom": {"name": "grammar_tool"}}, + "acompletion", + "Tool 'grammar_tool' denied by rule 'deny_custom'", ), ( {"id": "deny_read", "tool_name": r"^Read$", "decision": "deny"}, @@ -1439,7 +1469,16 @@ class TestToolPermissionGuardrailAnthropicMessages: "Tool 'Read' denied by rule 'deny_read'", ), ], - ids=["responses_mcp_by_type", "anthropic_mcp_toolset_by_default", "chat_custom_nested_name"], + ids=[ + "responses_mcp_by_type", + "anthropic_mcp_toolset_by_server_name", + "responses_mcp_by_server_label", + "responses_namespace_custom_member", + "gemini_function_declarations", + "gemini_type_only_tool_by_its_key", + "chat_custom_keeps_its_type", + "chat_custom_nested_name", + ], ) async def test_pre_call_checks_tools_that_carry_no_top_level_name( self, rule: dict[str, str], tool: dict[str, object], call_type: CallTypesLiteral, detection_message: str @@ -1453,14 +1492,77 @@ class TestToolPermissionGuardrailAnthropicMessages: assert excinfo.value.detail["detection_message"] == detection_message @pytest.mark.asyncio - async def test_pre_call_passes_a_tool_no_rule_could_ever_match(self) -> None: - guardrail = self._pre_call(self.rules, "block", default_action="deny") + async def test_pre_call_lets_a_type_rule_allow_a_gemini_tool_by_its_key(self) -> None: + guardrail = self._pre_call( + [{"id": "allow_search", "tool_type": r"^googleSearch$", "decision": "allow"}], "block", default_action="deny" + ) data = {"model": "gemini-3", "messages": [{"role": "user", "content": "hi"}], "tools": [{"googleSearch": {}}]} result = await self._run_pre_call(guardrail, data, "acompletion") assert result["tools"] == [{"googleSearch": {}}] + @pytest.mark.asyncio + async def test_pre_call_blocks_a_denied_tool_loaded_by_responses_tool_search(self) -> None: + guardrail = self._pre_call([{"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}], "block") + loaded = {"type": "tool_search_output", "tools": [{"type": "function", "name": "mcp__weather__lookup"}]} + data = {"model": "gpt-5", "input": [loaded], "tools": []} + + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, "responses") + + assert excinfo.value.detail["detection_message"] == "Tool 'mcp__weather__lookup' denied by rule 'deny_mcp'" + + @pytest.mark.asyncio + async def test_pre_call_rewrite_keeps_the_allowed_members_of_grouped_and_loaded_tools(self) -> None: + guardrail = self._pre_call([{"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}], "rewrite") + get_weather = {"type": "function", "name": "get_weather"} + lookup = {"type": "function", "name": "mcp__weather__lookup"} + data = { + "model": "m", + "input": [{"role": "user", "content": "hi"}, {"type": "tool_search_output", "tools": [get_weather, lookup]}], + "tools": [{"functionDeclarations": [{"name": "get_weather"}, {"name": "mcp__weather__lookup"}]}], + } + + result = await self._run_pre_call(guardrail, data, "responses") + + assert result["tools"] == [{"functionDeclarations": [{"name": "get_weather"}]}] + assert result["input"] == [ + {"role": "user", "content": "hi"}, + {"type": "tool_search_output", "tools": [get_weather]}, + ] + + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("rule", "tools", "tool_choice"), + [ + ( + {"id": "deny_search", "tool_type": r"^web_search$", "decision": "deny"}, + [{"type": "web_search"}, {"type": "function", "name": "get_weather"}], + {"type": "web_search"}, + ), + ( + {"id": "deny_weather", "tool_name": r"^weather$", "decision": "deny"}, + [ + {"type": "mcp", "server_label": "weather", "server_url": "https://a.example.com"}, + {"type": "mcp", "server_label": "files", "server_url": "https://b.example.com"}, + ], + {"type": "mcp", "server_label": "weather"}, + ), + ], + ids=["hosted_tool_type", "hosted_mcp_server"], + ) + async def test_pre_call_rewrite_relaxes_a_hosted_tool_choice_it_removed( + self, rule: dict[str, str], tools: list[dict[str, str]], tool_choice: dict[str, str] + ) -> None: + guardrail = self._pre_call([rule], "rewrite") + data = {"model": "gpt-5", "input": "hi", "tools": tools, "tool_choice": tool_choice} + + result = await self._run_pre_call(guardrail, data, "responses") + + assert result["tools"] == tools[1:] + assert result["tool_choice"] == "none" + @pytest.mark.asyncio @pytest.mark.parametrize( ("tools", "tool_choice", "call_type", "expected_tool_choice"), @@ -1514,6 +1616,12 @@ class TestToolPermissionGuardrailAnthropicMessages: "anthropic_messages", {"type": "any"}, ), + ( + [{"type": "custom", "custom": {"name": "Bash"}}, {"type": "custom", "custom": {"name": "Read"}}], + {"type": "custom", "custom": {"name": "Read"}}, + "acompletion", + "none", + ), ], ids=[ "responses_custom_choice", @@ -1522,6 +1630,7 @@ class TestToolPermissionGuardrailAnthropicMessages: "chat_allowed_tools_all_denied", "anthropic_any_with_no_tools_left", "anthropic_any_with_a_tool_left", + "chat_custom_choice", ], ) async def test_pre_call_rewrite_leaves_no_tool_choice_that_needs_a_removed_tool( @@ -1543,6 +1652,37 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tool_choice"] == expected_tool_choice + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("tool", "tool_choice", "call_type", "allowed_tool_type"), + [ + ({"type": "custom", "name": "apply_patch"}, {"type": "custom", "name": "apply_patch"}, "responses", r"^custom$"), + ( + {"type": "web_search_20250305", "name": "web_search"}, + {"type": "tool", "name": "web_search"}, + "anthropic_messages", + r"^web_search_\d+$", + ), + ], + ids=["responses_custom_tool", "anthropic_server_tool"], + ) + async def test_pre_call_checks_a_forced_choice_with_its_tool_type( + self, + tool: dict[str, str], + tool_choice: dict[str, str], + call_type: CallTypesLiteral, + allowed_tool_type: str, + ) -> None: + guardrail = self._pre_call( + [{"id": "allow_type", "tool_type": allowed_tool_type, "decision": "allow"}], "block", default_action="deny" + ) + data = {"model": "m", "input": "hi", "tools": [tool], "tool_choice": tool_choice} + + result = await self._run_pre_call(guardrail, data, call_type) + + assert result["tools"] == [tool] + assert result["tool_choice"] == tool_choice + @pytest.mark.asyncio async def test_pre_call_rewrite_relaxes_a_choice_for_a_tool_a_type_rule_removed(self) -> None: guardrail = self._pre_call([{"id": "deny_custom", "tool_type": r"^custom$", "decision": "deny"}], "rewrite") From 4b1695392e63a6192856317cd16fff5b67a4d498 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Thu, 29 Oct 2026 00:40:21 -0700 Subject: [PATCH 09/39] fix(guardrails): drop references to removed tools and count loaded tools in tool permission rewrite --- .../guardrail_hooks/tool_permission.py | 71 +++++++++-- .../guardrail_hooks/test_tool_permission.py | 119 ++++++++++++++++++ 2 files changed, 183 insertions(+), 7 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index fe7f8d8dc17..bd775c077b7 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -158,6 +158,62 @@ def _loaded_input_tools(data: object) -> tuple[object, ...]: return tuple(chain.from_iterable(_tool_search_output_tools(item) or () for item in _input_items(data))) +def _reference_name(part: object) -> str | None: + fields: Final = _object_mapping(part) + is_reference: Final = fields is not None and fields.get("type") == "tool_reference" + return _non_empty_string(fields.get("tool_name")) if fields is not None and is_reference else None + + +def _references_one_of(part: object, names: frozenset[str]) -> bool: + name: Final = _reference_name(part) + return name is not None and name in names + + +def _without_references_to(parts: Sequence[object], names: frozenset[str]) -> Sequence[object]: + removed: Final = [name for name in map(_reference_name, parts) if name is not None and name in names] + kept: Final = [part for part in parts if not _references_one_of(part, names)] + if kept or not removed: + return kept + return [{"type": "text", "text": f"Permission denied: tool {', '.join(removed)} is not available"}] + + +def _tool_result_without_references(fields: Mapping[str, object], names: frozenset[str]) -> object: + parts: Final = _object_list(fields.get("content")) + return {**fields, "content": _without_references_to(parts, names)} if parts else fields + + +def _search_result_without_references(fields: Mapping[str, object], names: frozenset[str]) -> object: + result: Final = _object_mapping(fields.get("content")) + references: Final = _object_list(result.get("tool_references")) if result is not None else None + if result is None or references is None: + return fields + kept: Final = [reference for reference in references if not _references_one_of(reference, names)] + return {**fields, "content": {**result, "tool_references": kept}} + + +def _without_references_in_block(block: object, names: frozenset[str]) -> object: + fields: Final = _object_mapping(block) + if fields is None: + return block + match fields.get("type"): + case "tool_result": + return _tool_result_without_references(fields, names) + case "tool_search_tool_result": + return _search_result_without_references(fields, names) + case _: + return block + + +def _without_references_in_message(message: object, names: frozenset[str]) -> object: + fields: Final = _object_mapping(message) + content: Final = _object_list(fields.get("content")) if fields is not None else None + if fields is None or content is None: + return message + if fields.get("role") == "tool": + return {**fields, "content": _without_references_to(content, names)} + return {**fields, "content": [_without_references_in_block(block, names) for block in content]} + + def _allowed_tool_entries(tool_choice: Mapping[str, object]) -> Sequence[object] | None: if tool_choice.get("type") != "allowed_tools": return None @@ -920,25 +976,26 @@ class ToolPermissionGuardrail(CustomGuardrail): if tools is not None and kept_tools is not None else frozenset() ) - tool_choice: Final = _REQUEST_DATA.validate_python(data.get("tool_choice")) - if tool_choice is not None: - data["tool_choice"] = self._rewritten_tool_choice( - tool_choice, removed_names, removed_types, bool(kept_tools) or bool(kept_functions) - ) - input_items: Final = _input_items(data) if any(_tool_search_output_tools(item) is not None for item in input_items): data["input"] = [ self._with_kept_loaded_tools(item, denied_targets, denied_names, call_type) for item in input_items ] + tools_remain: Final = bool(kept_tools) or bool(kept_functions) or bool(_loaded_input_tools(data)) + tool_choice: Final = _REQUEST_DATA.validate_python(data.get("tool_choice")) + if tool_choice is not None: + data["tool_choice"] = self._rewritten_tool_choice(tool_choice, removed_names, removed_types, tools_remain) + named_function_call: Final = self._get_named_function_call(data) if named_function_call in denied_names: data["function_call"] = "none" messages: Final = without_tool_search_items_loading(_REQUEST_DATA.validate_python(data), denied_names) if messages is not None: - data["messages"] = messages # rebind-ok: rewrite mode edits the request in place + data["messages"] = [ # rebind-ok: rewrite mode edits the request in place + _without_references_in_message(message, removed_names) for message in messages + ] return data diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index bf26bbb62a9..da854dc79f1 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -1532,6 +1532,125 @@ class TestToolPermissionGuardrailAnthropicMessages: {"type": "tool_search_output", "tools": [get_weather]}, ] + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("call_type", "message", "rewritten"), + [ + ( + "anthropic_messages", + { + "role": "user", + "content": [ + { + "type": "tool_result", + "tool_use_id": "toolu_1", + "content": [{"type": "tool_reference", "tool_name": "mcp__weather__lookup"}], + }, + {"type": "text", "text": "Tool loaded."}, + ], + }, + { + "role": "user", + "content": [ + { + "type": "tool_result", + "tool_use_id": "toolu_1", + "content": [ + { + "type": "text", + "text": "Permission denied: tool mcp__weather__lookup is not available", + } + ], + }, + {"type": "text", "text": "Tool loaded."}, + ], + }, + ), + ( + "anthropic_messages", + { + "role": "assistant", + "content": [ + { + "type": "tool_search_tool_result", + "tool_use_id": "srvtoolu_1", + "content": { + "type": "tool_search_tool_search_result", + "tool_references": [ + {"type": "tool_reference", "tool_name": "mcp__weather__lookup"}, + {"type": "tool_reference", "tool_name": "get_weather"}, + ], + }, + } + ], + }, + { + "role": "assistant", + "content": [ + { + "type": "tool_search_tool_result", + "tool_use_id": "srvtoolu_1", + "content": { + "type": "tool_search_tool_search_result", + "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}], + }, + } + ], + }, + ), + ( + "acompletion", + { + "role": "tool", + "tool_call_id": "call_1", + "content": [ + {"type": "tool_reference", "tool_name": "mcp__weather__lookup"}, + {"type": "tool_reference", "tool_name": "get_weather"}, + ], + }, + { + "role": "tool", + "tool_call_id": "call_1", + "content": [{"type": "tool_reference", "tool_name": "get_weather"}], + }, + ), + ], + ) + async def test_pre_call_rewrite_drops_references_to_a_removed_tool(self, call_type, message, rewritten) -> None: + guardrail = self._pre_call([{"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}], "rewrite") + data = { + "model": "m", + "messages": [{"role": "user", "content": "weather in Istanbul"}, message], + "tools": [ + {"name": "get_weather", "input_schema": {"type": "object"}, "defer_loading": True}, + {"name": "mcp__weather__lookup", "input_schema": {"type": "object"}, "defer_loading": True}, + ], + } + + result = await self._run_pre_call(guardrail, data, call_type) + + assert [tool["name"] for tool in result["tools"]] == ["get_weather"] + assert result["messages"] == [{"role": "user", "content": "weather in Istanbul"}, rewritten] + + @pytest.mark.asyncio + @pytest.mark.parametrize("tool_choice", ["required", {"type": "function", "name": "get_weather"}]) + async def test_pre_call_rewrite_keeps_tool_choice_when_only_loaded_tools_remain(self, tool_choice) -> None: + guardrail = self._pre_call([{"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}], "rewrite") + get_weather = {"type": "function", "name": "get_weather"} + lookup = {"type": "function", "name": "mcp__weather__lookup"} + data = { + "model": "m", + "input": [{"role": "user", "content": "hi"}, {"type": "tool_search_output", "tools": [get_weather, lookup]}], + "tools": [lookup], + "tool_choice": tool_choice, + } + + result = await self._run_pre_call(guardrail, data, "responses") + + assert result["tools"] == [] + assert result["input"][1] == {"type": "tool_search_output", "tools": [get_weather]} + assert result["tool_choice"] == tool_choice + @pytest.mark.asyncio @pytest.mark.parametrize( ("rule", "tools", "tool_choice"), From 400061779c3c0d448a53a98339fdba9fa1ecaf7f Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Thu, 29 Oct 2026 06:15:15 -0700 Subject: [PATCH 10/39] fix(guardrails): check tools sent outside top-level tools in tool permission --- .../guardrail_hooks/tool_permission.py | 223 ++++++++++++------ .../guardrail_hooks/test_tool_permission.py | 180 ++++++++++++++ 2 files changed, 337 insertions(+), 66 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index bd775c077b7..f9d19a7465d 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -32,6 +32,7 @@ from litellm.proxy.guardrails.anthropic_sse import ( assemble_anthropic_sse_stream, is_raw_sse_stream, ) +from litellm.responses.additional_tools import ADDITIONAL_TOOLS_INPUT_ITEM_TYPE from litellm.types.guardrails import GuardrailEventHooks, LitellmParams from litellm.types.proxy.guardrails.guardrail_hooks.tool_permission import ( PermissionError, @@ -51,7 +52,9 @@ from litellm.types.utils import ( GUARDRAIL_NAME: Final = "tool_permission" _RESPONSES_CALL_TYPES: Final = frozenset({"responses", "aresponses", "_aresponses_websocket"}) _ANTHROPIC_CALL_TYPES: Final = frozenset({"anthropic_messages", "aanthropic_messages"}) -_HOSTED_SERVER_NAME_FIELDS: Final = MappingProxyType({"mcp": "server_label", "mcp_toolset": "mcp_server_name"}) +_MCP_TOOLSET_TYPE: Final = "mcp_toolset" +_HOSTED_SERVER_NAME_FIELDS: Final = MappingProxyType({"mcp": "server_label", _MCP_TOOLSET_TYPE: "mcp_server_name"}) +_TOOL_CARRYING_INPUT_TYPES: Final = frozenset({"tool_search_output", ADDITIONAL_TOOLS_INPUT_ITEM_TYPE}) _DECLARATION_KEYS: Final = ("functionDeclarations", "function_declarations") _NAMED_CHOICE_TYPES: Final = frozenset({"tool", "function", "custom", "allowed_tools", "any", "auto", "none"}) _DECODED_ARGUMENTS: Final = TypeAdapter(object) @@ -136,26 +139,48 @@ def _member_group(tool: object) -> _MemberGroup | None: return _MemberGroup(key, declarations, _declaration_target) if key is not None and declarations else None -def _sole_key(tool: object) -> str | None: +def _keyed_tool_fields(tool: object) -> Mapping[str, object] | None: fields: Final = _object_mapping(tool) - keys: Final = tuple(fields) if fields is not None else () - return keys[0] if len(keys) == 1 and keys[0] not in _DECLARATION_KEYS else None + if fields is None or isinstance(fields.get("type"), str) or _request_tool_names(tool): + return None + return fields -def _tool_search_output_tools(item: object) -> Sequence[object] | None: +def _part_keys(fields: Mapping[str, object]) -> tuple[str, ...]: + return tuple(key for key in fields if key not in _DECLARATION_KEYS) + + +def _input_item_tools(item: object) -> Sequence[object] | None: fields: Final = _object_mapping(item) - return ( - _object_list(fields.get("tools")) if fields is not None and fields.get("type") == "tool_search_output" else None - ) + carries_tools: Final = fields is not None and fields.get("type") in _TOOL_CARRYING_INPUT_TYPES + return _object_list(fields.get("tools")) if fields is not None and carries_tools else None + + +def _request_list(data: object, key: str) -> Sequence[object] | None: + fields: Final = _object_mapping(data) + return _object_list(fields.get(key)) if fields is not None else None def _input_items(data: object) -> Sequence[object]: + return _request_list(data, "input") or () + + +def _tools_in_items(items: Sequence[object]) -> tuple[object, ...]: + return tuple(chain.from_iterable(_input_item_tools(item) or () for item in items)) + + +def _extra_body(data: object) -> Mapping[str, object] | None: fields: Final = _object_mapping(data) - return (_object_list(fields.get("input")) if fields is not None else None) or () + return _object_mapping(fields.get("extra_body")) if fields is not None else None -def _loaded_input_tools(data: object) -> tuple[object, ...]: - return tuple(chain.from_iterable(_tool_search_output_tools(item) or () for item in _input_items(data))) +def _extra_body_tools(data: object) -> Sequence[object] | None: + return _request_list(_extra_body(data), "tools") + + +def _mcp_server_target(server: object) -> _ToolTarget: + fields: Final = _object_mapping(server) + return (_non_empty_string(fields.get("name")) if fields is not None else None, _MCP_TOOLSET_TYPE) def _reference_name(part: object) -> str | None: @@ -234,6 +259,12 @@ def _is_denied_target( return target in denied_targets or target[0] in denied_names +def _kept_members(group: _MemberGroup | None, is_denied: Callable[[_ToolTarget], bool]) -> tuple[object, ...]: + if group is None: + return () + return tuple(member for member in group.members if not is_denied(group.target_of(member) or (None, None))) + + def _none_tool_choice(tool_choice: object) -> object: choice: Final = _object_mapping(tool_choice) return {"type": "none"} if choice is not None and choice.get("type") in ("tool", "any") else "none" @@ -434,7 +465,7 @@ class ToolPermissionGuardrail(CustomGuardrail): name_required: Final = rule.tool_name is not None type_required: Final = rule.tool_type is not None - name_matched: Final = self._matches_regex(name_pattern, tool_name) if name_required else True + name_matched: Final = self._matches_regex(name_pattern, tool_name or tool_type) if name_required else True type_matched: Final = self._matches_regex(type_pattern, tool_type) if type_required else True overall_match: Final = name_matched and type_matched @@ -797,18 +828,23 @@ class ToolPermissionGuardrail(CustomGuardrail): def _get_request_tool_targets(self, tool: object, call_type: CallTypesLiteral) -> tuple[_ToolTarget, ...]: group: Final = _member_group(tool) + member_targets: Final = ( + tuple(target for target in map(group.target_of, group.members) if target is not None) + if group is not None + else () + ) + keyed: Final = _keyed_tool_fields(tool) + if keyed is not None: + return member_targets + tuple((None, key) for key in _part_keys(keyed)) if group is not None: - return tuple(target for target in map(group.target_of, group.members) if target is not None) + return member_targets tool_type: Final = self._get_mapping_value(tool, "type") reads_as_function: Final = tool_type is None or (tool_type == "custom" and call_type in _ANTHROPIC_CALL_TYPES) normalized_type: Final = "function" if reads_as_function else tool_type names: Final = _request_tool_names(tool) if names: return tuple((name, normalized_type) for name in names) - if isinstance(tool_type, str): - return ((None, tool_type),) - sole_key: Final = _sole_key(tool) - return ((None, sole_key),) if sole_key is not None else () + return ((None, tool_type),) if isinstance(tool_type, str) else () def _get_legacy_function_name(self, function: object) -> str | None: return self._get_mapping_value(function, "name") @@ -841,9 +877,13 @@ class ToolPermissionGuardrail(CustomGuardrail): def _collect_request_tools(self, data: dict, call_type: CallTypesLiteral) -> list[_ToolTarget]: request_tools: Final[list[_ToolTarget]] = [] + request: Final = _REQUEST_DATA.validate_python(data) for tool in data.get("tools") or []: request_tools.extend(self._get_request_tool_targets(tool, call_type)) + for extra_body_tool in _extra_body_tools(request) or (): + request_tools.extend(self._get_request_tool_targets(extra_body_tool, call_type)) + request_tools.extend(map(_mcp_server_target, _request_list(request, "mcp_servers") or ())) for function in data.get("functions") or []: function_name = self._get_legacy_function_name(function) @@ -858,10 +898,10 @@ class ToolPermissionGuardrail(CustomGuardrail): if forced_tool_name is not None and forced_tool_name not in listed_names: request_tools.append((forced_tool_name, "function")) - replayed: Final = map(_function_tool_name, replayed_tool_search_tools(_REQUEST_DATA.validate_python(data))) + replayed: Final = map(_function_tool_name, replayed_tool_search_tools(request)) request_tools.extend((name, "function") for name in replayed if name is not None) - for loaded_tool in _loaded_input_tools(data): - request_tools.extend(self._get_request_tool_targets(loaded_tool, call_type)) + for input_tool in _tools_in_items(_input_items(request)): + request_tools.extend(self._get_request_tool_targets(input_tool, call_type)) return request_tools @@ -876,36 +916,55 @@ class ToolPermissionGuardrail(CustomGuardrail): denied_names: frozenset[str], call_type: CallTypesLiteral, ) -> tuple[object, ...]: + is_denied: Final = partial(_is_denied_target, denied_targets=denied_targets, denied_names=denied_names) group: Final = _member_group(tool) + keyed: Final = _keyed_tool_fields(tool) fields: Final = _object_mapping(tool) - if group is None or fields is None: - targets: Final = self._get_request_tool_targets(tool, call_type) - denied: Final = any(_is_denied_target(target, denied_targets, denied_names) for target in targets) - return () if denied else (tool,) - kept_members: Final = [ - member - for member in group.members - if not _is_denied_target(group.target_of(member) or (None, None), denied_targets, denied_names) - ] - if not kept_members: - return () - return (tool,) if len(kept_members) == len(group.members) else ({**fields, group.key: kept_members},) + if fields is None or (group is None and keyed is None): + return () if any(map(is_denied, self._get_request_tool_targets(tool, call_type))) else (tool,) + kept_members: Final = _kept_members(group, is_denied) + denied_keys: Final = ( + frozenset(key for key in _part_keys(keyed) if is_denied((None, key))) + if keyed is not None + else frozenset[str]() + ) + if not denied_keys and len(kept_members) == len(group.members if group is not None else ()): + return (tool,) + emptied_group: Final = frozenset({group.key}) if group is not None and not kept_members else frozenset[str]() + dropped_keys: Final = denied_keys | emptied_group + kept_fields: Final = { + key: list(kept_members) if group is not None and key == group.key else value + for key, value in fields.items() + if key not in dropped_keys + } + parts_left: Final = bool(kept_members) or (keyed is not None and bool(_part_keys(kept_fields))) + return (kept_fields,) if parts_left else () - def _with_kept_loaded_tools( + def _kept_tool_list( + self, + tools: Sequence[object], + denied_targets: frozenset[_ToolTarget], + denied_names: frozenset[str], + call_type: CallTypesLiteral, + ) -> tuple[object, ...]: + return tuple( + chain.from_iterable(self._kept_tools(tool, denied_targets, denied_names, call_type) for tool in tools) + ) + + def _kept_input_items( self, item: object, denied_targets: frozenset[_ToolTarget], denied_names: frozenset[str], call_type: CallTypesLiteral, - ) -> object: + ) -> tuple[object, ...]: fields: Final = _object_mapping(item) - loaded: Final = _tool_search_output_tools(item) - if fields is None or loaded is None: - return item - kept: Final = chain.from_iterable( - self._kept_tools(tool, denied_targets, denied_names, call_type) for tool in loaded - ) - return {**fields, "tools": list(kept)} + tools: Final = _input_item_tools(item) + if fields is None or tools is None: + return (item,) + kept: Final = self._kept_tool_list(tools, denied_targets, denied_names, call_type) + emptied: Final = bool(tools) and not kept and fields.get("type") == ADDITIONAL_TOOLS_INPUT_ITEM_TYPE + return () if emptied else ({**fields, "tools": list(kept)},) def _tool_types_in(self, tools: Sequence[object], call_type: CallTypesLiteral) -> frozenset[str]: targets: Final = chain.from_iterable(self._get_request_tool_targets(tool, call_type) for tool in tools) @@ -946,16 +1005,26 @@ class ToolPermissionGuardrail(CustomGuardrail): verbose_proxy_logger.info("Blocking %s unauthorized tool uses", len(denied_targets)) denied_names: Final = frozenset(name for name, _ in denied_targets if name is not None) - tools: Final = _OPTIONAL_REQUEST_LIST.validate_python(data.get("tools")) - kept_tools: Final = ( - None - if tools is None - else list( - chain.from_iterable(self._kept_tools(tool, denied_targets, denied_names, call_type) for tool in tools) - ) + is_denied: Final = partial(_is_denied_target, denied_targets=denied_targets, denied_names=denied_names) + kept_tool_list: Final = partial( + self._kept_tool_list, denied_targets=denied_targets, denied_names=denied_names, call_type=call_type ) + + request: Final = _REQUEST_DATA.validate_python(data) + + tools: Final = _OPTIONAL_REQUEST_LIST.validate_python(data.get("tools")) + kept_tools: Final = None if tools is None else kept_tool_list(tools) if kept_tools is not None: - data["tools"] = kept_tools + data["tools"] = list(kept_tools) # rebind-ok: rewrite mode edits the request in place + + extra_body: Final = _extra_body(request) + extra_body_tools: Final = _extra_body_tools(request) + kept_extra_body_tools: Final = None if extra_body_tools is None else kept_tool_list(extra_body_tools) + if extra_body is not None and kept_extra_body_tools is not None: + data["extra_body"] = { # rebind-ok: rewrite mode edits the request in place + **extra_body, + "tools": list(kept_extra_body_tools), + } functions: Final = _OPTIONAL_REQUEST_LIST.validate_python(data.get("functions")) kept_functions: Final = ( @@ -964,32 +1033,54 @@ class ToolPermissionGuardrail(CustomGuardrail): else [function for function in functions if self._get_legacy_function_name(function) not in denied_names] ) if kept_functions is not None: - data["functions"] = kept_functions + data["functions"] = kept_functions # rebind-ok: rewrite mode edits the request in place + mcp_servers: Final = _request_list(request, "mcp_servers") + kept_mcp_servers: Final = ( + None + if mcp_servers is None + else tuple(server for server in mcp_servers if not is_denied(_mcp_server_target(server))) + ) + if kept_mcp_servers is not None: + data["mcp_servers"] = list(kept_mcp_servers) # rebind-ok: rewrite mode edits the request in place + + input_items: Final = _input_items(request) + rewrites_input: Final = any(_input_item_tools(item) is not None for item in input_items) + kept_input_items: Final = ( + tuple( + chain.from_iterable( + self._kept_input_items(item, denied_targets, denied_names, call_type) for item in input_items + ) + ) + if rewrites_input + else input_items + ) + if rewrites_input: + data["input"] = list(kept_input_items) # rebind-ok: rewrite mode edits the request in place + + sent_tools: Final = (*(tools or ()), *(extra_body_tools or ()), *_tools_in_items(input_items)) + kept_sent_tools: Final = ( + *(kept_tools or ()), + *(kept_extra_body_tools or ()), + *_tools_in_items(kept_input_items), + ) removed_names: Final = denied_names | ( - self._tool_names_in(tools, call_type) - self._tool_names_in(kept_tools, call_type) - if tools is not None and kept_tools is not None - else frozenset() + self._tool_names_in(sent_tools, call_type) - self._tool_names_in(kept_sent_tools, call_type) ) - removed_types: Final = ( - self._tool_types_in(tools, call_type) - self._tool_types_in(kept_tools, call_type) - if tools is not None and kept_tools is not None - else frozenset() - ) - input_items: Final = _input_items(data) - if any(_tool_search_output_tools(item) is not None for item in input_items): - data["input"] = [ - self._with_kept_loaded_tools(item, denied_targets, denied_names, call_type) for item in input_items - ] + kept_types: Final = self._tool_types_in(kept_sent_tools, call_type) + removed_types: Final = self._tool_types_in(sent_tools, call_type) - kept_types - tools_remain: Final = bool(kept_tools) or bool(kept_functions) or bool(_loaded_input_tools(data)) + tools_remain: Final = bool(kept_sent_tools) or bool(kept_functions) or bool(kept_mcp_servers) tool_choice: Final = _REQUEST_DATA.validate_python(data.get("tool_choice")) if tool_choice is not None: - data["tool_choice"] = self._rewritten_tool_choice(tool_choice, removed_names, removed_types, tools_remain) + rewritten_choice: Final = self._rewritten_tool_choice( + tool_choice, removed_names, removed_types, tools_remain + ) + data["tool_choice"] = rewritten_choice # rebind-ok: rewrite mode edits the request in place named_function_call: Final = self._get_named_function_call(data) if named_function_call in denied_names: - data["function_call"] = "none" + data["function_call"] = "none" # rebind-ok: rewrite mode edits the request in place messages: Final = without_tool_search_items_loading(_REQUEST_DATA.validate_python(data), denied_names) if messages is not None: diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index da854dc79f1..24d291ebc23 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2,6 +2,7 @@ Unit tests for Tool Permission Guardrail (OpenAI tool_calls semantics) """ +import copy import json import logging import re @@ -1817,6 +1818,185 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tools"] == [{"type": "function", "name": "Bash"}] assert result["tool_choice"] == "none" + async def _blocked_and_rewritten( + self, rules: list[dict[str, str]], request: dict[str, object], call_type: CallTypesLiteral + ) -> tuple[str, dict[str, object]]: + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(self._pre_call(rules, "block"), copy.deepcopy(request), call_type) + rewritten = await self._run_pre_call(self._pre_call(rules, "rewrite"), request, call_type) + return excinfo.value.detail["detection_message"], rewritten + + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("denied_tool", "detection_message"), + [ + ( + {"type": "function", "name": "mcp__weather__lookup"}, + "Tool 'mcp__weather__lookup' denied by rule 'deny_mcp'", + ), + ( + {"type": "namespace", "name": "mcp__weather", "tools": [{"type": "function", "name": "lookup"}]}, + "Tool 'mcp__weather__lookup' denied by rule 'deny_mcp'", + ), + ({"type": "web_search"}, "Tool 'web_search' denied by rule 'deny_search'"), + ], + ids=["flat", "namespace_member", "hosted_type"], + ) + async def test_pre_call_checks_and_strips_tools_in_responses_additional_tools_items( + self, denied_tool: dict[str, object], detection_message: str + ) -> None: + rules = [ + {"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}, + {"id": "deny_search", "tool_type": r"^web_search$", "decision": "deny"}, + ] + get_weather = {"type": "function", "name": "get_weather"} + request = { + "model": "gpt-5", + "input": [ + {"role": "user", "content": "hi"}, + {"type": "additional_tools", "tools": [get_weather, denied_tool]}, + {"type": "additional_tools", "tools": [denied_tool]}, + ], + "tools": [], + "tool_choice": "required", + } + + message, rewritten = await self._blocked_and_rewritten(rules, request, "responses") + + assert message == detection_message + assert rewritten["input"] == [ + {"role": "user", "content": "hi"}, + {"type": "additional_tools", "tools": [get_weather]}, + ] + assert rewritten["tool_choice"] == "required" + + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("call_type", "bash", "read"), + [ + ( + "acompletion", + {"type": "function", "function": {"name": "Bash"}}, + {"type": "function", "function": {"name": "Read"}}, + ), + ("responses", {"type": "function", "name": "Bash"}, {"type": "function", "name": "Read"}), + ( + "anthropic_messages", + {"name": "Bash", "input_schema": {"type": "object"}}, + {"name": "Read", "input_schema": {"type": "object"}}, + ), + ], + ids=["chat", "responses", "anthropic"], + ) + async def test_pre_call_checks_and_strips_tools_in_extra_body( + self, call_type: CallTypesLiteral, bash: dict[str, object], read: dict[str, object] + ) -> None: + request = { + "model": "m", + "messages": [{"role": "user", "content": "hi"}], + "input": "hi", + "extra_body": {"tools": [bash, read], "seed": 7}, + } + + message, rewritten = await self._blocked_and_rewritten(self.rules, request, call_type) + + assert message == "Tool 'Read' denied by rule 'deny_read'" + assert rewritten["extra_body"] == {"tools": [bash], "seed": 7} + + @pytest.mark.asyncio + @pytest.mark.parametrize( + "rule", + [ + {"id": "deny_deepwiki", "tool_name": r"^deepwiki$", "decision": "deny"}, + {"id": "deny_deepwiki", "tool_name": r"^deepwiki$", "tool_type": r"^mcp_toolset$", "decision": "deny"}, + ], + ids=["by_server_name", "by_server_name_and_mcp_toolset_type"], + ) + async def test_pre_call_checks_and_strips_anthropic_mcp_servers_like_an_mcp_toolset( + self, rule: dict[str, str] + ) -> None: + deepwiki = {"type": "url", "url": "https://mcp.deepwiki.com/mcp", "name": "deepwiki"} + files = {"type": "url", "url": "https://files.example.com/mcp", "name": "files"} + request = { + "model": "claude-sonnet-4-5", + "messages": [{"role": "user", "content": "hi"}], + "mcp_servers": [deepwiki, files], + "tool_choice": {"type": "any"}, + } + + message, rewritten = await self._blocked_and_rewritten([rule], request, "anthropic_messages") + + assert message == "Tool 'deepwiki' denied by rule 'deny_deepwiki'" + assert rewritten["mcp_servers"] == [files] + assert rewritten["tool_choice"] == {"type": "any"} + + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("rule", "tool", "detection_message", "kept_tools"), + [ + ( + {"id": "deny_code", "tool_type": r"^codeExecution$", "decision": "deny"}, + {"googleSearch": {}, "codeExecution": {}}, + "Tool 'codeExecution' denied by rule 'deny_code'", + [{"googleSearch": {}}], + ), + ( + {"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}, + {"functionDeclarations": [{"name": "mcp__weather__lookup"}], "googleSearch": {}}, + "Tool 'mcp__weather__lookup' denied by rule 'deny_mcp'", + [{"googleSearch": {}}], + ), + ( + {"id": "deny_search", "tool_type": r"^googleSearch$", "decision": "deny"}, + {"functionDeclarations": [{"name": "get_weather"}], "googleSearch": {}}, + "Tool 'googleSearch' denied by rule 'deny_search'", + [{"functionDeclarations": [{"name": "get_weather"}]}], + ), + ( + {"id": "deny_builtin", "tool_type": r"^(googleSearch|codeExecution)$", "decision": "deny"}, + {"googleSearch": {}, "codeExecution": {}}, + "Tool 'googleSearch' denied by rule 'deny_builtin'", + [], + ), + ], + ids=["denied_key_beside_a_key", "every_declaration_denied", "denied_key_beside_declarations", "all_denied"], + ) + async def test_pre_call_checks_and_strips_each_part_of_a_multi_key_gemini_tool( + self, + rule: dict[str, str], + tool: dict[str, object], + detection_message: str, + kept_tools: list[dict[str, object]], + ) -> None: + request = {"model": "gemini-3", "contents": [{"role": "user", "parts": [{"text": "hi"}]}], "tools": [tool]} + + message, rewritten = await self._blocked_and_rewritten([rule], request, "agenerate_content") + + assert message == detection_message + assert rewritten["tools"] == kept_tools + + @pytest.mark.asyncio + @pytest.mark.parametrize("on_disallowed_action", ["block", "rewrite"]) + @pytest.mark.parametrize( + ("tool", "call_type"), + [({"type": "web_search"}, "responses"), ({"googleSearch": {}}, "acompletion")], + ids=["responses_hosted_type", "gemini_tool_key"], + ) + async def test_pre_call_matches_a_name_rule_against_a_nameless_tool_by_its_type( + self, + tool: dict[str, object], + call_type: CallTypesLiteral, + on_disallowed_action: Literal["block", "rewrite"], + ) -> None: + guardrail = self._pre_call( + [{"id": "allow_all", "tool_name": r".*", "decision": "allow"}], on_disallowed_action, default_action="deny" + ) + data = {"model": "m", "messages": [{"role": "user", "content": "hi"}], "input": "hi", "tools": [tool]} + + result = await self._run_pre_call(guardrail, data, call_type) + + assert result["tools"] == [tool] + @pytest.mark.asyncio async def test_denied_anthropic_tool_use_is_blocked(self): response = self._response({"type": "text", "text": "reading"}, self._tool_use("Read")) From 96de70f9a9e2eead4f668f6437d9655135ac7374 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Thu, 29 Oct 2026 09:24:47 -0700 Subject: [PATCH 11/39] fix(guardrails): judge namespace members by their bare name as a fallback and keep rewrites valid for Gemini, Bedrock and hosted tools A namespace member is checked by namespace__name first, and by its bare name when no rule names the joined one. Rewrite mode now prunes Gemini allowedFunctionNames and turns off forced calling when no function is left, drops a removed hosted tool from allowed_tools, reads Bedrock toolSpec and systemTool blocks by name, skips cachePoint markers, and leaves a tools field that is not a list for the provider to reject instead of failing with a 500 --- .../guardrail_hooks/tool_permission.py | 131 ++++++++++++-- .../guardrail_hooks/test_tool_permission.py | 165 ++++++++++++++++++ 2 files changed, 280 insertions(+), 16 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index f9d19a7465d..f12b1163ae9 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -50,16 +50,19 @@ from litellm.types.utils import ( ) GUARDRAIL_NAME: Final = "tool_permission" -_RESPONSES_CALL_TYPES: Final = frozenset({"responses", "aresponses", "_aresponses_websocket"}) _ANTHROPIC_CALL_TYPES: Final = frozenset({"anthropic_messages", "aanthropic_messages"}) _MCP_TOOLSET_TYPE: Final = "mcp_toolset" _HOSTED_SERVER_NAME_FIELDS: Final = MappingProxyType({"mcp": "server_label", _MCP_TOOLSET_TYPE: "mcp_server_name"}) _TOOL_CARRYING_INPUT_TYPES: Final = frozenset({"tool_search_output", ADDITIONAL_TOOLS_INPUT_ITEM_TYPE}) _DECLARATION_KEYS: Final = ("functionDeclarations", "function_declarations") +_NON_TOOL_PART_KEYS: Final = frozenset({*_DECLARATION_KEYS, "cachePoint"}) +_TOOL_CONFIG_KEYS: Final = ("toolConfig", "tool_config") +_FUNCTION_CALLING_CONFIG_KEYS: Final = ("functionCallingConfig", "function_calling_config") +_ALLOWED_FUNCTION_NAMES_KEYS: Final = ("allowedFunctionNames", "allowed_function_names") +_FORCED_FUNCTION_CALLING_MODES: Final = frozenset({"ANY", "VALIDATED"}) _NAMED_CHOICE_TYPES: Final = frozenset({"tool", "function", "custom", "allowed_tools", "any", "auto", "none"}) _DECODED_ARGUMENTS: Final = TypeAdapter(object) _REQUEST_DATA: Final = TypeAdapter(object) -_OPTIONAL_REQUEST_LIST: Final[TypeAdapter[list[object] | None]] = TypeAdapter(list[object] | None) _ToolTarget: TypeAlias = tuple[str | None, str | None] @@ -104,14 +107,33 @@ def _namespace_members(tool: object) -> Sequence[object]: return members or () +def _qualified_member_name(namespace: str, name: str) -> str: + return f"{namespace}__{name}" + + def _namespace_member_target(namespace: str | None, member: object) -> _ToolTarget | None: fields: Final = _object_mapping(member) if fields is None: return None member_type: Final = _non_empty_string(fields.get("type")) name: Final = _non_empty_string(fields.get("name")) - qualified: Final = name is not None and namespace is not None - return (f"{namespace}__{name}" if qualified else name, member_type) + if name is None or namespace is None: + return (name, member_type) + return (_qualified_member_name(namespace, name), member_type) + + +def _member_name(member: object) -> str | None: + fields: Final = _object_mapping(member) + return _non_empty_string(fields.get("name")) if fields is not None else None + + +def _bare_member_names(tool: object) -> tuple[tuple[str, str], ...]: + fields: Final = _object_mapping(tool) + namespace: Final = _non_empty_string(fields.get("name")) if fields is not None else None + if namespace is None: + return () + names: Final = (name for name in map(_member_name, _namespace_members(tool)) if name is not None) + return tuple((_qualified_member_name(namespace, name), name) for name in names) def _declaration_target(declaration: object) -> _ToolTarget | None: @@ -147,7 +169,11 @@ def _keyed_tool_fields(tool: object) -> Mapping[str, object] | None: def _part_keys(fields: Mapping[str, object]) -> tuple[str, ...]: - return tuple(key for key in fields if key not in _DECLARATION_KEYS) + return tuple(key for key in fields if key not in _NON_TOOL_PART_KEYS) + + +def _part_target(fields: Mapping[str, object], key: str) -> _ToolTarget: + return (_member_name(fields.get(key)), key) def _input_item_tools(item: object) -> Sequence[object] | None: @@ -178,6 +204,14 @@ def _extra_body_tools(data: object) -> Sequence[object] | None: return _request_list(_extra_body(data), "tools") +def _sent_tools(data: object) -> tuple[object, ...]: + return ( + *(_request_list(data, "tools") or ()), + *(_extra_body_tools(data) or ()), + *_tools_in_items(_input_items(data)), + ) + + def _mcp_server_target(server: object) -> _ToolTarget: fields: Final = _object_mapping(server) return (_non_empty_string(fields.get("name")) if fields is not None else None, _MCP_TOOLSET_TYPE) @@ -246,6 +280,15 @@ def _allowed_tool_entries(tool_choice: Mapping[str, object]) -> Sequence[object] return _object_list((nested if nested is not None else tool_choice).get("tools")) +def _is_removed_entry(entry: object, removed_names: frozenset[str], removed_types: frozenset[str]) -> bool: + names: Final = _request_tool_names(entry) + if names: + return any(name in removed_names for name in names) + fields: Final = _object_mapping(entry) + entry_type: Final = _non_empty_string(fields.get("type")) if fields is not None else None + return entry_type is not None and entry_type in removed_types + + def _with_allowed_tool_entries(tool_choice: Mapping[str, object], entries: list[object]) -> dict[str, object]: nested: Final = _object_mapping(tool_choice.get("allowed_tools")) if nested is None: @@ -275,6 +318,40 @@ def _requires_a_tool(tool_choice: object) -> bool: return tool_choice == "required" or (choice is not None and choice.get("type") == "any") +def _kept_allowed_function_names(config: Mapping[str, object], removed_names: frozenset[str]) -> Mapping[str, object]: + listed: Final = tuple((key, _object_list(config.get(key))) for key in _ALLOWED_FUNCTION_NAMES_KEYS) + return {key: [name for name in names if name not in removed_names] for key, names in listed if names is not None} + + +def _rewritten_function_calling_config( + config: Mapping[str, object], removed_names: frozenset[str], functions_remain: bool +) -> Mapping[str, object]: + kept_names: Final = _kept_allowed_function_names(config, removed_names) + every_listed_name_removed: Final = bool(kept_names) and not any(kept_names.values()) + forces_a_function: Final = str(config.get("mode", "")).upper() in _FORCED_FUNCTION_CALLING_MODES + if not every_listed_name_removed and (functions_remain or not forces_a_function): + return {**config, **kept_names} + return {**{key: value for key, value in config.items() if key not in _ALLOWED_FUNCTION_NAMES_KEYS}, "mode": "NONE"} + + +def _rewritten_tool_config_field( + key: str, value: object, removed_names: frozenset[str], functions_remain: bool +) -> object: + config: Final = _object_mapping(value) + if key not in _FUNCTION_CALLING_CONFIG_KEYS or config is None: + return value + return _rewritten_function_calling_config(config, removed_names, functions_remain) + + +def _rewritten_tool_config(tool_config: object, removed_names: frozenset[str], functions_remain: bool) -> object: + fields: Final = _object_mapping(tool_config) + if fields is None: + return tool_config + return { + key: _rewritten_tool_config_field(key, value, removed_names, functions_remain) for key, value in fields.items() + } + + class _ToolPermissionRuleFields(TypedDict, total=False): """The config-file shape a :class:`ToolPermissionRule` is built from.""" @@ -527,6 +604,21 @@ class ToolPermissionGuardrail(CustomGuardrail): verbose_proxy_logger.debug(message) return is_allowed, None, message + def _has_matching_rule(self, tool_name: str | None, tool_type: str | None) -> bool: + return any(self._rule_matches_tool(rule, tool_name=tool_name, tool_type=tool_type)[0] for rule in self.rules) + + def _check_target_permission( + self, target: _ToolTarget, bare_names: Mapping[str, str] + ) -> tuple[bool, str | None, str | None]: + name, tool_type = target + bare_name: Final = bare_names.get(name) if name is not None else None + falls_back: Final = ( + bare_name is not None + and not self._has_matching_rule(name, tool_type) + and self._has_matching_rule(bare_name, tool_type) + ) + return self._check_tool_permission(bare_name if falls_back else name, tool_type) + def _parse_tool_call_arguments( self, tool_call: ChatCompletionMessageToolCall ) -> tuple[Mapping[str, object] | None, str | None]: @@ -835,7 +927,7 @@ class ToolPermissionGuardrail(CustomGuardrail): ) keyed: Final = _keyed_tool_fields(tool) if keyed is not None: - return member_targets + tuple((None, key) for key in _part_keys(keyed)) + return member_targets + tuple(_part_target(keyed, key) for key in _part_keys(keyed)) if group is not None: return member_targets tool_type: Final = self._get_mapping_value(tool, "type") @@ -879,13 +971,13 @@ class ToolPermissionGuardrail(CustomGuardrail): request_tools: Final[list[_ToolTarget]] = [] request: Final = _REQUEST_DATA.validate_python(data) - for tool in data.get("tools") or []: + for tool in _request_list(request, "tools") or (): request_tools.extend(self._get_request_tool_targets(tool, call_type)) for extra_body_tool in _extra_body_tools(request) or (): request_tools.extend(self._get_request_tool_targets(extra_body_tool, call_type)) request_tools.extend(map(_mcp_server_target, _request_list(request, "mcp_servers") or ())) - for function in data.get("functions") or []: + for function in _request_list(request, "functions") or (): function_name = self._get_legacy_function_name(function) if function_name is not None: request_tools.append((function_name, "function")) @@ -924,7 +1016,7 @@ class ToolPermissionGuardrail(CustomGuardrail): return () if any(map(is_denied, self._get_request_tool_targets(tool, call_type))) else (tool,) kept_members: Final = _kept_members(group, is_denied) denied_keys: Final = ( - frozenset(key for key in _part_keys(keyed) if is_denied((None, key))) + frozenset(key for key in _part_keys(keyed) if is_denied(_part_target(keyed, key))) if keyed is not None else frozenset[str]() ) @@ -982,9 +1074,7 @@ class ToolPermissionGuardrail(CustomGuardrail): return _none_tool_choice(tool_choice) allowed: Final = _allowed_tool_entries(choice) if choice is not None else None if choice is not None and allowed is not None: - kept: Final = [ - entry for entry in allowed if not any(name in removed_names for name in _request_tool_names(entry)) - ] + kept: Final = [entry for entry in allowed if not _is_removed_entry(entry, removed_names, removed_types)] return _with_allowed_tool_entries(choice, kept) if kept and tools_remain else _none_tool_choice(choice) if not tools_remain and (named is not None or _requires_a_tool(tool_choice)): return _none_tool_choice(tool_choice) @@ -1011,8 +1101,9 @@ class ToolPermissionGuardrail(CustomGuardrail): ) request: Final = _REQUEST_DATA.validate_python(data) + sent_tools: Final = _sent_tools(request) - tools: Final = _OPTIONAL_REQUEST_LIST.validate_python(data.get("tools")) + tools: Final = _request_list(request, "tools") kept_tools: Final = None if tools is None else kept_tool_list(tools) if kept_tools is not None: data["tools"] = list(kept_tools) # rebind-ok: rewrite mode edits the request in place @@ -1026,7 +1117,7 @@ class ToolPermissionGuardrail(CustomGuardrail): "tools": list(kept_extra_body_tools), } - functions: Final = _OPTIONAL_REQUEST_LIST.validate_python(data.get("functions")) + functions: Final = _request_list(request, "functions") kept_functions: Final = ( None if functions is None @@ -1058,7 +1149,6 @@ class ToolPermissionGuardrail(CustomGuardrail): if rewrites_input: data["input"] = list(kept_input_items) # rebind-ok: rewrite mode edits the request in place - sent_tools: Final = (*(tools or ()), *(extra_body_tools or ()), *_tools_in_items(input_items)) kept_sent_tools: Final = ( *(kept_tools or ()), *(kept_extra_body_tools or ()), @@ -1082,6 +1172,12 @@ class ToolPermissionGuardrail(CustomGuardrail): if named_function_call in denied_names: data["function_call"] = "none" # rebind-ok: rewrite mode edits the request in place + functions_remain: Final = "function" in kept_types + for config_key in (key for key in _TOOL_CONFIG_KEYS if key in data): + data[config_key] = _rewritten_tool_config( # rebind-ok: rewrite mode edits the request in place + data[config_key], removed_names, functions_remain + ) + messages: Final = without_tool_search_items_loading(_REQUEST_DATA.validate_python(data), denied_names) if messages is not None: data["messages"] = [ # rebind-ok: rewrite mode edits the request in place @@ -1199,7 +1295,10 @@ class ToolPermissionGuardrail(CustomGuardrail): ) return data - decisions: Final = tuple((target, self._check_tool_permission(*target)) for target in new_tools) + bare_names: Final = MappingProxyType( + dict(chain.from_iterable(map(_bare_member_names, _sent_tools(_REQUEST_DATA.validate_python(data))))) + ) + decisions: Final = tuple((target, self._check_target_permission(target, bare_names)) for target in new_tools) denied: Final = tuple( (target, message) for target, (is_allowed, _, message) in decisions diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 24d291ebc23..3fcda956401 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -1997,6 +1997,171 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tools"] == [tool] + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("rules", "default_action", "detection_message"), + [ + ( + [{"id": "deny_exec", "tool_name": r"^exec$", "decision": "deny"}], + "allow", + "Tool 'exec' denied by rule 'deny_exec'", + ), + ([{"id": "allow_exec", "tool_name": r"^exec$", "decision": "allow"}], "deny", None), + ( + [ + {"id": "allow_exec", "tool_name": r"^exec$", "decision": "allow"}, + {"id": "deny_functions", "tool_name": r"^functions__.*$", "decision": "deny"}, + ], + "allow", + "Tool 'functions__exec' denied by rule 'deny_functions'", + ), + ], + ids=["bare_name_deny_rule", "bare_name_allow_rule", "qualified_rule_wins_over_an_earlier_bare_rule"], + ) + async def test_pre_call_judges_a_namespace_member_by_its_bare_name_when_no_rule_names_it_qualified( + self, rules: list[dict[str, str]], default_action: Literal["allow", "deny"], detection_message: str | None + ) -> None: + guardrail = self._pre_call(rules, "block", default_action=default_action) + namespace = {"type": "namespace", "name": "functions", "tools": [{"type": "function", "name": "exec"}]} + data = {"model": "gpt-5", "input": "run date", "tools": [namespace]} + + if detection_message is None: + assert (await self._run_pre_call(guardrail, data, "responses"))["tools"] == [namespace] + return + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, "responses") + assert excinfo.value.detail["detection_message"] == detection_message + + @pytest.mark.asyncio + async def test_pre_call_rewrite_drops_a_namespace_member_a_bare_name_rule_denies(self) -> None: + guardrail = self._pre_call([{"id": "deny_exec", "tool_name": r"^exec$", "decision": "deny"}], "rewrite") + members = [{"type": "function", "name": "exec"}, {"type": "function", "name": "read_file"}] + namespace = {"type": "namespace", "name": "functions", "tools": members} + data = {"model": "gpt-5", "input": "run date", "tools": [namespace]} + + result = await self._run_pre_call(guardrail, data, "responses") + + assert result["tools"] == [{"type": "namespace", "name": "functions", "tools": members[1:]}] + + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("tool_config", "rewritten_tool_config"), + [ + ( + { + "functionCallingConfig": { + "mode": "ANY", + "allowedFunctionNames": ["mcp__weather__lookup", "get_weather"], + } + }, + {"functionCallingConfig": {"mode": "ANY", "allowedFunctionNames": ["get_weather"]}}, + ), + ( + {"functionCallingConfig": {"mode": "ANY", "allowedFunctionNames": ["mcp__weather__lookup"]}}, + {"functionCallingConfig": {"mode": "NONE"}}, + ), + ( + {"function_calling_config": {"mode": "any", "allowed_function_names": ["mcp__weather__lookup"]}}, + {"function_calling_config": {"mode": "NONE"}}, + ), + ({"functionCallingConfig": {"mode": "ANY"}}, {"functionCallingConfig": {"mode": "ANY"}}), + ], + ids=["some_allowed_names_left", "every_allowed_name_removed", "snake_case_fields", "no_allowed_names"], + ) + async def test_pre_call_rewrite_drops_removed_functions_from_a_gemini_tool_config( + self, tool_config: dict[str, object], rewritten_tool_config: dict[str, object] + ) -> None: + guardrail = self._pre_call([{"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}], "rewrite") + config_key = "tool_config" if "function_calling_config" in tool_config else "toolConfig" + data = { + "model": "gemini-3", + "contents": [{"role": "user", "parts": [{"text": "weather in Paris?"}]}], + "tools": [{"functionDeclarations": [{"name": "mcp__weather__lookup"}, {"name": "get_weather"}]}], + config_key: tool_config, + } + + result = await self._run_pre_call(guardrail, data, "agenerate_content") + + assert result["tools"] == [{"functionDeclarations": [{"name": "get_weather"}]}] + assert result[config_key] == rewritten_tool_config + + @pytest.mark.asyncio + async def test_pre_call_rewrite_turns_off_forced_gemini_calling_when_no_function_is_left(self) -> None: + guardrail = self._pre_call([{"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}], "rewrite") + data = { + "model": "gemini-3", + "contents": [{"role": "user", "parts": [{"text": "weather in Paris?"}]}], + "tools": [{"functionDeclarations": [{"name": "mcp__weather__lookup"}]}, {"googleSearch": {}}], + "toolConfig": {"functionCallingConfig": {"mode": "ANY"}}, + } + + result = await self._run_pre_call(guardrail, data, "agenerate_content") + + assert result["tools"] == [{"googleSearch": {}}] + assert result["toolConfig"] == {"functionCallingConfig": {"mode": "NONE"}} + + @pytest.mark.asyncio + async def test_pre_call_rewrite_drops_a_removed_hosted_tool_from_allowed_tools(self) -> None: + guardrail = self._pre_call([{"id": "deny_search", "tool_type": r"^web_search$", "decision": "deny"}], "rewrite") + weather = {"type": "function", "name": "get_weather"} + tool_choice = {"type": "allowed_tools", "mode": "required", "tools": [weather, {"type": "web_search"}]} + data = {"model": "gpt-5", "input": "hi", "tools": [weather, {"type": "web_search"}], "tool_choice": tool_choice} + + result = await self._run_pre_call(guardrail, data, "responses") + + assert result["tools"] == [weather] + assert result["tool_choice"] == {"type": "allowed_tools", "mode": "required", "tools": [weather]} + + @pytest.mark.asyncio + @pytest.mark.parametrize("tools", [{"not": "a list"}, '[{"type": "function"}]'], ids=["object", "json_string"]) + async def test_pre_call_rewrite_leaves_a_tools_field_that_is_not_a_list_for_the_provider_to_reject( + self, tools: object + ) -> None: + guardrail = self._pre_call([{"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}], "rewrite") + data = { + "model": "gpt-5", + "messages": [{"role": "user", "content": "hi"}], + "tools": tools, + "tool_choice": {"type": "function", "function": {"name": "mcp__weather__lookup"}}, + } + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == tools + assert result["tool_choice"] == "none" + + @pytest.mark.asyncio + @pytest.mark.parametrize("on_disallowed_action", ["block", "rewrite"]) + async def test_pre_call_reads_bedrock_tool_blocks_by_name_and_skips_cache_points( + self, on_disallowed_action: Literal["block", "rewrite"] + ) -> None: + guardrail = self._pre_call( + [{"id": "allow_weather", "tool_name": r"^get_weather$", "decision": "allow"}], + on_disallowed_action, + default_action="deny", + ) + weather = {"toolSpec": {"name": "get_weather", "inputSchema": {"json": {}}}} + tools = [weather, {"cachePoint": {"type": "default"}}] + data = {"model": "bedrock/claude", "messages": [{"role": "user", "content": "hi"}], "tools": tools} + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == tools + + @pytest.mark.asyncio + async def test_pre_call_rewrite_drops_a_denied_bedrock_tool_block_by_its_name(self) -> None: + guardrail = self._pre_call([{"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}], "rewrite") + kept = [{"toolSpec": {"name": "get_weather"}}, {"cachePoint": {"type": "default"}}] + data = { + "model": "bedrock/claude", + "messages": [{"role": "user", "content": "hi"}], + "tools": [{"toolSpec": {"name": "mcp__weather__lookup"}}, *kept], + } + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == kept + @pytest.mark.asyncio async def test_denied_anthropic_tool_use_is_blocked(self): response = self._response({"type": "text", "text": "reading"}, self._tool_use("Read")) From 20b76a339c069693c713acad55f8460a0734b84f Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Thu, 29 Oct 2026 20:39:43 -0700 Subject: [PATCH 12/39] fix(guardrails): let only name rules decide a namespace member's bare-name fallback --- .../guardrails/guardrail_hooks/tool_permission.py | 11 +++++++---- .../guardrail_hooks/test_tool_permission.py | 15 ++++++++++++++- 2 files changed, 21 insertions(+), 5 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index f12b1163ae9..c5337045172 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -604,8 +604,11 @@ class ToolPermissionGuardrail(CustomGuardrail): verbose_proxy_logger.debug(message) return is_allowed, None, message - def _has_matching_rule(self, tool_name: str | None, tool_type: str | None) -> bool: - return any(self._rule_matches_tool(rule, tool_name=tool_name, tool_type=tool_type)[0] for rule in self.rules) + def _has_matching_name_rule(self, tool_name: str | None, tool_type: str | None) -> bool: + return any( + rule.tool_name is not None and self._rule_matches_tool(rule, tool_name=tool_name, tool_type=tool_type)[0] + for rule in self.rules + ) def _check_target_permission( self, target: _ToolTarget, bare_names: Mapping[str, str] @@ -614,8 +617,8 @@ class ToolPermissionGuardrail(CustomGuardrail): bare_name: Final = bare_names.get(name) if name is not None else None falls_back: Final = ( bare_name is not None - and not self._has_matching_rule(name, tool_type) - and self._has_matching_rule(bare_name, tool_type) + and not self._has_matching_name_rule(name, tool_type) + and self._has_matching_name_rule(bare_name, tool_type) ) return self._check_tool_permission(bare_name if falls_back else name, tool_type) diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 3fcda956401..012561624e0 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2015,8 +2015,21 @@ class TestToolPermissionGuardrailAnthropicMessages: "allow", "Tool 'functions__exec' denied by rule 'deny_functions'", ), + ( + [ + {"id": "deny_exec", "tool_name": r"^exec$", "decision": "deny"}, + {"id": "allow_functions", "tool_type": r"^function$", "decision": "allow"}, + ], + "allow", + "Tool 'exec' denied by rule 'deny_exec'", + ), + ], + ids=[ + "bare_name_deny_rule", + "bare_name_allow_rule", + "qualified_rule_wins_over_an_earlier_bare_rule", + "type_rule_keeps_an_earlier_bare_name_rule_in_charge", ], - ids=["bare_name_deny_rule", "bare_name_allow_rule", "qualified_rule_wins_over_an_earlier_bare_rule"], ) async def test_pre_call_judges_a_namespace_member_by_its_bare_name_when_no_rule_names_it_qualified( self, rules: list[dict[str, str]], default_action: Literal["allow", "deny"], detection_message: str | None From a39a8d02c5a5c4e1d754d68e6836f7069daebac9 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Fri, 30 Oct 2026 04:40:37 -0700 Subject: [PATCH 13/39] fix(guardrails): judge malformed tool types, empty Gemini name lists and pass-through Anthropic tools like the endpoints do A tool or tool_choice whose type is not a string now reads as untyped instead of crashing the guardrail with a 500, and a null type key is never read as a Gemini tool part. An empty allowedFunctionNames list no longer turns off the functions a rewrite kept. An Anthropic custom tool reads as a function by its input_schema on every route, so a pass-through route judges it the same as /v1/messages. A Responses WebSocket frame now forwards the extra_body tools a rewrite stripped --- litellm/proxy/_lazy_openapi_snapshot.json | 2 +- .../guardrail_hooks/tool_permission.py | 67 ++++++-------- .../proxy/response_api_endpoints/endpoints.py | 5 +- .../guardrail_hooks/tool_permission.py | 2 +- .../guardrail_hooks/test_tool_permission.py | 89 +++++++++++++++++-- .../response_api_endpoints/test_endpoints.py | 35 ++++++++ ui/litellm-dashboard/src/lib/http/schema.d.ts | 2 +- 7 files changed, 152 insertions(+), 50 deletions(-) diff --git a/litellm/proxy/_lazy_openapi_snapshot.json b/litellm/proxy/_lazy_openapi_snapshot.json index bc64a4c7ef0..459a4a1d5d6 100644 --- a/litellm/proxy/_lazy_openapi_snapshot.json +++ b/litellm/proxy/_lazy_openapi_snapshot.json @@ -19623,7 +19623,7 @@ "type": "null" } ], - "description": "Regex pattern applied to the tool's function name", + "description": "Regex pattern applied to the tool's name, or to its type when the tool has no name", "title": "Tool Name" }, "tool_type": { diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index b7985c8ed46..4c505bd4feb 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -51,12 +51,11 @@ from litellm.types.utils import ( ) GUARDRAIL_NAME: Final = "tool_permission" -_ANTHROPIC_CALL_TYPES: Final = frozenset({"anthropic_messages", "aanthropic_messages"}) _MCP_TOOLSET_TYPE: Final = "mcp_toolset" _HOSTED_SERVER_NAME_FIELDS: Final = MappingProxyType({"mcp": "server_label", _MCP_TOOLSET_TYPE: "mcp_server_name"}) _TOOL_CARRYING_INPUT_TYPES: Final = frozenset({"tool_search_output", ADDITIONAL_TOOLS_INPUT_ITEM_TYPE}) _DECLARATION_KEYS: Final = ("functionDeclarations", "function_declarations") -_NON_TOOL_PART_KEYS: Final = frozenset({*_DECLARATION_KEYS, "cachePoint"}) +_NON_TOOL_PART_KEYS: Final = frozenset({*_DECLARATION_KEYS, "cachePoint", "type"}) _TOOL_CONFIG_KEYS: Final = ("toolConfig", "tool_config") _FUNCTION_CALLING_CONFIG_KEYS: Final = ("functionCallingConfig", "function_calling_config") _ALLOWED_FUNCTION_NAMES_KEYS: Final = ("allowedFunctionNames", "allowed_function_names") @@ -328,7 +327,8 @@ def _rewritten_function_calling_config( config: Mapping[str, object], removed_names: frozenset[str], functions_remain: bool ) -> Mapping[str, object]: kept_names: Final = _kept_allowed_function_names(config, removed_names) - every_listed_name_removed: Final = bool(kept_names) and not any(kept_names.values()) + had_names: Final = any(_object_list(config.get(key)) for key in _ALLOWED_FUNCTION_NAMES_KEYS) + every_listed_name_removed: Final = had_names and not any(kept_names.values()) forces_a_function: Final = str(config.get("mode", "")).upper() in _FORCED_FUNCTION_CALLING_MODES if not every_listed_name_removed and (functions_remain or not forces_a_function): return {**config, **kept_names} @@ -922,7 +922,7 @@ class ToolPermissionGuardrail(CustomGuardrail): if not any(_is_tool_use_block(block) for block in kept_blocks): response["stop_reason"] = "end_turn" # rebind-ok: dropping every tool_use ends the turn - def _get_request_tool_targets(self, tool: object, call_type: CallTypesLiteral) -> tuple[_ToolTarget, ...]: + def _get_request_tool_targets(self, tool: object) -> tuple[_ToolTarget, ...]: group: Final = _member_group(tool) member_targets: Final = ( tuple(target for target in map(group.target_of, group.members) if target is not None) @@ -934,13 +934,14 @@ class ToolPermissionGuardrail(CustomGuardrail): return member_targets + tuple(_part_target(keyed, key) for key in _part_keys(keyed)) if group is not None: return member_targets - tool_type: Final = self._get_mapping_value(tool, "type") - reads_as_function: Final = tool_type is None or (tool_type == "custom" and call_type in _ANTHROPIC_CALL_TYPES) - normalized_type: Final = "function" if reads_as_function else tool_type + raw_type: Final = self._get_mapping_value(tool, "type") + tool_type: Final = raw_type if isinstance(raw_type, str) else None + anthropic_custom: Final = tool_type == "custom" and self._get_mapping_value(tool, "input_schema") is not None + normalized_type: Final = "function" if tool_type is None or anthropic_custom else tool_type names: Final = _request_tool_names(tool) if names: return tuple((name, normalized_type) for name in names) - return ((None, tool_type),) if isinstance(tool_type, str) else () + return ((None, tool_type),) if tool_type is not None else () def _get_legacy_function_name(self, function: object) -> str | None: return self._get_mapping_value(function, "name") @@ -971,14 +972,14 @@ class ToolPermissionGuardrail(CustomGuardrail): return function_call return self._get_mapping_value(function_call, "name") - def _collect_request_tools(self, data: dict, call_type: CallTypesLiteral) -> list[_ToolTarget]: + def _collect_request_tools(self, data: dict) -> list[_ToolTarget]: request_tools: Final[list[_ToolTarget]] = [] request: Final = _REQUEST_DATA.validate_python(data) for tool in _request_list(request, "tools") or (): - request_tools.extend(self._get_request_tool_targets(tool, call_type)) + request_tools.extend(self._get_request_tool_targets(tool)) for extra_body_tool in _extra_body_tools(request) or (): - request_tools.extend(self._get_request_tool_targets(extra_body_tool, call_type)) + request_tools.extend(self._get_request_tool_targets(extra_body_tool)) request_tools.extend(map(_mcp_server_target, _request_list(request, "mcp_servers") or ())) for function in _request_list(request, "functions") or (): @@ -997,12 +998,12 @@ class ToolPermissionGuardrail(CustomGuardrail): replayed: Final = map(_function_tool_name, replayed_tool_search_tools(request)) request_tools.extend((name, "function") for name in replayed if name is not None) for input_tool in _tools_in_items(_input_items(request)): - request_tools.extend(self._get_request_tool_targets(input_tool, call_type)) + request_tools.extend(self._get_request_tool_targets(input_tool)) return request_tools - def _tool_names_in(self, tools: Sequence[object], call_type: CallTypesLiteral) -> frozenset[str]: - targets: Final = chain.from_iterable(self._get_request_tool_targets(tool, call_type) for tool in tools) + def _tool_names_in(self, tools: Sequence[object]) -> frozenset[str]: + targets: Final = chain.from_iterable(self._get_request_tool_targets(tool) for tool in tools) return frozenset(name for name, _ in targets if name is not None) def _kept_tools( @@ -1010,14 +1011,13 @@ class ToolPermissionGuardrail(CustomGuardrail): tool: object, denied_targets: frozenset[_ToolTarget], denied_names: frozenset[str], - call_type: CallTypesLiteral, ) -> tuple[object, ...]: is_denied: Final = partial(_is_denied_target, denied_targets=denied_targets, denied_names=denied_names) group: Final = _member_group(tool) keyed: Final = _keyed_tool_fields(tool) fields: Final = _object_mapping(tool) if fields is None or (group is None and keyed is None): - return () if any(map(is_denied, self._get_request_tool_targets(tool, call_type))) else (tool,) + return () if any(map(is_denied, self._get_request_tool_targets(tool))) else (tool,) kept_members: Final = _kept_members(group, is_denied) denied_keys: Final = ( frozenset(key for key in _part_keys(keyed) if is_denied(_part_target(keyed, key))) @@ -1041,29 +1041,25 @@ class ToolPermissionGuardrail(CustomGuardrail): tools: Sequence[object], denied_targets: frozenset[_ToolTarget], denied_names: frozenset[str], - call_type: CallTypesLiteral, ) -> tuple[object, ...]: - return tuple( - chain.from_iterable(self._kept_tools(tool, denied_targets, denied_names, call_type) for tool in tools) - ) + return tuple(chain.from_iterable(self._kept_tools(tool, denied_targets, denied_names) for tool in tools)) def _kept_input_items( self, item: object, denied_targets: frozenset[_ToolTarget], denied_names: frozenset[str], - call_type: CallTypesLiteral, ) -> tuple[object, ...]: fields: Final = _object_mapping(item) tools: Final = _input_item_tools(item) if fields is None or tools is None: return (item,) - kept: Final = self._kept_tool_list(tools, denied_targets, denied_names, call_type) + kept: Final = self._kept_tool_list(tools, denied_targets, denied_names) emptied: Final = bool(tools) and not kept and fields.get("type") == ADDITIONAL_TOOLS_INPUT_ITEM_TYPE return () if emptied else ({**fields, "tools": list(kept)},) - def _tool_types_in(self, tools: Sequence[object], call_type: CallTypesLiteral) -> frozenset[str]: - targets: Final = chain.from_iterable(self._get_request_tool_targets(tool, call_type) for tool in tools) + def _tool_types_in(self, tools: Sequence[object]) -> frozenset[str]: + targets: Final = chain.from_iterable(self._get_request_tool_targets(tool) for tool in tools) return frozenset(tool_type for _, tool_type in targets if tool_type is not None) def _rewritten_tool_choice( @@ -1073,7 +1069,7 @@ class ToolPermissionGuardrail(CustomGuardrail): if named is not None and named in removed_names: return _none_tool_choice(tool_choice) choice: Final = _object_mapping(tool_choice) - hosted_type: Final = choice.get("type") if choice is not None else None + hosted_type: Final = _non_empty_string(choice.get("type")) if choice is not None else None if hosted_type not in _NAMED_CHOICE_TYPES and hosted_type in removed_types: return _none_tool_choice(tool_choice) allowed: Final = _allowed_tool_entries(choice) if choice is not None else None @@ -1088,7 +1084,6 @@ class ToolPermissionGuardrail(CustomGuardrail): self, data: dict, denied_targets: frozenset[_ToolTarget], - call_type: CallTypesLiteral, ): """ Remove denied tools from the request, and relax any tool_choice that would still require one @@ -1100,9 +1095,7 @@ class ToolPermissionGuardrail(CustomGuardrail): denied_names: Final = frozenset(name for name, _ in denied_targets if name is not None) is_denied: Final = partial(_is_denied_target, denied_targets=denied_targets, denied_names=denied_names) - kept_tool_list: Final = partial( - self._kept_tool_list, denied_targets=denied_targets, denied_names=denied_names, call_type=call_type - ) + kept_tool_list: Final = partial(self._kept_tool_list, denied_targets=denied_targets, denied_names=denied_names) request: Final = _REQUEST_DATA.validate_python(data) sent_tools: Final = _sent_tools(request) @@ -1143,9 +1136,7 @@ class ToolPermissionGuardrail(CustomGuardrail): rewrites_input: Final = any(_input_item_tools(item) is not None for item in input_items) kept_input_items: Final = ( tuple( - chain.from_iterable( - self._kept_input_items(item, denied_targets, denied_names, call_type) for item in input_items - ) + chain.from_iterable(self._kept_input_items(item, denied_targets, denied_names) for item in input_items) ) if rewrites_input else input_items @@ -1158,11 +1149,9 @@ class ToolPermissionGuardrail(CustomGuardrail): *(kept_extra_body_tools or ()), *_tools_in_items(kept_input_items), ) - removed_names: Final = denied_names | ( - self._tool_names_in(sent_tools, call_type) - self._tool_names_in(kept_sent_tools, call_type) - ) - kept_types: Final = self._tool_types_in(kept_sent_tools, call_type) - removed_types: Final = self._tool_types_in(sent_tools, call_type) - kept_types + removed_names: Final = denied_names | (self._tool_names_in(sent_tools) - self._tool_names_in(kept_sent_tools)) + kept_types: Final = self._tool_types_in(kept_sent_tools) + removed_types: Final = self._tool_types_in(sent_tools) - kept_types tools_remain: Final = bool(kept_sent_tools) or bool(kept_functions) or bool(kept_mcp_servers) tool_choice: Final = _REQUEST_DATA.validate_python(data.get("tool_choice")) @@ -1298,7 +1287,7 @@ class ToolPermissionGuardrail(CustomGuardrail): if self.should_run_guardrail(data=data, event_type=event_type) is not True: return data - new_tools: Final = self._collect_request_tools(data, call_type) + new_tools: Final = self._collect_request_tools(data) if not new_tools: verbose_proxy_logger.debug( "Tool Permission Guardrail: not running guardrail. No tools or functions in data" @@ -1326,7 +1315,7 @@ class ToolPermissionGuardrail(CustomGuardrail): ) if denied: - self._modify_request_with_permission_errors(data, frozenset(target for target, _ in denied), call_type) + self._modify_request_with_permission_errors(data, frozenset(target for target, _ in denied)) verbose_proxy_logger.debug("Tool Permission Guardrail Pre-Call Hook: All tools allowed") diff --git a/litellm/proxy/response_api_endpoints/endpoints.py b/litellm/proxy/response_api_endpoints/endpoints.py index d78eeff26f5..7b1c3c41e9b 100644 --- a/litellm/proxy/response_api_endpoints/endpoints.py +++ b/litellm/proxy/response_api_endpoints/endpoints.py @@ -2154,6 +2154,7 @@ _GUARDRAIL_INFORMATION: Final = TypeAdapter(list[dict[str, object]]) _PII_TOKENS: Final = TypeAdapter(dict[str, str]) _GUARDRAIL_INFORMATION_KEY: Final = "standard_logging_guardrail_information" _GUARDED_FRAME_FIELDS: Final = ("input", "instructions", "tools", "tool_choice") +_REWRITTEN_FRAME_FIELDS: Final = (*_GUARDED_FRAME_FIELDS, "extra_body") _CLIENT_METADATA_KEYS: Final = ("metadata", "litellm_metadata") # the guardrail list is merged from key, team and the admission frame; a later frame cannot shrink it _CLIENT_GUARDRAIL_SELECTORS: Final = ("guardrails", "guardrail_config", "policies") @@ -2226,8 +2227,8 @@ def _responses_ws_frame_guard( await _bill_rejected_frame(rejected_frame_auth, rerouted, frame_data) raise rerouted # a guardrail may delete a field (the Responses translation pops ``instructions``), so start without them - guarded_fields: Final = {key: guarded_data[key] for key in _GUARDED_FRAME_FIELDS if key in guarded_data} - kept: Final = {key: value for key, value in body.items() if key not in _GUARDED_FRAME_FIELDS} + guarded_fields: Final = {key: guarded_data[key] for key in _REWRITTEN_FRAME_FIELDS if key in guarded_data} + kept: Final = {key: value for key, value in body.items() if key not in _REWRITTEN_FRAME_FIELDS} rewritten: Final = ( {**frame_obj, "response": {**kept, **guarded_fields}} if isinstance(nested, dict) diff --git a/litellm/types/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/types/proxy/guardrails/guardrail_hooks/tool_permission.py index 6f521d1fd1b..99ff7953ee2 100644 --- a/litellm/types/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/types/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -16,7 +16,7 @@ class ToolPermissionRule(LiteLLMBaseModel): id: str = Field(description="Unique identifier for the rule") tool_name: str | None = Field( default=None, - description="Regex pattern applied to the tool's function name", + description="Regex pattern applied to the tool's name, or to its type when the tool has no name", ) tool_type: str | None = Field( default=None, diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 6d3cfc3d9e1..6756178cccc 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -1399,12 +1399,20 @@ class TestToolPermissionGuardrailAnthropicMessages: @pytest.mark.asyncio @pytest.mark.parametrize( - ("rule_tool_type", "call_type"), - [(r"^custom$", "responses"), (r"^function$", "anthropic_messages")], - ids=["responses_custom_stays_custom", "anthropic_custom_reads_as_function"], + ("tool_fields", "rule_tool_type", "call_type"), + [ + ({"format": {"type": "text"}}, r"^custom$", "responses"), + ({"input_schema": {"type": "object", "properties": {}}}, r"^function$", "anthropic_messages"), + ({"input_schema": {"type": "object", "properties": {}}}, r"^function$", "pass_through_endpoint"), + ], + ids=[ + "responses_custom_stays_custom", + "anthropic_custom_reads_as_function", + "anthropic_custom_reads_as_function_on_a_pass_through_route", + ], ) async def test_pre_call_tool_type_rules_follow_the_request_format( - self, rule_tool_type: str, call_type: CallTypesLiteral + self, tool_fields: dict[str, object], rule_tool_type: str, call_type: CallTypesLiteral ) -> None: guardrail = ToolPermissionGuardrail( guardrail_name=f"tool-type-{call_type}", @@ -1417,7 +1425,7 @@ class TestToolPermissionGuardrailAnthropicMessages: data = { "model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "hi"}], - "tools": [{"type": "custom", "name": "apply_patch", "input_schema": {"type": "object", "properties": {}}}], + "tools": [{"type": "custom", "name": "apply_patch", **tool_fields}], } with pytest.raises(HTTPException) as excinfo: @@ -2189,8 +2197,18 @@ class TestToolPermissionGuardrailAnthropicMessages: {"function_calling_config": {"mode": "NONE"}}, ), ({"functionCallingConfig": {"mode": "ANY"}}, {"functionCallingConfig": {"mode": "ANY"}}), + ( + {"functionCallingConfig": {"mode": "AUTO", "allowedFunctionNames": []}}, + {"functionCallingConfig": {"mode": "AUTO", "allowedFunctionNames": []}}, + ), + ], + ids=[ + "some_allowed_names_left", + "every_allowed_name_removed", + "snake_case_fields", + "no_allowed_names", + "empty_allowed_names_list", ], - ids=["some_allowed_names_left", "every_allowed_name_removed", "snake_case_fields", "no_allowed_names"], ) async def test_pre_call_rewrite_drops_removed_functions_from_a_gemini_tool_config( self, tool_config: dict[str, object], rewritten_tool_config: dict[str, object] @@ -2224,6 +2242,65 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tools"] == [{"googleSearch": {}}] assert result["toolConfig"] == {"functionCallingConfig": {"mode": "NONE"}} + @pytest.mark.asyncio + async def test_pre_call_blocks_a_tool_whose_type_is_not_a_string_by_its_name(self) -> None: + guardrail = self._pre_call( + [ + {"id": "allow_search", "tool_type": r"^web_search$", "decision": "allow"}, + {"id": "deny_read", "tool_name": r"^Read$", "decision": "deny"}, + ], + "block", + ) + data = { + "model": "claude-sonnet-4-5", + "messages": [{"role": "user", "content": "hi"}], + "tools": [{"type": ["custom"], "name": "Read", "input_schema": {"type": "object"}}], + } + + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, "anthropic_messages") + + assert excinfo.value.status_code == 400 + assert excinfo.value.detail["detection_message"] == "Tool 'Read' denied by rule 'deny_read'" + + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("malformed_tool", "tool_choice", "call_type"), + [ + ({"type": ["custom"], "name": "Read", "input_schema": {"type": "object"}}, None, "anthropic_messages"), + ({"type": "function", "name": "Read"}, {"type": {"a": 1}}, "responses"), + ], + ids=["tool_type_is_a_list", "tool_choice_type_is_an_object"], + ) + async def test_pre_call_rewrite_strips_a_denied_tool_and_leaves_malformed_fields_for_the_provider( + self, malformed_tool: dict[str, object], tool_choice: dict[str, object] | None, call_type: CallTypesLiteral + ) -> None: + guardrail = self._pre_call([{"id": "deny_read", "tool_name": r"^Read$", "decision": "deny"}], "rewrite") + bash = {"type": "function", "name": "Bash"} + data = { + "model": "m", + "messages": [{"role": "user", "content": "hi"}], + "tools": [bash, malformed_tool], + **({"tool_choice": tool_choice} if tool_choice is not None else {}), + } + + result = await self._run_pre_call(guardrail, data, call_type) + + assert result["tools"] == [bash] + assert result.get("tool_choice") == tool_choice + + @pytest.mark.asyncio + async def test_pre_call_judges_a_tool_with_a_null_type_by_its_nested_function_name(self) -> None: + guardrail = self._pre_call( + [{"id": "allow_read", "tool_name": r"^Read$", "decision": "allow"}], "block", default_action="deny" + ) + tool = {"type": None, "function": {"name": "Read", "parameters": {"type": "object"}}} + data = {"model": "gpt-5", "messages": [{"role": "user", "content": "hi"}], "tools": [tool]} + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [tool] + @pytest.mark.asyncio async def test_pre_call_rewrite_drops_a_removed_hosted_tool_from_allowed_tools(self) -> None: guardrail = self._pre_call([{"id": "deny_search", "tool_type": r"^web_search$", "decision": "deny"}], "rewrite") diff --git a/tests/unit/proxy/response_api_endpoints/test_endpoints.py b/tests/unit/proxy/response_api_endpoints/test_endpoints.py index 2c084bec894..d185b49e56f 100644 --- a/tests/unit/proxy/response_api_endpoints/test_endpoints.py +++ b/tests/unit/proxy/response_api_endpoints/test_endpoints.py @@ -2453,6 +2453,41 @@ class TestResponsesWSFirstFrameModelAuth: sent = guarded["response"] if nested else guarded assert (sent["tools"], sent["tool_choice"]) == ([], "none") + @pytest.mark.asyncio + @pytest.mark.parametrize("nested", [True, False]) + async def test_frame_guard_forwards_the_extra_body_tools_a_rewrite_guardrail_stripped(self, nested: bool): + from litellm.proxy.guardrails.guardrail_hooks.tool_permission import ToolPermissionGuardrail + from litellm.proxy.response_api_endpoints.endpoints import _responses_ws_frame_guard + from litellm.types.guardrails import GuardrailEventHooks + + guardrail = ToolPermissionGuardrail( + guardrail_name="ws-rewrite", + rules=[{"id": "deny_shell", "tool_name": r"^shell$", "decision": "deny"}], + default_action="allow", + on_disallowed_action="rewrite", + event_hook=GuardrailEventHooks.pre_call, + default_on=True, + ) + + async def pre_call_hook(user_api_key_dict, data, call_type, guardrails_only): + return await guardrail.async_pre_call_hook( + user_api_key_dict=user_api_key_dict, cache=MagicMock(), data=data, call_type=call_type + ) + + proxy_logging_obj = MagicMock() + proxy_logging_obj.pre_call_hook = AsyncMock(side_effect=pre_call_hook) + guard = _responses_ws_frame_guard( + {"model": "gpt-4o-mini", "litellm_metadata": {}}, MagicMock(), proxy_logging_obj, MagicMock() + ) + weather = {"type": "function", "name": "get_weather"} + body = {"input": "hi", "extra_body": {"tools": [weather, {"type": "function", "name": "shell"}]}} + frame = {"type": "response.create", "response": body} if nested else {"type": "response.create", **body} + + guarded = json.loads((await guard(json.dumps(frame))).frame) + + sent = guarded["response"] if nested else guarded + assert sent["extra_body"] == {"tools": [weather]} + @pytest.mark.asyncio async def test_frame_guard_strips_the_proxy_owned_metadata_keys_a_client_sends(self): from litellm.proxy.response_api_endpoints.endpoints import _responses_ws_frame_guard diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts index 13a064517a4..dd29d72c44c 100644 --- a/ui/litellm-dashboard/src/lib/http/schema.d.ts +++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts @@ -47565,7 +47565,7 @@ export interface components { id: string; /** * Tool Name - * @description Regex pattern applied to the tool's function name + * @description Regex pattern applied to the tool's name, or to its type when the tool has no name */ tool_name?: string | null; /** From cea6450059062e284b8857b689c7c3f02c3a9a9e Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Fri, 30 Oct 2026 06:38:53 -0700 Subject: [PATCH 14/39] fix(guardrails): judge a named hosted tool by its type and keep a nested chat custom tool custom --- .../guardrail_hooks/tool_permission.py | 10 +++++-- .../guardrail_hooks/test_tool_permission.py | 29 +++++++++++++++++++ 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 4c505bd4feb..42c73921e58 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -60,6 +60,7 @@ _TOOL_CONFIG_KEYS: Final = ("toolConfig", "tool_config") _FUNCTION_CALLING_CONFIG_KEYS: Final = ("functionCallingConfig", "function_calling_config") _ALLOWED_FUNCTION_NAMES_KEYS: Final = ("allowedFunctionNames", "allowed_function_names") _FORCED_FUNCTION_CALLING_MODES: Final = frozenset({"ANY", "VALIDATED"}) +_NAME_IDENTIFIED_TYPES: Final = frozenset({"function", "custom", "namespace", *_HOSTED_SERVER_NAME_FIELDS}) _NAMED_CHOICE_TYPES: Final = frozenset({"tool", "function", "custom", "allowed_tools", "any", "auto", "none"}) _DECODED_ARGUMENTS: Final = TypeAdapter(object) _REQUEST_DATA: Final = TypeAdapter(object) @@ -936,11 +937,16 @@ class ToolPermissionGuardrail(CustomGuardrail): return member_targets raw_type: Final = self._get_mapping_value(tool, "type") tool_type: Final = raw_type if isinstance(raw_type, str) else None - anthropic_custom: Final = tool_type == "custom" and self._get_mapping_value(tool, "input_schema") is not None + anthropic_custom: Final = ( + tool_type == "custom" + and self._get_mapping_value(tool, "input_schema") is not None + and _object_mapping(self._get_mapping_value(tool, "custom")) is None + ) normalized_type: Final = "function" if tool_type is None or anthropic_custom else tool_type names: Final = _request_tool_names(tool) + type_target: Final = ((None, normalized_type),) if normalized_type not in _NAME_IDENTIFIED_TYPES else () if names: - return tuple((name, normalized_type) for name in names) + return tuple((name, normalized_type) for name in names) + type_target return ((None, tool_type),) if tool_type is not None else () def _get_legacy_function_name(self, function: object) -> str | None: diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 6756178cccc..032641e9c5c 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -1404,11 +1404,13 @@ class TestToolPermissionGuardrailAnthropicMessages: ({"format": {"type": "text"}}, r"^custom$", "responses"), ({"input_schema": {"type": "object", "properties": {}}}, r"^function$", "anthropic_messages"), ({"input_schema": {"type": "object", "properties": {}}}, r"^function$", "pass_through_endpoint"), + ({"custom": {"name": "apply_patch"}, "input_schema": {"type": "object"}}, r"^custom$", "acompletion"), ], ids=[ "responses_custom_stays_custom", "anthropic_custom_reads_as_function", "anthropic_custom_reads_as_function_on_a_pass_through_route", + "chat_custom_with_a_stray_input_schema_stays_custom", ], ) async def test_pre_call_tool_type_rules_follow_the_request_format( @@ -2242,6 +2244,33 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tools"] == [{"googleSearch": {}}] assert result["toolConfig"] == {"functionCallingConfig": {"mode": "NONE"}} + @pytest.mark.asyncio + @pytest.mark.parametrize("on_disallowed_action", ["block", "rewrite"]) + async def test_pre_call_judges_a_named_hosted_tool_by_its_type_as_well_as_its_name( + self, on_disallowed_action: Literal["block", "rewrite"] + ) -> None: + guardrail = self._pre_call( + [{"id": "allow_weather", "tool_name": r"^get_weather$", "decision": "allow"}], + on_disallowed_action, + default_action="deny", + ) + weather = {"type": "function", "function": {"name": "get_weather"}} + data = { + "model": "gemini-3", + "messages": [{"role": "user", "content": "hi"}], + "tools": [weather, {"type": "web_search", "name": "get_weather"}], + } + + if on_disallowed_action == "block": + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, "acompletion") + assert excinfo.value.detail["detection_message"] == "Tool 'web_search' denied by default action" + return + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [weather] + @pytest.mark.asyncio async def test_pre_call_blocks_a_tool_whose_type_is_not_a_string_by_its_name(self) -> None: guardrail = self._pre_call( From 3927751bb10df31ea7e37798c77444989e392fec Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Fri, 30 Oct 2026 09:01:10 -0700 Subject: [PATCH 15/39] fix(guardrails): keep judging Anthropic client tools and type-named server tools by their name --- .../guardrail_hooks/tool_permission.py | 16 ++++- .../guardrail_hooks/test_tool_permission.py | 58 +++++++++++++++++++ 2 files changed, 72 insertions(+), 2 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 42c73921e58..832638c77a0 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -61,12 +61,22 @@ _FUNCTION_CALLING_CONFIG_KEYS: Final = ("functionCallingConfig", "function_calli _ALLOWED_FUNCTION_NAMES_KEYS: Final = ("allowedFunctionNames", "allowed_function_names") _FORCED_FUNCTION_CALLING_MODES: Final = frozenset({"ANY", "VALIDATED"}) _NAME_IDENTIFIED_TYPES: Final = frozenset({"function", "custom", "namespace", *_HOSTED_SERVER_NAME_FIELDS}) +_CLIENT_RUN_TYPE_PREFIXES: Final = ("bash_", "text_editor_", "computer_", "memory_") +_TYPE_VERSION_SUFFIX: Final = re.compile(r"_\d{8}$") _NAMED_CHOICE_TYPES: Final = frozenset({"tool", "function", "custom", "allowed_tools", "any", "auto", "none"}) _DECODED_ARGUMENTS: Final = TypeAdapter(object) _REQUEST_DATA: Final = TypeAdapter(object) _ToolTarget: TypeAlias = tuple[str | None, str | None] +def _name_identifies_tool(name: str, tool_type: str) -> bool: + return ( + tool_type in _NAME_IDENTIFIED_TYPES + or tool_type.startswith(_CLIENT_RUN_TYPE_PREFIXES) + or _TYPE_VERSION_SUFFIX.sub("", tool_type) == name + ) + + def _object_mapping(value: object) -> Mapping[str, object] | None: """Return ``value`` as an opaque mapping when it is a dict.""" return value if isinstance(value, dict) else None @@ -944,9 +954,11 @@ class ToolPermissionGuardrail(CustomGuardrail): ) normalized_type: Final = "function" if tool_type is None or anthropic_custom else tool_type names: Final = _request_tool_names(tool) - type_target: Final = ((None, normalized_type),) if normalized_type not in _NAME_IDENTIFIED_TYPES else () + named_targets: Final = tuple((name, normalized_type) for name in names) + if names and all(_name_identifies_tool(name, normalized_type) for name in names): + return named_targets if names: - return tuple((name, normalized_type) for name in names) + type_target + return (*named_targets, (None, normalized_type)) return ((None, tool_type),) if tool_type is not None else () def _get_legacy_function_name(self, function: object) -> str | None: diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 032641e9c5c..a54de960932 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2271,6 +2271,64 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tools"] == [weather] + @pytest.mark.asyncio + @pytest.mark.parametrize( + "rules, tool", + [ + ( + [{"id": "allow_bash", "tool_name": r"^bash$", "decision": "allow"}], + {"type": "bash_20250124", "name": "bash"}, + ), + ( + [{"id": "allow_edit", "tool_name": r"^str_replace_based_edit_tool$", "decision": "allow"}], + {"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}, + ), + ( + [{"id": "allow_search", "tool_name": r"^web_search$", "decision": "allow"}], + {"type": "web_search_20250305", "name": "web_search"}, + ), + ( + [ + { + "id": "allow_search", + "tool_name": r"^web_search$", + "tool_type": r"^web_search_20250305$", + "decision": "allow", + } + ], + {"type": "web_search_20250305", "name": "web_search"}, + ), + ], + ids=["client_tool_by_name", "client_tool_with_its_own_name", "server_tool_by_name", "name_and_type_rule"], + ) + async def test_pre_call_allows_an_anthropic_defined_tool_that_an_allowlist_names( + self, rules: list[dict[str, object]], tool: dict[str, object] + ) -> None: + guardrail = self._pre_call(rules, "block", default_action="deny") + data = {"model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "hi"}], "tools": [tool]} + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [tool] + + @pytest.mark.asyncio + async def test_pre_call_blocks_an_anthropic_server_tool_whose_name_is_not_its_own(self) -> None: + guardrail = self._pre_call( + [{"id": "allow_weather", "tool_name": r"^get_weather$", "decision": "allow"}], + "block", + default_action="deny", + ) + data = { + "model": "gemini-3", + "messages": [{"role": "user", "content": "hi"}], + "tools": [{"type": "web_search_20250305", "name": "get_weather"}], + } + + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, "anthropic_messages") + + assert excinfo.value.detail["detection_message"] == "Tool 'web_search_20250305' denied by default action" + @pytest.mark.asyncio async def test_pre_call_blocks_a_tool_whose_type_is_not_a_string_by_its_name(self) -> None: guardrail = self._pre_call( From 51f8fdf2090681ebd456c9c0b383c1fbf030ea9c Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Fri, 30 Oct 2026 12:05:29 -0700 Subject: [PATCH 16/39] fix(guardrails): judge a named tool by its name alone only when the name is its type's own --- .../guardrail_hooks/tool_permission.py | 8 +++-- .../guardrail_hooks/test_tool_permission.py | 31 ++++++++++++++----- 2 files changed, 28 insertions(+), 11 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 832638c77a0..f463f8069f6 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -34,6 +34,7 @@ from litellm.proxy.guardrails.anthropic_sse import ( ) from litellm.responses.additional_tools import ADDITIONAL_TOOLS_INPUT_ITEM_TYPE from litellm.types.guardrails import GuardrailEventHooks, LitellmParams +from litellm.types.llms.anthropic import ANTHROPIC_HOSTED_TOOLS from litellm.types.proxy.guardrails.guardrail_hooks.tool_permission import ( PermissionError, ToolPermissionRule, @@ -61,7 +62,7 @@ _FUNCTION_CALLING_CONFIG_KEYS: Final = ("functionCallingConfig", "function_calli _ALLOWED_FUNCTION_NAMES_KEYS: Final = ("allowedFunctionNames", "allowed_function_names") _FORCED_FUNCTION_CALLING_MODES: Final = frozenset({"ANY", "VALIDATED"}) _NAME_IDENTIFIED_TYPES: Final = frozenset({"function", "custom", "namespace", *_HOSTED_SERVER_NAME_FIELDS}) -_CLIENT_RUN_TYPE_PREFIXES: Final = ("bash_", "text_editor_", "computer_", "memory_") +_TEXT_EDITOR_TOOL_NAMES: Final = frozenset({"str_replace_editor", "str_replace_based_edit_tool"}) _TYPE_VERSION_SUFFIX: Final = re.compile(r"_\d{8}$") _NAMED_CHOICE_TYPES: Final = frozenset({"tool", "function", "custom", "allowed_tools", "any", "auto", "none"}) _DECODED_ARGUMENTS: Final = TypeAdapter(object) @@ -70,10 +71,11 @@ _ToolTarget: TypeAlias = tuple[str | None, str | None] def _name_identifies_tool(name: str, tool_type: str) -> bool: + stem: Final = _TYPE_VERSION_SUFFIX.sub("", tool_type) return ( tool_type in _NAME_IDENTIFIED_TYPES - or tool_type.startswith(_CLIENT_RUN_TYPE_PREFIXES) - or _TYPE_VERSION_SUFFIX.sub("", tool_type) == name + or name == stem + or (stem == ANTHROPIC_HOSTED_TOOLS.TEXT_EDITOR.value and name in _TEXT_EDITOR_TOOL_NAMES) ) diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index a54de960932..98f6e2025f5 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2312,22 +2312,37 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tools"] == [tool] @pytest.mark.asyncio - async def test_pre_call_blocks_an_anthropic_server_tool_whose_name_is_not_its_own(self) -> None: + @pytest.mark.parametrize( + "tool, call_type", + [ + ({"type": "web_search_20250305", "name": "get_weather"}, "anthropic_messages"), + ( + { + "type": "computer_20251124", + "name": "get_weather", + "function": {"parameters": {"display_width_px": 1024, "display_height_px": 768}}, + }, + "acompletion", + ), + ({"type": "computer_use", "name": "get_weather", "environment": "browser"}, "acompletion"), + ({"type": "text_editor_20250728", "name": "get_weather"}, "anthropic_messages"), + ], + ids=["server_tool", "anthropic_computer_tool", "gemini_computer_use", "text_editor"], + ) + async def test_pre_call_blocks_a_provider_defined_tool_whose_name_is_not_its_own( + self, tool: dict[str, object], call_type: CallTypesLiteral + ) -> None: guardrail = self._pre_call( [{"id": "allow_weather", "tool_name": r"^get_weather$", "decision": "allow"}], "block", default_action="deny", ) - data = { - "model": "gemini-3", - "messages": [{"role": "user", "content": "hi"}], - "tools": [{"type": "web_search_20250305", "name": "get_weather"}], - } + data = {"model": "gemini-3", "messages": [{"role": "user", "content": "hi"}], "tools": [tool]} with pytest.raises(HTTPException) as excinfo: - await self._run_pre_call(guardrail, data, "anthropic_messages") + await self._run_pre_call(guardrail, data, call_type) - assert excinfo.value.detail["detection_message"] == "Tool 'web_search_20250305' denied by default action" + assert excinfo.value.detail["detection_message"] == f"Tool '{tool['type']}' denied by default action" @pytest.mark.asyncio async def test_pre_call_blocks_a_tool_whose_type_is_not_a_string_by_its_name(self) -> None: From dc821b68fcb1e398a8917356b2eb440867a99e20 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Fri, 30 Oct 2026 14:18:34 -0700 Subject: [PATCH 17/39] fix(guardrails): judge the function a tool names beside a declaration list or a top-level name --- .../guardrail_hooks/tool_permission.py | 17 ++++-- .../guardrail_hooks/test_tool_permission.py | 58 +++++++++++++++++++ 2 files changed, 70 insertions(+), 5 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index f463f8069f6..70ef58b7221 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -109,7 +109,10 @@ def _request_tool_names(tool: object) -> tuple[str, ...]: server_name: Final = ( _non_empty_string(fields.get(server_field)) if fields is not None and server_field is not None else None ) - return anthropic_tool_names(tool) + tuple(name for name in (custom_name, server_name) if name is not None) + function: Final = _object_mapping(fields.get("function")) if fields is not None else None + function_name: Final = _non_empty_string(function.get("name")) if function is not None else None + extra_names: Final = tuple(name for name in (function_name, custom_name, server_name) if name is not None) + return tuple(dict.fromkeys(anthropic_tool_names(tool) + extra_names)) def _namespace_members(tool: object) -> Sequence[object]: @@ -943,10 +946,12 @@ class ToolPermissionGuardrail(CustomGuardrail): else () ) keyed: Final = _keyed_tool_fields(tool) - if keyed is not None: - return member_targets + tuple(_part_target(keyed, key) for key in _part_keys(keyed)) - if group is not None: - return member_targets + part_targets: Final = tuple(_part_target(keyed, key) for key in _part_keys(keyed)) if keyed is not None else () + return member_targets + part_targets + self._own_tool_targets(tool) + + def _own_tool_targets(self, tool: object) -> tuple[_ToolTarget, ...]: + if _keyed_tool_fields(tool) is not None or _namespace_members(tool): + return () raw_type: Final = self._get_mapping_value(tool, "type") tool_type: Final = raw_type if isinstance(raw_type, str) else None anthropic_custom: Final = ( @@ -1038,6 +1043,8 @@ class ToolPermissionGuardrail(CustomGuardrail): fields: Final = _object_mapping(tool) if fields is None or (group is None and keyed is None): return () if any(map(is_denied, self._get_request_tool_targets(tool))) else (tool,) + if any(map(is_denied, self._own_tool_targets(tool))): + return () kept_members: Final = _kept_members(group, is_denied) denied_keys: Final = ( frozenset(key for key in _part_keys(keyed) if is_denied(_part_target(keyed, key))) diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 98f6e2025f5..bd148f39f5c 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2344,6 +2344,64 @@ class TestToolPermissionGuardrailAnthropicMessages: assert excinfo.value.detail["detection_message"] == f"Tool '{tool['type']}' denied by default action" + @pytest.mark.asyncio + @pytest.mark.parametrize("on_disallowed_action", ["block", "rewrite"]) + @pytest.mark.parametrize( + "tool", + [ + {"type": "function", "function": {"name": "delete_db"}, "functionDeclarations": [{"name": "get_weather"}]}, + {"type": "function", "function": {"name": "delete_db"}, "function_declarations": [{"name": "get_weather"}]}, + {"type": "custom", "name": "get_weather", "function": {"name": "delete_db"}}, + {"type": "mcp", "server_label": "get_weather", "function": {"name": "delete_db"}}, + { + "type": "computer_20251124", + "name": "computer", + "function": {"name": "delete_db", "parameters": {"display_width_px": 1024, "display_height_px": 768}}, + }, + ], + ids=[ + "declarations_list", + "snake_case_declarations_list", + "custom_top_level_name", + "mcp_server_label", + "computer_top_level_name", + ], + ) + async def test_pre_call_judges_the_function_a_tool_runs_behind_an_allowed_name( + self, tool: dict[str, object], on_disallowed_action: Literal["block", "rewrite"] + ) -> None: + guardrail = self._pre_call( + [{"id": "allow_known", "tool_name": r"^(get_weather|computer)$", "decision": "allow"}], + on_disallowed_action, + default_action="deny", + ) + weather = {"type": "function", "function": {"name": "get_weather"}} + data = {"model": "gemini-3", "messages": [{"role": "user", "content": "hi"}], "tools": [weather, tool]} + + if on_disallowed_action == "block": + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, "acompletion") + assert excinfo.value.detail["detection_message"] == "Tool 'delete_db' denied by default action" + return + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [weather] + + @pytest.mark.asyncio + async def test_pre_call_allows_a_custom_tool_by_its_function_name(self) -> None: + guardrail = self._pre_call( + [{"id": "allow_weather", "tool_name": r"^get_weather$", "decision": "allow"}], + "block", + default_action="deny", + ) + tool = {"type": "custom", "function": {"name": "get_weather"}} + data = {"model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "hi"}], "tools": [tool]} + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [tool] + @pytest.mark.asyncio async def test_pre_call_blocks_a_tool_whose_type_is_not_a_string_by_its_name(self) -> None: guardrail = self._pre_call( From 600547764da8cc6578f177aa6baec3c6ca7ba582 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Fri, 30 Oct 2026 18:48:41 -0700 Subject: [PATCH 18/39] fix(guardrails): judge Gemini hosted keys whatever the tool type and a namespace's function --- .../guardrail_hooks/tool_permission.py | 37 +++++++++-- .../guardrail_hooks/test_tool_permission.py | 62 ++++++++++++++++++- 2 files changed, 92 insertions(+), 7 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 70ef58b7221..b5e160ca919 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -35,6 +35,7 @@ from litellm.proxy.guardrails.anthropic_sse import ( from litellm.responses.additional_tools import ADDITIONAL_TOOLS_INPUT_ITEM_TYPE from litellm.types.guardrails import GuardrailEventHooks, LitellmParams from litellm.types.llms.anthropic import ANTHROPIC_HOSTED_TOOLS +from litellm.types.llms.vertex_ai import VertexToolName from litellm.types.proxy.guardrails.guardrail_hooks.tool_permission import ( PermissionError, ToolPermissionRule, @@ -64,6 +65,7 @@ _FORCED_FUNCTION_CALLING_MODES: Final = frozenset({"ANY", "VALIDATED"}) _NAME_IDENTIFIED_TYPES: Final = frozenset({"function", "custom", "namespace", *_HOSTED_SERVER_NAME_FIELDS}) _TEXT_EDITOR_TOOL_NAMES: Final = frozenset({"str_replace_editor", "str_replace_based_edit_tool"}) _TYPE_VERSION_SUFFIX: Final = re.compile(r"_\d{8}$") +_GEMINI_HOSTED_TOOL_KEYS: Final = frozenset(tool.value.replace("_", "").lower() for tool in VertexToolName) _NAMED_CHOICE_TYPES: Final = frozenset({"tool", "function", "custom", "allowed_tools", "any", "auto", "none"}) _DECODED_ARGUMENTS: Final = TypeAdapter(object) _REQUEST_DATA: Final = TypeAdapter(object) @@ -109,12 +111,29 @@ def _request_tool_names(tool: object) -> tuple[str, ...]: server_name: Final = ( _non_empty_string(fields.get(server_field)) if fields is not None and server_field is not None else None ) - function: Final = _object_mapping(fields.get("function")) if fields is not None else None - function_name: Final = _non_empty_string(function.get("name")) if function is not None else None - extra_names: Final = tuple(name for name in (function_name, custom_name, server_name) if name is not None) + extra_names: Final = tuple(name for name in (_function_name(tool), custom_name, server_name) if name is not None) return tuple(dict.fromkeys(anthropic_tool_names(tool) + extra_names)) +def _function_name(tool: object) -> str | None: + fields: Final = _object_mapping(tool) + function: Final = _object_mapping(fields.get("function")) if fields is not None else None + return _non_empty_string(function.get("name")) if function is not None else None + + +def _namespace_function_targets(tool: object) -> tuple[_ToolTarget, ...]: + function_name: Final = _function_name(tool) + return ((function_name, "function"),) if function_name is not None else () + + +def _gemini_hosted_key_targets(tool: object) -> tuple[_ToolTarget, ...]: + fields: Final = _object_mapping(tool) + if fields is None: + return () + hosted_keys: Final = (key for key in fields if key.replace("_", "").lower() in _GEMINI_HOSTED_TOOL_KEYS) + return tuple(_part_target(fields, key) for key in hosted_keys) + + def _namespace_members(tool: object) -> Sequence[object]: fields: Final = _object_mapping(tool) members: Final = ( @@ -950,8 +969,12 @@ class ToolPermissionGuardrail(CustomGuardrail): return member_targets + part_targets + self._own_tool_targets(tool) def _own_tool_targets(self, tool: object) -> tuple[_ToolTarget, ...]: - if _keyed_tool_fields(tool) is not None or _namespace_members(tool): + if _keyed_tool_fields(tool) is not None: return () + named: Final = _namespace_function_targets(tool) if _namespace_members(tool) else self._named_tool_targets(tool) + return named + _gemini_hosted_key_targets(tool) + + def _named_tool_targets(self, tool: object) -> tuple[_ToolTarget, ...]: raw_type: Final = self._get_mapping_value(tool, "type") tool_type: Final = raw_type if isinstance(raw_type, str) else None anthropic_custom: Final = ( @@ -1043,7 +1066,8 @@ class ToolPermissionGuardrail(CustomGuardrail): fields: Final = _object_mapping(tool) if fields is None or (group is None and keyed is None): return () if any(map(is_denied, self._get_request_tool_targets(tool))) else (tool,) - if any(map(is_denied, self._own_tool_targets(tool))): + own_targets: Final = self._own_tool_targets(tool) + if any(map(is_denied, own_targets)): return () kept_members: Final = _kept_members(group, is_denied) denied_keys: Final = ( @@ -1060,7 +1084,8 @@ class ToolPermissionGuardrail(CustomGuardrail): for key, value in fields.items() if key not in dropped_keys } - parts_left: Final = bool(kept_members) or (keyed is not None and bool(_part_keys(kept_fields))) + own_name_left: Final = any(name is not None for name, _ in own_targets) + parts_left: Final = bool(kept_members) or own_name_left or (keyed is not None and bool(_part_keys(kept_fields))) return (kept_fields,) if parts_left else () def _kept_tool_list( diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index bd148f39f5c..e4ad261b346 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2353,6 +2353,12 @@ class TestToolPermissionGuardrailAnthropicMessages: {"type": "function", "function": {"name": "delete_db"}, "function_declarations": [{"name": "get_weather"}]}, {"type": "custom", "name": "get_weather", "function": {"name": "delete_db"}}, {"type": "mcp", "server_label": "get_weather", "function": {"name": "delete_db"}}, + { + "type": "namespace", + "name": "github", + "tools": [{"type": "function", "name": "create_issue"}], + "function": {"name": "delete_db"}, + }, { "type": "computer_20251124", "name": "computer", @@ -2364,6 +2370,7 @@ class TestToolPermissionGuardrailAnthropicMessages: "snake_case_declarations_list", "custom_top_level_name", "mcp_server_label", + "namespace_with_members", "computer_top_level_name", ], ) @@ -2371,7 +2378,7 @@ class TestToolPermissionGuardrailAnthropicMessages: self, tool: dict[str, object], on_disallowed_action: Literal["block", "rewrite"] ) -> None: guardrail = self._pre_call( - [{"id": "allow_known", "tool_name": r"^(get_weather|computer)$", "decision": "allow"}], + [{"id": "allow_known", "tool_name": r"^(get_weather|computer|github__create_issue)$", "decision": "allow"}], on_disallowed_action, default_action="deny", ) @@ -2388,6 +2395,59 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tools"] == [weather] + @pytest.mark.asyncio + @pytest.mark.parametrize("on_disallowed_action", ["block", "rewrite"]) + @pytest.mark.parametrize( + ("tool", "hosted_key"), + [ + ({"type": "get_weather", "googleSearch": {}}, "googleSearch"), + ({"type": "function", "codeExecution": {}}, "codeExecution"), + ({"type": "get_weather", "url_context": {}}, "url_context"), + ], + ids=["named_type_google_search", "function_type_code_execution", "named_type_url_context"], + ) + async def test_pre_call_judges_a_gemini_hosted_tool_key_whatever_the_tool_type( + self, tool: dict[str, object], hosted_key: str, on_disallowed_action: Literal["block", "rewrite"] + ) -> None: + guardrail = self._pre_call( + [ + {"id": "allow_weather", "tool_name": r"^get_weather$", "decision": "allow"}, + {"id": "allow_functions", "tool_type": r"^function$", "decision": "allow"}, + ], + on_disallowed_action, + default_action="deny", + ) + weather = {"type": "function", "function": {"name": "get_weather"}} + data = {"model": "gemini-3", "messages": [{"role": "user", "content": "hi"}], "tools": [weather, tool]} + + if on_disallowed_action == "block": + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, "acompletion") + assert excinfo.value.detail["detection_message"] == f"Tool '{hosted_key}' denied by default action" + return + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [weather] + + @pytest.mark.asyncio + async def test_rewrite_keeps_an_allowed_function_whose_declaration_list_is_denied(self) -> None: + guardrail = self._pre_call( + [{"id": "allow_weather", "tool_name": r"^get_weather$", "decision": "allow"}], + "rewrite", + default_action="deny", + ) + tool = { + "type": "function", + "function": {"name": "get_weather"}, + "functionDeclarations": [{"name": "delete_db"}], + } + data = {"model": "gemini-3", "messages": [{"role": "user", "content": "hi"}], "tools": [tool]} + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [{"type": "function", "function": {"name": "get_weather"}}] + @pytest.mark.asyncio async def test_pre_call_allows_a_custom_tool_by_its_function_name(self) -> None: guardrail = self._pre_call( From d308905b72da0f80202acda9a7e89eca9085be14 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Fri, 30 Oct 2026 21:29:23 -0700 Subject: [PATCH 19/39] fix(guardrails): judge legacy functions entries like tools and send Gemini a namespace's members --- .../vertex_and_google_ai_studio_gemini.py | 17 +++++- .../guardrail_hooks/tool_permission.py | 43 ++++++++------- ...test_vertex_and_google_ai_studio_gemini.py | 18 +++++++ .../guardrail_hooks/test_tool_permission.py | 53 +++++++++++++++++++ 4 files changed, 112 insertions(+), 19 deletions(-) diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index 1ef5267df14..38bb016d976 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -8,6 +8,7 @@ import time from collections.abc import Awaitable, Callable, Mapping, Sequence from copy import deepcopy from functools import lru_cache, partial +from itertools import chain from types import MappingProxyType from typing import TYPE_CHECKING, Any, Final, Literal, Optional, Protocol, Union, cast, get_args @@ -510,6 +511,19 @@ def mapped_gemini_speech_config( } +def _namespace_members_or_tool(tool: JsonValue) -> tuple[JsonValue, ...]: + if not isinstance(tool, dict) or tool.get("type") != "namespace": + return (tool,) + members: Final = tool.get("tools") + return tuple(members) if isinstance(members, list) else () + + +def _with_namespace_members_inlined(tools: JsonValue) -> JsonValue: + if not isinstance(tools, list): + return tools + return list(chain.from_iterable(map(_namespace_members_or_tool, tools))) + + class VertexAIBaseConfig: def get_mapped_special_auth_params(self) -> dict: """ @@ -1063,7 +1077,8 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig): # remove 'strict' from tools remove_strict_from_schema(schema_value) - for tool in cast(list[dict], schema_value): # cast-ok: a deep copy keeps the caller's tool shape + inlined_tools: Final = _with_namespace_members_inlined(schema_value) + for tool in cast(list[dict], inlined_tools): # cast-ok: a deep copy keeps the caller's tool shape openai_function_object: ChatCompletionToolParamFunctionChunk | None = None if "function" in tool: # tools list _openai_function_object = ChatCompletionToolParamFunctionChunk(**tool["function"]) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index b5e160ca919..20e059f7e25 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -65,13 +65,27 @@ _FORCED_FUNCTION_CALLING_MODES: Final = frozenset({"ANY", "VALIDATED"}) _NAME_IDENTIFIED_TYPES: Final = frozenset({"function", "custom", "namespace", *_HOSTED_SERVER_NAME_FIELDS}) _TEXT_EDITOR_TOOL_NAMES: Final = frozenset({"str_replace_editor", "str_replace_based_edit_tool"}) _TYPE_VERSION_SUFFIX: Final = re.compile(r"_\d{8}$") -_GEMINI_HOSTED_TOOL_KEYS: Final = frozenset(tool.value.replace("_", "").lower() for tool in VertexToolName) +_GEMINI_TYPED_HOSTED_TOOLS: Final = ("computer_use", "web_search", "web_search_preview") _NAMED_CHOICE_TYPES: Final = frozenset({"tool", "function", "custom", "allowed_tools", "any", "auto", "none"}) _DECODED_ARGUMENTS: Final = TypeAdapter(object) _REQUEST_DATA: Final = TypeAdapter(object) _ToolTarget: TypeAlias = tuple[str | None, str | None] +def _snake_case(name: str) -> str: + return re.sub(r"(? str: + head, *rest = name.split("_") + return head + "".join(part.title() for part in rest) + + +_GEMINI_HOSTED_TOOL_KEYS: Final = frozenset( + chain.from_iterable((_snake_case(tool.value), _camel_case(tool.value)) for tool in VertexToolName) +) + + def _name_identifies_tool(name: str, tool_type: str) -> bool: stem: Final = _TYPE_VERSION_SUFFIX.sub("", tool_type) return ( @@ -128,10 +142,10 @@ def _namespace_function_targets(tool: object) -> tuple[_ToolTarget, ...]: def _gemini_hosted_key_targets(tool: object) -> tuple[_ToolTarget, ...]: fields: Final = _object_mapping(tool) - if fields is None: + if fields is None or fields.get("type") in _GEMINI_TYPED_HOSTED_TOOLS: return () - hosted_keys: Final = (key for key in fields if key.replace("_", "").lower() in _GEMINI_HOSTED_TOOL_KEYS) - return tuple(_part_target(fields, key) for key in hosted_keys) + keys: Final = tuple(key for key in fields if key != "type") + return (_part_target(fields, keys[0]),) if len(keys) == 1 and keys[0] in _GEMINI_HOSTED_TOOL_KEYS else () def _namespace_members(tool: object) -> Sequence[object]: @@ -242,6 +256,7 @@ def _extra_body_tools(data: object) -> Sequence[object] | None: def _sent_tools(data: object) -> tuple[object, ...]: return ( *(_request_list(data, "tools") or ()), + *(_request_list(data, "functions") or ()), *(_extra_body_tools(data) or ()), *_tools_in_items(_input_items(data)), ) @@ -991,9 +1006,6 @@ class ToolPermissionGuardrail(CustomGuardrail): return (*named_targets, (None, normalized_type)) return ((None, tool_type),) if tool_type is not None else () - def _get_legacy_function_name(self, function: object) -> str | None: - return self._get_mapping_value(function, "name") - def _get_named_tool_choice(self, tool_choice: object) -> str | None: if not tool_choice or tool_choice in ("auto", "none", "required"): return None @@ -1031,9 +1043,7 @@ class ToolPermissionGuardrail(CustomGuardrail): request_tools.extend(map(_mcp_server_target, _request_list(request, "mcp_servers") or ())) for function in _request_list(request, "functions") or (): - function_name = self._get_legacy_function_name(function) - if function_name is not None: - request_tools.append((function_name, "function")) + request_tools.extend(self._get_request_tool_targets(function)) listed_names: Final = frozenset(name for name, _ in request_tools) for forced_tool_name in ( @@ -1167,13 +1177,9 @@ class ToolPermissionGuardrail(CustomGuardrail): } functions: Final = _request_list(request, "functions") - kept_functions: Final = ( - None - if functions is None - else [function for function in functions if self._get_legacy_function_name(function) not in denied_names] - ) + kept_functions: Final = None if functions is None else kept_tool_list(functions) if kept_functions is not None: - data["functions"] = kept_functions # rebind-ok: rewrite mode edits the request in place + data["functions"] = list(kept_functions) # rebind-ok: rewrite mode edits the request in place mcp_servers: Final = _request_list(request, "mcp_servers") kept_mcp_servers: Final = ( @@ -1198,6 +1204,7 @@ class ToolPermissionGuardrail(CustomGuardrail): kept_sent_tools: Final = ( *(kept_tools or ()), + *(kept_functions or ()), *(kept_extra_body_tools or ()), *_tools_in_items(kept_input_items), ) @@ -1205,7 +1212,7 @@ class ToolPermissionGuardrail(CustomGuardrail): kept_types: Final = self._tool_types_in(kept_sent_tools) removed_types: Final = self._tool_types_in(sent_tools) - kept_types - tools_remain: Final = bool(kept_sent_tools) or bool(kept_functions) or bool(kept_mcp_servers) + tools_remain: Final = bool(kept_sent_tools) or bool(kept_mcp_servers) tool_choice: Final = _REQUEST_DATA.validate_python(data.get("tool_choice")) if tool_choice is not None: rewritten_choice: Final = self._rewritten_tool_choice( @@ -1214,7 +1221,7 @@ class ToolPermissionGuardrail(CustomGuardrail): data["tool_choice"] = rewritten_choice # rebind-ok: rewrite mode edits the request in place named_function_call: Final = self._get_named_function_call(data) - if named_function_call in denied_names: + if named_function_call in removed_names: data["function_call"] = "none" # rebind-ok: rewrite mode edits the request in place functions_remain: Final = "function" in kept_types diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index 98d1b8f1300..3aae3d13023 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -1783,6 +1783,24 @@ def test_vertex_ai_map_tools(): assert tools == new_tools +def test_vertex_ai_map_tools_declares_a_namespace_by_its_members() -> None: + namespace = { + "type": "namespace", + "name": "github", + "tools": [ + {"type": "function", "name": "create_issue", "parameters": {"type": "object", "properties": {}}}, + {"type": "function", "function": {"name": "close_issue"}}, + ], + } + + tools = VertexGeminiConfig().map_function(value=[namespace], optional_params={}) + + assert [declaration["name"] for declaration in tools[0]["function_declarations"]] == [ + "create_issue", + "close_issue", + ] + + def test_vertex_ai_map_tool_with_anyof(): """ Related issue: https://github.com/BerriAI/litellm/issues/11164 diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index e4ad261b346..1bbba314efd 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2430,6 +2430,59 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tools"] == [weather] + @pytest.mark.asyncio + @pytest.mark.parametrize("on_disallowed_action", ["block", "rewrite"]) + async def test_pre_call_leaves_a_gemini_hosted_key_that_sits_beside_a_function( + self, on_disallowed_action: Literal["block", "rewrite"] + ) -> None: + guardrail = self._pre_call( + [{"id": "allow_weather", "tool_name": r"^get_weather$", "decision": "allow"}], + on_disallowed_action, + default_action="deny", + ) + tool = {"type": "function", "function": {"name": "get_weather"}, "googleSearch": {}} + data = {"model": "gemini-3", "messages": [{"role": "user", "content": "hi"}], "tools": [tool]} + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [tool] + + @pytest.mark.asyncio + @pytest.mark.parametrize("on_disallowed_action", ["block", "rewrite"]) + @pytest.mark.parametrize( + ("function", "denied"), + [ + ({"type": "function", "function": {"name": "delete_db"}}, "delete_db"), + ({"name": "get_weather", "function": {"name": "delete_db"}}, "delete_db"), + ({"googleSearch": {}}, "googleSearch"), + ], + ids=["function_object", "function_object_behind_an_allowed_name", "gemini_hosted_key"], + ) + async def test_pre_call_judges_a_legacy_functions_entry_like_a_tool( + self, function: dict[str, object], denied: str, on_disallowed_action: Literal["block", "rewrite"] + ) -> None: + guardrail = self._pre_call( + [{"id": "allow_weather", "tool_name": r"^get_weather$", "decision": "allow"}], + on_disallowed_action, + default_action="deny", + ) + weather = {"name": "get_weather"} + data = { + "model": "gemini-3", + "messages": [{"role": "user", "content": "hi"}], + "functions": [weather, function], + } + + if on_disallowed_action == "block": + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, "acompletion") + assert excinfo.value.detail["detection_message"] == f"Tool '{denied}' denied by default action" + return + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["functions"] == [weather] + @pytest.mark.asyncio async def test_rewrite_keeps_an_allowed_function_whose_declaration_list_is_denied(self) -> None: guardrail = self._pre_call( From 499015c671344b59cadb91d67010d93d6330af1f Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Fri, 30 Oct 2026 23:38:59 -0700 Subject: [PATCH 20/39] fix(guardrails): judge a namespace member by every name a provider reads and send Gemini its schema converted --- .../vertex_and_google_ai_studio_gemini.py | 11 +- .../guardrail_hooks/tool_permission.py | 109 ++++++++++-------- ...test_vertex_and_google_ai_studio_gemini.py | 17 +++ .../guardrail_hooks/test_tool_permission.py | 93 ++++++++++++++- 4 files changed, 183 insertions(+), 47 deletions(-) diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index 38bb016d976..e2d0adcdad0 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -511,11 +511,20 @@ def mapped_gemini_speech_config( } +def _as_chat_tool(member: JsonValue) -> JsonValue: + if not isinstance(member, dict) or "function" in member or "name" not in member: + return member + return { + "type": member.get("type", "function"), + "function": {key: value for key, value in member.items() if key != "type"}, + } + + def _namespace_members_or_tool(tool: JsonValue) -> tuple[JsonValue, ...]: if not isinstance(tool, dict) or tool.get("type") != "namespace": return (tool,) members: Final = tool.get("tools") - return tuple(members) if isinstance(members, list) else () + return tuple(map(_as_chat_tool, members)) if isinstance(members, list) else () def _with_namespace_members_inlined(tools: JsonValue) -> JsonValue: diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 20e059f7e25..ef13b45bce9 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -160,15 +160,11 @@ def _qualified_member_name(namespace: str, name: str) -> str: return f"{namespace}__{name}" -def _namespace_member_target(namespace: str | None, member: object) -> _ToolTarget | None: - fields: Final = _object_mapping(member) - if fields is None: - return None - member_type: Final = _non_empty_string(fields.get("type")) - name: Final = _non_empty_string(fields.get("name")) - if name is None or namespace is None: - return (name, member_type) - return (_qualified_member_name(namespace, name), member_type) +def _qualified_target(namespace: str | None, target: _ToolTarget) -> _ToolTarget: + name, tool_type = target + return ( + (_qualified_member_name(namespace, name), tool_type) if namespace is not None and name is not None else target + ) def _member_name(member: object) -> str | None: @@ -176,38 +172,30 @@ def _member_name(member: object) -> str | None: return _non_empty_string(fields.get("name")) if fields is not None else None -def _bare_member_names(tool: object) -> tuple[tuple[str, str], ...]: - fields: Final = _object_mapping(tool) - namespace: Final = _non_empty_string(fields.get("name")) if fields is not None else None - if namespace is None: - return () - names: Final = (name for name in map(_member_name, _namespace_members(tool)) if name is not None) - return tuple((_qualified_member_name(namespace, name), name) for name in names) - - -def _declaration_target(declaration: object) -> _ToolTarget | None: - fields: Final = _object_mapping(declaration) - name: Final = _non_empty_string(fields.get("name")) if fields is not None else None - return (name, "function") if name is not None else None +def _declaration_targets(declaration: object) -> tuple[_ToolTarget, ...]: + name: Final = _member_name(declaration) + return ((name, "function"),) if name is not None else () @dataclass(frozen=True, slots=True) class _MemberGroup: key: str members: Sequence[object] - target_of: Callable[[object], _ToolTarget | None] + targets_of: Callable[[object], tuple[_ToolTarget, ...]] -def _member_group(tool: object) -> _MemberGroup | None: +def _member_group( + tool: object, namespace_member_targets: Callable[[str | None, object], tuple[_ToolTarget, ...]] +) -> _MemberGroup | None: fields: Final = _object_mapping(tool) if fields is None: return None members: Final = _namespace_members(tool) if members: - return _MemberGroup("tools", members, partial(_namespace_member_target, _non_empty_string(fields.get("name")))) + return _MemberGroup("tools", members, partial(namespace_member_targets, _member_name(tool))) key: Final = next((key for key in _DECLARATION_KEYS if _object_list(fields.get(key))), None) declarations: Final = _object_list(fields.get(key)) if key is not None else None - return _MemberGroup(key, declarations, _declaration_target) if key is not None and declarations else None + return _MemberGroup(key, declarations, _declaration_targets) if key is not None and declarations else None def _keyed_tool_fields(tool: object) -> Mapping[str, object] | None: @@ -355,7 +343,7 @@ def _is_denied_target( def _kept_members(group: _MemberGroup | None, is_denied: Callable[[_ToolTarget], bool]) -> tuple[object, ...]: if group is None: return () - return tuple(member for member in group.members if not is_denied(group.target_of(member) or (None, None))) + return tuple(member for member in group.members if not any(map(is_denied, group.targets_of(member)))) def _none_tool_choice(tool_choice: object) -> object: @@ -655,23 +643,31 @@ class ToolPermissionGuardrail(CustomGuardrail): verbose_proxy_logger.debug(message) return is_allowed, None, message - def _has_matching_name_rule(self, tool_name: str | None, tool_type: str | None) -> bool: - return any( - rule.tool_name is not None and self._rule_matches_tool(rule, tool_name=tool_name, tool_type=tool_type)[0] - for rule in self.rules - ) + def _is_name_rule_for(self, rule: ToolPermissionRule, tool_name: str, tool_type: str | None) -> bool: + return rule.tool_name is not None and self._rule_matches_tool(rule, tool_name=tool_name, tool_type=tool_type)[0] + + def _first_name_rule(self, tool_name: str, tool_type: str | None) -> ToolPermissionRule | None: + return next((rule for rule in self.rules if self._is_name_rule_for(rule, tool_name, tool_type)), None) + + def _deciding_member_name(self, qualified: str, bare: str, tool_type: str | None) -> str: + qualified_rule: Final = self._first_name_rule(qualified, tool_type) + bare_rule: Final = self._first_name_rule(bare, tool_type) + if bare_rule is None or bare_rule is qualified_rule: + return qualified + if qualified_rule is None or self._is_name_rule_for(qualified_rule, bare, tool_type): + return bare + if self._is_name_rule_for(bare_rule, qualified, tool_type): + return qualified + return bare if bare_rule.decision == "deny" else qualified def _check_target_permission( self, target: _ToolTarget, bare_names: Mapping[str, str] ) -> tuple[bool, str | None, str | None]: name, tool_type = target bare_name: Final = bare_names.get(name) if name is not None else None - falls_back: Final = ( - bare_name is not None - and not self._has_matching_name_rule(name, tool_type) - and self._has_matching_name_rule(bare_name, tool_type) - ) - return self._check_tool_permission(bare_name if falls_back else name, tool_type) + if name is None or bare_name is None: + return self._check_tool_permission(name, tool_type) + return self._check_tool_permission(self._deciding_member_name(name, bare_name, tool_type), tool_type) def _parse_tool_call_arguments( self, tool_call: ChatCompletionMessageToolCall @@ -972,13 +968,36 @@ class ToolPermissionGuardrail(CustomGuardrail): if not any(_is_tool_use_block(block) for block in kept_blocks): response["stop_reason"] = "end_turn" # rebind-ok: dropping every tool_use ends the turn - def _get_request_tool_targets(self, tool: object) -> tuple[_ToolTarget, ...]: - group: Final = _member_group(tool) - member_targets: Final = ( - tuple(target for target in map(group.target_of, group.members) if target is not None) - if group is not None + def _unqualified_member_targets(self, member: object) -> tuple[_ToolTarget, ...]: + fields: Final = _object_mapping(member) + if fields is None: + return () + targets: Final = self._get_request_tool_targets(member) + own_name: Final = _member_name(member) + judged_names: Final = frozenset(name for name, _ in targets) + own_target: Final = ( + ((own_name, _non_empty_string(fields.get("type"))),) + if own_name is not None and own_name not in judged_names else () ) + return targets + own_target + + def _namespace_member_targets(self, namespace: str | None, member: object) -> tuple[_ToolTarget, ...]: + return tuple(_qualified_target(namespace, target) for target in self._unqualified_member_targets(member)) + + def _bare_member_names(self, tool: object) -> tuple[tuple[str, str], ...]: + namespace: Final = _member_name(tool) + members: Final = _namespace_members(tool) + if namespace is None or not members: + return () + targets: Final = chain.from_iterable(map(self._unqualified_member_targets, members)) + return tuple((_qualified_member_name(namespace, name), name) for name, _ in targets if name is not None) + + def _get_request_tool_targets(self, tool: object) -> tuple[_ToolTarget, ...]: + group: Final = _member_group(tool, self._namespace_member_targets) + member_targets: Final = ( + tuple(chain.from_iterable(map(group.targets_of, group.members))) if group is not None else () + ) keyed: Final = _keyed_tool_fields(tool) part_targets: Final = tuple(_part_target(keyed, key) for key in _part_keys(keyed)) if keyed is not None else () return member_targets + part_targets + self._own_tool_targets(tool) @@ -1071,7 +1090,7 @@ class ToolPermissionGuardrail(CustomGuardrail): denied_names: frozenset[str], ) -> tuple[object, ...]: is_denied: Final = partial(_is_denied_target, denied_targets=denied_targets, denied_names=denied_names) - group: Final = _member_group(tool) + group: Final = _member_group(tool, self._namespace_member_targets) keyed: Final = _keyed_tool_fields(tool) fields: Final = _object_mapping(tool) if fields is None or (group is None and keyed is None): @@ -1354,7 +1373,7 @@ class ToolPermissionGuardrail(CustomGuardrail): return data bare_names: Final = MappingProxyType( - dict(chain.from_iterable(map(_bare_member_names, _sent_tools(_REQUEST_DATA.validate_python(data))))) + dict(chain.from_iterable(map(self._bare_member_names, _sent_tools(_REQUEST_DATA.validate_python(data))))) ) decisions: Final = tuple((target, self._check_target_permission(target, bare_names)) for target in new_tools) denied: Final = tuple( diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index 3aae3d13023..1026ac8ba95 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -1801,6 +1801,23 @@ def test_vertex_ai_map_tools_declares_a_namespace_by_its_members() -> None: ] +def test_vertex_ai_map_tools_declares_a_namespace_member_like_the_same_chat_tool() -> None: + parameters = { + "type": "object", + "properties": {"repo": {"$ref": "#/$defs/Repo"}, "label": {"type": ["string", "null"]}}, + "$defs": {"Repo": {"type": "string"}}, + } + function = {"name": "create_issue", "description": "Open an issue", "parameters": parameters} + namespace = {"type": "namespace", "name": "github", "tools": [{"type": "function", **function}]} + + from_namespace = VertexGeminiConfig().map_function(value=[namespace], optional_params={}) + from_chat_tool = VertexGeminiConfig().map_function( + value=[{"type": "function", "function": function}], optional_params={} + ) + + assert from_namespace == from_chat_tool + + def test_vertex_ai_map_tool_with_anyof(): """ Related issue: https://github.com/BerriAI/litellm/issues/11164 diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 1bbba314efd..1227f137d1e 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2144,15 +2144,33 @@ class TestToolPermissionGuardrailAnthropicMessages: "allow", "Tool 'exec' denied by rule 'deny_exec'", ), + ( + [ + {"id": "deny_exec", "tool_name": r"^exec$", "decision": "deny"}, + {"id": "allow_all", "tool_name": r"^.*$", "decision": "allow"}, + ], + "deny", + "Tool 'exec' denied by rule 'deny_exec'", + ), + ( + [ + {"id": "allow_functions", "tool_name": r"^functions__.*$", "decision": "allow"}, + {"id": "deny_all", "tool_name": r"^.*$", "decision": "deny"}, + ], + "allow", + None, + ), ], ids=[ "bare_name_deny_rule", "bare_name_allow_rule", "qualified_rule_wins_over_an_earlier_bare_rule", "type_rule_keeps_an_earlier_bare_name_rule_in_charge", + "bare_name_deny_beats_a_later_catch_all_allow", + "qualified_allow_beats_a_later_catch_all_deny", ], ) - async def test_pre_call_judges_a_namespace_member_by_its_bare_name_when_no_rule_names_it_qualified( + async def test_pre_call_judges_a_namespace_member_by_its_qualified_and_bare_names( self, rules: list[dict[str, str]], default_action: Literal["allow", "deny"], detection_message: str | None ) -> None: guardrail = self._pre_call(rules, "block", default_action=default_action) @@ -2177,6 +2195,79 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tools"] == [{"type": "namespace", "name": "functions", "tools": members[1:]}] + @pytest.mark.asyncio + @pytest.mark.parametrize("placement", ["tools", "functions"]) + @pytest.mark.parametrize("on_disallowed_action", ["block", "rewrite"]) + @pytest.mark.parametrize( + ("member", "detection_message"), + [ + ({"type": "function", "function": {"name": "delete_db"}}, "Tool 'delete_db' denied by rule 'deny_delete'"), + ( + {"type": "function", "name": "lookup", "function": {"name": "delete_db"}}, + "Tool 'delete_db' denied by rule 'deny_delete'", + ), + ({"googleSearch": {}}, "Tool 'googleSearch' denied by rule 'deny_search'"), + ( + { + "type": "namespace", + "name": "inner", + "tools": [{"type": "function", "name": "noop"}], + "function": {"name": "delete_db"}, + }, + "Tool 'delete_db' denied by rule 'deny_delete'", + ), + ], + ids=["chat_shaped_member", "function_object_behind_another_name", "hosted_key_member", "nested_namespace"], + ) + async def test_pre_call_judges_a_namespace_member_by_what_a_provider_reads_from_it( + self, + member: dict[str, object], + detection_message: str, + on_disallowed_action: Literal["block", "rewrite"], + placement: Literal["tools", "functions"], + ) -> None: + guardrail = self._pre_call( + [ + {"id": "deny_delete", "tool_name": r"^delete_db$", "decision": "deny"}, + {"id": "deny_search", "tool_type": r"^googleSearch$", "decision": "deny"}, + ], + on_disallowed_action, + ) + weather = {"type": "function", "name": "get_weather"} + data = { + "model": "gemini-3", + "messages": [{"role": "user", "content": "hi"}], + placement: [{"type": "namespace", "name": "ops", "tools": [weather, member]}], + } + + if on_disallowed_action == "block": + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, "acompletion") + assert excinfo.value.detail["detection_message"] == detection_message + return + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result[placement] == [{"type": "namespace", "name": "ops", "tools": [weather]}] + + @pytest.mark.asyncio + async def test_pre_call_allows_a_chat_shaped_namespace_member_the_allowlist_names(self) -> None: + guardrail = self._pre_call( + [{"id": "allow_create", "tool_name": r"^github__create_issue$", "decision": "allow"}], + "block", + default_action="deny", + ) + namespace = { + "type": "namespace", + "name": "github", + "tools": [{"type": "function", "function": {"name": "create_issue"}}], + } + data = {"model": "gemini-3", "messages": [{"role": "user", "content": "hi"}], "tools": [namespace]} + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [namespace] + @pytest.mark.asyncio @pytest.mark.parametrize( ("tool_config", "rewritten_tool_config"), From 85817e64d8496b7887237d55fcd06fea2f21fc45 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Sat, 31 Oct 2026 00:16:13 -0700 Subject: [PATCH 21/39] fix(guardrails): judge a legacy functions entry as a function and relax a tool_choice in extra_body --- .../guardrail_hooks/tool_permission.py | 38 ++++++++++++---- .../guardrail_hooks/test_tool_permission.py | 45 +++++++++++++++++++ 2 files changed, 74 insertions(+), 9 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index ef13b45bce9..e99f10edfad 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -1062,7 +1062,7 @@ class ToolPermissionGuardrail(CustomGuardrail): request_tools.extend(map(_mcp_server_target, _request_list(request, "mcp_servers") or ())) for function in _request_list(request, "functions") or (): - request_tools.extend(self._get_request_tool_targets(function)) + request_tools.extend(self._legacy_function_targets(function)) listed_names: Final = frozenset(name for name, _ in request_tools) for forced_tool_name in ( @@ -1079,6 +1079,24 @@ class ToolPermissionGuardrail(CustomGuardrail): return request_tools + def _legacy_function_targets(self, function: object) -> tuple[_ToolTarget, ...]: + targets: Final = self._get_request_tool_targets(function) + as_functions: Final = tuple((name, "function") for name, _ in targets if name is not None) + return tuple(dict.fromkeys(targets + as_functions)) + + def _rewritten_extra_body( + self, + extra_body: Mapping[str, object], + kept_tools: tuple[object, ...] | None, + rewrite_choice: Callable[[object], object], + ) -> dict[str, object]: + choice: Final = extra_body.get("tool_choice") + return { + **extra_body, + **({"tools": list(kept_tools)} if kept_tools is not None else {}), + **({"tool_choice": rewrite_choice(choice)} if choice is not None else {}), + } + def _tool_names_in(self, tools: Sequence[object]) -> frozenset[str]: targets: Final = chain.from_iterable(self._get_request_tool_targets(tool) for tool in tools) return frozenset(name for name, _ in targets if name is not None) @@ -1189,11 +1207,6 @@ class ToolPermissionGuardrail(CustomGuardrail): extra_body: Final = _extra_body(request) extra_body_tools: Final = _extra_body_tools(request) kept_extra_body_tools: Final = None if extra_body_tools is None else kept_tool_list(extra_body_tools) - if extra_body is not None and kept_extra_body_tools is not None: - data["extra_body"] = { # rebind-ok: rewrite mode edits the request in place - **extra_body, - "tools": list(kept_extra_body_tools), - } functions: Final = _request_list(request, "functions") kept_functions: Final = None if functions is None else kept_tool_list(functions) @@ -1232,12 +1245,19 @@ class ToolPermissionGuardrail(CustomGuardrail): removed_types: Final = self._tool_types_in(sent_tools) - kept_types tools_remain: Final = bool(kept_sent_tools) or bool(kept_mcp_servers) + rewrite_choice: Final = partial( + self._rewritten_tool_choice, + removed_names=removed_names, + removed_types=removed_types, + tools_remain=tools_remain, + ) tool_choice: Final = _REQUEST_DATA.validate_python(data.get("tool_choice")) if tool_choice is not None: - rewritten_choice: Final = self._rewritten_tool_choice( - tool_choice, removed_names, removed_types, tools_remain + data["tool_choice"] = rewrite_choice(tool_choice) # rebind-ok: rewrite mode edits the request in place + if extra_body is not None and (kept_extra_body_tools is not None or "tool_choice" in extra_body): + data["extra_body"] = self._rewritten_extra_body( # rebind-ok: rewrite mode edits the request in place + extra_body, kept_extra_body_tools, rewrite_choice ) - data["tool_choice"] = rewritten_choice # rebind-ok: rewrite mode edits the request in place named_function_call: Final = self._get_named_function_call(data) if named_function_call in removed_names: diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 1227f137d1e..d772bf00108 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2024,6 +2024,25 @@ class TestToolPermissionGuardrailAnthropicMessages: assert message == "Tool 'Read' denied by rule 'deny_read'" assert rewritten["extra_body"] == {"tools": [bash], "seed": 7} + @pytest.mark.asyncio + async def test_rewrite_relaxes_an_extra_body_tool_choice_that_names_a_dropped_tool(self) -> None: + guardrail = self._pre_call([{"id": "deny_delete", "tool_name": r"^delete_db$", "decision": "deny"}], "rewrite") + weather = {"type": "function", "function": {"name": "get_weather"}} + delete_db = {"type": "function", "function": {"name": "delete_db"}} + data = { + "model": "m", + "messages": [{"role": "user", "content": "hi"}], + "extra_body": { + "tools": [weather, delete_db], + "tool_choice": {"type": "function", "function": {"name": "delete_db"}}, + "seed": 7, + }, + } + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["extra_body"] == {"tools": [weather], "tool_choice": "none", "seed": 7} + @pytest.mark.asyncio @pytest.mark.parametrize( "rule", @@ -2574,6 +2593,32 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["functions"] == [weather] + @pytest.mark.asyncio + @pytest.mark.parametrize("on_disallowed_action", ["block", "rewrite"]) + async def test_pre_call_judges_a_legacy_functions_entry_as_a_function_whatever_its_type( + self, on_disallowed_action: Literal["block", "rewrite"] + ) -> None: + guardrail = self._pre_call( + [{"id": "deny_delete", "tool_name": r"^delete_db$", "tool_type": r"^function$", "decision": "deny"}], + on_disallowed_action, + ) + weather = {"name": "get_weather"} + data = { + "model": "gemini-3", + "messages": [{"role": "user", "content": "hi"}], + "functions": [weather, {"type": "custom", "name": "delete_db"}], + } + + if on_disallowed_action == "block": + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, "acompletion") + assert excinfo.value.detail["detection_message"] == "Tool 'delete_db' denied by rule 'deny_delete'" + return + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["functions"] == [weather] + @pytest.mark.asyncio async def test_rewrite_keeps_an_allowed_function_whose_declaration_list_is_denied(self) -> None: guardrail = self._pre_call( From bb2dc14d911741cc73f8b4024401206c0e533a2b Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Sat, 31 Oct 2026 16:42:12 -0700 Subject: [PATCH 22/39] fix(gemini): keep a namespace whole when inlining its members would repeat a function name --- .../vertex_and_google_ai_studio_gemini.py | 12 +++++++++- ...test_vertex_and_google_ai_studio_gemini.py | 24 +++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index e2d0adcdad0..9b9fa624fb0 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -527,10 +527,20 @@ def _namespace_members_or_tool(tool: JsonValue) -> tuple[JsonValue, ...]: return tuple(map(_as_chat_tool, members)) if isinstance(members, list) else () +def _declared_function_name(tool: JsonValue) -> str | None: + if not isinstance(tool, dict): + return None + function: Final = tool.get("function") + name: Final = function.get("name") if isinstance(function, dict) else tool.get("name") + return name if isinstance(name, str) else None + + def _with_namespace_members_inlined(tools: JsonValue) -> JsonValue: if not isinstance(tools, list): return tools - return list(chain.from_iterable(map(_namespace_members_or_tool, tools))) + inlined: Final = tuple(chain.from_iterable(map(_namespace_members_or_tool, tools))) + names: Final = tuple(name for name in map(_declared_function_name, inlined) if name is not None) + return list(inlined) if len(names) == len(frozenset(names)) else tools class VertexAIBaseConfig: diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index 1026ac8ba95..55106c32c2c 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -1818,6 +1818,30 @@ def test_vertex_ai_map_tools_declares_a_namespace_member_like_the_same_chat_tool assert from_namespace == from_chat_tool +_GET_WEATHER = {"type": "function", "name": "get_weather", "parameters": {"type": "object", "properties": {}}} + + +@pytest.mark.parametrize( + "tools", + [ + [ + {"type": "namespace", "name": "forecast", "tools": [_GET_WEATHER]}, + {"type": "namespace", "name": "weather", "tools": [_GET_WEATHER]}, + ], + [ + {"type": "function", "function": {k: v for k, v in _GET_WEATHER.items() if k != "type"}}, + {"type": "namespace", "name": "weather", "tools": [_GET_WEATHER]}, + ], + ], + ids=["namespaces_share_a_member", "member_repeats_a_top_level_tool"], +) +def test_vertex_ai_map_tools_never_declares_a_function_name_twice_for_namespaces(tools: list[dict]) -> None: + mapped = VertexGeminiConfig().map_function(value=tools, optional_params={}) + + names = [declaration["name"] for declaration in mapped[0]["function_declarations"]] + assert len(names) == len(set(names)) == 2 + + def test_vertex_ai_map_tool_with_anyof(): """ Related issue: https://github.com/BerriAI/litellm/issues/11164 From 8f1a99d8535f0327a44f5952cf5555df4449f246 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Mon, 2 Nov 2026 14:47:33 -0800 Subject: [PATCH 23/39] fix(guardrails): judge a namespace member by every bare name that shares its qualified name --- .../guardrail_hooks/tool_permission.py | 20 +++++++++++++----- .../guardrail_hooks/test_tool_permission.py | 21 +++++++++++++++++++ 2 files changed, 36 insertions(+), 5 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index e99f10edfad..f11928e0234 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -661,13 +661,17 @@ class ToolPermissionGuardrail(CustomGuardrail): return bare if bare_rule.decision == "deny" else qualified def _check_target_permission( - self, target: _ToolTarget, bare_names: Mapping[str, str] + self, target: _ToolTarget, bare_names: Mapping[str, frozenset[str]] ) -> tuple[bool, str | None, str | None]: name, tool_type = target - bare_name: Final = bare_names.get(name) if name is not None else None - if name is None or bare_name is None: + candidates: Final = tuple(sorted(bare_names.get(name, ()))) if name is not None else () + if name is None or not candidates: return self._check_tool_permission(name, tool_type) - return self._check_tool_permission(self._deciding_member_name(name, bare_name, tool_type), tool_type) + results: Final = tuple( + self._check_tool_permission(self._deciding_member_name(name, bare_name, tool_type), tool_type) + for bare_name in candidates + ) + return next((result for result in results if not result[0]), results[0]) def _parse_tool_call_arguments( self, tool_call: ChatCompletionMessageToolCall @@ -1392,8 +1396,14 @@ class ToolPermissionGuardrail(CustomGuardrail): ) return data + member_names: Final = tuple( + chain.from_iterable(map(self._bare_member_names, _sent_tools(_REQUEST_DATA.validate_python(data)))) + ) bare_names: Final = MappingProxyType( - dict(chain.from_iterable(map(self._bare_member_names, _sent_tools(_REQUEST_DATA.validate_python(data))))) + { + qualified: frozenset(bare for key, bare in member_names if key == qualified) + for qualified, _ in member_names + } ) decisions: Final = tuple((target, self._check_target_permission(target, bare_names)) for target in new_tools) denied: Final = tuple( diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index d772bf00108..620aa57e527 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2214,6 +2214,27 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tools"] == [{"type": "namespace", "name": "functions", "tools": members[1:]}] + @pytest.mark.asyncio + @pytest.mark.parametrize("exec_first", [True, False], ids=["exec_namespace_first", "exec_namespace_last"]) + @pytest.mark.parametrize("on_disallowed_action", ["block", "rewrite"]) + async def test_pre_call_denies_a_bare_name_another_namespace_shares_a_qualified_name_with( + self, on_disallowed_action: Literal["block", "rewrite"], exec_first: bool + ) -> None: + guardrail = self._pre_call( + [{"id": "deny_exec", "tool_name": r"^exec$", "decision": "deny"}], on_disallowed_action + ) + exec_namespace = {"type": "namespace", "name": "mcp__ops", "tools": [{"type": "function", "name": "exec"}]} + twin_namespace = {"type": "namespace", "name": "mcp", "tools": [{"type": "function", "name": "ops__exec"}]} + tools = [exec_namespace, twin_namespace] if exec_first else [twin_namespace, exec_namespace] + data = {"model": "gpt-5", "input": "run date", "tools": tools} + + if on_disallowed_action == "rewrite": + assert (await self._run_pre_call(guardrail, data, "responses"))["tools"] == [] + return + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, "responses") + assert excinfo.value.detail["detection_message"] == "Tool 'exec' denied by rule 'deny_exec'" + @pytest.mark.asyncio @pytest.mark.parametrize("placement", ["tools", "functions"]) @pytest.mark.parametrize("on_disallowed_action", ["block", "rewrite"]) From 6ca82eccb2407f1710358008ed04e56f1be97aee Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Mon, 2 Nov 2026 15:53:15 -0800 Subject: [PATCH 24/39] fix(vertex_ai): declare a repeated namespace member name once instead of sending namespace names to Gemini --- .../vertex_and_google_ai_studio_gemini.py | 15 +++++++++++---- .../test_vertex_and_google_ai_studio_gemini.py | 18 +++++++++++++++--- 2 files changed, 26 insertions(+), 7 deletions(-) diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index 9b9fa624fb0..ac4d2253786 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -535,12 +535,19 @@ def _declared_function_name(tool: JsonValue) -> str | None: return name if isinstance(name, str) else None +def _is_namespace(tool: JsonValue) -> bool: + return isinstance(tool, dict) and tool.get("type") == "namespace" + + +def _first_declarations(tools: tuple[JsonValue, ...]) -> tuple[JsonValue, ...]: + names: Final = tuple(map(_declared_function_name, tools)) + return tuple(tool for index, tool in enumerate(tools) if names[index] is None or names[index] not in names[:index]) + + def _with_namespace_members_inlined(tools: JsonValue) -> JsonValue: - if not isinstance(tools, list): + if not isinstance(tools, list) or not any(map(_is_namespace, tools)): return tools - inlined: Final = tuple(chain.from_iterable(map(_namespace_members_or_tool, tools))) - names: Final = tuple(name for name in map(_declared_function_name, inlined) if name is not None) - return list(inlined) if len(names) == len(frozenset(names)) else tools + return list(_first_declarations(tuple(chain.from_iterable(map(_namespace_members_or_tool, tools))))) class VertexAIBaseConfig: diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index 55106c32c2c..e66cc635e28 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -1835,11 +1835,23 @@ _GET_WEATHER = {"type": "function", "name": "get_weather", "parameters": {"type" ], ids=["namespaces_share_a_member", "member_repeats_a_top_level_tool"], ) -def test_vertex_ai_map_tools_never_declares_a_function_name_twice_for_namespaces(tools: list[dict]) -> None: +def test_vertex_ai_map_tools_declares_a_repeated_member_name_once_and_never_a_namespace_name( + tools: list[dict], +) -> None: mapped = VertexGeminiConfig().map_function(value=tools, optional_params={}) - names = [declaration["name"] for declaration in mapped[0]["function_declarations"]] - assert len(names) == len(set(names)) == 2 + assert [declaration["name"] for declaration in mapped[0]["function_declarations"]] == ["get_weather"] + + +def test_vertex_ai_map_tools_keeps_repeated_chat_tools_when_no_namespace_is_sent() -> None: + function = {k: v for k, v in _GET_WEATHER.items() if k != "type"} + + mapped = VertexGeminiConfig().map_function( + value=[{"type": "function", "function": function}, {"type": "function", "function": function}], + optional_params={}, + ) + + assert [declaration["name"] for declaration in mapped[0]["function_declarations"]] == ["get_weather", "get_weather"] def test_vertex_ai_map_tool_with_anyof(): From 7591b8347e34b9c867cf2aceb78696866ccc97dc Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Mon, 2 Nov 2026 17:11:10 -0800 Subject: [PATCH 25/39] fix(guardrails): judge a tool_choice sent in extra_body like a top-level one A forced name only extra_body.tool_choice carried was never checked, so block mode let a denied name through to the provider --- .../guardrail_hooks/tool_permission.py | 6 +++++ .../guardrail_hooks/test_tool_permission.py | 25 +++++++++++++++++++ 2 files changed, 31 insertions(+) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index f11928e0234..ae03f09d3b9 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -241,6 +241,11 @@ def _extra_body_tools(data: object) -> Sequence[object] | None: return _request_list(_extra_body(data), "tools") +def _extra_body_tool_choice(data: object) -> object: + extra_body: Final = _extra_body(data) + return extra_body.get("tool_choice") if extra_body is not None else None + + def _sent_tools(data: object) -> tuple[object, ...]: return ( *(_request_list(data, "tools") or ()), @@ -1071,6 +1076,7 @@ class ToolPermissionGuardrail(CustomGuardrail): listed_names: Final = frozenset(name for name, _ in request_tools) for forced_tool_name in ( self._get_named_tool_choice(_REQUEST_DATA.validate_python(data.get("tool_choice"))), + self._get_named_tool_choice(_extra_body_tool_choice(request)), self._get_named_function_call(data), ): if forced_tool_name is not None and forced_tool_name not in listed_names: diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 620aa57e527..de4b1e31748 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2043,6 +2043,31 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["extra_body"] == {"tools": [weather], "tool_choice": "none", "seed": 7} + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("call_type", "tool_choice"), + [ + ("acompletion", {"type": "function", "function": {"name": "Read"}}), + ("responses", {"type": "function", "name": "Read"}), + ], + ids=["chat", "responses"], + ) + async def test_pre_call_checks_an_extra_body_tool_choice_that_names_an_unlisted_tool( + self, call_type: CallTypesLiteral, tool_choice: dict[str, object] + ) -> None: + request = { + "model": "m", + "messages": [{"role": "user", "content": "hi"}], + "input": "hi", + "tools": [{"type": "function", "name": "Bash"}], + "extra_body": {"tool_choice": tool_choice, "seed": 7}, + } + + message, rewritten = await self._blocked_and_rewritten(self.rules, request, call_type) + + assert message == "Tool 'Read' denied by rule 'deny_read'" + assert rewritten["extra_body"] == {"tool_choice": "none", "seed": 7} + @pytest.mark.asyncio @pytest.mark.parametrize( "rule", From 62afcc6c884809087e1cf38a0226609d72d4f0cd Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Mon, 2 Nov 2026 21:23:57 -0800 Subject: [PATCH 26/39] fix(guardrails): judge a Gemini namespace member returned by its bare name and force a named namespace's members --- .../vertex_and_google_ai_studio_gemini.py | 20 +- .../guardrail_hooks/tool_permission.py | 57 ++++-- ...test_vertex_and_google_ai_studio_gemini.py | 41 +++- .../guardrail_hooks/test_tool_permission.py | 183 ++++++++++++------ 4 files changed, 223 insertions(+), 78 deletions(-) diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index ac4d2253786..d68a8aefa88 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -550,6 +550,17 @@ def _with_namespace_members_inlined(tools: JsonValue) -> JsonValue: return list(_first_declarations(tuple(chain.from_iterable(map(_namespace_members_or_tool, tools))))) +def _forced_function_names(name: str, tools: JsonValue) -> tuple[str, ...]: + candidates: Final = tools if isinstance(tools, list) else [] + named: Final = next((tool for tool in candidates if _is_namespace(tool) and _member_name_of(tool) == name), None) + members: Final = map(_declared_function_name, _namespace_members_or_tool(named)) if named is not None else () + return tuple(dict.fromkeys(member for member in members if member is not None)) or (name,) + + +def _member_name_of(tool: JsonValue) -> JsonValue: + return tool.get("name") if isinstance(tool, dict) else None + + class VertexAIBaseConfig: def get_mapped_special_auth_params(self) -> dict: """ @@ -819,7 +830,7 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig): return supported_params - def map_tool_choice_values(self, model: str, tool_choice: str | dict) -> ToolConfig | None: + def map_tool_choice_values(self, model: str, tool_choice: str | dict, tools: JsonValue = None) -> ToolConfig | None: if tool_choice == "none": return ToolConfig(functionCallingConfig=FunctionCallingConfig(mode="NONE")) elif tool_choice == "required": @@ -829,7 +840,11 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig): elif isinstance(tool_choice, dict): # only supported for anthropic + mistral models - https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolChoice.html name: Final = tool_choice.get("function", {}).get("name", "") - return ToolConfig(functionCallingConfig=FunctionCallingConfig(mode="ANY", allowed_function_names=[name])) + return ToolConfig( + functionCallingConfig=FunctionCallingConfig( + mode="ANY", allowed_function_names=list(_forced_function_names(name, tools)) + ) + ) else: raise litellm.utils.UnsupportedParamsError( message=f"VertexAI doesn't support tool_choice={tool_choice}. Supported tool_choice values=['auto', 'required', json object]. To drop it from the call, set `litellm.drop_params = True.", @@ -1743,6 +1758,7 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig): _tool_choice_value = self.map_tool_choice_values( model=model, tool_choice=value, + tools=non_default_params.get("tools", non_default_params.get("functions")), ) if _tool_choice_value is not None: optional_params["tool_choice"] = _tool_choice_value diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index ae03f09d3b9..8b8e1efef1e 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -769,9 +769,9 @@ class ToolPermissionGuardrail(CustomGuardrail): return True, None def _get_permission_for_tool_call( - self, tool_call: ChatCompletionMessageToolCall + self, tool_call: ChatCompletionMessageToolCall, judged_name: str | None = None ) -> tuple[bool, str | None, str | None]: - tool_name: Final = tool_call.function.name if tool_call.function else None + tool_name: Final = judged_name or (tool_call.function.name if tool_call.function else None) tool_type: Final = getattr(tool_call, "type", None) if not tool_name and not tool_type: return self.default_action == "allow", None, None @@ -914,10 +914,39 @@ class ToolPermissionGuardrail(CustomGuardrail): tool_call for block in content if (tool_call := self._anthropic_tool_use_to_tool_call(block)) is not None ) + def _returned_call_names(self, data: Mapping[str, object]) -> Mapping[str, tuple[str, ...]]: + member_names: Final = tuple( + chain.from_iterable(map(self._bare_member_names, _sent_tools(_REQUEST_DATA.validate_python(data)))) + ) + if not member_names: + return MappingProxyType({}) + listed: Final = frozenset(name for name, _ in self._collect_request_tools(data) if name is not None) + return MappingProxyType( + {bare: self._judged_names_of_returned_call(bare, member_names, listed) for _, bare in member_names} + ) + + def _judged_names_of_returned_call( + self, bare: str, member_names: tuple[tuple[str, str], ...], listed: frozenset[str] + ) -> tuple[str, ...]: + qualified: Final = ( + self._deciding_member_name(name, bare, "function") for name, key in member_names if key == bare + ) + return tuple(dict.fromkeys((*qualified, *((bare,) if bare in listed else ())))) + + def _judge_tool_call( + self, tool_call: ChatCompletionMessageToolCall, judged_names: Mapping[str, tuple[str, ...]] + ) -> tuple[bool, str | None, str | None]: + returned_name: Final = tool_call.function.name if tool_call.function else None + names: Final = judged_names.get(returned_name, ()) if returned_name is not None else () + if not names: + return self._get_permission_for_tool_call(tool_call) + results: Final = tuple(self._get_permission_for_tool_call(tool_call, name) for name in names) + return next((result for result in results if not result[0]), results[0]) + def _evaluate_tool_calls( - self, tool_calls: Sequence[ChatCompletionMessageToolCall] + self, tool_calls: Sequence[ChatCompletionMessageToolCall], judged_names: Mapping[str, tuple[str, ...]] ) -> tuple[tuple[ChatCompletionMessageToolCall, PermissionError], ...]: - checked: Final = tuple((tool_call, *self._get_permission_for_tool_call(tool_call)) for tool_call in tool_calls) + checked: Final = tuple((tool_call, *self._judge_tool_call(tool_call, judged_names)) for tool_call in tool_calls) for _tool_call, is_allowed, _rule_id, message in checked: if not is_allowed and message is not None: @@ -1052,7 +1081,7 @@ class ToolPermissionGuardrail(CustomGuardrail): nested_name: Final = _non_empty_string(nested.get("name")) if nested is not None else None return nested_name or _non_empty_string(choice.get("name")) - def _get_named_function_call(self, data: dict) -> str | None: + def _get_named_function_call(self, data: Mapping[str, object]) -> str | None: function_call: Final = data.get("function_call") if not function_call or function_call in ("auto", "none"): return None @@ -1060,7 +1089,7 @@ class ToolPermissionGuardrail(CustomGuardrail): return function_call return self._get_mapping_value(function_call, "name") - def _collect_request_tools(self, data: dict) -> list[_ToolTarget]: + def _collect_request_tools(self, data: Mapping[str, object]) -> list[_ToolTarget]: request_tools: Final[list[_ToolTarget]] = [] request: Final = _REQUEST_DATA.validate_python(data) @@ -1476,7 +1505,7 @@ class ToolPermissionGuardrail(CustomGuardrail): verbose_proxy_logger.debug("Tool Permission Guardrail: Found %s tool calls", len(tool_calls)) - denied_tools: Final = self._evaluate_tool_calls(tool_calls) + denied_tools: Final = self._evaluate_tool_calls(tool_calls, self._returned_call_names(data)) if not denied_tools: verbose_proxy_logger.debug("Tool Permission Guardrail Post-Call Hook: All tools allowed") @@ -1500,7 +1529,7 @@ class ToolPermissionGuardrail(CustomGuardrail): Args: user_api_key_dict: User API key information (unused but required by interface) response: The model response to check - request_data: The model request (unused but required by interface) + request_data: The model request """ # Import here to avoid circular imports @@ -1517,7 +1546,9 @@ class ToolPermissionGuardrail(CustomGuardrail): stream_chunk_builder(chunks=all_chunks) if not is_raw_sse_stream(all_chunks) else None ) if isinstance(assembled_model_response, ModelResponse): - denied_tools = self._check_assembled_stream(assembled_model_response) + denied_tools = self._check_assembled_stream( + assembled_model_response, self._returned_call_names(request_data) + ) if denied_tools: self._modify_response_with_permission_errors(assembled_model_response, denied_tools) @@ -1541,7 +1572,9 @@ class ToolPermissionGuardrail(CustomGuardrail): yield chunk return - anthropic_denials: Final = self._check_assembled_stream(anthropic_response) + anthropic_denials: Final = self._check_assembled_stream( + anthropic_response, self._returned_call_names(request_data) + ) if not anthropic_denials: for chunk in all_chunks: yield chunk @@ -1552,7 +1585,7 @@ class ToolPermissionGuardrail(CustomGuardrail): yield sse_chunk def _check_assembled_stream( - self, assembled: ModelResponse + self, assembled: ModelResponse, judged_names: Mapping[str, tuple[str, ...]] ) -> tuple[tuple[ChatCompletionMessageToolCall, PermissionError], ...]: verbose_proxy_logger.debug("Tool Permission Guardrail: Checking response") tool_calls: Final = self._extract_tool_calls_from_response(assembled) @@ -1560,7 +1593,7 @@ class ToolPermissionGuardrail(CustomGuardrail): verbose_proxy_logger.debug("Tool Permission Guardrail: No tool uses found") return () verbose_proxy_logger.debug("Tool Permission Guardrail: Found %s tool calls", len(tool_calls)) - denied_tools: Final = self._evaluate_tool_calls(tool_calls) + denied_tools: Final = self._evaluate_tool_calls(tool_calls, judged_names) if not denied_tools: verbose_proxy_logger.debug("Tool Permission Guardrail Post-Call Hook: All tools allowed") return denied_tools diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index e66cc635e28..a26bbf618b3 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -328,7 +328,9 @@ def test_chat_audio_drop_params_keeps_every_voice_config_field_gemini_accepts(sp def test_chat_audio_reads_snake_case_wrapper_beside_null_camel_case_wrapper(): mapped: Final = VertexGeminiConfig().map_openai_params( - non_default_params={"audio": {"format": "pcm16", "speechConfig": None, "speech_config": {"voice_name": "Kore"}}}, + non_default_params={ + "audio": {"format": "pcm16", "speechConfig": None, "speech_config": {"voice_name": "Kore"}} + }, optional_params={}, model="gemini-2.5-flash-preview-tts", drop_params=False, @@ -1854,6 +1856,35 @@ def test_vertex_ai_map_tools_keeps_repeated_chat_tools_when_no_namespace_is_sent assert [declaration["name"] for declaration in mapped[0]["function_declarations"]] == ["get_weather", "get_weather"] +@pytest.mark.parametrize( + ("forced_name", "allowed_function_names"), + [("github", ["create_issue", "close_issue"]), ("close_issue", ["close_issue"])], + ids=["names_the_namespace", "names_a_member"], +) +def test_vertex_ai_tool_choice_forces_only_functions_gemini_is_sent( + forced_name: str, allowed_function_names: list[str] +) -> None: + namespace = { + "type": "namespace", + "name": "github", + "tools": [{"type": "function", "name": "create_issue"}, {"type": "function", "name": "close_issue"}], + } + + mapped = VertexGeminiConfig().map_openai_params( + non_default_params={ + "tools": [namespace], + "tool_choice": {"type": "function", "function": {"name": forced_name}}, + }, + optional_params={}, + model="gemini-3.8-flash", + drop_params=False, + ) + + declared = [declaration["name"] for declaration in mapped["tools"][0]["function_declarations"]] + assert mapped["tool_choice"]["functionCallingConfig"]["allowed_function_names"] == allowed_function_names + assert set(allowed_function_names) <= set(declared) + + def test_vertex_ai_map_tool_with_anyof(): """ Related issue: https://github.com/BerriAI/litellm/issues/11164 @@ -3539,9 +3570,7 @@ async def test_vertex_ai_streaming_bad_request_is_not_wrapped(): async def dispatch_failure_handlers(self, *args, **kwargs): return None - async def dispatch_attempt_failure_handlers( - self, exception: Exception, traceback_exception: str - ) -> None: + async def dispatch_attempt_failure_handlers(self, exception: Exception, traceback_exception: str) -> None: return None def attempt_scoped_copy(self) -> "DummyLogging": @@ -3671,9 +3700,7 @@ def test_grounding_annotations_preserve_all_web_sources(indices: list[int], expe ] metadata: Final = { "groundingChunks": chunks, - "groundingSupports": [ - {"segment": {"startIndex": 4, "endIndex": 11}, "groundingChunkIndices": indices} - ], + "groundingSupports": [{"segment": {"startIndex": 4, "endIndex": 11}, "groundingChunkIndices": indices}], } annotations: Final = VertexGeminiConfig._convert_grounding_metadata_to_annotations([metadata], "The passage") expected: Final = [ diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index de4b1e31748..06e6491c37c 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -75,9 +75,7 @@ class TestToolPermissionGuardrail: assert len(self.guardrail.rules) == 5 assert self.guardrail.default_action == "deny" assert self.guardrail.on_disallowed_action == "block" - assert GuardrailEventHooks.post_call in ( - self.guardrail.supported_event_hooks or [] - ) + assert GuardrailEventHooks.post_call in (self.guardrail.supported_event_hooks or []) def test_matches_regex_helper(self): pattern = re.compile(r"^Read$") @@ -132,7 +130,7 @@ class TestToolPermissionGuardrail: assert rule_id is None def test_rule_requires_name_or_type(self): - with pytest.raises(ValueError, match='validation error for ToolPermissionRule'): + with pytest.raises(ValueError, match="validation error for ToolPermissionRule"): ToolPermissionGuardrail( guardrail_name="invalid-rule", rules=[{"id": "no_target", "decision": "allow"}], @@ -170,9 +168,7 @@ class TestToolPermissionGuardrail: assert rule_id == "allow_bash" assert "allowed" in (msg or "") - is_allowed, rule_id, _ = self.guardrail._check_tool_permission( - "mcp__github_add_issue_comment" - ) + is_allowed, rule_id, _ = self.guardrail._check_tool_permission("mcp__github_add_issue_comment") assert is_allowed is True assert rule_id == "allow_github" @@ -469,6 +465,66 @@ class TestToolPermissionGuardrail: ] assert kept == [[], ["Read"]] + @pytest.mark.asyncio + @pytest.mark.parametrize("stream", [False, True], ids=["non_streaming", "streaming"]) + async def test_post_call_judges_a_returned_namespace_member_by_its_qualified_name(self, stream: bool) -> None: + guardrail = ToolPermissionGuardrail( + guardrail_name="post-mcp", + rules=[{"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}], + default_action="allow", + on_disallowed_action="rewrite", + event_hook=GuardrailEventHooks.post_call, + ) + namespace = {"type": "namespace", "name": "mcp__weather", "tools": [{"type": "function", "name": "lookup"}]} + data = {"guardrails": ["post-mcp"], "tools": [namespace]} + function = Function(name="lookup", arguments='{"city": "Paris"}') + + if stream: + + async def _stream(): + yield ModelResponseStream( + choices=[ + StreamingChoices( + index=0, + delta=Delta( + tool_calls=[ + ChatCompletionDeltaToolCall( + id="call_lookup", index=0, type="function", function=function + ) + ] + ), + ) + ] + ) + + chunks = [ + chunk + async for chunk in guardrail.async_post_call_streaming_iterator_hook( + user_api_key_dict=UserAPIKeyAuth(), response=_stream(), request_data=data + ) + ] + deltas = [choice.delta for choice in chain.from_iterable(chunk.choices for chunk in chunks)] + called = [call.function.name for call in chain.from_iterable(delta.tool_calls or () for delta in deltas)] + content = "".join(delta.content or "" for delta in deltas) + else: + response = ModelResponse( + choices=[ + Choices( + finish_reason="tool_calls", + message={"tool_calls": [{"id": "call_lookup", "type": "function", "function": function}]}, + ) + ] + ) + await guardrail.async_post_call_success_hook( + data=data, user_api_key_dict=UserAPIKeyAuth(), response=response + ) + message = response.choices[0].message + called = [call.function.name for call in message.tool_calls or ()] + content = message.content or "" + + assert called == [] + assert "Tool 'mcp__weather__lookup' denied by rule 'deny_mcp'" in content + @pytest.mark.asyncio async def test_async_post_call_success_hook_missing_arguments_blocks_param_rule( self, @@ -511,9 +567,7 @@ class TestToolPermissionGuardrail: '["owner@berri.ai"]', ], ) - async def test_async_post_call_success_hook_malformed_arguments_blocks_param_rule( - self, arguments - ): + async def test_async_post_call_success_hook_malformed_arguments_blocks_param_rule(self, arguments): guardrail = ToolPermissionGuardrail( guardrail_name="mail-guardrail", rules=[ @@ -888,9 +942,7 @@ class TestToolPermissionGuardrail: async def _fake_stream(): yield text_chunk - assembled = ModelResponse( - choices=[Choices(message={"content": "Hello, world!"})] - ) + assembled = ModelResponse(choices=[Choices(message={"content": "Hello, world!"})]) with patch("litellm.main.stream_chunk_builder", return_value=assembled): chunks = [] @@ -902,12 +954,10 @@ class TestToolPermissionGuardrail: chunks.append(chunk) assert len(chunks) >= 1, ( - "Hook must yield at least one chunk for plain-text responses; " - "got none — bare return bug" + "Hook must yield at least one chunk for plain-text responses; got none — bare return bug" ) assert chunks[0].choices[0].delta.content == "Hello, world!", ( - "Hook must preserve the original response content; " - f"got: {chunks[0].choices[0].delta.content!r}" + f"Hook must preserve the original response content; got: {chunks[0].choices[0].delta.content!r}" ) @pytest.mark.asyncio @@ -952,12 +1002,8 @@ class TestToolPermissionGuardrail: def test_modify_response_with_permission_errors(self): # Setup a response with one tool_call - tool_call = ChatCompletionMessageToolCall( - function={"name": "Read", "arguments": "{}"}, id="call_123" - ) - response = ModelResponse( - choices=[Choices(message={"tool_calls": [tool_call], "content": ""})] - ) + tool_call = ChatCompletionMessageToolCall(function={"name": "Read", "arguments": "{}"}, id="call_123") + response = ModelResponse(choices=[Choices(message={"tool_calls": [tool_call], "content": ""})]) # Denied tools tuple of (tool_call, PermissionError) denied_tools = [ @@ -989,7 +1035,9 @@ class TestToolPermissionGuardrail: denied_tools = [ ( tool_call, - PermissionError(tool_name="Read", rule_id="deny_read", message="Tool 'Read' denied by rule 'deny_read'"), + PermissionError( + tool_name="Read", rule_id="deny_read", message="Tool 'Read' denied by rule 'deny_read'" + ), ) ] @@ -1035,7 +1083,6 @@ class TestToolPermissionGuardrail: assert isinstance(choice.message.content, str) assert "Permission denied" in choice.message.content - def test_modify_response_with_permission_errors_keeps_custom_tool_call_in_another_choice(self): denied_call = ChatCompletionMessageToolCall( id="call_bash", type="function", function=Function(name="Bash", arguments="{}") @@ -1052,7 +1099,9 @@ class TestToolPermissionGuardrail: denied_tools = [ ( denied_call, - PermissionError(tool_name="Bash", rule_id="deny_bash", message="Tool 'Bash' denied by rule 'deny_bash'"), + PermissionError( + tool_name="Bash", rule_id="deny_bash", message="Tool 'Bash' denied by rule 'deny_bash'" + ), ) ] @@ -1065,6 +1114,7 @@ class TestToolPermissionGuardrail: ] assert kept == [[], ["call_patch"]] + class TestToolPermissionGuardrailIntegration: """Integration tests for Tool Permission Guardrail""" @@ -1194,10 +1244,7 @@ class TestToolPermissionGuardrailInMemoryUpdate: on_disallowed_action="block", ) # No pattern yet: any Bash command is allowed. - assert ( - guardrail._get_permission_for_tool_call(self._bash("echo blockme"))[0] - is True - ) + assert guardrail._get_permission_for_tool_call(self._bash("echo blockme"))[0] is True guardrail.update_in_memory_litellm_params( LitellmParams( @@ -1210,9 +1257,7 @@ class TestToolPermissionGuardrailInMemoryUpdate: "id": "native-bash", "tool_name": r"^Bash$", "decision": "allow", - "allowed_param_patterns": { - "command": r"^(?!(echo blockme)$).*$" - }, + "allowed_param_patterns": {"command": r"^(?!(echo blockme)$).*$"}, } ], ) @@ -1220,13 +1265,8 @@ class TestToolPermissionGuardrailInMemoryUpdate: # The compiled map must be rebuilt, and enforcement must reflect it. assert "command" in guardrail._compiled_rule_patterns.get("native-bash", {}) - assert ( - guardrail._get_permission_for_tool_call(self._bash("echo blockme"))[0] - is False - ) - assert ( - guardrail._get_permission_for_tool_call(self._bash("echo hello"))[0] is True - ) + assert guardrail._get_permission_for_tool_call(self._bash("echo blockme"))[0] is False + assert guardrail._get_permission_for_tool_call(self._bash("echo hello"))[0] is True def test_update_in_memory_recompiles_tool_name_target(self): guardrail = ToolPermissionGuardrail( @@ -1281,10 +1321,7 @@ class TestToolPermissionGuardrailInMemoryUpdate: assert len(guardrail.rules) == 1 assert "command" in guardrail._compiled_rule_patterns.get("native-bash", {}) - assert ( - guardrail._get_permission_for_tool_call(self._bash("echo blockme"))[0] - is False - ) + assert guardrail._get_permission_for_tool_call(self._bash("echo blockme"))[0] is False def test_update_in_memory_rejects_invalid_regex_and_keeps_previous_rules(self): """Regression: a live update whose rules contain an invalid regex must be @@ -1616,7 +1653,9 @@ class TestToolPermissionGuardrailAnthropicMessages: @pytest.mark.asyncio async def test_pre_call_lets_a_type_rule_allow_a_gemini_tool_by_its_key(self) -> None: guardrail = self._pre_call( - [{"id": "allow_search", "tool_type": r"^googleSearch$", "decision": "allow"}], "block", default_action="deny" + [{"id": "allow_search", "tool_type": r"^googleSearch$", "decision": "allow"}], + "block", + default_action="deny", ) data = {"model": "gemini-3", "messages": [{"role": "user", "content": "hi"}], "tools": [{"googleSearch": {}}]} @@ -1642,7 +1681,10 @@ class TestToolPermissionGuardrailAnthropicMessages: lookup = {"type": "function", "name": "mcp__weather__lookup"} data = { "model": "m", - "input": [{"role": "user", "content": "hi"}, {"type": "tool_search_output", "tools": [get_weather, lookup]}], + "input": [ + {"role": "user", "content": "hi"}, + {"type": "tool_search_output", "tools": [get_weather, lookup]}, + ], "tools": [{"functionDeclarations": [{"name": "get_weather"}, {"name": "mcp__weather__lookup"}]}], } @@ -1762,7 +1804,10 @@ class TestToolPermissionGuardrailAnthropicMessages: lookup = {"type": "function", "name": "mcp__weather__lookup"} data = { "model": "m", - "input": [{"role": "user", "content": "hi"}, {"type": "tool_search_output", "tools": [get_weather, lookup]}], + "input": [ + {"role": "user", "content": "hi"}, + {"type": "tool_search_output", "tools": [get_weather, lookup]}, + ], "tools": [lookup], "tool_choice": tool_choice, } @@ -1897,7 +1942,12 @@ class TestToolPermissionGuardrailAnthropicMessages: @pytest.mark.parametrize( ("tool", "tool_choice", "call_type", "allowed_tool_type"), [ - ({"type": "custom", "name": "apply_patch"}, {"type": "custom", "name": "apply_patch"}, "responses", r"^custom$"), + ( + {"type": "custom", "name": "apply_patch"}, + {"type": "custom", "name": "apply_patch"}, + "responses", + r"^custom$", + ), ( {"type": "web_search_20250305", "name": "web_search"}, {"type": "tool", "name": "web_search"}, @@ -2872,16 +2922,31 @@ class TestToolPermissionGuardrailAnthropicMessages: def _sse_chunks(self, tool_name, tool_id="tu_1"): events = [ - {"type": "message_start", "message": {"id": "msg_1", "type": "message", "role": "assistant", - "model": "claude-sonnet-4-5", "content": [], "stop_reason": None, - "usage": {"input_tokens": 10, "output_tokens": 0}}}, + { + "type": "message_start", + "message": { + "id": "msg_1", + "type": "message", + "role": "assistant", + "model": "claude-sonnet-4-5", + "content": [], + "stop_reason": None, + "usage": {"input_tokens": 10, "output_tokens": 0}, + }, + }, {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}, {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "working"}}, {"type": "content_block_stop", "index": 0}, - {"type": "content_block_start", "index": 1, - "content_block": {"type": "tool_use", "id": tool_id, "name": tool_name, "input": {}}}, - {"type": "content_block_delta", "index": 1, - "delta": {"type": "input_json_delta", "partial_json": '{"command": "ls"}'}}, + { + "type": "content_block_start", + "index": 1, + "content_block": {"type": "tool_use", "id": tool_id, "name": tool_name, "input": {}}, + }, + { + "type": "content_block_delta", + "index": 1, + "delta": {"type": "input_json_delta", "partial_json": '{"command": "ls"}'}, + }, {"type": "content_block_stop", "index": 1}, {"type": "message_delta", "delta": {"stop_reason": "tool_use"}, "usage": {"output_tokens": 5}}, {"type": "message_stop"}, @@ -2945,8 +3010,12 @@ class TestToolPermissionGuardrailAnthropicMessages: for line in body.splitlines() if line.startswith("data: ") and json.loads(line[6:]).get("type") == "message_start" )["message"] - assert message_start["id"].startswith("chatcmpl-"), "the rewritten stream must not adopt the upstream message id" - assert message_start["model"] == "claude-sonnet-4-5", "the rewritten stream reports the model the upstream served" + assert message_start["id"].startswith("chatcmpl-"), ( + "the rewritten stream must not adopt the upstream message id" + ) + assert message_start["model"] == "claude-sonnet-4-5", ( + "the rewritten stream reports the model the upstream served" + ) @pytest.mark.asyncio async def test_rewrite_mode_keeps_the_allowed_tool_use_verdict_with_its_explanation(self): From fb6966eac8b0a30e2a4984e71d756b9b26eb2319 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Mon, 2 Nov 2026 21:30:21 -0800 Subject: [PATCH 27/39] test: keep formatter churn out of the tool_permission and Gemini test files --- ...test_vertex_and_google_ai_studio_gemini.py | 12 +- .../guardrail_hooks/test_tool_permission.py | 123 ++++++++---------- 2 files changed, 64 insertions(+), 71 deletions(-) diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index a26bbf618b3..54b45939ece 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -328,9 +328,7 @@ def test_chat_audio_drop_params_keeps_every_voice_config_field_gemini_accepts(sp def test_chat_audio_reads_snake_case_wrapper_beside_null_camel_case_wrapper(): mapped: Final = VertexGeminiConfig().map_openai_params( - non_default_params={ - "audio": {"format": "pcm16", "speechConfig": None, "speech_config": {"voice_name": "Kore"}} - }, + non_default_params={"audio": {"format": "pcm16", "speechConfig": None, "speech_config": {"voice_name": "Kore"}}}, optional_params={}, model="gemini-2.5-flash-preview-tts", drop_params=False, @@ -3570,7 +3568,9 @@ async def test_vertex_ai_streaming_bad_request_is_not_wrapped(): async def dispatch_failure_handlers(self, *args, **kwargs): return None - async def dispatch_attempt_failure_handlers(self, exception: Exception, traceback_exception: str) -> None: + async def dispatch_attempt_failure_handlers( + self, exception: Exception, traceback_exception: str + ) -> None: return None def attempt_scoped_copy(self) -> "DummyLogging": @@ -3700,7 +3700,9 @@ def test_grounding_annotations_preserve_all_web_sources(indices: list[int], expe ] metadata: Final = { "groundingChunks": chunks, - "groundingSupports": [{"segment": {"startIndex": 4, "endIndex": 11}, "groundingChunkIndices": indices}], + "groundingSupports": [ + {"segment": {"startIndex": 4, "endIndex": 11}, "groundingChunkIndices": indices} + ], } annotations: Final = VertexGeminiConfig._convert_grounding_metadata_to_annotations([metadata], "The passage") expected: Final = [ diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 06e6491c37c..5c3d9982ff5 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -75,7 +75,9 @@ class TestToolPermissionGuardrail: assert len(self.guardrail.rules) == 5 assert self.guardrail.default_action == "deny" assert self.guardrail.on_disallowed_action == "block" - assert GuardrailEventHooks.post_call in (self.guardrail.supported_event_hooks or []) + assert GuardrailEventHooks.post_call in ( + self.guardrail.supported_event_hooks or [] + ) def test_matches_regex_helper(self): pattern = re.compile(r"^Read$") @@ -130,7 +132,7 @@ class TestToolPermissionGuardrail: assert rule_id is None def test_rule_requires_name_or_type(self): - with pytest.raises(ValueError, match="validation error for ToolPermissionRule"): + with pytest.raises(ValueError, match='validation error for ToolPermissionRule'): ToolPermissionGuardrail( guardrail_name="invalid-rule", rules=[{"id": "no_target", "decision": "allow"}], @@ -168,7 +170,9 @@ class TestToolPermissionGuardrail: assert rule_id == "allow_bash" assert "allowed" in (msg or "") - is_allowed, rule_id, _ = self.guardrail._check_tool_permission("mcp__github_add_issue_comment") + is_allowed, rule_id, _ = self.guardrail._check_tool_permission( + "mcp__github_add_issue_comment" + ) assert is_allowed is True assert rule_id == "allow_github" @@ -567,7 +571,9 @@ class TestToolPermissionGuardrail: '["owner@berri.ai"]', ], ) - async def test_async_post_call_success_hook_malformed_arguments_blocks_param_rule(self, arguments): + async def test_async_post_call_success_hook_malformed_arguments_blocks_param_rule( + self, arguments + ): guardrail = ToolPermissionGuardrail( guardrail_name="mail-guardrail", rules=[ @@ -942,7 +948,9 @@ class TestToolPermissionGuardrail: async def _fake_stream(): yield text_chunk - assembled = ModelResponse(choices=[Choices(message={"content": "Hello, world!"})]) + assembled = ModelResponse( + choices=[Choices(message={"content": "Hello, world!"})] + ) with patch("litellm.main.stream_chunk_builder", return_value=assembled): chunks = [] @@ -954,10 +962,12 @@ class TestToolPermissionGuardrail: chunks.append(chunk) assert len(chunks) >= 1, ( - "Hook must yield at least one chunk for plain-text responses; got none — bare return bug" + "Hook must yield at least one chunk for plain-text responses; " + "got none — bare return bug" ) assert chunks[0].choices[0].delta.content == "Hello, world!", ( - f"Hook must preserve the original response content; got: {chunks[0].choices[0].delta.content!r}" + "Hook must preserve the original response content; " + f"got: {chunks[0].choices[0].delta.content!r}" ) @pytest.mark.asyncio @@ -1002,8 +1012,12 @@ class TestToolPermissionGuardrail: def test_modify_response_with_permission_errors(self): # Setup a response with one tool_call - tool_call = ChatCompletionMessageToolCall(function={"name": "Read", "arguments": "{}"}, id="call_123") - response = ModelResponse(choices=[Choices(message={"tool_calls": [tool_call], "content": ""})]) + tool_call = ChatCompletionMessageToolCall( + function={"name": "Read", "arguments": "{}"}, id="call_123" + ) + response = ModelResponse( + choices=[Choices(message={"tool_calls": [tool_call], "content": ""})] + ) # Denied tools tuple of (tool_call, PermissionError) denied_tools = [ @@ -1035,9 +1049,7 @@ class TestToolPermissionGuardrail: denied_tools = [ ( tool_call, - PermissionError( - tool_name="Read", rule_id="deny_read", message="Tool 'Read' denied by rule 'deny_read'" - ), + PermissionError(tool_name="Read", rule_id="deny_read", message="Tool 'Read' denied by rule 'deny_read'"), ) ] @@ -1083,6 +1095,7 @@ class TestToolPermissionGuardrail: assert isinstance(choice.message.content, str) assert "Permission denied" in choice.message.content + def test_modify_response_with_permission_errors_keeps_custom_tool_call_in_another_choice(self): denied_call = ChatCompletionMessageToolCall( id="call_bash", type="function", function=Function(name="Bash", arguments="{}") @@ -1099,9 +1112,7 @@ class TestToolPermissionGuardrail: denied_tools = [ ( denied_call, - PermissionError( - tool_name="Bash", rule_id="deny_bash", message="Tool 'Bash' denied by rule 'deny_bash'" - ), + PermissionError(tool_name="Bash", rule_id="deny_bash", message="Tool 'Bash' denied by rule 'deny_bash'"), ) ] @@ -1114,7 +1125,6 @@ class TestToolPermissionGuardrail: ] assert kept == [[], ["call_patch"]] - class TestToolPermissionGuardrailIntegration: """Integration tests for Tool Permission Guardrail""" @@ -1244,7 +1254,10 @@ class TestToolPermissionGuardrailInMemoryUpdate: on_disallowed_action="block", ) # No pattern yet: any Bash command is allowed. - assert guardrail._get_permission_for_tool_call(self._bash("echo blockme"))[0] is True + assert ( + guardrail._get_permission_for_tool_call(self._bash("echo blockme"))[0] + is True + ) guardrail.update_in_memory_litellm_params( LitellmParams( @@ -1257,7 +1270,9 @@ class TestToolPermissionGuardrailInMemoryUpdate: "id": "native-bash", "tool_name": r"^Bash$", "decision": "allow", - "allowed_param_patterns": {"command": r"^(?!(echo blockme)$).*$"}, + "allowed_param_patterns": { + "command": r"^(?!(echo blockme)$).*$" + }, } ], ) @@ -1265,8 +1280,13 @@ class TestToolPermissionGuardrailInMemoryUpdate: # The compiled map must be rebuilt, and enforcement must reflect it. assert "command" in guardrail._compiled_rule_patterns.get("native-bash", {}) - assert guardrail._get_permission_for_tool_call(self._bash("echo blockme"))[0] is False - assert guardrail._get_permission_for_tool_call(self._bash("echo hello"))[0] is True + assert ( + guardrail._get_permission_for_tool_call(self._bash("echo blockme"))[0] + is False + ) + assert ( + guardrail._get_permission_for_tool_call(self._bash("echo hello"))[0] is True + ) def test_update_in_memory_recompiles_tool_name_target(self): guardrail = ToolPermissionGuardrail( @@ -1321,7 +1341,10 @@ class TestToolPermissionGuardrailInMemoryUpdate: assert len(guardrail.rules) == 1 assert "command" in guardrail._compiled_rule_patterns.get("native-bash", {}) - assert guardrail._get_permission_for_tool_call(self._bash("echo blockme"))[0] is False + assert ( + guardrail._get_permission_for_tool_call(self._bash("echo blockme"))[0] + is False + ) def test_update_in_memory_rejects_invalid_regex_and_keeps_previous_rules(self): """Regression: a live update whose rules contain an invalid regex must be @@ -1653,9 +1676,7 @@ class TestToolPermissionGuardrailAnthropicMessages: @pytest.mark.asyncio async def test_pre_call_lets_a_type_rule_allow_a_gemini_tool_by_its_key(self) -> None: guardrail = self._pre_call( - [{"id": "allow_search", "tool_type": r"^googleSearch$", "decision": "allow"}], - "block", - default_action="deny", + [{"id": "allow_search", "tool_type": r"^googleSearch$", "decision": "allow"}], "block", default_action="deny" ) data = {"model": "gemini-3", "messages": [{"role": "user", "content": "hi"}], "tools": [{"googleSearch": {}}]} @@ -1681,10 +1702,7 @@ class TestToolPermissionGuardrailAnthropicMessages: lookup = {"type": "function", "name": "mcp__weather__lookup"} data = { "model": "m", - "input": [ - {"role": "user", "content": "hi"}, - {"type": "tool_search_output", "tools": [get_weather, lookup]}, - ], + "input": [{"role": "user", "content": "hi"}, {"type": "tool_search_output", "tools": [get_weather, lookup]}], "tools": [{"functionDeclarations": [{"name": "get_weather"}, {"name": "mcp__weather__lookup"}]}], } @@ -1804,10 +1822,7 @@ class TestToolPermissionGuardrailAnthropicMessages: lookup = {"type": "function", "name": "mcp__weather__lookup"} data = { "model": "m", - "input": [ - {"role": "user", "content": "hi"}, - {"type": "tool_search_output", "tools": [get_weather, lookup]}, - ], + "input": [{"role": "user", "content": "hi"}, {"type": "tool_search_output", "tools": [get_weather, lookup]}], "tools": [lookup], "tool_choice": tool_choice, } @@ -1942,12 +1957,7 @@ class TestToolPermissionGuardrailAnthropicMessages: @pytest.mark.parametrize( ("tool", "tool_choice", "call_type", "allowed_tool_type"), [ - ( - {"type": "custom", "name": "apply_patch"}, - {"type": "custom", "name": "apply_patch"}, - "responses", - r"^custom$", - ), + ({"type": "custom", "name": "apply_patch"}, {"type": "custom", "name": "apply_patch"}, "responses", r"^custom$"), ( {"type": "web_search_20250305", "name": "web_search"}, {"type": "tool", "name": "web_search"}, @@ -2922,31 +2932,16 @@ class TestToolPermissionGuardrailAnthropicMessages: def _sse_chunks(self, tool_name, tool_id="tu_1"): events = [ - { - "type": "message_start", - "message": { - "id": "msg_1", - "type": "message", - "role": "assistant", - "model": "claude-sonnet-4-5", - "content": [], - "stop_reason": None, - "usage": {"input_tokens": 10, "output_tokens": 0}, - }, - }, + {"type": "message_start", "message": {"id": "msg_1", "type": "message", "role": "assistant", + "model": "claude-sonnet-4-5", "content": [], "stop_reason": None, + "usage": {"input_tokens": 10, "output_tokens": 0}}}, {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}, {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "working"}}, {"type": "content_block_stop", "index": 0}, - { - "type": "content_block_start", - "index": 1, - "content_block": {"type": "tool_use", "id": tool_id, "name": tool_name, "input": {}}, - }, - { - "type": "content_block_delta", - "index": 1, - "delta": {"type": "input_json_delta", "partial_json": '{"command": "ls"}'}, - }, + {"type": "content_block_start", "index": 1, + "content_block": {"type": "tool_use", "id": tool_id, "name": tool_name, "input": {}}}, + {"type": "content_block_delta", "index": 1, + "delta": {"type": "input_json_delta", "partial_json": '{"command": "ls"}'}}, {"type": "content_block_stop", "index": 1}, {"type": "message_delta", "delta": {"stop_reason": "tool_use"}, "usage": {"output_tokens": 5}}, {"type": "message_stop"}, @@ -3010,12 +3005,8 @@ class TestToolPermissionGuardrailAnthropicMessages: for line in body.splitlines() if line.startswith("data: ") and json.loads(line[6:]).get("type") == "message_start" )["message"] - assert message_start["id"].startswith("chatcmpl-"), ( - "the rewritten stream must not adopt the upstream message id" - ) - assert message_start["model"] == "claude-sonnet-4-5", ( - "the rewritten stream reports the model the upstream served" - ) + assert message_start["id"].startswith("chatcmpl-"), "the rewritten stream must not adopt the upstream message id" + assert message_start["model"] == "claude-sonnet-4-5", "the rewritten stream reports the model the upstream served" @pytest.mark.asyncio async def test_rewrite_mode_keeps_the_allowed_tool_use_verdict_with_its_explanation(self): From 2de6ddf153dee3b16867a6cc3546fa0d96d825be Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Mon, 2 Nov 2026 22:45:14 -0800 Subject: [PATCH 28/39] fix(guardrails): judge extra_body.input tools, argument-aware alias rules, and exact forced Gemini functions Tools loaded in extra_body.input are now checked and stripped like top-level input. A returned namespace member is judged by the alias whose first name rule its arguments satisfy. A forced Gemini name that matches a top-level function keeps that function. Alias grouping and Gemini declaration dedupe now run in one pass instead of quadratic scans. --- .../vertex_and_google_ai_studio_gemini.py | 5 +- .../guardrail_hooks/tool_permission.py | 124 ++++++++++++------ ...test_vertex_and_google_ai_studio_gemini.py | 14 +- .../guardrail_hooks/test_tool_permission.py | 57 ++++++++ 4 files changed, 157 insertions(+), 43 deletions(-) diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index 84833b03186..372f8fefb3e 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -575,7 +575,8 @@ def _is_namespace(tool: JsonValue) -> bool: def _first_declarations(tools: tuple[JsonValue, ...]) -> tuple[JsonValue, ...]: names: Final = tuple(map(_declared_function_name, tools)) - return tuple(tool for index, tool in enumerate(tools) if names[index] is None or names[index] not in names[:index]) + first_index: Final = {name: index for index, name in reversed(tuple(enumerate(names)))} + return tuple(tool for index, tool in enumerate(tools) if names[index] is None or first_index[names[index]] == index) def _with_namespace_members_inlined(tools: JsonValue) -> JsonValue: @@ -586,6 +587,8 @@ def _with_namespace_members_inlined(tools: JsonValue) -> JsonValue: def _forced_function_names(name: str, tools: JsonValue) -> tuple[str, ...]: candidates: Final = tools if isinstance(tools, list) else [] + if any(not _is_namespace(tool) and _declared_function_name(tool) == name for tool in candidates): + return (name,) named: Final = next((tool for tool in candidates if _is_namespace(tool) and _member_name_of(tool) == name), None) members: Final = map(_declared_function_name, _namespace_members_or_tool(named)) if named is not None else () return tuple(dict.fromkeys(member for member in members if member is not None)) or (name,) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index a36eab7bae7..28bb3b6ad6e 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -1,9 +1,9 @@ import json import re -from collections.abc import AsyncGenerator, AsyncIterable, Callable, Mapping, Sequence +from collections.abc import AsyncGenerator, AsyncIterable, Callable, Iterable, Mapping, Sequence from dataclasses import dataclass from functools import partial -from itertools import chain +from itertools import chain, groupby from types import MappingProxyType from typing import Any, Final, Literal, TypeAlias, TypedDict @@ -234,6 +234,19 @@ def _tools_in_items(items: Sequence[object]) -> tuple[object, ...]: return tuple(chain.from_iterable(_input_item_tools(item) or () for item in items)) +def _carries_tools(items: Sequence[object]) -> bool: + return any(_input_item_tools(item) is not None for item in items) + + +def _pair_key(pair: tuple[str, str]) -> str: + return pair[0] + + +def _grouped_values(pairs: Iterable[tuple[str, str]]) -> Mapping[str, tuple[str, ...]]: + groups: Final = groupby(sorted(pairs, key=_pair_key), key=_pair_key) + return MappingProxyType({key: tuple(dict.fromkeys(value for _, value in group)) for key, group in groups}) + + def _extra_body(data: object) -> Mapping[str, object] | None: fields: Final = _object_mapping(data) return _object_mapping(fields.get("extra_body")) if fields is not None else None @@ -243,6 +256,10 @@ def _extra_body_tools(data: object) -> Sequence[object] | None: return _request_list(_extra_body(data), "tools") +def _extra_body_input_items(data: object) -> Sequence[object]: + return _request_list(_extra_body(data), "input") or () + + def _extra_body_tool_choice(data: object) -> object: extra_body: Final = _extra_body(data) return extra_body.get("tool_choice") if extra_body is not None else None @@ -254,6 +271,7 @@ def _sent_tools(data: object) -> tuple[object, ...]: *(_request_list(data, "functions") or ()), *(_extra_body_tools(data) or ()), *_tools_in_items(_input_items(data)), + *_tools_in_items(_extra_body_input_items(data)), ) @@ -653,12 +671,37 @@ class ToolPermissionGuardrail(CustomGuardrail): def _is_name_rule_for(self, rule: ToolPermissionRule, tool_name: str, tool_type: str | None) -> bool: return rule.tool_name is not None and self._rule_matches_tool(rule, tool_name=tool_name, tool_type=tool_type)[0] - def _first_name_rule(self, tool_name: str, tool_type: str | None) -> ToolPermissionRule | None: - return next((rule for rule in self.rules if self._is_name_rule_for(rule, tool_name, tool_type)), None) + def _decides_call( + self, rule: ToolPermissionRule, tool_name: str, tool_call: ChatCompletionMessageToolCall | None + ) -> bool: + if tool_call is None or not rule.allowed_param_patterns: + return True + arguments, parse_error = self._parse_tool_call_arguments(tool_call) + if parse_error or not arguments: + return True + return self._patterns_match_for_rule(arguments=arguments, rule=rule, tool_name=tool_name)[0] - def _deciding_member_name(self, qualified: str, bare: str, tool_type: str | None) -> str: - qualified_rule: Final = self._first_name_rule(qualified, tool_type) - bare_rule: Final = self._first_name_rule(bare, tool_type) + def _first_name_rule( + self, tool_name: str, tool_type: str | None, tool_call: ChatCompletionMessageToolCall | None + ) -> ToolPermissionRule | None: + return next( + ( + rule + for rule in self.rules + if self._is_name_rule_for(rule, tool_name, tool_type) and self._decides_call(rule, tool_name, tool_call) + ), + None, + ) + + def _deciding_member_name( + self, + qualified: str, + bare: str, + tool_type: str | None, + tool_call: ChatCompletionMessageToolCall | None = None, + ) -> str: + qualified_rule: Final = self._first_name_rule(qualified, tool_type, tool_call) + bare_rule: Final = self._first_name_rule(bare, tool_type, tool_call) if bare_rule is None or bare_rule is qualified_rule: return qualified if qualified_rule is None or self._is_name_rule_for(qualified_rule, bare, tool_type): @@ -668,7 +711,7 @@ class ToolPermissionGuardrail(CustomGuardrail): return bare if bare_rule.decision == "deny" else qualified def _check_target_permission( - self, target: _ToolTarget, bare_names: Mapping[str, frozenset[str]] + self, target: _ToolTarget, bare_names: Mapping[str, tuple[str, ...]] ) -> tuple[bool, str | None, str | None]: name, tool_type = target candidates: Final = tuple(sorted(bare_names.get(name, ()))) if name is not None else () @@ -924,25 +967,24 @@ class ToolPermissionGuardrail(CustomGuardrail): return MappingProxyType({}) listed: Final = frozenset(name for name, _ in self._collect_request_tools(data) if name is not None) return MappingProxyType( - {bare: self._judged_names_of_returned_call(bare, member_names, listed) for _, bare in member_names} + { + bare: (*qualified, *((bare,) if bare in listed else ())) + for bare, qualified in _grouped_values((bare, name) for name, bare in member_names).items() + } ) - def _judged_names_of_returned_call( - self, bare: str, member_names: tuple[tuple[str, str], ...], listed: frozenset[str] - ) -> tuple[str, ...]: - qualified: Final = ( - self._deciding_member_name(name, bare, "function") for name, key in member_names if key == bare - ) - return tuple(dict.fromkeys((*qualified, *((bare,) if bare in listed else ())))) + def _judged_name(self, tool_call: ChatCompletionMessageToolCall, bare: str, name: str) -> str: + return name if name == bare else self._deciding_member_name(name, bare, "function", tool_call) def _judge_tool_call( self, tool_call: ChatCompletionMessageToolCall, judged_names: Mapping[str, tuple[str, ...]] ) -> tuple[bool, str | None, str | None]: returned_name: Final = tool_call.function.name if tool_call.function else None names: Final = judged_names.get(returned_name, ()) if returned_name is not None else () - if not names: + if returned_name is None or not names: return self._get_permission_for_tool_call(tool_call) - results: Final = tuple(self._get_permission_for_tool_call(tool_call, name) for name in names) + judged: Final = dict.fromkeys(self._judged_name(tool_call, returned_name, name) for name in names) + results: Final = tuple(self._get_permission_for_tool_call(tool_call, name) for name in judged) return next((result for result in results if not result[0]), results[0]) def _evaluate_tool_calls( @@ -1115,7 +1157,7 @@ class ToolPermissionGuardrail(CustomGuardrail): replayed: Final = map(_function_tool_name, replayed_tool_search_tools(request)) request_tools.extend((name, "function") for name in replayed if name is not None) - for input_tool in _tools_in_items(_input_items(request)): + for input_tool in _tools_in_items((*_input_items(request), *_extra_body_input_items(request))): request_tools.extend(self._get_request_tool_targets(input_tool)) return request_tools @@ -1129,12 +1171,14 @@ class ToolPermissionGuardrail(CustomGuardrail): self, extra_body: Mapping[str, object], kept_tools: tuple[object, ...] | None, + kept_input: tuple[object, ...] | None, rewrite_choice: Callable[[object], object], ) -> dict[str, object]: choice: Final = extra_body.get("tool_choice") return { **extra_body, **({"tools": list(kept_tools)} if kept_tools is not None else {}), + **({"input": list(kept_input)} if kept_input is not None else {}), **({"tool_choice": rewrite_choice(choice)} if choice is not None else {}), } @@ -1184,6 +1228,16 @@ class ToolPermissionGuardrail(CustomGuardrail): ) -> tuple[object, ...]: return tuple(chain.from_iterable(self._kept_tools(tool, denied_targets, denied_names) for tool in tools)) + def _kept_input_list( + self, + items: Sequence[object], + denied_targets: frozenset[_ToolTarget], + denied_names: frozenset[str], + ) -> tuple[object, ...] | None: + if not _carries_tools(items): + return None + return tuple(chain.from_iterable(self._kept_input_items(item, denied_targets, denied_names) for item in items)) + def _kept_input_items( self, item: object, @@ -1263,23 +1317,23 @@ class ToolPermissionGuardrail(CustomGuardrail): if kept_mcp_servers is not None: data["mcp_servers"] = list(kept_mcp_servers) # rebind-ok: rewrite mode edits the request in place - input_items: Final = _input_items(request) - rewrites_input: Final = any(_input_item_tools(item) is not None for item in input_items) - kept_input_items: Final = ( - tuple( - chain.from_iterable(self._kept_input_items(item, denied_targets, denied_names) for item in input_items) - ) - if rewrites_input - else input_items + kept_input_list: Final = partial( + self._kept_input_list, denied_targets=denied_targets, denied_names=denied_names ) - if rewrites_input: - data["input"] = list(kept_input_items) # rebind-ok: rewrite mode edits the request in place + input_items: Final = _input_items(request) + rewritten_input: Final = kept_input_list(input_items) + kept_input_items: Final = input_items if rewritten_input is None else rewritten_input + if rewritten_input is not None: + data["input"] = list(rewritten_input) # rebind-ok: rewrite mode edits the request in place + extra_body_input: Final = _extra_body_input_items(request) + kept_extra_body_input: Final = kept_input_list(extra_body_input) kept_sent_tools: Final = ( *(kept_tools or ()), *(kept_functions or ()), *(kept_extra_body_tools or ()), *_tools_in_items(kept_input_items), + *_tools_in_items(extra_body_input if kept_extra_body_input is None else kept_extra_body_input), ) removed_names: Final = denied_names | (self._tool_names_in(sent_tools) - self._tool_names_in(kept_sent_tools)) kept_types: Final = self._tool_types_in(kept_sent_tools) @@ -1295,9 +1349,10 @@ class ToolPermissionGuardrail(CustomGuardrail): tool_choice: Final = _REQUEST_DATA.validate_python(data.get("tool_choice")) if tool_choice is not None: data["tool_choice"] = rewrite_choice(tool_choice) # rebind-ok: rewrite mode edits the request in place - if extra_body is not None and (kept_extra_body_tools is not None or "tool_choice" in extra_body): + rewrites_extra_body: Final = kept_extra_body_tools is not None or kept_extra_body_input is not None + if extra_body is not None and (rewrites_extra_body or "tool_choice" in extra_body): data["extra_body"] = self._rewritten_extra_body( # rebind-ok: rewrite mode edits the request in place - extra_body, kept_extra_body_tools, rewrite_choice + extra_body, kept_extra_body_tools, kept_extra_body_input, rewrite_choice ) named_function_call: Final = self._get_named_function_call(data) @@ -1436,12 +1491,7 @@ class ToolPermissionGuardrail(CustomGuardrail): member_names: Final = tuple( chain.from_iterable(map(self._bare_member_names, _sent_tools(_REQUEST_DATA.validate_python(data)))) ) - bare_names: Final = MappingProxyType( - { - qualified: frozenset(bare for key, bare in member_names if key == qualified) - for qualified, _ in member_names - } - ) + bare_names: Final = _grouped_values(member_names) decisions: Final = tuple((target, self._check_target_permission(target, bare_names)) for target in new_tools) denied: Final = tuple( (target, message) diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index 939223a0969..0afd10d08ab 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -1857,12 +1857,16 @@ def test_vertex_ai_map_tools_keeps_repeated_chat_tools_when_no_namespace_is_sent @pytest.mark.parametrize( - ("forced_name", "allowed_function_names"), - [("github", ["create_issue", "close_issue"]), ("close_issue", ["close_issue"])], - ids=["names_the_namespace", "names_a_member"], + ("forced_name", "other_tools", "allowed_function_names"), + [ + ("github", [], ["create_issue", "close_issue"]), + ("close_issue", [], ["close_issue"]), + ("github", [{"type": "function", "function": {"name": "github"}}], ["github"]), + ], + ids=["names_the_namespace", "names_a_member", "names_a_function_sharing_the_namespace_name"], ) def test_vertex_ai_tool_choice_forces_only_functions_gemini_is_sent( - forced_name: str, allowed_function_names: list[str] + forced_name: str, other_tools: list[dict[str, object]], allowed_function_names: list[str] ) -> None: namespace = { "type": "namespace", @@ -1872,7 +1876,7 @@ def test_vertex_ai_tool_choice_forces_only_functions_gemini_is_sent( mapped = VertexGeminiConfig().map_openai_params( non_default_params={ - "tools": [namespace], + "tools": [namespace, *other_tools], "tool_choice": {"type": "function", "function": {"name": forced_name}}, }, optional_params={}, diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index b95db268561..653ce742950 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -529,6 +529,42 @@ class TestToolPermissionGuardrail: assert called == [] assert "Tool 'mcp__weather__lookup' denied by rule 'deny_mcp'" in content + @pytest.mark.asyncio + async def test_post_call_judges_a_returned_namespace_member_by_the_rule_its_arguments_satisfy(self) -> None: + guardrail = ToolPermissionGuardrail( + guardrail_name="post-exec", + rules=[ + { + "id": "allow_ls", + "tool_name": r"^exec$", + "decision": "allow", + "allowed_param_patterns": {"command": r"^ls$"}, + }, + {"id": "deny_exec", "tool_name": r"^exec$", "decision": "deny"}, + {"id": "allow_ops", "tool_name": r"^ops__.*$", "decision": "allow"}, + ], + default_action="allow", + on_disallowed_action="rewrite", + event_hook=GuardrailEventHooks.post_call, + ) + namespace = {"type": "namespace", "name": "ops", "tools": [{"type": "function", "name": "exec"}]} + data = {"guardrails": ["post-exec"], "tools": [namespace]} + function = Function(name="exec", arguments='{"command": "rm -rf /data"}') + response = ModelResponse( + choices=[ + Choices( + finish_reason="tool_calls", + message={"tool_calls": [{"id": "call_exec", "type": "function", "function": function}]}, + ) + ] + ) + + await guardrail.async_post_call_success_hook(data=data, user_api_key_dict=UserAPIKeyAuth(), response=response) + + message = response.choices[0].message + assert [call.function.name for call in message.tool_calls or ()] == [] + assert "Tool 'exec'" in (message.content or "") + @pytest.mark.asyncio async def test_async_post_call_success_hook_missing_arguments_blocks_param_rule( self, @@ -2084,6 +2120,27 @@ class TestToolPermissionGuardrailAnthropicMessages: assert message == "Tool 'Read' denied by rule 'deny_read'" assert rewritten["extra_body"] == {"tools": [bash], "seed": 7} + @pytest.mark.asyncio + async def test_pre_call_checks_and_strips_tools_loaded_in_extra_body_input(self) -> None: + rules = [{"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}] + get_weather = {"type": "function", "name": "get_weather"} + lookup = {"type": "function", "name": "mcp__weather__lookup"} + user = {"role": "user", "content": "hi"} + request = { + "model": "gpt-5", + "input": "hi", + "tools": [], + "extra_body": {"input": [user, {"type": "tool_search_output", "tools": [get_weather, lookup]}], "seed": 7}, + } + + message, rewritten = await self._blocked_and_rewritten(rules, request, "responses") + + assert message == "Tool 'mcp__weather__lookup' denied by rule 'deny_mcp'" + assert rewritten["extra_body"] == { + "input": [user, {"type": "tool_search_output", "tools": [get_weather]}], + "seed": 7, + } + @pytest.mark.asyncio async def test_rewrite_relaxes_an_extra_body_tool_choice_that_names_a_dropped_tool(self) -> None: guardrail = self._pre_call([{"id": "deny_delete", "tool_name": r"^delete_db$", "decision": "deny"}], "rewrite") From 67050b86433abafda451db812cc9e96acca62654 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Mon, 2 Nov 2026 23:56:34 -0800 Subject: [PATCH 29/39] fix(guardrails): judge and rewrite every tool field sent inside extra_body extra_body is merged into the upstream body, so functions, function_call, mcp_servers and toolConfig nested there reached the model unjudged. Treat extra_body as a second request layer that is collected and rewritten the same way as the top-level request. --- .../guardrail_hooks/tool_permission.py | 221 ++++++++---------- .../guardrail_hooks/test_tool_permission.py | 49 ++++ 2 files changed, 152 insertions(+), 118 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 28bb3b6ad6e..4ea3e497365 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -247,32 +247,44 @@ def _grouped_values(pairs: Iterable[tuple[str, str]]) -> Mapping[str, tuple[str, return MappingProxyType({key: tuple(dict.fromkeys(value for _, value in group)) for key, group in groups}) -def _extra_body(data: object) -> Mapping[str, object] | None: +def _request_layers(data: object) -> tuple[Mapping[str, object], ...]: fields: Final = _object_mapping(data) - return _object_mapping(fields.get("extra_body")) if fields is not None else None + extra_body: Final = _object_mapping(fields.get("extra_body")) if fields is not None else None + return tuple(layer for layer in (fields, extra_body) if layer is not None) -def _extra_body_tools(data: object) -> Sequence[object] | None: - return _request_list(_extra_body(data), "tools") - - -def _extra_body_input_items(data: object) -> Sequence[object]: - return _request_list(_extra_body(data), "input") or () - - -def _extra_body_tool_choice(data: object) -> object: - extra_body: Final = _extra_body(data) - return extra_body.get("tool_choice") if extra_body is not None else None +def _layer_sent_tools(layer: Mapping[str, object]) -> tuple[object, ...]: + return ( + *(_request_list(layer, "tools") or ()), + *(_request_list(layer, "functions") or ()), + *_tools_in_items(_input_items(layer)), + ) def _sent_tools(data: object) -> tuple[object, ...]: - return ( - *(_request_list(data, "tools") or ()), - *(_request_list(data, "functions") or ()), - *(_extra_body_tools(data) or ()), - *_tools_in_items(_input_items(data)), - *_tools_in_items(_extra_body_input_items(data)), - ) + return tuple(chain.from_iterable(map(_layer_sent_tools, _request_layers(data)))) + + +@dataclass(frozen=True, slots=True) +class _KeptLayer: + fields: Mapping[str, object] + tools: tuple[object, ...] | None + functions: tuple[object, ...] | None + mcp_servers: tuple[object, ...] | None + input: tuple[object, ...] | None + + def sent_tools(self) -> tuple[object, ...]: + kept_input: Final = _input_items(self.fields) if self.input is None else self.input + return (*(self.tools or ()), *(self.functions or ()), *_tools_in_items(kept_input)) + + def kept_lists(self) -> dict[str, object]: + lists: Final = ( + ("tools", self.tools), + ("functions", self.functions), + ("mcp_servers", self.mcp_servers), + ("input", self.input), + ) + return {key: list(kept) for key, kept in lists if kept is not None} def _mcp_server_target(server: object) -> _ToolTarget: @@ -1133,53 +1145,77 @@ class ToolPermissionGuardrail(CustomGuardrail): return function_call return self._get_mapping_value(function_call, "name") - def _collect_request_tools(self, data: Mapping[str, object]) -> list[_ToolTarget]: - request_tools: Final[list[_ToolTarget]] = [] + def _listed_layer_targets(self, layer: Mapping[str, object]) -> tuple[_ToolTarget, ...]: + return ( + *chain.from_iterable(map(self._get_request_tool_targets, _request_list(layer, "tools") or ())), + *map(_mcp_server_target, _request_list(layer, "mcp_servers") or ()), + *chain.from_iterable(map(self._legacy_function_targets, _request_list(layer, "functions") or ())), + ) + + def _forced_layer_names(self, layer: Mapping[str, object]) -> tuple[str | None, ...]: + return (self._get_named_tool_choice(layer.get("tool_choice")), self._get_named_function_call(layer)) + + def _collect_request_tools(self, data: Mapping[str, object]) -> tuple[_ToolTarget, ...]: request: Final = _REQUEST_DATA.validate_python(data) - - for tool in _request_list(request, "tools") or (): - request_tools.extend(self._get_request_tool_targets(tool)) - for extra_body_tool in _extra_body_tools(request) or (): - request_tools.extend(self._get_request_tool_targets(extra_body_tool)) - request_tools.extend(map(_mcp_server_target, _request_list(request, "mcp_servers") or ())) - - for function in _request_list(request, "functions") or (): - request_tools.extend(self._legacy_function_targets(function)) - - listed_names: Final = frozenset(name for name, _ in request_tools) - for forced_tool_name in ( - self._get_named_tool_choice(_REQUEST_DATA.validate_python(data.get("tool_choice"))), - self._get_named_tool_choice(_extra_body_tool_choice(request)), - self._get_named_function_call(data), - ): - if forced_tool_name is not None and forced_tool_name not in listed_names: - request_tools.append((forced_tool_name, "function")) - + layers: Final = _request_layers(request) + listed: Final = tuple(chain.from_iterable(map(self._listed_layer_targets, layers))) + listed_names: Final = frozenset(name for name, _ in listed) + forced: Final = chain.from_iterable(map(self._forced_layer_names, layers)) replayed: Final = map(_function_tool_name, replayed_tool_search_tools(request)) - request_tools.extend((name, "function") for name in replayed if name is not None) - for input_tool in _tools_in_items((*_input_items(request), *_extra_body_input_items(request))): - request_tools.extend(self._get_request_tool_targets(input_tool)) - - return request_tools + input_tools: Final = _tools_in_items(tuple(chain.from_iterable(map(_input_items, layers)))) + return ( + *listed, + *((name, "function") for name in forced if name is not None and name not in listed_names), + *((name, "function") for name in replayed if name is not None), + *chain.from_iterable(map(self._get_request_tool_targets, input_tools)), + ) def _legacy_function_targets(self, function: object) -> tuple[_ToolTarget, ...]: targets: Final = self._get_request_tool_targets(function) as_functions: Final = tuple((name, "function") for name, _ in targets if name is not None) return tuple(dict.fromkeys(targets + as_functions)) - def _rewritten_extra_body( + def _kept_layer( self, - extra_body: Mapping[str, object], - kept_tools: tuple[object, ...] | None, - kept_input: tuple[object, ...] | None, + layer: Mapping[str, object], + denied_targets: frozenset[_ToolTarget], + denied_names: frozenset[str], + ) -> _KeptLayer: + is_denied: Final = partial(_is_denied_target, denied_targets=denied_targets, denied_names=denied_names) + tools: Final = _request_list(layer, "tools") + functions: Final = _request_list(layer, "functions") + mcp_servers: Final = _request_list(layer, "mcp_servers") + return _KeptLayer( + fields=layer, + tools=None if tools is None else self._kept_tool_list(tools, denied_targets, denied_names), + functions=None if functions is None else self._kept_tool_list(functions, denied_targets, denied_names), + mcp_servers=( + None + if mcp_servers is None + else tuple(server for server in mcp_servers if not is_denied(_mcp_server_target(server))) + ), + input=self._kept_input_list(_input_items(layer), denied_targets, denied_names), + ) + + def _rewritten_layer_fields( + self, + kept: _KeptLayer, rewrite_choice: Callable[[object], object], + removed_names: frozenset[str], + functions_remain: bool, ) -> dict[str, object]: - choice: Final = extra_body.get("tool_choice") + layer: Final = kept.fields + choice: Final = layer.get("tool_choice") + relaxes_function_call: Final = self._get_named_function_call(layer) in removed_names return { - **extra_body, - **({"tools": list(kept_tools)} if kept_tools is not None else {}), - **({"input": list(kept_input)} if kept_input is not None else {}), + **kept.kept_lists(), **({"tool_choice": rewrite_choice(choice)} if choice is not None else {}), + **({"function_call": "none"} if relaxes_function_call else {}), + **{ + key: _rewritten_tool_config(layer[key], removed_names, functions_remain) + for key in _TOOL_CONFIG_KEYS + if key in layer + }, } def _tool_names_in(self, tools: Sequence[object]) -> frozenset[str]: @@ -1288,82 +1324,31 @@ class ToolPermissionGuardrail(CustomGuardrail): verbose_proxy_logger.info("Blocking %s unauthorized tool uses", len(denied_targets)) denied_names: Final = frozenset(name for name, _ in denied_targets if name is not None) - is_denied: Final = partial(_is_denied_target, denied_targets=denied_targets, denied_names=denied_names) - kept_tool_list: Final = partial(self._kept_tool_list, denied_targets=denied_targets, denied_names=denied_names) - request: Final = _REQUEST_DATA.validate_python(data) + kept_layers: Final = tuple( + self._kept_layer(layer, denied_targets, denied_names) for layer in _request_layers(request) + ) + sent_tools: Final = _sent_tools(request) - - tools: Final = _request_list(request, "tools") - kept_tools: Final = None if tools is None else kept_tool_list(tools) - if kept_tools is not None: - data["tools"] = list(kept_tools) # rebind-ok: rewrite mode edits the request in place - - extra_body: Final = _extra_body(request) - extra_body_tools: Final = _extra_body_tools(request) - kept_extra_body_tools: Final = None if extra_body_tools is None else kept_tool_list(extra_body_tools) - - functions: Final = _request_list(request, "functions") - kept_functions: Final = None if functions is None else kept_tool_list(functions) - if kept_functions is not None: - data["functions"] = list(kept_functions) # rebind-ok: rewrite mode edits the request in place - - mcp_servers: Final = _request_list(request, "mcp_servers") - kept_mcp_servers: Final = ( - None - if mcp_servers is None - else tuple(server for server in mcp_servers if not is_denied(_mcp_server_target(server))) - ) - if kept_mcp_servers is not None: - data["mcp_servers"] = list(kept_mcp_servers) # rebind-ok: rewrite mode edits the request in place - - kept_input_list: Final = partial( - self._kept_input_list, denied_targets=denied_targets, denied_names=denied_names - ) - input_items: Final = _input_items(request) - rewritten_input: Final = kept_input_list(input_items) - kept_input_items: Final = input_items if rewritten_input is None else rewritten_input - if rewritten_input is not None: - data["input"] = list(rewritten_input) # rebind-ok: rewrite mode edits the request in place - extra_body_input: Final = _extra_body_input_items(request) - kept_extra_body_input: Final = kept_input_list(extra_body_input) - - kept_sent_tools: Final = ( - *(kept_tools or ()), - *(kept_functions or ()), - *(kept_extra_body_tools or ()), - *_tools_in_items(kept_input_items), - *_tools_in_items(extra_body_input if kept_extra_body_input is None else kept_extra_body_input), - ) + kept_sent_tools: Final = tuple(chain.from_iterable(kept.sent_tools() for kept in kept_layers)) removed_names: Final = denied_names | (self._tool_names_in(sent_tools) - self._tool_names_in(kept_sent_tools)) kept_types: Final = self._tool_types_in(kept_sent_tools) removed_types: Final = self._tool_types_in(sent_tools) - kept_types - tools_remain: Final = bool(kept_sent_tools) or bool(kept_mcp_servers) + tools_remain: Final = bool(kept_sent_tools) or any(kept.mcp_servers for kept in kept_layers) rewrite_choice: Final = partial( self._rewritten_tool_choice, removed_names=removed_names, removed_types=removed_types, tools_remain=tools_remain, ) - tool_choice: Final = _REQUEST_DATA.validate_python(data.get("tool_choice")) - if tool_choice is not None: - data["tool_choice"] = rewrite_choice(tool_choice) # rebind-ok: rewrite mode edits the request in place - rewrites_extra_body: Final = kept_extra_body_tools is not None or kept_extra_body_input is not None - if extra_body is not None and (rewrites_extra_body or "tool_choice" in extra_body): - data["extra_body"] = self._rewritten_extra_body( # rebind-ok: rewrite mode edits the request in place - extra_body, kept_extra_body_tools, kept_extra_body_input, rewrite_choice - ) - - named_function_call: Final = self._get_named_function_call(data) - if named_function_call in removed_names: - data["function_call"] = "none" # rebind-ok: rewrite mode edits the request in place - - functions_remain: Final = "function" in kept_types - for config_key in (key for key in _TOOL_CONFIG_KEYS if key in data): - data[config_key] = _rewritten_tool_config( # rebind-ok: rewrite mode edits the request in place - data[config_key], removed_names, functions_remain - ) + rewritten: Final = tuple( + self._rewritten_layer_fields(kept, rewrite_choice, removed_names, "function" in kept_types) + for kept in kept_layers + ) + data.update(rewritten[0]) + if len(rewritten) > 1 and rewritten[1]: + data["extra_body"] = {**kept_layers[1].fields, **rewritten[1]} # rebind-ok: rewrite mode edits in place messages: Final = without_tool_search_items_loading(_REQUEST_DATA.validate_python(data), denied_names) if messages is not None: diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 653ce742950..f454853f580 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2185,6 +2185,55 @@ class TestToolPermissionGuardrailAnthropicMessages: assert message == "Tool 'Read' denied by rule 'deny_read'" assert rewritten["extra_body"] == {"tool_choice": "none", "seed": 7} + @pytest.mark.asyncio + async def test_pre_call_checks_and_strips_legacy_functions_in_extra_body(self) -> None: + rules = [{"id": "deny_delete", "tool_name": r"^delete_db$", "decision": "deny"}] + weather = {"name": "get_weather", "parameters": {"type": "object"}} + delete_db = {"name": "delete_db", "parameters": {"type": "object"}} + request = { + "model": "m", + "messages": [{"role": "user", "content": "hi"}], + "extra_body": {"functions": [weather, delete_db], "function_call": {"name": "delete_db"}, "seed": 7}, + } + + message, rewritten = await self._blocked_and_rewritten(rules, request, "acompletion") + + assert message == "Tool 'delete_db' denied by rule 'deny_delete'" + assert rewritten["extra_body"] == {"functions": [weather], "function_call": "none", "seed": 7} + + @pytest.mark.asyncio + @pytest.mark.parametrize( + "fields", + [ + {"functions": [{"name": "get_weather"}, {"name": "delete_db"}], "function_call": "delete_db"}, + { + "tools": [{"type": "function", "function": {"name": "get_weather"}}], + "mcp_servers": [{"type": "url", "url": "https://mcp.example.com/mcp", "name": "delete_db"}], + "tool_choice": "required", + }, + { + "tools": [{"functionDeclarations": [{"name": "get_weather"}, {"name": "delete_db"}]}], + "toolConfig": {"functionCallingConfig": {"mode": "ANY", "allowedFunctionNames": ["delete_db"]}}, + }, + ], + ids=["legacy_functions", "mcp_servers", "gemini_tool_config"], + ) + async def test_extra_body_fields_are_judged_and_rewritten_like_the_same_top_level_fields( + self, fields: dict[str, object] + ) -> None: + rules = [{"id": "deny_delete", "tool_name": r"^delete_db$", "decision": "deny"}] + base = {"model": "m", "messages": [{"role": "user", "content": "hi"}]} + top_request = {**base, **copy.deepcopy(fields)} + extra_request = {**base, "extra_body": {**copy.deepcopy(fields), "seed": 7}} + + top_message, top = await self._blocked_and_rewritten(rules, top_request, "acompletion") + extra_message, extra = await self._blocked_and_rewritten(rules, extra_request, "acompletion") + + top_fields = {key: top[key] for key in fields} + assert top_fields != fields + assert extra_message == top_message + assert extra["extra_body"] == {**top_fields, "seed": 7} + @pytest.mark.asyncio @pytest.mark.parametrize( "rule", From 7f1512129e87fdab7264e290aa22fe9333a4976f Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 3 Nov 2026 00:37:06 -0800 Subject: [PATCH 30/39] fix(guardrails): judge Gemini hosted keys by key and count only the tools a provider receives after extra_body --- .../guardrail_hooks/tool_permission.py | 24 ++++++++--- .../guardrail_hooks/test_tool_permission.py | 43 +++++++++++++++++++ 2 files changed, 62 insertions(+), 5 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 4ea3e497365..74b937e7007 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -2,7 +2,7 @@ import json import re from collections.abc import AsyncGenerator, AsyncIterable, Callable, Iterable, Mapping, Sequence from dataclasses import dataclass -from functools import partial +from functools import partial, reduce from itertools import chain, groupby from types import MappingProxyType from typing import Any, Final, Literal, TypeAlias, TypedDict @@ -212,7 +212,7 @@ def _part_keys(fields: Mapping[str, object]) -> tuple[str, ...]: def _part_target(fields: Mapping[str, object], key: str) -> _ToolTarget: - return (_member_name(fields.get(key)), key) + return (None if key in _GEMINI_HOSTED_TOOL_KEYS else _member_name(fields.get(key)), key) def _input_item_tools(item: object) -> Sequence[object] | None: @@ -265,6 +265,10 @@ def _sent_tools(data: object) -> tuple[object, ...]: return tuple(chain.from_iterable(map(_layer_sent_tools, _request_layers(data)))) +def _sent_fields(data: object) -> Mapping[str, object]: + return dict(chain.from_iterable(layer.items() for layer in _request_layers(data))) + + @dataclass(frozen=True, slots=True) class _KeptLayer: fields: Mapping[str, object] @@ -286,6 +290,15 @@ class _KeptLayer: ) return {key: list(kept) for key, kept in lists if kept is not None} + def overlaid_by(self, over: "_KeptLayer") -> "_KeptLayer": + return _KeptLayer( + fields={**self.fields, **over.fields}, + tools=over.tools if "tools" in over.fields else self.tools, + functions=over.functions if "functions" in over.fields else self.functions, + mcp_servers=over.mcp_servers if "mcp_servers" in over.fields else self.mcp_servers, + input=over.input if "input" in over.fields else self.input, + ) + def _mcp_server_target(server: object) -> _ToolTarget: fields: Final = _object_mapping(server) @@ -1329,13 +1342,14 @@ class ToolPermissionGuardrail(CustomGuardrail): self._kept_layer(layer, denied_targets, denied_names) for layer in _request_layers(request) ) - sent_tools: Final = _sent_tools(request) - kept_sent_tools: Final = tuple(chain.from_iterable(kept.sent_tools() for kept in kept_layers)) + sent_tools: Final = _layer_sent_tools(_sent_fields(request)) + kept_sent: Final = reduce(_KeptLayer.overlaid_by, kept_layers) + kept_sent_tools: Final = kept_sent.sent_tools() removed_names: Final = denied_names | (self._tool_names_in(sent_tools) - self._tool_names_in(kept_sent_tools)) kept_types: Final = self._tool_types_in(kept_sent_tools) removed_types: Final = self._tool_types_in(sent_tools) - kept_types - tools_remain: Final = bool(kept_sent_tools) or any(kept.mcp_servers for kept in kept_layers) + tools_remain: Final = bool(kept_sent_tools) or bool(kept_sent.mcp_servers) rewrite_choice: Final = partial( self._rewritten_tool_choice, removed_names=removed_names, diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index f454853f580..a97d2ecd1f2 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2160,6 +2160,25 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["extra_body"] == {"tools": [weather], "tool_choice": "none", "seed": 7} + @pytest.mark.asyncio + async def test_rewrite_relaxes_a_required_tool_choice_when_the_extra_body_tools_sent_lose_every_tool( + self, + ) -> None: + guardrail = self._pre_call([{"id": "deny_delete", "tool_name": r"^delete_db$", "decision": "deny"}], "rewrite") + weather = {"type": "function", "function": {"name": "get_weather"}} + delete_db = {"type": "function", "function": {"name": "delete_db"}} + data = { + "model": "m", + "messages": [{"role": "user", "content": "hi"}], + "tools": [weather], + "extra_body": {"tools": [delete_db], "tool_choice": "required", "seed": 7}, + } + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [weather] + assert result["extra_body"] == {"tools": [], "tool_choice": "none", "seed": 7} + @pytest.mark.asyncio @pytest.mark.parametrize( ("call_type", "tool_choice"), @@ -2593,6 +2612,30 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tools"] == [weather] + @pytest.mark.asyncio + @pytest.mark.parametrize("on_disallowed_action", ["block", "rewrite"]) + async def test_pre_call_judges_a_gemini_hosted_key_by_the_key_whatever_name_it_carries( + self, on_disallowed_action: Literal["block", "rewrite"] + ) -> None: + guardrail = self._pre_call( + [{"id": "allow_weather", "tool_name": r"^get_weather$", "decision": "allow"}], + on_disallowed_action, + default_action="deny", + ) + weather = {"type": "function", "function": {"name": "get_weather"}} + computer_use = {"computerUse": {"name": "get_weather", "environment": "browser"}} + data = {"model": "gemini-3", "messages": [{"role": "user", "content": "hi"}], "tools": [weather, computer_use]} + + if on_disallowed_action == "block": + with pytest.raises(HTTPException) as excinfo: + await self._run_pre_call(guardrail, data, "acompletion") + assert excinfo.value.detail["detection_message"] == "Tool 'computerUse' denied by default action" + return + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [weather] + @pytest.mark.asyncio @pytest.mark.parametrize( "rules, tool", From 9dbdf845524704b858c26a759abc648191dc57cc Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 3 Nov 2026 01:17:47 -0800 Subject: [PATCH 31/39] fix(guardrails): relax a tool_choice that names a dropped namespace member by its bare name Gemini and Anthropic chat send namespace members under their bare names, so rewrite mode now treats a dropped member's bare name, and an emptied namespace's own name, as removed when no kept tool still carries it --- .../guardrail_hooks/tool_permission.py | 13 +++- .../guardrail_hooks/test_tool_permission.py | 72 +++++++++++++++++++ 2 files changed, 84 insertions(+), 1 deletion(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 74b937e7007..bcb8043d514 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -1235,6 +1235,15 @@ class ToolPermissionGuardrail(CustomGuardrail): targets: Final = chain.from_iterable(self._get_request_tool_targets(tool) for tool in tools) return frozenset(name for name, _ in targets if name is not None) + def _referable_names_in(self, tools: Sequence[object]) -> frozenset[str]: + member_names: Final = chain.from_iterable(map(self._bare_member_names, tools)) + namespace_names: Final = (_member_name(tool) for tool in tools if _namespace_members(tool)) + return ( + self._tool_names_in(tools) + | frozenset(bare for _, bare in member_names) + | frozenset(name for name in namespace_names if name is not None) + ) + def _kept_tools( self, tool: object, @@ -1345,7 +1354,9 @@ class ToolPermissionGuardrail(CustomGuardrail): sent_tools: Final = _layer_sent_tools(_sent_fields(request)) kept_sent: Final = reduce(_KeptLayer.overlaid_by, kept_layers) kept_sent_tools: Final = kept_sent.sent_tools() - removed_names: Final = denied_names | (self._tool_names_in(sent_tools) - self._tool_names_in(kept_sent_tools)) + removed_names: Final = denied_names | ( + self._referable_names_in(sent_tools) - self._referable_names_in(kept_sent_tools) + ) kept_types: Final = self._tool_types_in(kept_sent_tools) removed_types: Final = self._tool_types_in(sent_tools) - kept_types diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index a97d2ecd1f2..e305c803789 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -2424,6 +2424,78 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tools"] == [{"type": "namespace", "name": "functions", "tools": members[1:]}] + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("choice", "relaxed"), + [ + ({"tool_choice": {"type": "function", "function": {"name": "exec"}}}, {"tool_choice": "none"}), + ({"tool_choice": {"type": "function", "function": {"name": "ops"}}}, {"tool_choice": "none"}), + ( + { + "tool_choice": { + "type": "allowed_tools", + "allowed_tools": { + "mode": "required", + "tools": [ + {"type": "function", "function": {"name": "exec"}}, + {"type": "function", "function": {"name": "get_weather"}}, + ], + }, + } + }, + { + "tool_choice": { + "type": "allowed_tools", + "allowed_tools": { + "mode": "required", + "tools": [{"type": "function", "function": {"name": "get_weather"}}], + }, + } + }, + ), + ( + {"toolConfig": {"functionCallingConfig": {"mode": "ANY", "allowedFunctionNames": ["exec"]}}}, + {"toolConfig": {"functionCallingConfig": {"mode": "NONE"}}}, + ), + ], + ids=["bare_member_choice", "namespace_choice", "allowed_tools_entry", "allowed_function_names"], + ) + async def test_pre_call_rewrite_relaxes_a_bare_name_a_dropped_namespace_member_was_sent_under( + self, choice: dict[str, object], relaxed: dict[str, object] + ) -> None: + guardrail = self._pre_call([{"id": "deny_exec", "tool_name": r"^ops__exec$", "decision": "deny"}], "rewrite") + weather = {"type": "function", "function": {"name": "get_weather", "parameters": {"type": "object"}}} + namespace = {"type": "namespace", "name": "ops", "tools": [{"type": "function", "name": "exec"}]} + data = { + "model": "gemini/gemini-2.5-flash", + "messages": [{"role": "user", "content": "hi"}], + "tools": [weather, namespace], + **choice, + } + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [weather] + assert {key: result[key] for key in relaxed} == relaxed + + @pytest.mark.asyncio + async def test_pre_call_rewrite_keeps_a_bare_name_another_kept_namespace_still_serves(self) -> None: + guardrail = self._pre_call([{"id": "deny_exec", "tool_name": r"^ops__exec$", "decision": "deny"}], "rewrite") + dropped_namespace = {"type": "namespace", "name": "ops", "tools": [{"type": "function", "name": "exec"}]} + kept_namespace = {"type": "namespace", "name": "dev", "tools": [{"type": "function", "name": "exec"}]} + tool_choice = {"type": "function", "function": {"name": "exec"}} + data = { + "model": "gemini/gemini-2.5-flash", + "messages": [{"role": "user", "content": "hi"}], + "tools": [dropped_namespace, kept_namespace], + "tool_choice": tool_choice, + } + + result = await self._run_pre_call(guardrail, data, "acompletion") + + assert result["tools"] == [kept_namespace] + assert result["tool_choice"] == tool_choice + @pytest.mark.asyncio @pytest.mark.parametrize("exec_first", [True, False], ids=["exec_namespace_first", "exec_namespace_last"]) @pytest.mark.parametrize("on_disallowed_action", ["block", "rewrite"]) From c4c3478124905fc50602fbc025c4104ba32b3a73 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 3 Nov 2026 03:54:14 -0800 Subject: [PATCH 32/39] fix(gemini,guardrails): keep a top-level function over a same-named namespace member and leave malformed tool values to the provider Gemini and Vertex chat now declare a top-level function over a namespace member that shares its name, so a forced call gets the top-level schema. post_call judges a returned name a top-level tool carries as that tool, and pre_call no longer raises on an unhashable or non-string tool name, input item type, or function_call name. --- .../vertex_and_google_ai_studio_gemini.py | 24 ++++++-- .../guardrail_hooks/tool_permission.py | 33 ++++++----- ...test_vertex_and_google_ai_studio_gemini.py | 19 ++++++ .../guardrail_hooks/test_tool_permission.py | 58 +++++++++++++++++++ 4 files changed, 116 insertions(+), 18 deletions(-) diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index 372f8fefb3e..4127e100c65 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -573,16 +573,30 @@ def _is_namespace(tool: JsonValue) -> bool: return isinstance(tool, dict) and tool.get("type") == "namespace" -def _first_declarations(tools: tuple[JsonValue, ...]) -> tuple[JsonValue, ...]: - names: Final = tuple(map(_declared_function_name, tools)) - first_index: Final = {name: index for index, name in reversed(tuple(enumerate(names)))} - return tuple(tool for index, tool in enumerate(tools) if names[index] is None or first_index[names[index]] == index) +def _declarations_with_origin(tool: JsonValue) -> tuple[tuple[JsonValue, bool], ...]: + return tuple((declaration, _is_namespace(tool)) for declaration in _namespace_members_or_tool(tool)) + + +def _declaration_precedence(entry: tuple[int, tuple[JsonValue, bool]]) -> tuple[bool, int]: + index, (_, from_namespace) = entry + return (from_namespace, index) + + +def _kept_declarations(entries: tuple[tuple[JsonValue, bool], ...]) -> tuple[JsonValue, ...]: + names: Final = tuple(_declared_function_name(declaration) for declaration, _ in entries) + by_precedence: Final = tuple(sorted(enumerate(entries), key=_declaration_precedence, reverse=True)) + kept_index: Final = {names[index]: index for index, _ in by_precedence} + return tuple( + declaration + for index, (declaration, _) in enumerate(entries) + if names[index] is None or kept_index[names[index]] == index + ) def _with_namespace_members_inlined(tools: JsonValue) -> JsonValue: if not isinstance(tools, list) or not any(map(_is_namespace, tools)): return tools - return list(_first_declarations(tuple(chain.from_iterable(map(_namespace_members_or_tool, tools))))) + return list(_kept_declarations(tuple(chain.from_iterable(map(_declarations_with_origin, tools))))) def _forced_function_names(name: str, tools: JsonValue) -> tuple[str, ...]: diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index bcb8043d514..b3f6fe5f9f8 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -150,11 +150,14 @@ def _gemini_hosted_key_targets(tool: object) -> tuple[_ToolTarget, ...]: return (_part_target(fields, keys[0]),) if len(keys) == 1 and keys[0] in _GEMINI_HOSTED_TOOL_KEYS else () +def _is_namespace(tool: object) -> bool: + fields: Final = _object_mapping(tool) + return fields is not None and fields.get("type") == "namespace" + + def _namespace_members(tool: object) -> Sequence[object]: fields: Final = _object_mapping(tool) - members: Final = ( - _object_list(fields.get("tools")) if fields is not None and fields.get("type") == "namespace" else None - ) + members: Final = _object_list(fields.get("tools")) if fields is not None and _is_namespace(tool) else None return members or () @@ -217,7 +220,7 @@ def _part_target(fields: Mapping[str, object], key: str) -> _ToolTarget: def _input_item_tools(item: object) -> Sequence[object] | None: fields: Final = _object_mapping(item) - carries_tools: Final = fields is not None and fields.get("type") in _TOOL_CARRYING_INPUT_TYPES + carries_tools: Final = fields is not None and _non_empty_string(fields.get("type")) in _TOOL_CARRYING_INPUT_TYPES return _object_list(fields.get("tools")) if fields is not None and carries_tools else None @@ -408,7 +411,11 @@ def _requires_a_tool(tool_choice: object) -> bool: def _kept_allowed_function_names(config: Mapping[str, object], removed_names: frozenset[str]) -> Mapping[str, object]: listed: Final = tuple((key, _object_list(config.get(key))) for key in _ALLOWED_FUNCTION_NAMES_KEYS) - return {key: [name for name in names if name not in removed_names] for key, names in listed if names is not None} + return { + key: [name for name in names if _non_empty_string(name) not in removed_names] + for key, names in listed + if names is not None + } def _rewritten_function_calling_config( @@ -985,17 +992,17 @@ class ToolPermissionGuardrail(CustomGuardrail): ) def _returned_call_names(self, data: Mapping[str, object]) -> Mapping[str, tuple[str, ...]]: - member_names: Final = tuple( - chain.from_iterable(map(self._bare_member_names, _sent_tools(_REQUEST_DATA.validate_python(data)))) - ) + sent_tools: Final = _sent_tools(_REQUEST_DATA.validate_python(data)) + member_names: Final = tuple(chain.from_iterable(map(self._bare_member_names, sent_tools))) if not member_names: return MappingProxyType({}) + top_level_names: Final = self._tool_names_in(tuple(tool for tool in sent_tools if not _is_namespace(tool))) + member_bare_names: Final = _grouped_values( + (bare, name) for name, bare in member_names if bare not in top_level_names + ) listed: Final = frozenset(name for name, _ in self._collect_request_tools(data) if name is not None) return MappingProxyType( - { - bare: (*qualified, *((bare,) if bare in listed else ())) - for bare, qualified in _grouped_values((bare, name) for name, bare in member_names).items() - } + {bare: (*qualified, *((bare,) if bare in listed else ())) for bare, qualified in member_bare_names.items()} ) def _judged_name(self, tool_call: ChatCompletionMessageToolCall, bare: str, name: str) -> str: @@ -1156,7 +1163,7 @@ class ToolPermissionGuardrail(CustomGuardrail): return None if isinstance(function_call, str): return function_call - return self._get_mapping_value(function_call, "name") + return _non_empty_string(self._get_mapping_value(function_call, "name")) def _listed_layer_targets(self, layer: Mapping[str, object]) -> tuple[_ToolTarget, ...]: return ( diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index 0afd10d08ab..6c02bdab6a0 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -1845,6 +1845,25 @@ def test_vertex_ai_map_tools_declares_a_repeated_member_name_once_and_never_a_na assert [declaration["name"] for declaration in mapped[0]["function_declarations"]] == ["get_weather"] +@pytest.mark.parametrize("namespace_first", [True, False], ids=["namespace_first", "top_level_first"]) +def test_vertex_ai_map_tools_declares_a_top_level_function_over_a_namespace_member_with_its_name( + namespace_first: bool, +) -> None: + member = {"type": "function", "name": "lookup", "parameters": {"type": "object", "properties": {"city": {}}}} + top_level = { + "type": "function", + "function": {"name": "lookup", "parameters": {"type": "object", "properties": {"country": {}}}}, + } + namespace = {"type": "namespace", "name": "mcp__weather", "tools": [member]} + tools = [namespace, top_level] if namespace_first else [top_level, namespace] + + mapped = VertexGeminiConfig().map_function(value=tools, optional_params={}) + + declarations = mapped[0]["function_declarations"] + assert [declaration["name"] for declaration in declarations] == ["lookup"] + assert set(declarations[0]["parameters"]["properties"]) == {"country"} + + def test_vertex_ai_map_tools_keeps_repeated_chat_tools_when_no_namespace_is_sent() -> None: function = {k: v for k, v in _GET_WEATHER.items() if k != "type"} diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index e305c803789..554d41a8cec 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -565,6 +565,37 @@ class TestToolPermissionGuardrail: assert [call.function.name for call in message.tool_calls or ()] == [] assert "Tool 'exec'" in (message.content or "") + @pytest.mark.asyncio + @pytest.mark.parametrize("namespace_first", [True, False], ids=["namespace_first", "top_level_first"]) + async def test_post_call_judges_a_returned_name_a_top_level_function_carries_as_that_function( + self, namespace_first: bool + ) -> None: + guardrail = ToolPermissionGuardrail( + guardrail_name="post-mcp", + rules=[{"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}], + default_action="allow", + on_disallowed_action="rewrite", + event_hook=GuardrailEventHooks.post_call, + ) + namespace = {"type": "namespace", "name": "mcp__weather", "tools": [{"type": "function", "name": "lookup"}]} + top_level = {"type": "function", "function": {"name": "lookup"}} + tools = [namespace, top_level] if namespace_first else [top_level, namespace] + function = Function(name="lookup", arguments='{"country": "France"}') + response = ModelResponse( + choices=[ + Choices( + finish_reason="tool_calls", + message={"tool_calls": [{"id": "call_lookup", "type": "function", "function": function}]}, + ) + ] + ) + + await guardrail.async_post_call_success_hook( + data={"guardrails": ["post-mcp"], "tools": tools}, user_api_key_dict=UserAPIKeyAuth(), response=response + ) + + assert [call.function.name for call in response.choices[0].message.tool_calls or ()] == ["lookup"] + @pytest.mark.asyncio async def test_async_post_call_success_hook_missing_arguments_blocks_param_rule( self, @@ -1634,6 +1665,33 @@ class TestToolPermissionGuardrailAnthropicMessages: assert result["tools"] == [{**partly_denied, "tools": partly_denied["tools"][:1]}] + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("call_type", "malformed"), + [ + ( + "agenerate_content", + {"toolConfig": {"functionCallingConfig": {"mode": "ANY", "allowedFunctionNames": [{"a": 1}]}}}, + ), + ("responses", {"input": [{"type": {"x": 1}, "content": "hi"}]}), + ("acompletion", {"extra_body": {"input": [{"type": [1]}]}}), + ("acompletion", {"extra_body": {"function_call": {"name": 5}}}), + ], + ids=["unhashable_allowed_function_name", "unhashable_input_type", "extra_body_input_type", "int_function_call"], + ) + async def test_pre_call_rewrite_leaves_a_malformed_value_for_the_provider_to_reject( + self, call_type: CallTypesLiteral, malformed: dict[str, object] + ) -> None: + guardrail = self._pre_call( + [{"id": "allow_weather", "tool_name": r"^get_weather$", "decision": "allow"}], "rewrite", "deny" + ) + tools = [{"type": "function", "function": {"name": name}} for name in ("get_weather", "shell")] + + result = await self._run_pre_call(guardrail, {"model": "m", "tools": tools, **malformed}, call_type) + + assert result["tools"] == tools[:1] + assert {key: result[key] for key in malformed} == malformed + @pytest.mark.asyncio @pytest.mark.parametrize( ("rule", "tool", "call_type", "detection_message"), From 3f45c3092367ff6ffc965966261b86a1d61bc30d Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 3 Nov 2026 04:40:42 -0800 Subject: [PATCH 33/39] fix(guardrails): judge a returned namespace member named like a hosted MCP server as that member --- .../guardrail_hooks/tool_permission.py | 6 ++- .../guardrail_hooks/test_tool_permission.py | 38 +++++++++++++++++++ 2 files changed, 43 insertions(+), 1 deletion(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index b3f6fe5f9f8..6959606945d 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -996,7 +996,7 @@ class ToolPermissionGuardrail(CustomGuardrail): member_names: Final = tuple(chain.from_iterable(map(self._bare_member_names, sent_tools))) if not member_names: return MappingProxyType({}) - top_level_names: Final = self._tool_names_in(tuple(tool for tool in sent_tools if not _is_namespace(tool))) + top_level_names: Final = self._function_names_in(tuple(tool for tool in sent_tools if not _is_namespace(tool))) member_bare_names: Final = _grouped_values( (bare, name) for name, bare in member_names if bare not in top_level_names ) @@ -1242,6 +1242,10 @@ class ToolPermissionGuardrail(CustomGuardrail): targets: Final = chain.from_iterable(self._get_request_tool_targets(tool) for tool in tools) return frozenset(name for name, _ in targets if name is not None) + def _function_names_in(self, tools: Sequence[object]) -> frozenset[str]: + targets: Final = chain.from_iterable(self._get_request_tool_targets(tool) for tool in tools) + return frozenset(name for name, kind in targets if name is not None and kind not in _HOSTED_SERVER_NAME_FIELDS) + def _referable_names_in(self, tools: Sequence[object]) -> frozenset[str]: member_names: Final = chain.from_iterable(map(self._bare_member_names, tools)) namespace_names: Final = (_member_name(tool) for tool in tools if _namespace_members(tool)) diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 554d41a8cec..0af0f3bfed4 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -596,6 +596,44 @@ class TestToolPermissionGuardrail: assert [call.function.name for call in response.choices[0].message.tool_calls or ()] == ["lookup"] + @pytest.mark.asyncio + @pytest.mark.parametrize( + "hosted_server", + [ + {"type": "mcp", "server_label": "lookup", "server_url": "https://mcp.example.com/sse"}, + {"type": "mcp_toolset", "mcp_server_name": "lookup"}, + ], + ids=["mcp", "mcp_toolset"], + ) + async def test_post_call_judges_a_returned_namespace_member_named_like_a_hosted_mcp_server_as_that_member( + self, hosted_server: dict[str, str] + ) -> None: + guardrail = ToolPermissionGuardrail( + guardrail_name="post-mcp", + rules=[{"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}], + default_action="allow", + on_disallowed_action="rewrite", + event_hook=GuardrailEventHooks.post_call, + ) + namespace = {"type": "namespace", "name": "mcp__weather", "tools": [{"type": "function", "name": "lookup"}]} + function = Function(name="lookup", arguments='{"country": "France"}') + response = ModelResponse( + choices=[ + Choices( + finish_reason="tool_calls", + message={"tool_calls": [{"id": "call_lookup", "type": "function", "function": function}]}, + ) + ] + ) + + await guardrail.async_post_call_success_hook( + data={"guardrails": ["post-mcp"], "tools": [namespace, hosted_server]}, + user_api_key_dict=UserAPIKeyAuth(), + response=response, + ) + + assert [call.function.name for call in response.choices[0].message.tool_calls or ()] == [] + @pytest.mark.asyncio async def test_async_post_call_success_hook_missing_arguments_blocks_param_rule( self, From 6d83d4d7451fd755852ae5fb057ce57c777f8f61 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 3 Nov 2026 08:28:49 -0800 Subject: [PATCH 34/39] fix(gemini,guardrails): send a namespace as main did when another tool has a member's name Gemini chat inlines a namespace's members only when no other tool, namespace member, or legacy functions entry declares the same name, and otherwise sends the namespace by its own name as main did. A tool_choice naming such a namespace forces the namespace itself. The tool permission post_call reads top-level names the way Gemini declares them and judges a call the Responses bridge tags with a namespace as that member. --- litellm/litellm_core_utils/tool_fields.py | 11 ++- .../vertex_and_google_ai_studio_gemini.py | 74 +++++++++++-------- .../guardrail_hooks/tool_permission.py | 25 +++++-- ...test_vertex_and_google_ai_studio_gemini.py | 64 ++++++++-------- .../guardrail_hooks/test_tool_permission.py | 46 ++++++++++-- 5 files changed, 146 insertions(+), 74 deletions(-) diff --git a/litellm/litellm_core_utils/tool_fields.py b/litellm/litellm_core_utils/tool_fields.py index 5ee96ea9133..0ba3ac05ad6 100644 --- a/litellm/litellm_core_utils/tool_fields.py +++ b/litellm/litellm_core_utils/tool_fields.py @@ -10,7 +10,7 @@ from typing_extensions import ReadOnly, TypedDict import litellm from litellm._logging import verbose_logger from litellm.exceptions import UnsupportedParamsError -from litellm.litellm_core_utils.core_helpers import drops_unsupported_params, normalize_drop_params +from litellm.litellm_core_utils.core_helpers import as_str_mapping, drops_unsupported_params, normalize_drop_params ROUTES_WITH_TOOLS: Final = frozenset( { @@ -58,6 +58,15 @@ _TOOL_ENTRY: Final = TypeAdapter(_ToolEntry) _WEB_SEARCH_OPTIONS: Final = TypeAdapter(dict[str, object] | None, config=ConfigDict(strict=True)) +def declared_function_name(tool: object) -> str | None: + fields: Final = as_str_mapping(tool) + if fields is None: + return None + function: Final = as_str_mapping(fields.get("function")) + name: Final = (fields if function is None else function).get("name") + return name if isinstance(name, str) and name else None + + @dataclass(frozen=True, slots=True) class DropPolicy: drop_params: bool diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index 4127e100c65..42fa5eb0451 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -35,7 +35,7 @@ from litellm.litellm_core_utils.json_fragment_accumulator import JSONFragmentAcc from litellm.litellm_core_utils.model_param_helper import embeds_thought_signature_in_tool_call_id from litellm.litellm_core_utils.prompt_templates.factory import encode_tool_call_id_with_signature from litellm.litellm_core_utils.reasoning_effort_utils import warn_dropped_reasoning -from litellm.litellm_core_utils.tool_fields import tool_params_without_hosted_mcp +from litellm.litellm_core_utils.tool_fields import declared_function_name, tool_params_without_hosted_mcp from litellm.llms.base_llm.chat.transformation import BaseConfig, BaseLLMException from litellm.llms.custom_httpx.http_handler import ( AsyncHTTPHandler, @@ -561,51 +561,50 @@ def _namespace_members_or_tool(tool: JsonValue) -> tuple[JsonValue, ...]: return tuple(map(_as_chat_tool, members)) if isinstance(members, list) else () -def _declared_function_name(tool: JsonValue) -> str | None: - if not isinstance(tool, dict): - return None - function: Final = tool.get("function") - name: Final = function.get("name") if isinstance(function, dict) else tool.get("name") - return name if isinstance(name, str) else None - - def _is_namespace(tool: JsonValue) -> bool: return isinstance(tool, dict) and tool.get("type") == "namespace" -def _declarations_with_origin(tool: JsonValue) -> tuple[tuple[JsonValue, bool], ...]: - return tuple((declaration, _is_namespace(tool)) for declaration in _namespace_members_or_tool(tool)) +def _listed(tools: JsonValue) -> tuple[JsonValue, ...]: + return tuple(tools) if isinstance(tools, list) else () -def _declaration_precedence(entry: tuple[int, tuple[JsonValue, bool]]) -> tuple[bool, int]: - index, (_, from_namespace) = entry - return (from_namespace, index) +def _declarable_names(tool: JsonValue) -> tuple[str | None, ...]: + members: Final = _namespace_members_or_tool(tool) if _is_namespace(tool) else () + return (declared_function_name(tool), *map(declared_function_name, members)) -def _kept_declarations(entries: tuple[tuple[JsonValue, bool], ...]) -> tuple[JsonValue, ...]: - names: Final = tuple(_declared_function_name(declaration) for declaration, _ in entries) - by_precedence: Final = tuple(sorted(enumerate(entries), key=_declaration_precedence, reverse=True)) - kept_index: Final = {names[index]: index for index, _ in by_precedence} - return tuple( - declaration - for index, (declaration, _) in enumerate(entries) - if names[index] is None or kept_index[names[index]] == index +def _declarable_names_in(tools: tuple[JsonValue, ...]) -> tuple[str | None, ...]: + return tuple(chain.from_iterable(map(_declarable_names, tools))) + + +def _inlines_members(tool: JsonValue, declarable: tuple[str | None, ...]) -> bool: + members: Final = _namespace_members_or_tool(tool) + return _is_namespace(tool) and all( + name is None or declarable.count(name) == 1 for name in map(declared_function_name, members) ) -def _with_namespace_members_inlined(tools: JsonValue) -> JsonValue: +def _with_namespace_members_inlined(tools: JsonValue, outside_declarations: JsonValue = None) -> JsonValue: if not isinstance(tools, list) or not any(map(_is_namespace, tools)): return tools - return list(_kept_declarations(tuple(chain.from_iterable(map(_declarations_with_origin, tools))))) + declarable: Final = _declarable_names_in((*tools, *_listed(outside_declarations))) + return list( + chain.from_iterable( + _namespace_members_or_tool(tool) if _inlines_members(tool, declarable) else (tool,) for tool in tools + ) + ) def _forced_function_names(name: str, tools: JsonValue) -> tuple[str, ...]: - candidates: Final = tools if isinstance(tools, list) else [] - if any(not _is_namespace(tool) and _declared_function_name(tool) == name for tool in candidates): + candidates: Final = _listed(tools) + if any(not _is_namespace(tool) and declared_function_name(tool) == name for tool in candidates): return (name,) named: Final = next((tool for tool in candidates if _is_namespace(tool) and _member_name_of(tool) == name), None) - members: Final = map(_declared_function_name, _namespace_members_or_tool(named)) if named is not None else () - return tuple(dict.fromkeys(member for member in members if member is not None)) or (name,) + if named is None or not _inlines_members(named, _declarable_names_in(candidates)): + return (name,) + members: Final = map(declared_function_name, _namespace_members_or_tool(named)) + return tuple(member for member in members if member is not None) or (name,) def _member_name_of(tool: JsonValue) -> JsonValue: @@ -1140,7 +1139,13 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig): return googleSearch, googleSearchRetrieval, enterpriseWebSearch, urlContext - def _map_function(self, value: list[dict], optional_params: dict, send_integer_enums: bool = False) -> list[Tools]: + def _map_function( + self, + value: list[dict], + optional_params: dict, + send_integer_enums: bool = False, + outside_declarations: JsonValue = None, + ) -> list[Tools]: """ Map OpenAI-style tools/functions to Vertex AI format. @@ -1171,7 +1176,7 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig): # remove 'strict' from tools remove_strict_from_schema(schema_value) - inlined_tools: Final = _with_namespace_members_inlined(schema_value) + inlined_tools: Final = _with_namespace_members_inlined(schema_value, outside_declarations) for tool in cast(list[dict], inlined_tools): # cast-ok: a deep copy keeps the caller's tool shape openai_function_object: ChatCompletionToolParamFunctionChunk | None = None if "function" in tool: # tools list @@ -1807,7 +1812,12 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig): elif (param == "tools" or param == "functions") and isinstance(value, list) and value: # Pass optional_params so _map_function can add toolConfig if needed mapped_tools = with_integer_enums_that_fit( - partial(self._map_function, value, optional_params), + partial( + self._map_function, + value, + optional_params, + outside_declarations=request_params.get("functions" if param == "tools" else "tools"), + ), allow_integer_enums and self._is_gemini_3_or_newer(model), ) optional_params = self._add_tools_to_optional_params(optional_params, mapped_tools) @@ -1815,7 +1825,7 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig): _tool_choice_value = self.map_tool_choice_values( model=model, tool_choice=value, - tools=non_default_params.get("tools", non_default_params.get("functions")), + tools=[*_listed(non_default_params.get("tools")), *_listed(non_default_params.get("functions"))], ) if _tool_choice_value is not None: optional_params["tool_choice"] = _tool_choice_value diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 6959606945d..1ea05810b83 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -22,6 +22,8 @@ from litellm.integrations.custom_guardrail import ( CustomGuardrail, log_guardrail_information, ) +from litellm.litellm_core_utils.core_helpers import as_str_mapping, attribute_or_none +from litellm.litellm_core_utils.tool_fields import declared_function_name from litellm.llms.base_llm.guardrail_translation.utils import anthropic_tool_names from litellm.proxy._types import UserAPIKeyAuth from litellm.proxy.common_utils.callback_utils import ( @@ -165,6 +167,20 @@ def _qualified_member_name(namespace: str, name: str) -> str: return f"{namespace}__{name}" +def _returned_namespace(tool_call: ChatCompletionMessageToolCall) -> str | None: + tags: Final = as_str_mapping(attribute_or_none(tool_call, "provider_specific_fields")) + return _non_empty_string(tags.get("namespace")) if tags is not None else None + + +def _judged_call_names( + tool_call: ChatCompletionMessageToolCall, returned_name: str, judged_names: Mapping[str, tuple[str, ...]] +) -> tuple[str, ...]: + namespace: Final = _returned_namespace(tool_call) + if namespace is not None: + return (_qualified_member_name(namespace, returned_name),) + return judged_names.get(returned_name, ()) + + def _qualified_target(namespace: str | None, target: _ToolTarget) -> _ToolTarget: name, tool_type = target return ( @@ -996,7 +1012,8 @@ class ToolPermissionGuardrail(CustomGuardrail): member_names: Final = tuple(chain.from_iterable(map(self._bare_member_names, sent_tools))) if not member_names: return MappingProxyType({}) - top_level_names: Final = self._function_names_in(tuple(tool for tool in sent_tools if not _is_namespace(tool))) + top_level_tools: Final = (tool for tool in sent_tools if not _is_namespace(tool)) + top_level_names: Final = frozenset(name for name in map(declared_function_name, top_level_tools) if name) member_bare_names: Final = _grouped_values( (bare, name) for name, bare in member_names if bare not in top_level_names ) @@ -1012,7 +1029,7 @@ class ToolPermissionGuardrail(CustomGuardrail): self, tool_call: ChatCompletionMessageToolCall, judged_names: Mapping[str, tuple[str, ...]] ) -> tuple[bool, str | None, str | None]: returned_name: Final = tool_call.function.name if tool_call.function else None - names: Final = judged_names.get(returned_name, ()) if returned_name is not None else () + names: Final = _judged_call_names(tool_call, returned_name, judged_names) if returned_name is not None else () if returned_name is None or not names: return self._get_permission_for_tool_call(tool_call) judged: Final = dict.fromkeys(self._judged_name(tool_call, returned_name, name) for name in names) @@ -1242,10 +1259,6 @@ class ToolPermissionGuardrail(CustomGuardrail): targets: Final = chain.from_iterable(self._get_request_tool_targets(tool) for tool in tools) return frozenset(name for name, _ in targets if name is not None) - def _function_names_in(self, tools: Sequence[object]) -> frozenset[str]: - targets: Final = chain.from_iterable(self._get_request_tool_targets(tool) for tool in tools) - return frozenset(name for name, kind in targets if name is not None and kind not in _HOSTED_SERVER_NAME_FIELDS) - def _referable_names_in(self, tools: Sequence[object]) -> frozenset[str]: member_names: Final = chain.from_iterable(map(self._bare_member_names, tools)) namespace_names: Final = (_member_name(tool) for tool in tools if _namespace_members(tool)) diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index 6c02bdab6a0..1e1eb678600 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -1823,45 +1823,43 @@ def test_vertex_ai_map_tools_declares_a_namespace_member_like_the_same_chat_tool _GET_WEATHER = {"type": "function", "name": "get_weather", "parameters": {"type": "object", "properties": {}}} +_WEATHER_NAMESPACE = {"type": "namespace", "name": "weather", "tools": [_GET_WEATHER]} +_TOP_LEVEL_GET_WEATHER = {"type": "function", "function": {k: v for k, v in _GET_WEATHER.items() if k != "type"}} + + @pytest.mark.parametrize( - "tools", + ("tools", "declared"), [ - [ - {"type": "namespace", "name": "forecast", "tools": [_GET_WEATHER]}, - {"type": "namespace", "name": "weather", "tools": [_GET_WEATHER]}, - ], - [ - {"type": "function", "function": {k: v for k, v in _GET_WEATHER.items() if k != "type"}}, - {"type": "namespace", "name": "weather", "tools": [_GET_WEATHER]}, - ], + ( + [{"type": "namespace", "name": "forecast", "tools": [_GET_WEATHER]}, _WEATHER_NAMESPACE], + ["forecast", "weather"], + ), + ([_TOP_LEVEL_GET_WEATHER, _WEATHER_NAMESPACE], ["get_weather", "weather"]), + ([_WEATHER_NAMESPACE, _TOP_LEVEL_GET_WEATHER], ["weather", "get_weather"]), ], - ids=["namespaces_share_a_member", "member_repeats_a_top_level_tool"], + ids=["namespaces_share_a_member", "top_level_first", "namespace_first"], ) -def test_vertex_ai_map_tools_declares_a_repeated_member_name_once_and_never_a_namespace_name( - tools: list[dict], +def test_vertex_ai_map_tools_declares_a_namespace_by_its_own_name_when_another_tool_declares_a_member_name( + tools: list[dict], declared: list[str] ) -> None: mapped = VertexGeminiConfig().map_function(value=tools, optional_params={}) - assert [declaration["name"] for declaration in mapped[0]["function_declarations"]] == ["get_weather"] + assert [declaration["name"] for declaration in mapped[0]["function_declarations"]] == declared -@pytest.mark.parametrize("namespace_first", [True, False], ids=["namespace_first", "top_level_first"]) -def test_vertex_ai_map_tools_declares_a_top_level_function_over_a_namespace_member_with_its_name( - namespace_first: bool, -) -> None: - member = {"type": "function", "name": "lookup", "parameters": {"type": "object", "properties": {"city": {}}}} - top_level = { - "type": "function", - "function": {"name": "lookup", "parameters": {"type": "object", "properties": {"country": {}}}}, - } - namespace = {"type": "namespace", "name": "mcp__weather", "tools": [member]} - tools = [namespace, top_level] if namespace_first else [top_level, namespace] +def test_vertex_ai_map_openai_params_declares_a_namespace_by_its_own_name_when_functions_repeat_a_member() -> None: + mapped = VertexGeminiConfig().map_openai_params( + non_default_params={ + "tools": [{"type": "namespace", "name": "mcp__weather", "tools": [{"type": "function", "name": "lookup"}]}], + "functions": [{"name": "lookup", "parameters": {"type": "object", "properties": {}}}], + }, + optional_params={}, + model="gemini-3.8-flash", + drop_params=False, + ) - mapped = VertexGeminiConfig().map_function(value=tools, optional_params={}) - - declarations = mapped[0]["function_declarations"] - assert [declaration["name"] for declaration in declarations] == ["lookup"] - assert set(declarations[0]["parameters"]["properties"]) == {"country"} + declared = [declaration["name"] for tool in mapped["tools"] for declaration in tool["function_declarations"]] + assert declared == ["mcp__weather", "lookup"] def test_vertex_ai_map_tools_keeps_repeated_chat_tools_when_no_namespace_is_sent() -> None: @@ -1881,8 +1879,14 @@ def test_vertex_ai_map_tools_keeps_repeated_chat_tools_when_no_namespace_is_sent ("github", [], ["create_issue", "close_issue"]), ("close_issue", [], ["close_issue"]), ("github", [{"type": "function", "function": {"name": "github"}}], ["github"]), + ("github", [{"type": "function", "function": {"name": "close_issue"}}], ["github"]), + ], + ids=[ + "names_the_namespace", + "names_a_member", + "names_a_function_sharing_the_namespace_name", + "names_a_namespace_whose_member_a_function_repeats", ], - ids=["names_the_namespace", "names_a_member", "names_a_function_sharing_the_namespace_name"], ) def test_vertex_ai_tool_choice_forces_only_functions_gemini_is_sent( forced_name: str, other_tools: list[dict[str, object]], allowed_function_names: list[str] diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 0af0f3bfed4..4f9b69679b3 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -598,15 +598,18 @@ class TestToolPermissionGuardrail: @pytest.mark.asyncio @pytest.mark.parametrize( - "hosted_server", + "same_named_tool", [ {"type": "mcp", "server_label": "lookup", "server_url": "https://mcp.example.com/sse"}, {"type": "mcp_toolset", "mcp_server_name": "lookup"}, + {"ignored": {"name": "lookup"}}, + {"type": "custom", "custom": {"name": "lookup"}}, + {"functionDeclarations": [{"name": "lookup"}]}, ], - ids=["mcp", "mcp_toolset"], + ids=["mcp", "mcp_toolset", "unknown_keyed_block", "chat_custom", "native_declaration"], ) - async def test_post_call_judges_a_returned_namespace_member_named_like_a_hosted_mcp_server_as_that_member( - self, hosted_server: dict[str, str] + async def test_post_call_judges_a_returned_namespace_member_as_that_member_beside_a_same_named_non_function( + self, same_named_tool: dict[str, object] ) -> None: guardrail = ToolPermissionGuardrail( guardrail_name="post-mcp", @@ -627,13 +630,46 @@ class TestToolPermissionGuardrail: ) await guardrail.async_post_call_success_hook( - data={"guardrails": ["post-mcp"], "tools": [namespace, hosted_server]}, + data={"guardrails": ["post-mcp"], "tools": [namespace, same_named_tool]}, user_api_key_dict=UserAPIKeyAuth(), response=response, ) assert [call.function.name for call in response.choices[0].message.tool_calls or ()] == [] + @pytest.mark.asyncio + async def test_post_call_judges_a_call_tagged_with_a_namespace_as_that_member_beside_a_same_named_function( + self, + ) -> None: + guardrail = ToolPermissionGuardrail( + guardrail_name="post-mcp", + rules=[{"id": "deny_mcp", "tool_name": r"^mcp__.*$", "decision": "deny"}], + default_action="allow", + on_disallowed_action="rewrite", + event_hook=GuardrailEventHooks.post_call, + ) + namespace = {"type": "namespace", "name": "mcp__weather", "tools": [{"type": "function", "name": "lookup"}]} + top_level = {"type": "function", "function": {"name": "lookup"}} + tagged_call = { + "id": "call_lookup", + "type": "function", + "function": Function(name="lookup", arguments='{"country": "France"}'), + "provider_specific_fields": {"namespace": "mcp__weather"}, + } + response = ModelResponse( + choices=[Choices(finish_reason="tool_calls", message={"tool_calls": [tagged_call]})] + ) + + await guardrail.async_post_call_success_hook( + data={"guardrails": ["post-mcp"], "tools": [namespace, top_level]}, + user_api_key_dict=UserAPIKeyAuth(), + response=response, + ) + + message = response.choices[0].message + assert [call.function.name for call in message.tool_calls or ()] == [] + assert "Tool 'mcp__weather__lookup' denied by rule 'deny_mcp'" in (message.content or "") + @pytest.mark.asyncio async def test_async_post_call_success_hook_missing_arguments_blocks_param_rule( self, From 07a6a211028b8f765befb53c9a6b2ba4c9987fed Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 3 Nov 2026 12:26:09 -0800 Subject: [PATCH 35/39] fix(gemini): send colliding namespace members as namespace__name functions and judge them in post_call When a namespace member shares a name with another tool, Gemini chat now gets that namespace's members as namespace__name functions instead of one function named after the namespace, so every function it can call is a name the rules judged. Declared names are counted once, and a forced member maps to each holder's qualified name. post_call judges a returned namespace__name as that member, by its qualified or bare name the way pre_call does, so a bare-name allowlist or denylist applies to it. --- litellm/litellm_core_utils/tool_fields.py | 4 ++ .../vertex_and_google_ai_studio_gemini.py | 54 +++++++++++++----- .../guardrail_hooks/tool_permission.py | 57 ++++++++++--------- ...test_vertex_and_google_ai_studio_gemini.py | 30 +++++++--- .../guardrail_hooks/test_tool_permission.py | 36 ++++++++++++ 5 files changed, 133 insertions(+), 48 deletions(-) diff --git a/litellm/litellm_core_utils/tool_fields.py b/litellm/litellm_core_utils/tool_fields.py index 0ba3ac05ad6..10b6f07bc4d 100644 --- a/litellm/litellm_core_utils/tool_fields.py +++ b/litellm/litellm_core_utils/tool_fields.py @@ -67,6 +67,10 @@ def declared_function_name(tool: object) -> str | None: return name if isinstance(name, str) and name else None +def qualified_member_name(namespace: str, name: str) -> str: + return f"{namespace}__{name}" + + @dataclass(frozen=True, slots=True) class DropPolicy: drop_params: bool diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index 42fa5eb0451..dac5cdf36cb 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -5,6 +5,7 @@ import json import re import threading import time +from collections import Counter from collections.abc import Awaitable, Callable, Mapping, Sequence from copy import deepcopy from functools import lru_cache, partial @@ -35,7 +36,11 @@ from litellm.litellm_core_utils.json_fragment_accumulator import JSONFragmentAcc from litellm.litellm_core_utils.model_param_helper import embeds_thought_signature_in_tool_call_id from litellm.litellm_core_utils.prompt_templates.factory import encode_tool_call_id_with_signature from litellm.litellm_core_utils.reasoning_effort_utils import warn_dropped_reasoning -from litellm.litellm_core_utils.tool_fields import declared_function_name, tool_params_without_hosted_mcp +from litellm.litellm_core_utils.tool_fields import ( + declared_function_name, + qualified_member_name, + tool_params_without_hosted_mcp, +) from litellm.llms.base_llm.chat.transformation import BaseConfig, BaseLLMException from litellm.llms.custom_httpx.http_handler import ( AsyncHTTPHandler, @@ -578,33 +583,56 @@ def _declarable_names_in(tools: tuple[JsonValue, ...]) -> tuple[str | None, ...] return tuple(chain.from_iterable(map(_declarable_names, tools))) -def _inlines_members(tool: JsonValue, declarable: tuple[str | None, ...]) -> bool: +def _inlines_members(tool: JsonValue, declarable: Counter[str | None]) -> bool: members: Final = _namespace_members_or_tool(tool) return _is_namespace(tool) and all( - name is None or declarable.count(name) == 1 for name in map(declared_function_name, members) + name is None or declarable[name] == 1 for name in map(declared_function_name, members) ) +def _qualified_member(namespace: str, member: JsonValue) -> JsonValue: + function: Final = member.get("function") if isinstance(member, dict) else None + name: Final = declared_function_name(member) + if not isinstance(member, dict) or not isinstance(function, dict) or name is None: + return member + return {**member, "function": {**function, "name": qualified_member_name(namespace, name)}} + + +def _as_declared(tool: JsonValue, declarable: Counter[str | None]) -> tuple[JsonValue, ...]: + if _inlines_members(tool, declarable): + return _namespace_members_or_tool(tool) + namespace: Final = declared_function_name(tool) + if not _is_namespace(tool) or namespace is None: + return (tool,) + return tuple(_qualified_member(namespace, member) for member in _namespace_members_or_tool(tool)) + + def _with_namespace_members_inlined(tools: JsonValue, outside_declarations: JsonValue = None) -> JsonValue: if not isinstance(tools, list) or not any(map(_is_namespace, tools)): return tools - declarable: Final = _declarable_names_in((*tools, *_listed(outside_declarations))) - return list( - chain.from_iterable( - _namespace_members_or_tool(tool) if _inlines_members(tool, declarable) else (tool,) for tool in tools - ) - ) + declarable: Final = Counter(_declarable_names_in((*tools, *_listed(outside_declarations)))) + return list(chain.from_iterable(_as_declared(tool, declarable) for tool in tools)) + + +def _qualified_names_of(member_name: str, tool: JsonValue, declarable: Counter[str | None]) -> tuple[str, ...]: + namespace: Final = declared_function_name(tool) + holds_member: Final = member_name in map(declared_function_name, _namespace_members_or_tool(tool)) + if not _is_namespace(tool) or namespace is None or not holds_member or _inlines_members(tool, declarable): + return () + return (qualified_member_name(namespace, member_name),) def _forced_function_names(name: str, tools: JsonValue) -> tuple[str, ...]: candidates: Final = _listed(tools) if any(not _is_namespace(tool) and declared_function_name(tool) == name for tool in candidates): return (name,) + declarable: Final = Counter(_declarable_names_in(candidates)) named: Final = next((tool for tool in candidates if _is_namespace(tool) and _member_name_of(tool) == name), None) - if named is None or not _inlines_members(named, _declarable_names_in(candidates)): - return (name,) - members: Final = map(declared_function_name, _namespace_members_or_tool(named)) - return tuple(member for member in members if member is not None) or (name,) + if named is not None: + declared: Final = map(declared_function_name, _as_declared(named, declarable)) + return tuple(member for member in declared if member is not None) or (name,) + qualified: Final = chain.from_iterable(_qualified_names_of(name, tool, declarable) for tool in candidates) + return tuple(qualified) or (name,) def _member_name_of(tool: JsonValue) -> JsonValue: diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index 1ea05810b83..e93a7ceb6cb 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -5,7 +5,7 @@ from dataclasses import dataclass from functools import partial, reduce from itertools import chain, groupby from types import MappingProxyType -from typing import Any, Final, Literal, TypeAlias, TypedDict +from typing import Any, Final, Literal, TypeAlias, TypedDict, TypeVar from fastapi import HTTPException from pydantic import TypeAdapter @@ -23,7 +23,7 @@ from litellm.integrations.custom_guardrail import ( log_guardrail_information, ) from litellm.litellm_core_utils.core_helpers import as_str_mapping, attribute_or_none -from litellm.litellm_core_utils.tool_fields import declared_function_name +from litellm.litellm_core_utils.tool_fields import declared_function_name, qualified_member_name from litellm.llms.base_llm.guardrail_translation.utils import anthropic_tool_names from litellm.proxy._types import UserAPIKeyAuth from litellm.proxy.common_utils.callback_utils import ( @@ -74,6 +74,8 @@ _NAMED_CHOICE_TYPES: Final = frozenset({"tool", "function", "custom", "allowed_t _DECODED_ARGUMENTS: Final = TypeAdapter(object) _REQUEST_DATA: Final = TypeAdapter(object) _ToolTarget: TypeAlias = tuple[str | None, str | None] +_JudgedCalls: TypeAlias = Mapping[str, tuple[tuple[str, str], ...]] +_GroupedT: Final = TypeVar("_GroupedT") def _snake_case(name: str) -> str: @@ -163,29 +165,23 @@ def _namespace_members(tool: object) -> Sequence[object]: return members or () -def _qualified_member_name(namespace: str, name: str) -> str: - return f"{namespace}__{name}" - - def _returned_namespace(tool_call: ChatCompletionMessageToolCall) -> str | None: tags: Final = as_str_mapping(attribute_or_none(tool_call, "provider_specific_fields")) return _non_empty_string(tags.get("namespace")) if tags is not None else None def _judged_call_names( - tool_call: ChatCompletionMessageToolCall, returned_name: str, judged_names: Mapping[str, tuple[str, ...]] -) -> tuple[str, ...]: + tool_call: ChatCompletionMessageToolCall, returned_name: str, judged_names: _JudgedCalls +) -> tuple[tuple[str, str], ...]: namespace: Final = _returned_namespace(tool_call) if namespace is not None: - return (_qualified_member_name(namespace, returned_name),) + return ((qualified_member_name(namespace, returned_name), returned_name),) return judged_names.get(returned_name, ()) def _qualified_target(namespace: str | None, target: _ToolTarget) -> _ToolTarget: name, tool_type = target - return ( - (_qualified_member_name(namespace, name), tool_type) if namespace is not None and name is not None else target - ) + return (qualified_member_name(namespace, name), tool_type) if namespace is not None and name is not None else target def _member_name(member: object) -> str | None: @@ -257,11 +253,11 @@ def _carries_tools(items: Sequence[object]) -> bool: return any(_input_item_tools(item) is not None for item in items) -def _pair_key(pair: tuple[str, str]) -> str: +def _pair_key(pair: tuple[str, object]) -> str: return pair[0] -def _grouped_values(pairs: Iterable[tuple[str, str]]) -> Mapping[str, tuple[str, ...]]: +def _grouped_values(pairs: Iterable[tuple[str, _GroupedT]]) -> Mapping[str, tuple[_GroupedT, ...]]: groups: Final = groupby(sorted(pairs, key=_pair_key), key=_pair_key) return MappingProxyType({key: tuple(dict.fromkeys(value for _, value in group)) for key, group in groups}) @@ -1007,37 +1003,44 @@ class ToolPermissionGuardrail(CustomGuardrail): tool_call for block in content if (tool_call := self._anthropic_tool_use_to_tool_call(block)) is not None ) - def _returned_call_names(self, data: Mapping[str, object]) -> Mapping[str, tuple[str, ...]]: + def _returned_call_names(self, data: Mapping[str, object]) -> _JudgedCalls: sent_tools: Final = _sent_tools(_REQUEST_DATA.validate_python(data)) member_names: Final = tuple(chain.from_iterable(map(self._bare_member_names, sent_tools))) if not member_names: return MappingProxyType({}) top_level_tools: Final = (tool for tool in sent_tools if not _is_namespace(tool)) top_level_names: Final = frozenset(name for name in map(declared_function_name, top_level_tools) if name) - member_bare_names: Final = _grouped_values( - (bare, name) for name, bare in member_names if bare not in top_level_names - ) listed: Final = frozenset(name for name, _ in self._collect_request_tools(data) if name is not None) + own_names: Final = frozenset(bare for _, bare in member_names if bare in listed) | top_level_names + returned_members: Final = _grouped_values( + chain( + ((bare, (name, bare)) for name, bare in member_names if bare not in top_level_names), + ((name, (name, bare)) for name, bare in member_names), + ) + ) return MappingProxyType( - {bare: (*qualified, *((bare,) if bare in listed else ())) for bare, qualified in member_bare_names.items()} + { + name: (*members, *(((name, name),) if name in own_names else ())) + for name, members in returned_members.items() + } ) - def _judged_name(self, tool_call: ChatCompletionMessageToolCall, bare: str, name: str) -> str: - return name if name == bare else self._deciding_member_name(name, bare, "function", tool_call) + def _judged_name(self, tool_call: ChatCompletionMessageToolCall, qualified: str, bare: str) -> str: + return qualified if qualified == bare else self._deciding_member_name(qualified, bare, "function", tool_call) def _judge_tool_call( - self, tool_call: ChatCompletionMessageToolCall, judged_names: Mapping[str, tuple[str, ...]] + self, tool_call: ChatCompletionMessageToolCall, judged_names: _JudgedCalls ) -> tuple[bool, str | None, str | None]: returned_name: Final = tool_call.function.name if tool_call.function else None names: Final = _judged_call_names(tool_call, returned_name, judged_names) if returned_name is not None else () if returned_name is None or not names: return self._get_permission_for_tool_call(tool_call) - judged: Final = dict.fromkeys(self._judged_name(tool_call, returned_name, name) for name in names) + judged: Final = dict.fromkeys(self._judged_name(tool_call, qualified, bare) for qualified, bare in names) results: Final = tuple(self._get_permission_for_tool_call(tool_call, name) for name in judged) return next((result for result in results if not result[0]), results[0]) def _evaluate_tool_calls( - self, tool_calls: Sequence[ChatCompletionMessageToolCall], judged_names: Mapping[str, tuple[str, ...]] + self, tool_calls: Sequence[ChatCompletionMessageToolCall], judged_names: _JudgedCalls ) -> tuple[tuple[ChatCompletionMessageToolCall, PermissionError], ...]: checked: Final = tuple((tool_call, *self._judge_tool_call(tool_call, judged_names)) for tool_call in tool_calls) @@ -1122,7 +1125,7 @@ class ToolPermissionGuardrail(CustomGuardrail): if namespace is None or not members: return () targets: Final = chain.from_iterable(map(self._unqualified_member_targets, members)) - return tuple((_qualified_member_name(namespace, name), name) for name, _ in targets if name is not None) + return tuple((qualified_member_name(namespace, name), name) for name, _ in targets if name is not None) def _get_request_tool_targets(self, tool: object) -> tuple[_ToolTarget, ...]: group: Final = _member_group(tool, self._namespace_member_targets) @@ -1669,7 +1672,7 @@ class ToolPermissionGuardrail(CustomGuardrail): self, anthropic_response: ModelResponse, source_chunks: Sequence[object], - judged_names: Mapping[str, tuple[str, ...]], + judged_names: _JudgedCalls, ) -> Sequence[object]: """The frames the client gets: on a failed upstream only what the check read, never the upstream's own. @@ -1684,7 +1687,7 @@ class ToolPermissionGuardrail(CustomGuardrail): return anthropic_sse_chunks_from_response(anthropic_response, source_chunks, keep_explanations=True) def _check_assembled_stream( - self, assembled: ModelResponse, judged_names: Mapping[str, tuple[str, ...]] + self, assembled: ModelResponse, judged_names: _JudgedCalls ) -> tuple[tuple[ChatCompletionMessageToolCall, PermissionError], ...]: verbose_proxy_logger.debug("Tool Permission Guardrail: Checking response") tool_calls: Final = self._extract_tool_calls_from_response(assembled) diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index 1e1eb678600..e33335aa431 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -1832,14 +1832,18 @@ _TOP_LEVEL_GET_WEATHER = {"type": "function", "function": {k: v for k, v in _GET [ ( [{"type": "namespace", "name": "forecast", "tools": [_GET_WEATHER]}, _WEATHER_NAMESPACE], - ["forecast", "weather"], + ["forecast__get_weather", "weather__get_weather"], + ), + ([_TOP_LEVEL_GET_WEATHER, _WEATHER_NAMESPACE], ["get_weather", "weather__get_weather"]), + ([_WEATHER_NAMESPACE, _TOP_LEVEL_GET_WEATHER], ["weather__get_weather", "get_weather"]), + ( + [{"type": "namespace", "name": "delete_db", "tools": [_GET_WEATHER, _GET_WEATHER]}], + ["delete_db__get_weather", "delete_db__get_weather"], ), - ([_TOP_LEVEL_GET_WEATHER, _WEATHER_NAMESPACE], ["get_weather", "weather"]), - ([_WEATHER_NAMESPACE, _TOP_LEVEL_GET_WEATHER], ["weather", "get_weather"]), ], - ids=["namespaces_share_a_member", "top_level_first", "namespace_first"], + ids=["namespaces_share_a_member", "top_level_first", "namespace_first", "namespace_repeats_a_member"], ) -def test_vertex_ai_map_tools_declares_a_namespace_by_its_own_name_when_another_tool_declares_a_member_name( +def test_vertex_ai_map_tools_declares_qualified_member_names_when_another_tool_declares_a_member_name( tools: list[dict], declared: list[str] ) -> None: mapped = VertexGeminiConfig().map_function(value=tools, optional_params={}) @@ -1847,7 +1851,7 @@ def test_vertex_ai_map_tools_declares_a_namespace_by_its_own_name_when_another_t assert [declaration["name"] for declaration in mapped[0]["function_declarations"]] == declared -def test_vertex_ai_map_openai_params_declares_a_namespace_by_its_own_name_when_functions_repeat_a_member() -> None: +def test_vertex_ai_map_openai_params_declares_qualified_member_names_when_functions_repeat_a_member() -> None: mapped = VertexGeminiConfig().map_openai_params( non_default_params={ "tools": [{"type": "namespace", "name": "mcp__weather", "tools": [{"type": "function", "name": "lookup"}]}], @@ -1859,7 +1863,7 @@ def test_vertex_ai_map_openai_params_declares_a_namespace_by_its_own_name_when_f ) declared = [declaration["name"] for tool in mapped["tools"] for declaration in tool["function_declarations"]] - assert declared == ["mcp__weather", "lookup"] + assert declared == ["mcp__weather__lookup", "lookup"] def test_vertex_ai_map_tools_keeps_repeated_chat_tools_when_no_namespace_is_sent() -> None: @@ -1879,13 +1883,23 @@ def test_vertex_ai_map_tools_keeps_repeated_chat_tools_when_no_namespace_is_sent ("github", [], ["create_issue", "close_issue"]), ("close_issue", [], ["close_issue"]), ("github", [{"type": "function", "function": {"name": "github"}}], ["github"]), - ("github", [{"type": "function", "function": {"name": "close_issue"}}], ["github"]), + ( + "github", + [{"type": "function", "function": {"name": "close_issue"}}], + ["github__create_issue", "github__close_issue"], + ), + ( + "close_issue", + [{"type": "namespace", "name": "gitlab", "tools": [{"type": "function", "name": "close_issue"}]}], + ["github__close_issue", "gitlab__close_issue"], + ), ], ids=[ "names_the_namespace", "names_a_member", "names_a_function_sharing_the_namespace_name", "names_a_namespace_whose_member_a_function_repeats", + "names_a_member_two_namespaces_share", ], ) def test_vertex_ai_tool_choice_forces_only_functions_gemini_is_sent( diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index 4f9b69679b3..a021625e49e 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -670,6 +670,42 @@ class TestToolPermissionGuardrail: assert [call.function.name for call in message.tool_calls or ()] == [] assert "Tool 'mcp__weather__lookup' denied by rule 'deny_mcp'" in (message.content or "") + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("decision", "default_action", "kept"), + [("allow", "deny", ["weather__get_weather"]), ("deny", "allow", [])], + ids=["bare_name_allowed", "bare_name_denied"], + ) + async def test_post_call_judges_a_returned_qualified_member_name_by_the_member_names_pre_call_judged( + self, decision: Literal["allow", "deny"], default_action: Literal["allow", "deny"], kept: list[str] + ) -> None: + guardrail = ToolPermissionGuardrail( + guardrail_name="post-weather", + rules=[{"id": "get_weather", "tool_name": r"^get_weather$", "decision": decision}], + default_action=default_action, + on_disallowed_action="rewrite", + event_hook=GuardrailEventHooks.post_call, + ) + namespace = {"type": "namespace", "name": "weather", "tools": [{"type": "function", "name": "get_weather"}]} + top_level = {"type": "function", "function": {"name": "get_weather"}} + function = Function(name="weather__get_weather", arguments='{"city": "Istanbul"}') + response = ModelResponse( + choices=[ + Choices( + finish_reason="tool_calls", + message={"tool_calls": [{"id": "call_weather", "type": "function", "function": function}]}, + ) + ] + ) + + await guardrail.async_post_call_success_hook( + data={"guardrails": ["post-weather"], "tools": [namespace, top_level]}, + user_api_key_dict=UserAPIKeyAuth(), + response=response, + ) + + assert [call.function.name for call in response.choices[0].message.tool_calls or ()] == kept + @pytest.mark.asyncio async def test_async_post_call_success_hook_missing_arguments_blocks_param_rule( self, From 427f2ce4e24d283b500e49dccf0d6ebb14d225ae Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 3 Nov 2026 13:21:40 -0800 Subject: [PATCH 36/39] fix(gemini): keep generated member names unique and let a top-level function own its exact name A namespace that listed a member twice, or a generated namespace__name that repeated a top-level function, sent Gemini two declarations with one name, and Gemini answered 400 where main answered 200. A name a namespace lists twice is now one member, and a top-level function keeps its exact name. post_call now judges a returned name a top-level function declares as that function, never as the namespace member the name could also mean. --- .../vertex_and_google_ai_studio_gemini.py | 35 ++++++++++-- .../guardrail_hooks/tool_permission.py | 2 +- ...test_vertex_and_google_ai_studio_gemini.py | 55 +++++++++++++++++-- .../guardrail_hooks/test_tool_permission.py | 31 +++++++++++ 4 files changed, 111 insertions(+), 12 deletions(-) diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index dac5cdf36cb..8fe3effbe7b 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -563,7 +563,19 @@ def _namespace_members_or_tool(tool: JsonValue) -> tuple[JsonValue, ...]: if not isinstance(tool, dict) or tool.get("type") != "namespace": return (tool,) members: Final = tool.get("tools") - return tuple(map(_as_chat_tool, members)) if isinstance(members, list) else () + return _members_named_once(tuple(map(_as_chat_tool, members))) if isinstance(members, list) else () + + +def _members_named_once( + members: tuple[JsonValue, ...], repeatable: frozenset[str] = frozenset() +) -> tuple[JsonValue, ...]: + names: Final = tuple(map(declared_function_name, members)) + first_index: Final = {name: index for index, name in reversed(tuple(enumerate(names)))} + return tuple( + member + for index, (member, name) in enumerate(zip(members, names, strict=True)) + if name is None or name in repeatable or first_index[name] == index + ) def _is_namespace(tool: JsonValue) -> bool: @@ -598,20 +610,31 @@ def _qualified_member(namespace: str, member: JsonValue) -> JsonValue: return {**member, "function": {**function, "name": qualified_member_name(namespace, name)}} -def _as_declared(tool: JsonValue, declarable: Counter[str | None]) -> tuple[JsonValue, ...]: +def _as_declared( + tool: JsonValue, declarable: Counter[str | None], top_level_names: frozenset[str] +) -> tuple[JsonValue, ...]: if _inlines_members(tool, declarable): return _namespace_members_or_tool(tool) namespace: Final = declared_function_name(tool) if not _is_namespace(tool) or namespace is None: return (tool,) - return tuple(_qualified_member(namespace, member) for member in _namespace_members_or_tool(tool)) + qualified: Final = (_qualified_member(namespace, member) for member in _namespace_members_or_tool(tool)) + return tuple(member for member in qualified if declared_function_name(member) not in top_level_names) + + +def _top_level_names_in(tools: tuple[JsonValue, ...]) -> frozenset[str]: + top_level_tools: Final = (tool for tool in tools if not _is_namespace(tool)) + return frozenset(name for name in map(declared_function_name, top_level_tools) if name is not None) def _with_namespace_members_inlined(tools: JsonValue, outside_declarations: JsonValue = None) -> JsonValue: if not isinstance(tools, list) or not any(map(_is_namespace, tools)): return tools - declarable: Final = Counter(_declarable_names_in((*tools, *_listed(outside_declarations)))) - return list(chain.from_iterable(_as_declared(tool, declarable) for tool in tools)) + candidates: Final = (*tools, *_listed(outside_declarations)) + declarable: Final = Counter(_declarable_names_in(candidates)) + top_level_names: Final = _top_level_names_in(candidates) + declared: Final = chain.from_iterable(_as_declared(tool, declarable, top_level_names) for tool in tools) + return list(_members_named_once(tuple(declared), top_level_names)) def _qualified_names_of(member_name: str, tool: JsonValue, declarable: Counter[str | None]) -> tuple[str, ...]: @@ -629,7 +652,7 @@ def _forced_function_names(name: str, tools: JsonValue) -> tuple[str, ...]: declarable: Final = Counter(_declarable_names_in(candidates)) named: Final = next((tool for tool in candidates if _is_namespace(tool) and _member_name_of(tool) == name), None) if named is not None: - declared: Final = map(declared_function_name, _as_declared(named, declarable)) + declared: Final = map(declared_function_name, _as_declared(named, declarable, frozenset())) return tuple(member for member in declared if member is not None) or (name,) qualified: Final = chain.from_iterable(_qualified_names_of(name, tool, declarable) for tool in candidates) return tuple(qualified) or (name,) diff --git a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py index e93a7ceb6cb..4d3fe39b91d 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py +++ b/litellm/proxy/guardrails/guardrail_hooks/tool_permission.py @@ -1015,7 +1015,7 @@ class ToolPermissionGuardrail(CustomGuardrail): returned_members: Final = _grouped_values( chain( ((bare, (name, bare)) for name, bare in member_names if bare not in top_level_names), - ((name, (name, bare)) for name, bare in member_names), + ((name, (name, bare)) for name, bare in member_names if name not in top_level_names), ) ) return MappingProxyType( diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index e33335aa431..1f7a457152d 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -1836,12 +1836,8 @@ _TOP_LEVEL_GET_WEATHER = {"type": "function", "function": {k: v for k, v in _GET ), ([_TOP_LEVEL_GET_WEATHER, _WEATHER_NAMESPACE], ["get_weather", "weather__get_weather"]), ([_WEATHER_NAMESPACE, _TOP_LEVEL_GET_WEATHER], ["weather__get_weather", "get_weather"]), - ( - [{"type": "namespace", "name": "delete_db", "tools": [_GET_WEATHER, _GET_WEATHER]}], - ["delete_db__get_weather", "delete_db__get_weather"], - ), ], - ids=["namespaces_share_a_member", "top_level_first", "namespace_first", "namespace_repeats_a_member"], + ids=["namespaces_share_a_member", "top_level_first", "namespace_first"], ) def test_vertex_ai_map_tools_declares_qualified_member_names_when_another_tool_declares_a_member_name( tools: list[dict], declared: list[str] @@ -1851,6 +1847,55 @@ def test_vertex_ai_map_tools_declares_qualified_member_names_when_another_tool_d assert [declaration["name"] for declaration in mapped[0]["function_declarations"]] == declared +def test_vertex_ai_map_tools_declares_a_member_a_namespace_lists_twice_once_from_its_first_entry() -> None: + first = {**_GET_WEATHER, "description": "Current weather"} + repeat = {**_GET_WEATHER, "description": "Forecast"} + namespace = {"type": "namespace", "name": "weather", "tools": [first, repeat]} + + mapped = VertexGeminiConfig().map_function(value=[namespace], optional_params={}) + + declarations = mapped[0]["function_declarations"] + assert [(declaration["name"], declaration["description"]) for declaration in declarations] == [ + ("get_weather", "Current weather") + ] + + +@pytest.mark.parametrize( + ("tools", "declared"), + [ + ( + [ + _WEATHER_NAMESPACE, + _TOP_LEVEL_GET_WEATHER, + {"type": "function", "function": {"name": "weather__get_weather", "description": "Top level"}}, + ], + [("get_weather", None), ("weather__get_weather", "Top level")], + ), + ( + [ + {"type": "namespace", "name": "mcp__ops", "tools": [{"type": "function", "name": "exec"}]}, + {"type": "namespace", "name": "mcp", "tools": [{"type": "function", "name": "ops__exec"}]}, + {"type": "function", "function": {"name": "exec"}}, + {"type": "function", "function": {"name": "ops__exec"}}, + ], + [("mcp__ops__exec", None), ("exec", None), ("ops__exec", None)], + ), + ( + [_TOP_LEVEL_GET_WEATHER, _TOP_LEVEL_GET_WEATHER, _WEATHER_NAMESPACE], + [("get_weather", None), ("get_weather", None), ("weather__get_weather", None)], + ), + ], + ids=["top_level_function_has_the_qualified_name", "namespaces_build_one_qualified_name", "client_repeats_a_function"], +) +def test_vertex_ai_map_tools_never_repeats_a_generated_name( + tools: list[dict], declared: list[tuple[str, str | None]] +) -> None: + mapped = VertexGeminiConfig().map_function(value=tools, optional_params={}) + + declarations = mapped[0]["function_declarations"] + assert [(declaration["name"], declaration.get("description")) for declaration in declarations] == declared + + def test_vertex_ai_map_openai_params_declares_qualified_member_names_when_functions_repeat_a_member() -> None: mapped = VertexGeminiConfig().map_openai_params( non_default_params={ diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py index a021625e49e..7d84c1ddb32 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/test_tool_permission.py @@ -706,6 +706,37 @@ class TestToolPermissionGuardrail: assert [call.function.name for call in response.choices[0].message.tool_calls or ()] == kept + @pytest.mark.asyncio + async def test_post_call_judges_a_top_level_function_by_its_own_name_beside_a_member_qualified_the_same( + self, + ) -> None: + guardrail = ToolPermissionGuardrail( + guardrail_name="post-exec", + rules=[{"id": "deny_exec", "tool_name": r"^exec$", "decision": "deny"}], + default_action="allow", + on_disallowed_action="rewrite", + event_hook=GuardrailEventHooks.post_call, + ) + namespace = {"type": "namespace", "name": "ops", "tools": [{"type": "function", "name": "exec"}]} + top_level = {"type": "function", "function": {"name": "ops__exec"}} + function = Function(name="ops__exec", arguments="{}") + response = ModelResponse( + choices=[ + Choices( + finish_reason="tool_calls", + message={"tool_calls": [{"id": "call_ops", "type": "function", "function": function}]}, + ) + ] + ) + + await guardrail.async_post_call_success_hook( + data={"guardrails": ["post-exec"], "tools": [namespace, top_level]}, + user_api_key_dict=UserAPIKeyAuth(), + response=response, + ) + + assert [call.function.name for call in response.choices[0].message.tool_calls or ()] == ["ops__exec"] + @pytest.mark.asyncio async def test_async_post_call_success_hook_missing_arguments_blocks_param_rule( self, From 3a0a30579e882c4440847a7974d00d135ebf335c Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 3 Nov 2026 13:47:58 -0800 Subject: [PATCH 37/39] fix(gemini): qualify namespace members by the namespace's top-level name The guardrail judges a member as `name__member` from the namespace's top-level name. Gemini built the name from `function.name` when the tool also carried one, so a request could pass pre-call and reach Gemini under a name no rule judged. --- .../vertex_and_google_ai_studio_gemini.py | 15 ++++++------ ...test_vertex_and_google_ai_studio_gemini.py | 23 +++++++++++++++++++ 2 files changed, 31 insertions(+), 7 deletions(-) diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index 8fe3effbe7b..03bfcaaf2ad 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -582,6 +582,11 @@ def _is_namespace(tool: JsonValue) -> bool: return isinstance(tool, dict) and tool.get("type") == "namespace" +def _top_level_name(tool: JsonValue) -> str | None: + name: Final = tool.get("name") if isinstance(tool, dict) else None + return name if isinstance(name, str) and name else None + + def _listed(tools: JsonValue) -> tuple[JsonValue, ...]: return tuple(tools) if isinstance(tools, list) else () @@ -615,7 +620,7 @@ def _as_declared( ) -> tuple[JsonValue, ...]: if _inlines_members(tool, declarable): return _namespace_members_or_tool(tool) - namespace: Final = declared_function_name(tool) + namespace: Final = _top_level_name(tool) if not _is_namespace(tool) or namespace is None: return (tool,) qualified: Final = (_qualified_member(namespace, member) for member in _namespace_members_or_tool(tool)) @@ -638,7 +643,7 @@ def _with_namespace_members_inlined(tools: JsonValue, outside_declarations: Json def _qualified_names_of(member_name: str, tool: JsonValue, declarable: Counter[str | None]) -> tuple[str, ...]: - namespace: Final = declared_function_name(tool) + namespace: Final = _top_level_name(tool) holds_member: Final = member_name in map(declared_function_name, _namespace_members_or_tool(tool)) if not _is_namespace(tool) or namespace is None or not holds_member or _inlines_members(tool, declarable): return () @@ -650,7 +655,7 @@ def _forced_function_names(name: str, tools: JsonValue) -> tuple[str, ...]: if any(not _is_namespace(tool) and declared_function_name(tool) == name for tool in candidates): return (name,) declarable: Final = Counter(_declarable_names_in(candidates)) - named: Final = next((tool for tool in candidates if _is_namespace(tool) and _member_name_of(tool) == name), None) + named: Final = next((tool for tool in candidates if _is_namespace(tool) and _top_level_name(tool) == name), None) if named is not None: declared: Final = map(declared_function_name, _as_declared(named, declarable, frozenset())) return tuple(member for member in declared if member is not None) or (name,) @@ -658,10 +663,6 @@ def _forced_function_names(name: str, tools: JsonValue) -> tuple[str, ...]: return tuple(qualified) or (name,) -def _member_name_of(tool: JsonValue) -> JsonValue: - return tool.get("name") if isinstance(tool, dict) else None - - class VertexAIBaseConfig: def get_mapped_special_auth_params(self) -> dict: """ diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index 1f7a457152d..b66ca48e1c5 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -1896,6 +1896,29 @@ def test_vertex_ai_map_tools_never_repeats_a_generated_name( assert [(declaration["name"], declaration.get("description")) for declaration in declarations] == declared +def test_vertex_ai_map_openai_params_qualifies_members_by_the_namespace_top_level_name() -> None: + namespace = { + "type": "namespace", + "name": "safe", + "function": {"name": "lookup"}, + "tools": [{"type": "function", "name": "lookup"}], + } + + mapped = VertexGeminiConfig().map_openai_params( + non_default_params={ + "tools": [namespace], + "tool_choice": {"type": "function", "function": {"name": "lookup"}}, + }, + optional_params={}, + model="gemini-3.8-flash", + drop_params=False, + ) + + declared = [declaration["name"] for tool in mapped["tools"] for declaration in tool["function_declarations"]] + assert declared == ["safe__lookup"] + assert mapped["tool_choice"]["functionCallingConfig"]["allowed_function_names"] == ["safe__lookup"] + + def test_vertex_ai_map_openai_params_declares_qualified_member_names_when_functions_repeat_a_member() -> None: mapped = VertexGeminiConfig().map_openai_params( non_default_params={ From 55037989763be6db6d1b0743a2d71221f32bee73 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 3 Nov 2026 15:16:08 -0800 Subject: [PATCH 38/39] fix(vertex_ai): force only the namespace members Gemini is sent A forced namespace or member on Gemini chat could still allow a generated name that a top-level function or an earlier namespace owns, so tool_choice forced an unrelated function. The forced names now come from the same collision checks the declarations use --- .../vertex_and_google_ai_studio_gemini.py | 36 ++++++++++++++----- ...test_vertex_and_google_ai_studio_gemini.py | 33 +++++++++++++++++ 2 files changed, 61 insertions(+), 8 deletions(-) diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index 03bfcaaf2ad..997304683b7 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -642,12 +642,27 @@ def _with_namespace_members_inlined(tools: JsonValue, outside_declarations: Json return list(_members_named_once(tuple(declared), top_level_names)) -def _qualified_names_of(member_name: str, tool: JsonValue, declarable: Counter[str | None]) -> tuple[str, ...]: +def _names_each_tool_declares(candidates: tuple[JsonValue, ...]) -> tuple[tuple[str, ...], ...]: + declarable: Final = Counter(_declarable_names_in(candidates)) + top_level_names: Final = _top_level_names_in(candidates) + declared: Final = tuple( + tuple(filter(None, map(declared_function_name, _as_declared(tool, declarable, top_level_names)))) + for tool in candidates + ) + return tuple( + tuple(name for name in names if name not in frozenset(chain.from_iterable(declared[:index]))) + for index, names in enumerate(declared) + ) + + +def _qualified_names_of( + member_name: str, tool: JsonValue, declarable: Counter[str | None], declared: tuple[str, ...] +) -> tuple[str, ...]: namespace: Final = _top_level_name(tool) - holds_member: Final = member_name in map(declared_function_name, _namespace_members_or_tool(tool)) - if not _is_namespace(tool) or namespace is None or not holds_member or _inlines_members(tool, declarable): + if not _is_namespace(tool) or namespace is None or _inlines_members(tool, declarable): return () - return (qualified_member_name(namespace, member_name),) + qualified: Final = qualified_member_name(namespace, member_name) + return (qualified,) if qualified in declared else () def _forced_function_names(name: str, tools: JsonValue) -> tuple[str, ...]: @@ -655,11 +670,16 @@ def _forced_function_names(name: str, tools: JsonValue) -> tuple[str, ...]: if any(not _is_namespace(tool) and declared_function_name(tool) == name for tool in candidates): return (name,) declarable: Final = Counter(_declarable_names_in(candidates)) - named: Final = next((tool for tool in candidates if _is_namespace(tool) and _top_level_name(tool) == name), None) + declared_by_tool: Final = tuple(zip(candidates, _names_each_tool_declares(candidates), strict=True)) + named: Final = next( + (declared for tool, declared in declared_by_tool if _is_namespace(tool) and _top_level_name(tool) == name), + None, + ) if named is not None: - declared: Final = map(declared_function_name, _as_declared(named, declarable, frozenset())) - return tuple(member for member in declared if member is not None) or (name,) - qualified: Final = chain.from_iterable(_qualified_names_of(name, tool, declarable) for tool in candidates) + return named or (name,) + qualified: Final = chain.from_iterable( + _qualified_names_of(name, tool, declarable, declared) for tool, declared in declared_by_tool + ) return tuple(qualified) or (name,) diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index b66ca48e1c5..06bb2ad5bd9 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -1961,6 +1961,36 @@ def test_vertex_ai_map_tools_keeps_repeated_chat_tools_when_no_namespace_is_sent [{"type": "namespace", "name": "gitlab", "tools": [{"type": "function", "name": "close_issue"}]}], ["github__close_issue", "gitlab__close_issue"], ), + ( + "github", + [ + {"type": "function", "function": {"name": "close_issue"}}, + {"type": "function", "function": {"name": "github__close_issue"}}, + ], + ["github__create_issue"], + ), + ( + "close_issue", + [ + {"type": "namespace", "name": "gitlab", "tools": [{"type": "function", "name": "close_issue"}]}, + {"type": "function", "function": {"name": "github__close_issue"}}, + ], + ["gitlab__close_issue"], + ), + ( + "mcp", + [ + {"type": "namespace", "name": "mcp__ops", "tools": [{"type": "function", "name": "exec"}]}, + { + "type": "namespace", + "name": "mcp", + "tools": [{"type": "function", "name": "ops__exec"}, {"type": "function", "name": "status"}], + }, + {"type": "function", "function": {"name": "exec"}}, + {"type": "function", "function": {"name": "ops__exec"}}, + ], + ["mcp__status"], + ), ], ids=[ "names_the_namespace", @@ -1968,6 +1998,9 @@ def test_vertex_ai_map_tools_keeps_repeated_chat_tools_when_no_namespace_is_sent "names_a_function_sharing_the_namespace_name", "names_a_namespace_whose_member_a_function_repeats", "names_a_member_two_namespaces_share", + "names_a_namespace_whose_generated_name_a_function_holds", + "names_a_member_whose_generated_name_a_function_holds", + "names_a_namespace_whose_generated_name_another_namespace_holds", ], ) def test_vertex_ai_tool_choice_forces_only_functions_gemini_is_sent( From f8df3413682109d9dab51df8ee7a0f1342f1194b Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 3 Nov 2026 17:07:10 -0800 Subject: [PATCH 39/39] fix(vertex_ai): reject a forced namespace Gemini gets no member of, and resolve forced names in one pass --- .../vertex_and_google_ai_studio_gemini.py | 28 ++++++++----- ...test_vertex_and_google_ai_studio_gemini.py | 41 +++++++++++++++++++ 2 files changed, 59 insertions(+), 10 deletions(-) diff --git a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py index 997304683b7..80244cfc3eb 100644 --- a/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py +++ b/litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py @@ -9,7 +9,7 @@ from collections import Counter from collections.abc import Awaitable, Callable, Mapping, Sequence from copy import deepcopy from functools import lru_cache, partial -from itertools import chain +from itertools import chain, repeat from types import MappingProxyType from typing import TYPE_CHECKING, Any, ClassVar, Final, Literal, Optional, Protocol, Union, cast, get_args @@ -649,10 +649,9 @@ def _names_each_tool_declares(candidates: tuple[JsonValue, ...]) -> tuple[tuple[ tuple(filter(None, map(declared_function_name, _as_declared(tool, declarable, top_level_names)))) for tool in candidates ) - return tuple( - tuple(name for name in names if name not in frozenset(chain.from_iterable(declared[:index]))) - for index, names in enumerate(declared) - ) + owned_names: Final = chain.from_iterable(zip(repeat(index), names) for index, names in enumerate(declared)) + first_owner: Final = {name: index for index, name in reversed(tuple(owned_names))} + return tuple(tuple(name for name in names if first_owner[name] == index) for index, names in enumerate(declared)) def _qualified_names_of( @@ -676,7 +675,7 @@ def _forced_function_names(name: str, tools: JsonValue) -> tuple[str, ...]: None, ) if named is not None: - return named or (name,) + return named qualified: Final = chain.from_iterable( _qualified_names_of(name, tool, declarable, declared) for tool, declared in declared_by_tool ) @@ -954,7 +953,9 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig): return supported_params - def map_tool_choice_values(self, model: str, tool_choice: str | dict, tools: JsonValue = None) -> ToolConfig | None: + def map_tool_choice_values( + self, model: str, tool_choice: str | dict, tools: JsonValue = None, drop_params: bool = False + ) -> ToolConfig | None: if tool_choice == "none": return ToolConfig(functionCallingConfig=FunctionCallingConfig(mode="NONE")) elif tool_choice == "required": @@ -964,10 +965,16 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig): elif isinstance(tool_choice, dict): # only supported for anthropic + mistral models - https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ToolChoice.html name: Final = tool_choice.get("function", {}).get("name", "") - return ToolConfig( - functionCallingConfig=FunctionCallingConfig( - mode="ANY", allowed_function_names=list(_forced_function_names(name, tools)) + forced: Final = _forced_function_names(name, tools) + if forced: + return ToolConfig( + functionCallingConfig=FunctionCallingConfig(mode="ANY", allowed_function_names=list(forced)) ) + if drops_unsupported_params(drop_params): + return None + raise litellm.utils.UnsupportedParamsError( + message=f"VertexAI can't force tool_choice '{name}', since none of that namespace's members can be sent to Gemini as a function. Name one of its functions instead, or set `litellm.drop_params = True` to drop tool_choice.", + status_code=400, ) else: raise litellm.utils.UnsupportedParamsError( @@ -1898,6 +1905,7 @@ class VertexGeminiConfig(VertexAIBaseConfig, BaseConfig): model=model, tool_choice=value, tools=[*_listed(non_default_params.get("tools")), *_listed(non_default_params.get("functions"))], + drop_params=drop_params, ) if _tool_choice_value is not None: optional_params["tool_choice"] = _tool_choice_value diff --git a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py index 06bb2ad5bd9..03bc308a89d 100644 --- a/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py +++ b/tests/unit/llms/vertex_ai/gemini/test_vertex_and_google_ai_studio_gemini.py @@ -2027,6 +2027,47 @@ def test_vertex_ai_tool_choice_forces_only_functions_gemini_is_sent( assert set(allowed_function_names) <= set(declared) +@pytest.mark.parametrize( + ("forced_name", "tools"), + [ + ( + "weather", + [ + {"type": "namespace", "name": "weather", "tools": [{"type": "function", "name": "lookup"}]}, + {"type": "function", "function": {"name": "lookup"}}, + {"type": "function", "function": {"name": "weather__lookup"}}, + ], + ), + ( + "ops__exec", + [ + {"type": "namespace", "name": "ops", "tools": [{"type": "function", "name": "exec"}]}, + {"type": "namespace", "name": "ops__exec", "tools": [{"type": "function", "name": "status"}]}, + {"type": "function", "function": {"name": "exec"}}, + {"type": "function", "function": {"name": "status"}}, + {"type": "function", "function": {"name": "ops__exec__status"}}, + ], + ), + ], + ids=["its_members_lose_to_functions", "another_namespace_generates_its_name"], +) +def test_vertex_ai_tool_choice_naming_a_namespace_gemini_gets_no_member_of( + forced_name: str, tools: list[dict[str, object]] +) -> None: + params = {"tools": tools, "tool_choice": {"type": "function", "function": {"name": forced_name}}} + + with pytest.raises(litellm.UnsupportedParamsError, match=f"tool_choice '{forced_name}'"): + VertexGeminiConfig().map_openai_params( + non_default_params=params, optional_params={}, model="gemini-3.8-flash", drop_params=False + ) + dropped = VertexGeminiConfig().map_openai_params( + non_default_params=params, optional_params={}, model="gemini-3.8-flash", drop_params=True + ) + + assert "tool_choice" not in dropped + assert dropped["tools"][0]["function_declarations"] + + def test_vertex_ai_map_tool_with_anyof(): """ Related issue: https://github.com/BerriAI/litellm/issues/11164