toolwall 0.4.2__tar.gz → 0.4.3__tar.gz

toolwall-0.4.2/README.md → toolwall-0.4.3/PKG-INFO

@@ -1,3 +1,38 @@
+Metadata-Version: 2.3
+Name: toolwall
+Version: 0.4.3
+Summary: Security gateway for AI agent tool calls: fail-closed schema + policy + secret-detection gate before any tool executes
+Project-URL: Homepage, https://toolwall.aya-ai.xyz
+Project-URL: Documentation, https://github.com/Dev-Saif-Ops/toolwall#readme
+Project-URL: Source, https://github.com/Dev-Saif-Ops/toolwall
+Project-URL: Changelog, https://github.com/Dev-Saif-Ops/toolwall/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Dev-Saif-Ops/toolwall/issues
+Project-URL: Security policy, https://github.com/Dev-Saif-Ops/toolwall/blob/main/SECURITY.md
+Author: Mohammad Safwan Athar
+License: MIT
+Keywords: agent-security,agents,ai,ai-agent-security,ai-agents,ai-safety,approval,asyncio,function-calling,guardrails,human-in-the-loop,llm,llm-security,mcp,mcp-security,policy,prompt-injection,secret-detection,security,tool-call-validation,tool-calling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
 # toolwall
 
 [![PyPI version](https://img.shields.io/pypi/v/toolwall.svg?cacheSeconds=300)](https://pypi.org/project/toolwall/)
@@ -29,7 +64,36 @@ pip install toolwall
 ```
 
 Zero required dependencies. Works with OpenAI, Anthropic, and Gemini native tool
-calling (and plain dicts). Python 3.10+.
+calling (and plain dicts). Python 3.10+, sync and async tools.
+
+**See it in 30 seconds, no API key:**
+
+```bash
+python -m toolwall demo
+```
+
+```text
+toolwall demo: a support agent serving customer c_42
+Every verdict below comes from the real gate. No model or API key.
+
+  ALLOW  issue_refund(order_id='o_9', amount=40.0)
+         an honest refund: ran: refunded 40.00 on o_9
+  BLOCK  issue_refund(order_id='o_9', amount=5000.0)
+         a refund over the cap: policy violation: arg 'amount' rejected by in_range(0.01, 500)
+  BLOCK  issue_refund(order_id='o_77', amount=40.0)
+         someone else's order: order does not belong to the signed-in customer
+  BLOCK  send_email(to='x@evil.com,ops@ourco.com', body='export')
+         a smuggled recipient: policy violation: arg 'to' rejected by customer_or_ourco
+  ALLOW  lookup_customer(customer_id='c_42')
+         a lookup whose record holds a key: ran, but tool output withheld: secret detected (stripe-key) in 'return.billing_api_key'
+  HELD   close_account(customer_id='c_42')
+         a destructive action: waiting for a human to approve
+  BLOCK  drop_all_tables()
+         a tool nobody registered: unknown tool: 'drop_all_tables'
+
+1 ran · 5 stopped · 1 waiting for a human. Every decision is in the audit log (wall.export).
+```
+
 
 ## Quickstart
 
@@ -55,6 +119,31 @@ results = wall.guard(openai_response)   # or gate a raw OpenAI/Anthropic/Gemini
 
 Only an `ALLOW` verdict runs the tool. `Gate` is the lower-level primitive underneath.
 
+**Async tools.** Agent frameworks are mostly async. Use `acall` and `aguard`: they
+await the tool, then scan what it returned, with every check `call` makes.
+
+```python
+async def lookup_customer(customer_id: str) -> dict: ...
+
+wall.register("lookup_customer", lookup_customer)   # schema from the annotations
+r = await wall.acall("lookup_customer", {"customer_id": "c_42"})
+results = await wall.aguard(openai_response)
+```
+
+The sync `call` refuses an async tool instead of reporting a coroutine as a run.
+A tool that streams (an async generator) has its output withheld on both paths:
+return a materialised list instead.
+
+A function whose parameters and return value are all annotated gets its schema
+from its signature: classes, `X | None`, `Optional`, `Union`, generic containers
+(`list[str]` checks for a list), `Any` and `Annotated[...]`; `float` also accepts an
+integer. Anything else (`Literal`, `TypedDict`, a non-runtime `Protocol`, a lambda,
+a partly annotated function) still needs `schema=`, for example
+`types={"filters": dict}`. A parameter annotated with a class JSON can't produce (a
+dataclass, an Enum, a pydantic model) is inferred but blocks every call; give it an
+explicit `schema=` with `dict` or `str`.
+
+
 ## What it stops
 
 ```python
@@ -166,6 +255,12 @@ changed. Argument integrity is not resource integrity. For resources that can ch
 owner or meaning, re-verify inside the tool's own transaction (for example
 compare-and-swap on a version column); the gate cannot see your datastore.
 
+## Security
+
+Found a way past the gate? Please report it privately through
+[GitHub's vulnerability reporting](https://github.com/Dev-Saif-Ops/toolwall/security/advisories/new),
+not as a public issue. Details in [SECURITY.md](https://github.com/Dev-Saif-Ops/toolwall/blob/main/SECURITY.md).
+
 ## Links
 
 - **Source, full docs, and the failure suite:** https://github.com/Dev-Saif-Ops/toolwall

toolwall-0.4.2/PKG-INFO → toolwall-0.4.3/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.3
-Name: toolwall
-Version: 0.4.2
-Summary: Security gateway for AI agent tool calls: fail-closed schema + policy + secret-detection gate before any tool executes
-Project-URL: Homepage, https://github.com/Dev-Saif-Ops/toolwall
-Author: Mohammad Safwan Athar
-License: MIT
-Keywords: agent-sandbox,agent-security,agents,ai,ai-agent-security,ai-agents,ai-safety,firewall,guardrails,llm,llm-security,mcp,mcp-firewall,mcp-proxy,mcp-security,prompt-injection,secret-detection,security,tool-call-validation,tool-calling
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Security
-Classifier: Topic :: Software Development :: Libraries
-Requires-Python: >=3.10
-Provides-Extra: dev
-Requires-Dist: pytest-cov>=4.0; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Provides-Extra: mcp
-Requires-Dist: mcp>=1.0.0; extra == 'mcp'
-Description-Content-Type: text/markdown
-
 # toolwall
 
 [![PyPI version](https://img.shields.io/pypi/v/toolwall.svg?cacheSeconds=300)](https://pypi.org/project/toolwall/)
@@ -51,7 +29,36 @@ pip install toolwall
 ```
 
 Zero required dependencies. Works with OpenAI, Anthropic, and Gemini native tool
-calling (and plain dicts). Python 3.10+.
+calling (and plain dicts). Python 3.10+, sync and async tools.
+
+**See it in 30 seconds, no API key:**
+
+```bash
+python -m toolwall demo
+```
+
+```text
+toolwall demo: a support agent serving customer c_42
+Every verdict below comes from the real gate. No model or API key.
+
+  ALLOW  issue_refund(order_id='o_9', amount=40.0)
+         an honest refund: ran: refunded 40.00 on o_9
+  BLOCK  issue_refund(order_id='o_9', amount=5000.0)
+         a refund over the cap: policy violation: arg 'amount' rejected by in_range(0.01, 500)
+  BLOCK  issue_refund(order_id='o_77', amount=40.0)
+         someone else's order: order does not belong to the signed-in customer
+  BLOCK  send_email(to='x@evil.com,ops@ourco.com', body='export')
+         a smuggled recipient: policy violation: arg 'to' rejected by customer_or_ourco
+  ALLOW  lookup_customer(customer_id='c_42')
+         a lookup whose record holds a key: ran, but tool output withheld: secret detected (stripe-key) in 'return.billing_api_key'
+  HELD   close_account(customer_id='c_42')
+         a destructive action: waiting for a human to approve
+  BLOCK  drop_all_tables()
+         a tool nobody registered: unknown tool: 'drop_all_tables'
+
+1 ran · 5 stopped · 1 waiting for a human. Every decision is in the audit log (wall.export).
+```
+
 
 ## Quickstart
 
@@ -77,6 +84,31 @@ results = wall.guard(openai_response)   # or gate a raw OpenAI/Anthropic/Gemini
 
 Only an `ALLOW` verdict runs the tool. `Gate` is the lower-level primitive underneath.
 
+**Async tools.** Agent frameworks are mostly async. Use `acall` and `aguard`: they
+await the tool, then scan what it returned, with every check `call` makes.
+
+```python
+async def lookup_customer(customer_id: str) -> dict: ...
+
+wall.register("lookup_customer", lookup_customer)   # schema from the annotations
+r = await wall.acall("lookup_customer", {"customer_id": "c_42"})
+results = await wall.aguard(openai_response)
+```
+
+The sync `call` refuses an async tool instead of reporting a coroutine as a run.
+A tool that streams (an async generator) has its output withheld on both paths:
+return a materialised list instead.
+
+A function whose parameters and return value are all annotated gets its schema
+from its signature: classes, `X | None`, `Optional`, `Union`, generic containers
+(`list[str]` checks for a list), `Any` and `Annotated[...]`; `float` also accepts an
+integer. Anything else (`Literal`, `TypedDict`, a non-runtime `Protocol`, a lambda,
+a partly annotated function) still needs `schema=`, for example
+`types={"filters": dict}`. A parameter annotated with a class JSON can't produce (a
+dataclass, an Enum, a pydantic model) is inferred but blocks every call; give it an
+explicit `schema=` with `dict` or `str`.
+
+
 ## What it stops
 
 ```python
@@ -188,6 +220,12 @@ changed. Argument integrity is not resource integrity. For resources that can ch
 owner or meaning, re-verify inside the tool's own transaction (for example
 compare-and-swap on a version column); the gate cannot see your datastore.
 
+## Security
+
+Found a way past the gate? Please report it privately through
+[GitHub's vulnerability reporting](https://github.com/Dev-Saif-Ops/toolwall/security/advisories/new),
+not as a public issue. Details in [SECURITY.md](https://github.com/Dev-Saif-Ops/toolwall/blob/main/SECURITY.md).
+
 ## Links
 
 - **Source, full docs, and the failure suite:** https://github.com/Dev-Saif-Ops/toolwall

{toolwall-0.4.2 → toolwall-0.4.3}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "toolwall"
-version = "0.4.2"
+version = "0.4.3"
 description = "Security gateway for AI agent tool calls: fail-closed schema + policy + secret-detection gate before any tool executes"
 readme = "README.md"
 license = { text = "MIT" }
@@ -14,15 +14,23 @@ requires-python = ">=3.10"
 authors = [{ name = "Mohammad Safwan Athar" }]
 keywords = [
     "ai", "agents", "ai-agents", "llm", "llm-security", "ai-agent-security",
-    "agent-security", "tool-calling", "tool-call-validation", "guardrails",
-    "security", "ai-safety", "mcp", "mcp-security", "mcp-firewall", "mcp-proxy",
-    "prompt-injection", "secret-detection", "agent-sandbox", "firewall",
+    "agent-security", "tool-calling", "function-calling", "tool-call-validation",
+    "guardrails", "human-in-the-loop", "approval", "policy", "security", "ai-safety",
+    "mcp", "mcp-security", "prompt-injection", "secret-detection", "asyncio",
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
     "Topic :: Software Development :: Libraries",
     "Topic :: Security",
 ]
@@ -36,7 +44,12 @@ dev = ["pytest>=8.0", "pytest-cov>=4.0"]
 toolwall = "toolwall.cli:main"
 
 [project.urls]
-Homepage = "https://github.com/Dev-Saif-Ops/toolwall"
+Homepage = "https://toolwall.aya-ai.xyz"
+Documentation = "https://github.com/Dev-Saif-Ops/toolwall#readme"
+Source = "https://github.com/Dev-Saif-Ops/toolwall"
+Changelog = "https://github.com/Dev-Saif-Ops/toolwall/blob/main/CHANGELOG.md"
+Issues = "https://github.com/Dev-Saif-Ops/toolwall/issues"
+"Security policy" = "https://github.com/Dev-Saif-Ops/toolwall/blob/main/SECURITY.md"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/toolwall"]

{toolwall-0.4.2 → toolwall-0.4.3}/src/toolwall/__init__.py

@@ -25,7 +25,7 @@ from toolwall.shield import Finding, Shield
 from toolwall.suggest import suggest_policies
 from toolwall.mcp_guard import GuardedCall, MCPGuard, to_mcp_error
 
-__version__ = "0.4.2"
+__version__ = "0.4.3"
 
 __all__ = [
     "ToolWall",

toolwall-0.4.3/src/toolwall/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m toolwall ...`: same as the `toolwall` command."""
+
+from toolwall.cli import main
+
+main()

toolwall-0.4.3/src/toolwall/_aio.py

@@ -0,0 +1,33 @@
+"""Small helpers for telling async callables and awaitables apart (stdlib only).
+
+An awaitable is truthy and is not the value it will produce. Anywhere the gate
+reads a callable's result as a decision or as output, an awaitable must either
+be awaited (async path) or refused (sync path); reading it as-is approves or
+leaks.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+from typing import Any
+
+
+def is_async_callable(fn: Any) -> bool:
+    """True for `async def` functions, partials of them, and objects whose
+    `__call__` is `async def`."""
+    while isinstance(fn, functools.partial):
+        fn = fn.func
+    if inspect.iscoroutinefunction(fn):
+        return True
+    call = getattr(fn, "__call__", None)
+    return call is not None and inspect.iscoroutinefunction(call)
+
+
+def discard_awaitable(value: Any) -> None:
+    """Drop an awaitable we refuse to await, without a 'never awaited' warning."""
+    if inspect.iscoroutine(value):
+        value.close()
+    elif isinstance(value, asyncio.Future):
+        value.cancel()

{toolwall-0.4.2 → toolwall-0.4.3}/src/toolwall/cli.py

@@ -1,4 +1,4 @@
-"""toolwall CLI — inspect meter/audit exports."""
+"""toolwall CLI: a no-key demo, and inspecting meter/audit exports."""
 
 from __future__ import annotations
 
@@ -28,10 +28,20 @@ def cmd_report(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_demo(args: argparse.Namespace) -> int:
+    from toolwall.demo import run_demo
+
+    return run_demo(color=False if args.no_color else None)
+
+
 def main() -> None:
     ap = argparse.ArgumentParser(prog="toolwall", description="toolwall dev tools")
     sub = ap.add_subparsers(dest="command", required=True)
 
+    demo = sub.add_parser("demo", help="Watch the gate stop a support agent's bad tool calls (no API key)")
+    demo.add_argument("--no-color", action="store_true", help="Plain output")
+    demo.set_defaults(func=cmd_demo)
+
     report = sub.add_parser("report", help="Print summary from a Meter JSON export")
     report.add_argument("file", help="Path to meter/audit JSON")
     report.set_defaults(func=cmd_report)

toolwall-0.4.3/src/toolwall/demo.py

@@ -0,0 +1,113 @@
+"""`python -m toolwall demo`: a support agent's tool calls, gated. No API key.
+
+A scripted "model" makes the calls a prompt-injected support agent might make
+on behalf of one signed-in customer. Every verdict printed is the real gate's.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+from toolwall.policy import Policy, email_domain, in_range
+from toolwall.schema import ToolSchema
+from toolwall.wall import ToolWall
+
+CUSTOMER = {"id": "c_42", "email": "amal@example.com"}
+ORDER_OWNER = {"o_9": "c_42", "o_10": "c_42", "o_77": "c_7"}
+# Built by concatenation so repository secret scanners don't flag the fixture.
+FAKE_KEY = "sk_live_" + "4eC39HqLyjWDarjtT1zdp7dc"
+
+
+def issue_refund(order_id: str, amount: float) -> str:
+    return f"refunded {amount:.2f} on {order_id}"
+
+
+def send_email(to: str, body: str) -> str:
+    return f"sent to {to}"
+
+
+def lookup_customer(customer_id: str) -> dict:
+    return {"id": customer_id, "plan": "pro", "billing_api_key": FAKE_KEY}
+
+
+def close_account(customer_id: str) -> str:
+    return f"closed {customer_id}"
+
+
+def own_order(args: dict[str, Any]) -> str | None:
+    owner = ORDER_OWNER.get(args.get("order_id"))
+    if owner != CUSTOMER["id"]:
+        return "order does not belong to the signed-in customer"
+    return None
+
+
+def customer_or_ourco(value: Any) -> bool:
+    return value == CUSTOMER["email"] or email_domain("ourco.com")(value)
+
+
+def build_wall() -> ToolWall:
+    wall = ToolWall()
+    # Fully annotated functions get their schema from the signature.
+    wall.register("issue_refund", issue_refund,
+                  policy=Policy(constraints={"amount": in_range(0.01, 500)}, cross=own_order))
+    wall.register("send_email", send_email, schema=ToolSchema(required=["to", "body"]),
+                  policy=Policy(constraints={"to": customer_or_ourco}))
+    wall.register("lookup_customer", lookup_customer)
+    wall.register("close_account", close_account, policy=Policy(require_approval=True))
+    return wall
+
+
+SCRIPT = [
+    ("issue_refund", {"order_id": "o_9", "amount": 40.0}, "an honest refund"),
+    ("issue_refund", {"order_id": "o_9", "amount": 5000.0}, "a refund over the cap"),
+    ("issue_refund", {"order_id": "o_77", "amount": 40.0}, "someone else's order"),
+    ("send_email", {"to": "x@evil.com,ops@ourco.com", "body": "export"}, "a smuggled recipient"),
+    ("lookup_customer", {"customer_id": "c_42"}, "a lookup whose record holds a key"),
+    ("close_account", {"customer_id": "c_42"}, "a destructive action"),
+    ("drop_all_tables", {}, "a tool nobody registered"),
+]
+
+
+def _paint(color: bool):
+    def paint(text: str, code: str) -> str:
+        return f"\033[{code}m{text}\033[0m" if color else text
+    return paint
+
+
+def _render_call(name: str, args: dict[str, Any]) -> str:
+    inner = ", ".join(f"{k}={v!r}" for k, v in args.items())
+    return f"{name}({inner})"
+
+
+def run_demo(color: bool | None = None, out: Any = None) -> int:
+    out = out or sys.stdout
+    if color is None:
+        color = getattr(out, "isatty", lambda: False)() and "NO_COLOR" not in os.environ
+    paint = _paint(color)
+    wall = build_wall()
+    print(paint(f"toolwall demo: a support agent serving customer {CUSTOMER['id']}", "1"), file=out)
+    print(paint("Every verdict below comes from the real gate. No model or API key.\n", "2"), file=out)
+
+    tally = {"ran": 0, "stopped": 0, "held": 0}
+    for name, args, label in SCRIPT:
+        r = wall.call(name, args)
+        call = _render_call(name, args)
+        if r.needs_approval:
+            tag, note, key = paint("HELD ", "33;1"), "waiting for a human to approve", "held"
+        elif r.blocked:
+            tag, note, key = paint("BLOCK", "31;1"), r.reason, "stopped"
+        elif r.error:
+            tag, note, key = paint("ALLOW", "32;1"), f"ran, but {r.error}", "stopped"
+        else:
+            tag, note, key = paint("ALLOW", "32;1"), f"ran: {r.return_value}", "ran"
+        tally[key] += 1
+        print(f"  {tag}  {call}", file=out)
+        print(paint(f"         {label}: {note}", "2"), file=out)
+
+    print(file=out)
+    print(f"{tally['ran']} ran · {tally['stopped']} stopped · {tally['held']} waiting for a human. "
+          "Every decision is in the audit log (wall.export).", file=out)
+    print(paint("Source of this demo: python -c \"import toolwall.demo as d; print(d.__file__)\"", "2"), file=out)
+    return 0

{toolwall-0.4.2 → toolwall-0.4.3}/src/toolwall/gate.py

@@ -14,6 +14,7 @@ Check order (first failure blocks, fail-closed):
 from __future__ import annotations
 
 import copy
+import inspect
 import threading
 import weakref
 from collections.abc import Callable
@@ -21,6 +22,7 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any, Literal
 
+from toolwall._aio import discard_awaitable, is_async_callable
 from toolwall.intake import IntakeError, ToolCall, parse_tool_calls
 from toolwall.meter import Meter, RunEvent
 from toolwall.policy import Policy
@@ -379,7 +381,71 @@ class Gate:
         the registered tool being called with them (MCPGuard forwards to a
         downstream server this way). Everything else applies unchanged; the tool
         must still be registered, because registration is the allowlist.
+
+        Synchronous. An async tool is refused here, before any budget is spent, and
+        an awaitable returned by a sync callable is withheld: neither has run, and
+        neither has an output the shield could scan. Use aexecute()/arun() for them.
+        """
+        admitted = self._admit(result, invoke, sync=True)
+        if isinstance(admitted, GateResult):
+            return admitted
+        target, args = admitted
+        try:
+            value = target(args)
+        except Exception as exc:
+            result.error = self._scan_error_text(f"{type(exc).__name__}: {exc}", type(exc).__name__)
+        except BaseException as exc:  # KeyboardInterrupt and friends: audit, then re-raise
+            result.error = f"cancelled ({type(exc).__name__}) after the tool started"
+            self._record_tool(result, invoke)
+            raise
+        else:
+            if inspect.isawaitable(value):
+                discard_awaitable(value)
+                result.error = (
+                    "tool returned an awaitable that was not awaited, so it did not run; "
+                    "call it with acall() / arun()"
+                )
+            else:
+                self._accept_output(result, value)
+        return self._record_tool(result, invoke)
+
+    async def aexecute(
+        self, result: GateResult, invoke: Callable[[dict[str, Any]], Any] | None = None
+    ) -> GateResult:
+        """execute() for async tools and forwards: awaits, then scans the output.
+
+        Every check is shared with execute(); only the call itself differs. Sync
+        tools run inline (not in a thread), exactly as they do in execute().
         """
+        admitted = self._admit(result, invoke, sync=False)
+        if isinstance(admitted, GateResult):
+            return admitted
+        target, args = admitted
+        try:
+            value = target(args)
+            if inspect.isawaitable(value):
+                value = await value
+        except Exception as exc:
+            result.error = self._scan_error_text(f"{type(exc).__name__}: {exc}", type(exc).__name__)
+        except BaseException as exc:
+            # Cancelled (or interrupted) after the tool started: its side effects may
+            # have happened. Record that in the audit, keep the spent budget, re-raise.
+            result.error = f"cancelled ({type(exc).__name__}) after the tool started"
+            self._record_tool(result, invoke)
+            raise
+        else:
+            if inspect.isawaitable(value):  # an awaitable that resolved to another one
+                discard_awaitable(value)
+                result.error = "tool output withheld: output could not be scanned (awaitable)"
+            else:
+                self._accept_output(result, value)
+        return self._record_tool(result, invoke)
+
+    def _admit(
+        self, result: GateResult, invoke: Callable[[dict[str, Any]], Any] | None, *, sync: bool
+    ) -> GateResult | tuple[Callable[[dict[str, Any]], Any], dict[str, Any]]:
+        """Every check between an ALLOW and the call. Returns the call to make, or
+        the final result when the call must not happen (refused, dry run)."""
         if not result.allowed or result.call is None:
             joined = "; ".join(result.reasons) or "no call"
             raise PermissionError(f"refusing to execute a {result.verdict.value} result: {joined}")
@@ -438,6 +504,16 @@ class Gate:
             # result keeps the checked args; the hash just proved the two identical.
             execute_args = frozen_args
 
+        tool = self.registry.get(result.call.name)
+        # Calling an async tool synchronously only creates a coroutine: the tool would
+        # not run and its output could not be scanned. Refuse before spending budget.
+        if sync and invoke is None and tool is not None and is_async_callable(tool):
+            return self._refuse(
+                result,
+                f"{result.call.name!r} is an async tool; call it with acall() / arun() "
+                "so it is awaited and its output scanned",
+            )
+
         # Re-check the budget and reserve the slot in one critical section. The check
         # in check() is advisory: between it and here other threads sharing this Gate
         # may have executed, and without this a burst of parallel calls all pass a
@@ -464,28 +540,29 @@ class Gate:
                     )
                 )
             return result
-        tool = self.registry.get(result.call.name)
         if tool is None:  # registry mutated between check and execute
             result.error = f"unknown tool at execute time: {result.call.name!r}"
-        else:
-            try:
-                if invoke is not None:
-                    result.return_value = invoke(execute_args)
-                else:
-                    result.return_value = tool(**execute_args)
-                result.executed = True
-            except Exception as exc:
-                result.error = self._scan_error_text(f"{type(exc).__name__}: {exc}", type(exc).__name__)
-            else:
-                try:
-                    self._scan_output(result)
-                except Exception as exc:
-                    # Output we could not scan is output we cannot vouch for.
-                    result.return_value = None
-                    detail = str(exc) if isinstance(exc, UnscannableError) else type(exc).__name__
-                    result.error = self._scrub(
-                        f"tool output withheld: output could not be scanned ({detail})"
-                    )
+            return self._record_tool(result, invoke)
+        if invoke is not None:
+            return invoke, execute_args
+        return (lambda args: tool(**args)), execute_args
+
+    def _accept_output(self, result: GateResult, value: Any) -> None:
+        result.return_value = value
+        result.executed = True
+        try:
+            self._scan_output(result)
+        except Exception as exc:
+            # Output we could not scan is output we cannot vouch for.
+            result.return_value = None
+            detail = str(exc) if isinstance(exc, UnscannableError) else type(exc).__name__
+            result.error = self._scrub(
+                f"tool output withheld: output could not be scanned ({detail})"
+            )
+
+    def _record_tool(
+        self, result: GateResult, invoke: Callable[[dict[str, Any]], Any] | None
+    ) -> GateResult:
         if self.meter is not None:
             self.meter.record(
                 RunEvent(
@@ -563,18 +640,54 @@ class Gate:
         return message
 
     def _resolve_approval(self, result: GateResult) -> GateResult:
-        """Called by run/run_all on NEEDS_APPROVAL. Fail closed without a handler."""
+        """Called by run/run_all on NEEDS_APPROVAL. Fail closed without a handler.
+
+        An async handler cannot be asked from here: its coroutine is truthy, and
+        reading it as "granted" would approve every call. It is refused, closed.
+        """
         if self.approval is None:
-            # Held for good: there is no approve-later path, so nothing may run it.
-            self._issued.pop(id(result), None)
-            return result
+            return self._approval_unavailable(result)
+        try:
+            granted = self.approval(result)
+        except Exception as exc:
+            return self._approval_failed(result, f"approval handler raised {type(exc).__name__}: fails closed")
+        if inspect.isawaitable(granted):
+            discard_awaitable(granted)
+            return self._approval_failed(
+                result, "approval handler is async; use acall() / arun() so it is awaited: fails closed"
+            )
+        return self._approval_decided(result, bool(granted))
+
+    async def _aresolve_approval(self, result: GateResult) -> GateResult:
+        """_resolve_approval() for the async path: an async handler is awaited."""
+        if self.approval is None:
+            return self._approval_unavailable(result)
         try:
-            granted = bool(self.approval(result))
+            granted = self.approval(result)
+            if inspect.isawaitable(granted):
+                granted = await granted
         except Exception as exc:
-            self._issued.pop(id(result), None)
-            result.verdict = Verdict.BLOCK
-            result.reasons.append(f"approval handler raised {type(exc).__name__}: fails closed")
-            return self._record_transition(result, "approval-error")
+            return self._approval_failed(result, f"approval handler raised {type(exc).__name__}: fails closed")
+        except BaseException:
+            self._issued.pop(id(result), None)  # cancelled mid-approval: never runnable
+            raise
+        if inspect.isawaitable(granted):
+            discard_awaitable(granted)
+            return self._approval_failed(result, "approval handler returned an awaitable: fails closed")
+        return self._approval_decided(result, bool(granted))
+
+    def _approval_unavailable(self, result: GateResult) -> GateResult:
+        # Held for good: there is no approve-later path, so nothing may run it.
+        self._issued.pop(id(result), None)
+        return result
+
+    def _approval_failed(self, result: GateResult, reason: str) -> GateResult:
+        self._issued.pop(id(result), None)
+        result.verdict = Verdict.BLOCK
+        result.reasons.append(reason)
+        return self._record_transition(result, "approval-error")
+
+    def _approval_decided(self, result: GateResult, granted: bool) -> GateResult:
         if granted:
             with self._lock:
                 entry = self._issued.get(id(result))
@@ -615,6 +728,32 @@ class Gate:
             out.append(self.execute(result) if result.allowed else result)
         return out
 
+    async def arun(self, payload: Any) -> GateResult:
+        """run() for async tools and async approval handlers."""
+        result = self.check(payload)
+        if result.verdict is Verdict.NEEDS_APPROVAL:
+            result = await self._aresolve_approval(result)
+        if result.allowed:
+            return await self.aexecute(result)
+        return result
+
+    async def arun_all(self, payload: Any) -> list[GateResult]:
+        """run_all() for async tools: calls run one after another, never at once,
+        so each check sees the budget the previous call spent."""
+        try:
+            calls = parse_tool_calls(payload)
+        except IntakeError as exc:
+            return [self._record(GateResult(Verdict.BLOCK, reasons=[f"intake: {exc}"]))]
+        if not calls:
+            return [self._record(GateResult(Verdict.BLOCK, reasons=["intake: no tool calls in payload"]))]
+        out: list[GateResult] = []
+        for call in calls:
+            result = self._check_one(call)
+            if result.verdict is Verdict.NEEDS_APPROVAL:
+                result = await self._aresolve_approval(result)
+            out.append(await self.aexecute(result) if result.allowed else result)
+        return out
+
     # -- reporting ----------------------------------------------------------------
 
     def report(self) -> dict[str, Any]:

{toolwall-0.4.2 → toolwall-0.4.3}/src/toolwall/mcp_guard.py

@@ -13,6 +13,7 @@ module imports it lazily so toolwall core stays stdlib-only. The logic below
 from __future__ import annotations
 
 from dataclasses import dataclass
+import inspect
 from typing import Any, Callable
 
 from toolwall.gate import Gate, GateResult, Verdict
@@ -55,6 +56,8 @@ class MCPGuard:
         self.forward = forward
 
     def handle(self, name: str, args: dict[str, Any]) -> GuardedCall:
+        """Check and forward synchronously. An async `forward` is refused here
+        (its coroutine would never run); use ahandle() for it."""
         result = self.gate.check({"name": name, "args": args})
 
         if result.verdict is Verdict.NEEDS_APPROVAL:
@@ -70,26 +73,48 @@ class MCPGuard:
         reached: list[bool] = []
 
         def invoke(verified_args: dict[str, Any]) -> Any:
-            reached.append(True)
-            return self.forward(name, verified_args)
+            value = self.forward(name, verified_args)
+            if not inspect.isawaitable(value):  # an un-awaited forward reached nothing
+                reached.append(True)
+            return value
+
+        return _finish(self.gate.execute(result, invoke=invoke), reached)
+
+    async def ahandle(self, name: str, args: dict[str, Any]) -> GuardedCall:
+        """handle() for async forwards and async approval handlers."""
+        result = self.gate.check({"name": name, "args": args})
 
-        result = self.gate.execute(result, invoke=invoke)
+        if result.verdict is Verdict.NEEDS_APPROVAL:
+            result = await self.gate._aresolve_approval(result)
 
-        if not result.allowed:  # refused at execute time (receipt mismatch, budget)
+        if not result.allowed:
             return _refused(result)
-        if result.dry_run:
-            return GuardedCall(verdict="allow", forwarded=False, reason="dry run: not forwarded")
-        if result.error is not None:  # downstream raised, or its output was withheld
-            return GuardedCall(
-                verdict="allow",
-                forwarded=bool(reached),
-                reason=result.error,
-                result={
-                    "isError": True,
-                    "content": [{"type": "text", "text": f"toolwall: {result.error}"}],
-                },
-            )
-        return GuardedCall(verdict="allow", forwarded=True, result=result.return_value)
+
+        reached: list[bool] = []
+
+        def invoke(verified_args: dict[str, Any]) -> Any:
+            reached.append(True)
+            return self.forward(name, verified_args)  # aexecute awaits it
+
+        return _finish(await self.gate.aexecute(result, invoke=invoke), reached)
+
+
+def _finish(result: GateResult, reached: list[bool]) -> GuardedCall:
+    if not result.allowed:  # refused at execute time (receipt mismatch, budget)
+        return _refused(result)
+    if result.dry_run:
+        return GuardedCall(verdict="allow", forwarded=False, reason="dry run: not forwarded")
+    if result.error is not None:  # downstream raised, or its output was withheld
+        return GuardedCall(
+            verdict="allow",
+            forwarded=bool(reached),
+            reason=result.error,
+            result={
+                "isError": True,
+                "content": [{"type": "text", "text": f"toolwall: {result.error}"}],
+            },
+        )
+    return GuardedCall(verdict="allow", forwarded=True, result=result.return_value)
 
 
 def _refused(result: GateResult) -> GuardedCall:

{toolwall-0.4.2 → toolwall-0.4.3}/src/toolwall/policy.py

@@ -6,12 +6,15 @@ Rules are plain callables returning truthy/falsy. A raising rule fails closed.
 
 from __future__ import annotations
 
+import inspect
 import math
 import re
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from typing import Any
 
+from toolwall._aio import discard_awaitable
+
 Rule = Callable[[Any], bool]
 CrossRule = Callable[[dict[str, Any]], "str | list[str] | None"]
 
@@ -136,7 +139,13 @@ class Policy:
                 continue
             name = getattr(rule, "__name__", "rule")
             try:
-                ok = bool(rule(args[key]))
+                verdict = rule(args[key])
+                if inspect.isawaitable(verdict):
+                    # A coroutine is truthy: reading it would pass every value.
+                    discard_awaitable(verdict)
+                    errors.append(f"policy rule {name} for arg {key!r} is async; rules must be synchronous: fails closed")
+                    continue
+                ok = bool(verdict)
             except Exception as exc:
                 errors.append(
                     f"policy rule {name} for arg {key!r} raised {type(exc).__name__}: fails closed"
@@ -150,8 +159,17 @@ class Policy:
             except Exception as exc:
                 errors.append(f"policy cross-rule raised {type(exc).__name__}: fails closed")
             else:
+                if inspect.isawaitable(verdict):
+                    discard_awaitable(verdict)
+                    errors.append("policy cross-rule is async; rules must be synchronous: fails closed")
+                    return errors
                 if isinstance(verdict, str):
                     errors.append(verdict)
                 elif verdict:
-                    errors.extend(verdict)
+                    for item in verdict:
+                        if inspect.isawaitable(item):
+                            discard_awaitable(item)
+                            errors.append("policy cross-rule returned an awaitable: fails closed")
+                        else:
+                            errors.append(item)
         return errors

toolwall-0.4.3/src/toolwall/schema.py

@@ -0,0 +1,183 @@
+"""Tool schema validation, run before a tool is allowed to execute."""
+
+from __future__ import annotations
+
+import inspect
+import types
+import typing
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolSchema:
+    """Minimal schema: required keys + optional crude types."""
+
+    required: list[str] = field(default_factory=list)
+    types: dict[str, type | tuple[type, ...]] = field(default_factory=dict)
+    allow_extra: bool = True
+    # Known-but-not-required arg names. Only consulted when allow_extra is False,
+    # so that an optional parameter carrying no type annotation (and therefore
+    # absent from `types`) is not mistaken for an unexpected argument.
+    optional: list[str] = field(default_factory=list)
+
+    def validate(self, args: dict[str, Any]) -> list[str]:
+        errors: list[str] = []
+        for key in self.required:
+            if key not in args:
+                errors.append(f"Missing required arg: {key}")
+        if not self.allow_extra:
+            allowed = set(self.required) | set(self.types) | set(self.optional)
+            for key in args:
+                if key not in allowed:
+                    errors.append(f"Unexpected arg: {key}")
+        for key, expected in self.types.items():
+            if key not in args:
+                continue
+            if not isinstance(args[key], expected):
+                errors.append(
+                    f"Arg {key!r} expected {expected}, got {type(args[key]).__name__}"
+                )
+        return errors
+
+
+def _signature(fn: Any) -> inspect.Signature:
+    # eval_str resolves string annotations (modules using `from __future__ import
+    # annotations`), so types are enforced there too. If any annotation can't be
+    # resolved, fall back to the raw signature: those annotations stay strings and
+    # are treated as unsupported, which means no inference rather than an error.
+    try:
+        return inspect.signature(fn, eval_str=True)
+    except Exception:
+        return inspect.signature(fn)
+
+
+_ANY = object()  # an annotation that constrains nothing (typing.Any)
+
+
+def _resolve_annotation(ann: Any) -> "tuple[type, ...] | object | None":
+    """Map an annotation to the classes isinstance() should accept.
+
+    Returns a tuple of classes, _ANY for typing.Any, or None when the annotation
+    can't be checked with isinstance (Literal, TypedDict, a string, a TypeVar...).
+    Generic containers check the container only: list[str] accepts any list.
+    float also accepts int, because JSON has one number type.
+    """
+    if ann is typing.Any:
+        return _ANY
+    origin = typing.get_origin(ann)
+    if origin is typing.Annotated:
+        return _resolve_annotation(typing.get_args(ann)[0])
+    if origin is typing.Union or origin is types.UnionType:
+        accepted: list[type] = []
+        for member in typing.get_args(ann):
+            resolved = _resolve_annotation(member)
+            if resolved is None:
+                return None
+            if resolved is _ANY:
+                return _ANY
+            accepted.extend(resolved)  # type: ignore[arg-type]
+        return tuple(dict.fromkeys(accepted))
+    if origin is not None:
+        # list[str] -> list, typing.List[str] -> list; Literal's origin is not a class.
+        return (origin,) if isinstance(origin, type) else None
+    if ann is None or ann is type(None):
+        return (type(None),)
+    # On 3.10, isinstance(list[str], type) is True; GenericAlias is handled above.
+    if isinstance(ann, type) and not isinstance(ann, types.GenericAlias):
+        # Some classes refuse isinstance() altogether (TypedDict, a Protocol that is
+        # not runtime_checkable). Inferring them would make a tool no call can pass.
+        try:
+            isinstance(None, ann)
+        except TypeError:
+            return None
+        return (int, float) if ann is float else (ann,)
+    return None
+
+
+def _named_params(sig: inspect.Signature) -> list[inspect.Parameter]:
+    return [
+        p for name, p in sig.parameters.items()
+        if name not in ("self", "cls") and p.kind is not p.VAR_POSITIONAL
+    ]
+
+
+def _fully_annotated(sig: inspect.Signature) -> bool:
+    named = _named_params(sig)
+    if any(p.kind is p.VAR_KEYWORD for p in named):
+        return False
+    if sig.return_annotation is inspect.Signature.empty:
+        return False
+    # Parameter.empty is itself a class, so it must be excluded explicitly.
+    return all(
+        p.annotation is not p.empty and _resolve_annotation(p.annotation) is not None
+        for p in named
+    )
+
+
+def fully_annotated(fn: Any) -> bool:
+    """True when every named parameter has an annotation toolwall can check (a
+    class, X | None, Union, Optional, a generic container, Any, Annotated[...]),
+    the return value is annotated, and there is no **kwargs: the author declared
+    the whole signature, so it can stand in for a schema. A lambda never does."""
+    try:
+        return _fully_annotated(_signature(fn))
+    except (TypeError, ValueError):
+        return False
+
+
+def infer_schema_if_annotated(fn: Any) -> "ToolSchema | None":
+    """One signature read: the inferred schema, or None when fn isn't fully
+    annotated. Annotation expressions are evaluated once."""
+    try:
+        sig = _signature(fn)
+    except (TypeError, ValueError):
+        return None
+    if not _fully_annotated(sig):
+        return None
+    return schema_from_signature(fn, _sig=sig)
+
+
+def schema_from_signature(
+    fn: Any, *, required: list[str] | None = None, _sig: inspect.Signature | None = None
+) -> ToolSchema:
+    """Best-effort schema from a callable signature (stdlib inspect).
+
+    Extra arguments are rejected, because the signature already tells us exactly
+    what the callable accepts. Passing one would raise TypeError inside the tool,
+    which surfaces as an executed=False result carrying an error rather than as a
+    verdict; a clean BLOCK is both more honest and fails closed.
+
+    The exception is a callable that declares **kwargs: it genuinely accepts
+    arguments we cannot enumerate, so extras stay allowed there.
+    """
+    sig = _sig if _sig is not None else _signature(fn)
+    req: list[str] = []
+    opt: list[str] = []
+    types: dict[str, type | tuple[type, ...]] = {}
+    takes_var_kwargs = False
+    for name, param in sig.parameters.items():
+        if name in ("self", "cls"):
+            continue
+        if param.kind is param.VAR_KEYWORD:
+            takes_var_kwargs = True
+            continue
+        if param.kind is param.VAR_POSITIONAL:
+            continue
+        if param.default is inspect.Parameter.empty:
+            req.append(name)
+        else:
+            opt.append(name)
+        ann = param.annotation
+        if ann is not inspect.Parameter.empty:
+            resolved = _resolve_annotation(ann)
+            if isinstance(resolved, tuple):
+                types[name] = resolved[0] if len(resolved) == 1 else resolved
+    if required is not None:
+        # A caller-supplied required list overrides which args are mandatory, but
+        # every name from the signature is still a known argument.
+        opt = [n for n in req + opt if n not in required]
+        req = list(required)
+    return ToolSchema(
+        required=req, types=types, allow_extra=takes_var_kwargs, optional=opt
+    )

{toolwall-0.4.2 → toolwall-0.4.3}/src/toolwall/shield.py

@@ -16,6 +16,7 @@ import enum
 import math
 import numbers
 import email.message
+import inspect
 import re
 import sqlite3
 import types
@@ -383,7 +384,18 @@ def _walk_strings(value: Any, path: str = "") -> Iterator[tuple[str, str]]:
             continue
         seen.add(id(item))
         keep.append(item)
-        if isinstance(item, Iterator):
+        # Lazy values: iterating, awaiting or async-iterating them is the only way to
+        # see what they hold, and that would consume them. An async generator is none
+        # of Iterator, awaitable or iter()-able, so it needs its own test.
+        if (
+            isinstance(item, Iterator)
+            or inspect.isawaitable(item)
+            or inspect.isasyncgen(item)
+            # On the type, as `async for` looks it up: probing the instance would run
+            # __getattr__ on attr-dicts and withhold plain data.
+            or hasattr(type(item), "__aiter__")
+            or hasattr(type(item), "__anext__")
+        ):
             raise _unscannable(item)
         if isinstance(item, array.array):
             # Element-wise each entry is one char or one int; scan the text it holds.

{toolwall-0.4.2 → toolwall-0.4.3}/src/toolwall/wall.py

@@ -25,7 +25,7 @@ from typing import Any
 from toolwall.gate import ApprovalHandler, DefaultMode, Gate, GateResult
 from toolwall.meter import Meter
 from toolwall.policy import Policy
-from toolwall.schema import ToolSchema
+from toolwall.schema import ToolSchema, infer_schema_if_annotated
 from toolwall.shield import Shield
 
 ToolFn = Callable[..., Any]
@@ -35,7 +35,8 @@ class ToolWall:
     """Fail-closed security gateway for AI agent tool calls.
 
     Args:
-        default: "deny" (registered tools still need a schema) or "allow".
+        default: "deny" (a registered tool needs a schema, given or inferred from a
+            fully annotated signature) or "allow".
         detect_secrets: attach a Shield. True blocks secrets in tool args;
             pass redact=True to replace them with placeholders instead.
         redact: if detecting secrets, redact instead of block.
@@ -65,9 +66,23 @@ class ToolWall:
         *,
         schema: ToolSchema | None = None,
         policy: Policy | None = None,
-        infer_schema: bool = False,
+        infer_schema: bool | None = None,
         replace: bool = False,
     ) -> "ToolWall":
+        """Register a tool. Registration is the allowlist.
+
+        With no schema, a function whose every parameter and return value are
+        annotated gets its schema from its signature: required args, types, no
+        unknown args. Supported annotations are classes, X | None, Optional and
+        Union of classes, generic containers (list[str] checks for a list), Any and
+        Annotated[...]; float also accepts int. Anything less (a lambda, a partly
+        annotated function, Literal) still needs a schema: under default deny it is
+        blocked until it has one. infer_schema=False opts out.
+        """
+        if infer_schema is None:
+            infer_schema = False
+            if schema is None:
+                schema = infer_schema_if_annotated(fn)  # None unless fully annotated
         self.gate.register(
             name, fn, schema, policy=policy, infer_schema=infer_schema, replace=replace
         )
@@ -95,6 +110,13 @@ class ToolWall:
         """Check the call and execute it only if allowed."""
         return self.gate.run({"name": name, "args": args or {}})
 
+    async def acall(self, name: str, args: dict[str, Any] | None = None) -> GateResult:
+        """call() for async tools: awaits the tool, then scans what it returned.
+
+        Works for sync tools too. Async approval handlers are awaited here.
+        """
+        return await self.gate.arun({"name": name, "args": args or {}})
+
     def check(self, name: str, args: dict[str, Any] | None = None) -> GateResult:
         """Return the verdict without executing anything."""
         return self.gate.check({"name": name, "args": args or {}})
@@ -103,6 +125,10 @@ class ToolWall:
         """Gate a raw LLM response (OpenAI/Anthropic/Gemini), possibly many calls."""
         return self.gate.run_all(response)
 
+    async def aguard(self, response: Any) -> list[GateResult]:
+        """guard() for async tools. Calls run one at a time, in order."""
+        return await self.gate.arun_all(response)
+
     # -- dry-run + reporting -------------------------------------------------
 
     @property

toolwall-0.4.2/src/toolwall/schema.py

@@ -1,81 +0,0 @@
-"""Tool schema validation, run before a tool is allowed to execute."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import Any
-
-
-@dataclass
-class ToolSchema:
-    """Minimal schema: required keys + optional crude types."""
-
-    required: list[str] = field(default_factory=list)
-    types: dict[str, type | tuple[type, ...]] = field(default_factory=dict)
-    allow_extra: bool = True
-    # Known-but-not-required arg names. Only consulted when allow_extra is False,
-    # so that an optional parameter carrying no type annotation (and therefore
-    # absent from `types`) is not mistaken for an unexpected argument.
-    optional: list[str] = field(default_factory=list)
-
-    def validate(self, args: dict[str, Any]) -> list[str]:
-        errors: list[str] = []
-        for key in self.required:
-            if key not in args:
-                errors.append(f"Missing required arg: {key}")
-        if not self.allow_extra:
-            allowed = set(self.required) | set(self.types) | set(self.optional)
-            for key in args:
-                if key not in allowed:
-                    errors.append(f"Unexpected arg: {key}")
-        for key, expected in self.types.items():
-            if key not in args:
-                continue
-            if not isinstance(args[key], expected):
-                errors.append(
-                    f"Arg {key!r} expected {expected}, got {type(args[key]).__name__}"
-                )
-        return errors
-
-
-def schema_from_signature(fn: Any, *, required: list[str] | None = None) -> ToolSchema:
-    """Best-effort schema from a callable signature (stdlib inspect).
-
-    Extra arguments are rejected, because the signature already tells us exactly
-    what the callable accepts. Passing one would raise TypeError inside the tool,
-    which surfaces as an executed=False result carrying an error rather than as a
-    verdict; a clean BLOCK is both more honest and fails closed.
-
-    The exception is a callable that declares **kwargs: it genuinely accepts
-    arguments we cannot enumerate, so extras stay allowed there.
-    """
-    import inspect
-
-    sig = inspect.signature(fn)
-    req: list[str] = []
-    opt: list[str] = []
-    types: dict[str, type | tuple[type, ...]] = {}
-    takes_var_kwargs = False
-    for name, param in sig.parameters.items():
-        if name in ("self", "cls"):
-            continue
-        if param.kind is param.VAR_KEYWORD:
-            takes_var_kwargs = True
-            continue
-        if param.kind is param.VAR_POSITIONAL:
-            continue
-        if param.default is inspect.Parameter.empty:
-            req.append(name)
-        else:
-            opt.append(name)
-        ann = param.annotation
-        if ann is not inspect.Parameter.empty and isinstance(ann, type):
-            types[name] = ann
-    if required is not None:
-        # A caller-supplied required list overrides which args are mandatory, but
-        # every name from the signature is still a known argument.
-        opt = [n for n in req + opt if n not in required]
-        req = list(required)
-    return ToolSchema(
-        required=req, types=types, allow_extra=takes_var_kwargs, optional=opt
-    )