hooks

package
v1.5.4 Latest Latest
Warning

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

 Go to latest Published: Jul 2, 2026 License: Apache-2.0 Imports: 11 Imported by: 7

Documentation

Overview

Package hooks provides synchronous interception points for provider calls, tool execution, and session lifecycle in the PromptKit runtime.

Index

Constants

View Source 
const (
	HookTypeProvider = "provider"
	HookTypeTool     = "tool"
	HookTypeSession  = "session"
	HookTypeEval     = "eval"
)

Hook type names as used in config.ExecHook.Hook.

Variables

View Source 
var Allow = Decision{Allow: true} //nolint:gochecknoglobals // convenience sentinel

Allow is the zero-cost approval decision.

Functions

func BuildExecHooks added in v1.5.2 

func BuildExecHooks(bindings map[string]*config.ExecHook, sandboxes map[string]sandbox.Sandbox) (
	provider []ProviderHook, tool []ToolHook, session []SessionHook, err error)

BuildExecHooks converts runtime-config exec-hook bindings into provider, tool, and session hook instances, resolving each binding's named sandbox from the provided map. Bindings with Hook=="eval" are skipped — eval hooks live in the evals package and are wired by the caller. This is the single source of truth for turning config.ExecHook bindings into runtime hooks, used by both the SDK and Arena so the two never drift.

func ResolveSandboxes added in v1.5.2 

func ResolveSandboxes(specs map[string]*config.SandboxConfig) (map[string]sandbox.Sandbox, error)

ResolveSandboxes builds a map from declared sandbox names to ready Sandbox instances using the process-wide factory registry. Factories must have been registered (via sandbox.RegisterFactory or a backend's init) beforehand. Shared by the SDK and Arena so both resolve sandboxes identically.

Types

type ChunkInterceptor 

type ChunkInterceptor interface {
	OnChunk(ctx context.Context, chunk *providers.StreamChunk) Decision
}

ChunkInterceptor is an opt-in streaming extension for ProviderHook. ProviderHooks that also implement ChunkInterceptor will have OnChunk called for each streaming chunk, enabling early abort.

type Decision 

type Decision struct {
	Allow    bool
	Reason   string
	Metadata map[string]any
	// Enforced indicates the hook already applied enforcement (e.g., truncated
	// or replaced content on the response). When true, the provider stage
	// records the validation result but continues the pipeline instead of
	// returning an error.
	Enforced bool
}

Decision is the result of a hook evaluation.

func Deny 

func Deny(reason string) Decision

Deny creates a denial decision with a reason.

func DenyWithMetadata 

func DenyWithMetadata(reason string, metadata map[string]any) Decision

DenyWithMetadata creates a denial decision with a reason and metadata.

func Enforced added in v1.3.12 

func Enforced(reason string, metadata map[string]any) Decision

Enforced creates an enforced decision — the hook applied enforcement (truncation, content replacement) and the pipeline should continue.

type ExecHookConfig added in v1.3.12 

type ExecHookConfig struct {
	Name      string
	Command   string
	Args      []string
	Env       []string
	TimeoutMs int
	Phases    []string
	Mode      string // "filter" | "observe"
	Sandbox   sandbox.Sandbox
}

ExecHookConfig holds the configuration for creating exec-based hooks.

Sandbox, when non-nil, controls how the hook subprocess is launched. When nil, the exec hooks fall back to the built-in direct sandbox which matches the historical behavior: exec.CommandContext(Command, Args...) in-process with the local environment. SDK consumers that want their hooks to run elsewhere — in a sidecar, a disposable container, a managed cloud sandbox — construct a Sandbox implementation and pass it here.

type ExecProviderHook added in v1.3.12 

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

ExecProviderHook implements ProviderHook by spawning an external subprocess.

func NewExecProviderHook added in v1.3.12 

func NewExecProviderHook(cfg *ExecHookConfig) *ExecProviderHook

NewExecProviderHook creates a new ExecProviderHook from the given config.

func (*ExecProviderHook) AfterCall added in v1.3.12 

func (h *ExecProviderHook) AfterCall(
	ctx context.Context, req *ProviderRequest, resp *ProviderResponse,
) Decision

AfterCall intercepts an LLM provider call after it completes.

func (*ExecProviderHook) BeforeCall added in v1.3.12 

func (h *ExecProviderHook) BeforeCall(ctx context.Context, req *ProviderRequest) Decision

BeforeCall intercepts an LLM provider call before it is sent.

func (*ExecProviderHook) Name added in v1.3.12 

func (h *ExecProviderHook) Name() string

Name returns the hook name.

type ExecSessionHook added in v1.3.12 

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

ExecSessionHook implements SessionHook by spawning an external subprocess.

func NewExecSessionHook added in v1.3.12 

func NewExecSessionHook(cfg *ExecHookConfig) *ExecSessionHook

NewExecSessionHook creates a new ExecSessionHook from the given config.

func (*ExecSessionHook) Name added in v1.3.12 

func (h *ExecSessionHook) Name() string

Name returns the hook name.

func (*ExecSessionHook) OnSessionEnd added in v1.3.12 

func (h *ExecSessionHook) OnSessionEnd(ctx context.Context, event SessionEvent) error

OnSessionEnd handles the session end event.

func (*ExecSessionHook) OnSessionStart added in v1.3.12 

func (h *ExecSessionHook) OnSessionStart(ctx context.Context, event SessionEvent) error

OnSessionStart handles the session start event.

func (*ExecSessionHook) OnSessionUpdate added in v1.3.12 

func (h *ExecSessionHook) OnSessionUpdate(ctx context.Context, event SessionEvent) error

OnSessionUpdate handles a session update event.

type ExecToolHook added in v1.3.12 

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

ExecToolHook implements ToolHook by spawning an external subprocess.

func NewExecToolHook added in v1.3.12 

func NewExecToolHook(cfg *ExecHookConfig) *ExecToolHook

NewExecToolHook creates a new ExecToolHook from the given config.

func (*ExecToolHook) AfterExecution added in v1.3.12 

func (h *ExecToolHook) AfterExecution(ctx context.Context, req ToolRequest, resp ToolResponse) Decision

AfterExecution intercepts a tool call after execution.

func (*ExecToolHook) BeforeExecution added in v1.3.12 

func (h *ExecToolHook) BeforeExecution(ctx context.Context, req ToolRequest) Decision

BeforeExecution intercepts a tool call before execution.

func (*ExecToolHook) Name added in v1.3.12 

func (h *ExecToolHook) Name() string

Name returns the hook name.

type HookDeniedError 

type HookDeniedError struct {
	HookName string
	HookType string // "provider_before", "provider_after", "chunk", "tool_before", "tool_after"
	Reason   string
	Metadata map[string]any
}

HookDeniedError is returned when a hook denies an operation.

func (*HookDeniedError) Error 

func (e *HookDeniedError) Error() string

type Option 

type Option func(*Registry)

Option configures a Registry during construction.

func WithProviderHook 

func WithProviderHook(h ProviderHook) Option

WithProviderHook registers a provider hook.

func WithSessionHook 

func WithSessionHook(h SessionHook) Option

WithSessionHook registers a session hook.

func WithToolHook 

func WithToolHook(h ToolHook) Option

WithToolHook registers a tool hook.

type ProviderHook 

type ProviderHook interface {
	Name() string
	BeforeCall(ctx context.Context, req *ProviderRequest) Decision
	AfterCall(ctx context.Context, req *ProviderRequest, resp *ProviderResponse) Decision
}

ProviderHook intercepts LLM provider calls.

type ProviderRequest 

type ProviderRequest struct {
	ProviderID   string
	Model        string
	Messages     []types.Message
	SystemPrompt string
	Round        int
	Metadata     map[string]any
}

ProviderRequest describes an LLM call about to be made.

type ProviderResponse 

type ProviderResponse struct {
	ProviderID string
	Model      string
	Message    types.Message
	Round      int
	LatencyMs  int64
}

ProviderResponse describes a completed LLM call.

type Registry 

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

Registry holds registered hooks and provides chain-execution methods. A nil *Registry is safe to use — all Run* methods return Allow / nil.

func NewRegistry 

func NewRegistry(opts ...Option) *Registry

NewRegistry creates a Registry with the given options.

func (*Registry) HasChunkInterceptors 

func (r *Registry) HasChunkInterceptors() bool

HasChunkInterceptors returns true if any registered provider hook implements ChunkInterceptor.

func (*Registry) IsEmpty 

func (r *Registry) IsEmpty() bool

IsEmpty returns true if no hooks are registered.

func (*Registry) RunAfterProviderCall 

func (r *Registry) RunAfterProviderCall(ctx context.Context, req *ProviderRequest, resp *ProviderResponse) Decision

RunAfterProviderCall executes all provider hooks' AfterCall in order. First deny wins and short-circuits.

func (*Registry) RunAfterToolExecution 

func (r *Registry) RunAfterToolExecution(ctx context.Context, req ToolRequest, resp ToolResponse) Decision

RunAfterToolExecution executes all tool hooks' AfterExecution in order. First deny wins and short-circuits.

func (*Registry) RunBeforeProviderCall 

func (r *Registry) RunBeforeProviderCall(ctx context.Context, req *ProviderRequest) Decision

RunBeforeProviderCall executes all provider hooks' BeforeCall in order. First deny wins and short-circuits.

func (*Registry) RunBeforeToolExecution 

func (r *Registry) RunBeforeToolExecution(ctx context.Context, req ToolRequest) Decision

RunBeforeToolExecution executes all tool hooks' BeforeExecution in order. First deny wins and short-circuits.

func (*Registry) RunOnChunk 

func (r *Registry) RunOnChunk(ctx context.Context, chunk *providers.StreamChunk) Decision

RunOnChunk executes all chunk interceptors in order. First deny wins and short-circuits.

func (*Registry) RunSessionEnd 

func (r *Registry) RunSessionEnd(ctx context.Context, event SessionEvent) error

RunSessionEnd executes all session hooks' OnSessionEnd in order. First error short-circuits.

func (*Registry) RunSessionStart 

func (r *Registry) RunSessionStart(ctx context.Context, event SessionEvent) error

RunSessionStart executes all session hooks' OnSessionStart in order. First error short-circuits.

func (*Registry) RunSessionUpdate 

func (r *Registry) RunSessionUpdate(ctx context.Context, event SessionEvent) error

RunSessionUpdate executes all session hooks' OnSessionUpdate in order. First error short-circuits.

type SessionEvent 

type SessionEvent struct {
	SessionID      string
	ConversationID string
	Messages       []types.Message
	TurnIndex      int
	Metadata       map[string]any
}

SessionEvent carries context for session lifecycle hooks.

type SessionHook 

type SessionHook interface {
	Name() string
	OnSessionStart(ctx context.Context, event SessionEvent) error
	OnSessionUpdate(ctx context.Context, event SessionEvent) error
	OnSessionEnd(ctx context.Context, event SessionEvent) error
}

SessionHook tracks session lifecycle.

type ToolHook 

type ToolHook interface {
	Name() string
	BeforeExecution(ctx context.Context, req ToolRequest) Decision
	AfterExecution(ctx context.Context, req ToolRequest, resp ToolResponse) Decision
}

ToolHook intercepts tool execution (LLM-initiated calls only).

type ToolRequest 

type ToolRequest struct {
	Name   string
	Args   json.RawMessage
	CallID string
}

ToolRequest describes a tool call about to be executed.

type ToolResponse 

type ToolResponse struct {
	Name      string
	CallID    string
	Content   string
	Error     string
	LatencyMs int64
}

ToolResponse describes a completed tool execution.

Source Files

View all Source files

Directories

Path Synopsis
Package guardrails provides built-in ProviderHook implementations that bridge the unified eval system to the pipeline's hook infrastructure.
 Package guardrails provides built-in ProviderHook implementations that bridge the unified eval system to the pipeline's hook infrastructure.
Package sandbox defines the Sandbox interface used by exec-backed hooks to externalize where and how the hook subprocess is spawned.
 Package sandbox defines the Sandbox interface used by exec-backed hooks to externalize where and how the hook subprocess is spawned.
direct
Package direct provides the default Sandbox implementation for exec hooks: it spawns the command as a local subprocess via exec.CommandContext.
 Package direct provides the default Sandbox implementation for exec hooks: it spawns the command as a local subprocess via exec.CommandContext.

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.