hooks

package
v0.21.0 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: MIT Imports: 20 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 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.

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 {
	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
}

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