Hooks
Automated reactions to events -- validation gates and workflow triggers
What is a Hook?
A shell script that runs automatically when something happens during an AI session.
Event-Driven Automation
Hooks are like git hooks but for AI sessions. They fire on lifecycle events:
- SessionStart — when the AI session begins
- PreToolUse — before the AI calls a tool (can block it)
- PostToolUse — after the AI finishes calling a tool
- SessionStop — when the AI session ends
Real Examples from KAI
Hooks that run in production every day.
SessionStart: Environment Validation
Validates .ai/config.yaml exists and Node version matches .nvmrc. Fails fast if the environment is misconfigured.
PreToolUse: Branch Guard
Blocks git commit on protected branches (main, master, development, develop).
Prevents accidental commits to the wrong branch.
PostToolUse: Figma Screenshot
Automatically saves screenshots from the Figma MCP to disk. Avoids repeated MCP calls for the same design during a session.
PostToolUse: Subagent Log
Logs a timestamp every time a subagent completes. Useful for debugging long-running autonomous pipelines.
Hook File Format
A single hooks.json file defines all hooks for the project.
{
"version": 1,
"hooks": {
"SessionStart": [{
"matcher": "",
"hooks": [{
"type": "command",
"command": "bash session-start.sh"
}]
}],
"PreToolUse": [{
"matcher": "Bash(git commit*)",
"hooks": [{
"type": "command",
"command": "bash branch-guard.sh"
}]
}]
}
} version: 1
Setting version: 1 makes the hooks file work in both Claude Code and
Copilot CLI (v1.0.6+). A single file, dual compatibility.
Hook Merging (Copilot CLI v1.0.11+)
Multiple plugins can contribute hooks without overwriting each other.
Multi-Plugin Hooks
Before v1.0.11, if both dx-core and dx-aem defined hooks, one would overwrite the other. Now hooks from multiple extensions merge — each plugin contributes its own hooks and they all fire correctly.
SessionStart Context Injection
SessionStart hook additionalContext is now injected into the conversation.
Our session-start.sh and next-step.sh hooks now surface active specs
and pending steps in Copilot CLI sessions — previously this context was lost.
What This Means for KAI
dx-core owns general hooks (branch guard, subagent log, Figma screenshots).
dx-aem now has its own hooks.json for AEM full-flow hooks (Chrome DevTools screenshots, component inspection, editorial capture).
Both plugins’ hooks fire in the same session without conflict.
When to Use Hooks vs Skills
Different tools for different jobs.
Hooks
- Automatic — fire without user input
- Deterministic — shell scripts, no AI reasoning
- Fast — milliseconds, no token cost
- Best for: validation gates, caching, logging
Skills
- Interactive — user invokes with /command
- AI-driven — reasoning and judgment
- Flexible — adapts to context
- Best for: complex tasks, code generation, analysis