hooks

Documentation

Index

• Constants
• func ExtractFilePath(toolName string, rawInput string) string
• func RunAgentStopHooks(cfg HookConfig, env HookEnv)
• func RunStreamStopHooks(cfg HookConfig, env HookEnv)
• func ValidateHooks(cfg HookConfig) []string
• type Hook
  • func (h Hook) HasType() HookType
• type HookConfig
• type HookEnv
• type HookPayload
  • func BuildPayload(env HookEnv) HookPayload
  • func (p HookPayload) JSON() []byte
• type HookResult
  • func Dispatch(cfg HookConfig, env HookEnv) HookResult
  • func RunPostHooks(hooks []Hook, env HookEnv) HookResult
  • func RunPreHooks(hooks []Hook, env HookEnv) HookResult
  • func RunUserMessageHooks(hooks []Hook, env HookEnv) HookResult
• type HookType
• type PayloadMsg
• type PayloadResult
• type PayloadStop
• type PayloadTool

Constants

const (
	EventOnUserMessage = "on_user_message"
	EventPreToolUse    = "pre_tool_use"
	EventPostToolUse   = "post_tool_use"
	EventOnAgentStop   = "on_agent_stop"
	EventOnStreamStop  = "on_stream_stop"
)

Event names.

Functions

func ExtractFilePath

func ExtractFilePath(toolName string, rawInput string) string

ExtractFilePath attempts to extract a file path from common tool argument patterns.

func RunAgentStopHooks

func RunAgentStopHooks(cfg HookConfig, env HookEnv)

RunAgentStopHooks runs on_agent_stop hooks asynchronously (fire-and-forget).

func RunStreamStopHooks

func RunStreamStopHooks(cfg HookConfig, env HookEnv)

RunStreamStopHooks runs on_stream_stop hooks asynchronously (fire-and-forget).

func ValidateHooks

func ValidateHooks(cfg HookConfig) []string

ValidateHooks checks a HookConfig for common misconfigurations. Returns a list of error strings (empty if all valid).

Types

type Hook

type Hook struct {
	Match        string            `yaml:"match" json:"match"`                 // glob/pipe/func-call match pattern. "*" matches all.
	Type         HookType          `yaml:"type" json:"type"`                   // "command" (default) or "http"
	Command      string            `yaml:"command" json:"command"`             // shell command (type=command)
	URL          string            `yaml:"url" json:"url"`                     // webhook URL (type=http)
	Method       string            `yaml:"method" json:"method"`               // HTTP method (type=http), default POST
	Headers      map[string]string `yaml:"headers" json:"headers"`             // custom HTTP headers (type=http)
	Timeout      string            `yaml:"timeout" json:"timeout"`             // timeout duration, e.g. "10s" (type=http). Default 10s.
	Secret       string            `yaml:"secret" json:"secret"`               // HMAC-SHA256 signing key (type=http)
	InjectOutput bool              `yaml:"inject_output" json:"inject_output"` // (post_tool_use only) inject stdout/response body into tool result
}

Hook represents a single hook bound to one event.

func (Hook) HasType

func (h Hook) HasType() HookType

HasType returns the effective type, defaulting to command for backward compatibility.

type HookConfig

type HookConfig struct {
	OnUserMessage []Hook `yaml:"on_user_message" json:"on_user_message"`
	PreToolUse    []Hook `yaml:"pre_tool_use" json:"pre_tool_use"`
	PostToolUse   []Hook `yaml:"post_tool_use" json:"post_tool_use"`
	OnAgentStop   []Hook `yaml:"on_agent_stop" json:"on_agent_stop"`
	OnStreamStop  []Hook `yaml:"on_stream_stop" json:"on_stream_stop"`
}

HookConfig holds all hooks from configuration, keyed by event.

type HookEnv

type HookEnv struct {
	// Universal
	Event      string // event name (EventPreToolUse, etc.)
	SessionID  string
	Workspace  string
	WorkingDir string

	// Tool context (pre_tool_use, post_tool_use)
	ToolName string
	FilePath string // extracted from tool arguments when applicable
	RawInput string // raw JSON tool arguments
	ToolID   string

	// Tool result (post_tool_use only)
	ToolSuccess  bool
	ToolError    string
	ToolResult   string // truncated tool output (first 4KB)
	ToolDuration string // human-readable duration

	// User message (on_user_message only)
	UserMessage string

	// Stop context (on_agent_stop, on_stream_stop only)
	StopReason string // "completed", "cancelled", "error"
	StopError  string
}

HookEnv holds all context data passed to hook commands and webhooks. It is the Go-native representation of the standardized payload.

type HookPayload

type HookPayload struct {
	Event     string `json:"event"`     // event name
	Timestamp string `json:"timestamp"` // RFC3339
	SessionID string `json:"session_id,omitempty"`
	Workspace string `json:"workspace,omitempty"`

	Tool   *PayloadTool   `json:"tool,omitempty"`    // pre/post_tool_use
	Result *PayloadResult `json:"result,omitempty"`  // post_tool_use only
	Msg    *PayloadMsg    `json:"message,omitempty"` // on_user_message only
	Stop   *PayloadStop   `json:"stop,omitempty"`    // on_agent_stop / on_stream_stop
}

HookPayload is the standardized JSON payload sent to all hooks. For command hooks: serialized to GGCODE_HOOK_PAYLOAD env var + stdin. For http hooks: sent as the POST request body.

func BuildPayload

func BuildPayload(env HookEnv) HookPayload

BuildPayload constructs the standardized payload from HookEnv.

func (HookPayload) JSON

func (p HookPayload) JSON() []byte

JSON serializes the payload to JSON bytes.

type HookResult

type HookResult struct {
	Allowed bool   // false means block the operation (pre hooks only)
	Output  string // captured stdout or HTTP response body (for inject_output)
	Err     error
}

HookResult is the result of running one or more hooks.

func Dispatch

func Dispatch(cfg HookConfig, env HookEnv) HookResult

Dispatch runs hooks for a given event. It is the single entry point for all hook execution.

For blocking events (on_user_message, pre_tool_use): runs synchronously. Returns HookResult with Allowed=false if any hook blocks.

For non-blocking events (post_tool_use, on_agent_stop, on_stream_stop): post_tool_use runs synchronously (to allow inject_output). on_agent_stop and on_stream_stop run asynchronously (fire-and-forget).

func RunPostHooks

func RunPostHooks(hooks []Hook, env HookEnv) HookResult

RunPostHooks runs post_tool_use hooks synchronously. Non-blocking; collects inject_output.

func RunPreHooks

func RunPreHooks(hooks []Hook, env HookEnv) HookResult

RunPreHooks runs pre_tool_use hooks synchronously. Blocking: exit 2 / HTTP 403.

func RunUserMessageHooks

func RunUserMessageHooks(hooks []Hook, env HookEnv) HookResult

RunUserMessageHooks runs on_user_message hooks synchronously. Blocking.

type HookType

type HookType string

HookType determines how a hook is executed.

const (
	HookTypeCommand HookType = "command" // execute a local shell command
	HookTypeHTTP    HookType = "http"    // send an HTTP POST webhook
)

type PayloadMsg

type PayloadMsg struct {
	Role    string `json:"role"`    // always "user"
	Content string `json:"content"` // text content
}

type PayloadResult

type PayloadResult struct {
	Success    bool   `json:"success"`
	Error      string `json:"error,omitempty"`
	Output     string `json:"output,omitempty"` // truncated to 4KB
	DurationMs int64  `json:"duration_ms,omitempty"`
}

type PayloadStop

type PayloadStop struct {
	Reason string `json:"reason"` // "completed", "cancelled", "error"
	Error  string `json:"error,omitempty"`
}

type PayloadTool

type PayloadTool struct {
	Name     string          `json:"name"`
	Input    json.RawMessage `json:"input,omitempty"`     // raw JSON tool arguments
	FilePath string          `json:"file_path,omitempty"` // convenience: extracted path
}