agentgovern 2.7.0__tar.gz → 2.7.3__tar.gz

{agentgovern-2.7.0 → agentgovern-2.7.3}/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 2.7.3 — release date is the `sdk-v2.7.3` tag's (prepared 2026-10-22)
+
+**This release bundles Claude Code hook 2.5.1** (it was 2.5.0), and **`agentgovern hook install` registers the Python that runs it, by absolute path, instead of a bare `python3`.** The dependencies and the Python requirement (3.10 or later; the hook itself runs on 3.9 or later) are unchanged from 2.7.2. After upgrading, run `agentgovern hook install --force`: it installs hook 2.5.1 and registers the Python by absolute path. The install snippet already passes the absolute path from 2026-10-22. The hook's behaviour changes only if you set `AGENTGOVERN_FAIL_ACTION=deny`.
+
+### Fix — `AGENTGOVERN_FAIL_ACTION=deny` blocks every tool call AgentGovern didn't check (NAGT-484)
+
+- **Before (hook 2.5.0 and earlier):** `deny` blocked a tool call only when the hook got no answer at all (its own 5-second timeout, or a network error). Two other unchecked cases still let the call run:
+  - **an error answer** from AgentGovern (any HTTP 4xx or 5xx, a 429 rate limit included);
+  - **a `timeout` verdict:** AgentGovern answered, but its policy engine could not evaluate the call. The dashboard shows these calls as "Evaluation Failed".
+- **Now:** with `deny`, the hook blocks in those two cases as well, so every call it couldn't get checked is blocked. The reason Claude Code shows is the hook's own text and, for an error, the HTTP status. Nothing from AgentGovern's response is shown.
+- **With a 429 under `deny`,** the call is blocked, and the "rate limit reached, allowed" notice from 2.5.0 is not shown, since it would no longer be true.
+- **The default (`allow`) is unchanged:** an unchecked call still runs.
+- **Not changed:** a verdict the hook doesn't recognise still lets the call run, so a newer server can't stop an older hook; prompt, tool-result and Stop events never block.
+- **Also blocked under `deny`: a tool call while `AGENTGOVERN_API_KEY` or `AGENTGOVERN_ACTOR_USER_ID` is unset or empty (NAGT-500).** Up to 2.5.0 the hook printed "… not set — governance unavailable, proceeding unaudited." and let the call run, whatever the setting. Now Claude Code shows: *"AgentGovern isn't set up in this shell: AGENTGOVERN_API_KEY is not set, so this tool call was not checked. AGENTGOVERN_FAIL_ACTION=deny: blocking it. To fix it, paste your install snippet again from Settings → Developers in the AgentGovern dashboard, or set AGENTGOVERN_API_KEY and open a new terminal."* It names only the variables that are missing, and never shows any value. Under `allow` the message and behaviour are unchanged. `AGENTGOVERN_HOOK_MODE=off` still turns the hook off.
+
+### Fix — the hook runs with the Python you installed, whatever Claude Code's PATH is (NAGT-490)
+
+- **What it did:** `hook install` wrote `"command": "python3"` (`python` on Windows) into `~/.claude/settings.json`. Claude Code looks that name up on its own PATH when it runs the hook, and that need not be your shell's: an app started from the Dock gets `/usr/bin:/bin:/usr/sbin:/sbin`.
+- **So the hook could run under a different Python from the one you installed with,** and on a Mac without the Command Line Tools, `/usr/bin/python3` is a stub that only asks you to install them. There the hook never ran, and every tool call went ahead unchecked.
+- **Now:** it writes the absolute path of the Python running `agentgovern hook install`: in a virtual environment, that environment's own `python`. It falls back to the bare name only if Python can't say where it is.
+- **`--python-command` still overrides it.**
+
+## 2.7.2 — release date is the `sdk-v2.7.2` tag's (prepared 2026-10-19)
+
+**`agentgovern hook uninstall` now leaves Claude Code's settings exactly as they were before the install.** The bundled Claude Code hook (2.5.0), the dependencies and the Python requirement (3.10 or later) are unchanged from 2.7.1. There is no need to reinstall the hook.
+
+### Fix — the uninstall leaves nothing behind in settings.json (NAGT-391 F8)
+
+- **The install-mode marker (`_agentgovern_install_mode`) is removed with the hook entries.** It was left in `~/.claude/settings.json`.
+- **The backup the uninstall writes (`settings.json.bak`) is removed once the new settings are written.** Left behind, it was a copy of the settings that still registered the hook, and restoring it would have pointed Claude Code at a hook script the uninstall steps delete. If the write fails, the backup stays.
+- Found by the install rehearsal workflow (`.github/workflows/guard-install-rehearsal.yml`), which installs and uninstalls on clean Linux, macOS and Windows runners and compares the home folder before and after.
+
+## 2.7.1 — release date is the `sdk-v2.7.1` tag's (prepared 2026-10-16)
+
+**Documentation and package metadata only. The code, its dependencies and the bundled Claude Code hook (2.5.0) are unchanged from 2.7.0.** There is no need to reinstall the hook.
+
+### Fix — the links on PyPI work (NAGT-391 F2)
+
+- **The project's Repository and Issues links pointed at a GitHub repository that is not public,** so they returned "not found" for everyone outside Zirahn. They are replaced by a **Support** link, https://zirahn.com/contact. The README's own links are corrected the same way.
+
+### Fix — the README says which Python you need (NAGT-391 F2)
+
+- **The install line now needs Python 3.10 or later and asks for `agentgovern>=2.7.0`.** On Python 3.9, such as the macOS system Python, an unpinned `pip install agentgovern` installed 2.5.0 without a word; the pinned line fails with "No matching distribution found" instead.
+- **The Claude Code hook section says what each policy mode does,** and that a new organization starts with nothing in enforce mode. It said the hook enforces your policies, which read as if it always blocked.
+
 ## 2.7.0 — release date is the `sdk-v2.7.0` tag's (prepared 2026-10-16)
 
 **The Claude Code hook bundled with this release is hook 2.5.0** (it was 2.4.0). Install it with `agentgovern hook install --force` after upgrading; see "Upgrading an existing install" in the README. Until you do, the hook you have keeps working exactly as before, and the AgentGovern server shows it a once-per-session notice that a newer hook is available.

{agentgovern-2.7.0 → agentgovern-2.7.3}/PKG-INFO

@@ -1,10 +1,9 @@
 Metadata-Version: 2.5
 Name: agentgovern
-Version: 2.7.0
+Version: 2.7.3
 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
-Project-URL: Issues, https://github.com/ahmedkhan-zirahn/agentgovern/issues
+Project-URL: Support, https://zirahn.com/contact
 Author-email: Ahmed Khan <ahmed.khan@zirahn.com>
 License: MIT
 License-File: LICENSE
@@ -44,14 +43,16 @@ Description-Content-Type: text/markdown
 
 **Compliance-as-code for agentic AI workflows.**
 
-> **Beta** — API may change before 1.0. [Report issues](https://github.com/ahmedkhan-zirahn/agentgovern/issues).
+> **Beta** — API may change before 1.0. Report issues through [zirahn.com/contact](https://zirahn.com/contact).
 
 AgentGovern intercepts AI agent actions, evaluates them against configurable compliance policies (the EU AI Act today; NIST AI RMF and ISO 42001 are on the roadmap — see the table below), and generates audit-ready evidence in near real-time. Tracking runs in a background thread and fails open. An `enforce`-mode block raises in your code (see *Enforcement modes* below for exactly what it stops). *(Corrected again 2026-10-03: the first correction said "the SDK blocks only if you enable Gate 2 `enforce` mode, where a block verdict raises `OutputBlocked`", which reads as if enforce mode halts an agent; through the integrations it does not — NAGT-380.)* This SDK auto-instruments LangChain and LangGraph; any other framework (CrewAI, OpenAI Agents and the rest) can report actions with `track_action()`. *(Corrected 2026-10-03: this said NIST AI RMF and ISO 42001 were supported, that the SDK never blocks, and that it instruments CrewAI and OpenAI Agents code.)*
 
 ## Install
 
+Needs **Python 3.10 or later**. The macOS system Python is 3.9, which is too old: install a newer one first, from python.org or with Homebrew (`brew install python@3.12`). On 3.9 this command fails with "No matching distribution found" rather than installing an old release.
+
 ```bash
-pip install "agentgovern[langchain]"
+python3 -m pip install "agentgovern[langchain]>=2.7.0"
 ```
 
 ## Quickstart — LangChain
@@ -212,19 +213,25 @@ Enable policy packs from the [AgentGovern dashboard](https://agentgovern.zirahn.
 **Policy engine address (2.4.0).** The default engine address is now the stable name
 `https://engine.zirahn.com`. Versions 2.3.0 and earlier call `https://agentgovern.onrender.com`
 directly. That address keeps working, so nothing breaks if you stay on an older version, but only
-the stable name can follow the engine if it moves. Upgrade with `pip install --upgrade agentgovern`.
+the stable name can follow the engine if it moves. Upgrade with `python3 -m pip install --upgrade "agentgovern>=2.7.0"`.
 If you set `policy_engine_url` or `AGENTGOVERN_POLICY_ENGINE_URL` yourself, it still takes precedence.
 
 ## Claude Code Hook
 
 The SDK ships a built-in CLI for installing the AgentGovern hook into Claude Code. The hook
-intercepts `PreToolUse` events for every tool call and enforces your tenant policies in real
-time — before the tool executes. A tool AgentGovern doesn't yet have a specific classification
-for is still captured and evaluated, tagged `action_type=unmapped_tool` rather than silently
-skipped.
+checks every tool call against your tenant's policies before the tool runs. A policy in
+**enforce** mode blocks the call and Claude Code shows the reason; **warn** lets it run and
+shows a warning; **log** only records it. A new organization starts with no policy in enforce
+mode. A tool AgentGovern doesn't yet have a specific classification for is still captured and
+evaluated, tagged `action_type=unmapped_tool` rather than silently skipped.
 
 ### Install
 
+**The simplest way is the dashboard:** on **Settings → Developers**, **Add Developer** gives an
+install snippet for bash and PowerShell that checks for Python 3.10 or later, installs this
+package into its own virtual environment, saves your two settings for new terminals, and runs
+the command below. To do it by hand:
+
 ```bash
 agentgovern hook install
 ```
@@ -242,7 +249,7 @@ reports it as already installed and changes nothing. Upgrade, read what is insta
 reinstall with `--force`:
 
 ```bash
-python3 -m pip install --upgrade agentgovern   # or the extra you installed with, e.g. "agentgovern[langchain]"
+python3 -m pip install --upgrade "agentgovern>=2.7.0"   # or the extra you installed with, e.g. "agentgovern[langchain]>=2.7.0"
 agentgovern hook status                        # note each line's cmd= value and the "Install mode" line
 agentgovern hook install --force               # plus the flags below, if status calls for them
 agentgovern hook status                        # reports no [DRIFT] lines once the hook is current
@@ -268,7 +275,7 @@ Your environment variables are not touched. Restart any running Claude Code sess
 
   ```bash
   python3 -m venv ~/.agentgovern-venv
-  ~/.agentgovern-venv/bin/python -m pip install --upgrade agentgovern
+  ~/.agentgovern-venv/bin/python -m pip install --upgrade "agentgovern>=2.7.0"
   ~/.agentgovern-venv/bin/agentgovern hook status
   ~/.agentgovern-venv/bin/agentgovern hook install --force   # plus the flags status called for
   ```
@@ -315,7 +322,7 @@ In PowerShell (the variable is removed again when claude exits):
 try { $env:AGENTGOVERN_HOOK_MODE='off'; claude } finally { Remove-Item Env:AGENTGOVERN_HOOK_MODE }
 ```
 
-See `packages/claude-hook/README.md` for the full option reference.
+`agentgovern hook install --help` lists the install options, and `agentgovern hook status` shows what is installed. The environment variables are in *Required env vars* and *Bypass* above.
 
 ## Design guarantees
 
@@ -327,8 +334,8 @@ See `packages/claude-hook/README.md` for the full option reference.
 ## Links
 
 - **Dashboard:** https://agentgovern.zirahn.com
-- **Documentation:** https://github.com/ahmedkhan-zirahn/agentgovern
-- **Issues:** https://github.com/ahmedkhan-zirahn/agentgovern/issues
+- **Documentation:** this README
+- **Support and issues:** https://zirahn.com/contact
 
 ## License
 

{agentgovern-2.7.0 → agentgovern-2.7.3}/README.md

@@ -2,14 +2,16 @@
 
 **Compliance-as-code for agentic AI workflows.**
 
-> **Beta** — API may change before 1.0. [Report issues](https://github.com/ahmedkhan-zirahn/agentgovern/issues).
+> **Beta** — API may change before 1.0. Report issues through [zirahn.com/contact](https://zirahn.com/contact).
 
 AgentGovern intercepts AI agent actions, evaluates them against configurable compliance policies (the EU AI Act today; NIST AI RMF and ISO 42001 are on the roadmap — see the table below), and generates audit-ready evidence in near real-time. Tracking runs in a background thread and fails open. An `enforce`-mode block raises in your code (see *Enforcement modes* below for exactly what it stops). *(Corrected again 2026-10-03: the first correction said "the SDK blocks only if you enable Gate 2 `enforce` mode, where a block verdict raises `OutputBlocked`", which reads as if enforce mode halts an agent; through the integrations it does not — NAGT-380.)* This SDK auto-instruments LangChain and LangGraph; any other framework (CrewAI, OpenAI Agents and the rest) can report actions with `track_action()`. *(Corrected 2026-10-03: this said NIST AI RMF and ISO 42001 were supported, that the SDK never blocks, and that it instruments CrewAI and OpenAI Agents code.)*
 
 ## Install
 
+Needs **Python 3.10 or later**. The macOS system Python is 3.9, which is too old: install a newer one first, from python.org or with Homebrew (`brew install python@3.12`). On 3.9 this command fails with "No matching distribution found" rather than installing an old release.
+
 ```bash
-pip install "agentgovern[langchain]"
+python3 -m pip install "agentgovern[langchain]>=2.7.0"
 ```
 
 ## Quickstart — LangChain
@@ -170,19 +172,25 @@ Enable policy packs from the [AgentGovern dashboard](https://agentgovern.zirahn.
 **Policy engine address (2.4.0).** The default engine address is now the stable name
 `https://engine.zirahn.com`. Versions 2.3.0 and earlier call `https://agentgovern.onrender.com`
 directly. That address keeps working, so nothing breaks if you stay on an older version, but only
-the stable name can follow the engine if it moves. Upgrade with `pip install --upgrade agentgovern`.
+the stable name can follow the engine if it moves. Upgrade with `python3 -m pip install --upgrade "agentgovern>=2.7.0"`.
 If you set `policy_engine_url` or `AGENTGOVERN_POLICY_ENGINE_URL` yourself, it still takes precedence.
 
 ## Claude Code Hook
 
 The SDK ships a built-in CLI for installing the AgentGovern hook into Claude Code. The hook
-intercepts `PreToolUse` events for every tool call and enforces your tenant policies in real
-time — before the tool executes. A tool AgentGovern doesn't yet have a specific classification
-for is still captured and evaluated, tagged `action_type=unmapped_tool` rather than silently
-skipped.
+checks every tool call against your tenant's policies before the tool runs. A policy in
+**enforce** mode blocks the call and Claude Code shows the reason; **warn** lets it run and
+shows a warning; **log** only records it. A new organization starts with no policy in enforce
+mode. A tool AgentGovern doesn't yet have a specific classification for is still captured and
+evaluated, tagged `action_type=unmapped_tool` rather than silently skipped.
 
 ### Install
 
+**The simplest way is the dashboard:** on **Settings → Developers**, **Add Developer** gives an
+install snippet for bash and PowerShell that checks for Python 3.10 or later, installs this
+package into its own virtual environment, saves your two settings for new terminals, and runs
+the command below. To do it by hand:
+
 ```bash
 agentgovern hook install
 ```
@@ -200,7 +208,7 @@ reports it as already installed and changes nothing. Upgrade, read what is insta
 reinstall with `--force`:
 
 ```bash
-python3 -m pip install --upgrade agentgovern   # or the extra you installed with, e.g. "agentgovern[langchain]"
+python3 -m pip install --upgrade "agentgovern>=2.7.0"   # or the extra you installed with, e.g. "agentgovern[langchain]>=2.7.0"
 agentgovern hook status                        # note each line's cmd= value and the "Install mode" line
 agentgovern hook install --force               # plus the flags below, if status calls for them
 agentgovern hook status                        # reports no [DRIFT] lines once the hook is current
@@ -226,7 +234,7 @@ Your environment variables are not touched. Restart any running Claude Code sess
 
   ```bash
   python3 -m venv ~/.agentgovern-venv
-  ~/.agentgovern-venv/bin/python -m pip install --upgrade agentgovern
+  ~/.agentgovern-venv/bin/python -m pip install --upgrade "agentgovern>=2.7.0"
   ~/.agentgovern-venv/bin/agentgovern hook status
   ~/.agentgovern-venv/bin/agentgovern hook install --force   # plus the flags status called for
   ```
@@ -273,7 +281,7 @@ In PowerShell (the variable is removed again when claude exits):
 try { $env:AGENTGOVERN_HOOK_MODE='off'; claude } finally { Remove-Item Env:AGENTGOVERN_HOOK_MODE }
 ```
 
-See `packages/claude-hook/README.md` for the full option reference.
+`agentgovern hook install --help` lists the install options, and `agentgovern hook status` shows what is installed. The environment variables are in *Required env vars* and *Bypass* above.
 
 ## Design guarantees
 
@@ -285,8 +293,8 @@ See `packages/claude-hook/README.md` for the full option reference.
 ## Links
 
 - **Dashboard:** https://agentgovern.zirahn.com
-- **Documentation:** https://github.com/ahmedkhan-zirahn/agentgovern
-- **Issues:** https://github.com/ahmedkhan-zirahn/agentgovern/issues
+- **Documentation:** this README
+- **Support and issues:** https://zirahn.com/contact
 
 ## License
 

{agentgovern-2.7.0 → agentgovern-2.7.3}/RELEASING.md

@@ -93,4 +93,12 @@ To re-run a publish after a failed run, trigger the workflow manually **from the
   - its bundled `hook.py` is hook 2.4.0, byte-identical to the tag commit's;
   - each file's PyPI attestation names publisher `ZirahnAI/agentgovern`, workflow `publish-sdk.yml`, environment `pypi`, with a subject digest equal to the file's;
   - an unpinned install resolves 2.6.0 on Python 3.12 and 2.5.0 on Python 3.9.6 (`/usr/bin/python3`, macOS 15.8.1).
+- **2026-10-16:** 2.7.0 was published by run `38849510745` from tag `sdk-v2.7.0` at `90a5d6db` (#947's merge). **The tag was pushed by Claude Code under Ahmed's explicit, one-time authorisation for this tag**; the push printed the tag ruleset's "Cannot create ref due to creations being restricted" line and created the tag (the admin bypass). Build 04:13:32–04:13:52Z, Publish 04:13:56–04:14:27Z; files uploaded 04:14:22Z and 04:14:23Z. Verified afterwards, read-only:
+  - the wheel and sdist sha256 match PyPI's digests (`57105511…`, `e266e7e9…`), compared with the run's own `dist` artifact;
+  - the wheel's `METADATA` says `Version: 2.7.0`, `Requires-Python: >=3.10`;
+  - its bundled `hook.py` is **hook 2.5.0**, sha256 `f43c3c95010120dd34e8a91982de11516d9d3c582b5e2fd4bb7791c8fa6ffec1`, byte-identical to the tag commit's;
+  - each file's PyPI attestation names publisher `ZirahnAI/agentgovern`, workflow `publish-sdk.yml`, environment `pypi`;
+  - a fresh Python 3.12 venv installing `agentgovern==2.7.0` from PyPI reports `__version__` 2.7.0, and `hook install` into a temporary HOME writes hook 2.5.0 with all four events OK (`hook test` not run: it calls production);
+  - Python 3.9.6 (`/usr/bin/python3`) resolves `agentgovern-2.5.0`;
+  - the hook version changed, so the released-hook manifest moved to 2.5.0 after the tag (NAGT-400 (c), #953, `b748b1f7`).
 

agentgovern-2.7.3/agentgovern/_version.py

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

{agentgovern-2.7.0 → agentgovern-2.7.3}/agentgovern/hook/cli.py

@@ -57,7 +57,8 @@ def add_hook_subparsers(hook_parser: argparse.ArgumentParser) -> None:
         default=None,
         help=(
             "Override the python command written to settings.json "
-            "(default: 'python' on Windows, 'python3' elsewhere)."
+            "(default: the absolute path of the Python running this command; "
+            "'python' on Windows or 'python3' elsewhere if it is unknown)."
         ),
     )
     install.add_argument(

{agentgovern-2.7.0 → agentgovern-2.7.3}/agentgovern/hook/data/hook.py

@@ -18,6 +18,10 @@ Configuration (environment variables):
         entirely, for all events, unchanged.
     AGENTGOVERN_HOOK_VERBOSE      Default: 0     (0 | 1)
     AGENTGOVERN_FAIL_ACTION       Default: allow (allow | deny)
+        What a PreToolUse does when AgentGovern did not check the call. 'deny'
+        blocks it: on no answer at all, on an HTTP error answer, and (since
+        v2.5.1, NAGT-484) on a `timeout` verdict, the server's "Evaluation
+        Failed". 'allow' lets it run.
     AGENTGOVERN_HOOK_TIMEOUT_MS   Default: 5000
     AGENTGOVERN_CAPTURE_MODE      Default: enriched  (enriched | minimal)
         enriched — all 4 events (UserPromptSubmit, PreToolUse, PostToolUse, Stop)
@@ -49,6 +53,12 @@ policies_violated entry whose enforcement_mode matches the verdict
 falling back to the first entry; and async events dropped on an HTTP error
 are counted per session and reported once per session in verbose mode.
 
+NAGT-484 (v2.5.1), docs/audit-reports/nagt-484-deny-on-errors-2026-10-22.md:
+AGENTGOVERN_FAIL_ACTION=deny also blocks a PreToolUse that gets an HTTP error
+back (a 429 included) or a `timeout` verdict, not only one that gets no answer.
+The deny reason is the hook's own text and the HTTP status; nothing from the
+response body reaches it. With the default (allow), nothing changes.
+
 See README.md for installation instructions.
 """
 from __future__ import annotations
@@ -70,7 +80,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-__version__ = "2.5.0"
+__version__ = "2.5.1"
 
 # ── Constants ──────────────────────────────────────────────────────────────────
 
@@ -487,6 +497,35 @@ def format_warn_message(evaluation: dict[str, Any]) -> str:
     )
 
 
+def _unchecked_deny_reason(what: str) -> str:
+    """NAGT-484: the deny reason when AGENTGOVERN_FAIL_ACTION=deny blocks an unchecked call.
+
+    `what` is the hook's own words (and at most an HTTP status number): nothing
+    from the response body, which can come from an edge proxy, reaches Claude.
+    """
+    return (
+        f"AgentGovern {what}, so this tool call was not checked. "
+        "AGENTGOVERN_FAIL_ACTION=deny: blocking it."
+    )
+
+
+def _missing_config_deny_reason(missing: list[str]) -> str:
+    """NAGT-500: the deny reason when AGENTGOVERN_FAIL_ACTION=deny blocks a call
+    the hook can't send for checking, because its configuration is missing.
+
+    `missing` holds variable NAMES only; their values are empty by definition,
+    and no other environment value is included.
+    """
+    names = " and ".join(missing)
+    verb = "is" if len(missing) == 1 else "are"
+    return (
+        f"AgentGovern isn't set up in this shell: {names} {verb} not set, "
+        "so this tool call was not checked. AGENTGOVERN_FAIL_ACTION=deny: blocking it. "
+        "To fix it, paste your install snippet again from Settings → Developers "
+        f"in the AgentGovern dashboard, or set {names} and open a new terminal."
+    )
+
+
 def render_deny_output(reason: str) -> str:
     """Return the JSON string for a PreToolUse deny decision."""
     return json.dumps({
@@ -657,10 +696,11 @@ def _claim_session_notice(session_id: Any, kind: str = "stale_hook") -> bool:
 
 
 # NAGT-400 (b): a PreToolUse HTTP 429 means the tenant's ingest rate limit was
-# reached, so this tool call was not evaluated and is being allowed (HTTP
-# errors never deny, AGENTGOVERN_FAIL_ACTION included). The stderr line reaches
-# only the debug log; this is the developer-visible half. The text is the
-# hook's own: nothing from the 429's body is shown.
+# reached, so this tool call was not evaluated and is being allowed (with
+# AGENTGOVERN_FAIL_ACTION=deny it is blocked instead, NAGT-484, and this message
+# is not shown). The stderr line reaches only the debug log; this is the
+# developer-visible half. The text is the hook's own: nothing from the 429's
+# body is shown.
 _RATE_LIMIT_MESSAGE = (
     "AgentGovern: your team reached Guard's rate limit, so this tool call was "
     "not checked by Guard and was allowed. Please tell your team's AgentGovern admin."
@@ -1555,6 +1595,26 @@ def _handle_pre_tool_use(
         _vlog("[agentgovern] Mode=off — skipping.")
         return 0
 
+    # NAGT-500: under deny, a call the hook can't send for checking (no key, no
+    # actor id) is as unchecked as one AgentGovern didn't answer, so it is
+    # blocked too. Under allow (the default) both cases below are unchanged.
+    missing = [
+        name
+        for name, value in (
+            ("AGENTGOVERN_API_KEY", api_key),
+            ("AGENTGOVERN_ACTOR_USER_ID", actor_user_id),
+        )
+        if not value
+    ]
+    if missing and fail_action == "deny":
+        _err(
+            f"[agentgovern] {' and '.join(missing)} not set — "
+            "blocking (AGENTGOVERN_FAIL_ACTION=deny)."
+        )
+        sys.stdout.write(render_deny_output(_missing_config_deny_reason(missing)))
+        sys.stdout.flush()
+        return 0
+
     if not api_key:
         _err(
             "[agentgovern] AGENTGOVERN_API_KEY not set — "
@@ -1623,15 +1683,27 @@ def _handle_pre_tool_use(
             if isinstance(err_obj, dict):
                 code = err_obj.get("code", "")
         detail = f" ({code})" if code else ""
+        if fail_action == "deny":
+            # NAGT-484: an error answer leaves the call as unchecked as no
+            # answer does. Only the status number is used, never the body.
+            _err(f"[agentgovern] HTTP {status}{detail} from governance endpoint — blocking.")
+            what = (
+                "reached your team's rate limit (HTTP 429)"
+                if status == 429
+                else f"answered with an error (HTTP {status if isinstance(status, int) else '?'})"
+            )
+            sys.stdout.write(render_deny_output(_unchecked_deny_reason(what)))
+            sys.stdout.flush()
+            return 0
         _err(
             f"[agentgovern] HTTP {status}{detail} from governance endpoint "
             "— proceeding unaudited."
         )
         if status == 429:
             # NAGT-400 (b): the developer-visible half, at most once a minute
-            # per session. systemMessage only, never a permissionDecision; the
-            # call is still allowed whatever AGENTGOVERN_FAIL_ACTION says, as
-            # every HTTP error is. Fail-open inside.
+            # per session. systemMessage only, never a permissionDecision; with
+            # the default fail action the call is still allowed, as every HTTP
+            # error is. Fail-open inside.
             _surface_rate_limited(hook_event.get("session_id"))
         return 0
 
@@ -1670,6 +1742,14 @@ def _handle_pre_tool_use(
         return 0
 
     if verdict == "timeout":
+        if fail_action == "deny":
+            # NAGT-484: the server could not evaluate the call (it is marked
+            # "Evaluation Failed"), so it was not checked.
+            _err("[agentgovern] Policy evaluation timed out server-side — blocking.")
+            reason = _unchecked_deny_reason("couldn't evaluate this tool call")
+            sys.stdout.write(render_deny_output(reason))
+            sys.stdout.flush()
+            return 0
         _err(
             "[agentgovern] Policy evaluation timed out server-side "
             "— tool call proceeding unaudited."

{agentgovern-2.7.0 → agentgovern-2.7.3}/agentgovern/hook/installer.py

@@ -103,6 +103,19 @@ def _hook_target_path() -> Path:
 
 
 def _detect_python_command() -> str:
+    """The interpreter the hook entry runs: the one running this installer.
+
+    NAGT-490: a bare `python3` is looked up on the PATH Claude Code has when it
+    runs the hook, which need not be the shell's. Started from the Dock, it is
+    /usr/bin:/bin:..., where a Mac without the Command Line Tools has only a stub
+    python3 that asks to install them and runs nothing. sys.executable is the
+    absolute path of a Python that has this package, so 3.10 or later: in a
+    venv, the venv's own python. Bare names remain the fallback for an
+    interpreter that cannot say where it is.
+    """
+    exe = sys.executable
+    if exe and os.path.isabs(exe) and os.path.isfile(exe):
+        return exe
     return "python" if sys.platform == "win32" else "python3"
 
 
@@ -703,6 +716,10 @@ def uninstall() -> int:
         print("AgentGovern hook is not installed (no entry found in settings.json).")
         return 0
 
+    # NAGT-391 F8: the install-mode marker is Guard's own key, written by the
+    # install; it goes with the hook, so the settings are left as they were.
+    new_settings.pop(INSTALL_MODE_KEY, None)
+
     if settings_path.exists():
         backup(settings_path)
 
@@ -712,6 +729,12 @@ def uninstall() -> int:
         print(f"Error: {exc}", file=sys.stderr)
         return 1
 
+    # NAGT-391 F8: the backup only guards the write above, which succeeded. Left
+    # behind, it is a copy of the settings that still registers Guard's hook, and
+    # restoring it would point Claude Code at a hook script the uninstall
+    # snippet then deletes. (Found by the install rehearsal workflow.)
+    settings_path.with_suffix(".json.bak").unlink(missing_ok=True)
+
     print(f"AgentGovern hook removed from {settings_path} (all event types).")
     print(f"The hook script at {hook_target} was not deleted.")
     return 0

{agentgovern-2.7.0 → agentgovern-2.7.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentgovern"
-version = "2.7.0"
+version = "2.7.3"
 description = "Compliance-as-code middleware for agentic AI workflows."
 readme = "README.md"
 license = { text = "MIT" }
@@ -64,8 +64,7 @@ agentgovern = "agentgovern.__main__:main"
 
 [project.urls]
 Homepage = "https://agentgovern.zirahn.com"
-Repository = "https://github.com/ahmedkhan-zirahn/agentgovern"
-Issues = "https://github.com/ahmedkhan-zirahn/agentgovern/issues"
+Support = "https://zirahn.com/contact"
 
 [build-system]
 requires = ["hatchling"]

agentgovern-2.7.3/tests/hook/fixtures/action_name_cuts.json

@@ -0,0 +1,35 @@
+{
+  "_comment": "NAGT-403: action names made by the Guard hook's own functions (packages/claude-hook/agentgovern_hook.py: _truncate_for_action_name for prompts and replies, format_action_name for Bash). {GH} stands for a fake GitHub token, ghp_ followed by 36 'a', and {GHP} for its ghp_ prefix where a name cut it short; each test substitutes both (literal fragments would trip the repository's secret scan). test_action_name_cuts_fixture.py regenerates every name from the hook and fails if one differs.",
+  "cases": [
+    {
+      "id": "prompt-cut-through-token",
+      "kind": "prompt",
+      "source": "Create a .env file in this folder with the lines DEBUG=true and GITHUB_TOKEN={GH} and nothing else.",
+      "hook_action_name": "Create a .env file in this folder with the lines DEBUG=true and GITHUB_TOKEN={GHP}aaaaaaaaaaaaaaaa..."
+    },
+    {
+      "id": "prompt-newlines-flattened",
+      "kind": "prompt",
+      "source": "Please set up the project.\nUse these settings:\nDEBUG=true\nAPI token for GitHub is GITHUB_TOKEN={GH}\nThanks",
+      "hook_action_name": "Please set up the project. Use these settings: DEBUG=true API token for GitHub is GITHUB_TOKEN=gh..."
+    },
+    {
+      "id": "reply-cut-through-token",
+      "kind": "reply",
+      "source": "I created `/Users/someone/project/.env` with two lines. The second sets GITHUB_TOKEN={GH} as you asked.",
+      "hook_action_name": "I created `/Users/someone/project/.env` with two lines. The second sets GITHUB_TOKEN={GHP}aaaaaaaa..."
+    },
+    {
+      "id": "bash-cut-at-200-through-token",
+      "kind": "bash",
+      "source": "echo 'configuring the deployment environment for the staging cluster, then writing the token into the local env file so that the gh CLI can authenticate' && export GITHUB_TOKEN={GH} && gh auth status",
+      "hook_action_name": "Bash: echo 'configuring the deployment environment for the staging cluster, then writing the token into the local env file so that the gh CLI can authenticate' && export GITHUB_TOKEN={GHP}aaaaaaaaaaaaa"
+    },
+    {
+      "id": "prompt-not-cut",
+      "kind": "prompt",
+      "source": "Use GITHUB_TOKEN={GH} please",
+      "hook_action_name": "Use GITHUB_TOKEN={GH} please"
+    }
+  ]
+}

{agentgovern-2.7.0 → agentgovern-2.7.3}/tests/hook/fixtures/hook_2_4_0_golden_outputs.json

@@ -324,38 +324,6 @@
         "stdout": ""
       }
     ],
-    "http-503-deny-mode": [
-      {
-        "rc": 0,
-        "sent": [
-          {
-            "action_name": "Bash: ls -la",
-            "action_type": "code_execution",
-            "actor_user_id": "user_test",
-            "client_timestamp": "<TS>",
-            "command_executed": "ls -la",
-            "context_snapshot": {
-              "claude_code_version": "unknown",
-              "cwd": null,
-              "git_branch": null,
-              "git_commit_sha": null,
-              "hook_version": "<HOOK_VERSION>"
-            },
-            "conversation_id": "sess-1",
-            "evaluation_mode": "sync",
-            "input": {
-              "command": "ls -la"
-            },
-            "schema_version": "1",
-            "source_type": "interactive_cli",
-            "source_version": "agentgovern-claude-hook/<HOOK_VERSION>",
-            "tool_event_type": "execute"
-          }
-        ],
-        "stderr": "[agentgovern] Response in <N>ms\n[agentgovern] HTTP 503 from governance endpoint — proceeding unaudited.\n",
-        "stdout": ""
-      }
-    ],
     "minimal-block": [
       {
         "rc": 0,

agentgovern-2.7.3/tests/hook/test_action_name_cuts_fixture.py

@@ -0,0 +1,50 @@
+"""NAGT-403: the action-name cut fixture matches the hook that makes the names.
+
+The web app's ingest masking (apps/web/lib/secret-masking/ingest.ts) is tested
+against fixtures/action_name_cuts.json: prompts, replies and Bash commands with a
+fake GitHub token, and the action name the Guard hook builds from each. This test
+rebuilds every name with the hook's own functions, so a change to how the hook
+cuts names fails here instead of leaving the web tests on a stale copy.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from types import ModuleType
+
+FIXTURE = Path(__file__).parent / "fixtures" / "action_name_cuts.json"
+GH = "ghp_" + "a" * 36
+PLACEHOLDER = "{GH}"
+PREFIX_PLACEHOLDER = "{GHP}"
+
+
+def _expand(text: str) -> str:
+    return text.replace(PLACEHOLDER, GH).replace(PREFIX_PLACEHOLDER, "ghp_")
+
+
+def _name(hook_mod: ModuleType, kind: str, source: str) -> str:
+    if kind == "bash":
+        return hook_mod.format_action_name("Bash", {"command": source})
+    return hook_mod._truncate_for_action_name(source)
+
+
+def test_every_fixture_name_is_what_the_hook_builds(hook_mod: ModuleType) -> None:
+    cases = json.loads(FIXTURE.read_text())["cases"]
+    assert {c["kind"] for c in cases} == {"prompt", "reply", "bash"}
+    for case in cases:
+        built = _name(hook_mod, case["kind"], _expand(case["source"]))
+        assert built == _expand(case["hook_action_name"]), case["id"]
+
+
+def test_the_cut_cases_really_cut_the_token_short(hook_mod: ModuleType) -> None:
+    """Each *-cut-* case leaves a token fragment the masking pattern cannot match
+    ({20,} after the prefix), which is the defect NAGT-403 fixes."""
+    cases = json.loads(FIXTURE.read_text())["cases"]
+    cut = [c for c in cases if "-cut-" in c["id"]]
+    assert len(cut) == 3
+    for case in cut:
+        assert PLACEHOLDER not in case["hook_action_name"], case["id"]
+        name = _expand(case["hook_action_name"])
+        tail = name.removesuffix("...").rsplit("ghp_", 1)[1]
+        assert 0 <= len(tail) < 20, case["id"]

{agentgovern-2.7.0 → agentgovern-2.7.3}/tests/hook/test_hook_v2_nagt400.py

@@ -135,9 +135,9 @@ def _only_system_message(stdout: str) -> str:
 
 
 def test_version_is_2_5_0(env):
-    assert env.__version__ == "2.5.0"
-    assert env.HOOK_VERSION == "2.5.0"
-    assert env._SOURCE_VERSION == "agentgovern-claude-hook/2.5.0"
+    assert env.__version__ == "2.5.1"
+    assert env.HOOK_VERSION == "2.5.1"
+    assert env._SOURCE_VERSION == "agentgovern-claude-hook/2.5.1"
 
 
 # ── 1. usage_limit notice ─────────────────────────────────────────────────────
@@ -373,13 +373,17 @@ def test_rate_limit_marker_that_is_not_a_regular_file_means_do_not_show(env, tmp
     assert abs(directory.stat().st_mtime - old) < 1
 
 
-def test_429_in_deny_mode_still_allows(env, monkeypatch, capsys):
+def test_429_in_deny_mode_blocks_without_the_rate_limit_message(env, monkeypatch, capsys):
+    # NAGT-484 (hook 2.5.1): deny blocks an unchecked call, a 429 included,
+    # and the deny is the only output (no systemMessage beside it).
     monkeypatch.setenv("AGENTGOVERN_FAIL_ACTION", "deny")
-    rc, out, err = _pre(env, monkeypatch, capsys, _R429)
-    assert rc == 0
-    _assert_rate_limit_output(out, err)
-    rc, out, _ = _pre(env, monkeypatch, capsys, _R429)  # throttled: nothing, still no deny
-    assert rc == 0 and out == ""
+    for _ in range(2):
+        rc, out, err = _pre(env, monkeypatch, capsys, _R429)
+        obj = json.loads(out)
+        assert rc == 0 and set(obj) == {"hookSpecificOutput"}
+        assert obj["hookSpecificOutput"]["permissionDecision"] == "deny"
+        assert "rate limit (HTTP 429)" in obj["hookSpecificOutput"]["permissionDecisionReason"]
+        assert "HTTP 429" in err
 
 
 @pytest.mark.parametrize("status", [400, 401, 403, 404, 413, 428, 430, 500, 502, 503, 504])

{agentgovern-2.7.0 → agentgovern-2.7.3}/tests/hook/test_hook_v2_nagt400_compat.py

@@ -18,6 +18,11 @@ Deliberately NOT in this table, because 2.5.0 changes them on purpose: an HTTP
 429 on PreToolUse (now a systemMessage), a "usage_limit" notice (now shown),
 entries carrying `enforcement_mode` (now selected by mode), and verbose mode on
 a Stop event after a dropped async event (now reported).
+
+Removed in 2.5.1 (NAGT-484), because it changes on purpose: an HTTP error on
+PreToolUse with AGENTGOVERN_FAIL_ACTION=deny (the "http-503-deny-mode" case,
+now a deny; packages/claude-hook/tests/test_deny_on_errors.py). Every other
+case still matches 2.4.0 byte for byte.
 """
 
 from __future__ import annotations
@@ -135,7 +140,6 @@ CASES: dict[str, list[tuple[dict[str, str], dict, Any]]] = {
     "http-503": [({}, _pre(), _http(503, "SERVICE_UNAVAILABLE"))],
     "http-403": [({}, _pre(), _http(403, "ACTOR_NOT_IN_TENANT"))],
     "http-400-no-body": [({}, _pre(), _http(400))],
-    "http-503-deny-mode": [({"AGENTGOVERN_FAIL_ACTION": "deny"}, _pre(), _http(503))],
     "network-allow": [({}, _pre(), None)],
     "network-deny": [({"AGENTGOVERN_FAIL_ACTION": "deny"}, _pre(), None)],
     "minimal-block": [({"AGENTGOVERN_CAPTURE_MODE": "minimal"}, _pre(), _ok("block", [_P1]))],
@@ -229,6 +233,6 @@ def test_golden_file_covers_exactly_these_cases() -> None:
 
 def test_2_4_0_style_exchanges_are_byte_identical_to_2_4_0(hook_mod: ModuleType) -> None:
     golden = json.loads(GOLDEN.read_text(encoding="utf-8"))["cases"]
-    assert hook_mod.__version__ == "2.5.0"
+    assert hook_mod.__version__ == "2.5.1"
     for name, steps in CASES.items():
         assert run_case(hook_mod, steps) == golden[name], name

{agentgovern-2.7.0 → agentgovern-2.7.3}/tests/hook/test_installer.py

@@ -92,10 +92,40 @@ def test_install_writes_absolute_path_to_args(
     assert "%USERPROFILE%" not in args_val
 
 
+def test_install_registers_the_running_python_by_absolute_path(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """NAGT-490: the interpreter running `hook install` (a venv's python), not a bare name."""
+    home = _fake_home(tmp_path, monkeypatch)
+    venv_python = tmp_path / "my venv" / "bin" / "python"
+    venv_python.parent.mkdir(parents=True)
+    venv_python.write_text("")
+    monkeypatch.setattr(sys, "executable", str(venv_python))
+    for platform in ("darwin", "linux", "win32"):
+        monkeypatch.setattr(sys, "platform", platform)
+        installer.install(_default_args(force=True))
+        cfg = json.loads(_settings_path(home).read_text())
+        for event in ("PreToolUse", "UserPromptSubmit", "PostToolUse", "Stop"):
+            assert cfg["hooks"][event][0]["hooks"][0]["command"] == str(venv_python), event
+
+
+@pytest.mark.parametrize("executable", ["", "python3", "/no/such/python"])
+def test_install_falls_back_to_a_bare_name_when_the_python_is_unknown(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, executable: str
+) -> None:
+    """sys.executable can be empty, relative or gone; then the 2.7.2 default."""
+    monkeypatch.setattr(sys, "executable", executable)
+    monkeypatch.setattr(sys, "platform", "darwin")
+    assert installer._detect_python_command() == "python3"
+    monkeypatch.setattr(sys, "platform", "win32")
+    assert installer._detect_python_command() == "python"
+
+
 def test_install_uses_python3_on_non_windows(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
     home = _fake_home(tmp_path, monkeypatch)
+    monkeypatch.setattr(sys, "executable", "")
     monkeypatch.setattr(sys, "platform", "linux")
     monkeypatch.setattr(installer, "_python_on_path", lambda cmd: True)
     installer.install(_default_args())
@@ -106,6 +136,7 @@ def test_install_uses_python3_on_non_windows(
 
 def test_install_uses_python_on_windows(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     home = _fake_home(tmp_path, monkeypatch)
+    monkeypatch.setattr(sys, "executable", "")
     monkeypatch.setattr(sys, "platform", "win32")
     monkeypatch.setattr(installer, "_python_on_path", lambda cmd: True)
     installer.install(_default_args())
@@ -601,6 +632,37 @@ def test_uninstall_preserves_other_config(tmp_path: Path, monkeypatch: pytest.Mo
     assert cfg.get("theme") == "dark"
 
 
+def test_uninstall_leaves_the_settings_exactly_as_before_the_install(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """NAGT-391 F8: no install-mode marker and no backup are left behind."""
+    home = _fake_home(tmp_path, monkeypatch)
+    before = {"theme": "dark", "permissions": {"allow": ["Bash(ls:*)"]}}
+    _write_json(_settings_path(home), before)
+    installer.install(_default_args())
+    assert _MARKER_KEY in json.loads(_settings_path(home).read_text())
+    assert _settings_path(home).with_suffix(".json.bak").exists()
+    assert installer.uninstall() == 0
+    assert json.loads(_settings_path(home).read_text()) == before
+    assert not _settings_path(home).with_suffix(".json.bak").exists()
+
+
+def test_uninstall_keeps_the_backup_when_the_write_fails(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The backup is removed only after a successful write."""
+    home = _fake_home(tmp_path, monkeypatch)
+    _write_json(_settings_path(home), {"theme": "dark"})
+    installer.install(_default_args())
+
+    def refuse(*_args, **_kwargs):  # type: ignore[no-untyped-def]
+        raise PermissionError("read-only")
+
+    monkeypatch.setattr(installer, "atomic_write", refuse)
+    assert installer.uninstall() == 1
+    assert _settings_path(home).with_suffix(".json.bak").exists()
+
+
 def test_uninstall_not_installed_exits_zero(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture
 ) -> None:

agentgovern-2.7.0/agentgovern/_version.py

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