hooks

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildExecutionSpec

func BuildExecutionSpec(target harness.Target, hook Hook, event Event, context RenderContext, output *RenderOutput) (string, error)

func CandidateToolNames

func CandidateToolNames(raw string) []string

func CheckSupport

func CheckSupport(target harness.Target, hook Hook, support Support, output *RenderOutput, nativeMessage, emulatedMessage string) (bool, error)

func Executable

func Executable() string

Executable is the agentpack binary a staged hook runs: the absolute path of the one that is staging, so that the hook does not depend on what the name `agentpack` resolves to on the agent's PATH (nothing, or another version). A test binary has no hook-exec; there the bare name is kept.

func ExecutableCommand

func ExecutableCommand() string

ExecutableCommand is Executable as a word of a shell command line.

func ExtractJSONObject

func ExtractJSONObject(text string) (any, error)

func ExtractToolName

func ExtractToolName(value any) string

func GuidanceAdditionalContext

func GuidanceAdditionalContext(body string) map[string]any

func GuidanceAdditionalContextContinue

func GuidanceAdditionalContextContinue(body string) map[string]any

func GuidanceHookSpecific

func GuidanceHookSpecific(body string, event Event) map[string]any

func HandlerObject

func HandlerObject(hook Hook, includeExtra bool) map[string]any

func HookAssetRoot

func HookAssetRoot(target harness.Target, root string) string

func HookDispatchCommand

func HookDispatchCommand(target harness.Target, event Event, specsRoot string) string

func HookExecCommand

func HookExecCommand(kind HandlerKind, target harness.Target, specPath string) string

func HookOutput

func HookOutput(target harness.Target, event Event, result Result) any

func LooksLikeCursor

func LooksLikeCursor(value any) bool

LooksLikeCursor reports whether a hooks file found at a default location is in Cursor's format: it names Cursor events and no Claude Code event.

func MatcherMatches

func MatcherMatches(matcher string, candidates []string) bool

func PushDiagnostic

func PushDiagnostic(output *RenderOutput, level string, hook Hook, message string)

func SpecPath

func SpecPath(target harness.Target, root string, hook Hook) string

func StageOriginPackages

func StageOriginPackages(bundle Bundle, target harness.Target, targetRoot string, effective mode.Effective) (map[string]string, error)

func StrictMappingError

func StrictMappingError(target harness.Target, hook Hook, reason string) error

func WriteRenderedFiles

func WriteRenderedFiles(output RenderOutput) error

Types

type Bundle

type Bundle struct {
	Hooks []Hook `json:"hooks,omitempty"`
	// Skipped names what a hook file holds that was not read: an event no
	// agent documents, a handler type agentpack cannot run, a file that does
	// not parse. The rest of the package is unaffected.
	Skipped []Diagnostic `json:"-"`
}

func Collect

func Collect(projectRoot string, lock lockfile.PackLock, seededCodexHooks string, effective mode.Effective) (Bundle, error)

func ParseCodex

func ParseCodex(sourcePath string, value any, base Origin) (Bundle, error)

func ParseCursor

func ParseCursor(sourcePath string, value any, base Origin) (Bundle, error)

ParseCursor reads a Cursor hooks file: {"version": 1, "hooks": {"<event>": [{"command": "...", "matcher": "...", ...}]}}, with camelCase event names and one flat entry per hook.

func ParseNested

func ParseNested(sourcePath string, value any, base Origin) (Bundle, error)

func (Bundle) ForTarget

func (bundle Bundle) ForTarget(target harness.Target) Bundle

ForTarget keeps, for each package, the hooks of one dialect: the target's own when the package publishes hooks for that agent, otherwise Claude Code's, then Cursor's, then Codex's. A package that ships a hook file per agent would otherwise run every one of them on each agent.

type CommandOutput

type CommandOutput struct {
	Stdout, Stderr []byte
	ExitCode       int
}

func RunCommand

func RunCommand(ctx context.Context, spec ExecutionSpec, stdin []byte) (CommandOutput, error)

type Decision

type Decision string
const (
	Allow Decision = "allow"
	Ask   Decision = "ask"
	Deny  Decision = "deny"
)

type Diagnostic

type Diagnostic struct {
	Level, Source, Message string
}

type Dialect

type Dialect string

Dialect says which agent's hook file a hook was published in. The handler reads that agent's input and writes that agent's output.

const (
	ClaudeDialect Dialect = "claude"
	CursorDialect Dialect = "cursor"
	CodexDialect  Dialect = "codex"
)

type DispatchArgs

type DispatchArgs struct {
	Target         harness.Target
	Event          Event
	SpecsDirectory string
	Stdin          []byte
	Client         *http.Client
}

type DispatchOutcome

type DispatchOutcome struct {
	JSON     any
	ExitCode int
}

func Dispatch

func Dispatch(ctx context.Context, arguments DispatchArgs) (DispatchOutcome, error)

type Event

type Event string
const (
	PreToolUse        Event = "PreToolUse"
	PostToolUse       Event = "PostToolUse"
	UserPromptSubmit  Event = "UserPromptSubmit"
	Stop              Event = "Stop"
	SubagentStop      Event = "SubagentStop"
	SessionStart      Event = "SessionStart"
	SessionEnd        Event = "SessionEnd"
	PreCompact        Event = "PreCompact"
	Notification      Event = "Notification"
	PermissionRequest Event = "PermissionRequest"
)
const (
	PostToolUseFailure Event = "PostToolUseFailure"
	SubagentStart      Event = "SubagentStart"
)

Events that Claude Code and Cursor both have, under their Claude Code names.

func ParseCursorEvent

func ParseCursorEvent(value string) (Event, bool)

ParseCursorEvent reads an event name of a Cursor hooks file.

func ParseEvent

func ParseEvent(value string) (Event, bool)

ParseEvent reads an event as a hook file or the hook-exec command line names it: a Claude Code event, its dashed alias, or a Cursor event.

func (Event) Claude

func (event Event) Claude() bool

Claude reports whether Claude Code has the event.

func (Event) CursorName

func (event Event) CursorName() (string, bool)

CursorName is the event's name in a Cursor hooks file, when Cursor has it.

type ExecutionSpec

type ExecutionSpec struct {
	Target     harness.Target `json:"target"`
	Event      Event          `json:"event"`
	Handler    Handler        `json:"handler"`
	WorkingDir string         `json:"working_dir"`
	Matcher    string         `json:"matcher,omitempty"`
}

func LoadExecutionSpec

func LoadExecutionSpec(path string) (ExecutionSpec, error)

type Handler

type Handler struct {
	Kind    HandlerKind
	Command string
	// Args makes a command hook exec-form, as Claude Code writes it: Command
	// is the program and Args its arguments, run without a shell.
	Args    []string
	Timeout *uint64
	URL     string
	Method  string
	Headers map[string]string
	Body    any
	Prompt  string
	Agent   string
	Model   string
}

func (Handler) MarshalJSON

func (handler Handler) MarshalJSON() ([]byte, error)

MarshalJSON preserves the externally tagged representation used by hook execution specs.

func (*Handler) UnmarshalJSON

func (handler *Handler) UnmarshalJSON(data []byte) error

type HandlerKind

type HandlerKind string
const (
	CommandHandler HandlerKind = "command"
	HTTPHandler    HandlerKind = "http"
	PromptHandler  HandlerKind = "prompt"
	AgentHandler   HandlerKind = "agent"
)

type Hook

type Hook struct {
	Event             Event          `json:"event"`
	Dialect           Dialect        `json:"dialect,omitempty"`
	Matcher           string         `json:"matcher,omitempty"`
	Handler           Handler        `json:"handler"`
	Origin            Origin         `json:"origin"`
	MatcherGroupExtra map[string]any `json:"matcher_group_extra,omitempty"`
	RawExtra          map[string]any `json:"raw_extra,omitempty"`
}

func (Hook) Strict

func (hook Hook) Strict() bool

type Layer

type Layer string
const (
	SeededNative Layer = "SeededNative"
	PackPlugin   Layer = "PackPlugin"
	BareSkill    Layer = "BareSkill"
	DotAgents    Layer = "DotAgents"
)

func (Layer) Rank

func (layer Layer) Rank() int

type Origin

type Origin struct {
	Layer             Layer  `json:"layer"`
	Module            string `json:"module"`
	CacheKey          string `json:"cache_key,omitempty"`
	SourceRelative    string `json:"source_rel"`
	SourceRoot        string `json:"source_root"`
	SourceFile        string `json:"source_file"`
	PackageKey        string `json:"package_key"`
	EventIndex        int    `json:"event_index"`
	MatcherGroupIndex int    `json:"matcher_group_index"`
	HookIndex         int    `json:"hook_index"`
}

func (Origin) SourceID

func (origin Origin) SourceID() string

func (Origin) SourcePackage

func (origin Origin) SourcePackage() string

SourcePackage identifies the package (or layer) a hook came from.

type RenderContext

type RenderContext struct {
	ProjectRoot    string
	TargetRoot     string
	StagedPackages map[string]string
}

type RenderOutput

type RenderOutput struct {
	Files       []RenderedFile
	Diagnostics []Diagnostic
	Summary     RenderSummary
}

type RenderSummary

type RenderSummary struct{ Native, Emulated, Degraded, Omitted int }

type RenderedFile

type RenderedFile struct {
	Path string
	JSON any
	Text string
}

type Renderer

type Renderer interface {
	Target() harness.Target
	Render(Bundle, RenderContext) (RenderOutput, error)
}

type Result

type Result struct {
	Decision          Decision       `json:"decision"`
	Message           string         `json:"message,omitempty"`
	AdditionalContext string         `json:"additional_context,omitempty"`
	UpdatedInput      any            `json:"updated_input,omitempty"`
	UpdatedToolOutput any            `json:"updated_tool_output,omitempty"`
	Metadata          map[string]any `json:"metadata,omitempty"`
}

func NormalizeResponse

func NormalizeResponse(value any) Result

func RunAgent

func RunAgent(ctx context.Context, spec ExecutionSpec, stdin []byte) (Result, error)

func RunHTTP

func RunHTTP(ctx context.Context, client *http.Client, spec ExecutionSpec, stdin []byte) (Result, error)

func RunPrompt

func RunPrompt(ctx context.Context, spec ExecutionSpec, stdin []byte) (Result, error)

type Support

type Support struct {
	Kind   SupportKind
	Reason string
}

type SupportKind

type SupportKind string
const (
	Native      SupportKind = "native"
	Emulated    SupportKind = "emulated"
	Degraded    SupportKind = "degraded"
	Unsupported SupportKind = "unsupported"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL