Documentation
¶
Overview ¶
Package hooks is loom's side of the Claude Code hooks it registers at launch: the per-instance folder layout, the settings file and hook command, and the scan that turns the files the hooks write into Events. It does not interpret them: session/subagent tracks subagents from them, and session derives the session's status, ID and last message. See docs/superpowers/specs/2026-09-16-subagent-nesting-design.md and docs/superpowers/specs/2026-09-23-claude-hook-events-design.md.
It has no dependency on tmux, the UI or the app, so every piece can be tested against payloads captured from a real Claude session.
Index ¶
- Constants
- Variables
- func EventsDir(dir string) string
- func HookCommand(eventsDir string) string
- func Prepare(dir, autoMemoryDir string) (string, error)
- func SafePath(p string) bool
- func SettingsJSON(eventsDir, autoMemoryDir string) ([]byte, error)
- func SettingsPath(dir string) string
- type Event
- type Request
- type Result
- type Task
Constants ¶
const ( EventSubagentStart = "SubagentStart" EventSubagentStop = "SubagentStop" EventTeammateIdle = "TeammateIdle" EventStop = "Stop" EventSessionEnd = "SessionEnd" EventSessionStart = "SessionStart" EventUserPromptSubmit = "UserPromptSubmit" EventPermissionRequest = "PermissionRequest" EventNotification = "Notification" )
Hook event names loom registers.
const MaxMessageBytes = 4 << 10
MaxMessageBytes caps LastAssistantMessage and Message. Payloads can be up to maxEventBytes, and the text is kept in memory and in every .ev file; a card only shows a message's last few lines.
Variables ¶
var ErrNoHooks = errors.New("hooks: no hooks folder")
ErrNoHooks means the folder or its launch-id is missing: the session was launched without tracking.
var ErrUnknownEvent = errors.New("hooks: unknown hook event")
ErrUnknownEvent is returned by ParseEvent for a JSON object whose hook_event_name is not one loom registers.
var HookEvents = []string{ EventSubagentStart, EventSubagentStop, EventTeammateIdle, EventStop, EventSessionEnd, EventSessionStart, EventUserPromptSubmit, EventPermissionRequest, EventNotification, }
HookEvents lists the registered events.
Functions ¶
func HookCommand ¶
HookCommand returns the shell command every hook runs. It writes the payload Claude pipes on stdin to a new file in eventsDir, first as .tmp and then renamed, so a reader never sees a partial file. It always exits 0 and always reads its whole input, including when eventsDir is gone or the disk is full, so Claude never reports a hook error or fails writing the payload. The name is <unix-nanos>-<pid>; macOS date prints a literal N for %N, so there the pid alone keeps names unique and the scan orders by modification time. eventsDir must satisfy SafePath.
func Prepare ¶
Prepare empties dir and writes a fresh settings.json (with autoMemoryDir, when set), events folder and launch-id for a new launch, returning the launch ID. Events from an earlier launch describe agents that no longer exist, so nothing is kept. launch-id is written last, so a concurrent scan never sees a new ID without its settings.
func SafePath ¶
SafePath reports whether p can be embedded in the single-quoted hook command and the single-quoted --settings flag.
func SettingsJSON ¶
SettingsJSON returns the settings file registering HookCommand for every event in HookEvents. Claude adds these hooks to the user's own. A non-empty autoMemoryDir also sets Claude's autoMemoryDirectory, which outranks the user's own settings for this launch.
func SettingsPath ¶
SettingsPath is the file passed to claude --settings.
Types ¶
type Event ¶
type Event struct {
Name string
AgentID string
AgentType string
TeammateName string
TranscriptPath string
// Tasks is the background_tasks list. HasTasks is false when the field
// was absent, null or malformed. Reconciliation must then do nothing:
// reading an unusable list as empty would remove every agent.
Tasks []Task
HasTasks bool
// SessionID and Source are kept for SessionStart only: the ID names
// the conversation a relaunch resumes, and Source says why the
// session started (startup, resume, clear, compact).
SessionID string
Source string
// ToolName is kept for PermissionRequest only.
ToolName string
// NotificationType and Message are kept for Notification only.
NotificationType string
Message string
// LastAssistantMessage is kept for Stop only.
LastAssistantMessage string
// At is when the hook ran. Scan sets it from the file's name or
// modification time; ParseEvent and Compact leave it alone, since it
// is never part of a payload.
At time.Time
}
Event is one hook event. The same shape covers the raw payload Claude writes and the compact form the scan keeps (see Compact).
func ParseEvent ¶
ParseEvent decodes a raw hook payload or a compact event. It returns an error wrapping ErrUnknownEvent for events loom does not register, and a different error for input that is not a JSON object.
type Request ¶
type Request struct {
// Dir is the instance's hooks folder.
Dir string
// Cold replays the retained .ev log. True for the first scan after a
// launch or a loom restart.
Cold bool
}
Request describes one instance's scan.
type Result ¶
type Result struct {
LaunchID string
Events []Event
// Replayed is true when Events is the full history (Request.Cold).
Replayed bool
}
Result is what one scan found.
func Scan ¶
Scan collects hook events for one instance. New .json files (at most maxNewPerScan, oldest first) are parsed and replaced by compact .ev files that keep their original modification time. A cold scan also replays every .ev file that existed before this scan. Events are returned ordered by when their hooks ran (see eventTime), then file stem, each with At set. Scan only touches the filesystem, so it is safe to run from a tea.Cmd.