Skip to main content

Hooks

Declarative condition → action pairs on runtime events. Declared under runtime.hooks[] or agents[].hooks[]. Schema: internal/compiler/schema/hooks.go. Evaluation: internal/runtime/hooks.

Always quote YAML "on" (YAML 1.1 treats bare on: as boolean).

Shape​

FieldNotes
idUnique id
"on"Hook event (below)
condition{type, ...}
action{type, ...}
cooldown, max_fires, priority, enabled, tagsOptional controls

Events (AllHookEvents)​

Canonical / aliases include: turn_start (user_prompt), turn_end, stop, tool_start (pre_tool_use), tool_end (post_tool_use), pre_finish, session_start, session_end, pre_compact, error, approval_request, agent_spawn, agent_complete, activation.

NotYetRoutedHookEvents in schema currently marks agent_spawn, agent_complete, and activation as not routed at the hook layer (activation remains declared-only). Prefer events you see fired in internal/runtime/engine.go (session_start, turn_start/end, tool_start/end, error, approval_request, stop, ...).

Conditions (14)​

always, never, context_pressure, turn_count, tool_calls, message_count, tool_name, tool_failed, content_contains, error_type, expression, all_of, any_of, not.

Actions (AllHookActions)​

compact_context, inject_message, module_action, module_action_inject, log, shell, gate, transform_params, transform_result, chain, notify, pipe, lsp_diagnose, compile_yaml, auto_test_deploy (plus noop as a type constant).

Example:

yaml
runtime:
  hooks:
    - id: lint_after_write
      "on": tool_end
      condition:
        type: tool_name
        match: "filesystem.write"
      action:
        type: module_action
        module: lsp
        action: diagnostics
      enabled: true