Module Proto.Hooks

Claude Code Hooks System - Wire Format

This module defines the wire format for hook configuration. Hooks allow you to intercept and control events in Claude Code sessions, such as tool usage, prompt submission, and session stops.

Overview

Hooks are organized by event type, with each event having:

This is the wire format module - it does not include the callback system or Eio dependencies. For the full hooks system with callbacks, see the Hooks module in the lib directory.

Hook Events

type event =
  1. | Pre_tool_use
    (*

    Fires before a tool is executed

    *)
  2. | Post_tool_use
    (*

    Fires after a tool completes

    *)
  3. | User_prompt_submit
    (*

    Fires when user submits a prompt

    *)
  4. | Stop
    (*

    Fires when conversation stops

    *)
  5. | Subagent_stop
    (*

    Fires when a subagent stops

    *)
  6. | Pre_compact
    (*

    Fires before message compaction

    *)

Hook event types

val event_to_string : event -> string

event_to_string event converts an event to its wire format string. Wire format: "PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop", "SubagentStop", "PreCompact"

val event_of_string : string -> event

event_of_string s parses an event from its wire format string.

val event_jsont : event Jsont.t

event_jsont is the Jsont codec for hook events.

Context

module Context : sig ... end

Context provided to hook callbacks.

Decisions

type decision =
  1. | Continue
    (*

    Allow the action to proceed

    *)
  2. | Block
    (*

    Block the action

    *)

Hook decision control

val decision_jsont : decision Jsont.t

decision_jsont is the Jsont codec for hook decisions. Wire format: "continue", "block"

Typed Hook Modules

module PreToolUse : sig ... end

PreToolUse hook - fires before tool execution

module PostToolUse : sig ... end

PostToolUse hook - fires after tool execution

module UserPromptSubmit : sig ... end

UserPromptSubmit hook - fires when user submits a prompt

module Stop : sig ... end

Stop hook - fires when conversation stops

module SubagentStop : sig ... end

SubagentStop hook - fires when a subagent stops

module PreCompact : sig ... end

PreCompact hook - fires before message compaction

Generic Hook Result

type result = {
  1. decision : decision option;
  2. system_message : string option;
  3. hook_specific_output : Jsont.json option;
  4. unknown : Unknown.t;
}

Generic result structure for hooks

val result_jsont : result Jsont.t

result_jsont is the Jsont codec for hook results.

val continue : ?system_message:string -> ?hook_specific_output:Jsont.json -> unit -> result

continue ?system_message ?hook_specific_output () creates a continue result.

  • parameter system_message

    Optional message to add to system context

  • parameter hook_specific_output

    Optional hook-specific output data

val block : ?system_message:string -> ?hook_specific_output:Jsont.json -> unit -> result

block ?system_message ?hook_specific_output () creates a block result.

  • parameter system_message

    Optional message to add to system context

  • parameter hook_specific_output

    Optional hook-specific output data