hexgate 0.2.6__tar.gz → 0.2.7__tar.gz

{hexgate-0.2.6 → hexgate-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexgate
-Version: 0.2.6
+Version: 0.2.7
 Summary: Hexgate — authorization infrastructure for AI agents (agent runtime + cloud client).
 License-Expression: MIT
 Requires-Python: >=3.13
@@ -1329,7 +1329,7 @@ FastAPI over SQLite. Run with:
 
 ```bash
 cd platform/api
-uv run uvicorn main:app --reload --port 8000
+uv run uvicorn hexgate_api.main:app --reload --port 8000
 ```
 
 The default `support-bot` project is seeded on first boot with two agents — `default` (broad access, side-effects gated by `approval_required`) and `read_only` (everything mutating denied).

{hexgate-0.2.6 → hexgate-0.2.7}/README.md

@@ -1288,7 +1288,7 @@ FastAPI over SQLite. Run with:
 
 ```bash
 cd platform/api
-uv run uvicorn main:app --reload --port 8000
+uv run uvicorn hexgate_api.main:app --reload --port 8000
 ```
 
 The default `support-bot` project is seeded on first boot with two agents — `default` (broad access, side-effects gated by `approval_required`) and `read_only` (everything mutating denied).

hexgate-0.2.7/hexgate/adapters/google/mcp.py

@@ -0,0 +1,95 @@
+"""Google ADK adapter for :class:`~hexgate.mcp.MCPToolset`.
+
+Every :class:`~hexgate.mcp.MCPToolProxy` produced by the toolset becomes
+a :class:`google.adk.tools.BaseTool` subclass whose ``_get_declaration``
+returns a ``FunctionDeclaration`` carrying the MCP tool's raw
+JSON Schema (via ``parametersJsonSchema``) and whose ``run_async``
+forwards to the proxy's ``call``. Once wrapped, the resulting tools
+are indistinguishable from ADK-native :class:`FunctionTool` instances
+to the rest of the Google ADK path — attach them to an ``Agent``, then
+wrap via :func:`~hexgate.adapters.google.wrap_google_agent` so the
+existing per-tool policy gate covers MCP invocations too.
+
+Usage::
+
+    from google.adk.agents import Agent
+    from hexgate.adapters.google import wrap_google_agent
+    from hexgate.adapters.google.mcp import wrap_mcp_toolset
+    from hexgate.mcp import MCPServerConfig, MCPToolset
+
+    slack = MCPServerConfig(name="slack", transport="stdio", command="slack-mcp")
+    async with MCPToolset(slack) as mcp:
+        agent = Agent(
+            name="bot",
+            tools=[*wrap_mcp_toolset(mcp), *native],
+        )
+        wrapped, binding = wrap_google_agent(agent, api_key=api_key)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from google.adk.tools import BaseTool
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types as genai_types
+
+from hexgate.mcp.proxy import MCPToolProxy, MCPToolset
+
+
+class _MCPProxyTool(BaseTool):
+    """One :class:`BaseTool` that forwards to an :class:`MCPToolProxy`.
+
+    ADK's :class:`FunctionTool` derives its schema from a Python
+    callable's signature via reflection, which can't express the shapes
+    MCP servers advertise (partial ``required``, ``anyOf`` unions,
+    nested objects with dynamic keys). Subclassing :class:`BaseTool`
+    and returning a hand-built :class:`FunctionDeclaration` from
+    ``_get_declaration`` bypasses the reflection path and hands the
+    server's raw JSON Schema straight to the model — via ADK's
+    ``parametersJsonSchema`` alias which accepts JSON Schema dicts.
+    """
+
+    def __init__(self, proxy: MCPToolProxy) -> None:
+        super().__init__(name=proxy.qualified_name, description=proxy.description)
+        # Store the schema + call as private attrs — ADK's BaseTool has
+        # no field for them, so we ride on the object dict.
+        self._input_schema = proxy.input_schema
+        self._call = proxy.call
+
+    def _get_declaration(self) -> genai_types.FunctionDeclaration:
+        # Gemini's FunctionDeclaration validator rejects any
+        # parametersJsonSchema missing a top-level `type` — literal `{}`,
+        # or a partial like `{"properties": {...}}`, or a bare
+        # `{"anyOf": [...]}`. All three shapes cause the whole tool
+        # list to fail at declaration time, so the agent never gets to
+        # run. Fill in `type: "object"` (the only shape Gemini accepts
+        # for a function-args container) whenever it's absent, and
+        # ensure a `properties` map so the LLM sees an argument surface
+        # rather than an opaque object. LangChain and OpenAI Agents
+        # both tolerate the missing `type` unchanged.
+        schema = self._input_schema if isinstance(self._input_schema, dict) else {}
+        if "type" not in schema:
+            schema = {"type": "object", "properties": {}, **schema}
+        return genai_types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parametersJsonSchema=schema,
+        )
+
+    async def run_async(
+        self, *, args: dict[str, Any], tool_context: ToolContext
+    ) -> Any:
+        return await self._call(**(args or {}))
+
+
+def wrap_mcp_toolset(toolset: MCPToolset) -> list[BaseTool]:
+    """Wrap every proxy in ``toolset`` as a Google ADK :class:`BaseTool`.
+
+    The returned tools share the toolset's connection lifecycle — they
+    stop working (returning a ``use_after_close`` envelope) once the
+    ``async with MCPToolset(...)`` block exits. Combine with
+    :func:`~hexgate.adapters.google.wrap_google_agent` to gate every
+    invocation through :class:`~hexgate.security.PolicyEnforcer`.
+    """
+    return [_MCPProxyTool(p) for p in toolset.proxies]

{hexgate-0.2.6 → hexgate-0.2.7}/hexgate/adapters/google/runner.py

@@ -16,6 +16,7 @@ from langfuse import get_client, propagate_attributes
 from openinference.instrumentation.google_adk import GoogleADKInstrumentor
 
 from hexgate.adapters.google.wrapper import wrap_google_agent
+from hexgate.agents.factory import ApprovalHandler
 from hexgate.config.env import resolve_api_key
 from hexgate.runtime import User
 
@@ -30,6 +31,7 @@ class HexgateRunner:
         app_name: str,
         session_service: BaseSessionService,
         api_key: str | None = None,
+        approval_handler: ApprovalHandler | None = None,
         **runner_kwargs: Any,
     ):
         self.api_key = resolve_api_key(api_key)
@@ -41,7 +43,7 @@ class HexgateRunner:
         # Runner is built once — refresh swaps the enforcer's policy
         # without touching it.
         self._wrapped_agent, self._binding = wrap_google_agent(
-            agent, api_key=self.api_key
+            agent, api_key=self.api_key, approval_handler=approval_handler
         )
         self._runner = Runner(
             agent=self._wrapped_agent,

{hexgate-0.2.6 → hexgate-0.2.7}/hexgate/adapters/google/tools.py

@@ -1,6 +1,11 @@
 """Google ADK adapter: wrap ``BaseTool`` so ``run_async`` consults a
 :class:`PolicyEnforcer` first. Non-allow outcomes render as markered
 strings the model sees as tool output.
+
+When a caller supplies ``approval_handler``, a ``NEEDS_APPROVAL``
+decision fires the callback and runs the original tool on truthy return;
+falsy return (or a missing handler) keeps today's behavior of surfacing
+the ``[approval_required]`` marker to the model.
 """
 
 from __future__ import annotations
@@ -14,6 +19,9 @@ from google.adk.tools.base_tool import BaseTool
 from google.adk.tools.function_tool import FunctionTool
 from google.adk.tools.tool_context import ToolContext
 
+from hexgate.agents.approvals import resolve_approval_async
+from hexgate.agents.factory import ApprovalHandler
+from hexgate.security.decision import DecisionOutcome
 from hexgate.security.enforcer import PolicyEnforcer
 
 
@@ -32,7 +40,12 @@ def _normalize(tool: ToolEntry) -> BaseTool:
     )
 
 
-def wrap_tool(tool: ToolEntry, enforcer: PolicyEnforcer) -> BaseTool:
+def wrap_tool(
+    tool: ToolEntry,
+    enforcer: PolicyEnforcer,
+    *,
+    approval_handler: ApprovalHandler | None = None,
+) -> BaseTool:
     """Return a copy of ``tool`` with ``run_async`` gated by ``enforcer``."""
     base = _normalize(tool)
     name = base.name
@@ -45,6 +58,12 @@ def wrap_tool(tool: ToolEntry, enforcer: PolicyEnforcer) -> BaseTool:
         decision = enforcer.decide(name, args or {})
         if decision.allowed:
             return await original_run_async(args=args, tool_context=tool_context)
+        if (
+            decision.outcome is DecisionOutcome.NEEDS_APPROVAL
+            and approval_handler is not None
+            and await resolve_approval_async(approval_handler, decision)
+        ):
+            return await original_run_async(args=args, tool_context=tool_context)
         return decision.as_error_message()
 
     wrapped = copy.copy(base)
@@ -52,6 +71,11 @@ def wrap_tool(tool: ToolEntry, enforcer: PolicyEnforcer) -> BaseTool:
     return wrapped
 
 
-def wrap_tools(tools: list[ToolEntry], enforcer: PolicyEnforcer) -> list[BaseTool]:
+def wrap_tools(
+    tools: list[ToolEntry],
+    enforcer: PolicyEnforcer,
+    *,
+    approval_handler: ApprovalHandler | None = None,
+) -> list[BaseTool]:
     """Return a fresh list of policy-gated copies."""
-    return [wrap_tool(t, enforcer) for t in tools]
+    return [wrap_tool(t, enforcer, approval_handler=approval_handler) for t in tools]

{hexgate-0.2.6 → hexgate-0.2.7}/hexgate/adapters/google/wrapper.py

@@ -13,20 +13,27 @@ from __future__ import annotations
 from google.adk.agents import BaseAgent
 
 from hexgate.adapters.google.tools import wrap_tools
+from hexgate.agents.factory import ApprovalHandler
 from hexgate.security.binding import PolicyBinding, resolve_policy
 from hexgate.security.enforcer import build_enforcer
 
 
 def wrap_google_agent(
-    agent: BaseAgent, *, api_key: str
+    agent: BaseAgent,
+    *,
+    api_key: str,
+    approval_handler: ApprovalHandler | None = None,
 ) -> tuple[BaseAgent, PolicyBinding]:
     """Return a policy-gated clone of ``agent`` plus its refresh binding.
 
     Caller must open a :class:`User` scope around the run.
-    ``NEEDS_APPROVAL`` outcomes surface as ``[approval_required]``-prefixed
-    strings in tool results; ``[policy_denied]`` for denials. Refresh the
-    returned binding at run boundaries (``HexgateRunner`` does). Fail-loud:
-    an unregistered agent (platform 404) raises — register it first with
+    ``NEEDS_APPROVAL`` outcomes fire ``approval_handler`` (async
+    ``fn(decision) -> bool`` or ``bool`` shorthand); a truthy return
+    runs the tool, falsy or missing handler surfaces the
+    ``[approval_required]``-prefixed string as tool result.
+    ``[policy_denied]`` marks plain denials. Refresh the returned
+    binding at run boundaries (``HexgateRunner`` does). Fail-loud: an
+    unregistered agent (platform 404) raises — register it first with
     ``hexgate register``.
     """
     agent_name = getattr(agent, "name", "default")
@@ -34,7 +41,7 @@ def wrap_google_agent(
 
     resolved = resolve_policy(agent_name, api_key=api_key)
     enforcer = build_enforcer(resolved.engine, agent_name=agent_name, api_key=api_key)
-    guarded_tools = wrap_tools(tools, enforcer)
+    guarded_tools = wrap_tools(tools, enforcer, approval_handler=approval_handler)
     return (
         agent.model_copy(update={"tools": guarded_tools}),
         PolicyBinding(enforcer, resolved.source),

hexgate-0.2.7/hexgate/adapters/langchain/mcp.py

@@ -0,0 +1,47 @@
+"""LangChain-facing wrapper for :class:`~hexgate.mcp.MCPToolset`.
+
+Every :class:`~hexgate.mcp.MCPToolProxy` produced by the toolset becomes
+a :class:`~langchain_core.tools.StructuredTool` that forwards to the
+proxy's ``call``. Once wrapped, the resulting :class:`BaseTool` objects
+are indistinguishable from native ``@agent_tool`` functions to the rest
+of the LangChain path — hand them to :func:`create_agent`, call
+:func:`enforce_policy`, and the existing :class:`GuardedTool` pass
+gates every invocation through :class:`PolicyEnforcer`.
+"""
+
+from __future__ import annotations
+
+from langchain_core.tools import BaseTool, StructuredTool
+
+from hexgate.mcp.proxy import MCPToolProxy, MCPToolset
+
+
+def _wrap_one(proxy: MCPToolProxy) -> BaseTool:
+    """Build a single :class:`StructuredTool` around ``proxy.call``.
+
+    LangChain's ``StructuredTool.from_function(args_schema=<dict>)``
+    accepts a raw JSON Schema directly — no Pydantic model generation
+    needed. ``proxy.call`` is used verbatim as the coroutine; its
+    ``__name__`` is already set to the qualified name by
+    :func:`hexgate.mcp.proxy._build_proxy`.
+    """
+    return StructuredTool.from_function(
+        coroutine=proxy.call,
+        name=proxy.qualified_name,
+        description=proxy.description,
+        args_schema=proxy.input_schema,
+    )
+
+
+def wrap_mcp_toolset(toolset: MCPToolset) -> list[BaseTool]:
+    """Wrap every proxy in ``toolset`` as a LangChain :class:`BaseTool`.
+
+    Called implicitly by :meth:`MCPToolset.tools` for back-compat, or
+    explicitly by adapter-aware callers that want the same
+    ``wrap_mcp_toolset(mcp)`` shape they'd use with the OpenAI /
+    Pydantic AI / Google ADK adapters. The returned tools share the
+    toolset's connection lifecycle — they stop working (returning a
+    ``use_after_close`` envelope) once the ``async with MCPToolset(...)``
+    block exits.
+    """
+    return [_wrap_one(p) for p in toolset.proxies]

{hexgate-0.2.6 → hexgate-0.2.7}/hexgate/adapters/langchain/tools.py

@@ -14,15 +14,20 @@ from __future__ import annotations
 
 import functools
 from collections.abc import Awaitable, Callable
-from inspect import isawaitable
 from typing import Any
 
 from langchain_core.tools import BaseTool
 from langchain_core.tools.structured import StructuredTool
 from pydantic import ConfigDict
 
+from hexgate.agents.approvals import (
+    resolve_approval_async as _resolve_approval_async,
+)
+from hexgate.agents.approvals import (
+    resolve_approval_sync as _resolve_approval_sync,
+)
 from hexgate.agents.factory import ApprovalHandler
-from hexgate.security.decision import Decision, DecisionOutcome
+from hexgate.security.decision import DecisionOutcome
 from hexgate.security.enforcer import PolicyEnforcer
 from hexgate.tools.decorators import TOOL_METADATA_ATTR
 
@@ -35,29 +40,6 @@ def _copy_tool_metadata(source: Any, target: Any) -> Any:
     return target
 
 
-def _resolve_approval_sync(handler: ApprovalHandler, decision: Decision) -> bool:
-    """Resolve a NEEDS_APPROVAL decision in a sync caller (rejects coroutines)."""
-    if isinstance(handler, bool):
-        return handler
-    result = handler(decision)
-    if isawaitable(result):
-        raise RuntimeError(
-            "approval_handler returned a coroutine; sync tool invocation cannot "
-            "await it — use ainvoke/astream/astream_events"
-        )
-    return bool(result)
-
-
-async def _resolve_approval_async(handler: ApprovalHandler, decision: Decision) -> bool:
-    """Resolve a NEEDS_APPROVAL decision in an async caller."""
-    if isinstance(handler, bool):
-        return handler
-    result = handler(decision)
-    if isawaitable(result):
-        result = await result
-    return bool(result)
-
-
 class GuardedTool(BaseTool):
     """LangChain tool wrapper that consults a :class:`PolicyEnforcer`.
 

hexgate-0.2.7/hexgate/adapters/openai/mcp.py

@@ -0,0 +1,97 @@
+"""OpenAI Agents adapter for :class:`~hexgate.mcp.MCPToolset`.
+
+Every :class:`~hexgate.mcp.MCPToolProxy` produced by the toolset becomes
+an :class:`agents.FunctionTool` whose ``on_invoke_tool`` forwards to the
+proxy's ``call``. Once wrapped, the resulting :class:`FunctionTool`
+objects are indistinguishable from native ``@function_tool``-decorated
+callables to the rest of the OpenAI Agents path — hand them to an
+``Agent`` alongside your other tools, then wrap the agent via
+:func:`~hexgate.adapters.openai.wrap_openai_agent` so the existing
+per-tool policy gate covers MCP invocations too.
+
+Usage::
+
+    from agents import Agent
+    from hexgate.adapters.openai import wrap_openai_agent
+    from hexgate.adapters.openai.mcp import wrap_mcp_toolset
+    from hexgate.mcp import MCPServerConfig, MCPToolset
+
+    slack = MCPServerConfig(name="slack", transport="stdio", command="slack-mcp")
+    async with MCPToolset(slack) as mcp:
+        agent = Agent(
+            name="bot",
+            tools=[*wrap_mcp_toolset(mcp), *native_tools],
+        )
+        wrapped = wrap_openai_agent(agent, enforcer=enforcer)
+        await HexgateRunner(api_key).run(wrapped, "…", user=user)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from agents import FunctionTool
+from agents.tool import ToolContext
+
+from hexgate.mcp.proxy import MCPToolProxy, MCPToolset
+
+
+def _parse_args(raw: str) -> dict[str, Any]:
+    """Best-effort JSON-to-dict parse of a tool-call payload.
+
+    An empty or unparseable payload becomes ``{}`` — the proxy's
+    JSON-Schema validator then decides whether that's acceptable.
+    Matches the same tolerance the native OpenAI wrap has.
+    """
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except (TypeError, ValueError):
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _wrap_one(proxy: MCPToolProxy) -> FunctionTool:
+    """Build a single :class:`FunctionTool` around ``proxy.call``.
+
+    OpenAI Agents' ``FunctionTool`` accepts a raw JSON Schema in
+    ``params_json_schema`` — no dynamic Pydantic model generation
+    needed. ``strict_json_schema=False`` is deliberate: MCP servers
+    routinely advertise schemas that don't meet OpenAI's strict-mode
+    requirements (partial ``required``, optional ``additionalProperties``,
+    ``anyOf`` unions), and we'd rather forward the server's spec
+    verbatim than reject legitimate tools at wrap time. Our own
+    pre-call validator in ``proxy.call`` still catches malformed args
+    before the round trip.
+
+    ``on_invoke_tool`` is the one bit that can't collapse to
+    ``proxy.call`` directly — OpenAI hands us the raw JSON string, not
+    a parsed dict.
+    """
+    call = proxy.call
+
+    async def on_invoke_tool(ctx: ToolContext[Any], raw: str) -> Any:
+        return await call(**_parse_args(raw))
+
+    return FunctionTool(
+        name=proxy.qualified_name,
+        description=proxy.description,
+        params_json_schema=proxy.input_schema,
+        on_invoke_tool=on_invoke_tool,
+        strict_json_schema=False,
+    )
+
+
+def wrap_mcp_toolset(toolset: MCPToolset) -> list[FunctionTool]:
+    """Wrap every proxy in ``toolset`` as an OpenAI Agents
+    :class:`FunctionTool`.
+
+    The returned tools share the toolset's connection lifecycle — they
+    stop working (returning a ``use_after_close`` envelope) once the
+    ``async with MCPToolset(...)`` block exits. Combine with
+    :func:`~hexgate.adapters.openai.wrap_openai_agent` to gate every
+    invocation through :class:`~hexgate.security.PolicyEnforcer`.
+    """
+    return [_wrap_one(p) for p in toolset.proxies]

{hexgate-0.2.6 → hexgate-0.2.7}/hexgate/adapters/openai/runner.py

@@ -25,6 +25,7 @@ from langfuse import get_client, propagate_attributes
 from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor
 
 from hexgate.adapters.openai.wrapper import wrap_openai_agent
+from hexgate.agents.factory import ApprovalHandler
 from hexgate.config.env import resolve_api_key
 from hexgate.runtime import User
 from hexgate.security.binding import PolicyBinding, resolve_policy
@@ -34,7 +35,12 @@ from hexgate.security.enforcer import build_enforcer
 class HexgateRunner:
     """Runner for OpenAI agents with Hexgate tool policy and observability."""
 
-    def __init__(self, api_key: str | None = None):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        approval_handler: ApprovalHandler | None = None,
+    ):
         self.api_key = resolve_api_key(api_key)
         if self.api_key is None:
             raise ValueError(
@@ -42,6 +48,7 @@ class HexgateRunner:
             )
         # Cached per agent name — keeps the ETag memory alive across runs.
         self._bindings: dict[str, PolicyBinding] = {}
+        self._approval_handler = approval_handler
 
     def _binding_for(self, agent: Agent) -> PolicyBinding:
         """Get-or-resolve the cached policy binding for ``agent``'s name.
@@ -98,7 +105,11 @@ class HexgateRunner:
         self._setup_observability()
         binding = self._binding_for(agent)
         await binding.refresh_async()  # per-run policy pull; 304 when unchanged
-        wrapped_agent = wrap_openai_agent(agent, enforcer=binding.enforcer)
+        wrapped_agent = wrap_openai_agent(
+            agent,
+            enforcer=binding.enforcer,
+            approval_handler=self._approval_handler,
+        )
         async with user:
             with self._propagate(user, agent.name):
                 return await Runner.run(
@@ -117,7 +128,11 @@ class HexgateRunner:
         self._setup_observability()
         binding = self._binding_for(agent)
         binding.refresh()  # per-run policy pull; 304 when unchanged
-        wrapped_agent = wrap_openai_agent(agent, enforcer=binding.enforcer)
+        wrapped_agent = wrap_openai_agent(
+            agent,
+            enforcer=binding.enforcer,
+            approval_handler=self._approval_handler,
+        )
         with user.sync_scope():
             with self._propagate(user, agent.name):
                 return Runner.run_sync(
@@ -143,7 +158,11 @@ class HexgateRunner:
         self._setup_observability()
         binding = self._binding_for(agent)
         binding.refresh()  # must precede the wrap + setup
-        wrapped_agent = wrap_openai_agent(agent, enforcer=binding.enforcer)
+        wrapped_agent = wrap_openai_agent(
+            agent,
+            enforcer=binding.enforcer,
+            approval_handler=self._approval_handler,
+        )
 
         with user.sync_scope():
             with self._propagate(user, agent.name):

{hexgate-0.2.6 → hexgate-0.2.7}/hexgate/adapters/openai/tools.py

@@ -1,6 +1,11 @@
 """OpenAI Agents adapter: wrap ``FunctionTool`` so ``on_invoke_tool``
 consults a :class:`PolicyEnforcer` first. Non-allow outcomes render as
 markered strings the model sees as tool output.
+
+When a caller supplies ``approval_handler``, a ``NEEDS_APPROVAL``
+decision fires the callback and runs the original tool on truthy return;
+falsy return (or a missing handler) keeps today's behavior of surfacing
+the ``[approval_required]`` marker to the model.
 """
 
 from __future__ import annotations
@@ -13,6 +18,9 @@ from typing import Any
 from agents import FunctionTool
 from agents.tool import ToolContext
 
+from hexgate.agents.approvals import resolve_approval_async
+from hexgate.agents.factory import ApprovalHandler
+from hexgate.security.decision import DecisionOutcome
 from hexgate.security.enforcer import PolicyEnforcer
 
 
@@ -27,7 +35,12 @@ def _parse_args(raw: str) -> dict[str, Any] | None:
     return parsed if isinstance(parsed, dict) else None
 
 
-def wrap_tool(tool: FunctionTool, enforcer: PolicyEnforcer) -> FunctionTool:
+def wrap_tool(
+    tool: FunctionTool,
+    enforcer: PolicyEnforcer,
+    *,
+    approval_handler: ApprovalHandler | None = None,
+) -> FunctionTool:
     """Return a copy of ``tool`` with ``on_invoke_tool`` gated by ``enforcer``."""
     if not isinstance(tool, FunctionTool):
         raise TypeError(
@@ -43,6 +56,12 @@ def wrap_tool(tool: FunctionTool, enforcer: PolicyEnforcer) -> FunctionTool:
         decision = enforcer.decide(name, _parse_args(input) or {})
         if decision.allowed:
             return await original_invoke(ctx, input)
+        if (
+            decision.outcome is DecisionOutcome.NEEDS_APPROVAL
+            and approval_handler is not None
+            and await resolve_approval_async(approval_handler, decision)
+        ):
+            return await original_invoke(ctx, input)
         return decision.as_error_message()
 
     wrapped = copy.copy(tool)
@@ -51,7 +70,13 @@ def wrap_tool(tool: FunctionTool, enforcer: PolicyEnforcer) -> FunctionTool:
 
 
 def wrap_tools(
-    tools: list[FunctionTool], enforcer: PolicyEnforcer
+    tools: list[FunctionTool],
+    enforcer: PolicyEnforcer,
+    *,
+    approval_handler: ApprovalHandler | None = None,
 ) -> list[FunctionTool]:
     """Return a fresh list of policy-gated copies."""
-    return [wrap_tool(t, enforcer) for t in tools]
+    return [wrap_tool(t, enforcer, approval_handler=approval_handler) for t in tools]
+
+
+__all__ = ["_parse_args", "wrap_tool", "wrap_tools"]

{hexgate-0.2.6 → hexgate-0.2.7}/hexgate/adapters/openai/wrapper.py

@@ -15,14 +15,23 @@ import dataclasses
 from agents import Agent
 
 from hexgate.adapters.openai.tools import wrap_tools
+from hexgate.agents.factory import ApprovalHandler
 from hexgate.security.enforcer import PolicyEnforcer
 
 
-def wrap_openai_agent(agent: Agent, *, enforcer: PolicyEnforcer) -> Agent:
+def wrap_openai_agent(
+    agent: Agent,
+    *,
+    enforcer: PolicyEnforcer,
+    approval_handler: ApprovalHandler | None = None,
+) -> Agent:
     """Return a clone of ``agent`` whose tools are gated by ``enforcer``.
 
     Mechanics only — resolution/refresh live with the caller. Caller
-    must open a :class:`User` scope around the run.
+    must open a :class:`User` scope around the run. ``approval_handler``
+    (async ``fn(decision) -> bool`` or ``bool`` shorthand) fires when a
+    tool call carries a ``NEEDS_APPROVAL`` outcome; a truthy return runs
+    the tool, falsy surfaces the ``[approval_required]`` marker.
     """
-    guarded_tools = wrap_tools(agent.tools, enforcer)
+    guarded_tools = wrap_tools(agent.tools, enforcer, approval_handler=approval_handler)
     return dataclasses.replace(agent, tools=guarded_tools)

hexgate-0.2.7/hexgate/adapters/pydantic_ai/mcp.py

@@ -0,0 +1,60 @@
+"""Pydantic AI adapter for :class:`~hexgate.mcp.MCPToolset`.
+
+Every :class:`~hexgate.mcp.MCPToolProxy` produced by the toolset becomes
+a :class:`pydantic_ai.tools.Tool` via ``Tool.from_schema`` — Pydantic
+AI's raw-JSON-Schema entry point. Once wrapped, the resulting Tools
+are indistinguishable from ``@agent.tool``-decorated callables to the
+rest of the Pydantic AI path — attach them to an ``Agent`` and wrap
+via :func:`~hexgate.adapters.pydantic_ai.wrap_pydantic_agent` so the
+existing per-tool policy gate covers MCP invocations too.
+
+Usage::
+
+    from pydantic_ai import Agent
+    from hexgate.adapters.pydantic_ai import wrap_pydantic_agent
+    from hexgate.adapters.pydantic_ai.mcp import wrap_mcp_toolset
+    from hexgate.mcp import MCPServerConfig, MCPToolset
+
+    slack = MCPServerConfig(name="slack", transport="stdio", command="slack-mcp")
+    async with MCPToolset(slack) as mcp:
+        agent = Agent("openai:gpt-5.4", tools=[*wrap_mcp_toolset(mcp), *native])
+        proxy = wrap_pydantic_agent(agent=agent)
+        await proxy.run("…", user=user)
+"""
+
+from __future__ import annotations
+
+from pydantic_ai.tools import Tool
+
+from hexgate.mcp.proxy import MCPToolProxy, MCPToolset
+
+
+def _wrap_one(proxy: MCPToolProxy) -> Tool:
+    """Build a single :class:`Tool` around ``proxy.call``.
+
+    Pydantic AI's ``Tool.from_schema`` accepts a raw JSON Schema — no
+    dynamic Pydantic model generation is needed. ``proxy.call`` is
+    passed verbatim as the function; its ``__name__`` is already the
+    qualified name (set by :func:`hexgate.mcp.proxy._build_proxy`).
+    Pydantic AI's own validator (built from the same schema) is the
+    outer gate; our ``proxy.call`` runs its own JSON-Schema check as a
+    defence-in-depth layer before the server round-trip.
+    """
+    return Tool.from_schema(
+        function=proxy.call,
+        name=proxy.qualified_name,
+        description=proxy.description,
+        json_schema=proxy.input_schema,
+    )
+
+
+def wrap_mcp_toolset(toolset: MCPToolset) -> list[Tool]:
+    """Wrap every proxy in ``toolset`` as a Pydantic AI :class:`Tool`.
+
+    The returned tools share the toolset's connection lifecycle — they
+    stop working (returning a ``use_after_close`` envelope) once the
+    ``async with MCPToolset(...)`` block exits. Combine with
+    :func:`~hexgate.adapters.pydantic_ai.wrap_pydantic_agent` to gate
+    every invocation through :class:`~hexgate.security.PolicyEnforcer`.
+    """
+    return [_wrap_one(p) for p in toolset.proxies]