hooks

type AgentContext ¶

type AgentContext struct {
	ID              string
	Type            string
	TranscriptPath  string
	ParentSessionID string
	ParentToolUseID string
}

AgentContext identifies a subagent on hosts that report one.

type ClaudeSource ¶

type ClaudeSource struct{}

ClaudeSource decodes the legacy Claude Code hook wire format into the product event contract. It preserves the historical decoder semantics: UTF-8 BOM skipping, decoding exactly the first JSON value from the reader without waiting for EOF, and ignoring trailing data.

func (ClaudeSource) Decode(_ context.Context, hookEvent string, input io.Reader) (Event, error)

type CodexDecodeFunc ¶

type CodexDecodeFunc func(ctx context.Context, publicEvent string, payload []byte) (codexsource.Decoded, error)

CodexDecodeFunc is the narrow DTO-returning seam between this package and internal/codexsource; this package never imports the SDK itself.

type CodexSource ¶

type CodexSource struct {
	DecodeFn CodexDecodeFunc
}

CodexSource decodes Codex hook payloads through the SDK adapter into the product event contract. Wire names never leak past this mapping.

func NewCodexSource() CodexSource

func (s CodexSource) Decode(ctx context.Context, publicEvent string, input io.Reader) (Event, error)

type CodexTurnEnricher ¶

type CodexTurnEnricher interface {
	// EnrichStop classifies a completed (sub)agent turn.
	EnrichStop(ctx context.Context, ev Event, p StopPayload) TurnInsight
	// EnrichPreToolUse classifies an interactive-tool call. A returned
	// StatusUnknown means "no notification for this tool".
	EnrichPreToolUse(ctx context.Context, ev Event, p PreToolUsePayload) TurnInsight
}

CodexTurnEnricher derives notification policy inputs for Codex events.

This is the seam for richer turn analysis: the default implementation is a pure heuristic over the hook payload, and a future adapter may consult the Codex app-server thread/turn API instead. Implementations must be side-effect-free and fast — they run inside the hook's time budget and must never block delivery on external state.

type Event ¶

type Event struct {
	Product          Product
	PayloadEventName string // diagnostic only; never selects the route
	Session          SessionContext
	Payload          EventPayload
	Raw              json.RawMessage // sensitive, retained for forward compatibility
}

Event is the product-owned envelope. Host DTO types never cross this boundary.

func (e Event) Kind() EventKind

type EventKind ¶

type EventKind string

EventKind is the product-level event classification derived from the sealed payload type, never stored separately.

const (
	EventUnknown           EventKind = ""
	EventPreToolUse        EventKind = "pre_tool_use"
	EventNotification      EventKind = "notification"
	EventStop              EventKind = "stop"
	EventSubagentStop      EventKind = "subagent_stop"
	EventPermissionRequest EventKind = "permission_request"
	EventTeammateIdle      EventKind = "teammate_idle"
)

type EventPayload ¶

type EventPayload interface {
	// contains filtered or unexported methods
}

EventPayload is sealed inside this package by the unexported method.

type EventSource ¶

type EventSource interface {
	Decode(context.Context, string, io.Reader) (Event, error)
}

EventSource decodes one host invocation into the product event contract. The string argument is the validated public event name from argv.

type Handler ¶

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

Handler handles hook events

func NewHandler(pluginRoot string) (*Handler, error)

func NewHandlerWithSource(pluginRoot string, product Product, source EventSource) (*Handler, error)

func (h *Handler) HandleHook(hookEvent string, input io.Reader) error

type HookData ¶

type HookData struct {
	TranscriptPath string `json:"transcript_path"`
	SessionID      string `json:"session_id"`
	CWD            string `json:"cwd"`
	ToolName       string `json:"tool_name,omitempty"`
	HookEventName  string `json:"hook_event_name,omitempty"`
	// Team-related fields (present in TeammateIdle, TaskCreated, TaskCompleted hooks)
	TeamName     string `json:"team_name,omitempty"`
	TeammateName string `json:"teammate_name,omitempty"`
}

HookData represents the data received from Claude Code hooks

type NotificationPayload ¶

type NotificationPayload struct{}

NotificationPayload is the Claude permission-prompt Notification event.

type PermissionRequestPayload ¶

type PermissionRequestPayload struct {
	ToolName  string
	ToolInput json.RawMessage
	Agent     *AgentContext // optional on the Codex wire
}

PermissionRequestPayload is a host request for user approval of a tool call.

type PreToolUsePayload ¶

type PreToolUsePayload struct {
	ToolName  string
	ToolUseID string
	ToolInput json.RawMessage
}

PreToolUsePayload is an interactive-tool event (Claude PreToolUse, or Codex PreToolUse for notification-relevant tools). ToolUseID is set on the Codex wire and empty for legacy Claude payloads.

type Product ¶

type Product string

Product identifies the host product that emitted a hook event.

const (
	ProductClaude Product = "claude"
	ProductCodex  Product = "codex"
)

type SessionContext ¶

type SessionContext struct {
	SessionID      string
	TurnID         string
	CWD            string
	TranscriptPath string
	Model          string
	PermissionMode string
}

SessionContext carries the host-neutral session identity shared by all events.

type StopPayload ¶

type StopPayload struct {
	AssistantMessage string
	Continuation     bool
}

StopPayload is the main-agent turn completion.

type SubagentStopPayload ¶

type SubagentStopPayload struct {
	Stop  StopPayload
	Agent *AgentContext // required for Codex, absent for legacy Claude payloads
}

SubagentStopPayload is a subagent turn completion.

type TeammateIdlePayload ¶

type TeammateIdlePayload struct {
	TeamName     string
	TeammateName string
}

TeammateIdlePayload is the Claude team event.

type TurnInsight ¶

type TurnInsight struct {
	Status analyzer.Status
	Body   string
}

TurnInsight is the policy-relevant view of a Codex event derived by an enricher: the notification status plus an optional pre-rendered body. An empty Body means "let the message generator use its defaults".