hooks

Documentation

Overview

Package hooks fires Claude-Code-shaped hook events. Two hook types are supported: Type="http" posts the JSON event body to a URL, and Type="command" pipes the JSON event body to a shell command's stdin. Sender accepts a flat map of matchers keyed by event name — callers (e.g. cmd/claude) own the on-disk Settings struct that wraps this map.

Index

• Constants
• type Hook
• type Matcher
• type Sender
  • func NewSender(matchers map[string][]Matcher, ...) *Sender
  • func (s *Sender) OnNotification(ctx context.Context, matcher, message, title string) error
  • func (s *Sender) OnPermissionRequest(ctx context.Context, toolUseID, toolName string, toolInput any) (hookresult.Result, error)
  • func (s *Sender) OnPostCompact(ctx context.Context, trigger string) error
  • func (s *Sender) OnPostToolUse(ctx context.Context, toolUseID, toolName string, toolInput, toolResponse any, ...) error
  • func (s *Sender) OnPreCompact(ctx context.Context, trigger string) error
  • func (s *Sender) OnPreToolUse(ctx context.Context, toolUseID, toolName string, toolInput any) (hookresult.Result, error)
  • func (s *Sender) OnPrompt(ctx context.Context, prompt, sessionTitle string) error
  • func (s *Sender) OnSessionEnd(ctx context.Context, reason string) error
  • func (s *Sender) OnSessionStart(ctx context.Context, source string) error
  • func (s *Sender) OnStop(ctx context.Context, lastAssistantMessage string, stopHookActive bool) error

Constants

const (
	UserPromptSubmit  = "UserPromptSubmit"
	PreToolUse        = "PreToolUse"
	PostToolUse       = "PostToolUse"
	Stop              = "Stop"
	SessionStart      = "SessionStart"
	SessionEnd        = "SessionEnd"
	PreCompact        = "PreCompact"
	PostCompact       = "PostCompact"
	Notification      = "Notification"
	PermissionRequest = "PermissionRequest"
)

Claude Code hook event names, exported so callers can build matcher maps without stringly-typed event keys.

const (
	NotificationPermissionPrompt    = "permission_prompt"
	NotificationIdlePrompt          = "idle_prompt"
	NotificationAuthSuccess         = "auth_success"
	NotificationElicitationDialog   = "elicitation_dialog"
	NotificationElicitationComplete = "elicitation_complete"
	NotificationElicitationResponse = "elicitation_response"
)

Notification matcher values, mirroring Claude Code's documented set. Orchestrators can configure hooks scoped to any subset; testagent passes these through as the Matcher field in the event body.

Types

type Hook

type Hook struct {
	Type    string            `json:"type"`
	URL     string            `json:"url,omitempty"`
	Command string            `json:"command,omitempty"`
	Timeout int               `json:"timeout"`
	Headers map[string]string `json:"headers,omitempty"`
}

Hook is a single hook target. Type="http" POSTs the event body to URL with Headers applied; Type="command" pipes the event body to Command's stdin via the platform's default shell. Timeout (seconds) bounds the per-hook wall-clock for either type; 0 → defaultTimeout.

type Matcher

type Matcher struct {
	Matcher string `json:"matcher"`
	Hooks   []Hook `json:"hooks"`
}

Matcher binds a matcher pattern to one or more http hooks. Mirrors the shape Claude Code's settings.json uses under hooks.<event>[].

type Sender

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

Sender posts hook events to URLs declared in matchers.

func NewSender

func NewSender(matchers map[string][]Matcher, sessionID, cwd, transcriptPath, permissionMode string, debugWriter io.Writer) *Sender

NewSender returns a sender wired to the given matcher map. matchers may be nil (no-op sender). sessionID is the value emitted in the body's session_id field. cwd/transcriptPath/permissionMode populate every event body. debugWriter is optional; nil disables verbose logging.

func (*Sender) OnNotification

func (s *Sender) OnNotification(ctx context.Context, matcher, message, title string) error

OnNotification fires Notification. Claude Code uses this for idle prompts, permission UI events, and the elicitation lifecycle — all advisory. matcher is one of the documented values (use the Notification* constants); message and title are user-facing strings. Any decision returned by the hook is discarded (Notification does not gate anything).

matcher doubles as the filter axis: every Notification matcher whose pattern matches this value fires. An empty matcher broadcasts to all Notification matchers — callers should normally pass one of the documented values.

func (*Sender) OnPermissionRequest

func (s *Sender) OnPermissionRequest(ctx context.Context, toolUseID, toolName string, toolInput any) (hookresult.Result, error)

OnPermissionRequest fires PermissionRequest and waits for the hook server to return an allow/deny decision (default per-hook timeout 120s, matching agentsd's reference). The returned hookresult.Result carries the aggregated behavior; aggregation is any-deny-wins, otherwise last-allow-wins (see internal/hookresult).

func (*Sender) OnPostCompact

func (s *Sender) OnPostCompact(ctx context.Context, trigger string) error

OnPostCompact fires PostCompact after the SessionStart that follows compaction. trigger matches the PreCompact value.

func (*Sender) OnPostToolUse

func (s *Sender) OnPostToolUse(ctx context.Context, toolUseID, toolName string, toolInput, toolResponse any, durationMs int64) error

OnPostToolUse fires PostToolUse after the tool completes.

func (*Sender) OnPreCompact

func (s *Sender) OnPreCompact(ctx context.Context, trigger string) error

OnPreCompact fires PreCompact before context-summarization runs. trigger is "manual" (user typed /compact) or "auto" (auto-compact lifecycle).

func (*Sender) OnPreToolUse

func (s *Sender) OnPreToolUse(ctx context.Context, toolUseID, toolName string, toolInput any) (hookresult.Result, error)

OnPreToolUse fires PreToolUse before the tool runs. The returned hookresult.Result carries the aggregated decision the hook server(s) returned (block / ask / allow + reason). Callers that gate tool execution on the response — currently the slash dispatcher — consult Block and Ask; other callers may discard it.

func (*Sender) OnPrompt

func (s *Sender) OnPrompt(ctx context.Context, prompt, sessionTitle string) error

OnPrompt fires UserPromptSubmit. sessionTitle is the human-facing label.

func (*Sender) OnSessionEnd

func (s *Sender) OnSessionEnd(ctx context.Context, reason string) error

OnSessionEnd fires SessionEnd. reason is one of "clear", "logout", "other", etc.

func (*Sender) OnSessionStart

func (s *Sender) OnSessionStart(ctx context.Context, source string) error

OnSessionStart fires SessionStart. source is one of "startup", "resume", "clear", "compact" — same vocabulary Claude Code uses on the matcher field.

func (*Sender) OnStop

func (s *Sender) OnStop(ctx context.Context, lastAssistantMessage string, stopHookActive bool) error

OnStop fires Stop.