Skip to content

github.com/ricardo/anthrogo/internal/hooks

package hooks // import "github.com/ricardo/anthrogo/internal/hooks"


TYPES

type Behavior int
    Behavior describes what the manager decided for a PreToolUse check.

const (
    // DecisionPass means no hook expressed an opinion; proceed normally.
    DecisionPass Behavior = iota
    // DecisionAllow means at least one hook explicitly allowed the action.
    DecisionAllow
    // DecisionDeny means at least one hook denied the action.
    DecisionDeny
)
type Common struct {
    HookEventName EventName `json:"hook_event_name"`
    SessionID     string    `json:"session_id"`
    Cwd           string    `json:"cwd"`
    Version       string    `json:"anthrogo_version"`
}
    Common is the envelope every payload carries.

type Config struct {
    PreToolUse       []Spec `yaml:"PreToolUse,omitempty"`
    PostToolUse      []Spec `yaml:"PostToolUse,omitempty"`
    UserPromptSubmit []Spec `yaml:"UserPromptSubmit,omitempty"`
    Stop             []Spec `yaml:"Stop,omitempty"`
    SubagentStop     []Spec `yaml:"SubagentStop,omitempty"`
    Notification     []Spec `yaml:"Notification,omitempty"`
    PreCompact       []Spec `yaml:"PreCompact,omitempty"`
    SessionStart     []Spec `yaml:"SessionStart,omitempty"`
    SessionEnd       []Spec `yaml:"SessionEnd,omitempty"`
}
    Config holds per-event hook lists. Field names match event names so YAML
    keys are PascalCase (PreToolUse, etc.).

func (c Config) AppendOverlay(overlay Config) Config
    AppendOverlay returns a new Config = c with each event's list extended by
    overlay's list.

func (c *Config) Expand()
    Expand replaces ~/ and $VAR in every Command, fills in default Timeout per
    event.

func (c *Config) Validate() []string
    Validate compiles all matchers; invalid ones drop their spec and append a
    warning.

type Decision struct {
    Behavior      Behavior
    Reason        string
    ModifiedInput map[string]any
}
    Decision is the result of FirePreToolUse.

type EventName string
    EventName is one of the 9 hook event names.

const (
    EventPreToolUse       EventName = "PreToolUse"
    EventPostToolUse      EventName = "PostToolUse"
    EventUserPromptSubmit EventName = "UserPromptSubmit"
    EventStop             EventName = "Stop"
    EventSubagentStop     EventName = "SubagentStop"
    EventNotification     EventName = "Notification"
    EventPreCompact       EventName = "PreCompact"
    EventSessionStart     EventName = "SessionStart"
    EventSessionEnd       EventName = "SessionEnd"
)
type HookSpecificOutput struct {
    HookEventName            EventName      `json:"hookEventName"`
    PermissionDecision       string         `json:"permissionDecision,omitempty"`
    PermissionDecisionReason string         `json:"permissionDecisionReason,omitempty"`
    ModifiedInput            map[string]any `json:"modifiedInput,omitempty"`
    AdditionalContext        string         `json:"additionalContext,omitempty"`
}

type Manager struct {
    // Has unexported fields.
}
    Manager coordinates hook dispatch for all nine events.

func NewManager(cfg Config, opts ManagerOptions) *Manager
    NewManager creates a Manager. cfg should already have been Validate()d.

func (m *Manager) Drain(timeout time.Duration)
    Drain blocks until all in-flight async hook goroutines finish or timeout
    elapses.

func (m *Manager) FireNotification(ctx context.Context, message, kind string)
    FireNotification fires Notification hooks asynchronously.

func (m *Manager) FirePostToolUse(ctx context.Context, toolName string, input map[string]any, response map[string]any) string
    FirePostToolUse runs PostToolUse hooks sequentially and returns concatenated
    additionalContext strings. Errors are logged only, never propagated.

func (m *Manager) FirePreCompact(ctx context.Context, trigger string)
    FirePreCompact runs PreCompact hooks synchronously (log-only per spec §5.2).

func (m *Manager) FirePreToolUse(ctx context.Context, toolName string, input map[string]any) Decision
    FirePreToolUse runs PreToolUse hooks sequentially and returns a Decision.

    Exit semantics:
      - timeout → DecisionDeny, reason "hook X timeout"
      - exit 2 → DecisionDeny, reason = stderr text
      - exit non-zero/non-2 → DecisionDeny, reason "hook X exited N"
      - exit 0, permissionDecision "deny" → DecisionDeny immediately
      - exit 0, permissionDecision "allow" → mark DecisionAllow, keep looping
      - exit 0, modifiedInput present → merge into accumulated ModifiedInput

func (m *Manager) FireSessionEnd(ctx context.Context, kind string)
    FireSessionEnd fires SessionEnd hooks asynchronously.

func (m *Manager) FireSessionStart(ctx context.Context, kind string)
    FireSessionStart fires SessionStart hooks asynchronously.

func (m *Manager) FireStop(ctx context.Context, stopReason string)
    FireStop fires Stop hooks asynchronously.

func (m *Manager) FireSubagentStop(ctx context.Context, stopReason string)
    FireSubagentStop fires SubagentStop hooks asynchronously.

func (m *Manager) FireUserPromptSubmit(ctx context.Context, prompt string) (context.Context, string, bool, string)
    FireUserPromptSubmit runs UserPromptSubmit hooks and returns:

        (ctx, finalPrompt, abort, reason)

    Sequential; any exit-2 or timeout causes abort=true. Exit 0 with
    additionalContext appends it to the prompt.

type ManagerOptions struct {
    SessionID string
    Cwd       string
    Version   string
    // LogSink, if non-nil, is called for informational/error log lines.
    // eventName is the hook event (e.g. "PreToolUse"); msg is free-form text.
    LogSink func(eventName, msg string)
}
    ManagerOptions holds session-level metadata for the Manager.

type NotificationPayload struct {
    Common
    Message string `json:"message"`
    Kind    string `json:"kind"`
}

type Output struct {
    Continue           *bool               `json:"continue,omitempty"`
    StopReason         string              `json:"stopReason,omitempty"`
    HookSpecificOutput *HookSpecificOutput `json:"hookSpecificOutput,omitempty"`
}
    Output is what the hook writes to stdout. All fields optional.

type PostToolUsePayload struct {
    Common
    ToolName     string         `json:"tool_name"`
    ToolInput    map[string]any `json:"tool_input"`
    ToolResponse map[string]any `json:"tool_response"`
}

type PreCompactPayload struct {
    Common
    Trigger string `json:"trigger"`
}

type PreToolUsePayload struct {
    Common
    ToolName  string         `json:"tool_name"`
    ToolInput map[string]any `json:"tool_input"`
}

type Result struct {
    ExitCode int
    Stdout   []byte
    Stderr   []byte
    Output   *Output
    TimedOut bool
}
    Result is what the runner reports back. Output is nil if stdout was empty or
    not parseable JSON.

func RunHook(ctx context.Context, spec Spec, payload any) (*Result, error)
    RunHook spawns `spec.Command`, feeds `payload` (marshaled JSON) to stdin,
    waits up to spec.Timeout. Always returns a Result on completion or timeout;
    returns a non-nil error only on setup failure (e.g. cmd.Start() failure).

type SessionEndPayload struct {
    Common
    Kind string `json:"kind"`
}

type SessionStartPayload struct {
    Common
    Kind string `json:"kind"`
}

type Spec struct {
    Matcher string        `yaml:"matcher,omitempty"`
    Command string        `yaml:"command"`
    Timeout time.Duration `yaml:"timeout,omitempty"`

    // Has unexported fields.
}
    Spec is one hook entry under a given event.

type StopPayload struct {
    Common
    StopReason string `json:"stop_reason"`
}

type UserPromptSubmitPayload struct {
    Common
    Prompt string `json:"prompt"`
}