agentgovern 2.0.2__tar.gz → 2.1.0__tar.gz

{agentgovern-2.0.2 → agentgovern-2.1.0}/.gitignore

@@ -34,3 +34,13 @@ test-results/
 .claude/settings.local.json
 
 .vercel
+
+# Ad-hoc test fixtures with decoy/fake secret-shaped content (never real).
+decoy.env
+decoy_notebook.ipynb
+decoy_multiedit.md
+
+.env*
+
+# Demo scaffolding (fixtures, decoy secrets for demo scripts) — not product code.
+demo-fixtures/

{agentgovern-2.0.2 → agentgovern-2.1.0}/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 2.1.0 — 2026-07-20
+
+### Feature — durable local outbox retry queue for the Claude Code hook (NAGT-095)
+
+Fire-and-forget hook sends (`UserPromptSubmit`/`PostToolUse`/`Stop`) that fail
+at the network level are no longer silently lost. A failed send is now queued
+to a local durable outbox (`~/.agentgovern/outbox/`, one file per event) and
+retried opportunistically on a later hook invocation — bounded so a backlog
+can never meaningfully delay the invocation performing the retry (at most 5
+items per invocation, a 1.5s wall-clock budget, a 60s per-file cooldown).
+Permanently-abandoned events (48h TTL, or a 500-file size cap) are recorded to
+`~/.agentgovern/outbox-dead/` instead of disappearing without a trace.
+
+- **Swallowed-exception capture**: the network exception behind a failed send
+  is now captured into the queued record itself, turning the next real-world
+  occurrence into inspectable diagnostic data instead of a silent, unlogged
+  drop.
+- **`client_event_id`**: every fire-and-forget payload now carries a
+  client-generated UUID v4, captured (not yet enforced) server-side —
+  positions a future dedup fix to act retroactively on rows this release
+  ever writes. Delivery remains at-least-once, not exactly-once, until that
+  follow-on ships.
+- **Directory hardening**: `~/.agentgovern/outbox(-dead)/` are created
+  owner-only (`chmod 0700` on POSIX, an `icacls` ACL lockdown on Windows).
+- Hook script version (`HOOK_VERSION`, distinct from this package version)
+  bumped 2.0.0 → 2.1.0 in lockstep.
+
+No API or behavior change for installs that never experience a send failure.
+Requires `agentgovern hook install --force` (or a fresh install) to pick up
+the updated hook script — existing deployed hooks do not auto-update.
+
+Full design and build record: `docs/audit-reports/nagt-095-async-prompt-drop-2026-07-20.md`.
+
 ## 2.0.2 — 2026-07-02
 
 ### Fix — README quickstart correctness (NAGT-019)
@@ -50,11 +83,15 @@ pip install agentgovern[sdk]
 # After — LangChain (sdk is pulled in automatically)
 pip install agentgovern[langchain]
 
-# Hook-only users (Claude Code / Cursor governance) — no change needed
+# Hook-only users (Claude Code governance) — no change needed
 pip install agentgovern
 agentgovern hook install
 ```
 
+**Errata (2026-07-10):** this entry originally read "Claude Code / Cursor
+governance" — Cursor was never shipped as a hook target; corrected to
+Claude Code, the only host with a working client.
+
 ### Why
 
 The hook CLI (`agentgovern hook install/uninstall/status/test`) is pure Python

{agentgovern-2.0.2 → agentgovern-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentgovern
-Version: 2.0.2
+Version: 2.1.0
 Summary: Compliance-as-code middleware for agentic AI workflows.
 Project-URL: Homepage, https://agentgovern.zirahn.com
 Project-URL: Repository, https://github.com/ahmedkhan-zirahn/agentgovern

agentgovern-2.1.0/agentgovern/_version.py

@@ -0,0 +1 @@
+__version__ = "2.1.0"

{agentgovern-2.0.2 → agentgovern-2.1.0}/agentgovern/exceptions.py

@@ -1,111 +1,111 @@
-"""AgentGovern SDK exceptions."""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from agentgovern.types import InputEvaluation
-
-
-# noqa: N818 — name is part of stable SDK public API; renaming would break import contracts for existing users.
-class PolicyViolation(Exception):  # noqa: N818
-    """
-    Raised by Gate 1 when enforcement_mode=enforce and the input is blocked.
-
-    Gate 2 (async ingest) never raises — it fails silently per the fail-open guarantee.
-    """
-
-    def __init__(self, evaluation: InputEvaluation) -> None:
-        first = evaluation.violations[0] if evaluation.violations else None
-        msg = first.reason if first else "Input blocked by compliance policy."
-        super().__init__(msg)
-        self.evaluation = evaluation
-
-    @property
-    def rule_code(self) -> str | None:
-        return self.evaluation.violations[0].rule_code if self.evaluation.violations else None
-
-    @property
-    def reason(self) -> str:
-        return str(self.args[0])
-
-    @property
-    def framework_ref(self) -> str | None:
-        return self.evaluation.violations[0].framework_ref if self.evaluation.violations else None
-
-    def __repr__(self) -> str:
-        return (
-            f"PolicyViolation(rule_code={self.rule_code!r}, "
-            f"reason={self.reason!r}, "
-            f"framework_ref={self.framework_ref!r})"
-        )
-
-
-# noqa: N818 — name is part of stable SDK public API; renaming would break import contracts for existing users.
-class GateUnavailable(Exception):  # noqa: N818
-    """
-    Raised when Gate 1 is unreachable and fail_closed=True.
-
-    With the default fail_closed=False, Gate 1 errors are silently treated as
-    allowed=True so the agent continues unaffected.
-    """
-
-
-class OutputBlocked(Exception):  # noqa: N818
-    """
-    Raised by Gate 2 when the agent's output is blocked in enforce mode.
-
-    The output is never returned to the caller. Catch this to handle a blocked
-    response (e.g. show an error message, fall back to a safe default, log to
-    your own audit trail).
-    """
-
-    def __init__(self, reason: str, *, evaluation_id: str | None = None) -> None:
-        super().__init__(reason)
-        self.reason = reason
-        self.evaluation_id = evaluation_id
-
-    def __repr__(self) -> str:
-        return (
-            f"OutputBlocked(reason={self.reason!r}, "
-            f"evaluation_id={self.evaluation_id!r})"
-        )
-
-
-class OutputEscalated(Exception):  # noqa: N818
-    """
-    Raised by Gate 2 when the agent's output is escalated for human review.
-
-    A review_queue row has been created. The output is held until a human
-    approves or rejects it. Catch this to notify the caller that a review
-    is in progress and surface the review_id so they can poll for a decision.
-    """
-
-    def __init__(self, review_id: str, *, evaluation_id: str | None = None) -> None:
-        super().__init__(f"Output escalated for human review: {review_id}")
-        self.review_id = review_id
-        self.evaluation_id = evaluation_id
-
-    def __repr__(self) -> str:
-        return (
-            f"OutputEscalated(review_id={self.review_id!r}, "
-            f"evaluation_id={self.evaluation_id!r})"
-        )
-
-
-class ClientError(Exception):
-    """
-    Raised on 4xx responses from the AgentGovern API.
-
-    This always propagates regardless of fail_silently — a 4xx indicates a
-    configuration problem (wrong API key, invalid payload) that the caller
-    should fix, not a transient network issue.
-    """
-
-    def __init__(self, message: str, *, status_code: int) -> None:
-        super().__init__(message)
-        self.status_code = status_code
-
-    def __repr__(self) -> str:
-        return f"ClientError(status_code={self.status_code}, message={str(self.args[0])!r})"
+"""AgentGovern SDK exceptions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentgovern.types import InputEvaluation
+
+
+# noqa: N818 — name is part of stable SDK public API; renaming would break import contracts for existing users.
+class PolicyViolation(Exception):  # noqa: N818
+    """
+    Raised by Gate 1 when enforcement_mode=enforce and the input is blocked.
+
+    Gate 2 (async ingest) never raises — it fails silently per the fail-open guarantee.
+    """
+
+    def __init__(self, evaluation: InputEvaluation) -> None:
+        first = evaluation.violations[0] if evaluation.violations else None
+        msg = first.reason if first else "Input blocked by compliance policy."
+        super().__init__(msg)
+        self.evaluation = evaluation
+
+    @property
+    def rule_code(self) -> str | None:
+        return self.evaluation.violations[0].rule_code if self.evaluation.violations else None
+
+    @property
+    def reason(self) -> str:
+        return str(self.args[0])
+
+    @property
+    def framework_ref(self) -> str | None:
+        return self.evaluation.violations[0].framework_ref if self.evaluation.violations else None
+
+    def __repr__(self) -> str:
+        return (
+            f"PolicyViolation(rule_code={self.rule_code!r}, "
+            f"reason={self.reason!r}, "
+            f"framework_ref={self.framework_ref!r})"
+        )
+
+
+# noqa: N818 — name is part of stable SDK public API; renaming would break import contracts for existing users.
+class GateUnavailable(Exception):  # noqa: N818
+    """
+    Raised when Gate 1 is unreachable and fail_closed=True.
+
+    With the default fail_closed=False, Gate 1 errors are silently treated as
+    allowed=True so the agent continues unaffected.
+    """
+
+
+class OutputBlocked(Exception):  # noqa: N818
+    """
+    Raised by Gate 2 when the agent's output is blocked in enforce mode.
+
+    The output is never returned to the caller. Catch this to handle a blocked
+    response (e.g. show an error message, fall back to a safe default, log to
+    your own audit trail).
+    """
+
+    def __init__(self, reason: str, *, evaluation_id: str | None = None) -> None:
+        super().__init__(reason)
+        self.reason = reason
+        self.evaluation_id = evaluation_id
+
+    def __repr__(self) -> str:
+        return (
+            f"OutputBlocked(reason={self.reason!r}, "
+            f"evaluation_id={self.evaluation_id!r})"
+        )
+
+
+class OutputEscalated(Exception):  # noqa: N818
+    """
+    Raised by Gate 2 when the agent's output is escalated for human review.
+
+    A review_queue row has been created. The output is held until a human
+    approves or rejects it. Catch this to notify the caller that a review
+    is in progress and surface the review_id so they can poll for a decision.
+    """
+
+    def __init__(self, review_id: str, *, evaluation_id: str | None = None) -> None:
+        super().__init__(f"Output escalated for human review: {review_id}")
+        self.review_id = review_id
+        self.evaluation_id = evaluation_id
+
+    def __repr__(self) -> str:
+        return (
+            f"OutputEscalated(review_id={self.review_id!r}, "
+            f"evaluation_id={self.evaluation_id!r})"
+        )
+
+
+class ClientError(Exception):
+    """
+    Raised on 4xx responses from the AgentGovern API.
+
+    This always propagates regardless of fail_silently — a 4xx indicates a
+    configuration problem (wrong API key, invalid payload) that the caller
+    should fix, not a transient network issue.
+    """
+
+    def __init__(self, message: str, *, status_code: int) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+    def __repr__(self) -> str:
+        return f"ClientError(status_code={self.status_code}, message={str(self.args[0])!r})"