Integrate Arcjet Guard Claude Agent Sdk

Integrate Arcjet Guard into a Claude Agent SDK agent

@arcjet/guard's Claude Agent SDK v0 namespace wraps the agent's existing Arcjet client. It never talks to the Arcjet API itself. Three surfaces, one decision rule:

• An authored tool (tool() + createSdkMcpServer()) → guardTool(). DENY is a CallToolResult with isError: true. Do not throw.
• Inbound text → guardHooks() UserPromptSubmit. DENY is { decision: "block" }. Timeout already fail-closes the prompt (Claude Code v2.1.208+).
• Built-ins / unwrapped MCP → guardHooks() PreToolUse with permissionDecision: "deny". Timeout already fail-closes (the tool does not run). PostToolUse is capture only.
• Correlation → claudeAgentContext() reads session_id from hook input or options.sessionId. Subagents have agent_id (metadata only). It never mints a new id. options.sessionId must be a UUID and can only be created once — see Step 5.

Screen inbound with UserPromptSubmit

This is the only place a turn can be declined before the model sees the prompt. There is no guardInbound. Put detectPromptInjection on guardHooks({ inbound }). A DENY returns { decision: "block", reason } and Claude Code erases the prompt.

canUseTool is not a policy gate

Claude's docs say canUseTool is skipped by allowedTools, allow rules, and bypassPermissions / acceptEdits. There is no guardCanUseTool. Do not put Arcjet policy on canUseTool. Same trap as Google ADK requireConfirmation: after a human yes, Guard still runs.

PreToolUse is the only deny for unwrapped tools

Built-ins (Bash, Write, …) and MCP tools you did not pass through guardTool are gated here. Annotations (readOnlyHint, …) and sandbox settings are not enforcement. PostToolUse cannot undo a tool that already ran.

Questions to ask the human first

Ask only what you cannot infer from the code; suggest defaults.

1. Which tools are risky (external side effects, irreversible, spends money, sends messages)? Those get guardTool. Built-ins and unwrapped MCP get guardHooks PreToolUse.
2. What limits? (e.g. "10 lookups/min per order" → tokenBucket.)
3. Who is the user for metadata — an opaque user/tenant ID (never PII)? Default: none. Pass it via metadata on the policy. Session id is the correlation id, not the user.
4. Is an Arcjet outage unacceptable? Every helper defaults to onGuardError: "deny". Ask explicitly about inbound UserPromptSubmit: failing closed there means the agent stops answering for the duration of the outage, so "allow" is a routine and legitimate choice at that one call site.

The seven things readers get wrong

1. There is no guardInbound. Screen prompt injection on guardHooks({ inbound }) via UserPromptSubmit.
2. canUseTool is not a policy gate. It is skipped by allowedTools, allow rules, and bypassPermissions / acceptEdits. Use guardTool or PreToolUse.
3. The import path is versioned and there is no alias. @arcjet/guard/claude-agent-sdk/v0. @arcjet/guard/claude-agent-sdk does not resolve.
4. options.sessionId is a UUID, and only once. A non-UUID exits with "Invalid session ID"; reusing one exits with "already in use". Mint a UUID for the conversation and resume it on later turns.
5. Correlation is read, never minted. Do not call createAgentContext inside a Claude callback — that generates a second id and splits the Sequence. claudeAgentContext reads session_id / options.sessionId and omits correlationId when neither is a valid id. Subagent agent_id is metadata, not the correlation id.
6. Do not double-wrap with @arcjet/guard/vercel-ai/v7, @arcjet/guard/agents, or @arcjet/guard/claude-managed-agents/v0. Claude tools are tool(), not AI SDK tool(), and this is not hosted Claude Managed Agents. guardTool throws if the tool already carries the Arcjet protection brand. Applying guardTool and guardHooks PreToolUse to the same authored tool double-calls the guard.
7. A denial from guardTool is a CallToolResult with isError: true, not a throw. If onDeny throws, the handler still does not run and the model still receives the default denial result.

Step 1: Install and find the guard client

Install @arcjet/guard (required), plus @anthropic-ai/claude-agent-sdk (optional peer, needed for @arcjet/guard/claude-agent-sdk/v0). Always use the versioned path: @arcjet/guard/claude-agent-sdk/v0 resolves; @arcjet/guard/claude-agent-sdk throws ERR_PACKAGE_PATH_NOT_EXPORTED.

npm install @arcjet/guard @anthropic-ai/claude-agent-sdk

If the agent has no guard client yet, launch one once at module scope:

import { launchArcjet } from "@arcjet/guard";

export const arcjet = launchArcjet({ key: process.env.ARCJET_KEY! });

Step 2: Gate authored tools

import { tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
import { guardTool } from "@arcjet/guard/claude-agent-sdk/v0";
import { tokenBucket, localDetectSensitiveInfo, policyInput } from "@arcjet/guard";

import { arcjet } from "./arcjet.js";

const lookupLimit = tokenBucket({
  bucket: "lookups",
  refillRate: 10,
  intervalSeconds: 60,
  maxTokens: 10,
});
const detectPii = localDetectSensitiveInfo();

export const lookupOrder = guardTool(
  arcjet,
  tool(
    "lookup_order",
    "Look up an order by ID",
    {
      orderId: z.string(),
      note: z.string(),
    },
    async ({ orderId, note }) => ({
      content: [{ type: "text", text: `${orderId}: shipped (${note})` }],
    }),
  ),
  {
    action: "order.looked-up",
    actor: userId,
    inputs: (input) => ({
      orderId: policyInput.server.string(input.orderId),
    }),
    rules: (input) => [lookupLimit({ key: input.orderId, requested: 1 }), detectPii(input.note)],
  },
);

• Omit rules to submit none. The guard call still happens.
• Optional actor and inputs (static, or a resolver over this adapter's native call — parsed input plus trusted runtime/context) are forwarded on the guard call so a remote policy that declares those names can evaluate. Build each input with policyInput.
• On DENY the tool's handler never runs. The model receives { content, structuredContent: { arcjetDenied, reason, message, retryable }, isError: true }.
• Default onGuardError: "deny" blocks the tool if Arcjet is unreachable.
• Pass the same sessionId you give query({ options.sessionId }) on the policy when the handler extra does not carry session_id.

Step 3: Screen inbound with UserPromptSubmit

import { query } from "@anthropic-ai/claude-agent-sdk";
import { guardHooks } from "@arcjet/guard/claude-agent-sdk/v0";
import { detectPromptInjection } from "@arcjet/guard";

import { arcjet } from "./arcjet.js";

const sessionId = conversationId;

for await (const message of query({
  prompt: userText,
  options: {
    sessionId,
    hooks: guardHooks(arcjet, {
      sessionId,
      inbound: {
        action: "message.received",
        rules: ({ prompt }) => [detectPromptInjection()(prompt)],
      },
    }),
  },
})) {
  void message;
}

• On DENY, UserPromptSubmit returns { decision: "block", reason } and the prompt is erased. The model never sees it.
• Default onGuardError: "deny" — if the guard cannot be evaluated, the prompt is blocked. Use "allow" on inbound when the human cost of rejecting a legitimate message exceeds the security cost of an outage.

Step 4: Gate tools you did not wrap

import { guardHooks } from "@arcjet/guard/claude-agent-sdk/v0";
import { detectPromptInjection, tokenBucket } from "@arcjet/guard";

import { arcjet } from "./arcjet.js";

const mcpLimit = tokenBucket({
  bucket: "mcp-access",
  refillRate: 20,
  intervalSeconds: 60,
  maxTokens: 20,
});

export const hooks = guardHooks(arcjet, {
  sessionId: conversationId,
  action: ({ toolName }) => `${toolName}.invoked`,
  rules: ({ toolName }) => [mcpLimit({ key: toolName, requested: 1 })],
  // Tools that already guard themselves via `guardTool`. Without this they
  // are guarded twice per invocation.
  exclude: [{ server: "support", name: "lookup_order" }],
  inbound: {
    action: "message.received",
    rules: ({ prompt }) => [detectPromptInjection()(prompt)],
  },
});

Pass hooks to query({ options.hooks }). PreToolUse returns permissionDecision: "deny" so Bash / Write / unwrapped MCP never execute. PostToolUse is observe-only.

Use this for tools you did not pass through guardTool. PreToolUse fires for every tool and the hook input carries only a name, never the Arcjet brand guardTool applies — so list your wrapped tools in exclude, or each one costs two guard calls and two quota units per invocation.

Entries match the reported name exactly. A bare string matches only that name, which is what you want for a built-in like "Bash". An authored tool arrives as mcp__<server>__<tool>, so exclude it with { server, name } — or the full reported name — and never with the bare authored name: two servers can expose the same tool name with only one of them wrapped, so a loose match would drop the gate on the unprotected one. Excluding a tool stops the gate, not the PostToolUse capture.

Step 5: Correlation

Two Claude CLI constraints decide the shape of this, and neither is Arcjet's:

1. options.sessionId must be a UUID. Anything else exits the CLI with Error: Invalid session ID. Must be a valid UUID.
2. A session id can only be created once. Passing the same id to a second query() exits with Error: Session ID <id> is already in use. Continue the conversation with options.resume instead.

So the conversation identity is a UUID, minted once, and every later turn resumes it. That is also the only shape that keeps a multi-turn conversation on one Sequence: claudeAgentContext reads the hook's session_id first, so a fresh UUID per turn silently splits correlation instead of erroring.

import { randomUUID } from "node:crypto";

// Store this with the conversation; do not generate one per turn.
const sessionId = conversationId ?? randomUUID();

async function turn(userText: string, firstTurn: boolean) {
  for await (const message of query({
    prompt: userText,
    options: {
      ...(firstTurn ? { sessionId } : { resume: sessionId }),
      hooks: guardHooks(arcjet, { sessionId }),
    },
  })) {
    void message;
  }
}

Pass sessionId to guardHooks either way: on a resumed turn the hook input carries the same id, and the policy value is the fallback when it does not. If neither is a valid 1–256 printable-ASCII string, the call is uncorrelated rather than joined to a generated id nobody has. Subagent agent_id is recorded as claude.agent metadata only.

A single query() with a streaming-input prompt is the other supported multi-turn shape, and needs no resume.

Verify the integration

1. npm run typecheck passes.
2. Exercise inbound PI, a tool deny, PII on args, a rate limit, a built-in deny (Bash / Write), and fail-closed (an unreachable guard).
3. Confirm a wrapped tool produces one guard decision per invocation, not two — a second decision under the PreToolUse action means a missing exclude entry.
4. Confirm in the Arcjet dashboard that decisions share the session id as their correlation id.
5. Manual E2E with a real ARCJET_KEY is still-to-verify until you run it.

A full working demo belongs in arcjet/examples (follow-up; do not add an example under examples/ in the JS SDK repo).

Note: capture events are fire-and-forget and batched, so events can lag the decisions they accompany by a few seconds. A dropped event is diagnosed, never thrown.