Documentation
¶
Overview ¶
Package hooks implements PreToolUse, PostToolUse, SessionStart, and Stop hook runners.
Mirrors src/utils/hooks/ from the TS source. Hooks are shell commands defined in settings.json under the `hooks` key. They run synchronously before/after tool calls and can block execution by returning non-zero.
Hook input is written as JSON to the hook's stdin. stdout is parsed for optional JSON directives:
{"decision": "block", "reason": "..."} — blocks the tool call
{"decision": "approve"} — approves without further prompting
(anything else / no JSON) — no effect, hook is advisory
Index ¶
Constants ¶
This section is empty.
Variables ¶
subAgentRunner is a function that can run a sub-agent prompt. Injected by the caller (agent loop) when prompt/agent hooks are needed. If nil, prompt/agent hooks are skipped (treated as advisory no-ops).
Functions ¶
func Notify ¶
func Notify(title, body string)
Notify sends a desktop notification on macOS (osascript) and Linux (notify-send). Non-fatal — silently ignored if unavailable. Mirrors the desktop notification behavior from src/utils/hooks/ (notifs/).
func RunSessionStart ¶
func RunSessionStart(ctx context.Context, hooks []settings.HookMatcher, sessionID string)
RunSessionStart runs all SessionStart hooks. Results are advisory — never blocks.
Types ¶
type HookInput ¶
type HookInput struct {
SessionID string `json:"session_id"`
ToolName string `json:"tool_name,omitempty"`
ToolInput map[string]any `json:"tool_input,omitempty"`
Output string `json:"tool_response,omitempty"`
}
HookInput is the JSON payload sent to hook stdin.
type HookOutput ¶
type HookOutput struct {
Decision string `json:"decision"` // "approve" | "block" | ""
Reason string `json:"reason"`
}
HookOutput is the optional JSON a hook writes to stdout.
type Result ¶
type Result struct {
// Blocked is true if any hook returned decision=block.
Blocked bool
// Reason is the block reason if Blocked.
Reason string
// Approved is true if a hook returned decision=approve, bypassing further
// permission prompts for this tool call.
Approved bool
}
Result is the outcome of running a hook set.
func RunPostToolUse ¶
func RunPostToolUse(ctx context.Context, hooks []settings.HookMatcher, sessionID, toolName, output string) Result
RunPostToolUse runs all PostToolUse hooks matching toolName.
func RunPreToolUse ¶
func RunPreToolUse(ctx context.Context, hooks []settings.HookMatcher, sessionID, toolName string, toolInput map[string]any) Result
RunPreToolUse runs all PreToolUse hooks matching toolName. Returns a Result; if Result.Blocked, the tool call should be aborted.
Source Files