hooks

Documentation

Overview

Package hooks runs user-defined shell commands at agent lifecycle points — the extensibility seam for policy and automation the prompt can't provide (deterministic guards, notifications, context injection). Configuration is plain JSON the user owns: ~/.memcode/hooks.json (user-wide) merged with <root>/.memcode/hooks.json (project; runs after user hooks).

Events and semantics (deliberately Claude-Code-compatible so existing hook scripts port over):

session_start   payload {event, session_id, root}; combined stdout is
                injected into the system prompt as standing context.
pre_tool_use    payload {event, tool, input, session_id, root}. Exit 2
                BLOCKS the tool call and feeds stderr to the model as the
                reason. Any other non-zero exit is a non-blocking warning.
post_tool_use   payload adds {result, is_error}; exit codes are advisory.
session_end     payload {event, session_id, root}; fire-and-forget.

The hook command runs through the platform shell with the payload as JSON on stdin, cwd = project root, and MEMCODE_HOOK_EVENT / MEMCODE_TOOL_NAME / MEMCODE_SESSION_ID / MEMCODE_PROJECT_DIR in the environment. Default timeout 60s per hook (config "timeout" in seconds overrides).

Index

• Constants
• type Hook
• type Result
• type Set
  • func Load(root string) *Set
  • func (s *Set) Empty() bool
  • func (s *Set) Run(ctx context.Context, event, toolName string, payload any) []Result
  • func (s *Set) SetSessionID(id string)
  • func (s *Set) Warnings() []string

Constants

const (
	SessionStart = "session_start"
	PreToolUse   = "pre_tool_use"
	PostToolUse  = "post_tool_use"
	SessionEnd   = "session_end"
)

Events.

Types

type Hook

type Hook struct {
	// Matcher is a regexp matched against the TOOL NAME for pre/post_tool_use
	// (full match; empty = every tool). Ignored for session events.
	Matcher string `json:"matcher,omitempty"`
	Command string `json:"command"`
	Timeout int    `json:"timeout,omitempty"` // seconds; 0 = default
	// contains filtered or unexported fields
}

Hook is one configured command.

type Result

type Result struct {
	Block   bool   // pre_tool_use exit 2
	Message string // block reason (stderr) or warning text
	Stdout  string // captured stdout (used by session_start context injection)
}

Result is one hook execution's outcome.

type Set

type Set struct {
	// contains filtered or unexported fields
}

Set is the merged, compiled hook configuration for one session.

func Load

func Load(root string) *Set

Load reads and merges the user-wide then project hooks files. Missing files are fine (empty set); malformed files or matchers become Warnings, never errors — a broken hooks.json must not take the agent down.

func (*Set) Empty

func (s *Set) Empty() bool

Empty reports whether no hooks are configured (the fast path).

func (*Set) Run

func (s *Set) Run(ctx context.Context, event, toolName string, payload any) []Result

Run executes every hook for event whose matcher accepts toolName, in config order, and returns their results. payload is marshalled once onto stdin.

func (*Set) SetSessionID

func (s *Set) SetSessionID(id string)

SetSessionID stamps the CURRENT session id onto the set so hook commands see it as MEMCODE_SESSION_ID. Callers re-stamp on use (the id changes across /resume and /fork while the loaded set is cached for the Session's lifetime).

func (*Set) Warnings

func (s *Set) Warnings() []string

Warnings are non-fatal load problems (bad JSON, bad matchers) for surfacing once per session.