agentapprovalprotocol 0.1.0__tar.gz → 0.2.0__tar.gz

{agentapprovalprotocol-0.1.0 → agentapprovalprotocol-0.2.0}/.gitignore

@@ -14,5 +14,6 @@ playwright-report/
 /sdk/python/.venv/
 /sdk/python/dist/
 /sdk/typescript/dist/
+/sdk/typescript-ai-sdk/dist/
 __pycache__/
 /sdk/python/.pytest_cache/

agentapprovalprotocol-0.2.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: agentapprovalprotocol
+Version: 0.2.0
+Summary: Put an AI agent's tool calls behind an Agent Approval Protocol (AAP) approval provider.
+Project-URL: Homepage, https://agentapprovalprotocol.io
+Project-URL: Source, https://github.com/agentapprovalprotocol/agentapprovalprotocol
+License-Expression: Apache-2.0
+Keywords: aap,agents,ai,approval,human-in-the-loop
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: adk
+Requires-Dist: google-adk>=2.11; extra == 'adk'
+Provides-Extra: claude-agent-sdk
+Requires-Dist: claude-agent-sdk>=0.2.165; extra == 'claude-agent-sdk'
+Provides-Extra: crewai
+Requires-Dist: crewai>=1.15; (python_full_version < '3.14') and extra == 'crewai'
+Provides-Extra: langgraph
+Requires-Dist: langchain>=1.0; extra == 'langgraph'
+Requires-Dist: langgraph>=1.0; extra == 'langgraph'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.23; extra == 'openai-agents'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai-slim>=2.55; (python_full_version >= '3.11') and extra == 'pydantic-ai'
+Description-Content-Type: text/markdown
+
+# Agent Approval Protocol for Python
+
+Put an AI agent's tool calls behind an [AAP](https://agentapprovalprotocol.io) approval provider. Each call waits for the provider's decision, runs only if approved, and runs at most once.
+
+```sh
+pip install agentapprovalprotocol
+```
+
+## Check a tool call
+
+```python
+from agentapprovalprotocol import Call, Client, Gate
+
+gate = Gate(Client("https://approvals.example.com/api/aap", token))
+
+with gate.guard(Call(key=f"{run_id}:{tool_call.id}", tool=tool_call.name, arguments=tool_call.args)) as verdict:
+    if verdict:
+        result = run_tool(tool_call)
+    else:
+        result = verdict.reason  # return this to the model as the tool result
+```
+
+`key` must identify the tool call within its run, and stay the same if the call is seen again after a retry or resume. `guard` reports whether the tool succeeded when the block exits.
+
+`AsyncGate` and `AsyncClient` provide the same API for `asyncio`.
+
+## Pause instead of waiting
+
+With `mode="async"`, `check` returns `Pending` when there is no decision yet, so the run can pause and the process can exit. Mount a `Receiver` where the provider can reach it. When a decision arrives it wakes the run, and the gate checks the decision again before anything runs.
+
+Framework integrations handle pausing and resuming for you.
+
+## LangChain, LangGraph and Deep Agents
+
+```sh
+pip install "agentapprovalprotocol[langgraph]"
+```
+
+```python
+from agentapprovalprotocol.langgraph import ApprovalMiddleware
+
+approvals = ApprovalMiddleware("https://approvals.example.com/api/aap", token)
+agent = create_agent(model, tools=tools, middleware=[approvals])
+```
+
+Every tool call the agent makes goes to the provider. A denied call returns the reason to the model as the tool result.
+
+For Deep Agents, also add the middleware to every subagent:
+
+```python
+from agentapprovalprotocol.langgraph import deep_agent_subagents
+
+agent = create_deep_agent(model, tools=tools, middleware=[approvals], subagents=deep_agent_subagents(approvals, my_subagents))
+```
+
+To pause instead of waiting, use `ApprovalMiddleware(..., mode="async")` with a checkpointer, and mount a `Receiver` with `resumers={"langgraph": resumer(agent)}`. On LangSmith Deployment, use `deployment_resumer(get_client())` in a custom route instead. Resuming a thread any other way cannot approve a call: the middleware asks the provider again.
+
+## Pydantic AI
+
+```sh
+pip install "agentapprovalprotocol[pydantic-ai]"
+```
+
+Needs Python 3.11 or later.
+
+```python
+from agentapprovalprotocol.pydantic_ai import ApprovalCapability
+
+approvals = ApprovalCapability("https://approvals.example.com/api/aap", token)
+agent = Agent(model, tools=tools, capabilities=[approvals])
+```
+
+Every tool call the agent makes goes to the provider, including MCP and other toolset tools. A denied call returns the reason to the model as a failed tool result. Add the same capability to every agent you run as a sub-agent.
+
+Tools that run at the model provider, such as native web search or code execution, cannot be sent for approval. A run that includes one stops with an error. Use a local tool instead.
+
+To pause instead of waiting, use `ApprovalCapability(..., mode="async")` and add `DeferredToolRequests` to the agent's `output_type`. When a run ends with `DeferredToolRequests`, save `result.conversation`. Mount a `Receiver` with `resumers={"pydantic-ai": resumer(agent, load=load, save=save)}`, where `load(conversation_id)` returns the saved conversation and `save(conversation)` stores the resumed one. Calls inside a sub-agent wait instead of pausing. Continuing a conversation any other way cannot approve a call: the capability asks the provider again, and an approval with edited arguments is refused.
+
+## Google Agent Development Kit
+
+```sh
+pip install "agentapprovalprotocol[adk]"
+```
+
+```python
+from agentapprovalprotocol.adk import ApprovalPlugin, check_coverage
+
+approvals = ApprovalPlugin("https://approvals.example.com/api/aap", token)
+app = App(name="support", root_agent=agent, plugins=[approvals])
+check_coverage(app, approvals)
+```
+
+Every tool call from every agent in the app goes to the provider, including sub-agents and agents used as tools. A denied call returns the reason to the model as the tool result. Register the plugin first, and don't change tool arguments in later plugins or `before_tool_callback`.
+
+`check_coverage` raises an error for agents whose calls the plugin cannot see: code executors, remote agents, and agents used as tools with `include_plugins=False`. Gemini built-in tools such as `google_search` run on Google's servers, so the plugin stops the run when an agent uses one.
+
+To pause instead of waiting, use `ApprovalPlugin(..., mode="async")`, set `resumability_config=ResumabilityConfig(is_resumable=True)` on the app, and mount a `Receiver` with `resumers={"adk": resumer(runner)}`. Calls inside an agent used as a tool, and calls in live (streaming audio or video) runs, wait instead of pausing. For a runner in another process, such as `adk api_server`, send `wake_message(session.events, request.id)` as the new message from your own resumer. Answering the confirmation any other way cannot approve a call: the plugin asks the provider again.
+
+## OpenAI Agents SDK
+
+```sh
+pip install "agentapprovalprotocol[openai-agents]"
+```
+
+```python
+from agentapprovalprotocol.openai_agents import Approvals
+
+approvals = Approvals("https://approvals.example.com/api/aap", token)
+agent = approvals.protect(Agent(name="Support", tools=tools, handoffs=handoffs))
+result = await Runner.run(agent, "Refund the duplicate charge")
+```
+
+`protect` covers the agent's tools, its local MCP servers, its handoff targets and agents it uses as tools. Call it after the agent is fully configured. A denied call returns the reason to the model as the tool result.
+
+`protect` refuses tools that run inside OpenAI's response, such as web search, file search and code interpreter, because their calls cannot be stopped. It also refuses local shell, computer and apply patch tools: wrap the action in a function tool instead. Hosted MCP servers are supported, and their calls always wait for the decision.
+
+To pause instead of waiting, use `Approvals(..., mode="async", save=save, load=load)`, where `save(run_id, state)` and `load(run_id)` keep each run's state on your server. Start runs with `await approvals.run(agent, input, run_id=run_id)` and mount a `Receiver` with `resumers={"openai-agents": approvals.resumer(agent)}`. Approving the run state any other way cannot run a call: only a decision from the provider can.
+
+## Claude Agent SDK
+
+```sh
+pip install "agentapprovalprotocol[claude-agent-sdk]"
+```
+
+```python
+from agentapprovalprotocol.claude_agent_sdk import ApprovalHooks
+
+approvals = ApprovalHooks("https://approvals.example.com/api/aap", token)
+options = approvals.options(ClaudeAgentOptions(mcp_servers=servers))
+async for message in query(prompt=prompt, options=options):
+    ...
+```
+
+Every tool call the agent makes goes to the provider, including built-in tools, MCP tools and calls made by subagents. A denied call returns the reason to the model.
+
+`options()` does not load your user settings (`~/.claude/settings.json`) unless you set `setting_sources` yourself. If the Claude Code approval hook is installed there, loading them asks for approval twice for every call.
+
+To pause instead of waiting, use `ApprovalHooks(..., mode="async")`. A call without a decision ends the run with `stop_reason="tool_deferred"`. Mount a `Receiver` with `resumers={"claude-agent-sdk": resumer(options)}` on the machine that stores the session, and it resumes the session when the decision arrives. Calls made by subagents, and a second call in the same turn, wait for their decision instead of pausing.
+
+Tools that the Claude API runs itself, such as the advisor, never reach the hooks, so they are not sent for approval.
+
+## CrewAI
+
+CrewAI and the OpenAI Agents SDK need different major versions of `openai`, so the `crewai` and `openai-agents` extras can't be installed together.
+
+```sh
+pip install "agentapprovalprotocol[crewai]"
+```
+
+CrewAI supports Python 3.10 to 3.13.
+
+```python
+from agentapprovalprotocol.crewai import ApprovalHooks
+
+ApprovalHooks("https://approvals.example.com/api/aap", token).install()
+crew.kickoff()
+```
+
+Every tool call any crew, agent or flow in the process makes goes to the provider, including delegation to coworkers. A denied call returns the reason to the model as the tool result.
+
+CrewAI cannot pause a run at a tool call, so each call waits for the decision. In `akickoff` the wait blocks the event loop.
+
+Limitations:
+
+- Register any hook that changes tool arguments before `install()`. A hook registered later, including one from a `@CrewBase` crew, runs after the approval. If it changes the arguments, the call is reported to the provider as failed.
+- Models with `builtin_tools` run those tools at the model provider, where they cannot be checked. Runs that use such a model stop with an error.
+- Tools you run yourself with `llm.call(available_functions=...)` are not checked.

agentapprovalprotocol-0.2.0/README.md

@@ -0,0 +1,167 @@
+# Agent Approval Protocol for Python
+
+Put an AI agent's tool calls behind an [AAP](https://agentapprovalprotocol.io) approval provider. Each call waits for the provider's decision, runs only if approved, and runs at most once.
+
+```sh
+pip install agentapprovalprotocol
+```
+
+## Check a tool call
+
+```python
+from agentapprovalprotocol import Call, Client, Gate
+
+gate = Gate(Client("https://approvals.example.com/api/aap", token))
+
+with gate.guard(Call(key=f"{run_id}:{tool_call.id}", tool=tool_call.name, arguments=tool_call.args)) as verdict:
+    if verdict:
+        result = run_tool(tool_call)
+    else:
+        result = verdict.reason  # return this to the model as the tool result
+```
+
+`key` must identify the tool call within its run, and stay the same if the call is seen again after a retry or resume. `guard` reports whether the tool succeeded when the block exits.
+
+`AsyncGate` and `AsyncClient` provide the same API for `asyncio`.
+
+## Pause instead of waiting
+
+With `mode="async"`, `check` returns `Pending` when there is no decision yet, so the run can pause and the process can exit. Mount a `Receiver` where the provider can reach it. When a decision arrives it wakes the run, and the gate checks the decision again before anything runs.
+
+Framework integrations handle pausing and resuming for you.
+
+## LangChain, LangGraph and Deep Agents
+
+```sh
+pip install "agentapprovalprotocol[langgraph]"
+```
+
+```python
+from agentapprovalprotocol.langgraph import ApprovalMiddleware
+
+approvals = ApprovalMiddleware("https://approvals.example.com/api/aap", token)
+agent = create_agent(model, tools=tools, middleware=[approvals])
+```
+
+Every tool call the agent makes goes to the provider. A denied call returns the reason to the model as the tool result.
+
+For Deep Agents, also add the middleware to every subagent:
+
+```python
+from agentapprovalprotocol.langgraph import deep_agent_subagents
+
+agent = create_deep_agent(model, tools=tools, middleware=[approvals], subagents=deep_agent_subagents(approvals, my_subagents))
+```
+
+To pause instead of waiting, use `ApprovalMiddleware(..., mode="async")` with a checkpointer, and mount a `Receiver` with `resumers={"langgraph": resumer(agent)}`. On LangSmith Deployment, use `deployment_resumer(get_client())` in a custom route instead. Resuming a thread any other way cannot approve a call: the middleware asks the provider again.
+
+## Pydantic AI
+
+```sh
+pip install "agentapprovalprotocol[pydantic-ai]"
+```
+
+Needs Python 3.11 or later.
+
+```python
+from agentapprovalprotocol.pydantic_ai import ApprovalCapability
+
+approvals = ApprovalCapability("https://approvals.example.com/api/aap", token)
+agent = Agent(model, tools=tools, capabilities=[approvals])
+```
+
+Every tool call the agent makes goes to the provider, including MCP and other toolset tools. A denied call returns the reason to the model as a failed tool result. Add the same capability to every agent you run as a sub-agent.
+
+Tools that run at the model provider, such as native web search or code execution, cannot be sent for approval. A run that includes one stops with an error. Use a local tool instead.
+
+To pause instead of waiting, use `ApprovalCapability(..., mode="async")` and add `DeferredToolRequests` to the agent's `output_type`. When a run ends with `DeferredToolRequests`, save `result.conversation`. Mount a `Receiver` with `resumers={"pydantic-ai": resumer(agent, load=load, save=save)}`, where `load(conversation_id)` returns the saved conversation and `save(conversation)` stores the resumed one. Calls inside a sub-agent wait instead of pausing. Continuing a conversation any other way cannot approve a call: the capability asks the provider again, and an approval with edited arguments is refused.
+
+## Google Agent Development Kit
+
+```sh
+pip install "agentapprovalprotocol[adk]"
+```
+
+```python
+from agentapprovalprotocol.adk import ApprovalPlugin, check_coverage
+
+approvals = ApprovalPlugin("https://approvals.example.com/api/aap", token)
+app = App(name="support", root_agent=agent, plugins=[approvals])
+check_coverage(app, approvals)
+```
+
+Every tool call from every agent in the app goes to the provider, including sub-agents and agents used as tools. A denied call returns the reason to the model as the tool result. Register the plugin first, and don't change tool arguments in later plugins or `before_tool_callback`.
+
+`check_coverage` raises an error for agents whose calls the plugin cannot see: code executors, remote agents, and agents used as tools with `include_plugins=False`. Gemini built-in tools such as `google_search` run on Google's servers, so the plugin stops the run when an agent uses one.
+
+To pause instead of waiting, use `ApprovalPlugin(..., mode="async")`, set `resumability_config=ResumabilityConfig(is_resumable=True)` on the app, and mount a `Receiver` with `resumers={"adk": resumer(runner)}`. Calls inside an agent used as a tool, and calls in live (streaming audio or video) runs, wait instead of pausing. For a runner in another process, such as `adk api_server`, send `wake_message(session.events, request.id)` as the new message from your own resumer. Answering the confirmation any other way cannot approve a call: the plugin asks the provider again.
+
+## OpenAI Agents SDK
+
+```sh
+pip install "agentapprovalprotocol[openai-agents]"
+```
+
+```python
+from agentapprovalprotocol.openai_agents import Approvals
+
+approvals = Approvals("https://approvals.example.com/api/aap", token)
+agent = approvals.protect(Agent(name="Support", tools=tools, handoffs=handoffs))
+result = await Runner.run(agent, "Refund the duplicate charge")
+```
+
+`protect` covers the agent's tools, its local MCP servers, its handoff targets and agents it uses as tools. Call it after the agent is fully configured. A denied call returns the reason to the model as the tool result.
+
+`protect` refuses tools that run inside OpenAI's response, such as web search, file search and code interpreter, because their calls cannot be stopped. It also refuses local shell, computer and apply patch tools: wrap the action in a function tool instead. Hosted MCP servers are supported, and their calls always wait for the decision.
+
+To pause instead of waiting, use `Approvals(..., mode="async", save=save, load=load)`, where `save(run_id, state)` and `load(run_id)` keep each run's state on your server. Start runs with `await approvals.run(agent, input, run_id=run_id)` and mount a `Receiver` with `resumers={"openai-agents": approvals.resumer(agent)}`. Approving the run state any other way cannot run a call: only a decision from the provider can.
+
+## Claude Agent SDK
+
+```sh
+pip install "agentapprovalprotocol[claude-agent-sdk]"
+```
+
+```python
+from agentapprovalprotocol.claude_agent_sdk import ApprovalHooks
+
+approvals = ApprovalHooks("https://approvals.example.com/api/aap", token)
+options = approvals.options(ClaudeAgentOptions(mcp_servers=servers))
+async for message in query(prompt=prompt, options=options):
+    ...
+```
+
+Every tool call the agent makes goes to the provider, including built-in tools, MCP tools and calls made by subagents. A denied call returns the reason to the model.
+
+`options()` does not load your user settings (`~/.claude/settings.json`) unless you set `setting_sources` yourself. If the Claude Code approval hook is installed there, loading them asks for approval twice for every call.
+
+To pause instead of waiting, use `ApprovalHooks(..., mode="async")`. A call without a decision ends the run with `stop_reason="tool_deferred"`. Mount a `Receiver` with `resumers={"claude-agent-sdk": resumer(options)}` on the machine that stores the session, and it resumes the session when the decision arrives. Calls made by subagents, and a second call in the same turn, wait for their decision instead of pausing.
+
+Tools that the Claude API runs itself, such as the advisor, never reach the hooks, so they are not sent for approval.
+
+## CrewAI
+
+CrewAI and the OpenAI Agents SDK need different major versions of `openai`, so the `crewai` and `openai-agents` extras can't be installed together.
+
+```sh
+pip install "agentapprovalprotocol[crewai]"
+```
+
+CrewAI supports Python 3.10 to 3.13.
+
+```python
+from agentapprovalprotocol.crewai import ApprovalHooks
+
+ApprovalHooks("https://approvals.example.com/api/aap", token).install()
+crew.kickoff()
+```
+
+Every tool call any crew, agent or flow in the process makes goes to the provider, including delegation to coworkers. A denied call returns the reason to the model as the tool result.
+
+CrewAI cannot pause a run at a tool call, so each call waits for the decision. In `akickoff` the wait blocks the event loop.
+
+Limitations:
+
+- Register any hook that changes tool arguments before `install()`. A hook registered later, including one from a `@CrewBase` crew, runs after the approval. If it changes the arguments, the call is reported to the provider as failed.
+- Models with `builtin_tools` run those tools at the model provider, where they cannot be checked. Runs that use such a model stop with an error.
+- Tools you run yourself with `llm.call(available_functions=...)` are not checked.

{agentapprovalprotocol-0.1.0 → agentapprovalprotocol-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentapprovalprotocol"
-version = "0.1.0"
+version = "0.2.0"
 description = "Put an AI agent's tool calls behind an Agent Approval Protocol (AAP) approval provider."
 readme = "README.md"
 license = "Apache-2.0"
@@ -17,6 +17,7 @@ Homepage = "https://agentapprovalprotocol.io"
 Source = "https://github.com/agentapprovalprotocol/agentapprovalprotocol"
 
 [project.optional-dependencies]
+claude-agent-sdk = ["claude-agent-sdk>=0.2.165"]
 langgraph = [
     "langchain>=1.0",
     "langgraph>=1.0",
@@ -24,6 +25,13 @@ langgraph = [
 pydantic-ai = [
     "pydantic-ai-slim>=2.55 ; python_full_version >= '3.11'",
 ]
+adk = [
+    "google-adk>=2.11",
+]
+openai-agents = [
+    "openai-agents>=0.23",
+]
+crewai = ["crewai>=1.15 ; python_full_version < '3.14'"]
 
 [dependency-groups]
 dev = [
@@ -43,3 +51,10 @@ packages = ["src/agentapprovalprotocol"]
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]
+
+[tool.uv]
+# CrewAI needs openai below 3 and the OpenAI Agents SDK needs openai 3, so
+# the two extras resolve separately and cannot be installed together.
+conflicts = [[{ extra = "crewai" }, { extra = "openai-agents" }]]
+# chromadb (through crewai) allows onnxruntime releases without Python 3.10 wheels.
+constraint-dependencies = ["onnxruntime<1.24 ; python_full_version < '3.11'"]

agentapprovalprotocol-0.2.0/src/agentapprovalprotocol/adk.py

@@ -0,0 +1,262 @@
+"""Approvals for Google Agent Development Kit (ADK) agents.
+
+``ApprovalPlugin`` gates every tool call any agent in a runner makes,
+including sub-agents and agents used as tools. In sync mode the call waits
+for the decision. In async mode the run pauses with an ADK tool
+confirmation, the process can exit, and a ``Receiver`` wakes the session
+when the decision arrives. On resume the plugin asks the provider again and
+ignores the confirmation's ``confirmed`` flag, so a confirmation sent by
+anything else cannot approve a call.
+
+Install with ``pip install "agentapprovalprotocol[adk]"``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+from typing import Any, Awaitable, Callable, Iterable, Literal, Mapping
+
+from google.adk.agents import BaseAgent, LlmAgent
+from google.adk.apps import App
+from google.adk.events import Event
+from google.adk.plugins.base_plugin import BasePlugin
+from google.adk.tools.agent_tool import AgentTool
+from google.genai import types
+
+from ._client import AsyncClient
+from ._gate import Allow, AsyncGate, Call, Deny, Pending
+from ._wire import Request
+
+PAYLOAD_KEY = "aap_request_id"
+CONFIRMATION = "adk_request_confirmation"
+PENDING_TEXT = "This call is waiting for approval. It will run if it is approved."
+
+# Tool fields Gemini executes itself, outside ADK's tool pipeline, are refused.
+# Function declarations (and computer use, whose actions are function calls)
+# come back to ADK as calls the plugin sees.
+_CLIENT_RUN = {"function_declarations", "computer_use"}
+
+# Set while an approved tool runs, so calls made inside it (an agent used as
+# a tool runs a nested runner) know their run cannot pause.
+_inside_tool: contextvars.ContextVar[bool] = contextvars.ContextVar("aap_adk_inside_tool", default=False)
+
+
+class UnsupportedToolError(RuntimeError):
+    """An agent uses something whose calls cannot wait for approval."""
+
+
+def _function_call(events: Iterable[Event], call_id: str | None) -> tuple[Event, types.FunctionCall] | None:
+    if not call_id:
+        return None
+    for event in reversed(list(events)):
+        for call in event.get_function_calls():
+            if call.id == call_id and call.name != CONFIRMATION:
+                return event, call
+    return None
+
+
+def _reasoning(event: Event | None) -> str | None:
+    if event is None or event.content is None:
+        return None
+    text = "".join(part.text for part in event.content.parts or [] if part.text and not part.thought)
+    return text.strip() or None
+
+
+def _failed(result: Any) -> bool:
+    return isinstance(result, Mapping) and "error" in result
+
+
+class ApprovalPlugin(BasePlugin):
+    """Send every tool call to an AAP provider before it runs.
+
+    Register it first in ``App(plugins=[...])``, so no other plugin answers
+    or rewrites a call before the provider sees it, and keep tool arguments
+    unchanged in later plugins and agent ``before_tool_callback``s.
+
+    ``mode="async"`` pauses runs and needs ``App(resumability_config=
+    ResumabilityConfig(is_resumable=True))``. Calls that cannot pause wait
+    instead: calls in an app that is not resumable, inside an agent used as a
+    tool, in live (bidi) runs and in workflow tool nodes.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token: str | None = None,
+        *,
+        mode: Literal["sync", "async"] = "sync",
+        gate: AsyncGate | None = None,
+        context: Mapping[str, Any] | None = None,
+        name: str = "aap_approvals",
+        **gate_options: Any,
+    ):
+        super().__init__(name)
+        if gate is None and (base_url is None or token is None):
+            raise ValueError("pass base_url and token, or a gate")
+        self.gate = gate or AsyncGate(AsyncClient(base_url, token), mode=mode, **gate_options)  # type: ignore[arg-type]
+        self.context = {"framework": "adk", **(context or {})}
+        self._allowed: dict[str, Allow] = {}
+
+    def _call(self, tool: Any, args: Mapping[str, Any], tool_context: Any) -> tuple[Call, bool]:
+        ic = tool_context.get_invocation_context()
+        session = ic.session
+        found = _function_call(session.events, tool_context.function_call_id)
+        resume = {"framework": "adk", "app_name": session.app_name, "user_id": session.user_id, "session_id": session.id}
+        call = Call(
+            key=f"{session.app_name}:{session.user_id}:{session.id}:{ic.invocation_id}:{tool_context.function_call_id}",
+            tool=tool.name,
+            arguments=dict(args),
+            reasoning=_reasoning(found[0] if found else None),
+            context={**self.context, "agent": tool_context.agent_name},
+            resume=resume,
+        )
+        # A pause needs a resumable app, a model function call ADK can resume,
+        # and a run that is not live or nested inside another tool.
+        can_pause = ic.is_resumable and found is not None and ic.live_request_queue is None and not _inside_tool.get()
+        return call, can_pause
+
+    async def before_tool_callback(self, *, tool: Any, tool_args: dict[str, Any], tool_context: Any) -> dict[str, Any] | None:
+        confirmation = tool_context.tool_confirmation
+        if (confirmation is None or not confirmation.confirmed) and await tool.check_require_confirmation(tool_args, tool_context) is True:
+            # The tool has its own ADK confirmation, which answers this call
+            # without running it. Ask the provider once the user confirms.
+            return None
+        call, can_pause = self._call(tool, tool_args, tool_context)
+        # A confirmation never approves a call: the provider is asked again.
+        verdict = await self.gate.check(call, can_pause=can_pause)
+        if isinstance(verdict, Pending):
+            tool_context.request_confirmation(hint=PENDING_TEXT, payload={PAYLOAD_KEY: verdict.request_id})
+            tool_context.actions.skip_summarization = True
+            return {"status": "pending", "message": PENDING_TEXT}
+        if isinstance(verdict, Deny):
+            return {"error": verdict.reason}
+        self._allowed[call.key] = verdict
+        _inside_tool.set(True)
+        return None
+
+    async def after_tool_callback(self, *, tool: Any, tool_args: dict[str, Any], tool_context: Any, result: Any) -> None:
+        await self._report(tool, tool_args, tool_context, "failed" if _failed(result) else "succeeded")
+        return None
+
+    async def on_tool_error_callback(self, *, tool: Any, tool_args: dict[str, Any], tool_context: Any, error: Exception) -> None:
+        await self._report(tool, tool_args, tool_context, "failed")
+        return None
+
+    async def _report(self, tool: Any, tool_args: Mapping[str, Any], tool_context: Any, status: Literal["succeeded", "failed"]) -> None:
+        call, _ = self._call(tool, tool_args, tool_context)
+        verdict = self._allowed.pop(call.key, None)
+        if verdict is not None and self.gate.report_outcomes:
+            await verdict.report(status)
+
+    async def before_model_callback(self, *, callback_context: Any, llm_request: Any) -> None:
+        agent = callback_context.get_invocation_context().agent
+        _refuse_code_executor(agent)
+        for tool in (llm_request.config.tools if llm_request.config else None) or []:
+            fields = set(tool.model_dump(exclude_none=True)) if isinstance(tool, types.Tool) else {type(tool).__name__}
+            if fields - _CLIENT_RUN:
+                names = ", ".join(sorted(fields - _CLIENT_RUN))
+                raise UnsupportedToolError(f"Agent {getattr(agent, 'name', '?')!r} uses {names}, which Gemini runs itself, so its calls cannot wait for approval. Remove it from the agent.")
+        return None
+
+
+def _refuse_code_executor(agent: Any) -> None:
+    if getattr(agent, "code_executor", None) is not None:
+        raise UnsupportedToolError(f"Agent {agent.name!r} runs model-written code with a code executor, which cannot wait for approval. Remove the code executor.")
+
+
+def check_coverage(app: App, plugin: ApprovalPlugin) -> None:
+    """Raise ``UnsupportedToolError`` where calls would not reach ``plugin``.
+
+    Checks that the plugin is the app's first plugin, and walks every agent,
+    sub-agent and agent used as a tool for code executors, agents used as
+    tools without the app's plugins, and remote agents. Gemini built-in tools
+    are refused when the model is called.
+    """
+    if not app.plugins or app.plugins[0] is not plugin:
+        raise UnsupportedToolError("Register the approval plugin first in App(plugins=[...]).")
+    seen: set[int] = set()
+
+    def walk(agent: BaseAgent) -> None:
+        if id(agent) in seen:
+            return
+        seen.add(id(agent))
+        if type(agent).__name__ == "RemoteA2aAgent":
+            raise UnsupportedToolError(f"Agent {agent.name!r} runs on another server. Add an approval plugin there.")
+        _refuse_code_executor(agent)
+        if isinstance(agent, LlmAgent):
+            for tool in agent.tools:
+                if isinstance(tool, AgentTool):
+                    if not tool.include_plugins:
+                        raise UnsupportedToolError(f"Agent tool {tool.name!r} runs without the app's plugins. Remove include_plugins=False.")
+                    walk(tool.agent)
+        for sub in agent.sub_agents:
+            walk(sub)
+
+    if app.root_agent is not None:
+        walk(app.root_agent)  # type: ignore[arg-type]
+
+
+def waiting(events: Iterable[Event], request_id: str) -> list[str]:
+    """IDs of the confirmation calls to answer to resume calls waiting on one request.
+
+    A call is waiting when its latest response is a pause on this request.
+    ADK re-runs a call when its latest confirmation is answered, even again,
+    so a call paused a second time is resumed through the same confirmation.
+    """
+    events = list(events)
+    last: dict[str, Event] = {}
+    confirmations: dict[str, str] = {}
+    for event in events:
+        for response in event.get_function_responses():
+            if response.id and response.name != CONFIRMATION:
+                last[response.id] = event
+        for call in event.get_function_calls():
+            original = (call.args or {}).get("originalFunctionCall") if call.name == CONFIRMATION else None
+            if call.id and isinstance(original, Mapping) and isinstance(original.get("id"), str):
+                confirmations[original["id"]] = call.id
+    out = []
+    for call_id, event in last.items():
+        pause = (event.actions.requested_tool_confirmations or {}).get(call_id)
+        payload = getattr(pause, "payload", None)
+        if isinstance(payload, Mapping) and payload.get(PAYLOAD_KEY) == request_id and call_id in confirmations:
+            out.append(confirmations[call_id])
+    return out
+
+
+def wake_message(events: Iterable[Event], request_id: str) -> types.Content | None:
+    """The message that resumes a session paused on one request, or None.
+
+    Send it as ``new_message`` to the runner, or to an ADK API server's
+    ``/run`` endpoint. The plugin asks the provider again on resume, so the
+    message itself approves nothing.
+    """
+    ids = waiting(events, request_id)
+    if not ids:
+        return None
+    parts = [types.Part(function_response=types.FunctionResponse(name=CONFIRMATION, id=i, response={"confirmed": True})) for i in ids]
+    return types.Content(role="user", parts=parts)
+
+
+def resumer(runner: Any, *, run_config: Any = None) -> Callable[[Mapping[str, Any], Request], Awaitable[None]]:
+    """A ``Receiver`` resumer for a ``Runner`` in this process.
+
+    It resumes only the confirmations waiting on the decided request, one
+    resume per session at a time. The resumed run continues here, so read
+    results from the session, not from the run that started it.
+    """
+    locks: dict[tuple[str, str], asyncio.Lock] = {}
+
+    async def resume(handle: Mapping[str, Any], request: Request) -> None:
+        user, session_id = handle.get("user_id"), handle.get("session_id")
+        if handle.get("app_name") != runner.app_name or not isinstance(user, str) or not isinstance(session_id, str):
+            return
+        async with locks.setdefault((user, session_id), asyncio.Lock()):
+            session = await runner.session_service.get_session(app_name=runner.app_name, user_id=user, session_id=session_id)
+            message = wake_message(session.events, request.id) if session else None
+            if message is None:
+                return
+            async for _ in runner.run_async(user_id=user, session_id=session_id, new_message=message, run_config=run_config):
+                pass
+
+    return resume