hooks

type BuiltinFunc func(ctx context.Context, in *Input, args []string) (*Output, error)

type Config = latest.HooksConfig

type Decision string

type ErrorPolicy string

type EventSpec struct {
	Type         EventType
	ToolScoped   bool
	FailClosed   bool
	StdoutPolicy StdoutPolicy
}

type EventType string

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

type Handler interface {
	Run(ctx context.Context, input []byte) (HandlerResult, error)
}

type HandlerEnv struct {
	WorkingDir string
	Env        []string
}

type HandlerFactory func(env HandlerEnv, hook Hook) (Handler, error)

type HandlerResult struct {
	Stdout   string
	Stderr   string
	ExitCode int
	Output   *Output
}

type Hook = latest.HookDefinition

type HookSpecificOutput struct {
	HookEventName EventType `json:"hook_event_name,omitempty"`

	// PreToolUse fields.
	PermissionDecision       Decision       `json:"permission_decision,omitempty"`
	PermissionDecisionReason string         `json:"permission_decision_reason,omitempty"`
	UpdatedInput             map[string]any `json:"updated_input,omitempty"`

	// PostToolUse / SessionStart / TurnStart / Stop fields.
	AdditionalContext string `json:"additional_context,omitempty"`

	// BeforeCompaction: when non-empty, the runtime applies this string as
	// the compaction summary verbatim and skips the LLM-based
	// summarization. Ignored on every other event.
	Summary string `json:"summary,omitempty"`
}

type HookType = string

type Input struct {
	SessionID     string    `json:"session_id"`
	Cwd           string    `json:"cwd"`
	HookEventName EventType `json:"hook_event_name"`

	// AgentName identifies the agent dispatching the event. Useful for
	// builtin hooks that need to look up per-agent state via a runtime
	// closure (e.g. response cache).
	AgentName string `json:"agent_name,omitempty"`

	// LastUserMessage is the text content of the latest user message in
	// the session at dispatch time. Populated for events that respond to
	// a user turn (stop, after_llm_call). Empty for events that aren't
	// turn-scoped (session_start, session_end, notification, ...).
	LastUserMessage string `json:"last_user_message,omitempty"`

	// Tool-related fields (PreToolUse, PostToolUse, PermissionRequest).
	ToolName  string         `json:"tool_name,omitempty"`
	ToolUseID string         `json:"tool_use_id,omitempty"`
	ToolInput map[string]any `json:"tool_input,omitempty"`

	// PostToolUse specific.
	ToolResponse any  `json:"tool_response,omitempty"`
	ToolError    bool `json:"tool_error,omitempty"`

	// SessionStart specific: "startup", "resume", "clear", "compact".
	// PreCompact specific: "manual", "auto", "overflow", "tool_overflow".
	Source string `json:"source,omitempty"`
	// SessionEnd specific: "clear", "logout", "prompt_input_exit", "other".
	Reason string `json:"reason,omitempty"`
	// Stop / AfterLLMCall / SubagentStop: the model's final response content.
	StopResponse string `json:"stop_response,omitempty"`
	// UserPromptSubmit specific: the text the user just submitted.
	Prompt string `json:"prompt,omitempty"`
	// SubagentStop populates [Input.AgentName] (above) with the name of
	// the sub-agent that just finished.
	// SubagentStop specific: ID of the parent session that spawned the sub-agent.
	ParentSessionID string `json:"parent_session_id,omitempty"`
	// Notification specific.
	NotificationLevel   string `json:"notification_level,omitempty"`
	NotificationMessage string `json:"notification_message,omitempty"`

	// OnAgentSwitch specific: the agent the runtime is moving away
	// from (FromAgent) and the one it's switching to (ToAgent), plus
	// the cause of the transition ("transfer_task", "handoff",
	// "transfer_task_return"). Empty FromAgent is valid for the
	// initial switch into the team's default agent.
	FromAgent       string `json:"from_agent,omitempty"`
	ToAgent         string `json:"to_agent,omitempty"`
	AgentSwitchKind string `json:"agent_switch_kind,omitempty"`

	// OnSessionResume specific: the iteration cap that was reached
	// (PreviousMaxIterations) and the new cap after the user approved
	// continuation (NewMaxIterations). Carrying both lets audit
	// pipelines compute how much extra runtime was granted without
	// reconstructing it from the iteration counter.
	PreviousMaxIterations int `json:"previous_max_iterations,omitempty"`
	NewMaxIterations      int `json:"new_max_iterations,omitempty"`

	// OnToolApprovalDecision specific: the verdict resolved by the
	// approval chain ("allow", "deny", "canceled") and a stable
	// classifier for what produced it ("yolo",
	// "session_permissions_allow", "session_permissions_deny",
	// "team_permissions_allow", "team_permissions_deny",
	// "readonly_hint", "user_approved", "user_approved_session",
	// "user_approved_tool", "user_rejected", "context_canceled").
	ApprovalDecision string `json:"approval_decision,omitempty"`
	ApprovalSource   string `json:"approval_source,omitempty"`

	// Compaction fields (BeforeCompaction, AfterCompaction).
	InputTokens  int64 `json:"input_tokens,omitempty"`
	OutputTokens int64 `json:"output_tokens,omitempty"`
	// ContextLimit is the model's context-window size in tokens. It is
	// 0 when the model definition is unavailable (e.g. an unknown
	// model ID); hooks should treat 0 as "unknown" rather than as a
	// real limit.
	ContextLimit int64 `json:"context_limit,omitempty"`
	// CompactionReason is one of "threshold", "overflow", "manual".
	CompactionReason string `json:"compaction_reason,omitempty"`
	// Summary is the produced compaction summary text. It is populated
	// only on AfterCompaction (BeforeCompaction fires before any
	// summary exists); on AfterCompaction it carries the actual text
	// applied to the session so observability handlers can audit /
	// archive what was summarized.
	Summary string `json:"summary,omitempty"`
}

type MatcherConfig = latest.HookMatcherConfig

type ModelClient interface {
	Ask(ctx context.Context, modelSpec, system, user string, schema *latest.StructuredOutput) (string, error)
}

type Output struct {
	// Continue indicates whether to continue execution (default: true).
	Continue *bool `json:"continue,omitempty"`
	// StopReason is shown when continue=false.
	StopReason string `json:"stop_reason,omitempty"`
	// SuppressOutput hides stdout from transcript.
	SuppressOutput bool `json:"suppress_output,omitempty"`
	// SystemMessage is a warning to show the user.
	SystemMessage string `json:"system_message,omitempty"`
	// Decision is for blocking operations ("block", ...).
	// In-process builtin hooks should use [DecisionBlockValue].
	Decision string `json:"decision,omitempty"`
	// Reason explains the decision.
	Reason string `json:"reason,omitempty"`
	// HookSpecificOutput contains event-specific fields.
	HookSpecificOutput *HookSpecificOutput `json:"hook_specific_output,omitempty"`
}

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

type ResponseShape func(raw string, in *Input) (*Output, error)

type Result struct {
	// Allowed indicates if the operation should proceed.
	Allowed bool
	// PermissionAllowed is set when a [EventPermissionRequest] hook
	// returned permission_decision="allow". The runtime treats this as
	// an explicit auto-approve and skips the interactive confirmation.
	PermissionAllowed bool
	// Message is feedback to include in the response.
	Message string
	// ModifiedInput contains modifications to tool input (PreToolUse).
	ModifiedInput map[string]any
	// AdditionalContext is context added by the hooks.
	AdditionalContext string
	// SystemMessage is a warning to show the user.
	SystemMessage string
	// ExitCode is the worst exit code seen (0 = success, 2 = blocking error, -1 = exec failure).
	ExitCode int
	// Stderr captures stderr from a failing hook.
	Stderr string
	// Summary is set by EventBeforeCompaction hooks to override the
	// LLM-generated compaction summary. When multiple hooks return a
	// non-empty summary, the first one wins.
	Summary string

	// Decision is the most-restrictive PreToolUse verdict reported by
	// any matching hook in the chain ("" when no hook produced one).
	// Most-restrictive ordering: Deny > Ask > Allow > "".
	//
	// The runtime's tool-approval flow consults this BEFORE asking the
	// user, so an LLM-judge hook that returns Allow can auto-approve a
	// call that would otherwise prompt, and Ask can force a prompt for
	// a call that would otherwise auto-run.
	//
	// Always empty for non-PreToolUse events.
	Decision Decision
	// DecisionReason is the human-readable rationale paired with
	// Decision (the reason from the most-restrictive hook). Empty when
	// Decision is empty.
	DecisionReason string
}

type StdoutPolicy int