Hooks Configuration

Introduction

Hooks are user-defined shell commands or LLM instructions that execute automatically at specific points in the Hawa Code lifecycle. Use this reference to find event schemas, configuration options, JSON input/output formats, and advanced features like asynchronous hooks.

Hook Lifecycle

Hooks trigger at specific points during a Hawa Code session. When an event fires and the matcher matches, Hawa Code passes JSON context about the event to your hook handler. For command hooks, input arrives via stdin. Your handler can then inspect the input, take action, and optionally return a decision. Some events fire once per session, while others fire repeatedly within the agent loop.

  • Stop - Triggered when the main Agent conversation ends
  • SubagentStop - Triggered when the Subagent conversation ends
  • SubagentStart - Triggered before the Subagent starts execution
  • PreToolUse - Triggered after tool parameters are created and before tool execution
  • PostToolUse - Triggered after a tool is successfully executed
  • PostToolUseFailure - Triggered when a tool execution fails
  • SessionStart - Triggered when a session starts or resumes
  • SessionEnd - Triggered when a session ends

Hooks Configuration

  • Project Level: {project_path}/.hcode/settings.json
  • User Level: ~/.hcode/settings.json

Matcher

Hooks support Matcher for matching tool names or Subagent names. Matching rules are as follows:

  • Single Match: Match a single attribute, e.g., "Edit".
  • Multiple Matches: Use pipe | to separate multiple attributes, e.g., "Edit|Write".
  • Wildcard Match: Use * for wildcard matching, e.g., "mcp__memory__.*", "mcp__.*__write.*", "mcp__.*__write.*|Edit".
Next