Hooks and gates for AI execution

Make AI actions auditable before you trust them to run unsupervised

After this, you'll be able to explain what hooks and gates are, write a simple pre-tool hook in Claude Code's settings, and use it to log or block specific agent actions.

Before you start

Complete MCP and Skills first; this lesson builds on understanding how Claude calls external tools and what happens at those call boundaries.

The idea

A hook is a script that fires automatically before or after an AI tool call. A gate is a hook that can stop execution if a condition fails. Together, hooks and gates are how you make AI-driven workflows auditable and safe enough to run without watching every step.

In Claude Code, you configure hooks in your settings file: a pre-tool hook runs before the agent calls a tool such as writing or deleting a file. A post-tool hook runs after the tool completes.

Here is the before and after: without hooks, an agent that deletes a file leaves no trace; you find out when the file is gone and have no record of when it happened or why. With a pre-tool hook that logs every write and delete to a timestamped file, you have a complete record, and you can add a gate that blocks any delete outside a specific directory.

Now try it: add a pre-tool hook to your Claude Code settings that logs the tool name and the target file path to /tmp/agent-log.txt every time the agent writes or edits a file. Run any small task, then open the log and confirm every file the agent touched appears there. Every gate condition you write after this depends on that log being accurate.

Try it (12 min)

Watch out for

Writing a hook that blocks all tool calls as a first step; start with logging only and add blocking conditions only after you have verified the log is accurate
Forgetting that hook scripts must be executable; run chmod +x on any script file before Claude can call it
Testing hooks only on successful paths; test what happens when the hook script fails or produces no output
Hardcoding absolute paths in hook scripts; they will break in CI and on any machine that is not yours. Use relative paths or environment variables instead.

Paste this into Claude

I am setting up hooks in Claude Code for [describe your project or workflow, e.g., a script that automates file cleanup or an agent that edits code files]. I want to add [describe the specific hook behavior, e.g., a pre-tool hook that logs all file write and delete actions, or a gate that blocks writes outside a specific folder]. For each hook: 1) write the exact shell script or command to use, 2) show me where in the Claude Code settings file to add it and in what exact format, 3) explain which event triggers it, and 4) describe what I should see when it fires. After I add it, give me a specific test command I can run to confirm the hook executed correctly and produced the expected output.

What good looks like

The hook script is a valid shell command you can run independently in a terminal to test before wiring it to Claude
You can read the Claude settings JSON entry and identify which event triggers the hook and what it does
After running a task, the log file or hook output exists and contains the data you expected
The hook fires on the specific tool call you targeted and not on unrelated tool calls

When this breaks

Breaks when the hook script is not executable because Claude silently skips the hook and continues execution as if it does not exist, leaving you with no log and false confidence
Breaks when a blocking gate has no fallback message because the agent stops with a cryptic error and you cannot tell whether the gate fired or the underlying task genuinely failed

You can now

Run a file-editing task, open the log file the hook was supposed to write, and confirm every file the agent touched appears in the log with a timestamp.

Key takeaways

Hooks fire before and after AI tool calls. Gates stop execution when a condition fails. Log first, then block; you need real data about what fires before you can write accurate conditions.

A hook is a script that fires before or after an AI tool call; a gate is a hook that can stop execution
Claude Code configures hooks in its settings file; pre-tool fires before, post-tool fires after
Add logging before you add blocking; you need real data about what fires before writing accurate gate conditions
A hook that fails silently is worse than no hook at all; test it standalone in a terminal before wiring it to Claude

Was this helpful?

← Back to lessons

I am setting up hooks in Claude Code for [describe your project or workflow, e.g., a script that automates file cleanup or an agent that edits code files]. I want to add [describe the specific hook behavior, e.g., a pre-tool hook that logs all file write and delete actions, or a gate that blocks writes outside a specific folder]. For each hook: 1) write the exact shell script or command to use, 2) show me where in the Claude Code settings file to add it and in what exact format, 3) explain which event triggers it, and 4) describe what I should see when it fires. After I add it, give me a specific test command I can run to confirm the hook executed correctly and produced the expected output.