Claude Agent SDK security

How do you secure a Claude Agent SDK agent?

Screen the prompt before the model sees it. Deny the tool before it runs. Those are two jobs.

guardTool wraps an authored tool(). guardHooks screens inbound text on UserPromptSubmit and denies unwrapped built-in and MCP tools on PreToolUse. claudeAgentContext reads session_id. It never mints an ID.

protect() is the HTTP check on a route. The Claude Agent SDK agent guard documentation is the product map.

How do you screen inbound prompts?

Put detectPromptInjection on guardHooks({ inbound }). That hook is UserPromptSubmit. On deny, Claude Code erases the prompt. The model never sees it.

That is the only place a submitted prompt can be declined before it starts. A clean injection score doesn't authorize a write.

Helpers default to onGuardError: "deny". "allow" is a legitimate choice on inbound, because failing closed there would stop the agent from answering during an outage. Timeout already fail-closes the prompt.

Why isn't canUseTool a security policy?

Because Claude can skip it. allowedTools, allow rules, bypassPermissions, and acceptEdits approve the call first. canUseTool is not a policy gate is that trap.

Don't put the deny on canUseTool. Anthropic's permissions documentation says the same thing: the callback runs when no earlier step resolved the call.

How do you deny Bash or other unwrapped tools?

On PreToolUse, through guardHooks. Use that for Bash, Write, and the MCP tools that you didn't pass through guardTool. Anthropic's hooks run first. A hook that returns a deny decision (permissionDecision: "deny" in hookSpecificOutput) skips the tool, including under bypassPermissions. That is the slot that still sees a bare allowedTools name.

Keep Claude's own allow and deny rules for the prompt surface. They aren't a labeled decision on this tool with application context.

Authored tools wrap with guardTool. A deny is a CallToolResult with isError: true. It doesn't throw. Don't also wrap those tools with @arcjet/guard/vercel-ai/v7. Don't apply guardTool and PreToolUse to the same authored tool.

1
import { tool } from "@anthropic-ai/claude-agent-sdk";
2
import { z } from "zod";
3
import { guardTool } from "@arcjet/guard/claude-agent-sdk/v0";
4
import { tokenBucket } from "@arcjet/guard";
5
import { arcjet } from "./arcjet.js";
6

7
const lookupLimit = tokenBucket({
8
  bucket: "lookups",
9
  refillRate: 10,
10
  intervalSeconds: 60,
11
  maxTokens: 10,
12
});
13

14
export const lookupOrder = guardTool(
15
  arcjet,
16
  tool(
17
    "lookup_order",
18
    "Look up an order by ID",
19
    {
20
      orderId: z.string(),
21
      note: z.string(),
22
    },
23
    async ({ orderId, note }) => ({
24
      content: [{ type: "text", text: `${orderId}: shipped (${note})` }],
25
    }),
26
  ),
27
  {
28
    action: "order.looked-up",
29
    rules: (input) => [lookupLimit({ key: input.orderId, requested: 1 })],
30
  },
31
);

PostToolUse is capture only. It can't un-send.

Does detection replace an action gate?

No. Detection labels text. An action gate is a labeled allow or deny on this tool, with application context, immediately before the side effect.

Runtime security for LLM applications already splits prompt injection, exfiltration, and unsafe actions. A well-formed Write isn't a jailbreak. Screen the prompt. Deny the tool. Keep canUseTool for the calls that actually reach it.