Documentation
¶
Overview ¶
Package hooks runs the user-configured hook command for chat events.
Each event runs hooks.command once with the event as one JSON line on stdin. Events follow the Claude Code hook format (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd) plus the suga-specific Interrupt, sent when the person types while a Stop call is still waiting. The command answers on stdout with optional JSON ({"decision","reason","hookSpecificOutput":{"additionalContext"}}); a Stop answer with decision "block" and a reason starts a new turn with that reason as input. Anything on stderr is shown to the person as a notice. Failures are logged and never stop the chat.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AdditionalContext ¶
AdditionalContext is the trimmed additional context of a hook response.
func StopBackground ¶
func StopBackground() bool
StopBackground reports hooks.stop_background: chat runs the Stop hook as a background task that typing does not interrupt; a block reply reaches the model as a task notice (and wakes an idle chat).
func TruncateOutput ¶
TruncateOutput cuts value to at most maxBytes without splitting a UTF-8 rune.
Types ¶
type Client ¶
type Client interface {
Call(context.Context, Event) Response
StartStop(context.Context, Event) Wait
// PostToolName reports whether a PostToolUse event is sent for the tool,
// and the tool name to put in it.
PostToolName(tool string) (string, bool)
}
Client calls the hook command.
func New ¶
New returns the hook client for the current configuration, or nil when hooks are disabled: hooks.command is unset or empty, or SUGA_HOOKS=off (tests use it so a local `go test` never runs a developer's configured hook command). Configuration keys:
- hooks.command: argv list, executed directly (never through a shell)
- hooks.timeout_ms: timeout of every non-Stop event (default 3000)
- hooks.stop_args: argv appended only to the Stop event
- hooks.stop_wait_sec: Stop waits up to stop_wait_sec+2 seconds; 0 uses timeout_ms (with stop_background: no limit of its own, tasks.max_duration applies)
- hooks.stop_background: run Stop as a background task (see StopBackground)
- hooks.post_tool_use.tools / .name: PostToolUse tool globs and the name sent
opts add what the caller knows (WithExtraEnv: the session variables of the command's environment).
type Event ¶
type Event struct {
Name string `json:"hook_event_name"`
SessionID string `json:"session_id"`
CWD string `json:"cwd"`
TranscriptPath string `json:"transcript_path,omitempty"`
Source string `json:"source,omitempty"`
Prompt string `json:"prompt,omitempty"`
// Injected marks a UserPromptSubmit whose input did not come from terminal typing
// (Stop-block reply/notification or a local-socket delivery). Omitted when false.
Injected bool `json:"injected,omitempty"`
LastAssistant string `json:"last_assistant_message,omitempty"`
StopHookActive bool `json:"stop_hook_active"`
ToolName string `json:"tool_name,omitempty"`
ToolInput map[string]any `json:"tool_input,omitempty"`
ToolOutput string `json:"tool_output,omitempty"`
}
Event is one hook invocation payload.
type PostToolFilter ¶
type PostToolFilter struct {
// Tools are tool name globs (path.Match); empty sends no PostToolUse at all.
Tools []string
// Name replaces the tool name in the event; empty keeps the original.
Name string
}
PostToolFilter selects the tools that send PostToolUse and the name they are sent as.
type PreToolFilter ¶
type PreToolFilter struct {
// Tools are tool name globs (path.Match); empty sends no PreToolUse at all.
Tools []string
// Name replaces the tool name in the event; empty keeps the original.
Name string
}
PreToolFilter selects the tools that are announced with PreToolUse (the same shape as PostToolFilter).
type Response ¶
type Response struct {
Decision string
Reason string
AdditionalContext string
// Notice is a one-line message the hook command wants the person at this
// terminal to see (e.g. the session was taken over elsewhere). The command
// prints it on its stderr, so the client captures that stream.
Notice string
// UpdatedInput replaces the arguments of the call (PreToolUse); nil keeps them.
UpdatedInput map[string]any
}
Response is the decoded hook answer.
type ToolGate ¶
type ToolGate interface {
PreTool(ctx context.Context, event Event) (Response, error)
// PreToolName reports whether a PreToolUse event is sent for the tool, and
// the tool name to put in it.
PreToolName(tool string) (string, bool)
}
ToolGate is the pre-run part of a Client: the PreToolUse event, whose answer can refuse the call or replace its arguments. PreTool reports a failure of the command (a timeout, a non-zero exit, an unreadable answer) as an error instead of swallowing it like Call does: the answer decides whether a call runs, so a broken hook has to fail closed.