agentgovern 2.6.0__tar.gz → 2.7.2__tar.gz

{agentgovern-2.6.0 → agentgovern-2.7.2}/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## 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.
+
+**Python 3.10 or later and the dependencies (`httpx`, `pydantic`) are unchanged from 2.6.0.** The hook itself still runs on Python 3.9 or later.
+
+### Change — you are told when Guard's rate limit lets a tool call through unchecked (hook 2.5.0, NAGT-400)
+
+- **When your team's Guard rate limit is reached, Claude Code now shows:**
+  `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.`
+- **At most once a minute per session,** so a burst does not flood the terminal.
+- **The tool call still proceeds,** as before, including with `AGENTGOVERN_FAIL_ACTION=deny`, which still applies only when the server cannot be reached at all.
+- **Hook 2.4.0 and earlier wrote this only to the hook's debug output, which Claude Code does not show,** so a rate-limited tool call passed silently.
+- The message is the hook's own text. Nothing from the server's response is shown.
+
+### Change — the hook shows usage-limit notices (hook 2.5.0, NAGT-400)
+
+- **When the AgentGovern server reports that your team has reached its Guard allowance or storage limit,** Claude Code shows that notice once per session.
+- It goes through the same path as the out-of-date-hook notice, with the same cleaning and length limits. The two notices are tracked separately, so one never hides the other.
+- **Nothing is blocked by it.** Guard keeps checking every tool call.
+
+### Fix — block and warning messages name the policy that decided (hook 2.5.0, NAGT-401)
+
+- **When one tool call fails several policies, the message now names the one that made the decision:** for a block, the first policy in *enforce* mode; for a warning, the first in *warn* or *alert* mode.
+- **Hook 2.4.0 named the first failing policy whatever its mode,** so a block could name a policy that was only logging.
+- **This needs a server that sends each policy's mode.** With an older server, the hook names the first failing policy, as before.
+
+### Change — dropped background events are counted (hook 2.5.0, NAGT-400)
+
+- **Prompts, tool results and the end of each Claude response** are sent in the background. When the server answers one of them with an error, it is still not retried, and it is now counted per session.
+- **With `AGENTGOVERN_HOOK_VERBOSE=1`, the count is reported once per session,** the first time Claude finishes a response after an event was dropped. It goes to the hook's debug output only; nothing is shown in Claude Code.
+
+### Change — three more kinds of session file
+
+- The hook's per-session files in `~/.agentgovern/sessions` gain three kinds: the usage-notice marker, the rate-limit message timer and the dropped-event count.
+- **They are cleaned up like the others,** after 30 days.
+
+### Fix — `agentgovern hook install` gives Windows instructions in PowerShell (NAGT-418)
+
+**What changed, on Windows only:**
+- **Missing environment variables.** When `AGENTGOVERN_API_KEY` or `AGENTGOVERN_ACTOR_USER_ID` is not set, `hook install` now prints one runnable line per variable, `[Environment]::SetEnvironmentVariable('<NAME>', '<your-value>', 'User')`, and tells you to open a new PowerShell window. It used to suggest `$env:VAR = 'value'` and adding it to `$PROFILE`.
+- **`agentgovern hook test`** gives the same advice when either variable is missing.
+- **The two closing hints** (turn governance off for one session, or go back to v1 capture) are now PowerShell commands, for example
+  `try { $env:AGENTGOVERN_HOOK_MODE='off'; claude } finally { Remove-Item Env:AGENTGOVERN_HOOK_MODE }`.
+  They used to print the bash form `AGENTGOVERN_HOOK_MODE=off claude`, which is an error in PowerShell. The variable is set for that one run of `claude` and removed from the PowerShell window when `claude` exits. **Unlike the bash form, it does not restore an earlier value:** if you had already set `AGENTGOVERN_HOOK_MODE` in that window, it is unset afterwards. A value saved at User scope is not touched, and new windows still get it.
+
+**What did not change:**
+- **On macOS and Linux, the installer's output is unchanged.**
+- **What the installer writes is unchanged** on every platform: the same hook file and the same `settings.json` entries.
+- **These lines are printed, not run.** The installer does not set any environment variable for you.
+
+**The Python command the hook is registered with is unchanged:** on Windows the installer still writes a bare `python` unless you pass `--python-command`. The dashboard's PowerShell install snippet now passes the virtual environment's own `python.exe` that way. The snippet is part of the dashboard, not of this package, and works with earlier SDK versions too, since `--python-command` is not new.
+
+The README (shown on PyPI) now gives the PowerShell form of the one-session bypass next to the bash form.
+
 ## 2.6.0 — release date is the `sdk-v2.6.0` tag's
 
 **The bundled Claude Code hook is unchanged: hook 2.4.0.** No `agentgovern hook install --force` is needed for this release.

{agentgovern-2.6.0 → agentgovern-2.7.2}/PKG-INFO

@@ -1,10 +1,9 @@
 Metadata-Version: 2.5
 Name: agentgovern
-Version: 2.6.0
+Version: 2.7.2
 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
   ```
@@ -287,9 +294,11 @@ the matcher is `*`, every tool — but only once `hook install --force` has rewr
 
 ```bash
 export AGENTGOVERN_API_KEY="ag_prod_..."           # Settings → API Keys
-export AGENTGOVERN_ACTOR_USER_ID="<your-actor-id>"  # from your install snippet: Settings → Developers (see the hook README)
+export AGENTGOVERN_ACTOR_USER_ID="<your-actor-id>"  # Settings → Developers: your install snippet, or "Your actor ID" (see the hook README)
 ```
 
+*(Corrected 2026-10-05, NAGT-379: the comment above named only the install snippet. Settings → Developers also shows the signed-in user's own **Your actor ID**, for running the hook yourself, and is shown when the workspace's workflow is Guard or Mixed.)*
+
 ### Subcommands
 
 | Command | Description |
@@ -307,7 +316,13 @@ To skip governance for a session without removing the hook:
 AGENTGOVERN_HOOK_MODE=off claude
 ```
 
-See `packages/claude-hook/README.md` for the full option reference.
+In PowerShell (the variable is removed again when claude exits):
+
+```powershell
+try { $env:AGENTGOVERN_HOOK_MODE='off'; claude } finally { Remove-Item Env:AGENTGOVERN_HOOK_MODE }
+```
+
+`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
 
@@ -319,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.6.0 → agentgovern-2.7.2}/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
   ```
@@ -245,9 +253,11 @@ the matcher is `*`, every tool — but only once `hook install --force` has rewr
 
 ```bash
 export AGENTGOVERN_API_KEY="ag_prod_..."           # Settings → API Keys
-export AGENTGOVERN_ACTOR_USER_ID="<your-actor-id>"  # from your install snippet: Settings → Developers (see the hook README)
+export AGENTGOVERN_ACTOR_USER_ID="<your-actor-id>"  # Settings → Developers: your install snippet, or "Your actor ID" (see the hook README)
 ```
 
+*(Corrected 2026-10-05, NAGT-379: the comment above named only the install snippet. Settings → Developers also shows the signed-in user's own **Your actor ID**, for running the hook yourself, and is shown when the workspace's workflow is Guard or Mixed.)*
+
 ### Subcommands
 
 | Command | Description |
@@ -265,7 +275,13 @@ To skip governance for a session without removing the hook:
 AGENTGOVERN_HOOK_MODE=off claude
 ```
 
-See `packages/claude-hook/README.md` for the full option reference.
+In PowerShell (the variable is removed again when claude exits):
+
+```powershell
+try { $env:AGENTGOVERN_HOOK_MODE='off'; claude } finally { Remove-Item Env:AGENTGOVERN_HOOK_MODE }
+```
+
+`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
 
@@ -277,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.6.0 → agentgovern-2.7.2}/RELEASING.md

@@ -87,3 +87,18 @@ To re-run a publish after a failed run, trigger the workflow manually **from the
   - the wheel's `METADATA` says 2.5.0;
   - 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.
+- **2026-10-04:** 2.6.0 was published by run `37233410794` from tag `sdk-v2.6.0` at `9539eaec` (pushed by Ahmed; Build 20:46:53–20:47:09Z, Publish 20:47:14–20:47:34Z; files uploaded 20:47:29Z and 20:47:31Z). Verified afterwards, read-only:
+  - the wheel and sdist sha256 match PyPI's digests (`be9fb7d5…`, `75016301…`);
+  - the wheel's `METADATA` says `Version: 2.6.0`, `Requires-Python: >=3.10`;
+  - 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.2/agentgovern/_version.py

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