Agents ask before they act. The approval is your audit evidence.
Two HTTP calls in your agent, a human inbox for the actions that need a person, and a hash-chained record your auditor can re-verify. Free to start: watch two agents at no cost.
Ask, answer, decide
- Step 1
The agent asks
Before a sensitive action, your agent calls POST /api/agent-watch/authorize with its x-agent-token and describes the action: what it is, its risk class, the target and, for an MCP tool call, the server and tool.
- Step 2
KollGuard answers
The answer is always one of allow, deny or pending. Kill switches, the agent’s autonomy tier, your risk-class policy, its declared write scopes and the per-tool MCP policy decide. Malformed input or any error resolves to deny, and anything the policy cannot place goes to a person.
- Step 3
A person decides what needs a person
Pending requests land in the Agent requests inbox in Agent Control. An owner or admin approves or denies with a reason the agent can read back. A route can name the approvers and require two different people. Every decision, automatic or human, is saved and written to the audit log.
curl -X POST https://<your-api-host>/api/agent-watch/authorize \
-H "x-agent-token: kgw_..." \
-H "Content-Type: application/json" \
-d '{
"action": "vault.write",
"actionClass": "write",
"resource": "vault:notes/2026/q3.md",
"summary": "Save the weekly summary",
"idempotencyKey": "run-812:save"
}'
# 200 {"decision":"pending","requestId":"...","reason":"Queued for human approval. ...",
# "expiresAt":"...","pollAfterMs":5000}curl https://<your-api-host>/api/agent-watch/authorize/<requestId> \
-H "x-agent-token: kgw_..."
# 200 {"decision":"allow","requestId":"...","status":"approved","reason":"...",
# "validUntil":"..."}
# Act only on "allow", and only before validUntil. Treat deny, expired,
# any non-200, a timeout or an unparseable body as deny.The body accepts action, actionClass, resource, summary, idempotencyKey and, for an MCP tool call, mcpServer together with tool. Unknown fields and over-long values are rejected, not truncated. Wait the suggested pollAfterMs (5 seconds) between polls. Field rules are documented in the Agent Control article in the in-app Help Center.
Gate Claude Code and Claude agents with KollGuard
You don't write the two HTTP calls yourself. A PreToolUse hook asks the gate before every Bash command, file edit, web fetch and MCP tool call. An allowed call runs. A denied call comes back to Claude with the reason. A call that needs a person waits for an approval in Agent Control. Only tool and argument names are sent, never argument values, file contents or paths. Risky tools fail closed if KollGuard can't be reached.
- Step 1
Create the agent in Agent Watch and approve it to pilot or production.
- Step 2
Copy its kgw_ token into KOLLGUARD_AGENT_TOKEN.
- Step 3
Add the hook to Claude Code settings, or kollguardHooks() to your Agent SDK agent.
// .claude/settings.json (npm install -g @kollguard/claude-hook)
{
"hooks": {
"PreToolUse": [{
"matcher": "^(Bash|Edit|MultiEdit|Write|NotebookEdit|WebFetch|WebSearch|mcp__.*)$",
"hooks": [{
"type": "command",
"command": "kollguard-claude-hook",
"timeout": 150,
"onFailure": "block"
}]
}]
}
}
// KOLLGUARD_AGENT_TOKEN=kgw_... in your environmentimport { query } from '@anthropic-ai/claude-agent-sdk';
import { kollguardHooks } from '@kollguard/agent-sdk';
for await (const m of query({
prompt: 'Run the tests and fix the first failure',
options: { hooks: kollguardHooks({ onAllow: 'approve' }) },
})) { /* ... */ }Any other MCP client: wrap the server with MCP Guard (npx -y @kollguard/mcp-guard --upstream <url>). It hides denied tools and holds approve-mode calls for a person. For TypeScript there is @kollguard/corewith adapters for Mastra, the Vercel AI SDK, the OpenAI Agents SDK and LangGraph, and for Python pip install "kollguard[langgraph]" or "kollguard[openai-agents]". Install steps, resumable approvals, signed webhooks, the HTTP API, evidence and local mode are in the developer docs. Signed-in users can also read the in-app Help Center article Gate Claude Code and Claude agents with KollGuard.
Every answer carries a reason code
The decision is deterministic and the reason code is safe to log. Kill switches come first, then the agent’s standing, the per-tool policy for MCP calls, and your risk-class policy. Anything the policy cannot place goes to a human.
| reasonCode | Answer | When |
|---|---|---|
| tenant_kill_switch | deny | The tenant-wide kill switch is engaged. Every agent action is denied. |
| agent_not_runnable | deny | The agent’s own kill switch is on, it is disabled or rejected, or it is not in pilot or production. |
| policy_off | deny | Your risk-class policy sets this class of action to off. |
| mcp_tool_denied | deny | The per-tool policy for that MCP server denies this tool. A tool deny is final. |
| malformed_input / internal_error | deny | Bad input, an unverifiable agent posture or any internal error. Fail closed. |
| policy_requires_human | pending | The class is set to approve, or the agent’s autonomy tier does not allow auto-run. |
| unclassified_requires_human | pending | No recognised action class was sent. Treated as the most restrictive class. |
| class_never_auto | pending | External communication, money and auth, PHI access and patient-facing actions never auto-run, even if the class is set to auto. |
| destructive_action | pending | The action name looks destructive (delete, drop, revoke and similar). A best-effort safety net that errs toward asking. |
| irreversible_agent | pending | The agent is registered as irreversible. |
| no_write_scopes / outside_write_scope | pending | The agent declares no write scopes, or the target falls outside the scopes it declared. |
| mcp_tool_requires_human / mcp_server_unregistered | pending | The per-tool policy says approve, or the MCP server is not registered in KollGuard. |
| read_allowed | allow | A read or propose action with no side effect, for an agent in good standing. |
| in_write_scope | allow | An internal write, by an autonomous agent, inside its declared write scopes, with a non-destructive name, and the write class set to auto. |
Per-tool policy for MCP servers
- Each registered MCP server gets a per-tool policy: allow, approve or deny, per tool, with a default for the tools the last scan saw.
- Tools the last scan did not see default to approve or deny, never allow, unless you write an explicit rule for them. A tool that has not been inventoried cannot be pre-approved by default.
- A tool set to allow still passes through your risk-class policy. The tool policy can make a request stricter, never more permissive.
- Loop auto-disable: when a run trips your loop policy (identical repeats, hot loops, ping-pong, deep recursion), the agent kill switch is engaged automatically and its next authorization request is denied as agent_not_runnable.
A log shows what happened. An approval shows who allowed it.
Observability records the action after it ran. An auditor testing CC8.1 asks for the authorization that came before it. The gate writes that record first, then the outcome.
| Property | Observability-only tools | Compliance automation platforms | KollGuard gate |
|---|---|---|---|
| When the record is written | After the action ran | On a schedule, after the fact | Before the action, then again with the outcome |
| What it proves to an auditor | What happened | That a control existed at a point in time | Who allowed this specific action, and how fast |
| Human approval of agent actions | Typically out of scope | Typically out of scope | Built in: inbox, reason, expiry |
| Tied to a compliance program | Separate tool | Yes | Yes: the same platform produces the audit packet |
Categories describe typical products, not any one vendor.
What the auditor receives
The audit readiness packet collects agent governance evidence for the audit period, as CSV and JSON, tagged with the SOC 2 controls it supports.
Every authorization request in the period: action, class, resource, status, who decided, the reason, and minutes_to_decision.
Agent Watch alerts in the period, including the escalation raised when a request is waiting for a human, with hours to resolve.
Every time a tenant or agent kill switch was engaged or cleared, by whom, and why.
The packet also carries a recomputed verification of the audit log’s sha256 hash chain, so the decisions behind these files can be checked for tampering. KollGuard produces the evidence; the audit itself is performed by your auditor.
What the gate does not do
Security reviewers ask this first, so we say it first.
- The gate is cooperative. Your agent has to call it and honour the answer. KollGuard does not sit in the network path, so an agent that skips the call or ignores a deny can still act with whatever credentials it holds.
- The gate is fail-closed. Malformed input, an internal error, an expired request or an audit-log failure all resolve to deny. An allow is only returned after the decision has been saved and written to the audit log.
- Time limits are short on purpose. A pending request that the agent waits on expires after 15 minutes and reads as denied. A run that can suspend may ask for a resumable approval instead: a person then has 72 hours (7 days on Enterprise), and the 15-minute allow starts when the approval is first used. Either way an allow is valid for 15 minutes, then the agent asks again with a new idempotencyKey. Each agent can hold at most 50 open inline requests and 500 resumable ones.
- The Claude Code hook and MCP Guard run on the agent’s host. The hook is enforced by Claude Code on every matching tool call, and MCP Guard (@kollguard/mcp-guard) applies the per-tool policy between an MCP client and the server, but someone who controls that host can remove either one. Deliver the hook through Claude Code managed settings for a team, and pair the gate with credentials your own broker issues only after an allow when a deny must be a hard stop.
30 seconds: request, approve, evidence
Frequently asked
- Do I need an SDK?
- No. The gate is two HTTP calls with an agent token: one to ask, one to poll while the answer is pending. Any language that can make an HTTPS request can use it. For Claude Code and the Claude Agent SDK there are ready-made packages, @kollguard/claude-hook and @kollguard/agent-sdk, and @kollguard/mcp-guard covers MCP servers. For agent frameworks there are @kollguard/mastra, @kollguard/vercel-ai, @kollguard/openai-agents and @kollguard/langgraph for TypeScript, and the kollguard package for Python (LangGraph and OpenAI Agents).
- Can an approval take days?
- Yes. A run that can suspend asks for a resumable approval: the request waits up to 72 hours for a person (7 days on Enterprise) and the agent run exits or suspends instead of polling. When the run resumes it asks again with the same idempotency key and gets the stored answer. A signed decision webhook can tell your code when to resume. An allow is still valid for only 15 minutes from its first use.
- Can two people be required to approve?
- Yes. An approver route names the approvers, or a role, and can require two different people to approve. Owners and admins can always deny. The route is fixed on each request when it is filed, so changing it later never lowers the bar for a request that is already waiting. The details are in the developer docs.
- Does this work with OpenTelemetry?
- Agent Watch can ingest agent telemetry over OpenTelemetry, which records what your agents did. The authorization gate is separate: it is the call an agent makes before acting, and it is what produces the approval record.
- What if the agent ignores a deny?
- Then the action is not stopped, because the gate is cooperative. The request and the deny are still on the audit log, so the gap is visible, and you can engage the agent’s kill switch. Pair the gate with credentials that are only issued after an allow so a deny actually blocks the action. For Claude Code and MCP servers, the Claude Code hook and MCP Guard apply the answer on the agent’s host, so the model cannot skip the check. An edit to the hook’s own settings is sent as a separate action that no ordinary write scope covers.
- What does an auditor receive?
- The audit readiness packet includes authorizations.csv, alerts.csv and kill-switch-events.csv for the audit period, each with the control IDs it supports, next to a hash-chain verification of the audit log. The authorization rows show who approved each action and the minutes to decision.
- How many agents can I try it on for free?
- Agent Watch, including the authorization gate, is available on every account, and a free account can watch two agents.
