agentgovern 2.0.2__tar.gz → 2.2.0__tar.gz

{agentgovern-2.0.2 → agentgovern-2.2.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.2.0/CHANGELOG.md

@@ -0,0 +1,174 @@
+# Changelog
+
+## 2.2.0 — 2026-08-11
+
+### Fix — capture-only hook events (UserPromptSubmit/PostToolUse/Stop) no longer block on a discarded synchronous verdict; async audit-event parity (NAGT-137)
+
+`AGENTGOVERN_HOOK_MODE`'s effect is now per-event, not global:
+
+- **`UserPromptSubmit`/`PostToolUse`/`Stop`** are capture-only — the hook
+  never reads their ingest response for control flow — and now default to
+  `evaluation_mode: async` regardless of `AGENTGOVERN_HOOK_MODE`, so they no
+  longer pay the policy-engine's synchronous round trip (previously up to
+  the full `AGENTGOVERN_HOOK_TIMEOUT_MS`/shell timeout on every turn
+  boundary and every tool call). Set `AGENTGOVERN_HOOK_MODE=sync` explicitly
+  to force a synchronous verdict on these three as well (debugging).
+- **`PreToolUse` always requests `sync` now** and always enforces the
+  verdict it gets back — it is the only event that gates whether a tool
+  runs, so its verdict was never safe to discard. **Behavior change:**
+  `AGENTGOVERN_HOOK_MODE=async` can no longer make `PreToolUse`
+  non-blocking; it could in 2.1.0 and earlier. This was documented (not
+  merely latent) — `packages/claude-hook/README.md`'s env-var reference
+  table and its rate-limit troubleshooting note both described `async` as
+  applying uniformly to all events — both updated in this release to
+  reflect the new per-event behavior.
+- **Server-side (`apps/web`):** `evaluateInteractiveAsync` — already the
+  default path for all SDK-originated traffic (`evaluation_mode` defaults
+  to `async`) — previously never parsed the policy engine's top-level
+  `verdict`/`review_id` fields, so any tenant with an enforce-mode policy
+  got a generic `interactive_action.failed` audit event with no
+  `review_id` and no block-vs-escalate distinction, for every finding.
+  `evaluateInteractiveAsync` now fires the same `interactive_action.blocked`
+  /`.warned` (with `review_id`) events `evaluateInteractiveSyncAndRespond`
+  already did. **Behavior change:** `interactive_action.failed` no longer
+  fires for a verdict-bearing block outcome under async — it's retained
+  only as the fallback for a malformed/unparseable engine response.
+  Consumers filtering the audit-event stream on `.failed` specifically will
+  see fewer of them; those findings now surface as `.blocked`.
+- Hook script version (`HOOK_VERSION`) bumped 2.1.0 → 2.2.0 in lockstep.
+
+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-137-hook-sync-blocking-2026-08-03.md`.
+
+### Fix — `langgraph` extra had no upper version bound (NAGT-169)
+
+`create_react_agent` is deprecated as of LangGraph v1.0 and scheduled for
+removal in v2.0. The `langgraph` extra's dependency (`langgraph>=0.2.0`) had
+no ceiling, so a fresh `pip install agentgovern[langgraph]` after LangGraph
+2.0 ships would have pulled it unpinned — breaking this SDK's own
+`test_langgraph.py` integration tests and the `create_react_agent`-based
+onboarding sample on first run. Pinned to `langgraph>=0.2.0,<2.0.0`. The
+`langchain` extra's `langchain-core` dependency was checked and left
+unbounded — the instrumentor only uses the foundational, non-deprecated
+`BaseCallbackHandler`, and `langchain-core` has no announced 2.0.
+
+### Fix — `agentgovern hook status`/`hook test`/`hook install` crash on Windows under the default `cp1252` console codepage (NAGT-090, NAGT-169)
+
+Several CLI status/error messages wrote non-ASCII characters (`✓`, `✗`, `→`)
+that `cp1252` — the default console codepage on an unconfigured Windows
+machine — cannot encode, raising `UnicodeEncodeError` in place of the
+intended output. Replaced with ASCII equivalents (`OK`/`MISSING`, `->`) at
+all five confirmed call sites: `hook status`'s per-event detail line and
+`hook test`'s coverage banner (the two originally filed under NAGT-090),
+`hook test`'s invalid-API-key/actor-ID error hints, and the
+`Right-click -> Properties -> Security -> ...` permission-fix hint raised
+when `~/.claude/settings.json` isn't writable — found by an exhaustive
+non-cp1252-character sweep of the installer/CLI/instrumentor surface
+while fixing the two originally-filed sites, not by a new bug report.
+
+Full record: `docs/audit-reports/nagt-169-sdk-packaging-hygiene-2026-08-11.md`.
+
+## 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)
+
+Two documentation corrections so the published quickstart actually works for a
+first-time customer. No code or API change.
+
+- **Install line** now reads `pip install "agentgovern[langchain]"`. The base
+  `pip install agentgovern` installs no runtime dependencies (they moved to the
+  `[sdk]`/`[langchain]` extras in 0.2.0), so the LangChain quickstart that
+  follows it could not run as written.
+- **API-key prefix** in the Claude Code Hook env-var example corrected from
+  `as_prod_` to `ag_prod_`, matching the prefix the server actually issues and
+  validates (`ag_prod_`/`ag_stg_`/`ag_dev_`).
+
+Surfaced by the IAG-007 customer-docs Phase 1 audit (PR #237).
+
+## 2.0.1 — 2026-06-29
+
+### Fix — Gate 1 wire-shape contract
+
+`evaluate_input()` now nests `context` and `metadata` inside the `input` field of
+the request body, matching the engine's `EvaluateInputRequest` schema. Previously
+these were sent at the top level, where the engine silently dropped them — so input
+policies that depend on `context`/`metadata` were evaluated against missing data.
+The public Python signature is unchanged; only the on-the-wire serialization is
+corrected. Surfaced by the SEC-002 pre-flight contract check.
+
+## 0.2.0 — 2026-06-11
+
+### Breaking change — optional SDK dependencies
+
+`httpx`, `pydantic`, and `python-dotenv` are no longer installed by default.
+They have moved to the `[sdk]` optional extra.
+
+**Affected users:** anyone who installed `agentgovern` and used the agent SDK
+(`init()`, `track_action()`, `evaluate_input()`, framework instrumentors).
+
+**Migration:**
+
+```bash
+# Before
+pip install agentgovern
+
+# After — agent SDK usage
+pip install agentgovern[sdk]
+
+# After — LangChain (sdk is pulled in automatically)
+pip install agentgovern[langchain]
+
+# 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
+standard library and does not need httpx or pydantic. Moving these to an
+optional extra reduces the installation footprint for hook-only deployments
+from ~45 MB to ~1 MB.
+
+## 0.1.1b15 — prior
+
+Initial beta releases. See git history.

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: agentgovern
-Version: 2.0.2
+Version: 2.2.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
@@ -42,7 +42,7 @@ Requires-Dist: python-dotenv>=1.0.0; extra == 'langchain'
 Provides-Extra: langgraph
 Requires-Dist: httpx>=0.27.0; extra == 'langgraph'
 Requires-Dist: langchain-core>=0.3.0; extra == 'langgraph'
-Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
+Requires-Dist: langgraph<2.0.0,>=0.2.0; extra == 'langgraph'
 Requires-Dist: pydantic>=2.10.0; extra == 'langgraph'
 Requires-Dist: python-dotenv>=1.0.0; extra == 'langgraph'
 Provides-Extra: openai

agentgovern-2.2.0/agentgovern/_version.py

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

{agentgovern-2.0.2 → agentgovern-2.2.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})"