Building Hooks in Claude Code

Hooks in Claude Code allow you to intercept and control tool calls before or after they execute. This gives you fine-grained control over what Claude can and cannot do in your development environment.

Building a Hook

Creating a hook involves four main steps:

1. Decide on a PreToolUse or PostToolUse hook - PreToolUse hooks can prevent tool calls from executing, while PostToolUse hooks run after the tool has already been used
2. Determine which type of tool calls you want to watch for - You need to specify exactly which tools should trigger your hook
3. Write a command that will receive the tool call - This command gets JSON data about the proposed tool call via standard input
4. If needed, command should provide feedback to Claude - Your command's exit code tells Claude whether to allow or block the operation

Available Tools

Claude Code provides several built-in tools that you can monitor with hooks:

• Read - Reading file contents
• Write - Writing to files
• Edit - Editing existing files
• MultiEdit - Editing multiple files
• Grep - Searching file contents
• List - Listing directory contents
• Execute - Running shell commands

To see exactly which tools are available in your current setup, you can ask Claude directly for a list. This is especially useful since the available tools can change when you add custom MCP servers.

Tool Call Data Structure

When your hook command executes, Claude sends JSON data through standard input containing details about the proposed tool call:

{
  "session_id": "2d6a1e4d-6...",
  "transcript_path": "/Users/sg/...",
  "hook_event_name": "PreToolUse",
  "tool_name": "Read",
  "tool_input": {
    "file_path": "/code/queries/.env"
  }
}

Your command reads this JSON from standard input, parses it, and then decides whether to allow or block the operation based on the tool name and input parameters.

Exit Codes and Control Flow

Your hook command communicates back to Claude through exit codes:

• Exit Code 0 - Everything is fine, allow the tool call to proceed
• Exit Code 2 - Block the tool call (PreToolUse hooks only)

When you exit with code 2 in a PreToolUse hook, any error messages you write to standard error will be sent to Claude as feedback, explaining why the operation was blocked.

Example Use Case

A common use case is preventing Claude from reading sensitive files like .env files. Since both the Read and Grep tools can access file contents, you'd want to monitor both tool types and check if they're trying to access restricted file paths.

This approach gives you complete control over Claude's file system access while providing clear feedback about why certain operations are restricted.