agent-polygraph 0.1.0__py3-none-any.whl

agent_polygraph/__init__.py

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+"""
+agent-polygraph -- a framework-agnostic completion-lie detector for AI agents.
+
+Given one agent turn -- a task, the tool calls and results it produced, and the
+final assistant message ("closing") -- ``verify()`` decides whether the closing
+makes a completion or success claim that the turn's own evidence contradicts.
+
+    from agent_polygraph import verify, ToolCall, ToolResult
+
+    v = verify(
+        [ToolCall("c1", "deploy", {"svc": "web"}),
+         ToolResult("c1", content="ERROR: image pull failed", is_error=True)],
+        final_claim="Done -- deployed successfully.",
+    )
+    v.verdict      # "lie"
+    v.category     # "L1"  (error concealment)
+
+The detector is the clean-room, heuristic-tier reimplementation validated at
+verdict parity with a private production gate (see README). Four framework
+adapters map native emissions onto the same ``verify()`` core:
+
+    from agent_polygraph.adapters import (
+        output_guardrail,     # OpenAI Agents SDK
+        verify_spans,         # OTel / OpenInference
+        stop_hook,            # Claude Code
+        post_call_guardrail,  # LiteLLM
+    )
+
+Pure, synchronous, zero runtime dependencies (standard library only).
+"""
+from __future__ import annotations
+
+from .events import (Message, ToolCall, ToolResult, Event,
+                     from_bench, to_bench, to_item, normalize_event)
+from .verify import (verify, Verdict, Finding, Config, DEFAULT_CONFIG,
+                     DETECTOR_VERSION)
+from .judge import Judge
+
+# Adapter entry points, surfaced at the top level for discoverability.
+from .adapters.openai_agents import output_guardrail, from_openai_agents
+from .adapters.openinference import verify_spans, from_openinference
+from .adapters.claude_code import stop_hook, from_transcript
+from .adapters.litellm import post_call_guardrail, from_litellm
+
+__version__ = "0.1.0"
+# detector_version tracks the package version 1:1 (verdicts self-stamp it).
+detector_version = DETECTOR_VERSION
+
+__all__ = [
+    # core
+    "verify", "Verdict", "Finding", "Config", "DEFAULT_CONFIG",
+    "Judge", "detector_version", "DETECTOR_VERSION",
+    # event model
+    "Message", "ToolCall", "ToolResult", "Event",
+    "from_bench", "to_bench", "to_item", "normalize_event",
+    # adapter entry points
+    "output_guardrail", "from_openai_agents",
+    "verify_spans", "from_openinference",
+    "stop_hook", "from_transcript",
+    "post_call_guardrail", "from_litellm",
+]

agent_polygraph/adapters/__init__.py

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""
+Framework adapters for agent-polygraph.
+
+Each adapter maps one framework's native emission shape into the locked SDK
+trajectory model and calls ``verify()``. Import the entry point you need:
+
+  * ``openai_agents.output_guardrail``  -- OpenAI Agents SDK output guardrail (audit + block)
+  * ``openinference.verify_spans``      -- OTel / OpenInference span consumer (audit only)
+  * ``claude_code.stop_hook``           -- Claude Code Stop hook (audit + block)
+  * ``litellm.post_call_guardrail``     -- LiteLLM post-call guardrail (audit only)
+
+The four modules are also re-exported here for convenience.
+"""
+from __future__ import annotations
+
+from .openai_agents import from_openai_agents, output_guardrail, GuardrailResult
+from .openinference import from_openinference, verify_spans
+from .claude_code import from_transcript, stop_hook
+from .litellm import from_litellm, post_call_guardrail
+
+__all__ = [
+    "from_openai_agents", "output_guardrail", "GuardrailResult",
+    "from_openinference", "verify_spans",
+    "from_transcript", "stop_hook",
+    "from_litellm", "post_call_guardrail",
+]

agent_polygraph/adapters/claude_code.py

@@ -0,0 +1,173 @@
+# -*- coding: utf-8 -*-
+"""
+Adapter 3 -- Claude Code stop-hook.
+
+Consumes the transcript-tail entries a Stop hook sees (human -> assistant
+text+tool_use -> user tool_result -> ... -> final assistant text) and maps them
+to an SDK trajectory. Blocking IS allowed (a stop hook can veto the turn).
+
+Real-emission deltas honoured (CAPTURE-NOTES) -- this is the strongest surface:
+
+  * Structured error bit: ``tool_result.is_error == true`` (absent/None on
+    success), with ``tool_use_id`` linking result <-> call. No sniffing needed.
+  * A SECOND error channel: ``attachment`` entries ``hook_blocking_error`` /
+    ``hook_non_blocking_error`` record a PreToolUse hook that BLOCKED a tool (it
+    never ran). These are NOT tool_results; by ruling they are NOT counted as
+    tool failures (a blocked call is a dangling call, not a returned error).
+  * ``tool_result.content`` is polymorphic: a string (Bash) or a list of
+    ``{"type":"text","text":...}`` blocks (Agent/Task). Both handled.
+  * Truncation is STRUCTURED here: the inline marker is ``[N lines truncated]``
+    (NOT the bench ``[...omitted...]``) and file-read attachments carry
+    ``truncatedByTokenCap: true`` with line counts. The marker match is INFERRED
+    (degraded); the ``truncatedByTokenCap`` flag is STRUCTURED (NOT degraded).
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+from ..events import Message, ToolCall, ToolResult, matches_truncation, redact
+from ..verify import Config, DEFAULT_CONFIG, verify
+
+# Claude Code's real inline truncation marker: "... [N lines truncated] ...".
+_CC_TRUNC_MARKER = re.compile(r"\[\d+\s+lines truncated\]")
+_DEFAULT_TRUNC_MARKERS: Tuple[Any, ...] = (_CC_TRUNC_MARKER,)
+
+
+def _text_from_content(content: Any) -> str:
+    """Flatten polymorphic tool_result / message content to text."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for b in content:
+            if isinstance(b, dict):
+                if b.get("type") == "text":
+                    parts.append(b.get("text") or "")
+                elif "text" in b:
+                    parts.append(b.get("text") or "")
+            elif isinstance(b, str):
+                parts.append(b)
+        return "\n".join(p for p in parts if p)
+    if content is None:
+        return ""
+    return str(content)
+
+
+def _message(entry: Dict[str, Any]) -> Dict[str, Any]:
+    m = entry.get("message")
+    return m if isinstance(m, dict) else {}
+
+
+def from_transcript(entries: List[Dict[str, Any]], *,
+                    config: Config = DEFAULT_CONFIG
+                    ) -> Tuple[List[Any], str, str]:
+    """Claude Code transcript entries -> (trajectory, final_claim, task).
+
+    final_claim = the LAST assistant text block(s). task = the FIRST human user
+    text (best-effort; the detector does not consume task).
+    """
+    markers = _DEFAULT_TRUNC_MARKERS + tuple(config.extra_truncation_markers)
+    task = ""
+    traj: List[Any] = []
+    last_assistant_text = ""
+    # collect truncatedByTokenCap tool_use_ids from file-read attachments
+    structured_trunc_ids: set = set()
+
+    # first pass: structured truncation flags on attachments
+    for e in entries or []:
+        if not isinstance(e, dict) or e.get("type") != "attachment":
+            continue
+        att = e.get("attachment") or {}
+        if att.get("truncatedByTokenCap"):
+            tid = att.get("toolUseID") or att.get("tool_use_id")
+            if tid:
+                structured_trunc_ids.add(tid)
+
+    for e in entries or []:
+        if not isinstance(e, dict) or "_meta" in e:
+            continue
+        etype = e.get("type")
+        if etype == "attachment":
+            continue  # side channel; hook-block errors are NOT tool failures (ruling)
+
+        msg = _message(e)
+        role = msg.get("role")
+        content = msg.get("content")
+
+        if etype == "user":
+            # a user entry is either the human task (string) or tool_result blocks
+            if isinstance(content, str):
+                if not task and content.strip():
+                    task = content
+                continue
+            if isinstance(content, list):
+                for b in content:
+                    if isinstance(b, dict) and b.get("type") == "tool_result":
+                        cid = b.get("tool_use_id") or ""
+                        body = _text_from_content(b.get("content"))
+                        is_error = bool(b.get("is_error"))  # None/absent -> False
+                        # truncation: structured flag OR inline marker (inferred)
+                        inferred = matches_truncation(body, markers)
+                        structured = cid in structured_trunc_ids
+                        truncated = inferred or structured
+                        if config.redact_paths:
+                            body = redact(body)
+                        traj.append(ToolResult(
+                            cid, content=body, is_error=is_error,
+                            truncated=truncated,
+                            error_sniffed=False,               # structured bit
+                            truncation_inferred=(inferred and not structured)))
+
+        elif etype == "assistant":
+            texts = []
+            if isinstance(content, list):
+                for b in content:
+                    if not isinstance(b, dict):
+                        continue
+                    bt = b.get("type")
+                    if bt == "text":
+                        texts.append(b.get("text") or "")
+                    elif bt == "tool_use":
+                        traj.append(ToolCall(
+                            b.get("id") or "", name=b.get("name") or "?",
+                            arguments=b.get("input", "")))
+                    # 'thinking' blocks ignored
+            elif isinstance(content, str):
+                texts.append(content)
+            joined = "\n".join(t for t in texts if t)
+            if joined.strip():
+                # emit as a mid-trajectory message AND track as running final claim
+                traj.append(Message(redact(joined) if config.redact_paths else joined))
+                last_assistant_text = joined
+
+    final_claim = redact(last_assistant_text) if config.redact_paths else last_assistant_text
+    # the final assistant text is the claim, not a mid-trajectory message: drop
+    # the trailing duplicate Message so the closing isn't double-counted.
+    if traj and isinstance(traj[-1], Message) and traj[-1].text == final_claim:
+        traj.pop()
+    return traj, final_claim, task
+
+
+# ---------------------------------------------------------------------------
+# stop-hook surface (block allowed)
+# ---------------------------------------------------------------------------
+def stop_hook(entries: List[Dict[str, Any]], *,
+              mode: str = "audit",
+              config: Config = DEFAULT_CONFIG) -> Dict[str, Any]:
+    """Run the polygraph check as a Claude Code Stop hook.
+
+    Returns a hook-decision dict. ``mode="block"`` emits ``{"decision":"block",
+    "reason":...}`` on a lie (Claude Code halts / feeds the reason back);
+    ``mode="audit"`` never blocks. ``verdict`` rides along for logging.
+    """
+    if mode not in ("audit", "block"):
+        raise ValueError(f"mode must be 'audit' or 'block', got {mode!r}")
+    traj, claim, task = from_transcript(entries, config=config)
+    v = verify(traj, claim, task)
+    out: Dict[str, Any] = {"decision": None, "verdict": v}
+    if mode == "block" and v.is_lie:
+        reason = "; ".join(f.detail for f in v.evidence) or "honesty gate: lie detected"
+        out["decision"] = "block"
+        out["reason"] = reason
+    return out

agent_polygraph/adapters/litellm.py

@@ -0,0 +1,162 @@
+# -*- coding: utf-8 -*-
+"""
+Adapter 4 -- LiteLLM post-call guardrail (AUDIT-ONLY per ruling).
+
+Reconstructs the trajectory from a single late call's ``data["messages"]`` (the
+"last-call-has-everything" trick: full-history-resend frameworks put the whole
+conversation -- assistant tool-call turns and ``role:"tool"`` results -- on every
+request). Pairs it with the final response as the claim. By ruling this is
+audit-only; ``mode="block"`` raises loud.
+
+Real-emission deltas honoured (CAPTURE-NOTES + ps-litellm-depth):
+
+  * The FINAL call's ``messages`` = the full trajectory (system, user,
+    assistant(tool_calls), tool, ...). Feed the LAST call.
+  * Tool calls are OpenAI-standard ``assistant.tool_calls[].function.{name,
+    arguments}`` + ``role:"tool"`` messages with ``tool_call_id``/``name``/
+    ``content``.
+  * OPAQUE tool errors: there is NO structured error field anywhere. A tool
+    failure is visible ONLY as text the agent wrote into the ``role:"tool"``
+    content (e.g. ``"ERROR: ..."``). Recovery is payload-sniff ONLY -> every
+    recovered error is DEGRADED (0.7). A silently-failing tool is invisible.
+  * ``assistant.tool_calls[].function`` may arrive as a proper dict OR (capture
+    artifact / some SDK reprs) a ``Function(arguments='...', name='...')`` repr
+    string -- both are parsed defensively.
+  * No truncation flag anywhere; only caller extras / bench seam, always INFERRED.
+  * A ``tool_call`` with no matching ``role:"tool"`` message is a dangling call
+    -- preserved, never fabricated.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Tuple
+
+from ..events import (Message, ToolCall, ToolResult, looks_like_error,
+                      matches_truncation, redact)
+from ..verify import Config, DEFAULT_CONFIG, Verdict, verify
+
+# LiteLLM proxy has NO truncation signal (CAPTURE-NOTES). No default marker;
+# supply one via Config.extra_truncation_markers. Any such mark is INFERRED.
+_DEFAULT_TRUNC_MARKERS: Tuple[Any, ...] = ()
+_FUNC_REPR = re.compile(r"name=(['\"])(?P<name>.*?)\1")
+_FUNC_ARGS = re.compile(r"arguments=(['\"])(?P<args>.*?)\1")
+
+
+def _parse_function(fn: Any) -> Tuple[str, Any]:
+    """(name, arguments) from a tool_call.function that may be a dict or a
+    ``Function(arguments=..., name=...)`` repr string."""
+    if isinstance(fn, dict):
+        return fn.get("name") or "?", fn.get("arguments", "")
+    if isinstance(fn, str):
+        name_m = _FUNC_REPR.search(fn)
+        args_m = _FUNC_ARGS.search(fn)
+        return (name_m.group("name") if name_m else "?",
+                args_m.group("args") if args_m else "")
+    return "?", ""
+
+
+def _final_claim(response: Any) -> str:
+    """Extract assistant text from a response / response_message object or dict."""
+    if response is None:
+        return ""
+    if isinstance(response, str):
+        return response
+    if isinstance(response, dict):
+        if "content" in response and isinstance(response["content"], str):
+            return response["content"]
+        choices = response.get("choices")
+        if isinstance(choices, list) and choices:
+            msg = choices[0].get("message") if isinstance(choices[0], dict) else None
+            if isinstance(msg, dict):
+                return msg.get("content") or ""
+    return ""
+
+
+def from_litellm(messages: List[Dict[str, Any]],
+                 response: Any = None, *,
+                 config: Config = DEFAULT_CONFIG
+                 ) -> Tuple[List[Any], str, str]:
+    """A single late call's ``messages`` array (+ its response) ->
+    (trajectory, final_claim, task)."""
+    markers = _DEFAULT_TRUNC_MARKERS + tuple(config.extra_truncation_markers)
+    task = ""
+    traj: List[Any] = []
+    seen_tool_ids: set = set()
+
+    for m in messages or []:
+        if not isinstance(m, dict):
+            continue
+        role = m.get("role")
+        content = m.get("content")
+
+        if role == "user":
+            if not task and isinstance(content, str) and content.strip():
+                task = content
+        elif role == "assistant":
+            if isinstance(content, str) and content.strip():
+                traj.append(Message(redact(content) if config.redact_paths else content))
+            for tc in m.get("tool_calls") or []:
+                if not isinstance(tc, dict):
+                    continue
+                cid = tc.get("id") or ""
+                name, args = _parse_function(tc.get("function"))
+                traj.append(ToolCall(cid, name=name, arguments=args))
+        elif role == "tool":
+            cid = m.get("tool_call_id") or ""
+            body = content if isinstance(content, str) else _stringify(content)
+            seen_tool_ids.add(cid)
+            is_error = error_sniffed = False
+            # OPAQUE errors: sniff-only recovery (always degraded)
+            if config.error_sniff and looks_like_error(body, config.error_patterns):
+                is_error = error_sniffed = True
+            truncated = matches_truncation(body, markers)
+            if config.redact_paths:
+                body = redact(body)
+            traj.append(ToolResult(cid, content=body, is_error=is_error,
+                                   truncated=truncated,
+                                   error_sniffed=error_sniffed,
+                                   truncation_inferred=truncated))
+        # 'system' ignored
+
+    final_claim = _final_claim(response)
+    if config.redact_paths:
+        final_claim = redact(final_claim)
+    return traj, final_claim, task
+
+
+def _stringify(v: Any) -> str:
+    if isinstance(v, str):
+        return v
+    if v is None:
+        return ""
+    try:
+        import json
+        return json.dumps(v, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return str(v)
+
+
+# ---------------------------------------------------------------------------
+# post-call guardrail surface (audit-only; block raises loud)
+# ---------------------------------------------------------------------------
+def post_call_guardrail(data: Dict[str, Any],
+                        response: Any = None, *,
+                        mode: str = "audit",
+                        config: Config = DEFAULT_CONFIG) -> Verdict:
+    """Audit hook shaped like ``async_post_call_success_hook``: ``data`` is the
+    request body (``data["messages"]`` = full resent history), ``response`` the
+    completion. ``mode="block"`` raises loud (ruling: post-call audit-only)."""
+    if mode == "block":
+        raise ValueError(
+            "LiteLLM adapter is audit-only (v1 ruling): tool-error status is "
+            "opaque at the proxy and blocking sits in the request critical path. "
+            "Use audit mode; escalate to a blocking surface elsewhere."
+        )
+    if mode != "audit":
+        raise ValueError(f"mode must be 'audit', got {mode!r}")
+    messages = (data or {}).get("messages") or []
+    resp = response
+    if resp is None:
+        resp = (data or {}).get("response") or (data or {}).get("response_message")
+    traj, claim, task = from_litellm(messages, resp, config=config)
+    return verify(traj, claim, task)

agent_polygraph/adapters/openai_agents.py

@@ -0,0 +1,176 @@
+# -*- coding: utf-8 -*-
+"""
+Adapter 1 -- OpenAI Agents SDK output guardrail.
+
+Consumes the span-export dicts a ``TracingProcessor`` receives (each span's
+native ``Span.export()``), maps them to an SDK trajectory, and exposes an
+``@output_guardrail``-shaped surface. Blocking IS allowed here (the SDK guardrail
+tripwire can halt a run), so ``mode="block"`` is supported.
+
+Real-emission deltas honoured (CAPTURE-NOTES, vs. the throwaway prototype which
+was WRONG about all of these):
+
+  * ``type`` is nested at ``span_data.type`` -- NOT top-level.
+  * The agent span carries NO task/output; task comes from the first
+    ``generation`` span's input (the user message), final claim from the LAST
+    ``generation`` span's non-empty assistant ``output[0].content``.
+  * A tool failure is on the span WRAPPER ``error`` (``SpanError{message,data}``),
+    NOT in ``span_data``; the function ``output`` is replaced with a generic
+    retry string, so the real error text survives only in ``error.data.error``.
+    We read the wrapper first; payload-sniff is the fallback.
+  * ``generation`` assistant tool-call turns have ``content=""`` with the call in
+    ``tool_calls`` -- those empty turns are NOT the final claim.
+  * ``function`` spans always carry an ``output`` (SDK guarantees result-or-error)
+    so a genuine dangling call is essentially non-inducible; we still preserve
+    ``output is None`` + no wrapper error as a dangling call and never fabricate.
+  * ``custom`` spans (turn/task) and the Responses-path caveat (export drops
+    content) are documented; ``custom`` spans are ignored.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+from ..events import (ToolCall, ToolResult, looks_like_error,
+                      matches_truncation, redact)
+from ..verify import Config, DEFAULT_CONFIG, Verdict, verify
+
+# Agents SDK has NO truncation signal at all (CAPTURE-NOTES). No default marker;
+# a deployment supplies one via Config.extra_truncation_markers. Any such mark is
+# INFERRED (degraded). The verdict is truncation-independent anyway (the detector
+# uses the bit only to grade confidence), so losing it never flips a verdict.
+_DEFAULT_TRUNC_MARKERS: Tuple[Any, ...] = ()
+
+
+def _span_type(sp: Dict[str, Any]) -> Optional[str]:
+    sd = sp.get("span_data")
+    if isinstance(sd, dict):
+        return sd.get("type")
+    return None
+
+
+def _generation_final_text(sp: Dict[str, Any]) -> Optional[str]:
+    """Non-empty assistant text from a generation span, or None (tool-call turn)."""
+    sd = sp.get("span_data") or {}
+    for msg in sd.get("output") or []:
+        if isinstance(msg, dict) and msg.get("role") == "assistant":
+            content = msg.get("content")
+            if isinstance(content, str) and content.strip():
+                return content
+    return None
+
+
+def _generation_user_task(sp: Dict[str, Any]) -> Optional[str]:
+    sd = sp.get("span_data") or {}
+    for msg in sd.get("input") or []:
+        if isinstance(msg, dict) and msg.get("role") == "user":
+            content = msg.get("content")
+            if isinstance(content, str) and content.strip():
+                return content
+    return None
+
+
+def from_openai_agents(trace_export: List[Dict[str, Any]], *,
+                       config: Config = DEFAULT_CONFIG
+                       ) -> Tuple[List[Any], str, str]:
+    """List of span-export dicts (a trace-processor stream, ``_meta``/``trace``
+    envelope lines tolerated) -> (trajectory, final_claim, task)."""
+    markers = _DEFAULT_TRUNC_MARKERS + tuple(config.extra_truncation_markers)
+    task, final_claim = "", ""
+    traj: List[Any] = []
+    call_n = 0
+
+    for sp in trace_export or []:
+        if not isinstance(sp, dict):
+            continue
+        # tolerate the capture envelope lines (_meta / {"object":"trace"})
+        if "_meta" in sp or sp.get("object") == "trace":
+            continue
+        k = _span_type(sp)
+        sd = sp.get("span_data") or {}
+
+        if k == "generation":
+            t = _generation_user_task(sp)
+            if t and not task:
+                task = t
+            final = _generation_final_text(sp)
+            if final is not None:
+                final_claim = final  # last non-empty assistant turn wins
+
+        elif k == "function":
+            call_n += 1
+            cid = f"fn{call_n}"
+            traj.append(ToolCall(cid, name=sd.get("name") or "?",
+                                 arguments=sd.get("input", "")))
+            out = sd.get("output")
+            wrapper_err = sp.get("error")  # SpanError{message,data} or None
+            if out is None and not wrapper_err:
+                # genuine dangling call (SDK rarely produces this) -- no result
+                continue
+            # error text: prefer wrapper error.data.error, else the (generic) output
+            is_error = False
+            error_sniffed = False
+            content = out if isinstance(out, str) else ("" if out is None else str(out))
+            if wrapper_err:
+                is_error = True
+                data = wrapper_err.get("data") if isinstance(wrapper_err, dict) else None
+                real = None
+                if isinstance(data, dict):
+                    real = data.get("error")
+                content = real or (wrapper_err.get("message") if isinstance(wrapper_err, dict) else None) or content
+            elif config.error_sniff and looks_like_error(content, config.error_patterns):
+                # no structured wrapper error -> sniff the payload (degraded)
+                is_error = True
+                error_sniffed = True
+
+            truncated = matches_truncation(content, markers)
+            if config.redact_paths:
+                content = redact(content)
+            traj.append(ToolResult(cid, content=content, is_error=is_error,
+                                   truncated=truncated,
+                                   error_sniffed=error_sniffed,
+                                   truncation_inferred=truncated))
+
+        elif k == "agent":
+            # agent span carries no task/output; a MaxTurnsExceeded / run error
+            # lands here but is not a tool-error bit -- ignored for detection.
+            continue
+        # 'custom' / 'response' / other -> ignored (documented)
+
+    return traj, final_claim, task
+
+
+# ---------------------------------------------------------------------------
+# @output_guardrail-shaped surface (tripwire; block allowed)
+# ---------------------------------------------------------------------------
+@dataclass
+class GuardrailResult:
+    """Mirrors the Agents SDK ``GuardrailFunctionOutput`` contract."""
+    tripwire_triggered: bool
+    output_info: Verdict
+
+    @property
+    def verdict(self) -> Verdict:
+        return self.output_info
+
+
+def output_guardrail(trace_export: List[Dict[str, Any]],
+                     final_claim: Optional[str] = None,
+                     task: Optional[str] = None,
+                     *,
+                     mode: str = "audit",
+                     config: Config = DEFAULT_CONFIG) -> GuardrailResult:
+    """Run the polygraph check as an Agents-SDK output guardrail.
+
+    ``mode="audit"`` (default) always returns tripwire=False (log-only).
+    ``mode="block"`` sets tripwire on a lie -> the SDK halts the run.
+    Explicit ``final_claim``/``task`` override what is parsed from the spans
+    (useful on the Responses path where export() drops the final content).
+    """
+    if mode not in ("audit", "block"):
+        raise ValueError(f"mode must be 'audit' or 'block', got {mode!r}")
+    traj, parsed_claim, parsed_task = from_openai_agents(trace_export, config=config)
+    v = verify(traj, final_claim if final_claim is not None else parsed_claim,
+               task if task is not None else parsed_task)
+    tripwire = (mode == "block" and v.is_lie)
+    return GuardrailResult(tripwire_triggered=tripwire, output_info=v)