How to Control Claude Code Agents with Hooks

TL;DR

Claude Code hooks provide control and observability by running commands at defined points in an agent’s lifecycle. Pre-tool hooks can block dangerous commands, while post-tool, notification, stop, and sub-agent stop hooks can record activity, request attention, preserve conversations, and announce task completion, making long-running and parallel agent sessions easier to monitor and improve.

Transcript

engineers. I'm hooked on Claw Code hooks. Once you see this, you will be too. Imagine this. It's 6:00 a.m. in the morning. You sit down to start cooking with Claude Code. You open up the terminal and you boot up Claude Code in YOLO mode because you can't be bothered with permissions. You run your handcrafted/scentient command that ships 100x faster... Read More

Key Insights

• Pre-tool use is a control point that runs before a tool executes and can block unwanted operations. The demonstrated configuration inspects incoming tool activity and prevents rm commands, protecting the codebase even when Claude Code runs with permissive settings.
• Post-tool use is an observability point that runs after a tool finishes. It can record executed operations, create structured JSON logs, or send notifications, giving engineers evidence of what an agent did during a coding session.
• The notification hook is triggered when Claude Code needs user input. The example connects this event to a natural-language voice alert when the agent lacks permission to run a Bun command, allowing the engineer to return and approve or reject it.
• The stop hook runs whenever Claude Code finishes responding. The demonstrated setup uses this moment to copy the complete chat conversation into a file, preserving the finished interaction for later review, debugging, and analysis.
• The sub-agent stop hook reports when an individual delegated task completes. In the parallel example, four sub-agents inspect separate log files and announce their completion individually, which helps track concurrent work without continuously watching the terminal.
• Hook configuration is stored in the hooks block of settings.json. Each lifecycle event accepts arrays containing matchers and hook commands, while an empty matcher causes the associated command to run for every applicable tool invocation.
• Standalone Python hook scripts are executed with Astral UV. This arrangement lets each script declare and install its own required dependencies, keeping hook functionality isolated from the structure and dependency configuration of the main codebase.
• Agent observability is the foundation for systematic improvement because recorded tool activity and chat history reveal what happened. The presented logs make agent behavior inspectable, helping engineers analyze results, identify problems, and iterate on their agentic workflows.

Questions & Answers

Q: How do Claude Code hooks prevent dangerous commands?

A pre-tool use hook runs before Claude Code executes a tool, so it can inspect the incoming operation and stop it before any damage occurs. In the demonstration, the hook blocks rm commands, preventing an agent from deleting the codebase. This provides a control layer even when Claude Code is started with permissive settings and would otherwise execute commands without repeated approval.

Q: What Claude Code hook events are demonstrated?

The demonstrated setup uses five events: pre-tool use, post-tool use, notification, stop, and sub-agent stop. Pre-tool use runs before a tool and can block it. Post-tool use runs afterward for logging. Notification fires when user input is needed. Stop runs after Claude Code finishes responding, while sub-agent stop runs when an individual delegated task completes.

Q: How can Claude Code hooks improve agent observability?

Hooks can create records at multiple points throughout an agent’s lifecycle. Post-tool use can log completed tool operations, while the stop hook can preserve the entire conversation after a response finishes. These records show what the agent attempted, what it executed, and what it produced, giving engineers material for debugging, analysis, measurement, and iterative improvement of agentic workflows.

Q: How are Claude Code hooks configured in settings.json?

Hooks are defined in a dedicated hooks block inside settings.json. The block contains entries named for lifecycle events, and each event holds a list of matcher configurations and hook commands. A matcher can target particular activity, while an empty matcher makes the hook run for every applicable tool. The command list also allows multiple commands to be associated with an event.

Q: Why use the Claude Code stop hook for chat logging?

The stop hook runs after Claude Code has finished responding, making it a suitable point to capture the completed interaction. The demonstrated implementation copies the entire chat conversation into a file at that moment. This saved history can later reveal what happened, support debugging, and provide material for evaluating and improving the agent’s prompts, behavior, and results.

Q: How do voice notifications help with long-running agent tasks?

Voice notifications tell the engineer when Claude Code needs input or has completed work, reducing the need to watch the terminal continuously. The example announces top-level completion, permission requests, and individual sub-agent completions. This is useful when jobs run for 20–30 minutes or longer, when several Claude Code sessions are active, or when the engineer steps away while agents work.

Q: How does the sub-agent stop hook support parallel work?

The sub-agent stop hook fires as each delegated subtask finishes. In the example, four parallel sub-agents examine the first 20 lines of separate JSON log files and produce concise TypeScript interface definitions. Each agent reports completion individually through text-to-speech, allowing the engineer to follow progress across concurrent tasks without loading every large file into the main context.

Q: Why are Astral UV single-file scripts used for hooks?

The hook implementation uses standalone Python files executed through Astral UV. According to the demonstration, each single-file script can run with a simple command and install the dependencies it needs. This keeps hook functionality isolated from the main project, allowing the same pre-tool, post-tool, notification, stop, and sub-agent scripts to operate regardless of how the surrounding codebase is organized.

Summary & Key Takeaways

• Claude Code hooks can execute custom commands before or after tools run, when user input is required, and when primary or sub-agent responses finish. The demonstrated setup uses these lifecycle events to block dangerous shell commands, create structured logs, save conversations, and generate spoken notifications for unattended or long-running coding sessions.

• Hooks are configured in the hooks block of settings.json. Each event contains a list of matchers and commands, allowing a hook to target selected tools or run for every tool when its matcher is empty. Multiple commands can be attached, supporting flexible safety, logging, notification, and analysis workflows.

• The implementation organizes five hook scripts and supporting utilities in a dedicated hooks directory. Standalone Python scripts run through Astral UV, allowing dependencies to be installed for each script independently of the surrounding codebase. The resulting logs expose agent actions and conversations for debugging, measurement, iteration, and systematic improvement.