trooth-verify 0.4.0__py3-none-any.whl

trooth_guard/__init__.py

@@ -0,0 +1,53 @@
+"""trooth_guard: the Trooth guard for Python agent frameworks.
+
+    from trooth_guard import decide
+    d = decide("policy.yaml", "stripe.create_payout", host="api.example.com")
+    d["decision"]  # "allow", "hold" or "deny"
+
+One decision implementation: this package runs `trooth guard decide --json`
+(the npm package `trooth`) in a subprocess and parses its Decision. It needs
+no Python package. Adapters, each importing nothing from its framework:
+trooth_guard.crewai, trooth_guard.langgraph, trooth_guard.langchain and
+trooth_guard.openai_agents. Licensed under the Apache License 2.0.
+
+The guard answers allow, hold or deny about an action under the caller's
+policy. It never labels a company.
+"""
+
+from .core import (
+    EXIT_ALLOW,
+    EXIT_DENY,
+    EXIT_HOLD,
+    TROOTH_VERSION,
+    GuardDeny,
+    GuardError,
+    GuardHold,
+    decide,
+    decide_tool_call,
+    describe,
+    covered,
+    error_for,
+    fail_closed,
+    is_approval,
+    reason_codes,
+    trooth_command,
+)
+
+__all__ = [
+    "EXIT_ALLOW",
+    "EXIT_DENY",
+    "EXIT_HOLD",
+    "TROOTH_VERSION",
+    "GuardDeny",
+    "GuardError",
+    "GuardHold",
+    "decide",
+    "decide_tool_call",
+    "describe",
+    "covered",
+    "error_for",
+    "fail_closed",
+    "is_approval",
+    "reason_codes",
+    "trooth_command",
+]

trooth_guard/core.py

@@ -0,0 +1,230 @@
+"""Run `trooth guard decide --json` and read its Decision.
+
+Exit codes of `trooth guard decide` (PHASE34 spec): 0 allow, 20 hold, 21 deny.
+Any other exit, a timeout, a missing command, output that is not a Decision,
+or a Decision that disagrees with the exit code gives a hold with
+SOURCE_UNREACHABLE. Nothing here ever turns a failure into allow.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import os
+import re
+import shlex
+import subprocess
+import unicodedata
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Union
+
+# The trooth release whose CLI has `trooth guard`. TROOTH_CMD or trooth_cmd overrides it.
+TROOTH_VERSION = "0.15.0"
+
+EXIT_ALLOW = 0
+EXIT_HOLD = 20
+EXIT_DENY = 21
+_BY_EXIT = {EXIT_ALLOW: "allow", EXIT_HOLD: "hold", EXIT_DENY: "deny"}
+
+Decision = Dict[str, Any]
+Command = Union[str, Sequence[str]]
+
+
+def trooth_command(trooth_cmd: Optional[Command] = None) -> List[str]:
+    """The command that runs the trooth CLI: trooth_cmd, else $TROOTH_CMD, else npx trooth@TROOTH_VERSION."""
+    cmd: Optional[Command] = trooth_cmd if trooth_cmd is not None else os.environ.get("TROOTH_CMD") or None
+    if cmd is None:
+        return ["npx", "--yes", f"trooth@{TROOTH_VERSION}"]
+    if isinstance(cmd, str):
+        parts = shlex.split(cmd)
+    else:
+        parts = [str(x) for x in cmd]
+    if not parts:
+        raise ValueError("the trooth command is empty")
+    return parts
+
+
+def _now() -> str:
+    return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
+def fail_closed(tool: Optional[str], host: Optional[str], detail: str) -> Decision:
+    """A hold Decision with SOURCE_UNREACHABLE, made locally when no Decision could be read."""
+    return {
+        "decision": "hold",
+        "reasons": [{"code": "SOURCE_UNREACHABLE", "detail": f"the guard gave no decision: {str(detail)[:300]}"}],
+        "subject": host or "",
+        "policy": {"id": None, "version": None, "sha256": None},
+        "evidence": [],
+        "action": {"tool": tool, "host": host},
+        "decided_at": _now(),
+    }
+
+
+def reason_codes(decision: Mapping[str, Any]) -> List[str]:
+    """The reason codes of a Decision, in order."""
+    reasons = decision.get("reasons") if isinstance(decision, Mapping) else None
+    if not isinstance(reasons, list):
+        return []
+    return [r["code"] for r in reasons if isinstance(r, Mapping) and isinstance(r.get("code"), str)]
+
+
+def describe(decision: Mapping[str, Any]) -> str:
+    """One plain sentence for a Decision, for a log line, an error or the model."""
+    d = decision.get("decision", "hold") if isinstance(decision, Mapping) else "hold"
+    action = decision.get("action") if isinstance(decision, Mapping) and isinstance(decision.get("action"), Mapping) else {}
+    tool = action.get("tool")
+    host = action.get("host") or (decision.get("subject") if isinstance(decision.get("subject"), str) and decision.get("subject") else None)
+    what = " ".join(x for x in [f"the call to {tool}" if tool else "this action", f"for {host}" if host else ""] if x)
+    pol = decision.get("policy") if isinstance(decision.get("policy"), Mapping) else {}
+    under = f" under policy {pol['id']}" + (f" version {pol['version']}" if pol.get("version") is not None else "") if pol.get("id") else ""
+    codes = reason_codes(decision)
+    why = f" Reasons: {', '.join(codes)}." if codes else ""
+    if d == "allow":
+        return f"Trooth guard: allow {what}{under}.{why}"
+    if d == "deny":
+        return f"Trooth guard: deny {what}{under}. The call was stopped.{why}"
+    return f"Trooth guard: hold {what}{under}. A person must approve it before it runs.{why}"
+
+
+class GuardError(Exception):
+    """A hold or deny, carrying the Decision."""
+
+    def __init__(self, decision: Decision, message: Optional[str] = None):
+        super().__init__(message or describe(decision))
+        self.decision = decision
+        self.reasons = reason_codes(decision)
+
+
+class GuardHold(GuardError):
+    """The policy needs a person to approve the action before it runs."""
+
+    code = "TROOTH_GUARD_HOLD"
+
+
+class GuardDeny(GuardError):
+    """The policy stops the action."""
+
+    code = "TROOTH_GUARD_DENY"
+
+
+def error_for(decision: Decision) -> Optional[GuardError]:
+    """GuardDeny for deny, None for allow, GuardHold for anything else."""
+    d = decision.get("decision") if isinstance(decision, Mapping) else None
+    if d == "allow":
+        return None
+    if d == "deny":
+        return GuardDeny(decision)
+    return GuardHold(decision)
+
+
+def is_approval(resume: Any) -> bool:
+    """Whether a resume value approves a held action: True, "approve", {"type": "approve"},
+    {"approved": True}, or {"decisions": [...]} when every decision has type "approve"."""
+    if resume is True or resume == "approve":
+        return True
+    if not isinstance(resume, Mapping):
+        return False
+    if resume.get("type") == "approve" or resume.get("approved") is True:
+        return True
+    ds = resume.get("decisions")
+    if isinstance(ds, list) and ds:
+        return all(isinstance(x, Mapping) and x.get("type") == "approve" for x in ds)
+    return False
+
+
+def decide(
+    policy_path: Union[str, "os.PathLike[str]"],
+    tool: str,
+    host: Optional[str] = None,
+    args: Any = None,
+    *,
+    cache: Optional[Union[str, "os.PathLike[str]"]] = None,
+    offline: bool = False,
+    trooth_cmd: Optional[Command] = None,
+    timeout: float = 120.0,
+) -> Optional[Decision]:
+    """Run `trooth guard decide --policy <p> --tool <t> [--host h] [--args json] --json` and return the Decision.
+
+    None when the policy does not cover the tool (the CLI exits 0 and says
+    covered: false); the caller lets such a call run unchecked, as the policy
+    intends. allow only when the CLI exits 0 and prints an allow Decision. The arguments
+    are passed on the command line to a local process; they are not sent
+    anywhere by this function.
+    """
+    try:
+        cmd = trooth_command(trooth_cmd) + ["guard", "decide", "--policy", os.fspath(policy_path), "--tool", str(tool)]
+        if host:
+            cmd += ["--host", str(host)]
+        if args is not None:
+            cmd += ["--args", json.dumps(args, separators=(",", ":"), default=str)]
+        if offline:
+            cmd.append("--offline")
+        if cache is not None:
+            cmd += ["--cache", os.fspath(cache)]
+        cmd.append("--json")
+    except Exception as e:  # noqa: BLE001 - any failure here is a hold
+        return fail_closed(tool, host, f"could not build the command: {e}")
+    try:
+        p = subprocess.run(cmd, stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=timeout, check=False)
+    except FileNotFoundError:
+        return fail_closed(tool, host, f"the trooth command was not found: {cmd[0]}")
+    except subprocess.TimeoutExpired:
+        return fail_closed(tool, host, f"the trooth command did not finish within {timeout} seconds")
+    except OSError as e:
+        return fail_closed(tool, host, f"the trooth command could not run: {e}")
+    expected = _BY_EXIT.get(p.returncode)
+    if expected is None:
+        err = (p.stderr or "").strip().splitlines()
+        return fail_closed(tool, host, f"trooth guard decide exited {p.returncode}" + (f": {err[-1][:200]}" if err else ""))
+    try:
+        d = json.loads(p.stdout)
+    except ValueError:
+        return fail_closed(tool, host, "the output was not JSON")
+    if p.returncode == 0 and isinstance(d, dict) and d.get("covered") is False and "decision" not in d:
+        return None  # the policy does not cover this tool; nothing was decided
+    if not isinstance(d, dict) or d.get("decision") not in ("allow", "hold", "deny") or not isinstance(d.get("reasons"), list):
+        return fail_closed(tool, host, "the output was not a Decision")
+    if d["decision"] != expected:
+        return fail_closed(tool, host, f"the exit code says {expected} and the Decision says {d['decision']}")
+    return d
+
+
+def covered(tool: Optional[str], tools: Optional[Sequence[str]]) -> bool:
+    """Whether a tool name matches one of the globs (* matches any characters); every tool when tools is None.
+
+    The adapters ask the CLI only about covered tools. Give them the policy's
+    applies_to.tools so a tool the policy does not cover is not held.
+    """
+    if tools is None:
+        return True
+    if tool is None:
+        return False
+    globs = list(tools)
+    if not globs:
+        return False
+    name = str(tool)
+    # The same rule as the CLI's toolCovered (bin/lib/guard-policy.mjs): "*" is the
+    # only wildcard; a name also matches once case and Unicode compatibility forms
+    # are folded; and a name that is not plain printable ASCII is covered whenever
+    # tools are listed, so a look-alike letter cannot slip past.
+    if any(_glob_re(g).match(name) for g in globs):
+        return True
+    if any(_glob_re(_fold(g)).match(_fold(name)) for g in globs):
+        return True
+    return not _PRINTABLE.match(name)
+
+
+_PRINTABLE = re.compile(r"[\x21-\x7e]+\Z")
+
+
+def _fold(s: str) -> str:
+    return unicodedata.normalize("NFKC", s).lower()
+
+
+def _glob_re(glob: str) -> "re.Pattern[str]":
+    return re.compile("".join(".*" if part == "*" else re.escape(part) for part in re.split(r"(\*)", glob)) + r"\Z", re.DOTALL)
+
+
+def decide_tool_call(policy_path: Union[str, "os.PathLike[str]"], tool: str, args: Any = None, **kw: Any) -> Optional[Decision]:
+    """decide() for a tool call: the CLI finds the host in the typed arguments (the policy's host_from)."""
+    return decide(policy_path, tool, None, args, **kw)

trooth_guard/crewai.py

@@ -0,0 +1,118 @@
+"""The Trooth guard for CrewAI. Imports nothing from crewai.
+
+Followed, read on October 7, 2026:
+  https://docs.crewai.com/en/concepts/tasks  (task guardrails: a function that takes the
+    TaskOutput and returns Tuple[bool, Any]; (True, result) passes, (False, "message") sends
+    the message back to the agent and retries up to guardrail_max_retries, default 3)
+  https://docs.crewai.com/en/learn/tool-hooks  (before_tool_call hooks: the hook gets a
+    ToolCallHookContext with tool_name and tool_input; returning False blocks the call)
+
+    from crewai.hooks import before_tool_call
+    from trooth_guard.crewai import before_tool_call_hook, task_guardrail
+
+    before_tool_call(before_tool_call_hook("policy.yaml"))            # every tool call
+    Task(..., guardrail=task_guardrail("policy.yaml", "stripe.create_payout"))
+
+allow runs (or passes). deny blocks. hold blocks unless `ask(decision)` returns
+True, which is where a person approves; a failure to decide is a hold.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable, Iterable, Mapping, Optional, Tuple
+
+from .core import covered, decide, describe
+
+
+def _default_extract(output: Any) -> Optional[Mapping[str, Any]]:
+    """The task output as typed arguments: json_dict, pydantic, or raw parsed as JSON."""
+    jd = getattr(output, "json_dict", None)
+    if isinstance(jd, Mapping):
+        return {"host": None, "args": dict(jd)}
+    pd = getattr(output, "pydantic", None)
+    if pd is not None and hasattr(pd, "model_dump"):
+        return {"host": None, "args": pd.model_dump()}
+    raw = getattr(output, "raw", output)
+    try:
+        args = json.loads(raw) if isinstance(raw, str) else raw
+    except ValueError:
+        args = raw
+    return {"host": None, "args": args}
+
+
+def task_guardrail(
+    policy_path: str,
+    tool: str,
+    *,
+    extract: Optional[Callable[[Any], Optional[Mapping[str, Any]]]] = None,
+    ask: Optional[Callable[[dict], bool]] = None,
+    on_decision: Optional[Callable[[dict], None]] = None,
+    **decide_kw: Any,
+) -> Callable[[Any], Tuple[bool, Any]]:
+    """A CrewAI task guardrail for a task whose output is an action to check.
+
+    extract(output) returns {"host": ..., "args": ...} for the action, or None
+    when the output names no action (then it passes). By default the output is
+    read as typed arguments and the CLI finds the host in them.
+    """
+    ex = extract or _default_extract
+
+    def guardrail(output: Any) -> Tuple[bool, Any]:
+        try:
+            action = ex(output)
+        except Exception as e:  # noqa: BLE001 - a failure to read the action is a hold
+            return (False, f"Trooth guard: hold. The action could not be read from the output: {e}")
+        if action is None:
+            return (True, output)
+        d = decide(policy_path, tool, action.get("host"), action.get("args"), **decide_kw)
+        if d is None:
+            return (True, output)
+        if on_decision:
+            on_decision(d)
+        if d["decision"] == "allow":
+            return (True, output)
+        if d["decision"] == "hold" and ask is not None and ask(d) is True:
+            return (True, output)
+        return (False, describe(d))
+
+    # CrewAI checks the return annotation with typing.get_origin when the Task
+    # is built. Under `from __future__ import annotations` the annotation is the
+    # string "Tuple[bool, Any]", which that check refuses, so give it the real type.
+    guardrail.__annotations__["return"] = Tuple[bool, Any]
+    guardrail.__annotations__["output"] = Any
+    return guardrail
+
+
+def before_tool_call_hook(
+    policy_path: str,
+    *,
+    tools: Optional[Iterable[str]] = None,
+    ask: Optional[Callable[[dict], bool]] = None,
+    on_decision: Optional[Callable[[dict], None]] = None,
+    **decide_kw: Any,
+) -> Callable[[Any], Optional[bool]]:
+    """A CrewAI before_tool_call hook: returns False to block the call, None to let it run.
+
+    tools: the policy's applies_to.tools globs; a call to any other tool runs
+    without asking the CLI. None asks about every call. ask(decision) is called for a hold; True lets
+    the call run.
+    """
+    only = list(tools) if tools is not None else None
+
+    def hook(context: Any) -> Optional[bool]:
+        name = getattr(context, "tool_name", None)
+        if not covered(name, only):
+            return None
+        d = decide(policy_path, str(name), None, getattr(context, "tool_input", None), **decide_kw)
+        if d is None:
+            return None
+        if on_decision:
+            on_decision(d)
+        if d["decision"] == "allow":
+            return None
+        if d["decision"] == "hold" and ask is not None and ask(d) is True:
+            return None
+        return False
+
+    return hook

trooth_guard/langchain.py

@@ -0,0 +1,149 @@
+"""The Trooth guard as LangChain v1 agent middleware (create_agent).
+
+Followed, read on October 7, 2026:
+  https://docs.langchain.com/oss/python/langchain/middleware/custom  (wrap_tool_call:
+    a function (request, handler) -> ToolMessage | Command; request.tool_call is a dict with
+    "name", "args" and "id"; the decorator langchain.agents.middleware.wrap_tool_call makes
+    middleware of it; AgentMiddleware subclasses define wrap_tool_call and awrap_tool_call)
+  https://docs.langchain.com/oss/python/langgraph/interrupts  (interrupt and Command(resume=...))
+
+    from langchain.agents import create_agent
+    from langchain.agents.middleware import wrap_tool_call
+    from langchain.messages import ToolMessage
+    from trooth_guard.langchain import tool_call_wrapper
+
+    guard = wrap_tool_call(tool_call_wrapper("policy.yaml", tool_message=ToolMessage))
+    agent = create_agent(model, tools=tools, middleware=[guard])
+
+allow runs the tool. hold: interrupt for a person when interrupt is passed
+(approve on resume runs the tool), else an error ToolMessage telling the model
+a person must approve (when tool_message is passed), else GuardHold is raised.
+deny: GuardDeny is raised, or with on_deny="message" an error ToolMessage.
+middleware() builds an AgentMiddleware subclass and imports langchain only then.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Awaitable, Callable, Optional, Sequence
+
+from .core import GuardDeny, GuardHold, covered, decide, describe, is_approval
+
+HOLD_INTERRUPT_TYPE = "trooth_guard_hold"
+
+
+def _call_of(request: Any) -> dict:
+    tc = getattr(request, "tool_call", None)
+    if tc is None and isinstance(request, dict):
+        tc = request.get("tool_call")
+    return tc if isinstance(tc, dict) else {}
+
+
+class _Plan:
+    def __init__(self, policy_path, interrupt, tool_message, on_hold, on_deny, tools, on_decision, decide_kw):
+        self.policy_path = policy_path
+        self.interrupt = interrupt
+        self.tool_message = tool_message
+        self.on_hold = on_hold or ("interrupt" if interrupt else "message" if tool_message else "raise")
+        self.on_deny = on_deny
+        self.tools = tools
+        self.on_decision = on_decision
+        self.decide_kw = decide_kw
+        if self.on_hold not in ("interrupt", "message", "raise"):
+            raise ValueError('on_hold is "interrupt", "message" or "raise"')
+        if self.on_deny not in ("raise", "message"):
+            raise ValueError('on_deny is "raise" or "message"')
+        if self.on_hold == "interrupt" and interrupt is None:
+            raise ValueError('on_hold="interrupt" needs interrupt (langgraph.types.interrupt)')
+        if "message" in (self.on_hold, self.on_deny) and tool_message is None:
+            raise ValueError('"message" needs tool_message (the ToolMessage class)')
+
+    def decision(self, call: dict) -> Optional[dict]:
+        if not covered(call.get("name"), self.tools):
+            return None
+        d = decide(self.policy_path, str(call.get("name")), None, call.get("args") or {}, **self.decide_kw)
+        if d is None:
+            return None
+        if self.on_decision:
+            self.on_decision(d)
+        return d
+
+    def message(self, call: dict, d: dict, extra: str = "") -> Any:
+        return self.tool_message(content=describe(d) + extra, tool_call_id=call.get("id"), name=call.get("name"), status="error")
+
+    def after(self, call: dict, d: Optional[dict]) -> Any:
+        """None to run the tool; otherwise the ToolMessage to return. Raises for raise paths."""
+        if d is None or d["decision"] == "allow":
+            return None
+        if d["decision"] == "deny":
+            if self.on_deny == "message":
+                return self.message(call, d)
+            raise GuardDeny(d)
+        if self.on_hold == "interrupt":
+            # Not inside a try: interrupt pauses the graph by raising.
+            resume = self.interrupt({"type": HOLD_INTERRUPT_TYPE, "tool_call": {"name": call.get("name"), "id": call.get("id")}, "decision": d, "message": describe(d)})
+            if is_approval(resume):
+                return None
+            if self.tool_message is not None:
+                return self.message(call, d, " A person did not approve it.")
+            raise GuardHold(d)
+        if self.on_hold == "message":
+            return self.message(call, d)
+        raise GuardHold(d)
+
+
+def tool_call_wrapper(
+    policy_path: str,
+    *,
+    interrupt: Optional[Callable[[Any], Any]] = None,
+    tool_message: Optional[Callable[..., Any]] = None,
+    on_hold: Optional[str] = None,
+    on_deny: str = "raise",
+    tools: Optional[Sequence[str]] = None,
+    on_decision: Optional[Callable[[dict], None]] = None,
+    **decide_kw: Any,
+) -> Callable[[Any, Callable[[Any], Any]], Any]:
+    """A (request, handler) function for langchain.agents.middleware.wrap_tool_call.
+
+    tools: the policy's applies_to.tools globs; other tools run without asking.
+    """
+    plan = _Plan(policy_path, interrupt, tool_message, on_hold, on_deny, tools, on_decision, decide_kw)
+
+    def trooth_guard(request: Any, handler: Callable[[Any], Any]) -> Any:
+        call = _call_of(request)
+        out = plan.after(call, plan.decision(call))
+        return handler(request) if out is None else out
+
+    trooth_guard.__name__ = "trooth_guard"
+    return trooth_guard
+
+
+def atool_call_wrapper(policy_path: str, **kw: Any) -> Callable[[Any, Callable[[Any], Awaitable[Any]]], Awaitable[Any]]:
+    """The async form of tool_call_wrapper; the CLI runs in a worker thread."""
+    plan = _Plan(policy_path, kw.pop("interrupt", None), kw.pop("tool_message", None), kw.pop("on_hold", None), kw.pop("on_deny", "raise"), kw.pop("tools", None), kw.pop("on_decision", None), kw)
+
+    async def trooth_guard(request: Any, handler: Callable[[Any], Awaitable[Any]]) -> Any:
+        call = _call_of(request)
+        d = await asyncio.to_thread(plan.decision, call)
+        out = plan.after(call, d)
+        return await handler(request) if out is None else out
+
+    trooth_guard.__name__ = "trooth_guard"
+    return trooth_guard
+
+
+def middleware(policy_path: str, **kw: Any) -> Any:
+    """An AgentMiddleware instance with wrap_tool_call and awrap_tool_call. Imports langchain."""
+    from langchain.agents.middleware import AgentMiddleware  # optional; only here
+
+    sync_fn = tool_call_wrapper(policy_path, **dict(kw))
+    async_fn = atool_call_wrapper(policy_path, **dict(kw))
+
+    class TroothGuardMiddleware(AgentMiddleware):
+        def wrap_tool_call(self, request, handler):
+            return sync_fn(request, handler)
+
+        async def awrap_tool_call(self, request, handler):
+            return await async_fn(request, handler)
+
+    return TroothGuardMiddleware()

trooth_guard/langgraph.py

@@ -0,0 +1,103 @@
+"""The Trooth guard as a LangGraph node that runs before the tool node.
+
+Followed, read on October 7, 2026:
+  https://docs.langchain.com/oss/python/langgraph/interrupts  (interrupt(value) pauses the
+    graph; graph.invoke(Command(resume=...), config) with the same thread_id resumes it and
+    interrupt returns the resume value; interrupt raises to pause, so it is never called
+    inside a try; the node runs again from the top on resume)
+
+    from langgraph.types import interrupt, Command
+    from trooth_guard.langgraph import guard_node
+
+    builder.add_node("trooth_guard", guard_node("policy.yaml", interrupt=interrupt))
+    builder.add_edge("trooth_guard", "tools")
+
+The node reads the tool calls of the last message in state["messages"] and
+decides each in order. Any deny raises GuardDeny (or routes to deny_goto with
+Command). Any hold, and no deny, calls interrupt once for all held calls; a
+resume that approves lets the tool node run, anything else raises GuardHold
+(or routes to hold_goto). This module imports nothing from langgraph unless
+interrupt is not passed, when it imports langgraph.types.interrupt.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Mapping, Optional
+
+from .core import GuardDeny, GuardHold, covered, decide, describe, is_approval
+
+HOLD_INTERRUPT_TYPE = "trooth_guard_hold"
+
+
+def _tool_calls(state: Any, key: str) -> List[Mapping[str, Any]]:
+    msgs = state.get(key) if isinstance(state, Mapping) else getattr(state, key, None)
+    if not msgs:
+        return []
+    last = msgs[-1]
+    calls = last.get("tool_calls") if isinstance(last, Mapping) else getattr(last, "tool_calls", None)
+    return list(calls or [])
+
+
+def guard_node(
+    policy_path: str,
+    *,
+    interrupt: Optional[Callable[[Any], Any]] = None,
+    tools: Optional[List[str]] = None,
+    messages_key: str = "messages",
+    decisions_key: Optional[str] = None,
+    command: Optional[Callable[..., Any]] = None,
+    deny_goto: Optional[str] = None,
+    hold_goto: Optional[str] = None,
+    tools_goto: Optional[str] = None,
+    on_decision: Optional[Callable[[dict], None]] = None,
+    **decide_kw: Any,
+) -> Callable[[Any], Any]:
+    """A node function for StateGraph.add_node. tools: the policy's applies_to.tools
+    globs; calls to other tools are not decided. None decides every call."""
+    if interrupt is None:
+        from langgraph.types import interrupt as _interrupt  # optional; only when not passed
+
+        interrupt = _interrupt
+    if (deny_goto or hold_goto) and command is None:
+        raise TypeError("deny_goto and hold_goto need command (langgraph.types.Command)")
+    # LangGraph runs a node's static edges in addition to a returned Command's goto,
+    # so a static edge to the tool node would also run after a routed deny. Routing
+    # needs tools_goto, no static edge from this node, and destinations declared.
+    if (deny_goto or hold_goto) and not tools_goto:
+        raise TypeError("deny_goto and hold_goto need tools_goto, and the graph must have no static edge from this node")
+
+    def update(decisions: List[Dict[str, Any]]) -> Dict[str, Any]:
+        return {decisions_key: decisions} if decisions_key else {}
+
+    def trooth_guard_node(state: Any) -> Any:
+        decisions: List[Dict[str, Any]] = []
+        for call in _tool_calls(state, messages_key):
+            name = call.get("name") if isinstance(call, Mapping) else getattr(call, "name", None)
+            args = call.get("args") if isinstance(call, Mapping) else getattr(call, "args", None)
+            cid = call.get("id") if isinstance(call, Mapping) else getattr(call, "id", None)
+            if not covered(name, tools):
+                continue
+            d = decide(policy_path, str(name), None, args if args is not None else {}, **decide_kw)
+            if d is None:
+                continue
+            if on_decision:
+                on_decision(d)
+            decisions.append({"tool_call": {"name": name, "id": cid}, "decision": d})
+        denied = [x for x in decisions if x["decision"]["decision"] == "deny"]
+        if denied:
+            if deny_goto:
+                return command(goto=deny_goto, update=update(decisions))
+            raise GuardDeny(denied[0]["decision"])
+        held = [x for x in decisions if x["decision"]["decision"] == "hold"]
+        if held:
+            # Not inside a try: interrupt pauses the graph by raising.
+            resume = interrupt({"type": HOLD_INTERRUPT_TYPE, "held": held, "message": " ".join(describe(x["decision"]) for x in held)})
+            if not is_approval(resume):
+                if hold_goto:
+                    return command(goto=hold_goto, update=update(decisions))
+                raise GuardHold(held[0]["decision"])
+        if tools_goto:
+            return command(goto=tools_goto, update=update(decisions))
+        return update(decisions)
+
+    return trooth_guard_node