How to block Bash in Claude Agent SDK

How do you block Bash in Claude Agent SDK?

Deny it on PreToolUse. Bash is a built-in tool. It has no local execute for guardTool. PreToolUse is the only labeled, application-context deny for unwrapped tools: Bash, Write, and the MCP tools that you didn't wrap.

guardTool wraps an authored tool() that you wrote. Don't use it on Bash. Don't apply both helpers to the same authored tool.

1
import { guardHooks } from "@arcjet/guard/claude-agent-sdk/v0";
2
import { tokenBucket } from "@arcjet/guard";
3
import { arcjet } from "./arcjet.js";
4

5
const bashLimit = tokenBucket({
6
  bucket: "bash",
7
  refillRate: 20,
8
  intervalSeconds: 60,
9
  maxTokens: 20,
10
});
11

12
const conversationId = "..."; // your conversation id
13

14
export const hooks = guardHooks(arcjet, {
15
  sessionId: conversationId,
16
  action: ({ toolName }) => `${toolName}.invoked`,
17
  rules: ({ toolName }) =>
18
    toolName === "Bash" ? [bashLimit({ key: "Bash", requested: 1 })] : [],
19
});

Pass hooks to query({ options: { hooks } }). protect() is the HTTP check on a route. This deny is the agent-side gate on the shell.

Why isn't canUseTool or allowedTools enough?

canUseTool is the ask path, not a check on every tool. A bare allowedTools name such as Bash auto-approves every call unless an ask rule or plan mode sends it back. Narrow documented exceptions apply, such as tools that require user interaction and critical-path rm. If you list Bash and put the check in the callback, then the callback never runs.

That is the whole article at canUseTool is not a policy gate. Don't put the deny on the callback.

Hiding Bash with a bare disallowedTools name removes the tool from the request, so that Claude doesn't see it. That is a prompt-surface control, not the PreToolUse deny on a call that still reaches the hook. A scoped deny rule such as Bash(rm *) does block matching calls at run time, in every mode, but it isn't a labeled decision on this call with application context.

Where does PreToolUse sit?

Hooks run before every other permission step. A PreToolUse deny applies even in bypassPermissions. It still sees a bare allowedTools name.

On deny, the hook returns permissionDecision: "deny" and the tool doesn't run. PostToolUse is capture only. It can't un-send.

Correlate the decision with a sessionId that you already have. claudeAgentContext reads that ID. It never mints one.

Does a sandbox replace the deny?

No. The Bash sandbox isolates the file system and network for the shell and its child processes. The operating system enforces that boundary. It doesn't decide whether this command should run.

A jailed curl | sh is still a send if egress is open. A jailed cat ~/.ssh/id_rsa is still a read if the path is allowed. A sandbox is not a tool policy. Isolation isn't authorization.

Keep the sandbox and tighten its egress. Put the deny on PreToolUse.

What if Arcjet is down on PreToolUse?

Helpers default to onGuardError: "deny". If Guard can't be evaluated, then the tool doesn't run.

Timeout already fail-closes, so the tool doesn't run while you wait. "allow" is a legitimate choice on inbound prompt screening, because failing closed there would stop the agent answering during an outage. It isn't the default on this tool.