New: Decision Runtime — closed-set judgments for Agent OS. Read the guide →
HazelJS LogoHazelJS

Agent Gatekeeper

Agent Gatekeeper (@hazeljs/agent-gatekeeper) authorizes every tool invocation: allow, deny, or require-approval. The CLI can validate and simulate policies without executing tools.

01What it is

Fail-closed authorization for tool calls. Build a bundle with createAgentGatekeeperBundle, bind it to the runtime (bindGatekeeper / authorizationGate), and return allow, deny, or require-approval. Default decision is deny when you follow the production sketch in the Agent OS guide.

02Problem it solves

  • LLMs invent tool args — policies must see the actual invocation context
  • High-risk writes need humans (hazel approvals / approve / deny)
  • Offline validate | simulate | explain before shipping policy changes
  • Decision confidence must not bypass authorization

03How you use it today

Attach policies to the runtime/tool path; use hazel gatekeeper validate|simulate|explain for offline checks. Durable HITL: AgentOS.approve / reject resume suspended runs. Full guide: Agent Gatekeeper.

04Where it sits in the stack

Govern layer after Decision and before tool execution. Works with Skillgate-classified skills and with hand-written @Tool methods. Content/PII filters may live separately in @hazeljs/guardrails when you opt in.

05Boundaries

  • Gatekeeper is authorization — not prompt injection detection by itself
  • require-approval needs a human task path (in-process or durableSuspend)
  • CLI simulate does not execute tools — it evaluates policy only

06FAQ

What are the three outcomes?
allow, deny, and require-approval — fail closed when no policy matches if you keep defaultDecision: deny.
How does HITL resume after a crash?
Use durableSuspend + AgentOS.approve / reject (approveAndResume). In-process approveToolExecution only works while the worker is still waiting.
Where is the broader security story?
See AI agent security and the security guide.

07Policy sketch

typescript
import { AgentGatekeeper, fromFunction } from '@hazeljs/agent-gatekeeper';

const gatekeeper = new AgentGatekeeper({
  policies: [
    fromFunction('refunds.create', async (ctx) =>
      ctx.amount > 50 ? 'require-approval' : 'allow',
    ),
  ],
});