hooks

package
v1.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 26, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package hooks provides lifecycle hooks for Claude Code events.

Index

Constants

View Source 
const (
	// DefaultHookTimeoutMS is the default timeout for hook execution in milliseconds
	DefaultHookTimeoutMS = 5000
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Config 

type Config struct {
	// contains filtered or unexported fields
}

Config holds the complete hook configuration for all events

func LoadConfig 

func LoadConfig() (*Config, error)

LoadConfig loads hook configuration from user and project locations Project config overrides user config

func NewConfig 

func NewConfig() *Config

NewConfig creates an empty hook configuration

func (*Config) GetHooks 

func (c *Config) GetHooks(eventType EventType) []HookConfig

GetHooks returns all hooks configured for a given event type

type Engine 

type Engine struct {
	// contains filtered or unexported fields
}

Engine manages hook execution across the application lifecycle

func NewEngine 

func NewEngine(projectPath, modelID string) (*Engine, error)

NewEngine creates a new hook engine

func NewEngineWithConfig 

func NewEngineWithConfig(config *Config, projectPath, modelID string) *Engine

NewEngineWithConfig creates an engine with a specific configuration Useful for testing

func (*Engine) Disable 

func (e *Engine) Disable()

Disable turns off hook execution

func (*Engine) Enable 

func (e *Engine) Enable()

Enable turns on hook execution

func (*Engine) Fire 

func (e *Engine) Fire(eventType EventType, data EventData) error

Fire executes all hooks for a given event Collects and returns all errors from failed hooks as a multi-error

func (*Engine) FireNotification 

func (e *Engine) FireNotification(level, message, source string) error

FireNotification is a convenience method for Notification event

func (*Engine) FirePermissionRequest 

func (e *Engine) FirePermissionRequest(toolName, action, description string, isSubagent bool) error

FirePermissionRequest is a convenience method for PermissionRequest event

func (*Engine) FirePostToolUse 

func (e *Engine) FirePostToolUse(toolName, filePath string, success bool, errMsg string, isSubagent bool) error

FirePostToolUse is a convenience method for PostToolUse event

func (*Engine) FirePreCompact 

func (e *Engine) FirePreCompact(compactionType string, currentSize, estimatedNewSize int) error

FirePreCompact is a convenience method for PreCompact event

func (*Engine) FirePreToolUse 

func (e *Engine) FirePreToolUse(toolName, filePath string, isSubagent bool) error

FirePreToolUse is a convenience method for PreToolUse event

func (*Engine) FireSessionEnd 

func (e *Engine) FireSessionEnd(projectPath string, messageCount int) error

FireSessionEnd is a convenience method for SessionEnd event

func (*Engine) FireSessionStart 

func (e *Engine) FireSessionStart(projectPath, modelID string) error

FireSessionStart is a convenience method for SessionStart event

func (*Engine) FireStop 

func (e *Engine) FireStop(responseLength, tokensUsed int, toolsUsed []string, isSubagent bool) error

FireStop is a convenience method for Stop event

func (*Engine) FireSubagentStop 

func (e *Engine) FireSubagentStop(taskDescription, subagentType string, responseLength, tokensUsed int, success bool, executionTime float64) error

FireSubagentStop is a convenience method for SubagentStop event

func (*Engine) FireUserPromptSubmit 

func (e *Engine) FireUserPromptSubmit(messageText string) error

FireUserPromptSubmit is a convenience method for UserPromptSubmit event

type Event 

type Event struct {
	Type      EventType
	Timestamp time.Time
	Data      EventData
}

Event represents a hook event with associated context data

type EventData 

type EventData interface {
	// ToEnvVars converts the event data to environment variables for shell execution
	ToEnvVars() map[string]string
}

EventData contains context-specific data for each event type

type EventType 

type EventType string

EventType represents the type of hook event 

const (
	// EventSessionStart fires when a Claude Code session begins (before first user message)
	EventSessionStart EventType = "SessionStart"

	// EventSessionEnd fires when Claude Code session terminates (clean shutdown)
	EventSessionEnd EventType = "SessionEnd"

	// EventUserPromptSubmit fires when user sends a message (before Claude processes it)
	EventUserPromptSubmit EventType = "UserPromptSubmit"

	// EventPreToolUse fires after Claude creates tool parameters, before tool execution
	EventPreToolUse EventType = "PreToolUse"

	// EventPostToolUse fires immediately after a tool completes successfully
	EventPostToolUse EventType = "PostToolUse"

	// EventPermissionRequest fires when user is shown a permission dialog for a tool
	EventPermissionRequest EventType = "PermissionRequest"

	// EventNotification fires when Claude Code sends notifications to the user
	EventNotification EventType = "Notification"

	// EventStop fires when main Claude Code agent finishes responding to user
	EventStop EventType = "Stop"

	// EventSubagentStop fires when a subagent finishes responding
	EventSubagentStop EventType = "SubagentStop"

	// EventPreCompact fires before Claude Code runs a compact operation
	EventPreCompact EventType = "PreCompact"
)

type ExecutionResult 

type ExecutionResult struct {
	Success  bool
	Stdout   string
	Stderr   string
	ExitCode int
	Error    error
}

ExecutionResult contains the result of a hook execution

type Executor 

type Executor struct {
	// contains filtered or unexported fields
}

Executor executes shell commands for hooks

func NewExecutor 

func NewExecutor(projectPath, modelID string) *Executor

NewExecutor creates a new hook executor

func (*Executor) Execute 

func (e *Executor) Execute(hook *HookConfig, event *Event) *ExecutionResult

Execute runs a hook command with the given event context

func (*Executor) ExecuteAsync 

func (e *Executor) ExecuteAsync(hook *HookConfig, event *Event)

ExecuteAsync runs a hook command asynchronously (fire and forget) Includes panic recovery to prevent crashes from hook failures

type HookConfig 

type HookConfig struct {
	// Command is the shell command to execute
	Command string `json:"command"`
	// Description explains what the hook does
	Description string `json:"description,omitempty"`
	// Timeout in milliseconds, defaults to DefaultHookTimeoutMS
	Timeout int `json:"timeout,omitempty"`
	// Env provides environment variables for the hook command
	Env map[string]string `json:"env,omitempty"`
	// Match defines conditions for when the hook should execute
	Match *MatchConfig `json:"match,omitempty"`
	// IgnoreFailure continues execution even if hook fails
	IgnoreFailure bool `json:"ignoreFailure,omitempty"`
	// Async runs the hook in the background without blocking
	Async bool `json:"async,omitempty"`
}

HookConfig represents a single hook configuration

func (*HookConfig) GetTimeout 

func (hc *HookConfig) GetTimeout() int

GetTimeout returns the timeout in milliseconds, defaulting to DefaultHookTimeoutMS if not set

func (*HookConfig) ShouldExecute 

func (hc *HookConfig) ShouldExecute(event *Event) bool

ShouldExecute checks if a hook should execute based on its match configuration

type MatchConfig 

type MatchConfig struct {
	// ToolName filters hooks to only run for specific tool names
	ToolName string `json:"toolName,omitempty"`
	// FilePattern is a regex to match against file paths in tool use events
	FilePattern string `json:"filePattern,omitempty"`
	// IsSubagent filters hooks based on whether execution is in a subagent context
	// Uses pointer to distinguish between false and unset
	IsSubagent *bool `json:"isSubagent,omitempty"`
	// Level filters notification events by severity level
	Level string `json:"level,omitempty"`
}

MatchConfig defines conditions for when a hook should execute

type MuxBridge added in v1.10.0 

type MuxBridge struct {
	// contains filtered or unexported fields
}

MuxBridge bridges mux's hook system to hex's hook engine. It registers handlers on a mux HookManager that forward events to the hex hook engine for shell command execution.

func NewMuxBridge added in v1.10.0 

func NewMuxBridge(hexEngine *Engine) (*MuxBridge, *muxhooks.Manager)

NewMuxBridge creates a bridge between mux hooks and the hex engine. Returns both the bridge and the mux HookManager to wire into agents.

func (*MuxBridge) Manager added in v1.10.0 

func (b *MuxBridge) Manager() *muxhooks.Manager

Manager returns the mux hook manager for wiring into agents.

type NotificationData 

type NotificationData struct {
	Level   string
	Message string
	Source  string
}

NotificationData contains data for Notification event

func (NotificationData) ToEnvVars 

func (d NotificationData) ToEnvVars() map[string]string

ToEnvVars converts NotificationData to environment variables

type PermissionRequestData 

type PermissionRequestData struct {
	ToolName    string
	Action      string
	Description string
	IsSubagent  bool
}

PermissionRequestData contains data for PermissionRequest event

func (PermissionRequestData) ToEnvVars 

func (d PermissionRequestData) ToEnvVars() map[string]string

ToEnvVars converts PermissionRequestData to environment variables

type PreCompactData 

type PreCompactData struct {
	CompactionType   string
	CurrentSize      int
	EstimatedNewSize int
}

PreCompactData contains data for PreCompact event

func (PreCompactData) ToEnvVars 

func (d PreCompactData) ToEnvVars() map[string]string

ToEnvVars converts PreCompactData to environment variables

type SessionEndData 

type SessionEndData struct {
	ProjectPath  string
	MessageCount int
}

SessionEndData contains data for SessionEnd event

func (SessionEndData) ToEnvVars 

func (d SessionEndData) ToEnvVars() map[string]string

ToEnvVars converts SessionEndData to environment variables

type SessionStartData 

type SessionStartData struct {
	ProjectPath string
	ModelID     string
}

SessionStartData contains data for SessionStart event

func (SessionStartData) ToEnvVars 

func (d SessionStartData) ToEnvVars() map[string]string

ToEnvVars converts SessionStartData to environment variables

type Settings 

type Settings struct {
	Hooks map[EventType]interface{} `json:"hooks,omitempty"`
}

Settings represents the .hex/settings.json structure

type StopData 

type StopData struct {
	ResponseLength int
	TokensUsed     int
	ToolsUsed      []string
	IsSubagent     bool
}

StopData contains data for Stop event

func (StopData) ToEnvVars 

func (d StopData) ToEnvVars() map[string]string

ToEnvVars converts StopData to environment variables

type SubagentStopData 

type SubagentStopData struct {
	TaskDescription string
	SubagentType    string
	ResponseLength  int
	TokensUsed      int
	Success         bool
	ExecutionTime   float64 // in seconds
}

SubagentStopData contains data for SubagentStop event

func (SubagentStopData) ToEnvVars 

func (d SubagentStopData) ToEnvVars() map[string]string

ToEnvVars converts SubagentStopData to environment variables

type ToolUseData 

type ToolUseData struct {
	ToolName   string
	FilePath   string // extracted from parameters if available
	Success    bool   // only for PostToolUse
	Error      string // only for PostToolUse (if failed)
	IsSubagent bool
}

ToolUseData contains data for PreToolUse and PostToolUse events

func (ToolUseData) ToEnvVars 

func (d ToolUseData) ToEnvVars() map[string]string

ToEnvVars converts ToolUseData to environment variables

type UserPromptSubmitData 

type UserPromptSubmitData struct {
	MessageText   string
	MessageLength int
}

UserPromptSubmitData contains data for UserPromptSubmit event

func (UserPromptSubmitData) ToEnvVars 

func (d UserPromptSubmitData) ToEnvVars() map[string]string

ToEnvVars converts UserPromptSubmitData to environment variables

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.