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 (Playwright 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