Hook development

Hooks are shell commands that fire on harness events. They enforce conformity, inject context, and run quality gates without operator intervention.

Hook events

Hook message files

Each hook has a corresponding message file at src/apothem/hooks/messages/<event>-<name>.md that provides context to the assistant at the moment the hook fires.

Registering a hook

Add the hook command to settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python src/apothem/hooks/my-check.py"
          }
        ]
      }
    ]
  }
}

The hook dispatcher

All hooks route through src/apothem/hooks/dispatch.py, which converts any hook error to a fail-open envelope so hooks never block the harness.