Picture this: It's 6 AM. You sit down to start cooking with Claude Code. You open up the terminal and boot up Claude Code in YOLO mode because you can't be bothered with permissions. You run your handcrafted /sentient command that ships 100x faster than you ever could by hand.
But today, something goes wrong.
Your agent has gotten so good that it realizes what every senior engineer has realized: the best code is no code at all. Your agent starts deleting your codebase with the rm -rf command.
But thankfully... "All set and ready for the next step."
Nice.
The Power of Pre-Tool Hooks
Thankfully, instead of nuking all your code, you set up the pre-tool-use Claude Code hook to prevent the tool use from happening at all. Every rm command was completely blocked, and Claude Code even has a voice to let you know when it's finished.
Security Hook: Blocking Dangerous Commands
This is just the tip of the iceberg of what you can do with hooks.
The Six Lifecycle Hooks
Claude Code provides six deterministic hooks that let you intercept and control every aspect of your agent's lifecycle:
1. Pre-Prompt Hook
Fires before your prompt is processed. Perfect for:
- Prompt enhancement
- Context injection
- Security filtering
2. Pre-Tool-Use Hook
Fires before any tool is executed. Use for:
- Command validation
- Permission checks
- Audit logging
3. Post-Tool-Use Hook
Fires after tool execution. Great for:
- Result processing
- Error handling
- Notifications
4. Notification Hook
Fires when Claude needs user input. Enables:
- Custom alerts
- External notifications
- UI integrations
5. Stop Hook
Fires when the agent completes. Perfect for:
- Summary generation
- Cleanup tasks
- Final logging
6. Pre-Compact Hook
Fires before context compaction. Use for:
- Context preservation
- Important data extraction
- Memory management
Pro Tip: Hooks run in a separate process and can be written in any language. They receive JSON via stdin and can exit with status codes to control flow.
Building an Observable System
Let's build a complete logging system that captures every action your agent takes:
Comprehensive Logging Setup
The Logging Hook
Universal Logging Hook
Configuring Multiple Hooks
Claude Settings Configuration
Adding Voice Feedback
One of the most powerful patterns is adding natural language feedback to your agents:
Text-to-Speech Notification Hook
Real-World Impact: With voice notifications, you can run long-running async jobs and be notified when they complete, without constantly checking your terminal.
Advanced Patterns
Pattern 1: Security Filtering
Multi-Layer Security
Pattern 2: Smart Summarization
Using small, fast models to summarize actions:
AI-Powered Summaries
Pattern 3: Conditional Tool Access
Time-Based Permissions
Building a Complete Observability Dashboard
With hooks sending events, you can build a real-time dashboard:
Simple Event Server
Best Practices
1. Keep Hooks Fast
Hooks run synchronously and can slow down your agent. Keep them under 100ms.
2. Fail Gracefully
Don't let logging failures break your workflow:
3. Use Status Codes Wisely
- Exit 0: Allow continuation
- Exit 1: Block the action
- Exit 2+: Custom handling
4. Layer Your Hooks
Run multiple hooks for the same event—security first, then logging, then notifications.
5. Test Your Hooks
Testing Hooks Locally
Security Note: Always validate and sanitize data in your hooks. Remember that agents can generate arbitrary content.
The Future of Observable AI
Hooks are just the beginning. As we scale up multi-agent systems, observability becomes critical. You need to:
- Track Everything: Every decision, every action, every outcome
- Monitor in Real-Time: See what your agents are doing as they do it
- Control the Flow: Intervene when necessary, guide when helpful
- Learn from Patterns: Use logs to improve prompts and workflows
Taking Action
Start simple:
- Add a Basic Security Hook: Block
rm -rfand other dangerous commands - Set Up Simple Logging: Just save events to a file initially
- Add One Notification: Maybe just a sound when tasks complete
- Iterate and Improve: Add more sophisticated hooks as needed
Remember: Hooks give you deterministic control over non-deterministic systems. They're your safety net, your observability layer, and your automation enabler all in one.
The best part? This is all available today. No waiting for the next version. No complex setup. Just simple scripts that give you complete control over your AI agents.
Start with one hook. See the power. Then build your complete observability system.
Your agents are powerful. Now make them observable, controllable, and safe.