extension-hooks-events

name	Extension: Hooks & Events
description	Hook catalog, lifecycle events, hook scripts, and event-driven automation

Extension: Hooks & Events

Hooks are event handlers that fire on system lifecycle events. They enable plugins to react to sessions, tool executions, agent activity, and user interactions.

---

1. Hook Events

Event	Trigger	Use Cases
tracking_session_start	User session begins	Initialize tracking
tracking_session_end	User session ends	Finalize analytics
tracking_post_tool_use	Tool executed successfully	Log tool usage
tracking_post_tool_use_failure	Tool execution failed	Alert on failures
tracking_subagent_start	Sub-agent spawned	Track agent lifecycle
tracking_subagent_stop	Sub-agent stopped	Cleanup
tracking_stop	Application shutdown	Graceful cleanup
tracking_user_prompt_submit	User submits prompt	Input validation

---

2. Hook Catalog

The hook catalog (hook_catalog table) stores hook definitions.

Schema

CREATE TABLE IF NOT EXISTS hook_catalog (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name TEXT NOT NULL UNIQUE,
    description TEXT,
    version TEXT NOT NULL DEFAULT '1.0.0',
    event TEXT NOT NULL,
    matcher TEXT,
    command TEXT NOT NULL,
    is_async BOOLEAN NOT NULL DEFAULT true,
    category TEXT,
    tags TEXT[],
    enabled BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

---

3. Hook Directory Structure

services/hooks/
  tracking_post_tool_use/
    my-hook.sh
  tracking_session_end/
    cleanup.sh
  tracking_session_start/
    init.sh
  tracking_stop/
    save-state.sh
  tracking_subagent_start/
    track-agent.sh
  tracking_user_prompt_submit/
    validate-input.sh

Hook Script Format

#!/bin/bash
set -euo pipefail

# Environment variables available:
# $HOOK_EVENT - Event type
# $HOOK_DATA - JSON payload with event details
# $SYSTEMPROMPT_PROFILE - Profile path

---

4. Async vs Blocking Hooks

Mode	Behavior	Use Case
Async (is_async: true)	Fire-and-forget	Logging, analytics, notifications
Blocking (is_async: false)	Waits for completion	Validation, authorization

Blocking hooks must complete within 5 seconds.

---

5. Hook Debugging

systemprompt core hooks list

HOOK_EVENT=tracking_session_start HOOK_DATA='{"session_id":"test"}' bash services/hooks/tracking_session_start/my-hook.sh

---

6. Rules

Rule	Rationale
Hook names must be unique	Catalog keyed by name
Scripts must be executable (chmod +x)	Shell execution requires permission
Use set -euo pipefail in scripts	Fail fast on errors
Prefer async hooks	Blocking hooks slow the pipeline
Hook data is JSON	Structured payload via $HOOK_DATA
Blocking hooks timeout at 5 seconds	Prevents hung pipelines