feat: lifecycle hooks system

[michaelneale]

Summary

Adds a hooks module that lets users extend goose at key lifecycle points via shell commands or HTTP endpoints, configured in config.yaml.

Hook Events

• before_tool_call — fires before tool execution, can block (exit code 2)
• after_tool_call — fires after tool dispatch
• before_reply — fires when user message arrives
• after_reply / on_session_start / on_session_end — available via emit_hook() for CLI/server callers

Handler Types

• command — shell script, receives JSON on stdin, returns JSON on stdout
• url — HTTP POST endpoint, receives JSON body

Configuration

In ~/.config/goose/config.yaml:

hooks:
  before_tool_call:
    - matcher: "bash|write_file"
      hooks:
        - command: "~/.config/goose/hooks/safety-check.sh"
          timeout: 5
  after_tool_call:
    - hooks:
        - url: "http://localhost:9000/hook"

Wire Protocol

Scripts receive JSON on stdin:

{
  "event": "before_tool_call",
  "session_id": "abc123",
  "tool_name": "bash",
  "tool_input": {"command": "rm -rf /"},
  "working_dir": "/home/user/project"
}

Decisions via stdout JSON — supports three formats:

• Claude Code: {"decision": "block", "reason": "..."}
• Hermes: {"action": "deny", "message": "..."}
• Direct: {"block": true, "reason": "..."}

Or simply exit code 2 to block (no JSON needed).

Design

Based on research of hooks in Pi, Hermes, and Claude Code:

• Fail-open: broken hooks log warnings, never crash the agent
• Matcher filtering: regex against tool name for tool events
• Short-circuit: first block wins for before_tool_call
• Zero overhead: has_hooks() fast-path skips when no hooks configured

cc @DOsinga for interest

[quancore]

@michaelneale this is very important feat, waiting

[alexhancock]

Closing this (per @michaelneale's OK in slack) because we have these going now

#9093
#9112