Hooks: Standalone Files, New Triggers

Lesson 2 · Kiro CLI v3 for v2 users. Time: 12 minutes. Tangible win: a working global PreToolUse guard.

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.

Primary source Hooks — kiro.dev. Schema, locations, confirmation prompts. About 10 minutes; also skim Hook types.

Three places a hook can live

PlacementApplies to
Agent profile hooks arrayThat agent only
.kiro/hooks/*.jsonThis workspace, any agent; shared with the IDE
~/.kiro/hooks/*.jsonEvery 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

v2v3Notes
agentSpawnSessionStartOld name still accepted
userPromptSubmitUserPromptSubmitIn the CLI it cannot block the prompt
preToolUsePreToolUseCan block a tool call
postToolUsePostToolUseSees tool results
stopStopSupports a confirm prompt
—SessionEndNew
—PreCompact, PostCompactNew in 3.1.0; exit 2 on Pre cancels compaction
—PostFileCreate, PostFileSave, PostFileDeleteNew; agent-made file changes; matcher is a regex on the path
—PreTaskExec, PostTaskExecNew; 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.

Regex trap

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.

Docs disagree slightly: test it

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.

  1. List them: ls ~/.kiro/hooks, and run /hooks in a V3 session to see what loaded.
  2. 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"
        }
      }]
    }
  3. In a scratch directory, ask Kiro to run rm -rf ./tmp-test. It should be refused with your message. Then check that ls still runs.
  4. Optional: change exit 2 to exit 1 and see whether the call is still blocked. That settles the doc discrepancy for your version.
Ask me to convert one of your existing v2 agent hooks objects into the v3 array, or into a standalone file. Anything unclear? Ask.