AI agent
Hooks intro
Hooks slot code around tool calls — gate, audit, inject context.
What hooks are
A hook is any executable script you write (any language) that Kition fires at specific points around agent tool calls. It can read inputs, mutate inputs, block the call outright, or inject extra messages back to the agent.
Think Express middleware — but for AI tool calls instead of HTTP requests. Compliance, auditing, and custom tool capabilities all ride on this layer.
The four hook moments
PreToolUse— before a tool runs; can mutate args or blockPostToolUse— after a tool returns; can mutate result or logPreCompact— before the agent compacts contextStop— after the agent finishes a turn
Where to put them
<vault>/.kition/hooks.json is vault-level, lives with the repo (good for teams). ~/.kition/hooks.json is global and only applies on your machine. When both exist, vault-level runs first.
Settings → Agent → Hooks also exposes a GUI editor that writes to the same JSON.
A simple Bash gate hook
{
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "node .kition/hooks/check-bash.js",
"timeout_ms": 3000
}
]
}
]
}The matching check-bash.js
const input = JSON.parse(require('fs').readFileSync(0, 'utf8'))
const cmd = input.tool_input.command || ''
const DANGEROUS = [/\brm\s+-rf\b/, /\bsudo\b/, /:\(\)\{/]
if (DANGEROUS.some((rx) => rx.test(cmd))) {
console.log(JSON.stringify({
decision: 'block',
reason: 'Blocked by hook: dangerous pattern in command.',
}))
process.exit(0)
}
console.log(JSON.stringify({ decision: 'allow' }))What people actually use them for
- Audit logs: append every Write to a log file for postmortem
- Project conventions: inject "use 2-space indent" before every Edit
- Last-mile safety: block reads of
.envor customer-data dirs - Custom tools: intercept a non-existent tool in PreToolUse and answer it yourself
- Cost gate: stop a chat after 50 tool calls in a single turn