Documentation
¶
Overview ¶
Package hooks provides user-configurable shell hooks that run before and after LLM tool calls.
Hooks are defined in .aura/config/hooks/**/*.yaml, matched by tool name regex, and executed via mvdan/sh. They receive JSON context on stdin and control behavior through exit codes and optional JSON stdout.
Exit code semantics:
- 0: success — parse stdout for optional {"message": "...", "deny": true, "reason": "..."}
- 2: block (pre) or feedback (post) — stderr is returned as the message
- other: non-blocking — stderr (or stdout) is returned as feedback to the LLM
Index ¶
Constants ¶
const DefaultTimeout = 10 * time.Second
DefaultTimeout is the default hook execution timeout.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Entry ¶
type Entry struct {
Name string // hook name from config map key
Matcher *regexp.Regexp // nil = match all tools
Files string // glob pattern for filepath.Match against basenames
Command string
Timeout time.Duration
Silent bool // suppress all output and exit codes
}
Entry is a compiled hook ready to match and execute.
func (Entry) MatchedPaths ¶
MatchedPaths returns file paths that match the entry's files glob. If no files glob is set, returns all paths unchanged.
type Event ¶
type Event struct {
HookEvent string `json:"hook_event"`
Tool struct {
Name string `json:"name"`
Input any `json:"input"`
Output string `json:"output,omitempty"`
} `json:"tool"`
CWD string `json:"cwd"`
FilePaths []string `json:"file_paths,omitempty"`
}
Event is the JSON payload piped to hook stdin.
type Runner ¶
type Runner struct {
Pre []Entry
Post []Entry
OnStart func(hookName string) // called before each matching hook executes; nil = no-op
}
Runner holds compiled pre and post hooks. Zero value is safe — all methods return immediately when no hooks are configured. This is a value type; no nil checks needed at call sites.
func New ¶
New compiles hook entries from config and orders them by dependency DAG. Panics on invalid regex (fail-fast). Returns error on dependency cycles or missing deps.
Source Files