Hooks For Data Pipeline Safety

Claude Code hooks are the most underused safety primitive in autonomous data work. A hook intercepts tool calls before they execute and can block, modify, or log any operation. Used well, hooks are how you enforce read-only by default, require approval on destructive actions, and keep the audit trail honest.

This guide walks through the hook types Data Workers uses in production, the specific safety patterns they enable, and the hook configuration that turns a raw Claude Code install into a production-grade data safety layer.

What Hooks Are

Hooks run at specific lifecycle events in a Claude Code session: before a tool call (PreToolUse), after a tool call (PostToolUse), on user message, on session start, on session stop. Each hook is a shell command that can inspect the event, make a decision, and return an allow, block, or modify action.

Pattern 1: Block Destructive SQL

A PreToolUse hook watches for SQL tool calls and parses the query. If the query contains DROP, TRUNCATE, or DELETE without WHERE, the hook blocks the call and returns an error message that the agent can read. This prevents destructive operations from ever reaching the warehouse, regardless of what the agent intends.

Pattern 2: Force Approval on Schema Changes

A PreToolUse hook on dbt run commands checks whether the run includes model changes that affect production schemas. If yes, the hook pauses the agent and surfaces an approval request in Slack. If no, the run proceeds automatically. This gives the agent autonomy on safe paths and gating on risky ones.

Pattern 3: Audit Logging

• •PostToolUse hook — writes every tool call to an append-only log
• •Structured JSON — captures tool name, input, output, timestamp, user, trace ID
• •Immutable storage — log ships to S3 or a SIEM for tamper-evidence
• •Searchable index — replays any failed run against the exact historical context
• •Cost attribution — token usage tagged per trace for billing and analysis
• •Compliance report — audit log exports directly to SOC 2 and ISO evidence format

Pattern 4: Read-Only Guard

A PreToolUse hook checks whether the current session has write access. If not, it blocks any write-capable tool (file edit, SQL write, HTTP POST to production endpoints) and returns a clear error. This is the runtime enforcement of the read-only default — the agent literally cannot write, even if its prompt tells it to.

Pattern 5: Cost Cap

A PostToolUse hook tracks token spend per session. When the session exceeds a configured budget, the hook terminates the agent and flags the run for review. This prevents runaway retry loops from cashing out at thousands of dollars. See autonomous data engineering.

Pattern 6: PII Redaction

A PreToolUse hook on any tool that returns data from the warehouse scans for PII patterns (email, SSN, phone) and redacts them before the data reaches the agent's context. This keeps sensitive data out of the LLM completely. See AI for data infrastructure for how PII middleware fits into the broader governance model.

Deploying Hooks in Practice

Hooks live in settings.json at the user or project level. Data Workers ships a reference hook pack that enables all six patterns with sensible defaults. Customize thresholds and destination endpoints for your environment. The hooks run on every Claude Code session, including interactive IDE sessions, CI runs, and scheduled agent jobs.

Hooks are how you turn Claude Code from a demo into a production-safe data agent platform. Six patterns, one settings file, no extra infrastructure. To see the hook pack deployed live, book a demo.

A practical example: the first time our team deployed Claude Code against a live warehouse, the agent attempted a DELETE on a staging table that shared a naming pattern with a production table. A PreToolUse hook blocked the call, logged the attempt, and returned an error message that the agent could read. The agent rephrased its approach, asked for human clarification, and the incident became a learning opportunity rather than a recovery exercise. Without the hook, we would have had a data loss incident on day one.

Hooks also make compliance auditable in a way that policy documents alone cannot. A SOC 2 auditor can read the hook configuration and immediately understand exactly which operations are blocked, logged, and escalated. This is much more convincing than a paragraph in a security document. The hook configuration becomes a machine-verifiable statement of intent, and auditors love machine-verifiable statements. Data Workers ships a reference hook pack that maps directly to SOC 2 control objectives for this reason.

Hook performance matters at scale. A PreToolUse hook that takes 500ms adds half a second to every tool call, which compounds across hundreds of calls in a long agent run. Keep hook logic simple and fast — parse the input, make a decision, return. Complex logic (database lookups, network calls) should be async or cached. Data Workers' reference hook pack is optimized for under 50ms per call, so the overhead is imperceptible.

Hook versioning is another operational consideration. When you update a hook, all active sessions should pick up the new version without needing to restart. Reference the hook as a file path (not an inline script) and update the file atomically. Data Workers ships hook packs as versioned directories with symlinks so rollbacks are one command. This operational discipline keeps hook updates safe and reversible, which is essential once hooks are in production.

PreToolUse blocks risky operations. PostToolUse captures audit evidence. Six patterns cover the full safety surface. Deploy once; trust everywhere.