PreToolUse guardrails: exit codes and permission decisions

1.What a PreToolUse hook receives

A PreToolUse hook runs before a tool call executes, and it is the hook event that can cancel the call. That is why destructive-action guardrails live there. Each time it fires, the handler receives the call as JSON. Shared fields such as session_id, cwd and hook_event_name come first, then tool_name, then tool_input, which holds the arguments Claude passed. For Bash the shell command is in tool_input.command. For file tools the target path is in tool_input.file_path.

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

A guardrail judges these arguments, not the model's stated intent. A script that pulls out tool_input.command with jq and greps it for drop table will catch that statement however the conversation got there, whether the user asked for it or instructions hidden in a fetched page did.

Sources12

2.Blocking with exit codes

The simplest guardrail answers with its exit code alone. Exit 2 blocks the call, and anything the script writes to stderr goes back to Claude as feedback, so Claude can change course rather than retry the same command blindly. Exit 0 means no objection, and the call carries on to the normal permission checks.

Other exit codes are where guardrails quietly fail. With any other code, Claude Code looks at stdout. If stdout holds JSON that passes schema validation, the JSON decides the outcome and the exit code is ignored. If stdout is plain text or empty, the call goes ahead and the transcript shows a non-blocking hook error. Suppose a script crashes with exit 1 when jq is missing. It has blocked nothing. A guardrail that must hold should exit 2 deliberately when it detects a problem, not rely on crashing.

Sources1

3.Structured decisions: deny, ask and allow

An exit code can say only "block" or "no objection". JSON output can say more. A PreToolUse hook prints a hookSpecificOutput object whose permissionDecision takes one of three values. deny cancels the call and sends permissionDecisionReason to Claude. ask shows the usual permission prompt to the user. allow skips the interactive prompt.

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # no decision; normal permission flow applies
fi

ask fills a gap the exit code leaves. Take an operations team that wants every database-write MCP tool call to wait for a human. A PreToolUse hook with a matcher such as mcp__db__.* can return ask for write calls. The user sees the prompt, and once they approve, the tool runs normally. Blocking with deny would rule the action out entirely, which is not what the team wanted.

allow is weaker than it looks. It removes the interactive prompt and nothing else. Deny and ask rules still apply, including enterprise-managed deny lists. An rm or rmdir that targets a critical path cannot be approved by any allow rule or hook allow. The asymmetry runs the other way for blocking: hooks are evaluated before the permission mode is checked, so a hook's deny still stops a tool when the session runs in bypassPermissions.

Sources13

4.The same guardrail in the Agent SDK

In the Agent SDK, hooks are callback functions passed in the agent's options instead of entries in a settings file. The hooks option maps an event name such as PreToolUse to a list of matchers. Each matcher has a pattern and the callbacks to run, and the pattern follows the same rules as matchers in settings files. MCP tools keep the mcp__<server>__<action> naming.

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[my_callback])]}
)

A callback answers by returning a value, not by exiting with a code. It receives the input data (tool_name, tool_input and the shared fields), a tool use ID that ties a PreToolUse event to the matching PostToolUse, and a context argument. To refuse a call it returns the same hookSpecificOutput structure a command hook prints. To let the call proceed it returns an empty object. A slow callback fails closed: one that exceeds its timeout blocks the tool call. Language support also differs. PreToolUse and PostToolUse work in both Python and TypeScript, but events such as SessionStart are TypeScript-only.

Top-level fields such as systemMessage, which shows a message to the user, and continue are accepted on every event. Some events discard them or deliver them somewhere else. If a guardrail's explanation never reaches your UI, check that event's section on the hooks page before you go hunting for a bug in the callback.

# Define a hook callback that receives tool call details
async def protect_env_files(input_data, tool_use_id, context):
    # Extract the file path from the tool's input arguments
    file_path = input_data["tool_input"].get("file_path", "")
    file_name = file_path.split("/")[-1]

    # Block the operation if targeting a .env file
    if file_name == ".env":
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": " ? ",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }

    # Return empty object to allow the operation
    return {}

Sources42

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.A PreToolUse hook that exits 0 approves the tool call.Why is that wrong?

   Exit 0 only means the hook has no objection. The normal permission flow still decides, and it may still prompt the user.

   Covered in Blocking with exit codes

2. 2.A hook returning permissionDecision allow can approve anything, including rm on a critical path.Why is that wrong?

   Allow only skips the prompt. Deny and ask rules still apply, and critical-path rm and rmdir removals cannot be approved by a hook's allow.

   Covered in Structured decisions: deny, ask and allow

Practise it for real

Install a project PreToolUse hook that denies rm -rf and watch it block a real call.

1. 1.Save the block-rm.sh script from this page as .claude/hooks/block-rm.sh in a scratch project.

   Why: Inside the project, the script can be committed alongside the settings that call it.

   You should see: The file exists and reads tool_input.command with jq.

2. 2.Run chmod +x .claude/hooks/block-rm.sh.

   Why: A command handler has to be executable on macOS and Linux.

   You should see: ls -l shows the execute bit set.

3. 3.In .claude/settings.json, register the script under PreToolUse with matcher Bash and if set to Bash(rm *).

   Why: The matcher limits the hook to Bash, and the if condition limits it further to rm commands.

   You should see: Claude Code loads the hook at the start of the next session.

4. 4.Ask Claude to delete a scratch directory with rm -rf.

   Why: The call matches both filters, so the handler runs and returns deny.

   You should see: The call is cancelled and Claude receives "Destructive command blocked by hook".

5. 5.Ask Claude to run ls.

   Why: The matcher passes it, but the if condition does not, so the handler never runs.

   You should see: The command goes through the normal permission flow.