hooks

package
v0.54.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 14 Imported by: 0

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

View Source
var ErrTimedOut = errors.New("hook timed out")

ErrTimedOut marks a hook that ran into its own bound (hooks.timeout_ms, or stop_wait_sec+2 for Stop) instead of failing: a long Stop wait that reaches its configured end is the normal way such a wait ends, so callers record it apart from a hook command that failed (issue my-tools-4x8a).

Functions

func AdditionalContext

func AdditionalContext(response Response) string

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

func TruncateOutput(value string, maxBytes int) string

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

func New(opts ...Option) (Client, error)

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 Option

type Option func(*commandClient)

Option configures the client New returns.

func WithExtraEnv

func WithExtraEnv(fn func(context.Context) []string) Option

WithExtraEnv adds the variables suga exports to the hook command (the session, its short name and the turn, see wiring's sessionEnvProvider). They are read at every call, so a session switch is followed.

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.

func (PostToolFilter) Match

func (f PostToolFilter) Match(tool string) (string, bool)

Match reports whether tool sends PostToolUse and the name to send.

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).

func (PreToolFilter) Match

func (f PreToolFilter) Match(tool string) (string, bool)

Match reports whether tool sends PreToolUse and the name to send.

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 Result

type Result struct {
	Response Response
	Err      error
}

Result is the outcome of a Stop wait.

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.

func GateOf

func GateOf(client Client) ToolGate

GateOf returns the PreToolUse part of client; nil when it has none.

type Wait

type Wait interface {
	Done() <-chan Result
	// Interrupt ends the wait. It returns a reply that had already been received
	// (Stop block) but not yet consumed, so the caller can still deliver it.
	Interrupt(context.Context) string
}

Wait is a pending Stop hook call.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL