Hook types

Agent hooks support various trigger types, each designed for specific automation scenarios. Understanding these types helps you choose the right approach for your workflow needs.

This page describes standalone Hook definitions stored in .kiro/hooks/*.json. Inline profile Hooks have separate current and legacy forms; see the agent configuration reference.

File and task triggers are available in the IDE and CLI V3. Kiro Web sessions run the Prompt Submit, Agent Stop, Session Start, Pre Tool Use, and Post Tool Use triggers. The table below shows what's supported where.

Triggers when the user submits a prompt.

Use Cases:

• Provide additional context to the agent relevant to the prompt
• Block certain prompts based on their content (IDE only; CLI Prompt Submit Hooks cannot block)
• Log all user prompts to a central location

Triggers when the agent has completed its turn and finished responding to the user.

Use Cases:

• Compile code and report any failures to the agent
• Format or review any agent-generated code
• Review changes made by agent and provide additional instructions

Triggers when a new chat session starts in the IDE or CLI V3.

Use Cases:

• Inject workspace-specific instructions into the agent's context
• Run environment checks (verify dependencies, validate credentials)
• Load project-specific configuration at session start

CLI 2.x used agentSpawn when the agent was first activated. CLI V3 uses SessionStart as the canonical trigger but accepts AgentSpawn and agentSpawn for compatibility. The event provides no tool context.

{
  "hook_event_name": "agentSpawn",
  "cwd": "/current/working/directory",
  "session_id": "abc123-def456-789"
}

Exit Code Behavior:

• 0: Hook succeeded, STDOUT is added to agent's context
• Other: Show STDERR warning to user

Use Cases:

• Set up environment context when a session starts
• Load project-specific configuration
• Initialize logging or auditing systems

The SessionEnd trigger fires when a CLI V3 session is torn down.

Triggers before Kiro compacts a conversation. In Kiro IDE, compaction is automatic, so the Hook runs when the session approaches the model's context limit; see Compaction. This trigger takes no matcher.

In Kiro IDE 1.4.121 or later, choose Pre Compaction from the Compaction Hooks group in the Hook editor's trigger list.

In Kiro CLI 3.1.0 or later, the PreCompact trigger fires before a CLI V3 session compacts its conversation. Compaction runs when you run /compact, when automatic summarization starts, when Kiro recovers from a context overflow, and when Kiro hands the session to another model.

Exit Code Behavior:

• 0: Compaction continues. In the IDE, Kiro gives the command's standard output to the summarizer as guidance. In CLI V3, STDOUT is added to the agent's context, up to 3,000 characters.
• 2: Cancel the compaction. In the IDE, Kiro reports STDERR as the reason, and the turn continues without compacting unless the context is nearly full. In CLI V3, the conversation stays as it is.

Use Cases:

• Save a snapshot of current work before older history is summarized
• Refuse compaction while a task you track outside Kiro is still open

Triggers after Kiro has compacted a conversation and the summary has replaced the older history. The Hook's output is added to the conversation, so the agent keeps details the summary left out. This trigger takes no matcher.

In Kiro IDE 1.4.121 or later, choose Post Compaction from the Compaction Hooks group in the Hook editor's trigger list.

In Kiro CLI 3.1.0 or later, the PostCompact trigger fires after a CLI V3 session compacts its conversation. The event JSON on STDIN includes summary, up to 3,000 characters of the summary text, and summary_path, the file containing the full summary. The Hook cannot undo the compaction or change the summary.

Use Cases:

• Restore task-specific guidance after compaction
• Archive each summary for review
• Record when a long session was compacted and what the summary kept

Triggers when the agent is about to invoke a tool. Can validate and block tool usage.

Use Cases:

• Block certain tool invocations
• Validate tool inputs before execution
• Provide additional instructions to the agent before it invokes a tool

Triggers after the agent has invoked a tool, with access to tool results.

Use Cases:

• Log tool invocations for auditing purposes
• Format or review any updated files after a "write" tool call
• Provide additional instructions to the agent on top of the tool response

Triggers when the agent creates new files matching specific patterns in your workspace.

Use Cases:

• Generate boilerplate code for new components
• Add license headers to new files
• Set up test files when creating implementation files

Triggers when the agent saves or modifies files matching specific patterns.

Use Cases:

• Run linting and formatting
• Update related files
• Generate documentation
• Run tests for changed files

Triggers when the agent deletes files matching specific patterns.

Use Cases:

• Clean up related files
• Update import references in other files
• Maintain project integrity

Triggers before a spec task begins execution.

Use Cases:

• Run setup scripts or environment preparation before task execution
• Validate prerequisites are met before a task starts
• Log task start events for tracking

Triggers after a spec task completes execution.

Use Cases:

• Run tests after a task completes to verify correctness
• Run linting or formatting on changed files
• Generate documentation for completed work
• Notify external systems of task completion

CLI V3 recognizes and lists Manual Hook definitions, but /hooks doesn't provide an action to invoke them.

In Kiro Web, you can choose Manual as the trigger when you create a Hook under Agent Config > Hooks.

Manual Hooks created in IDE 0.x continue to appear in the Agent Hooks panel with a legacy label. Enabled legacy manual Hooks remain runnable using the play button next to the Hook name or Start Hook in the Hook view.

IDE 0.x userTriggered Hooks don't have a v1 IDE trigger equivalent, and you can't create a new Manual-trigger Hook in the IDE. For a new IDE on-demand workflow, create a manually included Steering file; it runs as a /<filename> slash command.

For MCP tools, V3 Hook events use the sanitized internal tool ID mcp_<server>_<tool>, not the @server/tool display name:

{
  "hook_event_name": "PreToolUse",
  "cwd": "/current/working/directory",
  "session_id": "abc123-def456-789",
  "tool_name": "mcp_postgres_query",
  "tool_input": {
    "sql": "SELECT * FROM orders LIMIT 10;"
  }
}

This applies to both Pre Tool Use and Post Tool Use Hooks when targeting MCP server tools. In the Hook's matcher, use either the @<server> or @<server>/<tool> selector or a regex against the internal ID.