Hook-based safety guardrails

TL;DR

• Pre-tool hooks inspect tool call arguments before execution, blocking shell injection, path traversal, SQL injection, and credential access patterns with deterministic code rather than probabilistic LLM reasoning.
• Post-tool hooks scan tool results before returning them to the agent, preventing PII, secrets, and sensitive data from entering subsequent reasoning steps.
• Hooks are composable middleware: each hook has one responsibility and can be unit-tested independently without running the full agent. A typical production agent runs 5-10 hooks per tool call in under 20ms total.
• Deterministic code beats probabilistic prompts for safety enforcement. A regex check for rm -rf never fails because the model was distracted by a long context window.
• Limitation: hooks only catch what they're programmed to catch. Creative attacks that don't match known patterns slip through. Hooks are one layer in defense-in-depth, not a complete solution.

---

The Problem It Solves

Your autonomous coding agent runs overnight on a large refactoring task. At 3 AM, the agent decides the cleanest fix is rm -rf node_modules && npm install. Reasonable enough. Except it constructs the path wrong and runs rm -rf / instead. Your CI server is gone.

You could add "never run destructive commands" to the system prompt. That works 99% of the time. But 99% reliability on destructive operations means 1 in 100 runs nukes something. At 50 agent runs per day, you're looking at a catastrophic failure every two days.

The fundamental problem: system prompt safety instructions execute as probabilistic LLM reasoning. The model interprets them, weighs them against the task context, and sometimes decides the task is more important than the safety instruction. You can't build production safety on a mechanism that occasionally chooses to ignore your rules.

What Is It?

Hook-based safety guardrails are deterministic code functions that execute at defined interception points in the agent's tool-execution pipeline. Pre-tool hooks inspect arguments before a tool runs. Post-tool hooks inspect results before they return to the agent. Each hook enforces a single safety rule and either allows, warns, or blocks the operation.

Think of it as airport security. The TSA doesn't rely on passengers promising not to bring weapons (that's the system prompt approach). Instead, every bag goes through an X-ray machine (pre-tool hook) and every passenger walks through a metal detector (post-tool hook). The checks are deterministic, composable (add new scanners without changing existing ones), and independent of the passenger's intentions.

How It Works

The hook execution model

Every tool call in an agent framework passes through two interception points: pre-execution and post-execution. Each point runs an ordered chain of hook functions. If any pre-hook returns a "block" signal, the tool call is cancelled and the agent receives an error message explaining why. Post-hooks can redact, transform, or flag the output but typically can't undo execution (the tool already ran).

I've worked on agent systems where all the safety logic lived in the system prompt. It worked fine in demos. In production, with long conversations and complex multi-step tasks, the agent would "forget" safety instructions roughly once per 200 tool calls. Hooks eliminated that failure mode entirely.