agentgovern 2.2.0__tar.gz → 2.3.0__tar.gz

{agentgovern-2.2.0 → agentgovern-2.3.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.0 → agentgovern-2.3.0}/CHANGELOG.md

@@ -1,5 +1,148 @@
 # Changelog
 
+## 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)
+
+`register_agent()` previously scheduled its HTTP call directly against the
+background thread's event loop, gated on that loop already being confirmed
+running (`if self._loop is not None and self._loop.is_running():`). If
+called before the loop was ready — typically `<100ms` after `init()`, and
+this SDK's own README quickstart calls `register_agent()` on the very next
+line after `init()` — the registration was dropped with nothing queued
+anywhere and no error surfaced. No explicit `register_agent()` call had
+ever landed successfully in any installation of this SDK, for any agent,
+in over three months; every registered-looking agent row was actually the
+ingest route's own auto-provisioning fallback.
+
+- `register_agent()` now enqueues onto a dedicated buffer instead of
+  scheduling directly — the loop-readiness dependency is removed from the
+  call entirely. Drained by a new internal flush routine on the same
+  cadence actions already use.
+- Deduped by `external_id`: calling `register_agent()` more than once for
+  the same agent before a flush collapses to one pending entry with the
+  latest values, matching the server's own always-overwrite upsert
+  behavior, rather than queuing one call per invocation.
+- A failed registration now prints a `stderr` warning after repeated
+  consecutive failures, matching the existing warning behavior for action
+  ingest failures — never raises into the caller, but no longer silent
+  either.
+- `status()` gained two new informational fields:
+  `reg_buffer_size`, `reg_consecutive_failures`.
+- Internal null-strip added to the registration payload before
+  serialization, generalizing the same fix already applied to action
+  ingest (`_post_batch`) in `0.1.0b4` — Pydantic's `model_dump_json()`
+  sends unset optional fields as explicit JSON `null`; the server's schema
+  treats that as a distinct value from an absent key.
+
+No public API changes — `register_agent()`'s signature is unchanged, and
+every internal addition is private. Patch release: this restores
+previously-documented behavior rather than adding new capability.
+
+Full design and build record: `docs/audit-reports/story-109-register-agent-startup-race-2026-08-13.md`.
+
 ## 2.2.0 — 2026-08-11
 
 ### Fix — capture-only hook events (UserPromptSubmit/PostToolUse/Stop) no longer block on a discarded synchronous verdict; async audit-event parity (NAGT-137)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentgovern
-Version: 2.2.0
+Version: 2.3.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)
@@ -206,8 +195,10 @@ Enable policy packs from the [AgentGovern dashboard](https://agentgovern.zirahn.
 ## 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 +210,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.0 → agentgovern-2.3.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)
@@ -148,8 +152,10 @@ Enable policy packs from the [AgentGovern dashboard](https://agentgovern.zirahn.
 ## 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 +167,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.0 → agentgovern-2.3.0}/RELEASING.md

@@ -11,15 +11,17 @@ Before the first automated publish, configure trusted publishing on PyPI:
 
    | Field             | Value                        |
    |-------------------|------------------------------|
-   | Owner             | ahmedkhan-zirahn             |
+   | 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:
-- Go to https://github.com/ahmedkhan-zirahn/agentgovern/settings/environments
+- Go to https://github.com/ZirahnAI/agentgovern/settings/environments
 - Create environment named `pypi` (no protection rules required)
 
 ## Release steps
@@ -53,7 +55,7 @@ Also create the `pypi` environment in GitHub:
 
 If you need to publish without tagging (e.g., to re-publish after a failed run), trigger the workflow manually:
 
-1. Go to https://github.com/ahmedkhan-zirahn/agentgovern/actions/workflows/publish-sdk.yml
+1. Go to https://github.com/ZirahnAI/agentgovern/actions/workflows/publish-sdk.yml
 2. Click **Run workflow** → select branch `main` → **Run workflow**
 
 The manual run builds and publishes whatever version is currently in `packages/sdk-python/pyproject.toml`. Make sure the version in `pyproject.toml` and `_version.py` match before triggering.

{agentgovern-2.2.0 → agentgovern-2.3.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.
@@ -110,7 +152,8 @@ def init(
         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.
+        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.3.0/agentgovern/_version.py

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