Documentation
¶
Overview ¶
Package hooks runs user-defined shell commands that fire on hook events (e.g. PreToolUse), returning decisions that control agent behavior.
Index ¶
Constants ¶
const (
EventPreToolUse = "PreToolUse"
)
Hook event name constants.
const HaltExitCode = 49
HaltExitCode is the exit code that halts the whole turn. 2 blocks the current tool call; 49 sits in the no-man's-land between the generic-error range (1-30), the sysexits range (64-78), and the killed-by-signal range (128+) so it can't be hit by accident.
const SupportedOutputVersion = 1
SupportedOutputVersion is the highest envelope version this build understands. Hooks may omit `version` entirely (treated as 1) or pin an older version. Unknown higher versions are still parsed but logged.
Variables ¶
This section is empty.
Functions ¶
func BuildEnv ¶
BuildEnv constructs the environment variable slice for a hook command. It includes all current process env vars plus hook-specific ones.
func BuildPayload ¶
BuildPayload constructs the JSON stdin payload for a hook command.
Types ¶
type AggregateResult ¶
type AggregateResult struct {
Decision Decision
Halt bool // Any hook requested halt.
HookCount int // Number of hooks that ran.
Hooks []HookInfo // Info about each hook that ran (config order).
Reason string // Concatenated deny/halt reasons (newline-separated).
Context string // Concatenated context from all hooks.
UpdatedInput string // Merged tool_input JSON (empty if no patches).
}
AggregateResult holds the combined outcome of all hooks for an event.
type HookInfo ¶
type HookInfo struct {
Name string `json:"name"`
Matcher string `json:"matcher,omitempty"`
Decision string `json:"decision"`
Halt bool `json:"halt,omitempty"`
Reason string `json:"reason,omitempty"`
InputRewrite bool `json:"input_rewrite,omitempty"`
}
HookInfo identifies a single hook that ran and its individual result.
type HookMetadata ¶
type HookMetadata struct {
HookCount int `json:"hook_count"`
Decision string `json:"decision"`
Halt bool `json:"halt,omitempty"`
Reason string `json:"reason,omitempty"`
InputRewrite bool `json:"input_rewrite,omitempty"`
Hooks []HookInfo `json:"hooks,omitempty"`
}
HookMetadata is embedded in tool response metadata so the UI can display a hook indicator.
type HookResult ¶
type HookResult struct {
Decision Decision
Halt bool // If true, halt the whole turn.
Reason string // Deny or halt reason (same field, different audience).
Context string
UpdatedInput string // Shallow-merge patch against tool_input (opaque JSON).
}
HookResult holds the parsed output of a single hook execution.
type Payload ¶
type Payload struct {
Event string `json:"event"`
SessionID string `json:"session_id"`
CWD string `json:"cwd"`
ToolName string `json:"tool_name"`
ToolInput json.RawMessage `json:"tool_input"`
}
Payload is the JSON structure piped to hook commands via stdin. ToolInput is emitted as a parsed JSON object for compatibility with Claude Code hooks (which expect tool_input to be an object, not a string).
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner executes hook commands and aggregates their results.
func NewRunner ¶
func NewRunner(hooks []config.HookConfig, cwd, projectDir string) *Runner
NewRunner creates a Runner from the given hook configs. Each hook's Matcher is compiled here so the Runner is self-sufficient; callers do not have to pre-compile matchers on the config, and reloads or merges that rebuild HookConfig values can't silently strip compiled state.
Hooks whose matcher fails to compile are skipped with a warning rather than treated as match-everything. ValidateHooks is expected to have caught syntax errors earlier, so this is defense in depth.
func (*Runner) Hooks ¶
func (r *Runner) Hooks() []config.HookConfig
Hooks returns the hook configs the runner was created with, in config order. Hooks whose matcher failed to compile at construction are omitted. Intended for diagnostics; callers should not rely on ordering or identity beyond that.
Source Files