2 min lesson
Hooks: the deterministic guardrail layer
Say what this means in practice. "Hooks are the one truly deterministic control: actual code, not a model's good intentions."
Step 1 of 3
Gates, SoDSeparation of Duties. Short for separation of duties: the rule that authoring, approving and deploying a change never sit with one person. Auditors use the acronym; the control is the same. Press Enter for the full definition. and evidence are process controls. Hooks are the one truly deterministic control: actual code, not a model's good intentions. A regulated CI/release story is missing a layer without them.
A hook is a script that executes in the shell at a fixed point in the agent's lifecycle, in the IDE and the CLI. Because it's real code that either passes or halts, it doesn't depend on the model behaving. The core release path covers prompt submit, file reads and edits, MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. and terminal calls, any tool call and stop. Put PIIPersonally Identifiable Information. Data that can identify a person (names, emails, SSNs); regulated and sensitive. Press Enter for the full definition. and secret scans before the prompt, path and command policy before tools act, a generic tool gate on every tool call and a final audit at stop.
Learn more
Advanced table
Hooks are build-once and share-across-team
- Trigger point
- Prompt submit:
beforeSubmitPrompt - When it fires
- Before a prompt reaches the model
- What you'd enforce there
- Scan for PIIPersonally Identifiable Information. Data that can identify a person (names, emails, SSNs); regulated and sensitive. Press Enter for the full definition., API keys and secrets; halt and return a custom error if found
- Trigger point
- Agent reads a file:
beforeReadFile; edits are observed withafterFileEdit - When it fires
- Before the agent reads a file
- What you'd enforce there
- Block reads of sensitive paths; audit any edit that introduces a private key
- Trigger point
- MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. tool call:
beforeMCPExecution - When it fires
- Before an external tool runs
- What you'd enforce there
- Gate which integrations an agent may invoke
- Trigger point
- Terminal tool call:
beforeShellExecution - When it fires
- Before a shell command runs
- What you'd enforce there
- Block destructive or non-allowlisted commands
- Trigger point
- Any tool call:
preToolUse - When it fires
- Before any tool runs
- What you'd enforce there
- Gate risky operations such as deleting protected files or SQL writes
- Trigger point
- Stop hook:
stop - When it fires
- When an agent run finishes
- What you'd enforce there
- Final scan or audit log before the work is handed off
| Trigger point | When it fires | What you'd enforce there |
|---|---|---|
Prompt submit: beforeSubmitPrompt | Before a prompt reaches the model | Scan for PIIPersonally Identifiable Information. Data that can identify a person (names, emails, SSNs); regulated and sensitive. Press Enter for the full definition., API keys and secrets; halt and return a custom error if found |
Agent reads a file: beforeReadFile; edits are observed with afterFileEdit | Before the agent reads a file | Block reads of sensitive paths; audit any edit that introduces a private key |
MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. Press Enter for the full definition. tool call: beforeMCPExecution | Before an external tool runs | Gate which integrations an agent may invoke |
Terminal tool call: beforeShellExecution | Before a shell command runs | Block destructive or non-allowlisted commands |
Any tool call: preToolUse | Before any tool runs | Gate risky operations such as deleting protected files or SQL writes |
Stop hook: stop | When an agent run finishes | Final scan or audit log before the work is handed off |
Hooks are build-once and share-across-team. Cloud agents run your repo's command-based hooks except the MCP ones, plus team hooks on Enterprise.
Learn more
Optional practice
Test yourself on Hooks: the deterministic guardrail layer
QA controls owner asks how you prevent a secret from ever reaching the model. What's the deterministic answer and why is it stronger than 'the model is trained not to'?
QWhich best describes how hooks relate to a pipeline's red gates?