hooks

Documentation

Overview

Package hooks implements the event hooks system for GenCode. Compatible with Claude Code hooks that execute shell commands on events.

Index

• Constants
• func EventSupportsMatcher(event EventType) bool
• func GetMatchValue(event EventType, input HookInput) string
• func MatchesEvent(matcher, matchValue string) bool
• type Engine
  • func NewEngine(settings *config.Settings, sessionID, cwd, transcriptPath string) *Engine
  • func (e *Engine) Execute(ctx context.Context, event EventType, input HookInput) HookOutcome
  • func (e *Engine) ExecuteAsync(event EventType, input HookInput)
  • func (e *Engine) HasHooks(event EventType) bool
  • func (e *Engine) SetPermissionMode(mode string)
• type EventType
• type HookInput
• type HookOutcome
• type HookOutput
• type HookSpecificOutput
• type PermissionRequestDecision

Constants

const DefaultTimeout = 600

DefaultTimeout is the default timeout for hook commands in seconds.

Functions

func EventSupportsMatcher

func EventSupportsMatcher(event EventType) bool

EventSupportsMatcher returns true if the event type supports matcher filtering.

func GetMatchValue

func GetMatchValue(event EventType, input HookInput) string

GetMatchValue extracts the value to match against based on event type.

func MatchesEvent

func MatchesEvent(matcher, matchValue string) bool

MatchesEvent checks if a matcher pattern matches the given value. Empty or "*" matches everything. Matcher is regex-anchored at both ends.

Types

type Engine

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

Engine executes hooks based on events.

func NewEngine

func NewEngine(settings *config.Settings, sessionID, cwd, transcriptPath string) *Engine

NewEngine creates a new hook execution engine.

func (*Engine) Execute

func (e *Engine) Execute(ctx context.Context, event EventType, input HookInput) HookOutcome

Execute runs all matching hooks for an event synchronously.

func (*Engine) ExecuteAsync

func (e *Engine) ExecuteAsync(event EventType, input HookInput)

ExecuteAsync runs all matching hooks asynchronously (fire-and-forget).

func (*Engine) HasHooks

func (e *Engine) HasHooks(event EventType) bool

HasHooks returns true if there are any hooks configured for the given event.

func (*Engine) SetPermissionMode

func (e *Engine) SetPermissionMode(mode string)

SetPermissionMode sets the current permission mode (normal, auto, plan).

type EventType

type EventType string

EventType represents the type of hook event.

const (
	SessionStart       EventType = "SessionStart"       // matcher: startup, resume, clear, compact
	UserPromptSubmit   EventType = "UserPromptSubmit"   // no matcher
	PreToolUse         EventType = "PreToolUse"         // matcher: tool name
	PermissionRequest  EventType = "PermissionRequest"  // matcher: tool name
	PostToolUse        EventType = "PostToolUse"        // matcher: tool name
	PostToolUseFailure EventType = "PostToolUseFailure" // matcher: tool name
	Notification       EventType = "Notification"       // matcher: notification_type
	SubagentStart      EventType = "SubagentStart"      // matcher: agent_type
	SubagentStop       EventType = "SubagentStop"       // matcher: agent_type
	Stop               EventType = "Stop"               // no matcher
	PreCompact         EventType = "PreCompact"         // matcher: manual, auto
	SessionEnd         EventType = "SessionEnd"         // matcher: reason
)

Event types with their matcher support noted.

type HookInput

type HookInput struct {
	// Common fields
	SessionID      string `json:"session_id"`
	TranscriptPath string `json:"transcript_path"`
	Cwd            string `json:"cwd"`
	PermissionMode string `json:"permission_mode"`
	HookEventName  string `json:"hook_event_name"`

	// Tool events
	ToolName     string         `json:"tool_name,omitempty"`
	ToolInput    map[string]any `json:"tool_input,omitempty"`
	ToolUseID    string         `json:"tool_use_id,omitempty"`
	ToolResponse any            `json:"tool_response,omitempty"`
	Error        string         `json:"error,omitempty"`
	IsInterrupt  bool           `json:"is_interrupt,omitempty"`

	// UserPromptSubmit
	Prompt string `json:"prompt,omitempty"`

	// Notification
	Message          string `json:"message,omitempty"`
	Title            string `json:"title,omitempty"`
	NotificationType string `json:"notification_type,omitempty"`

	// Agent events
	AgentID             string `json:"agent_id,omitempty"`
	AgentType           string `json:"agent_type,omitempty"`
	AgentTranscriptPath string `json:"agent_transcript_path,omitempty"`
	StopHookActive      bool   `json:"stop_hook_active,omitempty"`

	// Session events
	Source             string `json:"source,omitempty"`
	Model              string `json:"model,omitempty"`
	Reason             string `json:"reason,omitempty"`
	Trigger            string `json:"trigger,omitempty"`
	CustomInstructions string `json:"custom_instructions,omitempty"`
}

HookInput is the JSON input passed to hook commands via stdin.

type HookOutcome

type HookOutcome struct {
	ShouldContinue    bool
	ShouldBlock       bool
	BlockReason       string
	AdditionalContext string
	UpdatedInput      map[string]any
	Error             error
}

HookOutcome is the processed result from hook execution.

type HookOutput

type HookOutput struct {
	Continue           *bool               `json:"continue,omitempty"`
	StopReason         string              `json:"stopReason,omitempty"`
	SuppressOutput     bool                `json:"suppressOutput,omitempty"`
	SystemMessage      string              `json:"systemMessage,omitempty"`
	Decision           string              `json:"decision,omitempty"`
	Reason             string              `json:"reason,omitempty"`
	HookSpecificOutput *HookSpecificOutput `json:"hookSpecificOutput,omitempty"`
}

HookOutput is the JSON output from hook commands.

type HookSpecificOutput

type HookSpecificOutput struct {
	HookEventName             string                     `json:"hookEventName"`
	PermissionDecision        string                     `json:"permissionDecision,omitempty"`
	PermissionDecisionReason  string                     `json:"permissionDecisionReason,omitempty"`
	UpdatedInput              map[string]any             `json:"updatedInput,omitempty"`
	AdditionalContext         string                     `json:"additionalContext,omitempty"`
	PermissionRequestDecision *PermissionRequestDecision `json:"decision,omitempty"`
}

HookSpecificOutput contains event-specific output fields.

type PermissionRequestDecision

type PermissionRequestDecision struct {
	Behavior           string         `json:"behavior"`
	UpdatedInput       map[string]any `json:"updatedInput,omitempty"`
	UpdatedPermissions []any          `json:"updatedPermissions,omitempty"`
	Message            string         `json:"message,omitempty"`
	Interrupt          bool           `json:"interrupt,omitempty"`
}

PermissionRequestDecision represents permission request hook decision.