agentguard-hitl 0.2.0__py3-none-any.whl

agentguard/__init__.py

@@ -0,0 +1,22 @@
+"""AgentGuard — stop dangerous AI agent actions before they execute."""
+
+from .core import (
+    AgentGuard,
+    ApprovalRequest,
+    ActionDenied,
+    ResolveOutcome,
+    ApprovalStore,
+    InMemoryStore,
+    classify,
+)
+
+__all__ = [
+    "AgentGuard",
+    "ApprovalRequest",
+    "ActionDenied",
+    "ResolveOutcome",
+    "ApprovalStore",
+    "InMemoryStore",
+    "classify",
+]
+__version__ = "0.2.0"

agentguard/core.py

@@ -0,0 +1,630 @@
+"""AgentGuard v0.2 — a permission gate for AI agent tool calls.
+
+Primitives, stdlib only, works with any agent or framework:
+
+    AgentGuard().execute(name, params, executor)   gate a tool dispatcher (sync)
+    await AgentGuard().aexecute(name, params, ...)  gate a tool dispatcher (async)
+    @gate                                           gate a single function
+    guard.pending() / guard.resolve(id, ok)         request-based approval (web UI)
+    agentguard.log                                  JSONL audit of gated actions
+
+The gate is code, not a prompt. An agent cannot talk its way past it.
+Design bias: over-gating is safe, under-gating is dangerous — so detection
+errs toward asking, and every error path fails *closed* (blocks).
+
+v0.2 adds concurrent multi-agent safety: every approval is a uniquely
+identified ``ApprovalRequest`` parked in a per-request registry, so two agents
+asking at once can never be mixed up — approving one never touches the other.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import json
+import os
+import sys
+import threading
+import time
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional, Protocol, Tuple
+
+# Audit log location — override with AGENTGUARD_LOG=/path/to/file
+LOG_FILE = os.environ.get("AGENTGUARD_LOG", "agentguard.log")
+
+# Dangerous-keyword -> human risk label. Scanned most-severe first; the first
+# hit wins. Substring match on the normalized name, so `bulk_delete`,
+# `deleteUser` and `DELETE-RECORD` all trip the same rule.
+_RISK_RULES = (
+    (("delete", "drop", "wipe", "truncate", "purge", "destroy", "remove"),
+     "IRREVERSIBLE - cannot be undone"),
+    (("send", "email", "message", "notify", "publish", "post"),
+     "EXTERNAL SEND - leaves your system"),
+    (("execute", "run", "shell", "command", "exec", "eval", "spawn"),
+     "SYSTEM EXECUTION - runs arbitrary code"),
+    (("write", "overwrite", "update", "insert", "modify", "save"),
+     "DATA MUTATION - changes stored state"),
+)
+
+_LOG_LOCK = threading.Lock()
+
+
+def _normalize(name: object) -> str:
+    """Lowercase and strip every non-alphanumeric char: delete_user -> deleteuser."""
+    return "".join(ch for ch in str(name).lower() if ch.isalnum())
+
+
+def classify(name: object) -> Optional[str]:
+    """Return a risk label if the tool name looks dangerous, else None."""
+    flat = _normalize(name)
+    for keywords, label in _RISK_RULES:
+        if any(kw in flat for kw in keywords):
+            return label
+    return None
+
+
+# --- Public value objects -----------------------------------------------------
+
+@dataclass(frozen=True)
+class ApprovalRequest:
+    """An immutable description of one dangerous action awaiting a decision.
+
+    Frozen so it can be shared across threads / handed to a web layer without
+    risk of mutation. ``request_id`` is the correlation key used everywhere:
+    in the log, in :meth:`AgentGuard.pending`, and in :meth:`AgentGuard.resolve`.
+    """
+
+    request_id: str
+    tool: str
+    params: Any
+    risk: str
+    reason: Optional[str] = None
+    agent_id: Optional[str] = None
+    session_id: Optional[str] = None
+    timestamp: str = ""
+    # Read-only metadata: ISO time this request auto-fails-closed, so a UI can
+    # render a countdown. Populated only in external mode when a timeout is set;
+    # None otherwise. Does NOT drive timeout behavior — it just surfaces it.
+    deadline: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Plain dict for JSON serialization (e.g. a /pending endpoint)."""
+        return {
+            "request_id": self.request_id,
+            "tool": self.tool,
+            "params": self.params,
+            "risk": self.risk,
+            "reason": self.reason,
+            "agent_id": self.agent_id,
+            "session_id": self.session_id,
+            "timestamp": self.timestamp,
+            "deadline": self.deadline,
+        }
+
+
+@dataclass(frozen=True)
+class ActionDenied:
+    """Returned (never raised) when an action is not approved.
+
+    It is a *value*, not an exception, so agent frameworks that auto-retry on
+    raised errors will treat it as an ordinary tool result and NOT retry it
+    (Req. 7). It is falsy, so ``if guard.execute(...):`` reads naturally.
+    """
+
+    reason: str = "user_denied"
+    tool: Optional[str] = None
+    request_id: Optional[str] = None
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __str__(self) -> str:
+        return f"Blocked by AgentGuard ({self.reason})"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"denied": True, "reason": self.reason,
+                "tool": self.tool, "request_id": self.request_id}
+
+
+class ApprovalState(Enum):
+    """Lifecycle of one parked request. Internal to the store."""
+
+    PENDING = "pending"
+    APPROVED = "approved"
+    DENIED = "denied"
+    EXPIRED = "expired"
+
+
+class ResolveOutcome(Enum):
+    """What :meth:`AgentGuard.resolve` did.
+
+    Backward compatible with the old ``bool`` return: only ``RESOLVED`` is
+    truthy, so existing ``if guard.resolve(...):`` code still means
+    "I just resolved it". The others are falsy.
+    """
+
+    RESOLVED = "resolved"                  # THIS call decided it (first wins)
+    ALREADY_RESOLVED = "already_resolved"  # decided already — safe idempotent no-op
+    UNKNOWN = "unknown"                    # no such request_id
+    EXPIRED = "expired"                    # deadline passed; already failed closed
+
+    def __bool__(self) -> bool:
+        return self is ResolveOutcome.RESOLVED
+
+
+# --- Terminal rendering (degrades to ASCII on legacy code pages) --------------
+
+def _supports_unicode() -> bool:
+    enc = getattr(sys.stdout, "encoding", None) or ""
+    try:
+        "⚠━".encode(enc)
+        return True
+    except (LookupError, UnicodeEncodeError, TypeError):
+        return False
+
+
+_WARN = "⚠️  " if _supports_unicode() else "[!] "
+_BAR = ("━" * 51) if _supports_unicode() else ("=" * 51)
+
+
+def _show(params: Any) -> str:
+    try:
+        return json.dumps(params, default=str, ensure_ascii=False)
+    except Exception:
+        return repr(params)
+
+
+class _TerminalConfirm:
+    """The default approval callback: a y/n terminal prompt.
+
+    Used when ``AgentGuard()`` is built with no confirm and no mode. It is an
+    ordinary confirm callback — not a special mode or code path — so it flows
+    through the same callback branch as any other approver. It serializes its
+    own prompts (its own lock) so concurrent agents don't interleave on the
+    shared console. No stdin (e.g. a headless process) -> returns False
+    (fail closed).
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+
+    def __call__(self, request: ApprovalRequest) -> bool:
+        with self._lock:
+            lines = [
+                "", _WARN + "AGENTGUARD: Action requires approval", _BAR,
+                "Tool      : " + str(request.tool),
+                "Parameters: " + _show(request.params),
+                "Risk      : " + str(request.risk),
+            ]
+            if request.reason:
+                lines.append("Reason    : " + str(request.reason))
+            if request.agent_id:
+                lines.append("Agent     : " + str(request.agent_id))
+            if request.session_id:
+                lines.append("Session   : " + str(request.session_id))
+            lines.append("Request   : " + request.request_id)
+            lines.append(_BAR)
+            sys.stdout.write("\n".join(lines) + "\n")
+            sys.stdout.flush()
+            try:
+                return input("Allow? (y/n): ").strip().lower() in ("y", "yes")
+            except (EOFError, KeyboardInterrupt, OSError):
+                sys.stdout.write("No interactive input available -> blocked (fail-closed).\n")
+                sys.stdout.flush()
+                return False
+
+
+# The default approver used by AgentGuard() with no confirm and no mode.
+_DEFAULT_CONFIRM = _TerminalConfirm()
+
+
+def _log(tool: object, params: Any, decision: str, *,
+         reason: Optional[str] = None, agent_id: Optional[str] = None,
+         session_id: Optional[str] = None, request_id: Optional[str] = None,
+         actor: Optional[str] = None) -> None:
+    """Append one JSON line per gated action. Logging never raises."""
+    entry: Dict[str, Any] = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "tool": str(tool),
+        "params": params,
+        "decision": decision,
+    }
+    for key, value in (("reason", reason), ("agent_id", agent_id),
+                       ("session_id", session_id), ("request_id", request_id),
+                       ("actor", actor)):
+        if value is not None:
+            entry[key] = value
+    try:
+        line = json.dumps(entry, default=str, ensure_ascii=False)
+        with _LOG_LOCK, open(LOG_FILE, "a", encoding="utf-8") as fh:
+            fh.write(line + "\n")
+    except Exception:
+        pass  # an audit failure must never crash the agent
+
+
+def _confirm_is_legacy(confirm: Callable) -> bool:
+    """True if ``confirm`` is the v0.1 ``confirm(tool, params)`` two-arg form.
+
+    A single-arg callable is the v0.2 ``confirm(request)`` form. If the
+    signature can't be introspected, assume the new (single-arg) form.
+    """
+    try:
+        sig = inspect.signature(confirm)
+    except (TypeError, ValueError):
+        return False
+    positional = [
+        p for p in sig.parameters.values()
+        if p.kind in (inspect.Parameter.POSITIONAL_ONLY,
+                      inspect.Parameter.POSITIONAL_OR_KEYWORD)
+    ]
+    return len(positional) >= 2
+
+
+class _Pending:
+    """Internal record for one in-flight request: the public request, the
+    in-process waiter that unblocks execute()/aexecute(), and the mutable
+    decision state. A custom :class:`ApprovalStore` stores and returns these
+    objects as-is — note ``event`` is an in-process primitive (see the
+    cross-process caveat on :class:`ApprovalStore`)."""
+
+    __slots__ = ("request", "event", "decision", "state", "actor",
+                 "deadline_monotonic")
+
+    def __init__(self, request: ApprovalRequest,
+                 deadline_monotonic: Optional[float] = None) -> None:
+        self.request = request
+        self.event = threading.Event()        # set when a decision arrives
+        self.decision: Optional[bool] = None
+        self.state = ApprovalState.PENDING
+        self.actor: Optional[str] = None
+        self.deadline_monotonic = deadline_monotonic  # None => never auto-expires
+
+
+class ApprovalStore(Protocol):
+    """Pluggable persistence for parked approvals (Req. 5).
+
+    The default is :class:`InMemoryStore`. Implement this Protocol to back
+    approvals with your own store. ``decide`` MUST be an atomic compare-and-set
+    so two near-simultaneous resolutions of the same id can never both win.
+
+    CROSS-PROCESS CAVEAT: records carry an in-process ``threading.Event`` that
+    AgentGuard waits on. A store that spans processes must ALSO arrange to wake
+    the waiting process (polling, pub/sub, …); that wake-up is NOT provided
+    here. See the README — out of the box this works single-process only.
+    """
+
+    def put(self, record: _Pending) -> None: ...
+    def get(self, request_id: str) -> Optional[_Pending]: ...
+    def list_pending(self) -> List[ApprovalRequest]: ...
+    def decide(self, request_id: str, approved: bool,
+               actor: Optional[str]) -> ResolveOutcome: ...
+    def remove(self, request_id: str) -> None: ...
+
+
+class InMemoryStore:
+    """Default store: a dict guarded by a lock — the same mechanism v0.2 used,
+    now behind the :class:`ApprovalStore` seam. Single process only.
+
+    Resolved/expired records are retained (not evicted) so duplicate
+    resolutions stay idempotent and :meth:`decide` can report
+    ALREADY_RESOLVED / EXPIRED accurately. Volume is bounded by the number of
+    gated actions; a custom store may add eviction.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._records: Dict[str, _Pending] = {}
+
+    def put(self, record: _Pending) -> None:
+        with self._lock:
+            self._records[record.request.request_id] = record
+
+    def get(self, request_id: str) -> Optional[_Pending]:
+        with self._lock:
+            return self._records.get(request_id)
+
+    def list_pending(self) -> List[ApprovalRequest]:
+        now = time.monotonic()
+        with self._lock:
+            return [r.request for r in self._records.values()
+                    if r.state is ApprovalState.PENDING
+                    and (r.deadline_monotonic is None
+                         or now < r.deadline_monotonic)]
+
+    def decide(self, request_id: str, approved: bool,
+               actor: Optional[str]) -> ResolveOutcome:
+        """Atomic compare-and-set. First caller to find PENDING wins."""
+        with self._lock:
+            rec = self._records.get(request_id)
+            if rec is None:
+                return ResolveOutcome.UNKNOWN
+            if rec.state is not ApprovalState.PENDING:
+                return (ResolveOutcome.EXPIRED
+                        if rec.state is ApprovalState.EXPIRED
+                        else ResolveOutcome.ALREADY_RESOLVED)
+            if (rec.deadline_monotonic is not None
+                    and time.monotonic() >= rec.deadline_monotonic):
+                rec.state = ApprovalState.EXPIRED          # lazily mark; fail closed
+                return ResolveOutcome.EXPIRED
+            rec.decision = bool(approved)
+            rec.actor = actor
+            rec.state = (ApprovalState.APPROVED if approved
+                         else ApprovalState.DENIED)
+            return ResolveOutcome.RESOLVED
+
+    def remove(self, request_id: str) -> None:
+        with self._lock:
+            self._records.pop(request_id, None)
+
+
+class AgentGuard:
+    """Gate a tool dispatcher, safe under many concurrent agents.
+
+        guard = AgentGuard()                      # terminal y/n (default)
+        guard = AgentGuard(confirm=my_callback)   # sync callback (Slack/web/etc.)
+        guard = AgentGuard(mode="external")        # park requests; resolve() later
+
+    Then change one line in your loop:
+        result = guard.execute(tool_name, params, executor=run_tool,
+                               agent_id="A", session_id="run-7")
+
+    Web UI / async approval: requests created in ``mode="external"`` are visible
+    via :meth:`pending` and answered via :meth:`resolve` — from any thread, in
+    any order. Each request waits on its own event, so answering one never
+    affects another. Pass ``on_request`` to be pushed each new request the
+    instant it is parked, and ``store`` to plug in your own persistence.
+
+    NOTE: external-mode approval works only when the code calling
+    :meth:`execute` / :meth:`aexecute` and the code calling :meth:`resolve` run
+    in the SAME process. Cross-process / distributed deployments need a custom
+    :class:`ApprovalStore` with its own cross-process wake-up (not provided).
+    """
+
+    def __init__(self, confirm: Optional[Callable] = None, *,
+                 mode: Optional[str] = None,
+                 timeout: Optional[float] = None,
+                 on_request: Optional[Callable[[ApprovalRequest], Any]] = None,
+                 store: Optional[ApprovalStore] = None,
+                 dangerous_tools: Optional[List[str]] = None) -> None:
+        # Terminal approval is no longer a separate mode: with no confirm and no
+        # (or "terminal") mode, use the built-in terminal y/n confirm CALLBACK.
+        if confirm is None and mode in (None, "terminal"):
+            confirm = _DEFAULT_CONFIRM
+            mode = None
+        self._confirm = confirm
+        if confirm is not None:
+            self._mode = "callback"
+            self._confirm_legacy = _confirm_is_legacy(confirm)
+        else:
+            self._mode = mode
+            if self._mode != "external":
+                raise ValueError("mode must be 'external'")
+            self._confirm_legacy = False
+        self._timeout = timeout
+        self._on_request = on_request
+        self._store: ApprovalStore = store if store is not None else InMemoryStore()
+        # Explicit override: these tool names always gate, even if classify() says safe.
+        self._dangerous_tools = set(dangerous_tools or [])
+
+    # --- Web-UI / async-approval primitives (Req. 4 & 5) ----------------------
+
+    def pending(self) -> List[ApprovalRequest]:
+        """Snapshot of requests currently awaiting a decision.
+
+        A frontend polls this, renders the list, and calls :meth:`resolve`.
+        Returns frozen ``ApprovalRequest`` objects (safe to serialize).
+        """
+        return self._store.list_pending()
+
+    def gate(self, func: Callable) -> Callable:
+        """Decorator: force ``func`` to always require approval, through THIS
+        guard's configured mode (default-terminal / callback / external) — not
+        hardcoded terminal. Registers the function's name so it always gates,
+        then routes each call through :meth:`execute`. Returns ``ActionDenied``
+        on denial, like :meth:`execute`.
+
+            guard = AgentGuard(mode="external", on_request=push)
+            @guard.gate
+            def charge_card(amount): ...     # parks a UI approval, not a y/n prompt
+        """
+        tool = getattr(func, "__name__", "function")
+        self._dangerous_tools.add(tool)        # always gate this name
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            params = {"args": list(args), "kwargs": kwargs}
+            return self.execute(tool, params,
+                                executor=lambda _n, _p: func(*args, **kwargs))
+        return wrapper
+
+    def resolve(self, request_id: str, approved: bool, *,
+                actor: Optional[str] = None) -> ResolveOutcome:
+        """Answer one parked request by id, from ANY transport (HTTP, WS,
+        webhook). Thread-safe and idempotent: the FIRST call to a given id wins
+        and returns ``RESOLVED``; later calls return ``ALREADY_RESOLVED`` (or
+        ``EXPIRED`` / ``UNKNOWN``). A double-clicked button or a retried webhook
+        is therefore a safe no-op, never a double-execution.
+
+        Backward compatible — only ``RESOLVED`` is truthy, so existing
+        ``if guard.resolve(...):`` checks still work.
+
+        ``actor`` (optional) is recorded in the audit log for this decision.
+        """
+        outcome = self._store.decide(request_id, bool(approved), actor)
+        if outcome is ResolveOutcome.RESOLVED:
+            record = self._store.get(request_id)
+            if record is not None:
+                record.event.set()        # wake the one parked execute()/aexecute()
+        return outcome
+
+    # --- Registry internals ---------------------------------------------------
+
+    def _fire_on_request(self, request: ApprovalRequest) -> None:
+        """Push a freshly-parked request to an external system. Best-effort:
+        any failure is logged and swallowed so a broken/​slow notifier can NEVER
+        wedge the gate — the request still sits in :meth:`pending` and still
+        fails closed on timeout exactly as without a notifier (Req. 2)."""
+        if self._on_request is None:
+            return
+        try:
+            self._on_request(request)
+        except Exception as exc:
+            _log(request.tool, request.params, "ON_REQUEST_ERROR",
+                 agent_id=request.agent_id, session_id=request.session_id,
+                 request_id=request.request_id, reason=repr(exc))
+
+    def _new_record(self, request: ApprovalRequest) -> _Pending:
+        """Create the in-flight record and park it in the store. The expiry
+        deadline is set only in external mode (terminal/callback resolve inline
+        and are unaffected, preserving their exact existing behavior)."""
+        deadline_monotonic = None
+        if self._mode == "external" and self._timeout is not None:
+            deadline_monotonic = time.monotonic() + self._timeout
+        record = _Pending(request, deadline_monotonic)
+        self._store.put(record)
+        return record
+
+    def _build_request(self, tool: str, params: Any, risk: str,
+                       reason: Optional[str], agent_id: Optional[str],
+                       session_id: Optional[str]) -> ApprovalRequest:
+        deadline = None
+        if self._mode == "external" and self._timeout is not None:
+            deadline = (datetime.now(timezone.utc)
+                        + timedelta(seconds=self._timeout)).isoformat()
+        return ApprovalRequest(
+            request_id=str(uuid.uuid4()),
+            tool=str(tool),
+            params=params,
+            risk=risk,
+            reason=reason,
+            agent_id=agent_id,
+            session_id=session_id,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            deadline=deadline,
+        )
+
+    def _invoke_confirm(self, request: ApprovalRequest) -> Any:
+        if self._confirm_legacy:
+            return self._confirm(request.tool, request.params)
+        return self._confirm(request)
+
+    # --- Decision flow --------------------------------------------------------
+    # Every mode funnels into one model: park the request in the store, let a
+    # decision arrive via resolve(), wait on this request's own event, read its
+    # slot. Only the external branch changed for this release — terminal and
+    # callback still resolve inline exactly as before.
+
+    def _decide_sync(self, request: ApprovalRequest) -> Tuple[bool, str, Optional[str]]:
+        record = self._new_record(request)
+        try:
+            if self._confirm is not None:                  # callback (incl. default terminal confirm)
+                answer = False
+                try:
+                    result = self._invoke_confirm(request)
+                    if inspect.iscoroutine(result):
+                        result.close()      # async confirm needs aexecute()
+                    else:
+                        answer = bool(result)
+                except Exception:
+                    answer = False           # broken approver -> fail closed
+                self.resolve(request.request_id, answer)
+            else:                                          # external mode
+                self._fire_on_request(request)             # push; never blocks the gate
+
+            got = record.event.wait(self._timeout)
+            if not got:
+                return False, "approval_timeout", None
+            approved = record.decision is True
+            return approved, ("approved" if approved else "user_denied"), record.actor
+        finally:
+            # Terminal/callback resolve inline and need no late idempotent
+            # resolve(); external retains its record so resolve() stays
+            # idempotent and can report ALREADY_RESOLVED / EXPIRED.
+            if self._mode != "external":
+                self._store.remove(request.request_id)
+
+    async def _decide_async(self, request: ApprovalRequest) -> Tuple[bool, str, Optional[str]]:
+        record = self._new_record(request)
+        loop = asyncio.get_running_loop()
+        try:
+            if self._confirm is not None:                  # callback (incl. default terminal confirm)
+                answer = False
+                try:
+                    result = self._invoke_confirm(request)
+                    if inspect.iscoroutine(result):
+                        result = await result
+                    answer = bool(result)
+                except Exception:
+                    answer = False
+                self.resolve(request.request_id, answer)
+            else:                                          # external mode
+                self._fire_on_request(request)
+
+            # Wait without blocking the loop: park the threading.Event in the
+            # default executor. resolve() (called from anywhere) wakes it.
+            got = await loop.run_in_executor(
+                None, record.event.wait, self._timeout)
+            if not got:
+                return False, "approval_timeout", None
+            approved = record.decision is True
+            return approved, ("approved" if approved else "user_denied"), record.actor
+        finally:
+            if self._mode != "external":
+                self._store.remove(request.request_id)
+
+    # --- Public entry points --------------------------------------------------
+
+    def execute(self, tool_name: str, params: Any = None, executor: Callable = None,
+                *, reason: Optional[str] = None, agent_id: Optional[str] = None,
+                session_id: Optional[str] = None) -> Any:
+        if not callable(executor):
+            raise ValueError("guard.execute requires executor=<callable>")
+        risk = classify(tool_name)
+        if risk is None and tool_name in self._dangerous_tools:
+            risk = "MANUALLY FLAGGED - always requires approval"
+        if risk is None:                       # safe tool: silent, zero friction
+            return executor(tool_name, params)
+        request = self._build_request(
+            tool_name, params, risk, reason, agent_id, session_id)
+        approved, why, actor = self._decide_sync(request)
+        if approved:
+            _log(tool_name, params, "APPROVED", reason=reason, agent_id=agent_id,
+                 session_id=session_id, request_id=request.request_id, actor=actor)
+            return executor(tool_name, params)
+        _log(tool_name, params, "BLOCKED", reason=why, agent_id=agent_id,
+             session_id=session_id, request_id=request.request_id, actor=actor)
+        return ActionDenied(reason=why, tool=str(tool_name),
+                            request_id=request.request_id)
+
+    async def aexecute(self, tool_name: str, params: Any = None,
+                       executor: Callable = None, *, reason: Optional[str] = None,
+                       agent_id: Optional[str] = None,
+                       session_id: Optional[str] = None) -> Any:
+        if not callable(executor):
+            raise ValueError("guard.aexecute requires executor=<callable>")
+        risk = classify(tool_name)
+        if risk is None and tool_name in self._dangerous_tools:
+            risk = "MANUALLY FLAGGED - always requires approval"
+        if risk is None:
+            return await _maybe_await(executor(tool_name, params))
+        request = self._build_request(
+            tool_name, params, risk, reason, agent_id, session_id)
+        approved, why, actor = await self._decide_async(request)
+        if approved:
+            _log(tool_name, params, "APPROVED", reason=reason, agent_id=agent_id,
+                 session_id=session_id, request_id=request.request_id, actor=actor)
+            return await _maybe_await(executor(tool_name, params))
+        _log(tool_name, params, "BLOCKED", reason=why, agent_id=agent_id,
+             session_id=session_id, request_id=request.request_id, actor=actor)
+        return ActionDenied(reason=why, tool=str(tool_name),
+                            request_id=request.request_id)
+
+
+async def _maybe_await(value: Any) -> Any:
+    """Await ``value`` if it is a coroutine, else return it as-is."""
+    if inspect.iscoroutine(value):
+        return await value
+    return value

agentguard_hitl-0.2.0.dist-info/METADATA

@@ -0,0 +1,364 @@
+Metadata-Version: 2.4
+Name: agentguard-hitl
+Version: 0.2.0
+Summary: A permission gate for AI agent tool calls. Stops dangerous actions before they execute. Safe under many concurrent agents.
+Project-URL: Homepage, https://github.com/agentguard/agentguard
+License-Expression: MIT
+Keywords: agents,ai,guardrails,llm,safety,tool-use
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# AgentGuard
+
+AgentGuard is a stop-and-ask checkpoint for software that can take actions on its own. Some programs don't just return text — they can run real operations like deleting a file, sending an email, or charging a card by calling functions in your code. AgentGuard sits in front of those function calls: when a call looks dangerous, it pauses the program and asks a person to approve or deny it before anything runs. If nobody answers in time, the action is blocked. The check is plain code, so the program cannot skip it by "deciding" to.
+
+No dependencies — pure Python standard library.
+
+## Install
+
+```bash
+pip install agentguard-hitl
+# or, from a clone of this repo:
+pip install -e .
+```
+
+## Smallest working example
+
+The main way to use AgentGuard is to wrap your tool calls in `guard.execute()`. It looks at the tool's name and, if the name looks dangerous, asks for approval before running the call.
+
+```python
+from agentguard import AgentGuard
+
+guard = AgentGuard()  # approval happens in the terminal
+
+def run_tool(name, params):
+    return f"ran {name} with {params}"
+
+# "delete_file" contains "delete", so this asks before running:
+result = guard.execute("delete_file", {"path": "notes.txt"}, executor=run_tool)
+print(result)
+```
+
+Run it and you get a prompt in your terminal:
+
+```
+[!] AGENTGUARD: Action requires approval
+===================================================
+Tool      : delete_file
+Parameters: {"path": "notes.txt"}
+Risk      : IRREVERSIBLE - cannot be undone
+Request   : 3f9c...
+===================================================
+Allow? (y/n):
+```
+
+Type `y` and `run_tool` runs. Type `n` — or run it where there's no keyboard — and the call is blocked and `result` is an `ActionDenied` value instead.
+
+## How it works
+
+**What gets gated.** When you call `guard.execute(name, params, executor=run_tool)`, AgentGuard looks at the tool's *name*. If the name contains a word like `delete`, `wipe`, `drop`, `send`, `run`, or `write`, it asks for approval first. If the name looks safe, the call runs right away with no prompt. The check reads only the name — not what the function does or what arguments it gets.
+
+**The two ways to gate, side by side.** `guard.execute()` is the main path: it runs the automatic name check. `guard.gate` is a manual override — a decorator bound to a guard that makes a function *always* require approval, regardless of its name. Both go through whichever approval mode the guard is configured with (terminal / callback / external). Use `execute()` for normal integration; use `guard.gate` to force approval on one specific function you already know is dangerous.
+
+**Where the human is asked.** You pick one when you create the guard:
+
+- **Terminal** (default): a `y/n` question in the console.
+- **Callback**: you give a function that returns `True` or `False` (for example, it posts to Slack and waits for a click).
+- **External**: the request is parked with an ID, and your own app approves it later by calling `resolve()`; `pending()` lists everything waiting. This is how you connect approvals to a web page or dashboard.
+
+**The result.** If the call is approved, it runs and you get its normal return value. If it is denied — or if no one answers before the optional timeout — it does not run, and you get an `ActionDenied` value back (a value, not an error you have to catch).
+
+## The `guard.gate` decorator
+
+Use `guard.gate` when you know a specific function is always dangerous regardless of its name. It is a decorator **bound to a guard**, so it forces approval through that guard's configured mode — terminal, callback, or external/UI.
+
+```python
+guard = AgentGuard()                       # or mode="external", confirm=..., etc.
+
+@guard.gate
+def delete_file(path):
+    print(f"deleting {path}")
+
+delete_file("notes.txt")   # always asks for approval, through the guard's mode
+```
+
+`guard.gate` registers the function's name so it always gates, then routes each call through `guard.execute()`. It gates every call regardless of the name and returns an `ActionDenied` value on denial (the same as `execute()`). Because it uses the guard's mode, on a `mode="external"` guard it shows up as a UI approval card, not a terminal prompt.
+
+## Function reference
+
+Everything exported from the top-level `agentguard` package:
+
+| Name | What it does | Returns |
+|---|---|---|
+| `AgentGuard` | The checkpoint object you put in front of tool calls. The main entry point. Its constructor takes `dangerous_tools=[...]` — a list of tool names that always require approval regardless of their name, through whichever mode you configured. | an `AgentGuard` instance |
+| `classify` | Checks whether a tool name looks dangerous. | a risk-label string, or `None` if safe |
+| `ApprovalRequest` | The details of one pending approval (tool, params, risk, ids, timestamp, deadline). Read-only. | an object; `.to_dict()` gives a plain dict |
+| `ActionDenied` | The value returned when an action is blocked. It is "falsy" and is a value, not an exception. | an object; `.reason`, `.tool`, `.request_id` |
+| `ResolveOutcome` | The result of answering a parked request: `RESOLVED`, `ALREADY_RESOLVED`, `UNKNOWN`, or `EXPIRED`. | an enum member |
+| `ApprovalStore` | The interface for plugging in your own storage for pending approvals. | (a type to implement) |
+| `InMemoryStore` | The default storage for pending approvals (kept in memory). | an `InMemoryStore` instance |
+
+Methods on an `AgentGuard` instance:
+
+| Method | What it does | Returns |
+|---|---|---|
+| `execute(tool_name, params, executor, *, reason=None, agent_id=None, session_id=None)` | Gates one tool call. Runs `executor(tool_name, params)` only if allowed. The main integration point. | the executor's result, or `ActionDenied` |
+| `aexecute(...)` | Same as `execute`, for `async`/`await` code. | the executor's result, or `ActionDenied` |
+| `resolve(request_id, approved, *, actor=None)` | Approves or denies a parked request (external mode). First answer wins. | a `ResolveOutcome` |
+| `pending()` | Lists the approval requests currently waiting. | a list of `ApprovalRequest` |
+| `gate(func)` | Decorator bound to this guard: forces `func` to always require approval, through this guard's mode. | the wrapped function |
+
+## Full integration example
+
+This is a complete, runnable program. It shows the recommended pattern: keep your real tools as normal functions, put them behind one dispatcher, and route that dispatcher through `guard.execute()`.
+
+```python
+from agentguard import AgentGuard, ActionDenied
+
+# 1. Your real tool implementations. Each takes a params dict and does its work.
+def read_customer(params):
+    return {"id": params["id"], "name": "Jane Doe", "plan": "pro"}
+
+def update_email(params):
+    # pretend this writes to a database
+    return f"Email for #{params['id']} set to {params['email']}"
+
+def delete_customer(params):
+    # pretend this deletes a row
+    return f"Customer #{params['id']} deleted"
+
+# 2. One dispatcher mapping a tool name to its implementation.
+TOOLS = {
+    "read_customer":   read_customer,
+    "update_email":    update_email,
+    "delete_customer": delete_customer,
+}
+
+def run_tool(name, params):
+    return TOOLS[name](params)
+
+# 3. Create the guard. Default asks in the terminal.
+guard = AgentGuard()
+# Other options (pick ONE when you create the guard):
+#   guard = AgentGuard(confirm=lambda req: ask_slack_and_wait(req))          # returns True/False
+#   guard = AgentGuard(mode="external", on_request=push_to_ui, timeout=120)  # web UI
+
+# 4. Anywhere your code currently runs a tool, route it through the guard instead.
+def handle_tool_call(name, params):
+    result = guard.execute(
+        name, params,
+        executor=run_tool,         # the guard calls this only after approval
+        agent_id="support-bot",    # optional: who is acting
+        session_id="ticket-4821",  # optional: which run this belongs to
+    )
+    if isinstance(result, ActionDenied):
+        # Blocked. Return a plain message; do NOT automatically retry.
+        return f"Action blocked: {result.reason}"
+    return result
+
+# 5. Use it.
+print(handle_tool_call("read_customer", {"id": 7}))                      # safe name -> runs, no prompt
+print(handle_tool_call("update_email", {"id": 7, "email": "a@b.com"}))   # "email"/"update" -> asks first
+print(handle_tool_call("delete_customer", {"id": 7}))                    # "delete" -> asks first
+```
+
+Notes for adapting this:
+- `executor` must be a function with the signature `executor(tool_name, params)`.
+- A safe-named tool (`read_customer`) runs with no prompt. A dangerous-named one (`update_email`, `delete_customer`) asks first.
+- To approve through a web UI instead of the terminal, create the guard with `mode="external"`, push each request to your UI from `on_request`, and call `guard.resolve(request_id, approved, actor=...)` from your Approve/Deny buttons. Always pass a finite `timeout`.
+- `guard.gate` is not used here on purpose: `execute()` is the direct path. Reach for `@guard.gate` only to force approval on one specific function — it routes through this same guard, so it uses the same approval mode.
+
+## Use with Cursor, Claude Code, or any AI coding agent
+
+Copy the block below and paste it into your own coding agent. It is a prompt to hand to a tool — not code to run directly.
+I want to integrate AgentGuard into this project. AgentGuard is a library 
+that pauses an AI agent before it runs a dangerous or irreversible tool call 
+and asks a human to approve or deny it first. Install it with:
+pip install agentguard-hitl
+
+Before writing a single line of code, do the following discovery steps and 
+tell me what you find:
+
+DISCOVERY (do this first, do not skip):
+1. Find every place in this codebase where an AI agent executes a tool or 
+   function call — the dispatcher, the tool runner, wherever "the agent 
+   picked a tool and now it runs." List every file and line.
+2. List every tool/function the agent can call. For each one, tell me: 
+   does its name sound dangerous (delete, send, wipe, drop, write, run, 
+   exec, update) or does it sound innocent but could be dangerous in 
+   practice (charge_card, grant_admin, transfer_funds, deploy, 
+   read_secrets, export, disable, reset, create_api_key, revoke)?
+3. Find where the existing UI is built — what framework (React, Vue, plain 
+   HTML, Jinja, etc.), what components already exist for modals, cards, 
+   dialogs, notifications, or alerts, and what the existing color scheme, 
+   font, spacing, and button styles look like. I want the approval card to 
+   look like it belongs in this UI, not like it was dropped in from outside.
+4. Find the web framework being used (Flask, FastAPI, Django, Express, etc.) 
+   and where routes/endpoints are defined.
+5. Find how real-time or live updates currently work in this project — 
+   WebSockets, Server-Sent Events, polling, a message queue, or nothing yet. 
+   If nothing exists, identify the simplest option that fits this stack.
+6. Find if there is an existing authenticated user session — how is the 
+   current user identified (user.id, session["user"], request.user, JWT, 
+   etc.)? I need this for the approver identity record.
+
+Do not proceed until you have listed findings for all six points above and 
+I have confirmed them.
+
+IMPLEMENTATION (after discovery is confirmed):
+
+Follow these exact steps in this exact order. Show me the diff for each 
+step before moving to the next. Do not batch them.
+
+STEP 1 — Create the guard (one place, app startup):
+- Import AgentGuard and ActionDenied at the top of the appropriate file 
+  (wherever app-level objects like db connections or config are initialized).
+- Define a push_to_ui(request) function that sends the approval request to 
+  the frontend using whatever real-time mechanism exists (or the simplest 
+  one you identified). It receives an ApprovalRequest object with these 
+  fields: request_id, tool, params, risk, agent_id, session_id, reason, 
+  timestamp, deadline. Send all of them — don't drop any.
+- Create exactly one guard instance:
+  guard = AgentGuard(
+      mode="external",
+      on_request=push_to_ui,
+      timeout=120,
+      dangerous_tools=[LIST EVERY INNOCENTLY-NAMED DANGEROUS TOOL YOU FOUND]
+  )
+- This instance must be importable by both the agent code and the route 
+  handlers. Put it somewhere both can reach — a shared module, app state, 
+  or dependency injection, whatever fits this project's existing pattern.
+
+STEP 2 — Wrap the tool dispatcher (one line changed):
+- Find the exact line(s) from discovery step 1 where tools execute.
+- Change each one from:
+    result = run_tool(name, params)
+  to:
+    result = guard.execute(
+        name, params,
+        executor=run_tool,
+        agent_id=<how this agent is identified in this codebase>,
+        session_id=<current session or run id if one exists>
+    )
+- Immediately after, handle denial:
+    if isinstance(result, ActionDenied):
+        <return or yield the denial message back to the agent in whatever 
+        format this project uses for tool results — string, dict, JSON, 
+        tool_result block, etc.>
+        <do NOT raise an exception, do NOT retry the call>
+- If multiple agents share one dispatcher, this one change guards all of 
+  them. If each agent has its own, make this change in each one.
+
+STEP 3 — Add two backend routes:
+Add these two endpoints using whatever routing pattern this project already 
+uses. Match the existing route style exactly (decorators, blueprints, 
+routers, controllers — whatever is already here):
+
+Route 1 — list pending approvals (used by the UI to render the queue):
+  GET /agentguard/pending
+  Returns: guard.pending() serialized as JSON (each ApprovalRequest has 
+  a .to_dict() method). Protect this route with whatever authentication 
+  middleware already exists on sensitive routes in this project.
+
+Route 2 — resolve an approval (called by Approve/Deny buttons):
+  POST /agentguard/resolve
+  Body: { request_id: string, approved: boolean }
+  Action: guard.resolve(request_id, approved, actor=<current user identity>)
+  Returns: { outcome: <ResolveOutcome value> }
+  On UNKNOWN or EXPIRED outcome, return an appropriate error response.
+  Protect this route identically to Route 1.
+
+STEP 4 — Build the approval UI component:
+- Build a single approval card component that matches the existing UI 
+  exactly — same framework, same design system, same component library if 
+  one exists. Do not introduce a new UI framework or new CSS library.
+- The card must show ALL of these fields, labeled clearly:
+    Tool name (what the agent wants to run)
+    Parameters (what it's passing — shown as a readable key/value list)
+    Risk level (the risk label from AgentGuard)
+    Agent ID (which agent is asking)
+    Session ID (which run this belongs to)
+    Reason (if provided)
+    Countdown timer to deadline (live, counts down in seconds)
+- Two buttons: Approve and Deny. On click, each calls the resolve route 
+  with the correct request_id and approved=true/false.
+- After clicking either button, disable both immediately to prevent 
+  double-submission (the library handles it safely, but the UI should 
+  reflect that the decision was made).
+- When the deadline countdown hits zero, mark the card as expired and 
+  disable both buttons.
+- Wire the card to receive new requests via the same real-time mechanism 
+  used in push_to_ui (step 1). The card should appear automatically when 
+  a new request is parked — no manual refresh.
+- Match the existing UI's: color scheme, font sizes, border radius, spacing, 
+  button styles (primary/danger), modal or panel patterns, and any existing 
+  loading/error states. If there's an existing modal or dialog component, 
+  use it as the wrapper. If there are existing button components, use them.
+
+STEP 5 — Verify end to end:
+Run through this exact sequence manually and confirm each step works:
+1. Trigger an agent action that calls a tool with a dangerous-sounding name.
+   Confirm: card appears in UI, agent is paused.
+2. Click Approve. Confirm: agent continues, tool runs, result is returned.
+3. Trigger the same action again. Click Deny. 
+   Confirm: ActionDenied is returned, agent receives the denial message, 
+   does not retry.
+4. Trigger an action that calls a tool from the dangerous_tools list 
+   (innocently named). Confirm: card appears (it was not silently allowed).
+5. Trigger an action that calls a safe tool (not dangerous-named, not in 
+   dangerous_tools list). Confirm: no card appears, tool runs immediately.
+6. Click Approve twice on the same card (simulate double-click). 
+   Confirm: second click returns ALREADY_RESOLVED, nothing bad happens.
+
+THINGS YOU MUST NOT DO:
+- Do not use @gate (the old top-level decorator — it no longer exists).
+  Use @guard.gate if you need to force-gate one specific function.
+- Do not create more than one AgentGuard instance.
+- Do not modify AgentGuard's internal code (core.py).
+- Do not auto-retry a denied action.
+- Do not set timeout=None — always use a finite number.
+- Do not run the agent process and the web server in separate processes 
+  unless you flag this to me explicitly, because cross-process approval 
+  is not supported out of the box.
+- Do not invent a new UI style — match what already exists.
+
+After all five steps are complete and verified, give me:
+1. A list of every file changed and exactly what was changed in each.
+2. A list of any tools you found that are dangerous but NOT currently 
+   covered by either the name classifier or the dangerous_tools list, 
+   so I can decide whether to add them.
+3. Any architectural concern you noticed — specifically whether the agent 
+   and web server run in the same process, and if not, what that means 
+   for this integration.
+```
+
+## Known limitations
+
+Read this before relying on AgentGuard. These are real and current.
+
+**Critical / high — do not ignore:**
+
+- **Ungated actions are also unlogged.** Only gated actions are written to the audit log. Combined with the point above, a dangerous-but-ordinarily-named action can run with no record at all.
+- **Approved parameters are not frozen.** The values shown to the approver are held by reference. If they change between approval and execution, a different action can run than the one that was approved.
+- **`confirm` plus `mode="external"` silently becomes callback mode.** If you pass both, the external/UI mode is ignored without warning. If your callback returns `True`, everything is auto-approved.
+- **`timeout` defaults to waiting forever, and a wrong type crashes.** With no `timeout`, a parked external-mode request blocks indefinitely if nobody answers. A non-numeric `timeout` raises an error on the first gated call. Always pass a finite number.
+- **Async use does not scale.** `aexecute()` parks each wait on a small shared thread pool. Many simultaneous approvals exhaust it and starve other async work, and a slow `on_request` callback blocks the event loop.
+- **One process only.** External-mode approval works only when `execute()` and `resolve()` run in the same process. If you split them across processes or containers (agent in a worker, UI in a separate web server), the agent hangs until its timeout even after a human approves. There is no built-in cross-process support.
+
+**Medium / low:**
+
+- **Memory grows over time.** In external mode, resolved requests are kept in memory and never removed; a long-running server slowly accumulates them.
+- **Parameters can leak secrets.** Tool parameters are written to the log and sent to the approval UI as-is. There is no redaction.
+- **Name matching is fuzzy.** Substring matching over-flags some safe names (for example `evaluate_model`, `prune_old`). The audit log is a single local file with no rotation and no protection against multiple processes writing it at once.
+
+**What you can honestly say it is:** a single-process, human-in-the-loop approval gate for AI tool calls, with terminal, callback, and same-process web-UI approval modes. It blocks when no one answers and when a timeout passes. Within one process, simultaneous approvals don't get mixed up and repeat approvals are safe.
+
+**What it is not (yet):** not a security or authorization system, and not proven for production. It does not work across processes or containers, does not scale for heavy async use, does not keep a complete record of all activity, and does not catch dangerous actions by what they do — only by what they are named.
+
+## License
+
+MIT.
+
+## Contributing
+
+Issues and pull requests are welcome. If you change gating behavior, include a test that covers it (`python test_agentguard.py`, `python test_multiagent.py`, `python test_external_resolve.py`).

agentguard_hitl-0.2.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+agentguard/__init__.py,sha256=5cXeysGIIMWUSKdqQX98v-3bh1d1cO1e4jMVCfT_yy4,402
+agentguard/core.py,sha256=ysSKuDvBxhwING9TLx-ireaR6nWR_CYYATm7SYRwa7k,27321
+agentguard_hitl-0.2.0.dist-info/METADATA,sha256=2hGJ9OXFCCauX0CLM7Xs9fe-1u56ayD9vnyCDBuNsxE,21126
+agentguard_hitl-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+agentguard_hitl-0.2.0.dist-info/RECORD,,

agentguard_hitl-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any