hooks

package
v0.43.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package hooks runs validated layered hook actions at agent lifecycle points.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrDenied               = errors.New("hook denied operation")
	ErrCommandOutputLimit   = errors.New("hook command output limit exceeded")
	ErrEventUnavailable     = errors.New("hook event publisher is unavailable")
	ErrInvalidContextTokens = errors.New("invalid hook context token estimate")
)

Functions

func DefaultStateRoot added in v0.11.0

func DefaultStateRoot(root string) string

DefaultStateRoot returns the stable root for hook state beneath one writable runtime-owned directory. Workers may supply a session-private directory instead of their read-only harness configuration mount.

Types

type Callback added in v0.22.0

type Callback func(context.Context, Invocation) (Outcome, error)

Callback runs beside file actions at a lifecycle boundary.

type CommandInput

type CommandInput struct {
	Command     string
	Args        []string
	Environment map[string]string
	WorkingDir  string
	Stdin       []byte
	MaxOutput   int
}

CommandInput is the fully structured event a command action receives on stdin. Arguments are passed directly without a shell.

type CommandRunner

type CommandRunner func(context.Context, CommandInput) ([]byte, error)

CommandRunner is a test seam around a direct executable invocation.

func WithCommander added in v0.22.0

func WithCommander(runner commander.Commander) CommandRunner

WithCommander uses the host process backend for executable hook actions. Output is drained with bounded buffers while the process runs.

type ContextTokenCounter

type ContextTokenCounter func(context.Context, Invocation) (int, error)

ContextTokenCounter estimates the active request's input tokens immediately before a command action runs. It is an estimate for local hook policy, not provider-reported billing usage.

type DenialError added in v0.13.1

type DenialError struct {
	Reason string
}

DenialError carries the exact reason a deny action or command gave. It matches ErrDenied through errors.Is.

The reason is model-facing text such as a project rule, so callers read it with errors.As rather than recovering it from a formatted error chain. A formatted chain adds wrap prefixes and a source location, and cutting those off by searching for the location marker also cuts any reason that happens to contain the same characters.

func (*DenialError) Error added in v0.13.1

func (e *DenialError) Error() string

func (*DenialError) Unwrap added in v0.13.1

func (e *DenialError) Unwrap() error

type EventPublisher

type EventPublisher = events.Publisher

EventPublisher publishes hook notices through the runtime's durable event path when the host wires one.

type Invocation

type Invocation struct {
	Event      harness.HookEvent `json:"event"`
	SessionID  uuid.UUID         `json:"sessionId,omitzero"`
	RequestID  uuid.UUID         `json:"requestId,omitzero"`
	TurnID     uuid.UUID         `json:"turnId,omitzero"`
	AgentRunID *uuid.UUID        `json:"agentRunId,omitempty"`
	Tool       string            `json:"tool,omitempty"`
	CallID     string            `json:"callId,omitempty"`
	Workspace  string            `json:"workspace"`
	Paths      []string          `json:"paths,omitempty"`
	Input      json.RawMessage   `json:"input,omitempty"`
	Result     json.RawMessage   `json:"result,omitempty"`
	Error      string            `json:"error,omitempty"`
	// StateDirectory is a private, per-session directory available only to
	// command actions. It is omitted when an invocation has no session.
	StateDirectory string `json:"stateDirectory,omitempty"`
	// ContextTokens is the estimated active request input token count at the
	// command boundary. Zero means no counter was configured or the estimate
	// itself was zero.
	ContextTokens int `json:"contextTokens"`
	// HasContextTokenEstimate is internal runner state. Callers that already
	// hold an exact active-request estimate set it so Runner does not replace
	// it with a broader lifecycle estimate.
	HasContextTokenEstimate bool `json:"-"`
}

Invocation is one full lifecycle occurrence available to hook matching and command stdin. Paths are canonical host paths chosen by the tool adapter.

type Options

type Options struct {
	Callback            func(context.Context, Invocation) (Outcome, error)
	Snapshot            harness.Snapshot
	Workspace           string
	CommandTimeout      time.Duration
	MaxCommandOutput    int
	Publisher           EventPublisher
	RunCommand          CommandRunner
	StateRoot           string
	ContextTokenCounter ContextTokenCounter
}

Options defines the execution policy for one turn's resolved hook list.

type Outcome

type Outcome struct {
	Injections []string
	Events     []events.Notice
}

Outcome is the non-destructive effect of a hook invocation. A caller makes injected messages model-visible at its next safe protocol boundary.

type Runner

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

Runner executes one turn's immutable, resolved hook list.

func New

func New(options Options) (Runner, error)

New validates execution bounds and captures a snapshot's hook list.

func (Runner) Run

func (r Runner) Run(
	ctx context.Context,
	invocation Invocation,
) (outcome Outcome, runErr error)

Run evaluates matching groups and actions serially. Config-root groups are always executable. Workspace groups require explicit runtime opt-in.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL