Hooks

Run custom scripts before or after Agent Nine actions.

Setup

Create .agent-nine/hooks.json in your project:

{
  "hooks": [
    {
      "event": "pre_tool_use",
      "match": { "tool_name": "bash" },
      "command": "echo 'About to run bash command'",
      "timeout_ms": 5000
    },
    {
      "event": "post_tool_use",
      "match": { "tool_name": "edit_file" },
      "command": "npx prettier --write $FILE_PATH",
      "timeout_ms": 10000
    },
    {
      "event": "session_start",
      "command": "echo 'Session started at $(date)' >> .agent-nine/log.txt"
    }
  ]
}

Hook Events

Event	When
pre_tool_use	Before any tool is executed
post_tool_use	After any tool completes
session_start	When a new session begins
session_end	When a session is closed

Match Filters

Hooks with match only run when the filter matches:

{
  "match": {
    "tool_name": "bash",
    "pattern": "npm *"
  }
}

Context

Hook commands receive JSON context on stdin:

{
  "event": "pre_tool_use",
  "tool_name": "bash",
  "tool_input": { "command": "npm test" },
  "session_id": "abc-123"
}

Timeouts

• Default: 60 seconds
• Maximum: 10 minutes
• If a hook times out, it's killed and the tool execution continues