Hooks use a defined JSON schema in standalone files at .kiro/hooks/*.json. This replaces the previous IDE .kiro.hook format with a structured, validated schema shared with the CLI — the same hook file works on every surface.
{ "version": "v1", "hooks": [ { "name": "format-on-save", "trigger": "PostFileSave", "matcher": "\\.ts$", "action": { "type": "command", "command": "prettier --write {{filePath}}" } } ] }
| Field | Required | Description |
|---|---|---|
version | Yes | Schema version — currently "v1" |
hooks[].name | Yes | Unique identifier for the hook |
hooks[].trigger | Yes | Event trigger name in PascalCase (see table below) |
hooks[].matcher | No | Regex pattern matched against the event subject |
hooks[].action.type | Yes | Action type: command or agent |
hooks[].action.command | Cond. | Shell command to run (when action.type: "command") |
hooks[].action.prompt | Cond. | Agent prompt to inject (when action.type: "agent") |
| Trigger | Fires when | Matcher matches | Can block? |
|---|---|---|---|
SessionStart | Session begins | — | No |
Stop | Agent execution completes | — | No |
UserPromptSubmit | You send a message | Prompt text | Yes |
PreTaskExec | Before a spec task starts | — | Yes |
PostTaskExec | After a spec task finishes | — | No |
PreToolUse | Before a tool executes | Tool name | Yes |
PostToolUse | After a tool executes | Tool name | No |
PostFileCreate | A new file is created by the agent | File path | No |
PostFileSave | A file is saved/modified by the agent | File path | No |
PostFileDelete | A file is deleted by the agent | File path | No |
Blocking: a command action that exits with code 2 blocks the triggering event (PreToolUse, UserPromptSubmit, PreTaskExec). Use this for policy enforcement — for example, block writes to *.env files. Any other non-zero exit code is treated as an error, not a block.
Legacy .kiro.hook trigger names map directly onto the new PascalCase triggers:
Old (when.type) | New (trigger) |
|---|---|
agentSpawn | SessionStart |
agentStop | Stop |
promptSubmit | UserPromptSubmit |
preToolUse | PreToolUse |
postToolUse | PostToolUse |
fileCreated | PostFileCreate |
fileEdited | PostFileSave |
fileDeleted | PostFileDelete |
preTaskExecution | PreTaskExec |
postTaskExecution | PostTaskExec |
userTriggered | Replaced by manual steering files — see below |
Your regex patterns transfer directly; the when/then structure becomes trigger/matcher/action. The IDE migrates hooks for you: open the Agent Hooks panel and click the upgrade badge on each legacy hook.
Manual hooks (the old userTriggered trigger) are replaced by manual steering files — markdown files in .kiro/steering/ invoked as /<filename> slash commands. See Steering.
command — runs a subprocess; receives JSON context on stdin. The {{filePath}} template variable is available for file-related triggers.agent — injects a prompt into the agent's context at trigger time. Use this to add conditional steering (e.g., "A test file was saved — check coverage"). Unlike command, it can't block the trigger.For the full reference (exit-code semantics, stdin payloads, global hooks in ~/.kiro/hooks/), see Hooks.
Hooks