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.

Not all hook triggers are available on every surface. Some triggers are specific to the IDE (task execution) or CLI (agent spawn). 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
• 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

Runs when the agent is first activated. No tool context is provided.

{
  "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

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, 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

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 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.

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

For MCP tools, the tool name includes the full namespaced format including the MCP server name:

{
  "hook_event_name": "preToolUse",
  "cwd": "/current/working/directory",
  "session_id": "abc123-def456-789",
  "tool_name": "@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.