hook

Documentation

Overview

Package hook runs shell hooks at agent lifecycle points (pre/post tool call, pre/post user turn) so users can attach gofmt, audit logging, lint gates etc. without rebuilding ub.

The runner is intentionally minimal:

• hook commands are argv slices, not shell strings, so quoting bugs surface in the config not in execution
• stdout/stderr each cap at outputCap; oversized output is dropped
• env passed to children is restricted to an explicit whitelist plus five UB_HOOK_* variables this package always sets
• block semantics live ONLY on pre_tool_call; all other phases treat a non-zero exit as warn so a misbehaving hook can never wedge the agent loop

Index

• Constants
• type Decision
• type Event
• type Kind
• type NopRunner
  • func (NopRunner) Run(_ context.Context, _ Event) Decision
• type Outcome
• type Runner
  • func New(cfg config.HooksConfig) Runner

Constants

const (

	// OnFailureWarn means a non-zero hook exit is reported but never blocks
	// the underlying tool call.
	OnFailureWarn = "warn"
	// OnFailureBlock means a non-zero hook exit on a pre_tool_call hook makes
	// the agent skip Execute and surface the hook stderr as an IsError tool
	// result. It has no effect on the other three trigger kinds.
	OnFailureBlock = "block"
)

Types

type Decision

type Decision struct {
	Block    bool
	Reason   string
	Outcomes []Outcome
}

Decision is the aggregated effect of all matched hooks for one event. Block is only ever true for KindPreToolCall when at least one matched hook had OnFailure=block AND exited non-zero.

type Event

type Event struct {
	Kind      Kind
	SessionID string
	Turn      int
	ToolName  string
	ToolUseID string
	ToolArgs  json.RawMessage
	// Result is only populated on post_tool_call events. The runner
	// serializes a tiny slice of fields (Content / IsError) into the
	// stdin JSON; full Result.Files etc. are deliberately omitted to keep
	// hook payloads small.
	Result *tool.Result
}

Event carries the contextual data a hook can see via stdin JSON and the UB_HOOK_* env variables.

type Kind

type Kind string

Kind identifies a hook trigger point.

const (
	KindPreToolCall  Kind = "pre_tool_call"
	KindPostToolCall Kind = "post_tool_call"
	KindPreUserTurn  Kind = "pre_user_turn"
	KindPostUserTurn Kind = "post_user_turn"
)

type NopRunner

type NopRunner struct{}

NopRunner is a Runner that returns an empty Decision for every event. The agent uses it whenever no hooks are configured.

func (NopRunner) Run

func (NopRunner) Run(_ context.Context, _ Event) Decision

Run implements Runner.

type Outcome

type Outcome struct {
	HookIndex int
	Command   []string
	ExitCode  int
	Stdout    string
	Stderr    string
	Duration  time.Duration
	Err       error
}

Outcome captures the result of one hook process.

type Runner

type Runner interface {
	Run(ctx context.Context, event Event) Decision
}

Runner is the contract the agent uses. A nil Runner is treated as no-op at the call site.

func New

func New(cfg config.HooksConfig) Runner

New returns a Runner constructed from the merged config. When no hook entries are configured for any kind, NopRunner is returned so callers pay zero runtime cost.