Documentation
¶
Overview ¶
Package hook provides Go-native lifecycle hooks (FR-08): callbacks fired at eight points in the agent loop that can observe state, block or rewrite tool calls, inject context, and gate the Stop transition. A Registry implements harness.HookRunner, so wiring it into a Session needs no glue.
Index ¶
- type Event
- type EventType
- type Func
- type Registry
- func (r *Registry) FireSessionEnd(ctx context.Context)
- func (r *Registry) FireSessionStart(ctx context.Context)
- func (r *Registry) FireSubagentStart(ctx context.Context, agentType string)
- func (r *Registry) FireUserPromptSubmit(ctx context.Context, prompt string) string
- func (r *Registry) On(t EventType, f Func) *Registry
- func (r *Registry) PostToolUse(ctx context.Context, name string, input, result []byte, isErr bool)
- func (r *Registry) PreToolUse(ctx context.Context, name string, input []byte) (bool, string, []byte)
- func (r *Registry) Stop(ctx context.Context, messages []llm.Message) (prevent bool, blockingErrors []string, message string)
- type Result
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Event ¶
type Event struct {
Type EventType
ToolName string
Input json.RawMessage
Result json.RawMessage
IsError bool
Prompt string
AgentType string
Messages []llm.Message
}
Event is the payload passed to a hook. Which fields are set depends on Type.
type EventType ¶
type EventType string
EventType enumerates the eight hook points (FR-08.2).
const ( PreToolUse EventType = "PreToolUse" PostToolUse EventType = "PostToolUse" PostToolUseFailure EventType = "PostToolUseFailure" UserPromptSubmit EventType = "UserPromptSubmit" SessionStart EventType = "SessionStart" SessionEnd EventType = "SessionEnd" Stop EventType = "Stop" SubagentStart EventType = "SubagentStart" )
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds hooks by event type and implements harness.HookRunner.
func (*Registry) FireSessionEnd ¶
func (*Registry) FireSessionStart ¶
FireSessionStart / FireSessionEnd are fire-and-forget notifications.
func (*Registry) FireSubagentStart ¶
FireSubagentStart notifies that a subagent is starting.
func (*Registry) FireUserPromptSubmit ¶
FireUserPromptSubmit runs UserPromptSubmit hooks and returns concatenated additional context to inject (empty if none).
func (*Registry) PostToolUse ¶
PostToolUse runs PostToolUse hooks (and PostToolUseFailure on error).
func (*Registry) PreToolUse ¶
func (r *Registry) PreToolUse(ctx context.Context, name string, input []byte) (bool, string, []byte)
PreToolUse runs PreToolUse hooks. The first block halts; the last non-empty UpdatedInput wins.
func (*Registry) Stop ¶
func (r *Registry) Stop(ctx context.Context, messages []llm.Message) (prevent bool, blockingErrors []string, message string)
Stop runs Stop hooks and reports two distinct outcomes: a hook may hard-terminate the loop (preventContinuation), or it may force the loop to continue by emitting blocking errors injected as messages (FR-08.4). preventContinuation wins if any hook sets it.
type Result ¶
type Result struct {
// Decision is "block" to halt the action, "approve"/"" to continue.
Decision string
// Message explains a block (shown to the model).
Message string
// UpdatedInput optionally rewrites a tool's input (PreToolUse).
UpdatedInput json.RawMessage
// AdditionalContext is injected into the conversation (UserPromptSubmit, Stop).
AdditionalContext string
// PreventContinuation, on a Stop hook, hard-terminates the loop
// (stop_hook_prevented) even if other logic would continue. A "block"
// decision instead forces the loop to continue with AdditionalContext
// injected (stop_hook_blocking).
PreventContinuation bool
}
Result is a hook's response (FR-08.3).
Source Files