underwrit-client 0.3.0__tar.gz

underwrit_client-0.3.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: underwrit-client
+Version: 0.3.0
+Summary: Client for an Underwrit data plane: decide, claim, record, and produce evidence for what an agent did.
+License: MIT
+Project-URL: Homepage, https://github.com/underwrit-io/dataplane
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# underwrit-client
+
+Integrate an agent runtime with an Underwrit data plane. Standard library only.
+
+```python
+import os
+from underwrit_client import Underwrit, Held
+
+underwrit = Underwrit("http://127.0.0.1:8787", token=os.environ["UNDERWRIT_AGENT_TOKEN"])
+
+with underwrit.session(agent="ops-assistant", environment="production",
+                  intent="Restart api during incident 4417") as s:
+    logs = s.call("k8s/get_k8s_logs", get_logs, pod="api-1")
+    try:
+        s.call("k8s/rollout_restart", restart, deployment="api", namespace="prod")
+    except Held as h:
+        park(h.decision["id"])            # a person answers in the console, then:
+        s.resume(h.decision["id"], restart, deployment="api", namespace="prod",
+                 verify=lambda r: {"status": "passed", "checks": [{"name": "rollout", "ok": True}]})
+```
+
+- `call()` decides, runs the function, and records the outcome. It raises `Held` when the data
+  plane says `act: "hold"` — enforcement on, verdict held or denied. In shadow mode nothing is
+  raised and the verdict is still recorded.
+- `resume()` claims an approval with the same arguments immediately before executing. The claim is
+  refused if the arguments or the stated preconditions changed, the approval expired, the policy
+  now refuses it, or it was already used.
+- A `TimeoutError` from the wrapped function is recorded as `uncertain`, and the data plane will not
+  let a retry overwrite that without `reconcile=True`.
+- `verify=` records what was observed afterwards, separately from whether the call succeeded.
+
+The full routes are in the Underwrit README; this client adds nothing the service does not do.
+
+## Also
+
+- `open_session(..., task_policy={...})` attaches a t=0 task policy; `guarded(session, tool)` wraps a
+  function so every call goes through the session.
+- `decide(..., signals={"taint": True, "risk": 80, "source": "my-classifier"})` lets an external
+  classifier raise taint or risk; it can never lower them.
+- `receipt(seq)` returns the per-entry receipt (leaf index, tree size, root, inclusion proof, signed
+  checkpoint) once a checkpoint covers the entry; `Decision["receipt"]` carries the chain position now.
+- 429 and 503 are retried with `Retry-After` (three times by default, capped at thirty seconds).
+- `Held` exposes `id`, `verdict`, `budgeted`, `duplicate`, `quorum` and `risk`.

underwrit_client-0.3.0/README.md

@@ -0,0 +1,43 @@
+# underwrit-client
+
+Integrate an agent runtime with an Underwrit data plane. Standard library only.
+
+```python
+import os
+from underwrit_client import Underwrit, Held
+
+underwrit = Underwrit("http://127.0.0.1:8787", token=os.environ["UNDERWRIT_AGENT_TOKEN"])
+
+with underwrit.session(agent="ops-assistant", environment="production",
+                  intent="Restart api during incident 4417") as s:
+    logs = s.call("k8s/get_k8s_logs", get_logs, pod="api-1")
+    try:
+        s.call("k8s/rollout_restart", restart, deployment="api", namespace="prod")
+    except Held as h:
+        park(h.decision["id"])            # a person answers in the console, then:
+        s.resume(h.decision["id"], restart, deployment="api", namespace="prod",
+                 verify=lambda r: {"status": "passed", "checks": [{"name": "rollout", "ok": True}]})
+```
+
+- `call()` decides, runs the function, and records the outcome. It raises `Held` when the data
+  plane says `act: "hold"` — enforcement on, verdict held or denied. In shadow mode nothing is
+  raised and the verdict is still recorded.
+- `resume()` claims an approval with the same arguments immediately before executing. The claim is
+  refused if the arguments or the stated preconditions changed, the approval expired, the policy
+  now refuses it, or it was already used.
+- A `TimeoutError` from the wrapped function is recorded as `uncertain`, and the data plane will not
+  let a retry overwrite that without `reconcile=True`.
+- `verify=` records what was observed afterwards, separately from whether the call succeeded.
+
+The full routes are in the Underwrit README; this client adds nothing the service does not do.
+
+## Also
+
+- `open_session(..., task_policy={...})` attaches a t=0 task policy; `guarded(session, tool)` wraps a
+  function so every call goes through the session.
+- `decide(..., signals={"taint": True, "risk": 80, "source": "my-classifier"})` lets an external
+  classifier raise taint or risk; it can never lower them.
+- `receipt(seq)` returns the per-entry receipt (leaf index, tree size, root, inclusion proof, signed
+  checkpoint) once a checkpoint covers the entry; `Decision["receipt"]` carries the chain position now.
+- 429 and 503 are retried with `Retry-After` (three times by default, capped at thirty seconds).
+- `Held` exposes `id`, `verdict`, `budgeted`, `duplicate`, `quorum` and `risk`.

underwrit_client-0.3.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "underwrit-client"
+version = "0.3.0"
+description = "Client for an Underwrit data plane: decide, claim, record, and produce evidence for what an agent did."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = []
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Security",
+]
+
+[project.urls]
+Homepage = "https://github.com/underwrit-io/dataplane"
+
+[project.scripts]
+underwrit-hook = "underwrit_client.integrations.claude_code:main"
+underwrit-interceptor = "underwrit_client.integrations.http_interceptor:main"
+
+[tool.setuptools]
+packages = ["underwrit_client", "underwrit_client.integrations"]

underwrit_client-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

underwrit_client-0.3.0/underwrit_client/__init__.py

@@ -0,0 +1,265 @@
+"""underwrit-client: integrate an agent runtime with an Underwrit data plane in under twenty lines.
+
+    from underwrit_client import Underwrit, Held
+
+    underwrit = Underwrit("http://127.0.0.1:8787", token=os.environ["UNDERWRIT_AGENT_TOKEN"])
+    with underwrit.session(agent="ops-assistant", environment="production",
+                      intent="Restart api during incident 4417") as s:
+        logs = s.call("k8s/get_k8s_logs", get_logs, pod="api-1")          # decided, run, recorded
+        try:
+            s.call("k8s/rollout_restart", restart, deployment="api")        # held? raises Held
+        except Held as h:
+            print("waiting on a person:", h.decision["id"])
+
+Standard library only. Every method maps to one data-plane route, and the shapes returned are the
+service's own — nothing is reinterpreted here.
+
+**`Held` is the contract.** When the data plane says `act: "hold"`, the wrapped call is not made
+and `Held` is raised with the decision attached, so a runtime can park the task, show the decision
+id, and come back with `claim()` once a person has answered. In shadow mode `act` is `"proceed"`
+and nothing is raised; the verdict is still recorded.
+
+**A claim before an approved execution.** `claim()` presents the same arguments again and is told
+whether the approval still holds — same arguments, same relevant state, still within its validity
+window, not already used. Use it immediately before executing anything that was held.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Callable
+
+__version__ = "0.3.0"
+__all__ = ["Underwrit", "Session", "Held", "UnderwritError", "guarded"]
+
+
+class UnderwritError(Exception):
+    """The data plane refused or failed a request. `status` is the HTTP status."""
+
+    def __init__(self, status: int, message: str):
+        super().__init__(f"{status}: {message}")
+        self.status = status
+        self.message = message
+
+
+class Held(Exception):
+    """The action must not proceed until a person answers, or was refused.
+
+    `decision` is the data plane's response — its `id` is what to resolve, and `reasons` say why.
+    """
+
+    def __init__(self, decision: dict, reason: str = ""):
+        rs = decision.get("reasons") or ([reason] if reason else [])
+        super().__init__(f"{decision.get('verdict', 'held')}: {'; '.join(rs) or 'held for a person'}")
+        self.decision = decision
+        self.reason = reason or (rs[0] if rs else "")
+        # What the data plane said beside the verdict, so a runtime can act on it without parsing.
+        self.id: str = str(decision.get("id") or "")
+        self.verdict: str = str(decision.get("verdict") or "")
+        self.budgeted: bool = bool(decision.get("budgeted"))
+        self.duplicate: bool = bool(decision.get("duplicate"))
+        self.quorum: dict | None = decision.get("quorum") if isinstance(decision.get("quorum"), dict) else None
+        self.risk: int = int(decision.get("risk") or 0)
+
+
+class Underwrit:
+    def __init__(self, url: str, token: str, *, timeout: float = 10.0, retries: int = 3,
+                 max_retry_wait: float = 30.0, sleep: Callable[[float], None] = time.sleep):
+        self.url = url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self.retries = retries
+        self.max_retry_wait = max_retry_wait
+        self._sleep = sleep
+
+    # -- transport -------------------------------------------------------------------------
+
+    def _call(self, method: str, path: str, body: dict | None = None) -> dict:
+        """One request. 429 and 503 are retried, honouring Retry-After, up to `retries` times and
+        never longer than `max_retry_wait` per wait; every other error is the caller's."""
+        attempt = 0
+        while True:
+            req = urllib.request.Request(
+                f"{self.url}{path}",
+                data=json.dumps(body).encode("utf-8") if body is not None else None,
+                headers={"Content-Type": "application/json", "Authorization": f"Bearer {self.token}"},
+                method=method,
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                    return json.loads(r.read().decode("utf-8") or "{}")
+            except urllib.error.HTTPError as e:
+                try:
+                    payload = json.loads(e.read().decode("utf-8") or "{}")
+                except ValueError:
+                    payload = {}
+                if e.code in (429, 503) and attempt < self.retries:
+                    attempt += 1
+                    try:
+                        wait = float(e.headers.get("Retry-After") or payload.get("retryAfterSeconds") or 0)
+                    except (TypeError, ValueError):
+                        wait = 0.0
+                    self._sleep(min(self.max_retry_wait, wait or min(2.0 ** attempt, self.max_retry_wait)))
+                    continue
+                raise UnderwritError(e.code, payload.get("error", "") or e.reason) from None
+            except urllib.error.URLError as e:
+                raise UnderwritError(0, f"cannot reach {self.url}: {e.reason}") from None
+
+    # -- the routes ------------------------------------------------------------------------
+
+    def open_session(self, *, session: str = "", agent: str = "", environment: str = "",
+                     intent: str = "", actor: str = "", task_policy: dict | None = None) -> "Session":
+        s = self._call("POST", "/v1/sessions", {"session": session, "agent": agent,
+                                                "environment": environment, "intent": intent,
+                                                "actor": actor,
+                                                **({"taskPolicy": task_policy} if task_policy else {})})
+        return Session(self, s["id"], s)
+
+    session = open_session
+
+    def decide(self, session: str, tool: str, arguments: dict | None = None, *,
+               preconditions: Any = None, idempotency_key: str = "", signals: dict | None = None) -> dict:
+        """`signals` carries an external classifier's verdict ({"taint": True, "risk": 80,
+        "source": "my-classifier"}); it can raise taint and risk, never lower them."""
+        body: dict = {"session": session, "tool": tool, "arguments": arguments or {}}
+        if preconditions is not None:
+            body["preconditions"] = preconditions
+        if idempotency_key:
+            body["idempotencyKey"] = idempotency_key
+        if signals:
+            body["signals"] = signals
+        return self._call("POST", "/v1/decide", body)
+
+    def receipt(self, seq: int) -> dict:
+        """The per-entry receipt: leaf index, tree size, root, inclusion proof and the signed
+        checkpoint. `pending: True` until a checkpoint covers the entry."""
+        return self._call("GET", f"/v1/receipts/{int(seq)}")
+
+    def pending(self, limit: int = 100, offset: int = 0) -> dict:
+        return self._call("GET", f"/v1/pending?limit={int(limit)}&offset={int(offset)}")
+
+    def claim(self, decision_id: str, arguments: dict | None = None, *,
+              preconditions: Any = None) -> dict:
+        body: dict = {}
+        if arguments is not None:
+            body["arguments"] = arguments
+        if preconditions is not None:
+            body["preconditions"] = preconditions
+        return self._call("POST", f"/v1/decisions/{decision_id}/claim", body)
+
+    def outcome(self, decision_id: str, status: str, detail: str = "", *,
+                verification: dict | None = None, reconcile: bool = False) -> dict:
+        body: dict = {"decision": decision_id, "status": status, "detail": detail}
+        if verification:
+            body["verification"] = verification
+        if reconcile:
+            body["reconcile"] = True
+        return self._call("POST", "/v1/outcome", body)
+
+    def decision(self, decision_id: str) -> dict:
+        return self._call("GET", f"/v1/decisions/{decision_id}")
+
+    def close(self, session: str, status: str = "succeeded") -> dict:
+        return self._call("POST", f"/v1/sessions/{session}/close", {"status": status})
+
+    def evidence(self, session: str) -> dict:
+        return self._call("GET", f"/v1/evidence/{session}")
+
+    def health(self) -> dict:
+        return self._call("GET", "/v1/health")
+
+
+class Session:
+    """One agent session. A context manager: closes on exit, `failed` if an exception escaped."""
+
+    def __init__(self, underwrit: Underwrit, session_id: str, meta: dict | None = None):
+        self.underwrit = underwrit
+        self.id = session_id
+        self.meta = meta or {}
+
+    def __enter__(self) -> "Session":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        try:
+            self.underwrit.close(self.id, "failed" if exc_type else "succeeded")
+        except UnderwritError:
+            pass
+        return False
+
+    def decide(self, tool: str, arguments: dict | None = None, **kw) -> dict:
+        return self.underwrit.decide(self.id, tool, arguments, **kw)
+
+    def outcome(self, decision_id: str, status: str, detail: str = "", **kw) -> dict:
+        return self.underwrit.outcome(decision_id, status, detail, **kw)
+
+    def claim(self, decision_id: str, arguments: dict | None = None, **kw) -> dict:
+        return self.underwrit.claim(decision_id, arguments, **kw)
+
+    def call(self, tool: str, fn: Callable[..., Any], /, *args, preconditions: Any = None,
+             idempotency_key: str = "", verify: Callable[[Any], dict] | None = None,
+             signals: dict | None = None, **kwargs) -> Any:
+        """Decide, then run `fn(*args, **kwargs)`, then report what happened. Raises `Held`.
+
+        The keyword arguments are the action's arguments as the data plane sees them; positional
+        arguments are passed through to `fn` but are not part of the decision.
+        """
+        d = self.decide(tool, kwargs, preconditions=preconditions, idempotency_key=idempotency_key, signals=signals)
+        if d.get("act") == "hold":
+            raise Held(d)
+        return self._run(d["id"], fn, args, kwargs, verify)
+
+    def resume(self, decision_id: str, fn: Callable[..., Any], /, *args,
+               preconditions: Any = None, verify: Callable[[Any], dict] | None = None,
+               **kwargs) -> Any:
+        """After a person answered: claim the approval with the same arguments, then run."""
+        c = self.claim(decision_id, kwargs, preconditions=preconditions)
+        if not c.get("ok") and c.get("act") == "hold":
+            raise Held(c.get("decision") or {"id": decision_id}, c.get("reason", ""))
+        return self._run(decision_id, fn, args, kwargs, verify)
+
+    def _run(self, decision_id, fn, args, kwargs, verify):
+        try:
+            result = fn(*args, **kwargs)
+        except TimeoutError as exc:
+            # A timeout may mean the action completed and the response was lost. Recorded as
+            # uncertain, which the data plane refuses to let a retry overwrite silently.
+            self.outcome(decision_id, "uncertain", str(exc)[:2000])
+            raise
+        except Exception as exc:
+            self.outcome(decision_id, "failed", str(exc)[:2000])
+            raise
+        detail = result if isinstance(result, str) else json.dumps(result, default=str)[:2000]
+        ver = None
+        if verify is not None:
+            try:
+                ver = verify(result)
+            except Exception as exc:  # noqa: BLE001 — a broken check is a failed verification
+                ver = {"status": "failed", "summary": f"verification raised {type(exc).__name__}"}
+        self.outcome(decision_id, "succeeded", detail, verification=ver)
+        return result
+
+
+def guarded(session: Session, tool: str | None = None, **opts):
+    """Decorate a tool function so every call goes through the session first.
+
+        @guarded(session, "bank/send_money")
+        def send_money(amount, recipient): ...
+
+    The function must be called with keyword arguments; they are the action's arguments.
+    """
+
+    def wrap(fn):
+        name = tool or fn.__name__
+
+        @functools.wraps(fn)
+        def inner(**kwargs):
+            return session.call(name, fn, **opts, **kwargs)
+
+        return inner
+
+    return wrap

underwrit_client-0.3.0/underwrit_client/integrations/__init__.py

@@ -0,0 +1,8 @@
+"""Adapters that put an Underwrit decision inside each framework's own pause.
+
+Every framework ships a "pause before the tool call"; none ships the decision, the separate
+approver, or the evidence. These adapters are thin on purpose: each maps one framework's hook onto
+`Session.decide` / `Session.claim` / `Session.outcome` and nothing else, so what a framework sees is
+exactly what the data plane decided. No framework is imported at module load; each adapter imports
+its framework lazily or not at all.
+"""

underwrit_client-0.3.0/underwrit_client/integrations/claude_code.py

@@ -0,0 +1,102 @@
+"""Claude Code hooks: PreToolUse decides, PostToolUse records the outcome.
+
+    # .claude/settings.json
+    {"hooks": {
+      "PreToolUse":  [{"matcher": "", "hooks": [{"type": "command", "command": "underwrit-hook pre"}]}],
+      "PostToolUse": [{"matcher": "", "hooks": [{"type": "command", "command": "underwrit-hook post"}]}]
+    }}
+
+The hook reads Claude Code's JSON on stdin (session_id, tool_name, tool_input, tool_response) and
+answers with a `permissionDecision`: `allow` for allow and allow_recorded, `ask` for a hold, `deny`
+for a denial. `ask` hands the decision to the person at the terminal — Underwrit records that a hold was
+raised; who answered it is that person, and the PostToolUse hook records what happened.
+
+Environment: UNDERWRIT_URL, UNDERWRIT_AGENT_TOKEN, optionally UNDERWRIT_ENVIRONMENT and UNDERWRIT_AGENT. The Claude
+Code session id becomes the Underwrit session id, so one conversation is one evidence subject.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from .. import Underwrit, UnderwritError
+
+_PERMISSION = {"allow": "allow", "allow_recorded": "allow", "require_human": "ask", "deny": "deny"}
+
+
+def _client() -> Underwrit:
+    return Underwrit(os.environ.get("UNDERWRIT_URL", "http://127.0.0.1:8787"), os.environ.get("UNDERWRIT_AGENT_TOKEN", ""))
+
+
+def _state_path(session_id: str) -> str:
+    return os.path.join(os.environ.get("TMPDIR", "/tmp"), f"underwrit-claude-{session_id}.json")
+
+
+def pre(event: dict) -> dict:
+    """Decide. Returns the hook's JSON output."""
+    sid = f"claude-{event.get('session_id', 'unknown')}"
+    tool = f"claude/{event.get('tool_name', '')}"
+    args = event.get("tool_input") if isinstance(event.get("tool_input"), dict) else {"input": event.get("tool_input")}
+    w = _client()
+    try:
+        w.open_session(session=sid, agent=os.environ.get("UNDERWRIT_AGENT", "claude-code"),
+                       environment=os.environ.get("UNDERWRIT_ENVIRONMENT", "dev"),
+                       intent=str(event.get("prompt") or "")[:400])
+        d = w.decide(sid, tool, args)
+    except UnderwritError as exc:
+        # The data plane is unreachable or refused: fail the way the operator chose. Default is
+        # to ask, which is the safe side of a decision plane that could not decide.
+        mode = os.environ.get("UNDERWRIT_HOOK_ON_ERROR", "ask")
+        return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": mode,
+                                       "permissionDecisionReason": f"Underwrit unavailable ({exc.message}); {mode}"}}
+    # Remember the decision id for the PostToolUse hook; Claude Code gives both hooks the tool_use_id.
+    try:
+        with open(_state_path(sid), "a") as f:
+            f.write(json.dumps({"tool_use_id": event.get("tool_use_id"), "decision": d["id"]}) + "\n")
+    except OSError:
+        pass
+    reason = "; ".join(d.get("reasons") or []) or d["verdict"]
+    return {"hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": _PERMISSION.get(d["verdict"], "ask"),
+        "permissionDecisionReason": f"Underwrit {d['verdict']} (decision {d['id']}, risk {d.get('risk', 0)}): {reason}",
+    }}
+
+
+def post(event: dict) -> dict:
+    """Record the outcome of the call the PreToolUse hook decided."""
+    sid = f"claude-{event.get('session_id', 'unknown')}"
+    did = None
+    try:
+        with open(_state_path(sid)) as f:
+            for line in f:
+                rec = json.loads(line)
+                if rec.get("tool_use_id") == event.get("tool_use_id"):
+                    did = rec["decision"]
+    except OSError:
+        pass
+    if not did:
+        return {}
+    resp = event.get("tool_response")
+    detail = resp if isinstance(resp, str) else json.dumps(resp, default=str)
+    failed = isinstance(resp, dict) and bool(resp.get("error") or resp.get("is_error"))
+    try:
+        _client().outcome(did, "failed" if failed else "succeeded", detail[:4000])
+    except UnderwritError:
+        pass
+    return {}
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    which = argv[0] if argv else "pre"
+    try:
+        event = json.load(sys.stdin)
+    except ValueError:
+        event = {}
+    out = pre(event) if which == "pre" else post(event)
+    if out:
+        sys.stdout.write(json.dumps(out))
+    return 0

underwrit_client-0.3.0/underwrit_client/integrations/google_adk.py

@@ -0,0 +1,47 @@
+"""Google ADK: a `before_tool_callback` that decides, and a confirmation guard.
+
+    from underwrit_client.integrations.google_adk import before_tool_callback
+    agent = Agent(..., before_tool_callback=before_tool_callback(session))
+
+The callback returns a dict to short-circuit the tool (ADK treats a returned dict as the tool's
+result) when Underwrit says hold or deny with enforcement on. The confirmation guard closes the class of
+bug in CVE-2026-18236: before honouring an `adk_request_confirmation` response, it claims the Underwrit
+decision with the arguments actually about to run, so a confirmation for one call cannot be
+replayed against another.
+"""
+
+from __future__ import annotations
+
+from .. import Session
+
+_by_tool_call: dict[str, str] = {}
+
+
+def before_tool_callback(session: Session, *, prefix: str = "adk"):
+    def _cb(tool, args, tool_context=None):
+        name = getattr(tool, "name", None) or str(tool)
+        d = session.decide(f"{prefix}/{name}", dict(args or {}))
+        key = getattr(tool_context, "function_call_id", None) or name
+        _by_tool_call[key] = d["id"]
+        if d.get("act") == "hold":
+            return {"error": f"held by Underwrit (decision {d['id']}): " + "; ".join(d.get("reasons") or [])}
+        return None
+    return _cb
+
+
+def after_tool_callback(session: Session):
+    def _cb(tool, args, tool_context=None, tool_response=None):
+        name = getattr(tool, "name", None) or str(tool)
+        key = getattr(tool_context, "function_call_id", None) or name
+        did = _by_tool_call.pop(key, None)
+        if did:
+            failed = isinstance(tool_response, dict) and "error" in tool_response
+            session.outcome(did, "failed" if failed else "succeeded", str(tool_response)[:4000])
+        return None
+    return _cb
+
+
+def confirmation_guard(session: Session, decision_id: str, arguments: dict) -> bool:
+    """True only if the approval for `decision_id` still holds for exactly these arguments."""
+    c = session.claim(decision_id, arguments)
+    return bool(c.get("ok"))

underwrit_client-0.3.0/underwrit_client/integrations/http_interceptor.py

@@ -0,0 +1,65 @@
+"""A pre-call HTTP interceptor for gateways that can call out before forwarding a tool call.
+
+Docker MCP Gateway (`--interceptor=before:http:<url>`), LiteLLM custom guardrails, agentgateway
+or Envoy `ext_authz` hops can POST the tool call here and get back allow / deny / hold. It is a
+stdlib HTTP server around one Underwrit session per caller-supplied session id.
+
+    UNDERWRIT_URL=... UNDERWRIT_AGENT_TOKEN=... python3 -m underwrit_client.integrations.http_interceptor 8790
+
+    POST /  {"session": "...", "tool": "...", "arguments": {...}}
+    -> {"allow": bool, "verdict": "...", "decision": "...", "reason": "..."}
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+from .. import Underwrit, UnderwritError
+
+
+def decide(body: dict) -> dict:
+    w = Underwrit(os.environ.get("UNDERWRIT_URL", "http://127.0.0.1:8787"), os.environ.get("UNDERWRIT_AGENT_TOKEN", ""))
+    sid = str(body.get("session") or "interceptor")
+    tool = str(body.get("tool") or (body.get("params") or {}).get("name") or "")
+    args = body.get("arguments") or (body.get("params") or {}).get("arguments") or {}
+    try:
+        w.open_session(session=sid, agent=os.environ.get("UNDERWRIT_AGENT", "gateway"),
+                       environment=os.environ.get("UNDERWRIT_ENVIRONMENT", "dev"))
+        d = w.decide(sid, tool, args if isinstance(args, dict) else {})
+    except UnderwritError as exc:
+        allow = os.environ.get("UNDERWRIT_HOOK_ON_ERROR", "deny") == "allow"
+        return {"allow": allow, "verdict": "unavailable", "reason": exc.message}
+    return {"allow": d.get("act") != "hold", "verdict": d["verdict"], "decision": d["id"],
+            "reason": "; ".join(d.get("reasons") or []), "risk": d.get("risk")}
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *a):
+        pass
+
+    def do_POST(self):
+        n = int(self.headers.get("Content-Length") or 0)
+        try:
+            body = json.loads(self.rfile.read(n) or b"{}")
+        except ValueError:
+            body = {}
+        out = json.dumps(decide(body)).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(out)))
+        self.end_headers()
+        self.wfile.write(out)
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    port = int(argv[0]) if argv else 8790
+    ThreadingHTTPServer(("127.0.0.1", port), Handler).serve_forever()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

underwrit_client-0.3.0/underwrit_client/integrations/langgraph.py

@@ -0,0 +1,33 @@
+"""LangGraph: wrap a tool so an Underwrit hold becomes an `interrupt()` carrying the decision id.
+
+    from underwrit_client.integrations.langgraph import guarded_tool
+
+    send_email = guarded_tool(session, "mail/send_email", send_email_impl)
+
+On `require_human` with enforcement on, the wrapper calls LangGraph's `interrupt()` with the
+decision id and reasons; when the graph resumes (after a person answered in the Underwrit console) it
+claims the decision with the same arguments and runs. In shadow mode it runs and records. Without
+LangGraph installed the wrapper raises `Held` instead, so the same code works under any runner.
+"""
+
+from __future__ import annotations
+
+from .. import Held, Session
+
+
+def guarded_tool(session: Session, tool: str, fn, *, preconditions=None, verify=None):
+    def _run(**kwargs):
+        d = session.decide(tool, kwargs, preconditions=preconditions)
+        if d.get("act") == "hold":
+            try:
+                from langgraph.types import interrupt  # type: ignore
+            except ImportError:
+                raise Held(d)
+            interrupt({"underwrit": {"decision": d["id"], "tool": tool, "reasons": d.get("reasons", []),
+                                "risk": d.get("risk")}})
+            # Resumed: the person answered in Underwrit. Claim with the same arguments before running.
+            return session.resume(d["id"], fn, preconditions=preconditions, verify=verify, **kwargs)
+        return session._run(d["id"], fn, (), kwargs, verify)
+    _run.__name__ = getattr(fn, "__name__", tool)
+    _run.__doc__ = getattr(fn, "__doc__", None)
+    return _run

underwrit_client-0.3.0/underwrit_client/integrations/openai_agents.py

@@ -0,0 +1,42 @@
+"""OpenAI Agents SDK: `needs_approval` from an Underwrit decision, and outcomes from tool results.
+
+    from underwrit_client.integrations.openai_agents import needs_approval, record_outcome
+
+    @function_tool(needs_approval=needs_approval(session, "bank/send_money"))
+    def send_money(recipient: str, amount: float) -> str: ...
+
+`needs_approval` returns True only when Underwrit says `require_human` with enforcement on, so the SDK
+pauses and surfaces a `ToolApprovalItem`; in shadow mode the decision is recorded and the call
+proceeds. The decision id is kept per call id so `record_outcome` can close it. Nothing here
+imports the SDK; the callable signature `(ctx, args, call_id)` is what it expects.
+"""
+
+from __future__ import annotations
+
+import json
+
+from .. import Session
+
+_by_call: dict[str, str] = {}
+
+
+def needs_approval(session: Session, tool: str, *, preconditions=None):
+    async def _needs(ctx, args, call_id=None):
+        arguments = args if isinstance(args, dict) else (json.loads(args) if isinstance(args, str) else {})
+        d = session.decide(tool, arguments, preconditions=preconditions, idempotency_key=call_id or "")
+        if call_id:
+            _by_call[call_id] = d["id"]
+        return d.get("act") == "hold"
+    return _needs
+
+
+def approve(session: Session, call_id: str, arguments: dict | None = None) -> dict:
+    """After a person approved in the SDK, claim the Underwrit decision before the tool actually runs."""
+    return session.claim(_by_call[call_id], arguments)
+
+
+def record_outcome(session: Session, call_id: str, result, *, failed: bool = False) -> None:
+    did = _by_call.pop(call_id, None)
+    if did:
+        detail = result if isinstance(result, str) else json.dumps(result, default=str)
+        session.outcome(did, "failed" if failed else "succeeded", detail[:4000])

underwrit_client-0.3.0/underwrit_client/integrations/otel.py

@@ -0,0 +1,72 @@
+"""OpenTelemetry: one span per Underwrit decision, with the attributes the GenAI conventions lack.
+
+The GenAI semantic conventions carry `gen_ai.tool.name` and `gen_ai.tool.call.id` and nothing for
+a policy decision or a human approval. These are the attributes Underwrit emits, proposed for that gap:
+
+    underwrit.decision            allow | allow_recorded | require_human | deny
+    underwrit.decision.id         the decision id (joins to the evidence bundle)
+    underwrit.policy.version
+    underwrit.taint               true when the session had consumed untrusted content
+    underwrit.authority           authorized | untrusted | violates | unknown | none
+    underwrit.risk                0–100
+    underwrit.act                 proceed | hold
+    underwrit.chain.args_digest   the keyed argument digest — never an argument value
+
+The same facts are emitted a second time under the names proposed to the OpenTelemetry GenAI
+SIG (`docs/OTEL-PROPOSAL.md`): `gen_ai.policy.decision`, `gen_ai.policy.enforced`,
+`gen_ai.policy.engine`, `gen_ai.policy.version`, `gen_ai.policy.decision.id`, `gen_ai.policy.risk`,
+`gen_ai.policy.provenance`, `gen_ai.session.tainted`, `gen_ai.approval.required`,
+`gen_ai.approval.binding`. Both namespaces stay until the proposal lands or is rejected.
+
+`opentelemetry-api` is imported lazily; without it `record` is a no-op. `attributes()` returns the
+dict for callers that want to attach it to their own span.
+"""
+
+from __future__ import annotations
+
+
+PROPOSED_ENGINE = "underwrit"
+
+
+def attributes(decision: dict, *, tool: str, session_id: str) -> dict:
+    """Every attribute `record` sets, as a plain dict (no OpenTelemetry needed)."""
+    verdict = decision.get("verdict", "")
+    status = (decision.get("authority") or {}).get("status", "none")
+    provenance = {"authorized": "user", "untrusted": "untrusted", "unknown": "unknown", "none": "none",
+                  "violates": "violates"}.get(status, status)
+    return {
+        "gen_ai.tool.name": tool,
+        # Underwrit's own names (kept).
+        "underwrit.session.id": session_id,
+        "underwrit.decision": verdict,
+        "underwrit.decision.id": decision.get("id", ""),
+        "underwrit.policy.version": int(decision.get("policyVersion") or 0),
+        "underwrit.taint": bool(decision.get("taint")),
+        "underwrit.authority": status,
+        "underwrit.risk": int(decision.get("risk") or 0),
+        "underwrit.act": decision.get("act", ""),
+        "underwrit.chain.args_digest": decision.get("argsDigest", ""),
+        # The proposed GenAI semantic-convention names (docs/OTEL-PROPOSAL.md).
+        "gen_ai.policy.decision": verdict,
+        "gen_ai.policy.enforced": bool(decision.get("enforced")),
+        "gen_ai.policy.engine": PROPOSED_ENGINE,
+        "gen_ai.policy.version": str(decision.get("policyVersion") or 0),
+        "gen_ai.policy.decision.id": decision.get("id", ""),
+        "gen_ai.policy.risk": int(decision.get("risk") or 0),
+        "gen_ai.policy.provenance": provenance,
+        "gen_ai.session.tainted": bool(decision.get("taint")),
+        "gen_ai.approval.required": verdict == "require_human",
+        "gen_ai.approval.binding": decision.get("argsDigest", ""),
+    }
+
+
+
+def record(decision: dict, *, tool: str, session_id: str, tracer_name: str = "underwrit") -> None:
+    try:
+        from opentelemetry import trace  # type: ignore
+    except ImportError:
+        return
+    tracer = trace.get_tracer(tracer_name)
+    with tracer.start_as_current_span("underwrit.decide") as span:
+        for k, v in attributes(decision, tool=tool, session_id=session_id).items():
+            span.set_attribute(k, v)

underwrit_client-0.3.0/underwrit_client/task.py

@@ -0,0 +1,53 @@
+"""Draft a task policy at t=0, with whatever model the runtime already has.
+
+    from underwrit_client.task import draft_prompt, parse_draft
+    policy = parse_draft(llm(draft_prompt(user_request, tools)))
+    session = underwrit.open_session(intent=user_request, task_policy=policy)
+
+The model sees the user's request and the tool catalogue — never a tool result — and answers
+with the tools the task needs and the values its authority-bearing fields may take. Underwrit enforces
+the answer deterministically at every sink, so nothing an injected string says later can widen it.
+The model is the runtime's; this file only writes the prompt and reads the answer.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+PROMPT = """You are scoping one task for an agent before it runs. You will see only the user's request and the
+tools available. Answer with JSON and nothing else:
+
+{"allowedTools": [tool names this request needs],
+ "constraints": {"<field>": [exact values or "re:<regex>" the request implies, e.g. a named recipient or amount]},
+ "openFields": [fields the request deliberately leaves to content the agent will read, e.g. "recipients"
+                when the request says "email each person mentioned in the file"],
+ "draftedBy": "<your model name>"}
+
+Rules: list only tools the request needs; put a value in constraints only if the request itself names it;
+put a field in openFields only if the request explicitly delegates it to content. Never invent values.
+
+Request: {request}
+
+Tools: {tools}
+"""
+
+
+def draft_prompt(request: str, tools: list[str]) -> str:
+    return PROMPT.replace("{request}", request.strip()).replace("{tools}", ", ".join(tools))
+
+
+def parse_draft(text: str) -> dict:
+    """The model's JSON, tolerant of fences. Raises ValueError if it is not a task policy."""
+    m = re.search(r"\{.*\}", text, re.S)
+    if not m:
+        raise ValueError("no JSON object in the draft")
+    doc = json.loads(m.group(0))
+    out = {"allowedTools": [str(t) for t in doc.get("allowedTools", [])],
+           "constraints": {str(k): [str(x) for x in (v if isinstance(v, list) else [v])]
+                           for k, v in (doc.get("constraints") or {}).items()},
+           "openFields": [str(f) for f in doc.get("openFields", [])],
+           "draftedBy": str(doc.get("draftedBy") or "")}
+    if not out["allowedTools"]:
+        raise ValueError("a task policy must name at least one tool")
+    return out

underwrit_client-0.3.0/underwrit_client.egg-info/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: underwrit-client
+Version: 0.3.0
+Summary: Client for an Underwrit data plane: decide, claim, record, and produce evidence for what an agent did.
+License: MIT
+Project-URL: Homepage, https://github.com/underwrit-io/dataplane
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# underwrit-client
+
+Integrate an agent runtime with an Underwrit data plane. Standard library only.
+
+```python
+import os
+from underwrit_client import Underwrit, Held
+
+underwrit = Underwrit("http://127.0.0.1:8787", token=os.environ["UNDERWRIT_AGENT_TOKEN"])
+
+with underwrit.session(agent="ops-assistant", environment="production",
+                  intent="Restart api during incident 4417") as s:
+    logs = s.call("k8s/get_k8s_logs", get_logs, pod="api-1")
+    try:
+        s.call("k8s/rollout_restart", restart, deployment="api", namespace="prod")
+    except Held as h:
+        park(h.decision["id"])            # a person answers in the console, then:
+        s.resume(h.decision["id"], restart, deployment="api", namespace="prod",
+                 verify=lambda r: {"status": "passed", "checks": [{"name": "rollout", "ok": True}]})
+```
+
+- `call()` decides, runs the function, and records the outcome. It raises `Held` when the data
+  plane says `act: "hold"` — enforcement on, verdict held or denied. In shadow mode nothing is
+  raised and the verdict is still recorded.
+- `resume()` claims an approval with the same arguments immediately before executing. The claim is
+  refused if the arguments or the stated preconditions changed, the approval expired, the policy
+  now refuses it, or it was already used.
+- A `TimeoutError` from the wrapped function is recorded as `uncertain`, and the data plane will not
+  let a retry overwrite that without `reconcile=True`.
+- `verify=` records what was observed afterwards, separately from whether the call succeeded.
+
+The full routes are in the Underwrit README; this client adds nothing the service does not do.
+
+## Also
+
+- `open_session(..., task_policy={...})` attaches a t=0 task policy; `guarded(session, tool)` wraps a
+  function so every call goes through the session.
+- `decide(..., signals={"taint": True, "risk": 80, "source": "my-classifier"})` lets an external
+  classifier raise taint or risk; it can never lower them.
+- `receipt(seq)` returns the per-entry receipt (leaf index, tree size, root, inclusion proof, signed
+  checkpoint) once a checkpoint covers the entry; `Decision["receipt"]` carries the chain position now.
+- 429 and 503 are retried with `Retry-After` (three times by default, capped at thirty seconds).
+- `Held` exposes `id`, `verdict`, `budgeted`, `duplicate`, `quorum` and `risk`.

underwrit_client-0.3.0/underwrit_client.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+underwrit_client/__init__.py
+underwrit_client/task.py
+underwrit_client.egg-info/PKG-INFO
+underwrit_client.egg-info/SOURCES.txt
+underwrit_client.egg-info/dependency_links.txt
+underwrit_client.egg-info/entry_points.txt
+underwrit_client.egg-info/top_level.txt
+underwrit_client/integrations/__init__.py
+underwrit_client/integrations/claude_code.py
+underwrit_client/integrations/google_adk.py
+underwrit_client/integrations/http_interceptor.py
+underwrit_client/integrations/langgraph.py
+underwrit_client/integrations/openai_agents.py
+underwrit_client/integrations/otel.py

underwrit_client-0.3.0/underwrit_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

underwrit_client-0.3.0/underwrit_client.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+underwrit-hook = underwrit_client.integrations.claude_code:main
+underwrit-interceptor = underwrit_client.integrations.http_interceptor:main

underwrit_client-0.3.0/underwrit_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+underwrit_client