Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var AllEvents = []Event{ PreEdit, PostEdit, PreCommand, PostCommand, PreSession, PostSession, PreCommit, PostCommit, OnError, OnToolCall, OnPermissionRequest, SessionStart, SessionEnd, UserPromptSubmit, Stop, StopFailure, PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied, PreCompact, PostCompact, SubagentStart, SubagentStop, WorkflowStart, WorkflowStop, WorkflowFailure, Notification, ConfigChange, FileChanged, PrePlan, PostPlan, PreFleet, PostFleet, OnAgentSpawn, OnAgentComplete, OnTokenLimit, OnCronTick, }
AllEvents lists every valid lifecycle event for documentation and validation.
Functions ¶
func DefaultTrustStorePath ¶ added in v0.24.0
func DefaultTrustStorePath() string
DefaultTrustStorePath returns the user-scoped hook trust store location.
Types ¶
type Event ¶
type Event string
Event is a lifecycle event that can trigger hooks.
const ( PreEdit Event = "pre-edit" PostEdit Event = "post-edit" PreCommand Event = "pre-command" PostCommand Event = "post-command" PreSession Event = "pre-session" PostSession Event = "post-session" PreCommit Event = "pre-commit" PostCommit Event = "post-commit" OnError Event = "on-error" OnToolCall Event = "on-tool-call" OnPermissionRequest Event = "on-permission-request" SessionStart Event = "session-start" SessionEnd Event = "session-end" UserPromptSubmit Event = "user-prompt-submit" Stop Event = "stop" StopFailure Event = "stop-failure" PreToolUse Event = "pre-tool-use" PostToolUse Event = "post-tool-use" PostToolUseFailure Event = "post-tool-use-failure" PermissionRequest Event = "permission-request" PermissionDenied Event = "permission-denied" PreCompact Event = "pre-compact" PostCompact Event = "post-compact" SubagentStart Event = "subagent-start" SubagentStop Event = "subagent-stop" WorkflowStart Event = "workflow-start" WorkflowStop Event = "workflow-stop" WorkflowFailure Event = "workflow-failure" Notification Event = "notification" ConfigChange Event = "config-change" FileChanged Event = "file-changed" // Plan lifecycle PrePlan Event = "pre-plan" PostPlan Event = "post-plan" // Fleet lifecycle PreFleet Event = "pre-fleet" PostFleet Event = "post-fleet" // Agent lifecycle OnAgentSpawn Event = "on-agent-spawn" OnAgentComplete Event = "on-agent-complete" // Token and cron events OnTokenLimit Event = "on-token-limit" OnCronTick Event = "on-cron-tick" )
type Hook ¶
type Hook struct {
Command string `yaml:"command"`
CommandWindows string `yaml:"command_windows,omitempty"`
Glob string `yaml:"glob,omitempty"`
Event Event `yaml:"-"`
SourceKind SourceKind `yaml:"-"`
SourceID string `yaml:"-"`
SourcePath string `yaml:"-"`
PluginName string `yaml:"-"`
PluginVersion string `yaml:"-"`
Hash string `yaml:"-"`
Trusted bool `yaml:"-"`
Disabled bool `yaml:"-"`
UnsupportedPlatform bool `yaml:"-"`
}
Hook defines a single hook command with an optional glob pattern.
func (Hook) DescriptorHash ¶ added in v0.24.0
DescriptorHash returns a stable hash for trust decisions. It intentionally excludes SourcePath so trust can move across checkouts and machines.
type HookConfig ¶
HookConfig holds the full hooks configuration.
func Load ¶
func Load(workingDir string) (*HookConfig, error)
Load reads hook configs from ~/.ratchet/hooks.yaml and .ratchet/hooks.yaml. Project-level hooks (.ratchet/hooks.yaml) override global ones.
func LoadWithOptions ¶ added in v0.24.0
func LoadWithOptions(opts LoadOptions) (*HookConfig, error)
LoadWithOptions reads hook configs and annotates each hook with source and trust metadata. User hooks remain trusted by default for compatibility.
func (*HookConfig) AnnotateSource ¶ added in v0.24.0
func (hc *HookConfig) AnnotateSource(meta SourceMetadata)
AnnotateSource applies stable source and trust metadata to every hook.
func (*HookConfig) ApplyTrust ¶ added in v0.24.0
func (hc *HookConfig) ApplyTrust(store *TrustStore)
ApplyTrust refreshes hook hashes and trust decisions against the supplied store. This lets long-running daemons observe trust changes without restart.
func (*HookConfig) Run ¶
func (hc *HookConfig) Run(event Event, data map[string]string) error
Run executes all hooks for the given event, expanding templates with data. data keys include: "file", "command", "error", "tool", "session_id", "plan_id", "fleet_id", "agent_name", "agent_role", "cron_id", "tokens_used", "tokens_limit"
type LoadOptions ¶ added in v0.24.0
type LoadOptions struct {
WorkingDir string
TrustStore *TrustStore
SkipUser bool
SkipProject bool
}
LoadOptions controls hook loading and trust annotation.
type SourceKind ¶ added in v0.24.0
type SourceKind string
SourceKind identifies where a hook declaration came from.
const ( SourceUser SourceKind = "user" SourceProject SourceKind = "project" SourcePlugin SourceKind = "plugin" )
type SourceMetadata ¶ added in v0.24.0
type SourceMetadata struct {
Kind SourceKind
ID string
Path string
PluginName string
PluginVersion string
TrustByDefault bool
TrustStore *TrustStore
}
SourceMetadata describes the source applied to a loaded HookConfig.
type TrustStore ¶ added in v0.24.0
type TrustStore struct {
Trusted map[string]bool `json:"trusted,omitempty"`
Disabled map[string]bool `json:"disabled,omitempty"`
// contains filtered or unexported fields
}
TrustStore persists explicit hook trust and disable decisions by descriptor hash. Disabled hashes always win over trusted hashes.
func LoadTrustStore ¶ added in v0.24.0
func LoadTrustStore(path string) (*TrustStore, error)
LoadTrustStore loads hook trust state from path, creating an empty in-memory store when the file does not exist.
func (*TrustStore) Disable ¶ added in v0.24.0
func (s *TrustStore) Disable(hash string) error
Disable records hash as disabled and removes any explicit trust.
func (*TrustStore) IsDisabled ¶ added in v0.24.0
func (s *TrustStore) IsDisabled(hash string) bool
func (*TrustStore) IsTrusted ¶ added in v0.24.0
func (s *TrustStore) IsTrusted(hash string) bool
func (*TrustStore) Trust ¶ added in v0.24.0
func (s *TrustStore) Trust(hash string) error
Trust records hash as trusted and removes any disabled marker.
func (*TrustStore) Untrust ¶ added in v0.24.0
func (s *TrustStore) Untrust(hash string) error
Untrust removes explicit trust without enabling a disabled hook.
Source Files