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.

Prompt Submit

Triggers when the user submits a prompt.

When using the shell command action, the user prompt can be accessed via the USER_PROMPT environment variable.

Use Cases:

• Provide additional context to the agent relevant to the prompt
• Block certain prompts based on their content
• Log all user prompts to a central location

Agent Stop

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

Pre Tool Use

Triggers when the agent is about to invoke a tool.

In the Tool name field, provide the names of the specific tools for which this hook should execute. You can specify multiple entries. The following built-in categories are supported:

• read — all built-in file read tools
• write — all built-in file write tools
• shell — all built-in shell command-related tools
• web — all built-in web tools
• spec — all built-in spec tools
• * — all tools (built-in and MCP)

You can also use prefix filters to target tools by source:

• @mcp — all MCP tools
• @powers — all Powers tools
• @builtin — all built-in tools

Prefixes starting with @ are matched by regex, so you can use patterns like @mcp.*sql.* to match specific MCP tools by name.

You can ask Kiro for the names of the available tools.

Use Cases:

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

Post Tool Use

Triggers after the agent has invoked a tool.

For details on the Tool name field, refer to the Pre Tool Use section above.

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

File Create

Triggers when new files matching specific patterns are created 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

File Save

Trigger when files matching specific patterns are saved.

Use Cases:

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

File Delete

Triggers when files matching specific patterns are deleted.

Use Cases:

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

Pre Task Execution

Triggers before a spec task begins execution, when its status changes to in_progress.

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

Post Task Execution

Triggers after a spec task completes execution, when its status changes to completed.

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

Manual Trigger

Manually execute a hook.

Use Cases:

• On-demand code reviews
• Documentation generation
• Security scanning
• Performance optimization