agenthooks

Documentation

Index

• func BackupFile(path, label string) error
• func HasCommand(hooks map[string]any, match CommandPredicate) bool
• func ReadJSONFile(path, description string) (map[string]any, error)
• func ShellQuote(value string) string
• func SplitCommand(command string) ([]string, bool)
• func ToJSONAny(value any) (any, error)
• func WithoutOwnedHandlers(raw any, isOwned CommandPredicate) []any
• func WriteJSONFile(path string, settings map[string]any) error
• func WriteRawFile(path string, data []byte) error
• type CommandHandler
• type CommandHook
• type CommandPredicate
• type Config
  • func (c Config) HooksMap() (map[string]any, error)
  • func (c Config) Merge(plan Plan, isOwned CommandPredicate) error
  • func (c Config) Remove(plan Plan, isOwned CommandPredicate) error
• type EventPlan
  • func (p EventPlan) Validate() error
• type MatchSpec
• type OwnerID
• type Placement
• type Plan
  • func (p Plan) Validate() error
• type ProviderID
• type SchemaVersion

Functions

func BackupFile

func BackupFile(path, label string) error

BackupFile copies path aside with a timestamped suffix and matching permissions. Missing files are a no-op.

func HasCommand

func HasCommand(hooks map[string]any, match CommandPredicate) bool

HasCommand reports whether any command handler in any event matches the predicate. Unparseable entries are ignored.

func ReadJSONFile

func ReadJSONFile(path, description string) (map[string]any, error)

ReadJSONFile parses a hook settings file into a generic map so unknown keys survive a read-merge-write round trip. A missing file is an empty map.

func ShellQuote

func ShellQuote(value string) string

ShellQuote quotes one shell token for hook command strings.

func SplitCommand

func SplitCommand(command string) ([]string, bool)

SplitCommand splits a shell-like command string enough for hook ownership detection. It supports quotes and backslash escapes, and reports false for unterminated quotes or trailing escapes.

func ToJSONAny

func ToJSONAny(value any) (any, error)

ToJSONAny round-trips a typed value through JSON so it lands in a generic map with the same shape WriteJSONFile will serialize.

func WithoutOwnedHandlers

func WithoutOwnedHandlers(raw any, isOwned CommandPredicate) []any

WithoutOwnedHandlers filters owned handlers out of every matcher group in an event's group list, dropping groups left without handlers. Unparseable entries are kept verbatim.

func WriteJSONFile

func WriteJSONFile(path string, settings map[string]any) error

WriteJSONFile writes a hook settings map atomically, preserving existing permission bits. If path is a symlink, the symlink is left in place and its resolved target is rewritten.

func WriteRawFile

func WriteRawFile(path string, data []byte) error

WriteRawFile writes data to path atomically (temp file + rename), preserving the existing file's permission bits (new files are 0600). If path is a symlink, the symlink is left in place and its resolved target is rewritten. The bytes are written verbatim, so the caller owns trailing-newline handling.

Types

type CommandHandler

type CommandHandler struct {
	Command string
	Args    []string
}

CommandHandler is the command-bearing portion of an agent hook handler.

type CommandHook

type CommandHook struct {
	Command string
	Args    []string
	Timeout int
	Async   *bool
}

type CommandPredicate

type CommandPredicate func(handler CommandHandler) bool

CommandPredicate reports whether a hook command handler belongs to a particular installer or product.

type Config

type Config struct {
	Settings         map[string]any
	HooksKey         string
	HooksDescription string
}

Config wraps a generic agent hook settings map. The expected JSON shape is:

{
  "hooks": {
    "<EventName>": [
      {"matcher": "...", "hooks": [{"command": "..."}]}
    ]
  }
}

func (Config) HooksMap

func (c Config) HooksMap() (map[string]any, error)

HooksMap returns the hooks object from the config. A missing hooks key is an empty map; a non-object hooks value is left untouched and reported as an error because the file belongs to the user.

func (Config) Merge

func (c Config) Merge(plan Plan, isOwned CommandPredicate) error

Merge removes existing owned handlers for each event in plan, then inserts that event's canonical group. Foreign content is preserved verbatim.

func (Config) Remove

func (c Config) Remove(plan Plan, isOwned CommandPredicate) error

Remove strips owned handlers from the selected events and prunes event keys or the top-level hooks key when they become empty. Foreign hooks survive.

type EventPlan

type EventPlan struct {
	Match     MatchSpec
	Command   CommandHook
	Placement Placement
}

func (EventPlan) Validate

func (p EventPlan) Validate() error

type MatchSpec

type MatchSpec struct {
	Pattern string
}

type OwnerID

type OwnerID string

const OwnerKontextManagedObserve OwnerID = "kontext/managed-observe"

type Placement

type Placement string

const PlacementAppend Placement = "append"

type Plan

type Plan struct {
	Version  SchemaVersion
	Provider ProviderID
	Owner    OwnerID
	Events   map[hook.HookName]EventPlan
}

func (Plan) Validate

func (p Plan) Validate() error

type ProviderID

type ProviderID string

const (
	ProviderClaudeCode ProviderID = "claude-code"
	ProviderCodex      ProviderID = "codex"
)

type SchemaVersion

type SchemaVersion string

const SchemaVersionV1 SchemaVersion = "kontext.agenthooks/v1"