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
import { AgentGatekeeper, fromFunction } from '@hazeljs/agent-gatekeeper';
const gatekeeper = new AgentGatekeeper({
policies: [
fromFunction('refunds.create', async (ctx) =>
ctx.amount > 50 ? 'require-approval' : 'allow',
),
],
});