Hooks: Standalone Files, New Triggers
v2 hooks lived inside an agent profile as an object keyed by camelCase trigger. v3 hooks are an array with PascalCase triggers, and they can live in their own files, project-wide or global. Hooks are for logic that rules cannot express; permissions remain the first line of control.
Three places a hook can live
| Placement | Applies to |
|---|---|
Agent profile hooks array | That agent only |
.kiro/hooks/*.json | This workspace, any agent; shared with the IDE |
~/.kiro/hooks/*.json | Every workspace (new: global hooks) |
Global and workspace hooks run alongside each other. /upgrade-agent converts v2 object hooks into the profile array and keeps camelCase triggers as aliases; use PascalCase when you write new ones.
The file
{
"version": "v1",
"hooks": [{
"name": "lint-on-save",
"trigger": "PostFileSave",
"matcher": "\\.(ts|tsx)$",
"action": { "type": "command", "command": "npx eslint --fix" },
"timeout": 30,
"enabled": true
}]
}
The action is either command (shell; gets session JSON on stdin; exit 0 puts stdout in the agent's context) or agent (injects a prompt). Default timeout is 60 seconds.
Triggers: renamed and new
| v2 | v3 | Notes |
|---|---|---|
agentSpawn | SessionStart | Old name still accepted |
userPromptSubmit | UserPromptSubmit | In the CLI it cannot block the prompt |
preToolUse | PreToolUse | Can block a tool call |
postToolUse | PostToolUse | Sees tool results |
stop | Stop | Supports a confirm prompt |
| — | SessionEnd | New |
| — | PreCompact, PostCompact | New in 3.1.0; exit 2 on Pre cancels compaction |
| — | PostFileCreate, PostFileSave, PostFileDelete | New; agent-made file changes; matcher is a regex on the path |
| — | PreTaskExec, PostTaskExec | New; around spec tasks |
Matchers for tool hooks
For PreToolUse and PostToolUse, the matcher is a tool ID, a category tag (read, write, shell, web, spec), a source selector (@builtin, @mcp, @server, @server/tool), a wildcard, or a regex.
A matcher containing regex metacharacters is evaluated as an unanchored regex against the internal tool ID. MCP tools arrive as mcp_<server>_<tool> in the event JSON. Prefer tags and @server/tool selectors.
The general Hook actions page says any non-zero exit blocks a PreToolUse call and sends stderr to the agent. Other Kiro tooling uses exit 2 as the block signal. Use exit 2 with a message on stderr, and confirm the behavior in the practice step.
Retrieval check
You want one hook to run in every workspace you open. Where does the file go?
Right. Global hooks in ~/.kiro/hooks/ fire in all workspaces and run alongside workspace hooks.
Profile hooks only apply to one agent, and per-repo files must be copied everywhere. Global hooks live in ~/.kiro/hooks/.
Which matcher targets only the query tool of an MCP server named postgres?
Right. @<server>/<tool> is the selector form for one MCP tool.
The selector syntax is @<server>/<tool>, so @postgres/query.
In the CLI, can a UserPromptSubmit hook stop your prompt from being sent?
Right. CLI prompt-submit hooks cannot block; use PreToolUse to gate actions.
The docs state CLI prompt-submit hooks cannot block. Blocking is for PreToolUse.
Practice
You already have scripts in ~/.kiro/hooks/ (for example deny-git.sh), so look at what is there first. Then add a guard in a new file so nothing existing is touched.
- List them:
ls ~/.kiro/hooks, and run/hooksin a V3 session to see what loaded. - Create
~/.kiro/hooks/block-rm-rf.json:{ "version": "v1", "hooks": [{ "name": "block-rm-rf", "trigger": "PreToolUse", "matcher": "shell", "action": { "type": "command", "command": "jq -r '.tool_input.command // \"\"' | grep -qE 'rm -rf' && { echo 'blocked: rm -rf' >&2; exit 2; }; exit 0" } }] } - In a scratch directory, ask Kiro to run
rm -rf ./tmp-test. It should be refused with your message. Then check thatlsstill runs. - Optional: change
exit 2toexit 1and see whether the call is still blocked. That settles the doc discrepancy for your version.
hooks objects into the v3 array, or into a standalone file. Anything unclear? Ask.