Hooks — deterministic gates around an agent

At a glance

Learning objectives

• Explain where hooks run — on tool-call and pre-run events, outside the model
• Match each safety hook to the failure it prevents
• Wire the two starter hooks every agent repo should have

What you need

• An agent host with hook support
• A data repository and a non-production database target
• The DE Data Toolkit plugin, which wires the destructive-SQL guard and the secret scanner

Steps

1. A hook is a deterministic gate — the destructive SQL guard intercepts DROP / TRUNCATE / DELETE-without-WHERE before an agent executes it. (from hook-destructive-sql-guard )
2. Its policy — destructive statements are denied by default; a DELETE/UPDATE without a WHERE clause is always denied; non-production targets can be allowed with a --allow-destructive flag that requires a human confirmation token. (from hook-destructive-sql-guard )
3. Production writes get a human gate — any write-class tool against a production target, classified by connection string, project or catalogue tag, is suspended for an approve-once token scoped to the single call. (from hook-prod-write-confirm )
4. Secrets never reach the repo — staged diffs are scanned for high-confidence secret patterns (AWS keys, private key headers, connection strings with passwords, JWTs); entropy-based detection warns, pattern matches block the commit. (from hook-secret-scan-commit )
5. Gates also run before a job starts — the backfill safety check refuses to start a backfill that lacks a rollback path or overlaps the daily run. (from hook-backfill-safety-check )
6. The starter plugin wires two of them for you — hook-destructive-sql-guard and hook-secret-scan-commit. (from plugin-de-data-toolkit )
7. Encode the whole safety policy as hooks — destructive SQL guard, prod write confirmation — so it holds even when the agent is prompted otherwise. (from pattern-agent-in-the-loop-review )

Check yourself

• A `DROP TABLE prod.orders` from the agent is denied and surfaced for confirmation — before any database call.
• A write against prod.sales is suspended until a human issues an approve-once token scoped to that single call.

Worked example

Matches the SQL string passed to a database/MCP tool. Destructive statements
are denied by default; a DELETE/UPDATE without a WHERE clause is always denied.
Statements on a non-production target can be allowed with a `--allow-destructive`
flag that requires a human confirmation token.

Failure behavior: block.

Classify the tool target as production by connection string, project or
catalogue tag. Any write-class tool against a production target is suspended
and surfaced for a human "approve once" token scoped to the single call.

Scan staged diffs for high-confidence secret patterns (AWS keys, private key
headers, connection strings with passwords, JWTs). Entropy-based detection runs
as a warning; pattern matches block the commit.

Sourced from

• Destructive SQL Guard
• Production Write Confirmation
• Secret Scan on Commit
• Backfill Safety Check
• DE Data Toolkit
• Agent-in-the-Loop Review

Security scan

Last sweep 2026-10-24: 0 finding(s), 0 marked as examples.

Common gotchas

• Destructive statements are denied by default — there is no flag that lets a DELETE/UPDATE without a WHERE through.
• Entropy-based secret detection warns; pattern matches block — a warning is not a pass.
• The guard's failure behavior is block — when it matches, the tool call does not proceed.

Production considerations

• Keep hook-destructive-sql-guard and hook-secret-scan-commit active on every repo agents commit to.
• The approve-once token is scoped to the single call — no standing write approvals.

Diagram

agent tool call
   |
   |- on-tool-call --> destructive SQL guard --> DROP/TRUNCATE/DELETE-no-WHERE --> block
   |
   |- write-class tool --> prod target --> suspend --> approve-once token
   |
   |- pre-commit --> secret scan --> pattern match --> block
   |
   |- pre-run --> backfill safety --> rollback path + no daily-run overlap

Registry stats