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. Web can store Hook configuration for later local use, but Web sessions do not run these 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 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.

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.