Documentation
¶
Overview ¶
Package hooks runs validated layered hook actions at agent lifecycle points.
Index ¶
Constants ¶
This section is empty.
Variables ¶
Functions ¶
func DefaultStateRoot ¶ added in v0.11.0
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 ¶
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
// Metrics records each hook event that matched a hook. Nil disables it.
Metrics *metrics.Metrics
}
Options defines the execution policy for one turn's resolved hook list.
type Outcome ¶
Outcome is the non-destructive effect of a hook invocation. A caller makes injected messages model-visible at its next safe protocol boundary.