Documentation
¶
Overview ¶
Package hooks runs user-configured commands before and after tool calls, and stop hooks that verify a run before it ends successfully. Hooks are trusted local executables from the user's config; they are a guardrail and automation point, not a sandbox.
Index ¶
Constants ¶
const ( SchemaVersion = 1 PreTool = "pre_tool" PostTool = "post_tool" Stop = "stop" MaxFeedback = 8 << 10 // bytes of one post_tool or stop hook's feedback // MaxStopContinuationsLimit is the largest allowed max_stop_continuations. MaxStopContinuationsLimit = 50 )
const ( Allow = "allow" Deny = "deny" Feedback = "feedback" Error = "error" // Continue is a stop hook's request to send the model back to work. Continue = "continue" )
Decisions reported for each hook run.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Input ¶
type Input struct {
ToolName string `json:"tool_name"`
ToolCallID string `json:"tool_call_id"`
Arguments any `json:"arguments"` // decoded JSON, or the raw string if malformed
Root string `json:"root"`
ReadOnly bool `json:"read_only"`
Step int `json:"step"`
// OutputFile (post_tool only) is the saved full output, relative to
// Root, when tool_output_files saved this result.
OutputFile string `json:"output_file,omitempty"`
// Subagent is the delegate child's id (d1, d2, ...) when a subagent,
// not the main agent, made this call.
Subagent string `json:"subagent,omitempty"`
// Worker is true when that subagent is a worker (w1, w2, ...), which
// works in its own Git worktree.
Worker bool `json:"worker,omitempty"`
}
Input describes the tool call a hook receives as JSON on stdin.
type Result ¶
type Result struct {
Event string
Command string
Decision string // Allow, Deny, Feedback, Continue, or Error
Duration time.Duration
// Denied means the pre_tool call must not run.
Denied bool
// Reason is the deny reason, or the failure when Decision is Error.
Reason string
// Feedback is the marked text to append to the tool result, or, for a
// stop hook that asks to continue, the marked reason for the model.
Feedback string
}
Result reports one hook run.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner holds the validated hooks for one run. A nil Runner runs nothing.
func New ¶
New validates cfg, read from the config file at path, and returns its hooks, or nil when none are configured.
func (*Runner) MaxStopContinuations ¶
MaxStopContinuations is the per-run cap on stop-hook continuations.
type StopInput ¶
type StopInput struct {
// Status is the status the run would end with: Submitted or Completed.
Status string `json:"status"`
Submission string `json:"submission"`
// StructuredOutput is the validated result of an --output-schema run.
StructuredOutput json.RawMessage `json:"structured_output,omitempty"`
Root string `json:"root"`
ReadOnly bool `json:"read_only"`
Step int `json:"step"`
// Continuations counts the stop-hook continuations already made this
// run; StopHookActive is set by Stop to Continuations > 0.
Continuations int `json:"continuations"`
StopHookActive bool `json:"stop_hook_active"`
}
StopInput describes the run outcome a stop hook receives as JSON on stdin.
Source Files
Directories