agentgovern 2.1.0__tar.gz → 2.2.0__tar.gz

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.1.0 → agentgovern-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: agentgovern
-Version: 2.1.0
+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.1.0 → agentgovern-2.2.0}/agentgovern/hook/data/hook.py

@@ -9,6 +9,13 @@ Configuration (environment variables):
     AGENTGOVERN_ACTOR_USER_ID     Required. Clerk user ID (user_xxxxx).
     AGENTGOVERN_API_URL           Default: https://agentgovern.zirahn.com
     AGENTGOVERN_HOOK_MODE         Default: sync  (sync | async | off)
+        NAGT-137: applies to UserPromptSubmit/PostToolUse/Stop only — these
+        capture-only events default to async (no blocking) regardless of
+        this variable; set 'sync' to force a synchronous verdict on them too
+        (debugging). PreToolUse always requests sync and always enforces the
+        verdict — this variable can no longer make PreToolUse non-blocking
+        (it could prior to v2.2.0; see CHANGELOG). 'off' disables the hook
+        entirely, for all events, unchanged.
     AGENTGOVERN_HOOK_VERBOSE      Default: 0     (0 | 1)
     AGENTGOVERN_FAIL_ACTION       Default: allow (allow | deny)
     AGENTGOVERN_HOOK_TIMEOUT_MS   Default: 5000
@@ -41,7 +48,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 
 # ── Constants ──────────────────────────────────────────────────────────────────
 
@@ -148,9 +155,28 @@ def _now_iso() -> str:
     return _iso_timestamp_utc()
 
 
-def _get_evaluation_mode() -> str:
-    """Return 'sync' or 'async' based on AGENTGOVERN_HOOK_MODE."""
-    hook_mode = os.environ.get("AGENTGOVERN_HOOK_MODE", "sync").lower()
+def _get_evaluation_mode(event_name: str) -> str:
+    """Return 'sync' or 'async' for this hook event type (NAGT-137).
+
+    PreToolUse always returns 'sync' — it gates whether the tool runs, so its
+    verdict is never discarded, and AGENTGOVERN_HOOK_MODE can no longer make
+    it non-blocking (removed deliberately; see the module docstring).
+
+    The three capture-only events (UserPromptSubmit, PostToolUse, Stop)
+    discard the response body regardless of what it contains (_send_to_ingest
+    never reads it for control flow) — they default to 'async' so they never
+    pay the policy-engine round trip for a verdict nobody reads. Set
+    AGENTGOVERN_HOOK_MODE='sync' explicitly to force a synchronous verdict on
+    these three as well (debugging escape hatch, preserved from the prior
+    single-switch behavior).
+    """
+    if event_name == "PreToolUse":
+        return "sync"
+    # NAGT-137: default is 'async' for these three, the opposite of
+    # PreToolUse/the pre-NAGT-137 global default — an unset env var must NOT
+    # fall back to 'sync' here, or these events would silently keep blocking
+    # exactly as before. Only an explicit 'sync' forces the debug escape hatch.
+    hook_mode = os.environ.get("AGENTGOVERN_HOOK_MODE", "").lower()
     return "sync" if hook_mode == "sync" else "async"
 
 
@@ -224,13 +250,19 @@ def format_action_name(tool_name: str, tool_input: dict[str, Any]) -> str:
 def build_payload(
     hook_event: dict[str, Any],
     actor_user_id: str,
-    hook_mode: str,
+    evaluation_mode: str,
 ) -> dict[str, Any]:
     """Build the interactiveSchema-compliant PreToolUse payload from a hook event.
 
     Preserved from v1 — produces a v1-identical payload (no context_snapshot,
     no turn_index).  Used directly by _handle_pre_tool_use in minimal mode.
     In enriched mode, _handle_pre_tool_use augments the result with context_snapshot.
+
+    evaluation_mode is the already-resolved 'sync'/'async' string (see
+    _get_evaluation_mode) — NAGT-137: this used to take the raw
+    AGENTGOVERN_HOOK_MODE value and normalize it internally; PreToolUse is
+    now the only caller and always resolves to 'sync', so the normalization
+    moved to the single call site instead of living here.
     """
     tool_name: str = hook_event.get("tool_name", "")
     tool_input: dict[str, Any] = hook_event.get("tool_input") or {}
@@ -238,7 +270,6 @@ def build_payload(
 
     tool_event_type, action_type = map_tool_to_event(tool_name)
     action_name = format_action_name(tool_name, tool_input)
-    evaluation_mode = "sync" if hook_mode == "sync" else "async"
 
     payload: dict[str, Any] = {
         "schema_version": "1",
@@ -515,9 +546,26 @@ def _windows_username_principal() -> str | None:
 
 def _harden_directory_windows(path: Path) -> None:
     """Best-effort ACL lockdown via icacls — the same tool and pattern this
-    repo's own CLAUDE.md prescribes for ~/.agentgovern/prod.env. There is no
-    dependency-free stdlib equivalent to POSIX chmod on Windows (adding
-    pywin32 as a new dependency for one directory lockdown is out of
+    repo's own CLAUDE.md prescribes for ~/.agentgovern/prod.env, including
+    that file's own explicit SYSTEM grant (CLAUDE.md's own success bar for
+    this class of file is "no Everyone/BUILTIN\\Users ACE", not "no
+    SYSTEM/Administrators" — SYSTEM can read any file on the box regardless
+    of ACLs, and a local admin can always take ownership and reset any ACL,
+    so neither principal's presence here grants anything they couldn't
+    already reach). `/inheritance:r` only strips ACEs the object *inherited*
+    from its parent — on a freshly-created folder near a user-profile root
+    (the real ~/.agentgovern/ shape, confirmed by direct testing — see
+    docs/audit-reports/nagt-095-async-prompt-drop-2026-07-20.md's
+    verification-gap note), SYSTEM and Administrators typically arrive as
+    *explicit* ACEs already, which /inheritance:r does not touch and
+    /grant:r does not remove for a principal it isn't asked about. The
+    explicit SYSTEM grant below doesn't change that end state — it makes it
+    intentional and self-documenting instead of an accident of Windows'
+    default folder-creation behavior, so the code doesn't silently rely on
+    an undocumented default that could change.
+
+    There is no dependency-free stdlib equivalent to POSIX chmod on Windows
+    (adding pywin32 as a new dependency for one directory lockdown is out of
     proportion), so this shells out rather than leaving the directory
     unhardened. If icacls is unavailable, times out, or fails for any reason
     (non-NTFS volume, restricted environment, etc.), this logs verbose and
@@ -535,7 +583,14 @@ def _harden_directory_windows(path: Path) -> None:
         return
     try:
         result = subprocess.run(
-            ["icacls", str(path), "/inheritance:r", "/grant:r", f"{principal}:(OI)(CI)F"],
+            [
+                "icacls",
+                str(path),
+                "/inheritance:r",
+                "/grant:r",
+                f"{principal}:(OI)(CI)F",
+                "NT AUTHORITY\\SYSTEM:(OI)(CI)F",
+            ],
             capture_output=True,
             text=True,
             timeout=2.0,
@@ -547,7 +602,10 @@ def _harden_directory_windows(path: Path) -> None:
                 "directory left at default (inherited) permissions."
             )
         else:
-            _vlog(f"[agentgovern] Hardened {path} to owner-only via icacls.")
+            _vlog(
+                f"[agentgovern] Restricted {path} to current user + SYSTEM + "
+                "local Administrators via icacls (excludes other local accounts)."
+            )
     except (subprocess.TimeoutExpired, FileNotFoundError, OSError, ValueError) as exc:
         _vlog(
             f"[agentgovern] icacls hardening of {path} raised {exc} — "
@@ -556,11 +614,14 @@ def _harden_directory_windows(path: Path) -> None:
 
 
 def _ensure_hardened_dir(path: Path) -> None:
-    """Create `path` if missing and harden it to owner-only, once, at
-    creation time only — every later call is a single cheap is_dir() stat,
-    never repeated chmod/icacls work, so this never adds per-invocation cost
-    to the hot path. Applies to both OUTBOX_DIR and DEAD_LETTER_DIR, since
-    both are only ever created via _write_json_atomic below."""
+    """Create `path` if missing and restrict it (current user + SYSTEM +
+    local Administrators on Windows, 0700 on POSIX — excludes other local
+    accounts; see _harden_directory_windows for why this isn't "owner-only"),
+    once, at creation time only — every later call is a single cheap
+    is_dir() stat, never repeated chmod/icacls work, so this never adds
+    per-invocation cost to the hot path. Applies to both OUTBOX_DIR and
+    DEAD_LETTER_DIR, since both are only ever created via _write_json_atomic
+    below."""
     if path.is_dir():
         return
     try:
@@ -970,6 +1031,10 @@ def _handle_pre_tool_use(
     api_url = os.environ.get("AGENTGOVERN_API_URL", _DEFAULT_API_URL).rstrip("/")
     hook_mode = os.environ.get("AGENTGOVERN_HOOK_MODE", "sync").lower()
     fail_action = os.environ.get("AGENTGOVERN_FAIL_ACTION", "allow").lower()
+    # NAGT-137: PreToolUse always requests sync, independent of hook_mode
+    # above — hook_mode is still read for the "off" kill switch and
+    # AGENTGOVERN_FAIL_ACTION handling below, just no longer for this.
+    evaluation_mode = _get_evaluation_mode("PreToolUse")
 
     try:
         timeout_seconds = (
@@ -997,7 +1062,7 @@ def _handle_pre_tool_use(
         )
         return 0
 
-    payload = build_payload(hook_event, actor_user_id, hook_mode)
+    payload = build_payload(hook_event, actor_user_id, evaluation_mode)
 
     # Enriched mode: add context_snapshot (absent in minimal mode for v1 compat).
     if capture_mode == CAPTURE_MODE_ENRICHED:
@@ -1008,7 +1073,7 @@ def _handle_pre_tool_use(
     timeout_ms_int = int(timeout_seconds * 1000)
     _vlog(
         f"[agentgovern] POST {endpoint} tool={tool_name} "
-        f"mode={hook_mode} timeout={timeout_ms_int}ms"
+        f"mode={evaluation_mode} timeout={timeout_ms_int}ms"
     )
 
     t0 = time.monotonic()
@@ -1057,10 +1122,18 @@ def _handle_pre_tool_use(
         )
         return 0
 
-    # ── Async mode ────────────────────────────────────────────────────────────
-    if hook_mode == "async":
-        _vlog("[agentgovern] Async ingest accepted.")
-        return 0
+    # NAGT-137: no async-skip branch here — PreToolUse's evaluation_mode is
+    # always 'sync' now (see above), so this payload always told the server
+    # to evaluate synchronously and this response always has a real verdict
+    # to parse. Before this change, the removed branch (`if hook_mode ==
+    # "async": return 0`) was consistent with the payload actually sent,
+    # since hook_mode drove both. Leaving it keyed on the raw
+    # AGENTGOVERN_HOOK_MODE env var after this change — rather than deleting
+    # it — would have reintroduced exactly that inconsistency in the other
+    # direction: an operator with AGENTGOVERN_HOOK_MODE=async set would still
+    # send 'sync' (per _get_evaluation_mode above) and get a real verdict
+    # back, but this branch would have discarded it unparsed, silently
+    # disabling enforcement. Deleted, not left dead.
 
     # ── Sync mode: parse verdict ──────────────────────────────────────────────
     data: dict[str, Any] = response.get("data") or {}
@@ -1131,7 +1204,7 @@ def _handle_user_prompt_submit(hook_event: dict[str, Any]) -> int:
         "client_event_id": str(uuid.uuid4()),
         "input": {"prompt": prompt_text},
         "client_timestamp": _now_iso(),
-        "evaluation_mode": _get_evaluation_mode(),
+        "evaluation_mode": _get_evaluation_mode("UserPromptSubmit"),
         "context_snapshot": _build_context_snapshot(hook_event),
     }
 
@@ -1174,7 +1247,7 @@ def _handle_post_tool_use(hook_event: dict[str, Any]) -> int:
         "client_event_id": str(uuid.uuid4()),
         "input": tool_input,
         "client_timestamp": _now_iso(),
-        "evaluation_mode": _get_evaluation_mode(),
+        "evaluation_mode": _get_evaluation_mode("PostToolUse"),
         "context_snapshot": _build_context_snapshot(hook_event),
     }
 
@@ -1277,7 +1350,7 @@ def _handle_stop(hook_event: dict[str, Any]) -> int:
         "input": {},
         "output": {"text": assistant_text_capped},
         "client_timestamp": _now_iso(),
-        "evaluation_mode": _get_evaluation_mode(),
+        "evaluation_mode": _get_evaluation_mode("Stop"),
         "context_snapshot": _build_context_snapshot(hook_event),
     }
 

{agentgovern-2.1.0 → agentgovern-2.2.0}/agentgovern/hook/installer.py

@@ -648,7 +648,7 @@ def status() -> int:
     if exit_code == 0 and drift_report.has_drift:
         exit_code = 2
 
-    # Per-event registration detail — every v2 event marked present (✓) or MISSING,
+    # Per-event registration detail — every v2 event marked present (OK) or MISSING,
     # with any matcher/timeout drift shown directly beneath its event.
     matcher_drift_by_event = {md.event_type: md for md in drift_report.matcher_drifts}
     timeout_drift_by_event = {td.event_type: td for td in drift_report.timeout_drifts}
@@ -665,7 +665,7 @@ def status() -> int:
         if entry.get("hooks"):
             cmd = entry["hooks"][0].get("command", "")
             timeout_val = entry["hooks"][0].get("timeout", "")
-        print(f"  {et:<20}  ✓  matcher={matcher_val}  cmd={cmd}  timeout={timeout_val}s")
+        print(f"  {et:<20}  OK  matcher={matcher_val}  cmd={cmd}  timeout={timeout_val}s")
 
         md = matcher_drift_by_event.get(et)
         for line in _format_matcher_drift_lines(md) if md is not None else []:
@@ -753,7 +753,9 @@ def _print_coverage_banner() -> None:
 
     status_label = _coverage_status_label(marker, registered)
 
-    marks = "  ".join(f"{et} {'✓' if et in registered else '✗'}" for et in _V2_HOOK_EVENT_TYPES)
+    marks = "  ".join(
+        f"{et} {'OK' if et in registered else 'MISSING'}" for et in _V2_HOOK_EVENT_TYPES
+    )
     print("Hook registration coverage:")
     print(f"  Registered events: {marks}")
     print(f"  Mode:   {marker if marker else 'legacy-unknown'}")
@@ -910,11 +912,11 @@ def _utc_timestamp() -> str:
 def _print_http_error_hint(status: int, code: str) -> None:
     if status == 401:
         print("\nYour AGENTGOVERN_API_KEY is invalid or revoked.")
-        print("Create a new key in the dashboard: Settings → API Keys.")
+        print("Create a new key in the dashboard: Settings -> API Keys.")
     elif status == 403 and "ACTOR_NOT_IN_TENANT" in code:
         print(
             "\nYour AGENTGOVERN_ACTOR_USER_ID is not a member of this tenant.\n"
-            "Check the user ID in the dashboard: Settings → Profile."
+            "Check the user ID in the dashboard: Settings -> Profile."
         )
     elif status == 429:
         print("\nRate limit exceeded. Try again in a few seconds.")

{agentgovern-2.1.0 → agentgovern-2.2.0}/agentgovern/hook/settings.py

@@ -84,7 +84,7 @@ def atomic_write(path: Path, content: dict[str, Any]) -> None:
         raise PermissionError(
             f"{check_target} is not writable.\n"
             "On Linux/macOS: chmod u+w " + str(check_target) + "\n"
-            "On Windows: Right-click → Properties → Security → "
+            "On Windows: Right-click -> Properties -> Security -> "
             "add write permission for your user."
         )
 

{agentgovern-2.1.0 → agentgovern-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentgovern"
-version = "2.1.0"
+version = "2.2.0"
 description = "Compliance-as-code middleware for agentic AI workflows."
 readme = "README.md"
 license = { text = "MIT" }
@@ -39,7 +39,7 @@ sdk = [
   "python-dotenv>=1.0.0",
 ]
 langchain = ["agentgovern[sdk]", "langchain-core>=0.3.0"]
-langgraph = ["agentgovern[sdk]", "langgraph>=0.2.0", "langchain-core>=0.3.0"]
+langgraph = ["agentgovern[sdk]", "langgraph>=0.2.0,<2.0.0", "langchain-core>=0.3.0"]
 crewai = ["agentgovern[sdk]", "crewai>=0.80.0"]
 openai = ["agentgovern[sdk]", "openai>=1.50.0"]
 dev = [

{agentgovern-2.1.0 → agentgovern-2.2.0}/tests/hook/test_hook_v2_outbox_queue.py

@@ -13,6 +13,9 @@ they never touch the real ~/.agentgovern/outbox(-dead)/.
 from __future__ import annotations
 
 import json
+import os
+import shutil
+import subprocess
 import time
 import uuid
 from datetime import datetime, timedelta, timezone
@@ -106,9 +109,24 @@ def test_posix_hardening_failure_does_not_raise(
     hook_mod._ensure_hardened_dir(tmp_path / "hardened-posix-fail")  # must not raise
 
 
-def test_windows_hardening_invokes_icacls_with_owner_only_grant(
+def test_windows_hardening_invokes_icacls_with_user_and_system_grant(
     hook_mod: ModuleType, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
+    """Verifies the COMMAND SHAPE only — deterministic and cross-platform,
+    since icacls itself can't run on the Linux CI runner. This is NOT a
+    claim that the resulting ACL is "owner-only": /inheritance:r strips only
+    inherited ACEs, and on the real ~/.agentgovern/ shape SYSTEM/
+    Administrators typically arrive as explicit ACEs it never touches (see
+    the module docstring on _harden_directory_windows and the "verification
+    gap" note in docs/audit-reports/nagt-095-async-prompt-drop-2026-07-20.md).
+    The explicit SYSTEM grant asserted below is intentional and matches
+    CLAUDE.md's own prod.env precedent — it does not remove Administrators
+    or change the end state, it just makes the intent visible instead of
+    relying on an undocumented Windows default. The real end-state
+    verification (no Everyone/Users/Authenticated Users ACE) is
+    test_windows_hardening_real_acl_excludes_other_local_accounts below,
+    which is Windows-only and skipped in CI.
+    """
     monkeypatch.setattr(hook_mod.os, "name", "nt")
     monkeypatch.setenv("USERDOMAIN", "MACHINE")
     monkeypatch.setenv("USERNAME", "ahmed")
@@ -134,6 +152,53 @@ def test_windows_hardening_invokes_icacls_with_owner_only_grant(
     assert str(target) in cmd
     assert "/inheritance:r" in cmd
     assert any("MACHINE\\ahmed:(OI)(CI)F" in part for part in cmd)
+    assert any("NT AUTHORITY\\SYSTEM:(OI)(CI)F" in part for part in cmd)
+    # The command itself must never add a broad grant — this is the one
+    # thing a mock CAN meaningfully assert about the real success criterion.
+    for part in cmd:
+        assert "Everyone" not in part
+        assert "BUILTIN\\Users" not in part
+        assert "Authenticated Users" not in part
+
+
+@pytest.mark.skipif(os.name != "nt", reason="icacls only exists on Windows")
+def test_windows_hardening_real_acl_excludes_other_local_accounts(
+    hook_mod: ModuleType,
+) -> None:
+    """Real (non-mocked) end-to-end check, run only on Windows.
+
+    This exists because the ORIGINAL verification for Finding 1 ran icacls
+    against a scratch directory deep under AppData/Local/Temp, where
+    SYSTEM/Administrators/owner all arrive as *inherited* ACEs — so
+    /inheritance:r stripped all three and the test (and the build-time
+    manual check) saw a misleadingly clean "owner alone" result. The real
+    ~/.agentgovern/ location is different: a freshly-created folder there
+    gets SYSTEM/Administrators as *explicit* ACEs from creation, which
+    /inheritance:r never touches. Testing against the wrong directory shape
+    is exactly how the false "owner-only" claim survived review — this test
+    therefore targets a directory created directly under
+    Path.home() / ".agentgovern", the real parent, not a generic tmp_path.
+
+    The real success criterion (matching CLAUDE.md's own prod.env bar) is
+    "no Everyone/BUILTIN\\Users/Authenticated Users ACE" — SYSTEM and
+    Administrators are expected and accepted, not a failure.
+    """
+    target = Path.home() / ".agentgovern" / f"pytest-acl-verify-{uuid.uuid4().hex}"
+    try:
+        hook_mod._ensure_hardened_dir(target)
+        assert target.is_dir()
+
+        result = subprocess.run(
+            ["icacls", str(target)], capture_output=True, text=True, timeout=5.0
+        )
+        assert result.returncode == 0, result.stderr
+
+        output = result.stdout
+        assert "Everyone" not in output, output
+        assert "BUILTIN\\Users" not in output, output
+        assert "Authenticated Users" not in output, output
+    finally:
+        shutil.rmtree(target, ignore_errors=True)
 
 
 def test_windows_hardening_failure_does_not_raise(

agentgovern-2.1.0/CHANGELOG.md

@@ -1,104 +0,0 @@
-# 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)
-
-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.1.0/agentgovern/_version.py

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