Documentation
¶
Index ¶
- type Decision
- type EventType
- type Payload
- type Runner
- func (r *Runner) Middleware() agentcore.ToolMiddleware
- func (r *Runner) RunNotification(_ context.Context, message string)
- func (r *Runner) RunPostStopValidation(ctx context.Context) (failOutput string)
- func (r *Runner) RunPostToolUse(_ context.Context, toolName string, args, output json.RawMessage, isError bool)
- func (r *Runner) RunPreToolUse(ctx context.Context, toolName string, args json.RawMessage) (Decision, error)
- func (r *Runner) RunSessionEnd(ctx context.Context)
- func (r *Runner) RunSessionStart(ctx context.Context)
- func (r *Runner) RunSubagentStop(_ context.Context, agentName string)
- func (r *Runner) RunTaskCompleted(ctx context.Context, previous, current TaskSnapshot) error
- func (r *Runner) RunTaskCreated(ctx context.Context, task TaskSnapshot) error
- func (r *Runner) RunUserPromptSubmit(ctx context.Context, prompt string) (Decision, error)
- func (r *Runner) WrapGate(next agentcore.ToolGate) agentcore.ToolGate
- type TaskSnapshot
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Decision ¶ added in v0.2.0
type Decision struct {
AdditionalContext string
UpdatedInput json.RawMessage
}
Decision is the normalized, allowed-with-extras result handed back to callers. A blocking hook is surfaced as an error by the Run* methods, so Decision only carries the payload that applies when the run proceeds.
type EventType ¶
type EventType string
EventType identifies when a hook fires.
const ( PreToolUse EventType = "PreToolUse" PostToolUse EventType = "PostToolUse" Notification EventType = "Notification" PostStopValidation EventType = "PostStopValidation" TaskCreated EventType = "TaskCreated" TaskCompleted EventType = "TaskCompleted" SessionStart EventType = "SessionStart" SessionEnd EventType = "SessionEnd" UserPromptSubmit EventType = "UserPromptSubmit" SubagentStop EventType = "SubagentStop" )
type Payload ¶
type Payload struct {
Event EventType `json:"event"`
Tool string `json:"tool,omitempty"`
Args json.RawMessage `json:"args,omitempty"`
Output json.RawMessage `json:"output,omitempty"`
IsError bool `json:"is_error,omitempty"`
Message string `json:"message,omitempty"`
Task *TaskSnapshot `json:"task,omitempty"`
PreviousTask *TaskSnapshot `json:"previous_task,omitempty"`
StatusFrom string `json:"status_from,omitempty"`
StatusTo string `json:"status_to,omitempty"`
Prompt string `json:"prompt,omitempty"` // UserPromptSubmit
Agent string `json:"agent,omitempty"` // SubagentStop: teammate name
}
Payload is the JSON written to the hook command's stdin.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner manages and executes hooks.
func New ¶
func New(cfg config.HooksConfig, sessionID string, engine *approval.Engine, model agentcore.ChatModel) *Runner
New parses a HooksConfig and returns a Runner. Returns nil if no valid hooks are found. The model parameter is used for prompt-type hooks and may be nil.
func (*Runner) Middleware ¶
func (r *Runner) Middleware() agentcore.ToolMiddleware
Middleware returns a ToolMiddleware that fires PostToolUse hooks after each tool execution. PreToolUse runs earlier, inside the tool gate (WrapGate), so permission decisions see hook-rewritten arguments; by the time this middleware runs, call.Args already carries the approved final form.
func (*Runner) RunNotification ¶
RunNotification fires matching Notification hooks asynchronously. Uses a detached context so hooks survive parent cancellation.
func (*Runner) RunPostStopValidation ¶ added in v0.1.0
RunPostStopValidation executes matching PostStopValidation hooks synchronously. Returns the output of the first failing hook (non-zero exit, exit-2 block, or approval denial), or "" when every validation passes.
func (*Runner) RunPostToolUse ¶
func (r *Runner) RunPostToolUse(_ context.Context, toolName string, args, output json.RawMessage, isError bool)
RunPostToolUse fires matching PostToolUse hooks asynchronously. Uses a detached context so hooks survive parent cancellation.
func (*Runner) RunPreToolUse ¶
func (r *Runner) RunPreToolUse(ctx context.Context, toolName string, args json.RawMessage) (Decision, error)
RunPreToolUse evaluates PreToolUse hooks. A blocking hook that signals a block returns an error; otherwise the returned Decision may carry an updated tool input or additional context.
func (*Runner) RunSessionEnd ¶ added in v0.1.0
RunSessionEnd fires SessionEnd hooks asynchronously.
func (*Runner) RunSessionStart ¶ added in v0.1.0
RunSessionStart fires SessionStart hooks asynchronously.
func (*Runner) RunSubagentStop ¶ added in v0.2.0
RunSubagentStop fires SubagentStop hooks asynchronously when a teammate's agent loop exits. The hook matcher is tested against the teammate name (an empty matcher fires for every teammate). Observation only — by the time it runs the teammate has already exited, so it cannot keep it alive.
func (*Runner) RunTaskCompleted ¶ added in v0.1.0
func (r *Runner) RunTaskCompleted(ctx context.Context, previous, current TaskSnapshot) error
RunTaskCompleted executes TaskCompleted hooks synchronously. Any blocking hook aborts the completion transition.
func (*Runner) RunTaskCreated ¶ added in v0.1.0
func (r *Runner) RunTaskCreated(ctx context.Context, task TaskSnapshot) error
RunTaskCreated executes TaskCreated hooks synchronously. Any blocking hook aborts the task creation so callers can roll back.
func (*Runner) RunUserPromptSubmit ¶ added in v0.1.0
RunUserPromptSubmit evaluates UserPromptSubmit hooks. A blocking hook rejects the prompt with an error; otherwise the returned Decision may carry additional context to prepend to the turn.
func (*Runner) WrapGate ¶ added in v0.3.0
WrapGate returns a ToolGate that runs PreToolUse hooks before delegating to next (the permission gate). Ordering matches Claude Code: hooks fire first — a blocking hook denies the call, an updated_input rewrite is applied to the request — and the permission decision is then made on the FINAL arguments. The rewrite is surfaced to the kernel via GateDecision.UpdatedArgs so the tool executes exactly what was approved.
type TaskSnapshot ¶ added in v0.1.0
type TaskSnapshot struct {
ID string `json:"id"`
Subject string `json:"subject"`
Description string `json:"description,omitempty"`
ActiveForm string `json:"active_form,omitempty"`
Status string `json:"status"`
Owner string `json:"owner,omitempty"`
Blocks []string `json:"blocks,omitempty"`
BlockedBy []string `json:"blocked_by,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
}
TaskSnapshot is the task payload exposed to lifecycle hooks.
Source Files