Agent authorization

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.

How it works

Ask, answer, decide

  1. 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.

  2. 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.

  3. 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.

Ask
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}
Poll while pending
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.

Claude Code and the Claude Agent SDK

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.

  1. Step 1

    Create the agent in Agent Watch and approve it to pilot or production.

  2. Step 2

    Copy its kgw_ token into KOLLGUARD_AGENT_TOKEN.

  3. Step 3

    Add the hook to Claude Code settings, or kollguardHooks() to your Agent SDK agent.

Claude Code
// .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 environment
Claude Agent SDK
import { 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.

What decides

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.

reasonCodeAnswerWhen
tenant_kill_switchdenyThe tenant-wide kill switch is engaged. Every agent action is denied.
agent_not_runnabledenyThe agent’s own kill switch is on, it is disabled or rejected, or it is not in pilot or production.
policy_offdenyYour risk-class policy sets this class of action to off.
mcp_tool_denieddenyThe per-tool policy for that MCP server denies this tool. A tool deny is final.
malformed_input / internal_errordenyBad input, an unverifiable agent posture or any internal error. Fail closed.
policy_requires_humanpendingThe class is set to approve, or the agent’s autonomy tier does not allow auto-run.
unclassified_requires_humanpendingNo recognised action class was sent. Treated as the most restrictive class.
class_never_autopendingExternal communication, money and auth, PHI access and patient-facing actions never auto-run, even if the class is set to auto.
destructive_actionpendingThe action name looks destructive (delete, drop, revoke and similar). A best-effort safety net that errs toward asking.
irreversible_agentpendingThe agent is registered as irreversible.
no_write_scopes / outside_write_scopependingThe agent declares no write scopes, or the target falls outside the scopes it declared.
mcp_tool_requires_human / mcp_server_unregisteredpendingThe per-tool policy says approve, or the MCP server is not registered in KollGuard.
read_allowedallowA read or propose action with no side effect, for an agent in good standing.
in_write_scopeallowAn 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.
Why logging is not authorization

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.

PropertyObservability-only toolsCompliance automation platformsKollGuard gate
When the record is writtenAfter the action ranOn a schedule, after the factBefore the action, then again with the outcome
What it proves to an auditorWhat happenedThat a control existed at a point in timeWho allowed this specific action, and how fast
Human approval of agent actionsTypically out of scopeTypically out of scopeBuilt in: inbox, reason, expiry
Tied to a compliance programSeparate toolYesYes: the same platform produces the audit packet

Categories describe typical products, not any one vendor.

The evidence

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.

authorizations.csv
SOC 2 CC8.1, CC6.1

Every authorization request in the period: action, class, resource, status, who decided, the reason, and minutes_to_decision.

alerts.csv
SOC 2 CC7.2, CC7.3

Agent Watch alerts in the period, including the escalation raised when a request is waiting for a human, with hours to resolve.

kill-switch-events.csv
SOC 2 CC7.3, CC8.1

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.

Honest limits

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.
See it

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.