hooks

package
v0.1.5 Latest Latest
Warning

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

 Go to latest Published: Mar 23, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package hooks provides lifecycle event hooks for the agentic loop.

Hooks are user-configured shell commands that execute at specific points in the session or tool-use lifecycle. They support environment variable substitution, glob-based tool matching, timeout enforcement, and optional output injection back into the model context.

Only "command" action hooks are supported. All hook execution is sequential in definition order. No LLM-based hooks — intentionally omitted to avoid contaminating evaluation.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func MatchesEvent 

func MatchesEvent(h Hook, event Event, toolName string) bool

MatchesEvent reports whether h should fire for the given event and tool name. toolName is relevant only for PreToolUse / PostToolUse events; pass "" otherwise.

func WithHooks 

func WithHooks(ctx context.Context, h []Hook) context.Context

WithHooks returns a context carrying the hook list.

Types

type Env 

type Env map[string]string

Env carries environment variables for hook command expansion.

type Event 

type Event string

Event identifies a lifecycle point where hooks can fire. 

const (
	SessionStart   Event = "session_start"
	PrePrompt      Event = "pre_prompt"
	PostResponse   Event = "post_response"
	PreToolUse     Event = "pre_tool_use"
	PostToolUse    Event = "post_tool_use"
	ContextCompact Event = "context_compact"
	SessionEnd     Event = "session_end"
)

type Hook 

type Hook struct {
	Name         string
	Event        Event
	Matcher      string        // tool name or glob; "" = match all events of type
	Command      string        // shell command to execute
	Timeout      time.Duration // 0 = no timeout (30s default applied at run time)
	InjectOutput bool          // if true, stdout is returned for context injection
	Enabled      bool
}

Hook is a parsed, ready-to-execute lifecycle hook.

func HooksFromContext 

func HooksFromContext(ctx context.Context) []Hook

HooksFromContext retrieves hooks from ctx. Returns nil when absent.

type HookResult 

type HookResult struct {
	Name     string
	Stdout   string
	Stderr   string
	ExitCode int
	Duration time.Duration
	TimedOut bool
}

HookResult captures the outcome of a single hook execution.

func Run 

func Run(ctx context.Context, hooks []Hook, event Event, toolName string, env Env) []HookResult

Run executes all matching hooks sequentially in definition order. env provides variable substitutions for the command string (e.g. $TOOL_NAME). Returns results for each hook that ran.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.