agentgovern 2.7.2__tar.gz → 2.8.0__tar.gz

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

@@ -1,5 +1,66 @@
 # Changelog
 
+## 2.8.0 — release date is the `sdk-v2.8.0` tag's (prepared 2026-10-29)
+
+**New: `agentgovern setup` and `agentgovern remove`, so Guard's install snippet can be four short lines (NAGT-557).** The dependencies and the Python requirement (3.10 or later) are unchanged. `agentgovern hook install` and its flags are unchanged, so install snippets copied before this release keep working with it.
+
+**This release also bundles Claude Code hook 2.5.2** (it was 2.5.1; NAGT-554). With `AGENTGOVERN_FAIL_ACTION=deny` and AgentGovern unreachable, hook 2.5.1 could run past the 6 seconds Claude Code gives it (6.3–6.9 s measured with events queued to resend), and Claude Code then ran the tool call unchecked. In hook 2.5.2 a `PreToolUse` no longer first resends queued events (the other events still do), and its check is given only what is left of 5 seconds from when the hook's code starts, including a name lookup that never answers, so the verdict is printed in time. `AGENTGOVERN_HOOK_TIMEOUT_MS` above that is capped on `PreToolUse`. `agentgovern hook install` takes its 6-second timeout from the bundled hook; the value it writes is unchanged. **Upgrading the package doesn't change an installed hook:** `agentgovern hook install --force` moves an existing install to 2.5.2 (`agentgovern setup` does too, since it installs with `--force`). With the default (`allow`), a call that gets no answer still goes ahead; what changes is how long a `PreToolUse` waits, and that it no longer resends queued events first.
+
+### `agentgovern setup --actor-user-id <id>`
+
+What the install snippet used to do after `pip install`, in order:
+
+1. **Checks the developer id**, then **asks for the API key** without showing it as you paste, so the key is never in the snippet or your shell's history. A shorter value, such as the key reference, is refused and asked again (three tries). If `AGENTGOVERN_API_KEY` already holds a whole key, Return keeps it. Without a terminal (a scripted install, including stdin from `NUL` on Windows), it reads `AGENTGOVERN_API_KEY` instead. Nothing is saved until both checks pass.
+2. **Checks both with AgentGovern** (`POST /api/v1/ingest/heartbeat`). A refused key, or a developer id that isn't in the key's organization, stops here with nothing saved. If AgentGovern can't be reached, setup goes on and says that until it can, Guard lets tool calls run unchecked, or blocks them instead if `AGENTGOVERN_FAIL_ACTION=deny` is set (unless `AGENTGOVERN_HOOK_MODE=off`). It refuses an `AGENTGOVERN_API_URL` that isn't https, other than plain http to `localhost`, `127.0.0.1` or `::1`, and follows no redirect, so the key goes nowhere else.
+3. **Saves both settings for new terminals**: on macOS and Linux, the same two lines ending in `# added by AgentGovern Guard`, in the profile of the shell you ran it from (`${ZDOTDIR:-~}/.zshrc` for zsh, `~/.bash_profile` for bash on macOS, `~/.bashrc` on Linux; `--profile` to choose). Running it again replaces them. On Windows, the two user environment variables.
+4. **Installs the hook** with the Python running setup, by absolute path, replacing only Guard's own entry.
+
+It ends with **"Done. Open a new terminal, then start Claude Code."** It can't change the terminal it runs in. `agentgovern setup --check` re-runs only step 2, with the current terminal's settings.
+
+### `agentgovern remove`
+
+Removes the hook entry, Guard's profile lines (from every profile the install could have used) or user variables, and Guard's files under `~/.agentgovern` (then the folder, only if it is empty). It doesn't delete `~/.venvs/agentgovern`, which it runs from; the uninstall line does that afterwards. It also removes an install made by an older snippet.
+
+### Security — `agentgovern hook test` no longer sends your API key to an unsafe `AGENTGOVERN_API_URL` (NAGT-559)
+
+- **Before:** `hook install` and `hook test` checked the URL by its first characters, so `http://localhost.example.com` and `http://localhost@example.com` (whose host is `example.com`) counted as this machine. `hook test` warned on an unsafe URL and sent the key anyway.
+- **Now:** one parsed check for `hook install`, `hook test` and `setup`: https, or plain http to `localhost`, `127.0.0.1` or `[::1]`, with no `user@` before the host. `hook test` refuses any other URL and sends nothing; `hook install` warns, as before. Plain http to a LAN or Docker host now fails `hook test`.
+
+### Fix — Gate 2 evaluates an output over the policy engine's 256 KB limit, instead of the engine refusing it (NAGT-545)
+
+- **Before:** an output whose Gate 2 request was over the engine's 256 KB body limit got a 413 and was never evaluated. With `gate_2_failure_mode="fail_closed"` it was blocked; otherwise it was allowed unchecked.
+- **Now:** the output and metadata are cut to fit (every string over one length is cut to it, keeping its start; keys, numbers and short strings are kept), and the part that fits is evaluated. `VerdictResult.partial`, or `.partial` on `OutputBlocked` / `OutputEscalated`, says so, with sizes only.
+- **A block, escalate or redact found in that part raises.** A redact blocks rather than redacts, since it can't be applied to the whole output. When no policy applies, the output is allowed, as it would be whole. Anything else is unchecked: `fail_closed` blocks it, as before; otherwise it is allowed.
+- **Not changed:** an output under the limit is sent byte for byte as before. Warn mode never raises. LangGraph's own 64 K-character cut of graph output is unchanged.
+
+### Fix — Gate 1 checks completion-style LLMs, and the newest input (NAGT-555)
+
+- **Completion-style (non-chat) LLMs are now checked by Gate 1** in the LangChain and LangGraph integrations, through `on_llm_start`, with the same blocking and fail-open behaviour as chat models. Before, they were never checked. With the default `auto_evaluate_input=True`, such a call now makes a synchronous Gate 1 request (5-second timeout) before the model runs, and an Enforce policy can stop it.
+- **Gate 1 now checks the last 4,000 characters of a call's input instead of the first 4,000.** In a longer conversation the first 4,000 were the system prompt and early history, so the newest message went unchecked. Now the newest message is checked, with as much history before it as fits; anything earlier is not checked in that call. A Gate 1 request is no larger than before.
+- If you subclassed the handler and overrode `on_llm_start`, chat calls no longer pass through it.
+
+## 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentgovern
-Version: 2.7.2
+Version: 2.8.0
 Summary: Compliance-as-code middleware for agentic AI workflows.
 Project-URL: Homepage, https://agentgovern.zirahn.com
 Project-URL: Support, https://zirahn.com/contact
@@ -66,7 +66,7 @@ from langchain_openai import ChatOpenAI
 agentgovern.init(
     api_key="ag_prod_...",           # from https://agentgovern.zirahn.com/settings/api-keys
     base_url="https://agentgovern.zirahn.com",
-    environment="development",       # "production" | "staging" | "development"
+    environment="production",        # your API key's environment: "production" | "staging" | "development"
 )
 
 # 2. Register your agent
@@ -94,14 +94,15 @@ and visible in the dashboard.
 
 ## Enforcement modes
 
-AgentGovern supports four enforcement modes per policy:
+AgentGovern supports five enforcement modes per policy:
 
 | Mode     | Behavior                                                   |
 |----------|------------------------------------------------------------|
 | warn     | Records the violation; the agent continues                 |
 | log      | Records the violation silently; the agent continues        |
-| disabled | Policy not evaluated                                       |
-| enforce  | Records the violation and **raises** in your code (below)  |
+| alert    | Same as warn today: records the violation; the agent continues |
+| disabled | Still evaluated, and failures are recorded; the agent continues |
+| enforce  | Records the violation, and **raises** in your code where the check runs before the action (below) |
 
 ### What enforce stops, through the LangChain and LangGraph integrations
 
@@ -109,18 +110,60 @@ When an enforce-mode policy blocks, the exception reaches the code that called
 `invoke()`, `ainvoke()`, `stream()` or `astream()`:
 
 - **Gate 1 (input) raises `PolicyViolation` before the model call runs.** This is the
-  control that stops an agent before it acts.
+  control that stops an agent before it acts. By default (`auto_evaluate_input=True`) it
+  runs before every model call the handler sees, chat models and completion-style LLMs
+  alike, and checks the last 4,000 characters of the call's input against your
+  policies' `input` rules: the newest message, and as much history before it as fits.
+  Anything earlier is not checked in that call, and a single message longer than
+  4,000 characters is checked only on its last 4,000.
+  *(Changed in SDK 2.8.0, NAGT-555. Earlier releases checked chat models only, and
+  only the first 4,000 characters, so a long conversation's newest message went
+  unchecked.)*
 - **Gate 2 (output) raises `OutputBlocked` (block) or `OutputEscalated` (escalate)**
-  when the run finishes. Gate 2 stops `invoke()` from **returning** a blocked answer.
+  when the run finishes, if you pass `gate_2_enforcement_mode="enforce"` to
+  `instrument_langchain()` or `instrument_langgraph()`. It is off by default.
+  Gate 2 stops `invoke()` from **returning** a blocked answer.
   **It does not undo anything that already happened:** tool calls have already run, a
   LangGraph checkpointer has already saved the final state, and a `stream()` caller has
   already received the streamed output. On LangChain, a run whose LLM streamed tokens skips the synchronous Gate 2 entirely.
 - **Redact** replaces the answer on LangChain; LangGraph does not apply it.
-
-**What never stops your agent:** warn, log and allow verdicts; AgentGovern being
-unreachable, slow, or returning an error (unless you configured `fail_open=False`, in
-which case Gate 1 raises `GateUnavailable`, or `gate_2_failure_mode="fail_closed"`, in
-which case Gate 2 raises `OutputBlocked`); and any error inside the SDK itself.
+- **An output over the policy engine's 256 KB limit** is cut to fit, and the part that
+  fits is evaluated; the result's `partial` (or the exception's) says so. A block,
+  escalate or redact found in that part raises `OutputBlocked` / `OutputEscalated` (a
+  redact can't be applied to the whole answer). When no policy applies to the action, it
+  is allowed, as it would be whole. Anything else is treated as unchecked: with
+  `gate_2_failure_mode="fail_closed"` it raises `OutputBlocked`, as the engine's refusal
+  did before; otherwise it is allowed. *(SDK 2.8.0, NAGT-545. Before, such an
+  output was never evaluated at all.)* On LangGraph, see the last item below.
+
+**What enforce does not stop:**
+
+- **A tool call.** The SDK does not check a tool call before it runs. A policy on tool
+  calls is evaluated on the recorded action after the tool has run, so in enforce mode
+  it records the failure but cannot prevent the call. (Guard's Claude Code hook, below,
+  does check each tool call before it runs.)
+- **An agent AgentGovern can't find.** Gate 1 allows the call, and records no
+  evaluation, when the agent isn't registered yet or is registered under a different
+  environment from the one `init()` names. `register_agent()` sends the registration in
+  the background, so a new agent's first model calls can pass this way.
+- **An input that also fails a warn, log, alert or disabled policy, until AgentGovern's
+  policy engine is updated (NAGT-555).** Gate 1 acts on the first `input` rule the input
+  fails, and that rule's policy decides. So when an input fails rules in two policies,
+  one set to enforce and one set to warn or disabled, it can be allowed instead of
+  blocked. The engine is updated separately from this SDK; after that update the
+  strictest failing rule decides, whatever SDK version you run.
+- **The rest of a long LangGraph output.** The LangGraph integration cuts the graph's
+  output to its first 65,536 characters before Gate 2 and evaluates that part as if it
+  were the whole output: it is not marked partial, and Gate 2 does not check the rest.
+
+**What never stops your agent:** warn, log, alert and allow verdicts, and any error
+inside the SDK itself. If Gate 1 can't complete its check (AgentGovern can't be reached,
+doesn't answer within 5 seconds, or returns a server error), the model call goes ahead,
+unless you pass `fail_open=False`, which makes Gate 1 raise `GateUnavailable`. A Gate 1
+request AgentGovern refuses (a 4xx, such as a wrong API key) lets the call go ahead
+either way. If Gate 2 can't complete its check, the output is returned, unless you pass
+both `gate_2_enforcement_mode="enforce"` and `gate_2_failure_mode="fail_closed"`, which
+makes Gate 2 raise `OutputBlocked`.
 
 **Pass AgentGovern's handler last.** When an enforce block raises, LangChain can stop
 delivering that event to the handlers after ours in the `callbacks` list (on synchronous
@@ -130,21 +173,42 @@ Put AgentGovern's handler at the end of the list:
 `config={"callbacks": [your_tracer, agentgovern_handler]}`.
 
 **How:** an instrumentor sets LangChain's `raise_error` when an enforce gate is
-configured (Gate 2 `enforce`, or Gate 1 auto-evaluation on), and lets only the three
-verdict exceptions above out of its callbacks.
+configured (Gate 2 `enforce`, or Gate 1 auto-evaluation on), and lets out of its
+callbacks only the three verdict exceptions above and, when you pass `fail_open=False`,
+`GateUnavailable`.
 
 *(Changed in SDK 2.6.0, NAGT-380. Earlier releases recorded enforce-mode violations
 but did not stop the agent: LangChain caught the exception.)*
 
-You can also check input yourself before invoking an agent:
+You can also check input yourself before invoking an agent. `evaluate_input()` raises
+`PolicyViolation` when a policy set to enforce blocks the input, and otherwise returns
+the result:
 
 ```python
-result = agentgovern.evaluate_input(agent_external_id="my-agent", prompt=user_prompt)
-if result.action_taken == "block":
+from agentgovern import PolicyViolation
+
+try:
+    agentgovern.evaluate_input(agent_external_id="my-agent", prompt=user_prompt)
+except PolicyViolation:
     raise HTTPException(status_code=403, detail="Prompt blocked by compliance policy")
 agent.invoke({"input": user_prompt})
 ```
 
+It sends the whole prompt, not 4,000 characters. Unlike the integrations, it raises
+`ClientError` when AgentGovern refuses the request (a 4xx). If AgentGovern can't be
+reached, doesn't answer within 5 seconds, or returns a server error, it returns an allowed
+result, unless you pass `fail_closed=True`, which makes it raise `GateUnavailable`.
+
+*(Corrected 2026-10-31, NAGT-607: the table listed four modes, without alert, and said
+a disabled policy is not evaluated. This section did not say that Gate 2 is off unless
+you turn it on, that tool calls are not checked before they run, that an agent
+AgentGovern can't find passes Gate 1, that an input failing a warn, log, alert or
+disabled policy first is not blocked until the engine is updated, or that the
+LangGraph integration's Gate 2 checks only the first 65,536 characters of an output.
+It said a Gate 1 error stops the call with `fail_open=False`, which a 4xx does not. Its
+example checked the returned result's `action_taken` for a block, a branch that never
+runs, because `evaluate_input()` raises on a block instead of returning.)*
+
 ## Multiple agents in one process
 
 If you run more than one agent in the same process, pass the agent ID explicitly to
@@ -206,7 +270,7 @@ 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"` |
+| `environment` | `"production"` | `"production"` \| `"staging"` \| `"development"`. Use your API key's environment. Actions are recorded under the key's environment whatever this says, but Gate 1 and Gate 2 look your agent up under this one, and an agent they can't find there goes unchecked |
 | `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 |
 

{agentgovern-2.7.2 → agentgovern-2.8.0}/README.md

@@ -25,7 +25,7 @@ from langchain_openai import ChatOpenAI
 agentgovern.init(
     api_key="ag_prod_...",           # from https://agentgovern.zirahn.com/settings/api-keys
     base_url="https://agentgovern.zirahn.com",
-    environment="development",       # "production" | "staging" | "development"
+    environment="production",        # your API key's environment: "production" | "staging" | "development"
 )
 
 # 2. Register your agent
@@ -53,14 +53,15 @@ and visible in the dashboard.
 
 ## Enforcement modes
 
-AgentGovern supports four enforcement modes per policy:
+AgentGovern supports five enforcement modes per policy:
 
 | Mode     | Behavior                                                   |
 |----------|------------------------------------------------------------|
 | warn     | Records the violation; the agent continues                 |
 | log      | Records the violation silently; the agent continues        |
-| disabled | Policy not evaluated                                       |
-| enforce  | Records the violation and **raises** in your code (below)  |
+| alert    | Same as warn today: records the violation; the agent continues |
+| disabled | Still evaluated, and failures are recorded; the agent continues |
+| enforce  | Records the violation, and **raises** in your code where the check runs before the action (below) |
 
 ### What enforce stops, through the LangChain and LangGraph integrations
 
@@ -68,18 +69,60 @@ When an enforce-mode policy blocks, the exception reaches the code that called
 `invoke()`, `ainvoke()`, `stream()` or `astream()`:
 
 - **Gate 1 (input) raises `PolicyViolation` before the model call runs.** This is the
-  control that stops an agent before it acts.
+  control that stops an agent before it acts. By default (`auto_evaluate_input=True`) it
+  runs before every model call the handler sees, chat models and completion-style LLMs
+  alike, and checks the last 4,000 characters of the call's input against your
+  policies' `input` rules: the newest message, and as much history before it as fits.
+  Anything earlier is not checked in that call, and a single message longer than
+  4,000 characters is checked only on its last 4,000.
+  *(Changed in SDK 2.8.0, NAGT-555. Earlier releases checked chat models only, and
+  only the first 4,000 characters, so a long conversation's newest message went
+  unchecked.)*
 - **Gate 2 (output) raises `OutputBlocked` (block) or `OutputEscalated` (escalate)**
-  when the run finishes. Gate 2 stops `invoke()` from **returning** a blocked answer.
+  when the run finishes, if you pass `gate_2_enforcement_mode="enforce"` to
+  `instrument_langchain()` or `instrument_langgraph()`. It is off by default.
+  Gate 2 stops `invoke()` from **returning** a blocked answer.
   **It does not undo anything that already happened:** tool calls have already run, a
   LangGraph checkpointer has already saved the final state, and a `stream()` caller has
   already received the streamed output. On LangChain, a run whose LLM streamed tokens skips the synchronous Gate 2 entirely.
 - **Redact** replaces the answer on LangChain; LangGraph does not apply it.
-
-**What never stops your agent:** warn, log and allow verdicts; AgentGovern being
-unreachable, slow, or returning an error (unless you configured `fail_open=False`, in
-which case Gate 1 raises `GateUnavailable`, or `gate_2_failure_mode="fail_closed"`, in
-which case Gate 2 raises `OutputBlocked`); and any error inside the SDK itself.
+- **An output over the policy engine's 256 KB limit** is cut to fit, and the part that
+  fits is evaluated; the result's `partial` (or the exception's) says so. A block,
+  escalate or redact found in that part raises `OutputBlocked` / `OutputEscalated` (a
+  redact can't be applied to the whole answer). When no policy applies to the action, it
+  is allowed, as it would be whole. Anything else is treated as unchecked: with
+  `gate_2_failure_mode="fail_closed"` it raises `OutputBlocked`, as the engine's refusal
+  did before; otherwise it is allowed. *(SDK 2.8.0, NAGT-545. Before, such an
+  output was never evaluated at all.)* On LangGraph, see the last item below.
+
+**What enforce does not stop:**
+
+- **A tool call.** The SDK does not check a tool call before it runs. A policy on tool
+  calls is evaluated on the recorded action after the tool has run, so in enforce mode
+  it records the failure but cannot prevent the call. (Guard's Claude Code hook, below,
+  does check each tool call before it runs.)
+- **An agent AgentGovern can't find.** Gate 1 allows the call, and records no
+  evaluation, when the agent isn't registered yet or is registered under a different
+  environment from the one `init()` names. `register_agent()` sends the registration in
+  the background, so a new agent's first model calls can pass this way.
+- **An input that also fails a warn, log, alert or disabled policy, until AgentGovern's
+  policy engine is updated (NAGT-555).** Gate 1 acts on the first `input` rule the input
+  fails, and that rule's policy decides. So when an input fails rules in two policies,
+  one set to enforce and one set to warn or disabled, it can be allowed instead of
+  blocked. The engine is updated separately from this SDK; after that update the
+  strictest failing rule decides, whatever SDK version you run.
+- **The rest of a long LangGraph output.** The LangGraph integration cuts the graph's
+  output to its first 65,536 characters before Gate 2 and evaluates that part as if it
+  were the whole output: it is not marked partial, and Gate 2 does not check the rest.
+
+**What never stops your agent:** warn, log, alert and allow verdicts, and any error
+inside the SDK itself. If Gate 1 can't complete its check (AgentGovern can't be reached,
+doesn't answer within 5 seconds, or returns a server error), the model call goes ahead,
+unless you pass `fail_open=False`, which makes Gate 1 raise `GateUnavailable`. A Gate 1
+request AgentGovern refuses (a 4xx, such as a wrong API key) lets the call go ahead
+either way. If Gate 2 can't complete its check, the output is returned, unless you pass
+both `gate_2_enforcement_mode="enforce"` and `gate_2_failure_mode="fail_closed"`, which
+makes Gate 2 raise `OutputBlocked`.
 
 **Pass AgentGovern's handler last.** When an enforce block raises, LangChain can stop
 delivering that event to the handlers after ours in the `callbacks` list (on synchronous
@@ -89,21 +132,42 @@ Put AgentGovern's handler at the end of the list:
 `config={"callbacks": [your_tracer, agentgovern_handler]}`.
 
 **How:** an instrumentor sets LangChain's `raise_error` when an enforce gate is
-configured (Gate 2 `enforce`, or Gate 1 auto-evaluation on), and lets only the three
-verdict exceptions above out of its callbacks.
+configured (Gate 2 `enforce`, or Gate 1 auto-evaluation on), and lets out of its
+callbacks only the three verdict exceptions above and, when you pass `fail_open=False`,
+`GateUnavailable`.
 
 *(Changed in SDK 2.6.0, NAGT-380. Earlier releases recorded enforce-mode violations
 but did not stop the agent: LangChain caught the exception.)*
 
-You can also check input yourself before invoking an agent:
+You can also check input yourself before invoking an agent. `evaluate_input()` raises
+`PolicyViolation` when a policy set to enforce blocks the input, and otherwise returns
+the result:
 
 ```python
-result = agentgovern.evaluate_input(agent_external_id="my-agent", prompt=user_prompt)
-if result.action_taken == "block":
+from agentgovern import PolicyViolation
+
+try:
+    agentgovern.evaluate_input(agent_external_id="my-agent", prompt=user_prompt)
+except PolicyViolation:
     raise HTTPException(status_code=403, detail="Prompt blocked by compliance policy")
 agent.invoke({"input": user_prompt})
 ```
 
+It sends the whole prompt, not 4,000 characters. Unlike the integrations, it raises
+`ClientError` when AgentGovern refuses the request (a 4xx). If AgentGovern can't be
+reached, doesn't answer within 5 seconds, or returns a server error, it returns an allowed
+result, unless you pass `fail_closed=True`, which makes it raise `GateUnavailable`.
+
+*(Corrected 2026-10-31, NAGT-607: the table listed four modes, without alert, and said
+a disabled policy is not evaluated. This section did not say that Gate 2 is off unless
+you turn it on, that tool calls are not checked before they run, that an agent
+AgentGovern can't find passes Gate 1, that an input failing a warn, log, alert or
+disabled policy first is not blocked until the engine is updated, or that the
+LangGraph integration's Gate 2 checks only the first 65,536 characters of an output.
+It said a Gate 1 error stops the call with `fail_open=False`, which a 4xx does not. Its
+example checked the returned result's `action_taken` for a block, a branch that never
+runs, because `evaluate_input()` raises on a block instead of returning.)*
+
 ## Multiple agents in one process
 
 If you run more than one agent in the same process, pass the agent ID explicitly to
@@ -165,7 +229,7 @@ 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"` |
+| `environment` | `"production"` | `"production"` \| `"staging"` \| `"development"`. Use your API key's environment. Actions are recorded under the key's environment whatever this says, but Gate 1 and Gate 2 look your agent up under this one, and an agent they can't find there goes unchecked |
 | `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 |
 

{agentgovern-2.7.2 → agentgovern-2.8.0}/RELEASING.md

@@ -101,4 +101,16 @@ To re-run a publish after a failed run, trigger the workflow manually **from the
   - 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`).
+- **2026-10-23:** 2.7.3 was published by run `39881523976` from tag `sdk-v2.7.3` at `ccbbcd6d` (#1043's merge; the release carries #1042 (NAGT-484, NAGT-500) and #1043 (NAGT-490)). **Ahmed pushed the tag.** Build 01:00:53–01:01:10Z, Publish 01:01:14–01:01:38Z; files uploaded 01:01:32Z and 01:01:34Z. Verified afterwards, read-only:
+  - the wheel and sdist sha256 match PyPI's digests (`11f01051…`, `8a5b51fd…`), compared with the run's own `dist` artifact;
+  - the wheel's `METADATA` says `Version: 2.7.3`, `Requires-Python: >=3.10`;
+  - its bundled `hook.py` is **hook 2.5.1**, sha256 `96e1ed3bdf2cc78932a8dd5e348e3b23c777723e2c9cb36b36a651bbeb40f327`, 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;
+  - Python 3.9.6 (`/usr/bin/python3`) resolves `agentgovern-2.5.0`;
+  - **Ahmed's fresh install from PyPI on his Mac, in a temp HOME** (`docs/runbooks/sdk-2.7.3-release-2026-10-23.md` §6), passed:
+    - `2.7.3 3.13.15`;
+    - all four hooks registered with the venv's own `…/.venvs/agentgovern/bin/python3.13`;
+    - hook `2.5.1`;
+    - under `deny`, an HTTP 501 is blocked and a missing `AGENTGOVERN_API_KEY` is blocked with the reinstall reason.
+  - the hook version changed, so the released-hook manifest moved to 2.5.1 in the release-record PR (#1050).
 

{agentgovern-2.7.2 → agentgovern-2.8.0}/agentgovern/__main__.py

@@ -1,6 +1,8 @@
 """AgentGovern CLI entry point.
 
 Dispatches to subcommands. Currently supported:
+  agentgovern setup [--actor-user-id ID] [--check] [--profile PATH]
+  agentgovern remove
   agentgovern hook [install|uninstall|status|test]
 """
 
@@ -28,12 +30,25 @@ def main(argv: Sequence[str] | None = None) -> int:
 
     add_hook_subparsers(hook_parser)
 
+    # `agentgovern setup` / `agentgovern remove` (NAGT-557): the install snippet's steps
+    from agentgovern.hook.setup import add_setup_subparsers
+
+    add_setup_subparsers(subparsers)
+
     args = parser.parse_args(argv)
 
     if args.command == "hook":
         from agentgovern.hook.cli import dispatch
 
         return dispatch(args)
+    if args.command == "setup":
+        from agentgovern.hook.setup import run_setup
+
+        return run_setup(args)
+    if args.command == "remove":
+        from agentgovern.hook.setup import run_remove
+
+        return run_remove(args)
 
     parser.error(f"Unknown command: {args.command}")
     return 2  # unreachable

agentgovern-2.8.0/agentgovern/_fit.py

@@ -0,0 +1,158 @@
+"""
+NAGT-545: fit a Gate 2 evaluate body under the policy engine's cap by shortening
+its longest strings, so a large output is evaluated on what fits rather than
+refused with a 413.
+
+The Python twin of apps/web/lib/eval/fit-evaluate-body.ts (NAGT-527, NAGT-540).
+Only string values inside the parts given are shortened (the output payload and
+the metadata), every one to the same maximum length (the largest that fits),
+keeping its start. Shorter strings, keys, numbers and structure are unchanged.
+
+The result of an evaluation of a cut body is partial: content past a cut was not
+seen. agentgovern/gate2.py never presents it as a full pass.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+# The engine is the authority: apps/policy-engine/app/config.py's
+# `engine_max_body_bytes` default, which app/main.py applies to /api/v1/evaluate/.
+# The engine refuses a body with `len(body) > max_bytes` (app/middleware.py), so
+# a body of exactly this many bytes is admitted. tests/test_fit_body.py reads the
+# engine's source and fails if this copy differs. A lower ENGINE_MAX_BODY_BYTES
+# override on the engine is not visible here; it is still safe: the engine
+# answers 413 and Gate 2's existing error path runs.
+ENGINE_EVALUATE_MAX_BODY_BYTES = 262_144
+
+
+def encode_body(body: Any) -> bytes:
+    """The exact bytes Gate 2 sends: httpx 0.28's `json=` encoding.
+
+    Measuring and sending the same bytes means no margin is needed.
+    """
+    return json.dumps(
+        body, ensure_ascii=False, separators=(",", ":"), allow_nan=False
+    ).encode("utf-8")
+
+
+@dataclass(frozen=True)
+class FitResult:
+    """`kind` is "whole", "partial" or "unfittable".
+
+    "unfittable": over the cap even with every string emptied; sent whole, as before.
+    `partial` is the record of the cut, set only when `kind` is "partial".
+    """
+
+    kind: str
+    body: bytes
+    partial: dict[str, Any] | None = None
+
+
+def _cut_strings(value: Any, max_len: int) -> tuple[Any, int]:
+    """`value` with every string longer than `max_len` cut, and how many were."""
+    count = 0
+
+    def walk(v: Any) -> Any:
+        nonlocal count
+        if isinstance(v, str):
+            if len(v) <= max_len:
+                return v
+            count += 1
+            return v[:max_len]
+        if isinstance(v, (list, tuple)):
+            return [walk(x) for x in v]
+        if isinstance(v, Mapping):
+            return {k: walk(child) for k, child in v.items()}
+        return v
+
+    return walk(value), count
+
+
+def _longest_string(value: Any) -> int:
+    if isinstance(value, str):
+        return len(value)
+    if isinstance(value, (list, tuple)):
+        return max((_longest_string(x) for x in value), default=0)
+    if isinstance(value, Mapping):
+        return max((_longest_string(x) for x in value.values()), default=0)
+    return 0
+
+
+def _size(value: Any) -> int:
+    return len(encode_body(value))
+
+
+def fit_body(
+    build: Callable[[dict[str, Any]], Any],
+    parts: dict[str, Any],
+    cap_bytes: int,
+) -> FitResult:
+    """The encoded body for `parts`, under `cap_bytes`.
+
+    `build` makes the whole engine body from the parts, so everything around them
+    is counted exactly as it will be sent. Each part is cut; the record has a side
+    for each, under the part's name in `parts`.
+    """
+    whole = encode_body(build(parts))
+    if len(whole) <= cap_bytes:
+        return FitResult(kind="whole", body=whole)
+    try:
+        return _cut_to_fit(build, parts, cap_bytes, whole)
+    except RecursionError:
+        # The walkers recurse once per nesting level and can overflow on a deeply
+        # nested body that json.dumps still encodes. Sent whole, such a body takes
+        # the existing 413 path, as any body that can't be cut to fit does.
+        return FitResult(kind="unfittable", body=whole)
+
+
+def _cut_parts(parts: dict[str, Any], max_len: int) -> tuple[dict[str, Any], dict[str, int]]:
+    cut: dict[str, Any] = {}
+    counts: dict[str, int] = {}
+    for name, value in parts.items():
+        cut[name], counts[name] = _cut_strings(value, max_len)
+    return cut, counts
+
+
+def _cut_to_fit(
+    build: Callable[[dict[str, Any]], Any],
+    parts: dict[str, Any],
+    cap_bytes: int,
+    whole: bytes,
+) -> FitResult:
+    def fits_at(max_len: int) -> bool:
+        return _size(build(_cut_parts(parts, max_len)[0])) <= cap_bytes
+
+    if not fits_at(0):
+        return FitResult(kind="unfittable", body=whole)
+
+    # The largest max_len that fits. fits_at(0) holds; fits_at(longest) does not,
+    # since at that length nothing is cut and the whole body is over the cap.
+    lo = 0
+    hi = max((_longest_string(v) for v in parts.values()), default=0)
+    while hi - lo > 1:
+        mid = (lo + hi) // 2
+        if fits_at(mid):
+            lo = mid
+        else:
+            hi = mid
+
+    cut, counts = _cut_parts(parts, lo)
+    body = encode_body(build(cut))
+    partial: dict[str, Any] = {
+        "cap_bytes": cap_bytes,
+        "body_bytes_before": len(whole),
+        "body_bytes_after": len(body),
+        # In code points (Python str); the web's is in UTF-16 code units.
+        "max_string_length": lo,
+    }
+    for name in parts:
+        partial[name] = {
+            "strings_cut": counts[name],
+            "bytes_before": _size(parts[name]),
+            "bytes_after": _size(cut[name]),
+        }
+    return FitResult(kind="partial", body=body, partial=partial)

agentgovern-2.8.0/agentgovern/_version.py

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