agentgovern 2.2.1__tar.gz → 2.4.0__tar.gz

{agentgovern-2.2.1 → agentgovern-2.4.0}/.gitignore

@@ -32,6 +32,13 @@ test-results/
 # Not project config — skills/ and agents/ under .claude/ remain tracked.
 .claude/settings.json
 .claude/settings.local.json
+# Backups of the above, which carry the same content and the same reason to stay
+# untracked. Added 2026-08-21: the exact-filename rules above do not match a
+# `.bak-*` sibling, so a pre-change backup sat untracked-but-not-ignored inside
+# the repo, where a `git add -A` would have staged it — and, with both `ask`
+# arrays now empty, without prompting.
+.claude/settings.json.bak-*
+.claude/settings.local.json.bak-*
 
 .vercel
 

{agentgovern-2.2.1 → agentgovern-2.4.0}/CHANGELOG.md

@@ -1,5 +1,133 @@
 # Changelog
 
+## 2.4.0 — release date is the `sdk-v2.4.0` tag's (prepared 2026-09-30)
+
+### Change — the SDK reaches the policy engine at a stable name, `https://engine.zirahn.com`
+
+`evaluate_input()` (Gate 1) and Gate 2's output checks call the policy engine
+directly. **Versions 2.3.0 and earlier call it at
+`https://agentgovern.onrender.com`, a hostname Render issued for one specific
+service.** Render cannot move a service to another region: a new service
+means a new hostname. So an SDK pinned to that name cannot follow the engine
+if it moves.
+
+- The default `policy_engine_url` is now **`https://engine.zirahn.com`**. It
+  is a custom domain pointing at the same engine today, so **latency and
+  behaviour are unchanged**. What changes is that a future move of the engine
+  needs no SDK release.
+- **2.3.0 and earlier keep working.** `agentgovern.onrender.com` still
+  serves the same engine, and it will not be removed while any supported
+  version defaults to it. Upgrading moves you to the stable name:
+  `pip install --upgrade agentgovern`.
+- **Overrides are unchanged.** The `policy_engine_url` argument to `init()`,
+  then the `AGENTGOVERN_POLICY_ENGINE_URL` environment variable, still take
+  precedence over the default. **If you set either yourself, you are not
+  affected.**
+- The Claude Code hook is unaffected. It reaches the engine through the
+  dashboard's API, not directly.
+
+## 2.3.0 — release date is the `sdk-v2.3.0` tag's (prepared 2026-09-29)
+
+### Security — the Claude Code hook now sees every tool call, but only after you reinstall it (NAGT-187)
+
+Until this release, `agentgovern hook install` registered the hook for a fixed
+list of tools (ten in 2.2.1: `Bash`, `Write`, `Edit`, `MultiEdit`,
+`NotebookEdit`, `Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`). **A tool call
+through any other tool never reached the hook, so no policy was applied to
+it.** On Windows, Claude Code's `PowerShell` tool was one such tool: every
+content rule could be bypassed by routing a command through it.
+
+- The `PreToolUse` and `PostToolUse` matchers are now `*`: every tool,
+  including tools that do not exist yet.
+- `PowerShell` is classified like `Bash` (`execute` / `code_execution`).
+- A tool the hook has no classification for is recorded as
+  `action_type="unmapped_tool"`. Before, it was recorded as `"custom"`, the
+  value the SDK reserves for your own `track_action()` calls. **A policy that
+  relied on `"custom"` as a catch-all for unknown tools needs
+  `"unmapped_tool"` added.**
+- The bundled hook script is version 2.3.0.
+
+> **Action required for existing installs.** Upgrading the package does not
+> change a hook that is already installed. Until you reinstall it, the hook
+> keeps its old tool list:
+>
+> ```bash
+> pip install --upgrade agentgovern
+> agentgovern hook install --force   # repeat --capture-mode=minimal, --matcher or --python-command if you used them
+> agentgovern hook status            # no [DRIFT] lines once it is current
+> ```
+>
+> Then restart any running Claude Code session. `--force` writes the current
+> defaults and does not remember options from the earlier install, so pass
+> them again. Without `--capture-mode=minimal`, it turns a minimal install
+> into a full one.
+
+### Change — `hook install` tells you when an existing hook is stale (NAGT-200)
+
+Before, running `agentgovern hook install` against an existing hook said
+*"already installed"*, even when that hook was out of date. It now adds which
+matcher, timeout or script version differs from what this package would
+write, and says to re-run with `--force`. **It still does not upgrade the
+hook itself.** The exit code and every refusal are unchanged, and `--force`
+is still required to write anything.
+
+### Fix — `httpx` and `pydantic` are now required dependencies (NAGT-324)
+
+`pip install agentgovern` installed no dependencies at all. The package
+imported cleanly, but 13 of its 23 public names, including `ActionType`,
+`ActionStatus` and `AgentGovernClient`, were bound to `None`. `init()` raised
+a clear `ImportError`, so any documented integration failed loudly at
+startup. But `register_agent()`, `track_action()` and `shutdown()` return
+silently when the SDK is uninitialised, so an integration that skipped or
+swallowed `init()` recorded nothing and reported nothing.
+
+This affected every release from 0.2.0 through 2.2.1. LangChain and LangGraph
+users were unaffected in practice: `langchain-core` depends on both `httpx`
+and `pydantic`, so those extras' own dependencies supplied them.
+
+- `httpx>=0.27.0` and `pydantic>=2.10.0` are now unconditional dependencies.
+  A bare install now also brings in their own dependencies: `anyio`,
+  `certifi`, `h11`, `httpcore`, `idna`, `pydantic-core`, `annotated-types`,
+  `typing-extensions` and `typing-inspection`.
+- **`python-dotenv` is removed.** No module in the package ever imported it.
+  If you relied on `agentgovern[sdk]` to install it, add it directly.
+- The `[sdk]` extra is kept, now empty, so `pip install "agentgovern[sdk]"`,
+  `[langchain]` and `[langgraph]` keep working unchanged, with no pip warning.
+- The import guard still catches any `ImportError`, so the hook CLI keeps
+  working in a `pip install --no-deps` or half-installed environment. **What
+  changed is the message:** `init()` now reports the error that actually
+  occurred. Before, it always told you to install the `[sdk]` extra, even
+  when that extra was already installed and something else had failed.
+- `init()`'s docstring now says what the fail-silent promise covers
+  (AgentGovern being *unreachable* once initialised). It also says what it
+  does not cover (the SDK being absent or misconfigured), and why `init()`
+  should not be wrapped in a bare `except`.
+
+### Docs
+
+- The LangChain samples in this README are updated for langchain 1.x, which
+  removed `AgentExecutor` and `create_openai_tools_agent`. They now use
+  `langchain.agents.create_agent` and pass the handler as
+  `config={"callbacks": [handler]}`. A new test runs such an agent and
+  confirms the handler's callbacks fire.
+- New README section: *Upgrading an existing install*.
+
+### Internal (not part of the installed package)
+
+- A new release gate: the wheel is built, its declared dependencies are
+  checked, and it is installed into a clean environment and imported before
+  it is uploaded. This runs on every pull request and in the publish workflow
+  itself.
+- `langchain>=1.0.0` added to the `dev` extra, for the new test.
+- Test fixes that make the suite trustworthy rather than change behaviour:
+  - NAGT-280: a test that pinned the hook version to the stale literal
+    `2.1.0` is removed; the test that checks the snapshot against the
+    module's own version stays;
+  - NAGT-326: Stop-hook tests no longer assume the temp directory is inside
+    `$HOME`;
+  - NAGT-327: the buffer-cap test is deterministic, with no live flush thread
+    and no network.
+
 ## 2.2.1 — 2026-08-13
 
 ### Fix — `register_agent()` silently no-op'd when called immediately after `init()`, the SDK's own documented call pattern (STORY-109)

{agentgovern-2.2.1 → agentgovern-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentgovern
-Version: 2.2.1
+Version: 2.4.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
@@ -20,40 +20,25 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Monitoring
 Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.10.0
 Provides-Extra: crewai
 Requires-Dist: crewai>=0.80.0; extra == 'crewai'
-Requires-Dist: httpx>=0.27.0; extra == 'crewai'
-Requires-Dist: pydantic>=2.10.0; extra == 'crewai'
-Requires-Dist: python-dotenv>=1.0.0; extra == 'crewai'
 Provides-Extra: dev
-Requires-Dist: httpx>=0.27.0; extra == 'dev'
-Requires-Dist: pydantic>=2.10.0; extra == 'dev'
+Requires-Dist: langchain>=1.0.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
 Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
 Requires-Dist: pytest>=8.3.0; extra == 'dev'
-Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
 Requires-Dist: respx>=0.21.0; extra == 'dev'
 Requires-Dist: ruff>=0.8.0; extra == 'dev'
 Provides-Extra: langchain
-Requires-Dist: httpx>=0.27.0; extra == 'langchain'
 Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
-Requires-Dist: pydantic>=2.10.0; extra == 'langchain'
-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<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
-Requires-Dist: httpx>=0.27.0; extra == 'openai'
 Requires-Dist: openai>=1.50.0; extra == 'openai'
-Requires-Dist: pydantic>=2.10.0; extra == 'openai'
-Requires-Dist: python-dotenv>=1.0.0; extra == 'openai'
 Provides-Extra: sdk
-Requires-Dist: httpx>=0.27.0; extra == 'sdk'
-Requires-Dist: pydantic>=2.10.0; extra == 'sdk'
-Requires-Dist: python-dotenv>=1.0.0; extra == 'sdk'
 Description-Content-Type: text/markdown
 
 # AgentGovern Python SDK
@@ -74,7 +59,7 @@ pip install "agentgovern[langchain]"
 
 ```python
 import agentgovern
-from langchain.agents import AgentExecutor, create_openai_tools_agent
+from langchain.agents import create_agent
 from langchain_openai import ChatOpenAI
 
 # 1. Initialize once at startup
@@ -94,12 +79,13 @@ agentgovern.register_agent(
 # 3. Get the callback handler — binds to credit-scoring-v2 automatically
 handler = agentgovern.instrument_langchain()
 
-# 4. Pass it to your AgentExecutor — no other changes needed
-llm = ChatOpenAI(model="gpt-4o")
-agent = create_openai_tools_agent(llm, tools, prompt)
-executor = AgentExecutor(agent=agent, tools=tools, callbacks=[handler])
+# 4. Build the agent and pass the handler via config — no other changes needed
+agent = create_agent(model=ChatOpenAI(model="gpt-4o"), tools=tools)
 
-result = executor.invoke({"input": "Evaluate loan application for customer #12345"})
+result = agent.invoke(
+    {"messages": [{"role": "user", "content": "Evaluate loan application for customer #12345"}]},
+    config={"callbacks": [handler]},
+)
 ```
 
 `instrument_langchain()` binds to the most recently registered agent. Every tool call,
@@ -154,8 +140,11 @@ agentgovern.register_agent("kyc-agent", name="KYC Agent")
 handler_fraud = agentgovern.instrument_langchain("fraud-detector")
 handler_kyc   = agentgovern.instrument_langchain("kyc-agent")
 
-fraud_executor = AgentExecutor(agent=..., tools=..., callbacks=[handler_fraud])
-kyc_executor   = AgentExecutor(agent=..., tools=..., callbacks=[handler_kyc])
+fraud_agent = create_agent(model=..., tools=...)
+kyc_agent   = create_agent(model=..., tools=...)
+
+fraud_agent.invoke(inputs, config={"callbacks": [handler_fraud]})
+kyc_agent.invoke(inputs, config={"callbacks": [handler_kyc]})
 ```
 
 ## Manual instrumentation (all frameworks)
@@ -201,13 +190,22 @@ Enable policy packs from the [AgentGovern dashboard](https://agentgovern.zirahn.
 | `api_key` | required | SDK ingest key from the dashboard |
 | `base_url` | `https://agentgovern.zirahn.com` | API endpoint |
 | `environment` | `"production"` | `"production"` \| `"staging"` \| `"development"` |
+| `policy_engine_url` | `https://engine.zirahn.com` | Policy engine endpoint for Gate 1 (`evaluate_input`) and Gate 2 checks. Override with this argument or the `AGENTGOVERN_POLICY_ENGINE_URL` env var |
 | `fail_silently` | `True` | If `True`, SDK errors never raise into your agent |
 
+**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`.
+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 and enforces your tenant policies in real time — before any
-write-class tool (`Bash`, `Write`, `Edit`, `MultiEdit`, `NotebookEdit`) executes.
+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.
 
 ### Install
 
@@ -219,6 +217,29 @@ This deploys the hook script to `~/.agentgovern/hook.py`, merges the correct ent
 `~/.claude/settings.json` (with an atomic backup), and prints instructions for any missing
 env vars.
 
+### Upgrading an existing install
+
+Upgrading the package does **not** update a hook that is already installed. `hook install`
+copies the hook script to `~/.agentgovern/hook.py` and writes its entries into
+`~/.claude/settings.json`, and a plain `agentgovern hook install` against an existing install
+reports it as already installed and changes nothing. After upgrading, reinstall with `--force`:
+
+```bash
+pip install --upgrade agentgovern     # or the extra you installed with, e.g. "agentgovern[langchain]"
+agentgovern hook install --force
+agentgovern hook status               # reports no [DRIFT] lines once the hook is current
+```
+
+`--force` writes the current defaults. It does not remember options from the earlier install: if
+you installed with `--capture-mode=minimal`, `--matcher` or `--python-command`, pass them again —
+`--force` without `--capture-mode=minimal` turns a minimal install into a full one.
+Your environment variables are not touched. Restart any running Claude Code session afterwards.
+
+**If your hook was installed by 2.2.1 or earlier, this step matters for coverage, not just
+freshness.** Those versions wrote a `PreToolUse` matcher naming a fixed list of tools (ten, in 2.2.1), so a call
+through any other tool (`PowerShell`, for example) never reached the hook. Starting with 2.3.0
+the matcher is `*`, every tool — but only once `hook install --force` has rewritten the entry.
+
 ### Required env vars
 
 ```bash

{agentgovern-2.2.1 → agentgovern-2.4.0}/README.md

@@ -16,7 +16,7 @@ pip install "agentgovern[langchain]"
 
 ```python
 import agentgovern
-from langchain.agents import AgentExecutor, create_openai_tools_agent
+from langchain.agents import create_agent
 from langchain_openai import ChatOpenAI
 
 # 1. Initialize once at startup
@@ -36,12 +36,13 @@ agentgovern.register_agent(
 # 3. Get the callback handler — binds to credit-scoring-v2 automatically
 handler = agentgovern.instrument_langchain()
 
-# 4. Pass it to your AgentExecutor — no other changes needed
-llm = ChatOpenAI(model="gpt-4o")
-agent = create_openai_tools_agent(llm, tools, prompt)
-executor = AgentExecutor(agent=agent, tools=tools, callbacks=[handler])
+# 4. Build the agent and pass the handler via config — no other changes needed
+agent = create_agent(model=ChatOpenAI(model="gpt-4o"), tools=tools)
 
-result = executor.invoke({"input": "Evaluate loan application for customer #12345"})
+result = agent.invoke(
+    {"messages": [{"role": "user", "content": "Evaluate loan application for customer #12345"}]},
+    config={"callbacks": [handler]},
+)
 ```
 
 `instrument_langchain()` binds to the most recently registered agent. Every tool call,
@@ -96,8 +97,11 @@ agentgovern.register_agent("kyc-agent", name="KYC Agent")
 handler_fraud = agentgovern.instrument_langchain("fraud-detector")
 handler_kyc   = agentgovern.instrument_langchain("kyc-agent")
 
-fraud_executor = AgentExecutor(agent=..., tools=..., callbacks=[handler_fraud])
-kyc_executor   = AgentExecutor(agent=..., tools=..., callbacks=[handler_kyc])
+fraud_agent = create_agent(model=..., tools=...)
+kyc_agent   = create_agent(model=..., tools=...)
+
+fraud_agent.invoke(inputs, config={"callbacks": [handler_fraud]})
+kyc_agent.invoke(inputs, config={"callbacks": [handler_kyc]})
 ```
 
 ## Manual instrumentation (all frameworks)
@@ -143,13 +147,22 @@ Enable policy packs from the [AgentGovern dashboard](https://agentgovern.zirahn.
 | `api_key` | required | SDK ingest key from the dashboard |
 | `base_url` | `https://agentgovern.zirahn.com` | API endpoint |
 | `environment` | `"production"` | `"production"` \| `"staging"` \| `"development"` |
+| `policy_engine_url` | `https://engine.zirahn.com` | Policy engine endpoint for Gate 1 (`evaluate_input`) and Gate 2 checks. Override with this argument or the `AGENTGOVERN_POLICY_ENGINE_URL` env var |
 | `fail_silently` | `True` | If `True`, SDK errors never raise into your agent |
 
+**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`.
+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 and enforces your tenant policies in real time — before any
-write-class tool (`Bash`, `Write`, `Edit`, `MultiEdit`, `NotebookEdit`) executes.
+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.
 
 ### Install
 
@@ -161,6 +174,29 @@ This deploys the hook script to `~/.agentgovern/hook.py`, merges the correct ent
 `~/.claude/settings.json` (with an atomic backup), and prints instructions for any missing
 env vars.
 
+### Upgrading an existing install
+
+Upgrading the package does **not** update a hook that is already installed. `hook install`
+copies the hook script to `~/.agentgovern/hook.py` and writes its entries into
+`~/.claude/settings.json`, and a plain `agentgovern hook install` against an existing install
+reports it as already installed and changes nothing. After upgrading, reinstall with `--force`:
+
+```bash
+pip install --upgrade agentgovern     # or the extra you installed with, e.g. "agentgovern[langchain]"
+agentgovern hook install --force
+agentgovern hook status               # reports no [DRIFT] lines once the hook is current
+```
+
+`--force` writes the current defaults. It does not remember options from the earlier install: if
+you installed with `--capture-mode=minimal`, `--matcher` or `--python-command`, pass them again —
+`--force` without `--capture-mode=minimal` turns a minimal install into a full one.
+Your environment variables are not touched. Restart any running Claude Code session afterwards.
+
+**If your hook was installed by 2.2.1 or earlier, this step matters for coverage, not just
+freshness.** Those versions wrote a `PreToolUse` matcher naming a fixed list of tools (ten, in 2.2.1), so a call
+through any other tool (`PowerShell`, for example) never reached the hook. Starting with 2.3.0
+the matcher is `*`, every tool — but only once `hook install --force` has rewritten the entry.
+
 ### Required env vars
 
 ```bash

agentgovern-2.4.0/RELEASING.md

@@ -0,0 +1,72 @@
+# Releasing agentgovern to PyPI
+
+Releases are automated via `.github/workflows/publish-sdk.yml` using PyPI trusted publishing (OIDC — no API tokens needed). Pushing a `sdk-v*` tag triggers a build and publish automatically.
+
+## Prerequisites (one-time PyPI setup)
+
+Before the first automated publish, configure trusted publishing on PyPI:
+
+1. Go to https://pypi.org/manage/project/agentgovern/settings/publishing/
+2. Add a new trusted publisher with these exact values:
+
+   | Field             | Value                        |
+   |-------------------|------------------------------|
+   | Owner             | ZirahnAI                     |
+   | Repository name   | agentgovern                  |
+   | Workflow filename | publish-sdk.yml              |
+   | Environment name  | pypi                         |
+
+   **Note:** the repository moved from `ahmedkhan-zirahn` to `ZirahnAI` in September 2026. A publisher for the old owner existed and was **deleted on 2026-09-14**. A trusted publisher that names a path the organisation no longer controls is a standing binding to a namespace someone else could later claim. See NAGT-314 in `docs/ROADMAP.md`.
+
+3. Save. No API token needed after this.
+
+Also create the `pypi` environment in GitHub, and restrict it to release tags:
+- Go to https://github.com/ZirahnAI/agentgovern/settings/environments
+- Create the environment named `pypi`.
+- Under **Deployment branches and tags**, choose **Selected branches and tags** and add a **tag** rule `sdk-v*`. The publish job carries `environment: pypi`, so it can only run from an `sdk-v*` tag.
+- **Required reviewers is not available here.** GitHub offers it for environments in private repositories only on Enterprise, and this repository is private on the Team plan (operator-confirmed 2026-09-30). So the publish does not pause for approval. **Pushing the tag is the release decision.**
+- Optionally, add a repository **tag ruleset** on `refs/tags/sdk-v*` that restricts creation to admins. One named "sdk release tags" exists. It was **not enforced** when checked on 2026-09-30, so it has no effect until its enforcement is set to Active.
+
+Check the environment with `gh api repos/ZirahnAI/agentgovern/environments/pypi/deployment-branch-policies`, which should list `{"name": "sdk-v*", "type": "tag"}`.
+
+## Release steps
+
+1. **Bump the version** in two places:
+   ```
+   packages/sdk-python/agentgovern/_version.py   → __version__ = "0.X.Y"
+   packages/sdk-python/pyproject.toml             → version = "0.X.Y"
+   ```
+
+2. **Add a CHANGELOG entry** (if `CHANGELOG.md` exists) describing what changed.
+
+3. **Commit the version bump:**
+   ```bash
+   git add packages/sdk-python/agentgovern/_version.py packages/sdk-python/pyproject.toml
+   git commit -m "chore(sdk): bump version to 0.X.Y"
+   git push
+   ```
+
+4. **Tag the merged commit and push that one tag.** Never `git push --tags`, which pushes every local tag, and any stray `sdk-v*` among them would publish:
+   ```bash
+   git fetch origin
+   git tag sdk-v0.X.Y <merged-commit-sha>
+   git push origin sdk-v0.X.Y
+   ```
+
+   The `publish-sdk.yml` workflow triggers on the tag push. It builds, checks the wheel's declared dependencies, installs that exact wheel in a clean venv, and then publishes to PyPI. **There is no approval step** (see above). PyPI never accepts a version twice, so a mistaken tag uses up that version for good.
+
+5. **Verify** at https://pypi.org/project/agentgovern/ — the new version should appear within a few minutes.
+
+## Manual fallback (workflow_dispatch)
+
+To re-run a publish after a failed run, trigger the workflow manually **from the release tag**:
+
+1. Go to https://github.com/ZirahnAI/agentgovern/actions/workflows/publish-sdk.yml
+2. Click **Run workflow**, choose the **tag** `sdk-v0.X.Y` under "Use workflow from", then **Run workflow**.
+
+**A run dispatched from `main` (or any branch) cannot publish.** Its build job runs, but the publish job targets the `pypi` environment, which only accepts `sdk-v*` tags. That comes from the environment restriction above, per GitHub's documented behaviour; it has not been tested by dispatching from `main`. The run publishes whatever version `pyproject.toml` says at that ref.
+
+## Trusted-publisher history
+
+- **2026-09-14:** run `34876650141` (dispatched from `main`) authenticated through the `ZirahnAI/agentgovern` publisher. PyPI then refused to re-upload 2.2.1 (`400 File already exists`), so the run's conclusion was `failure`.
+- **2026-09-30:** 2.3.0 was the first version published end to end from the `ZirahnAI` repository, by run `36667118357` from tag `sdk-v2.3.0`.

{agentgovern-2.2.1 → agentgovern-2.4.0}/agentgovern/__init__.py

@@ -29,9 +29,23 @@ from typing import Any
 
 from agentgovern._version import __version__
 
-# SDK deps (httpx, pydantic) are optional — required only for agent SDK usage.
-# The hook CLI (agentgovern hook install/...) works with a bare install.
-# Install with: pip install agentgovern[sdk]
+# httpx and pydantic are REQUIRED dependencies (NAGT-324). A normal
+# `pip install agentgovern` always has them, so this guard is not the
+# optional-extra switch it used to be.
+#
+# It still exists for one case: an install that deliberately suppressed
+# dependency resolution (`pip install --no-deps`), or one that is broken or
+# half-finished. In those, the Claude Code hook CLI -- which is stdlib-only
+# all the way down -- must keep working, and it cannot, because importing
+# `agentgovern.__main__` imports THIS module first.
+#
+# The catch stays BROAD on purpose. Narrowing it to `_exc.name in ("httpx",
+# "pydantic")` was tried and withdrawn: ImportError.name is the INNERMOST
+# missing module, so a broken `pydantic_core` (a compiled wheel, and one of
+# pydantic's most common real failures) reports 'pydantic_core', gets
+# re-raised, and takes the hook CLI down in exactly the case this guard is
+# for. What was actually wrong was the DIAGNOSTIC, not the breadth -- so the
+# exception is recorded and `_require_sdk()` reports what really happened.
 try:
     from agentgovern.client import AgentGovernClient
     from agentgovern.exceptions import (
@@ -51,8 +65,10 @@ try:
     )
 
     _SDK_AVAILABLE = True
-except ImportError:
+    _SDK_IMPORT_ERROR: ImportError | None = None
+except ImportError as _exc:
     _SDK_AVAILABLE = False
+    _SDK_IMPORT_ERROR = _exc
     # Provide placeholder names so `from agentgovern import X` fails at call
     # time with a clear message rather than at import time.
     AgentGovernClient = None  # type: ignore[assignment,misc]
@@ -71,12 +87,29 @@ except ImportError:
 
 
 def _require_sdk() -> None:
+    """Raise if the SDK half of this package could not be imported.
+
+    The message is derived from the exception actually raised, never assumed.
+    Before NAGT-324 this always said "install agentgovern[sdk]", which was
+    wrong whenever the real cause was anything else -- it told people to
+    install a dependency that was, in those cases, already installed.
+    """
     if not _SDK_AVAILABLE:
+        _missing = getattr(_SDK_IMPORT_ERROR, "name", None)
+        if _missing in ("httpx", "pydantic"):
+            raise ImportError(
+                f"The AgentGovern SDK requires {_missing}, which is not "
+                f"importable. It is a declared dependency, so this usually "
+                f"means the install skipped dependency resolution "
+                f"(pip install --no-deps) or is incomplete. Reinstall with: "
+                f"pip install --force-reinstall agentgovern"
+            ) from _SDK_IMPORT_ERROR
         raise ImportError(
-            "The AgentGovern SDK requires additional dependencies. "
-            "Install them with: pip install agentgovern[sdk]\n"
-            "The hook CLI (agentgovern hook install) works without this extra."
-        )
+            f"The AgentGovern SDK failed to load: {_SDK_IMPORT_ERROR!r}. "
+            f"This is NOT a missing optional extra -- the installation is "
+            f"broken or incomplete. Reinstall with: "
+            f"pip install --force-reinstall agentgovern"
+        ) from _SDK_IMPORT_ERROR
 
 
 _client: AgentGovernClient | None = None
@@ -100,8 +133,17 @@ def init(
     Initialize the AgentGovern SDK.
 
     Must be called once at application startup before any other SDK calls.
-    The SDK is designed to never break the customer's agent — if AgentGovern
-    is unreachable, all errors are silently discarded.
+
+    The fail-silent contract covers AgentGovern being UNREACHABLE: once the
+    SDK is initialised, network errors, timeouts and policy-engine failures
+    are discarded rather than raised into your agent.
+
+    It does NOT cover AgentGovern being absent or misconfigured. This function
+    raises if the SDK's dependencies cannot be imported, and it is the only
+    place that failure is reported — do not wrap this call in a bare
+    ``except``. If it raises, the SDK is not installed correctly and no action
+    will be recorded; ``status()`` returns ``{"initialized": False}`` for as
+    long as that is true.
 
     Args:
         api_key: SDK ingest key from the dashboard.
@@ -109,8 +151,9 @@ def init(
         base_url: Vercel deployment URL (action ingest + agent registration).
         policy_engine_url: Render policy engine URL (Gate 1 evaluate/input).
             Defaults to ``AGENTGOVERN_POLICY_ENGINE_URL`` env var, then
-            ``https://agentgovern.onrender.com``.
-        fail_silently: If ``True``, SDK errors never raise into your agent.
+            ``https://engine.zirahn.com``.
+        fail_silently: If ``True``, SDK errors never raise into your agent,
+            after initialisation. It does not affect this function.
     """
     _require_sdk()
     global _client  # noqa: PLW0603

agentgovern-2.4.0/agentgovern/_version.py

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

{agentgovern-2.2.1 → agentgovern-2.4.0}/agentgovern/client.py

@@ -53,6 +53,13 @@ def _iso_timestamp_utc(dt: datetime | None = None) -> str:
     return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}Z"
 
 
+# The policy engine's stable name. SDK <= 2.3.0 defaulted to the Render-issued
+# hostname https://agentgovern.onrender.com, which names one Render service and
+# cannot follow the engine to a new one (Render cannot change a service's
+# region: docs/audit-reports/engine-region-move-phase1-2026-09-30.md). A custom
+# domain can be re-pointed, so a future engine move needs no SDK release.
+DEFAULT_POLICY_ENGINE_URL = "https://engine.zirahn.com"
+
 _FLUSH_INTERVAL = 1.0  # seconds between automatic flushes
 _BATCH_SIZE = 100  # flush early when buffer hits this
 _BUFFER_MAXLEN = 10_000  # drop oldest when full
@@ -107,7 +114,7 @@ class AgentGovernClient:
         self.policy_engine_url = (
             policy_engine_url
             or os.environ.get("AGENTGOVERN_POLICY_ENGINE_URL")
-            or "https://agentgovern.onrender.com"
+            or DEFAULT_POLICY_ENGINE_URL
         ).rstrip("/")
         self.fail_silently = fail_silently
         self.batch_size = batch_size