hooks

package
v0.3.0-beta.39 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package hooks defines the dependency-free core types for the Compozy lifecycle hooks platform.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotImplemented reports that the requested executor seam is reserved for
	// future work.
	ErrNotImplemented = errors.New("hooks: executor not implemented")
	// ErrNativeCallbackRequired reports that a native executor lacks a callback.
	ErrNativeCallbackRequired = errors.New("hooks: native executor callback is required")
	// ErrSubprocessCommandRequired reports that a subprocess executor lacks a
	// command to start.
	ErrSubprocessCommandRequired = errors.New("hooks: subprocess executor command is required")
	// ErrInvalidHookExecutorKind reports an unsupported executor kind.
	ErrInvalidHookExecutorKind = errors.New("hooks: invalid hook executor kind")
)
View Source
var (
	ErrHookPatchRejected           = errors.New("hooks: hook patch rejected")
	ErrPermissionEscalationBlocked = errors.New("hooks: permission escalation blocked")
)
View Source
var (
	// ErrAutomationFireCancelled reports that a sync automation pre-fire hook canceled the dispatch.
	ErrAutomationFireCancelled = errors.New("hooks: automation fire canceled")
)
View Source
var ErrDispatchDepthExceeded = errors.New("hooks: dispatch depth exceeded")
View Source
var ErrExecutorResolverRequired = errors.New("hooks: executor resolver is required")

ErrExecutorResolverRequired reports that full normalization needs an executor resolver to attach the execution implementation.

View Source
var ErrInvalidHookSource = errors.New("hooks: invalid hook source")

Functions

func DefaultHookPriority

func DefaultHookPriority(source HookSource) (int32, error)

DefaultHookPriority returns the documented default priority for the source.

func InputMentionKindValues

func InputMentionKindValues() []string

InputMentionKindValues returns the mention kind wire vocabulary in declaration order.

func LoopGenerationOriginValues

func LoopGenerationOriginValues() []string

LoopGenerationOriginValues returns the closed wire vocabulary in declaration order.

func MatcherFieldAllowedForEvent

func MatcherFieldAllowedForEvent(event HookEvent, field string) bool

MatcherFieldAllowedForEvent reports whether a matcher field is valid for the event family.

func PriorityFromInt

func PriorityFromInt(value int) (int32, error)

PriorityFromInt converts external numeric priority inputs into the compact priority representation used by hook declarations.

func SortResolvedHooks

func SortResolvedHooks(hooks []*ResolvedHook)

SortResolvedHooks sorts the slice in place using deterministic dispatch precedence.

func TurnIDFromPayload

func TurnIDFromPayload(payload any) string

TurnIDFromPayload extracts the current turn identifier from typed payloads when present.

func ValidateHookDecl

func ValidateHookDecl(decl HookDecl) error

ValidateHookDecl validates one declaration without binding an executor.

func ValidateHookDecls

func ValidateHookDecls(decls []HookDecl) error

ValidateHookDecls validates a declaration slice and stops at the first error.

func ValidateMatcherForEvent

func ValidateMatcherForEvent(event HookEvent, matcher HookMatcher) error

ValidateMatcherForEvent ensures only the matcher fields defined for the event family are present.

func WithDispatchEventEmitter

func WithDispatchEventEmitter(ctx context.Context, emitter DispatchEventEmitter) context.Context

WithDispatchEventEmitter attaches a canonical dispatch-event emitter to the context.

func WithHookRunWriter

func WithHookRunWriter(ctx context.Context, writer HookRunWriter) context.Context

WithHookRunWriter attaches a direct hook-run persistence writer to the context.

Types

type AgentCrashedPatch

type AgentCrashedPatch = AgentLifecyclePatch

AgentCrashedPatch is the crashed patch surface.

type AgentCrashedPayload

type AgentCrashedPayload = AgentLifecyclePayload

AgentCrashedPayload is delivered when an agent crashes.

type AgentHeartbeatPolicyResolvedPayload

type AgentHeartbeatPolicyResolvedPayload struct {
	PayloadBase
	AuthoredContextProvenance
	Summary string `json:"summary,omitempty"`
}

AgentHeartbeatPolicyResolvedPayload is delivered after Heartbeat policy/status resolution.

type AgentHeartbeatWakeAfterPayload

type AgentHeartbeatWakeAfterPayload struct {
	PayloadBase
	SessionContext
	WakeEventID       string `json:"wake_event_id,omitempty"`
	Result            string `json:"result,omitempty"`
	Reason            string `json:"reason,omitempty"`
	PolicySnapshotID  string `json:"policy_snapshot_id,omitempty"`
	PolicyDigest      string `json:"policy_digest,omitempty"`
	ConfigDigest      string `json:"config_digest,omitempty"`
	SyntheticPromptID string `json:"synthetic_prompt_id,omitempty"`
	Source            string `json:"source,omitempty"`
}

AgentHeartbeatWakeAfterPayload is delivered after a managed Heartbeat wake decision.

type AgentHeartbeatWakeBeforePayload

type AgentHeartbeatWakeBeforePayload struct {
	PayloadBase
	SessionContext
	PolicySnapshotID string `json:"policy_snapshot_id,omitempty"`
	PolicyDigest     string `json:"policy_digest,omitempty"`
	ConfigDigest     string `json:"config_digest,omitempty"`
	Source           string `json:"source,omitempty"`
	DryRun           bool   `json:"dry_run,omitempty"`
}

AgentHeartbeatWakeBeforePayload is delivered before a managed Heartbeat wake decision.

type AgentLifecyclePatch

type AgentLifecyclePatch struct {
	Labels map[string]string `json:"labels,omitempty"`
}

AgentLifecyclePatch captures optional labels for observation events.

type AgentLifecyclePayload

type AgentLifecyclePayload struct {
	PayloadBase
	SessionContext
	Command  string   `json:"command,omitempty"`
	Args     []string `json:"args,omitempty"`
	Cwd      string   `json:"cwd,omitempty"`
	PID      int      `json:"pid,omitempty"`
	Provider string   `json:"provider,omitempty"`
	Model    string   `json:"model,omitempty"`
	Error    string   `json:"error,omitempty"`
}

AgentLifecyclePayload is shared by spawned, crashed, and stopped hooks.

type AgentPreStartPayload

type AgentPreStartPayload struct {
	PayloadBase
	SessionContext
	Command  string   `json:"command,omitempty"`
	Args     []string `json:"args,omitempty"`
	Cwd      string   `json:"cwd,omitempty"`
	Provider string   `json:"provider,omitempty"`
	Model    string   `json:"model,omitempty"`
}

AgentPreStartPayload is delivered before an agent process starts.

type AgentSoulMutationAfterPayload

type AgentSoulMutationAfterPayload struct {
	PayloadBase
	AuthoredContextProvenance
	AuthoredMutationProvenance
	RevisionID     string `json:"revision_id,omitempty"`
	Action         string `json:"action,omitempty"`
	PreviousDigest string `json:"previous_digest,omitempty"`
	NewDigest      string `json:"new_digest,omitempty"`
}

AgentSoulMutationAfterPayload is delivered after a managed SOUL.md mutation commits.

type AgentSoulSnapshotResolvedPayload

type AgentSoulSnapshotResolvedPayload struct {
	PayloadBase
	AuthoredContextProvenance
}

AgentSoulSnapshotResolvedPayload is delivered after Soul snapshot/read-model resolution.

type AgentSpawnedPatch

type AgentSpawnedPatch = AgentLifecyclePatch

AgentSpawnedPatch is the spawned patch surface.

type AgentSpawnedPayload

type AgentSpawnedPayload = AgentLifecyclePayload

AgentSpawnedPayload is delivered after an agent process starts.

type AgentStartPatch

type AgentStartPatch struct {
	ControlPatch
	Command *string  `json:"command,omitempty"`
	Args    []string `json:"args,omitempty"`
	Cwd     *string  `json:"cwd,omitempty"`
}

AgentStartPatch mutates or denies a pre-start operation.

type AgentStoppedPatch

type AgentStoppedPatch = AgentLifecyclePatch

AgentStoppedPatch is the stopped patch surface.

type AgentStoppedPayload

type AgentStoppedPayload = AgentLifecyclePayload

AgentStoppedPayload is delivered after an agent stops.

type AuthoredContextObservationPatch

type AuthoredContextObservationPatch = AutonomyObservationPatch

AuthoredContextObservationPatch captures labels on soul and heartbeat observations.

type AuthoredContextProvenance

type AuthoredContextProvenance struct {
	WorkspaceID      string `json:"workspace_id,omitempty"`
	AgentName        string `json:"agent_name,omitempty"`
	SourcePath       string `json:"source_path,omitempty"`
	SnapshotID       string `json:"snapshot_id,omitempty"`
	Digest           string `json:"digest,omitempty"`
	ConfigDigest     string `json:"config_digest,omitempty"`
	ValidationStatus string `json:"validation_status,omitempty"`
	Valid            bool   `json:"valid"`
	Active           bool   `json:"active"`
	Reason           string `json:"reason,omitempty"`
}

AuthoredContextProvenance carries redacted Soul/Heartbeat source identity.

type AuthoredMutationProvenance

type AuthoredMutationProvenance struct {
	ActorKind  string `json:"actor_kind,omitempty"`
	ActorID    string `json:"actor_id,omitempty"`
	OriginKind string `json:"origin_kind,omitempty"`
	OriginRef  string `json:"origin_ref,omitempty"`
}

AuthoredMutationProvenance records who caused a managed authored-context mutation.

type AutomationFirePatch

type AutomationFirePatch struct {
	Prompt *string `json:"prompt,omitempty"`
	Cancel bool    `json:"cancel,omitempty"`
}

AutomationFirePatch mutates or cancels one automation pre-fire dispatch.

type AutomationJobPostFirePayload

type AutomationJobPostFirePayload struct {
	ProfileID   string `json:"profile_id,omitempty"`
	JobID       string `json:"job_id"`
	JobName     string `json:"job_name,omitempty"`
	AgentName   string `json:"agent_name,omitempty"`
	WorkspaceID string `json:"workspace_id,omitempty"`
	RunID       string `json:"run_id,omitempty"`
	SessionID   string `json:"session_id,omitempty"`
}

AutomationJobPostFirePayload is delivered after a job fire hands off to a session.

func (AutomationJobPostFirePayload) HookProfileID

func (p AutomationJobPostFirePayload) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

type AutomationJobPreFirePayload

type AutomationJobPreFirePayload struct {
	ProfileID   string                     `json:"profile_id,omitempty"`
	JobID       string                     `json:"job_id"`
	JobName     string                     `json:"job_name,omitempty"`
	AgentName   string                     `json:"agent_name,omitempty"`
	WorkspaceID string                     `json:"workspace_id,omitempty"`
	Prompt      string                     `json:"prompt,omitempty"`
	Schedule    *AutomationSchedulePayload `json:"schedule,omitempty"`
	Payload     map[string]any             `json:"payload,omitempty"`
	Attempt     int                        `json:"attempt,omitempty"`
}

AutomationJobPreFirePayload is delivered before a job fire dispatches.

func (AutomationJobPreFirePayload) HookProfileID

func (p AutomationJobPreFirePayload) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

type AutomationObservationPatch

type AutomationObservationPatch struct{}

AutomationObservationPatch is the no-op patch surface for async automation observation hooks.

type AutomationRunCompletedPayload

type AutomationRunCompletedPayload struct {
	ProfileID   string `json:"profile_id,omitempty"`
	RunID       string `json:"run_id"`
	JobID       string `json:"job_id,omitempty"`
	TriggerID   string `json:"trigger_id,omitempty"`
	AgentName   string `json:"agent_name,omitempty"`
	WorkspaceID string `json:"workspace_id,omitempty"`
	SessionID   string `json:"session_id,omitempty"`
	Attempt     int    `json:"attempt,omitempty"`
	DurationMS  int64  `json:"duration_ms,omitempty"`
}

AutomationRunCompletedPayload is delivered after an automation run finishes successfully.

func (AutomationRunCompletedPayload) HookProfileID

func (p AutomationRunCompletedPayload) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

type AutomationRunFailedPayload

type AutomationRunFailedPayload struct {
	ProfileID   string `json:"profile_id,omitempty"`
	RunID       string `json:"run_id"`
	JobID       string `json:"job_id,omitempty"`
	TriggerID   string `json:"trigger_id,omitempty"`
	AgentName   string `json:"agent_name,omitempty"`
	WorkspaceID string `json:"workspace_id,omitempty"`
	SessionID   string `json:"session_id,omitempty"`
	Error       string `json:"error,omitempty"`
	Attempt     int    `json:"attempt,omitempty"`
	WillRetry   bool   `json:"will_retry,omitempty"`
}

AutomationRunFailedPayload is delivered after an automation run fails.

func (AutomationRunFailedPayload) HookProfileID

func (p AutomationRunFailedPayload) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

type AutomationSchedulePayload

type AutomationSchedulePayload struct {
	Mode     string `json:"mode,omitempty"`
	Expr     string `json:"expr,omitempty"`
	Interval string `json:"interval,omitempty"`
	Time     string `json:"time,omitempty"`
}

AutomationSchedulePayload carries the serializable schedule shape exposed to automation hooks.

type AutomationTriggerPostFirePayload

type AutomationTriggerPostFirePayload struct {
	ProfileID   string `json:"profile_id,omitempty"`
	TriggerID   string `json:"trigger_id"`
	TriggerName string `json:"trigger_name,omitempty"`
	Event       string `json:"event,omitempty"`
	AgentName   string `json:"agent_name,omitempty"`
	WorkspaceID string `json:"workspace_id,omitempty"`
	RunID       string `json:"run_id,omitempty"`
	SessionID   string `json:"session_id,omitempty"`
}

AutomationTriggerPostFirePayload is delivered after a trigger fire hands off to a session.

func (AutomationTriggerPostFirePayload) HookProfileID

func (p AutomationTriggerPostFirePayload) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

type AutomationTriggerPreFirePayload

type AutomationTriggerPreFirePayload struct {
	ProfileID   string         `json:"profile_id,omitempty"`
	TriggerID   string         `json:"trigger_id"`
	TriggerName string         `json:"trigger_name,omitempty"`
	Event       string         `json:"event,omitempty"`
	AgentName   string         `json:"agent_name,omitempty"`
	WorkspaceID string         `json:"workspace_id,omitempty"`
	Prompt      string         `json:"prompt,omitempty"`
	Payload     map[string]any `json:"payload,omitempty"`
	Attempt     int            `json:"attempt,omitempty"`
}

AutomationTriggerPreFirePayload is delivered before a trigger fire dispatches.

func (AutomationTriggerPreFirePayload) HookProfileID

func (p AutomationTriggerPreFirePayload) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

type AutonomyMatcher

type AutonomyMatcher struct {
	TaskID               string `json:"task_id,omitempty"                yaml:"task_id,omitempty"`
	RunID                string `json:"run_id,omitempty"                 yaml:"run_id,omitempty"`
	LoopRunID            string `json:"loop_run_id,omitempty"            yaml:"loop_run_id,omitempty"`
	LoopName             string `json:"loop_name,omitempty"              yaml:"loop_name,omitempty"`
	NodeID               string `json:"node_id,omitempty"                yaml:"node_id,omitempty"`
	WorkflowID           string `json:"workflow_id,omitempty"            yaml:"workflow_id,omitempty"`
	CoordinatorSessionID string `json:"coordinator_session_id,omitempty" yaml:"coordinator_session_id,omitempty"`
	ParentSessionID      string `json:"parent_session_id,omitempty"      yaml:"parent_session_id,omitempty"`
	RootSessionID        string `json:"root_session_id,omitempty"        yaml:"root_session_id,omitempty"`
	ChildSessionID       string `json:"child_session_id,omitempty"       yaml:"child_session_id,omitempty"`
	SpawnRole            string `json:"spawn_role,omitempty"             yaml:"spawn_role,omitempty"`
	ReleaseReason        string `json:"release_reason,omitempty"         yaml:"release_reason,omitempty"`
}

AutonomyMatcher narrows autonomy hooks by task, coordinator, and spawn correlation fields.

type AutonomyObservationPatch

type AutonomyObservationPatch struct {
	Labels map[string]string `json:"labels,omitempty"`
}

AutonomyObservationPatch captures optional labels for committed autonomy lifecycle events.

type BindingState

type BindingState struct {
	// contains filtered or unexported fields
}

BindingState captures one fully-built hook registry snapshot before it is atomically swapped into the live runtime.

func (*BindingState) HookCount

func (s *BindingState) HookCount() int

HookCount reports how many resolved hooks the binding state contains.

type CatalogEntry

type CatalogEntry struct {
	Order        int
	Name         string
	Event        HookEvent
	Source       HookSource
	SkillSource  HookSkillSource
	Mode         HookMode
	Required     bool
	Priority     int32
	Timeout      time.Duration
	ExecutorKind HookExecutorKind
	Matcher      HookMatcher
	Metadata     map[string]string
}

CatalogEntry describes one resolved hook in pipeline order.

type CatalogFilter

type CatalogFilter struct {
	ProfileID     string
	WorkspaceID   string
	WorkspaceRoot string
	AgentName     string
	Event         HookEvent
	Source        *HookSource
	Mode          HookMode
}

CatalogFilter narrows the resolved hook catalog for one workspace/agent view.

type CompactionMatcher

type CompactionMatcher struct {
	Trigger string `json:"compaction_trigger,omitempty" yaml:"compaction_trigger,omitempty"`
}

CompactionMatcher narrows context-compaction hooks by compaction metadata.

type ContextBlock

type ContextBlock struct {
	Kind     string            `json:"kind,omitempty"`
	Text     string            `json:"text,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

ContextBlock is a typed free-form context fragment attached to inputs or prompts.

type ContextCompactionPatch

type ContextCompactionPatch struct {
	Labels map[string]string `json:"labels,omitempty"`
}

ContextCompactionPatch annotates observed compaction.

type ContextCompactionPayload

type ContextCompactionPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	CompactionID string `json:"compaction_id"`
	Trigger      string `json:"trigger"`
	Status       string `json:"status,omitempty"`
	Summary      string `json:"summary,omitempty"`
	Error        string `json:"error,omitempty"`
}

ContextCompactionPayload is shared by context compaction hooks.

type ContextPostCompactPatch

type ContextPostCompactPatch = ContextCompactionPatch

ContextPostCompactPatch is the post-compact patch surface.

type ContextPostCompactPayload

type ContextPostCompactPayload = ContextCompactionPayload

ContextPostCompactPayload is delivered after compaction.

type ContextPreCompactPatch

type ContextPreCompactPatch = ContextCompactionPatch

ContextPreCompactPatch is the pre-compact patch surface.

type ContextPreCompactPayload

type ContextPreCompactPayload = ContextCompactionPayload

ContextPreCompactPayload is delivered before compaction.

type ControlPatch

type ControlPatch struct {
	Deny       bool   `json:"deny,omitempty"`
	DenyReason string `json:"deny_reason,omitempty"`
}

ControlPatch carries the common deny surface shared by mutable hook families.

type CoordinatorContext

type CoordinatorContext struct {
	ProfileID            string `json:"profile_id,omitempty"`
	WorkspaceID          string `json:"workspace_id,omitempty"`
	Workspace            string `json:"workspace,omitempty"`
	AgentName            string `json:"agent_name,omitempty"`
	CoordinatorSessionID string `json:"coordinator_session_id,omitempty"`
	TaskID               string `json:"task_id,omitempty"`
	RunID                string `json:"run_id,omitempty"`
	WorkflowID           string `json:"workflow_id,omitempty"`
	Provider             string `json:"provider,omitempty"`
	Model                string `json:"model,omitempty"`
}

CoordinatorContext carries the coordinator identifiers shared across coordinator hooks.

func (CoordinatorContext) HookProfileID

func (c CoordinatorContext) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

type CoordinatorDecisionPayload

type CoordinatorDecisionPayload = CoordinatorLifecyclePayload

CoordinatorDecisionPayload is delivered when a coordinator records a semantic decision.

type CoordinatorFailedPayload

type CoordinatorFailedPayload = CoordinatorLifecyclePayload

CoordinatorFailedPayload is delivered after a coordinator lifecycle failure.

type CoordinatorLifecyclePayload

type CoordinatorLifecyclePayload struct {
	PayloadBase
	CoordinatorContext
	DecisionKind string `json:"decision_kind,omitempty"`
	Decision     string `json:"decision,omitempty"`
	StopReason   string `json:"stop_reason,omitempty"`
	Error        string `json:"error,omitempty"`
}

CoordinatorLifecyclePayload is shared by committed coordinator lifecycle hooks.

type CoordinatorObservationPatch

type CoordinatorObservationPatch = AutonomyObservationPatch

CoordinatorObservationPatch is the observation patch surface for committed coordinator hooks.

type CoordinatorPreSpawnPayload

type CoordinatorPreSpawnPayload struct {
	PayloadBase
	CoordinatorContext
	Reason     string `json:"reason,omitempty"`
	Denied     bool   `json:"denied,omitempty"`
	DenyReason string `json:"deny_reason,omitempty"`
}

CoordinatorPreSpawnPayload is delivered before the daemon creates a coordinator session.

type CoordinatorSpawnPatch

type CoordinatorSpawnPatch struct {
	ControlPatch
	AgentName *string `json:"agent_name,omitempty"`
	Provider  *string `json:"provider,omitempty"`
	Model     *string `json:"model,omitempty"`
}

CoordinatorSpawnPatch mutates or denies coordinator spawn requests.

type CoordinatorSpawnedPayload

type CoordinatorSpawnedPayload = CoordinatorLifecyclePayload

CoordinatorSpawnedPayload is delivered after a coordinator session is created.

type CoordinatorStoppedPayload

type CoordinatorStoppedPayload = CoordinatorLifecyclePayload

CoordinatorStoppedPayload is delivered after a coordinator session stops.

type DeclarationProvider

type DeclarationProvider func(context.Context) ([]HookDecl, error)

DeclarationProvider returns the hook declarations for one source class.

type DeniedError

type DeniedError struct {
	Event    HookEvent
	HookName string
	Reason   string
}

DeniedError reports an explicit sync-hook denial separately from execution failures.

func (*DeniedError) Error

func (e *DeniedError) Error() string

type DispatchCorrelation

type DispatchCorrelation struct {
	TaskID               string
	RunID                string
	LoopRunID            string
	LoopName             string
	NodeID               string
	WorkflowID           string
	CoordinatorSessionID string
	ActorKind            string
	ActorID              string
	ReleaseReason        string
}

DispatchCorrelation carries the public correlation keys extractable from one typed hook payload without importing the store package.

func CorrelationFromPayload

func CorrelationFromPayload(payload any) DispatchCorrelation

CorrelationFromPayload extracts the correlation fields that are owned by the typed hook payload itself.

type DispatchEventEmitter

type DispatchEventEmitter interface {
	EmitHookDispatchEvent(
		ctx context.Context,
		payload any,
		hook RegisteredHook,
		phase DispatchPhase,
		outcome HookRunOutcome,
		err error,
		depth int,
		timestamp time.Time,
	)
}

DispatchEventEmitter emits canonical hook.dispatch.* events for public session and observe surfaces.

func DispatchEventEmitterFromContext

func DispatchEventEmitterFromContext(ctx context.Context) DispatchEventEmitter

DispatchEventEmitterFromContext resolves the attached dispatch-event emitter.

type DispatchPhase

type DispatchPhase string

DispatchPhase identifies whether a hook-dispatch event marks pipeline entry or one completed hook execution.

const (
	DispatchPhaseStart    DispatchPhase = "start"
	DispatchPhaseComplete DispatchPhase = "complete"
)

type EventDescriptor

type EventDescriptor struct {
	Event         HookEvent
	Family        HookEventFamily
	SyncEligible  bool
	PayloadSchema string
	PatchSchema   string
}

EventDescriptor describes one supported hook event for introspection APIs.

func AllEventDescriptors

func AllEventDescriptors() []EventDescriptor

AllEventDescriptors returns the hook taxonomy metadata in deterministic order.

func FilterEventDescriptors

func FilterEventDescriptors(filter EventFilter) []EventDescriptor

FilterEventDescriptors returns the hook taxonomy metadata in deterministic order.

type EventFilter

type EventFilter struct {
	Family   HookEventFamily
	SyncOnly bool
}

EventFilter narrows the supported hook taxonomy for introspection APIs.

type EventPostRecordPatch

type EventPostRecordPatch = EventRecordPatch

EventPostRecordPatch is the post-record patch surface.

type EventPostRecordPayload

type EventPostRecordPayload = EventRecordPayload

EventPostRecordPayload is delivered after an event record is written.

type EventPreRecordPatch

type EventPreRecordPatch = EventRecordPatch

EventPreRecordPatch is the pre-record patch surface.

type EventPreRecordPayload

type EventPreRecordPayload = EventRecordPayload

EventPreRecordPayload is delivered before an event record is written.

type EventRecordPatch

type EventRecordPatch struct {
	Labels map[string]string `json:"labels,omitempty"`
}

EventRecordPatch captures the optional observation patch surface for event hooks.

type EventRecordPayload

type EventRecordPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	RecordType string          `json:"record_type,omitempty"`
	Sequence   int64           `json:"sequence,omitempty"`
	Content    json.RawMessage `json:"content,omitempty"`
}

EventRecordPayload is shared by event pre/post-record hooks.

type Executor

type Executor interface {
	Kind() HookExecutorKind
	Execute(ctx context.Context, hook RegisteredHook, payload []byte) ([]byte, error)
}

Executor is the execution seam for hook implementations.

type ExecutorResolver

type ExecutorResolver func(HookDecl) (Executor, error)

ExecutorResolver binds a normalized declaration to its executor implementation.

type HookDecl

type HookDecl struct {
	Name           string `json:"name"                    yaml:"name"`
	*HookPlacement ` yaml:",inline"`
	Event          HookEvent         `json:"event"                   yaml:"event"`
	Mode           HookMode          `json:"mode,omitempty"          yaml:"mode,omitempty"`
	Matcher        HookMatcher       `json:"matcher"                 yaml:"matcher,omitempty"`
	ExecutorKind   HookExecutorKind  `json:"executor_kind,omitempty" yaml:"executor_kind,omitempty"`
	Command        string            `json:"command,omitempty"       yaml:"command,omitempty"`
	Args           []string          `json:"args,omitempty"          yaml:"args,omitempty"`
	WorkingDir     string            `json:"-"                       yaml:"-"`
	Env            map[string]string `json:"env,omitempty"           yaml:"env,omitempty"`
	SecretEnv      map[string]string `json:"secret_env,omitempty"    yaml:"secret_env,omitempty"`
	Metadata       map[string]string `json:"metadata,omitempty"      yaml:"metadata,omitempty"`
	Timeout        time.Duration     `json:"timeout,omitempty"       yaml:"timeout,omitempty"`
	Enabled        *bool             `json:"enabled,omitempty"       yaml:"enabled,omitempty"`
	Priority       int32             `json:"priority,omitempty"      yaml:"priority,omitempty"`
	SkillSource    HookSkillSource   `json:"-"                       yaml:"-"`
	Source         HookSource        `json:"source"                  yaml:"source"`
	Required       bool              `json:"required,omitempty"      yaml:"required,omitempty"`
	PrioritySet    bool              `json:"-"                       yaml:"-"`
}

HookDecl is the declarative record supplied by config, agent definitions, or skills.

func CanonicalizeHookDecl

func CanonicalizeHookDecl(decl HookDecl) (HookDecl, error)

CanonicalizeHookDecl validates one declaration and applies defaults without binding an executor.

func (HookDecl) ClonePlacement

func (d HookDecl) ClonePlacement() *HookPlacement

func (HookDecl) EnabledValue

func (d HookDecl) EnabledValue() bool

EnabledValue reports whether a declaration participates in dispatch.

func (HookDecl) PlacementProfileID

func (d HookDecl) PlacementProfileID() string

func (HookDecl) PlacementWorkspaces

func (d HookDecl) PlacementWorkspaces() []string

func (HookDecl) WithPlacement

func (d HookDecl) WithPlacement(profileID string, workspaces []string) HookDecl

type HookEvent

type HookEvent string

HookEvent identifies when a hook fires.

const (
	HookSessionPreCreate                HookEvent = "session.pre_create"
	HookSessionPostCreate               HookEvent = "session.post_create"
	HookSessionPreResume                HookEvent = "session.pre_resume"
	HookSessionPostResume               HookEvent = "session.post_resume"
	HookSessionPreStop                  HookEvent = "session.pre_stop"
	HookSessionPostStop                 HookEvent = "session.post_stop"
	HookSessionMessagePersisted         HookEvent = "session.message_persisted"
	HookSessionRuntimeRecoveryStarted   HookEvent = "session.runtime_recovery.started"
	HookSessionRuntimeRecoverySucceeded HookEvent = "session.runtime_recovery.succeeded"
	HookSessionRuntimeRecoveryExhausted HookEvent = "session.runtime_recovery.exhausted"

	HookInputPreSubmit HookEvent = "input.pre_submit"

	HookPromptPostAssemble HookEvent = "prompt.post_assemble"

	HookEventPreRecord  HookEvent = "event.pre_record"
	HookEventPostRecord HookEvent = "event.post_record"

	HookAutomationJobPreFire      HookEvent = "automation.job.pre_fire"
	HookAutomationJobPostFire     HookEvent = "automation.job.post_fire"
	HookAutomationTriggerPreFire  HookEvent = "automation.trigger.pre_fire"
	HookAutomationTriggerPostFire HookEvent = "automation.trigger.post_fire"
	HookAutomationRunCompleted    HookEvent = "automation.run.completed"
	HookAutomationRunFailed       HookEvent = "automation.run.failed"

	HookAgentPreStart                HookEvent = "agent.pre_start"
	HookAgentSpawned                 HookEvent = "agent.spawned"
	HookAgentCrashed                 HookEvent = "agent.crashed"
	HookAgentStopped                 HookEvent = "agent.stopped"
	HookAgentSoulSnapshotResolved    HookEvent = "agent.soul.snapshot.resolved"
	HookAgentSoulMutationAfter       HookEvent = "agent.soul.mutation.after"
	HookAgentHeartbeatPolicyResolved HookEvent = "agent.heartbeat.policy.resolved"
	HookAgentHeartbeatWakeBefore     HookEvent = "agent.heartbeat.wake.before"
	HookAgentHeartbeatWakeAfter      HookEvent = "agent.heartbeat.wake.after"
	HookSessionHealthUpdateAfter     HookEvent = "session.health.update.after"

	HookTurnStart HookEvent = "turn.start"
	HookTurnEnd   HookEvent = "turn.end"

	HookMessageStart HookEvent = "message.start"
	HookMessageDelta HookEvent = "message.delta"
	HookMessageEnd   HookEvent = "message.end"

	HookToolPreCall   HookEvent = "tool.pre_call"
	HookToolPostCall  HookEvent = "tool.post_call"
	HookToolPostError HookEvent = "tool.post_error"

	HookPermissionRequest  HookEvent = "permission.request"
	HookPermissionResolved HookEvent = "permission.resolved"
	HookPermissionDenied   HookEvent = "permission.denied"

	HookContextPreCompact  HookEvent = "context.pre_compact"
	HookContextPostCompact HookEvent = "context.post_compact"

	HookCoordinatorPreSpawn HookEvent = "coordinator.pre_spawn"
	HookCoordinatorSpawned  HookEvent = "coordinator.spawned"
	HookCoordinatorDecision HookEvent = "coordinator.decision"
	HookCoordinatorStopped  HookEvent = "coordinator.stopped"
	HookCoordinatorFailed   HookEvent = "coordinator.failed"

	HookTaskBlocked        HookEvent = "task.blocked"
	HookTaskUnblocked      HookEvent = "task.unblocked"
	HookTaskNeedsAttention HookEvent = "task.needs_attention"
	HookTaskRecovered      HookEvent = "task.recovered"
	HookTaskStatusChanged  HookEvent = "task.status_changed"

	HookTaskRunEnqueued       HookEvent = "task.run.enqueued"
	HookTaskRunPreClaim       HookEvent = "task.run.pre_claim"
	HookTaskRunPostClaim      HookEvent = "task.run.post_claim"
	HookTaskRunLeaseExtended  HookEvent = "task.run.lease_extended"
	HookTaskRunLeaseExpired   HookEvent = "task.run.lease_expired"
	HookTaskRunLeaseRecovered HookEvent = "task.run.lease_recovered"
	HookTaskRunReleased       HookEvent = "task.run.released"
	HookTaskRunCompleted      HookEvent = "task.run.completed"
	HookTaskRunFailed         HookEvent = "task.run.failed"

	HookLoopStarted        HookEvent = "loop.started"
	HookLoopGenerationPre  HookEvent = "loop.generation.pre"
	HookLoopGenerationPost HookEvent = "loop.generation.post"
	HookLoopGatePre        HookEvent = "loop.gate.pre"
	HookLoopGatePost       HookEvent = "loop.gate.post"
	HookLoopNodeTerminal   HookEvent = "loop.node.terminal"
	HookLoopTerminal       HookEvent = "loop.terminal"

	HookSubagentSettled    HookEvent = "subagent.settled"
	HookSpawnPreCreate     HookEvent = "spawn.pre_create"
	HookSpawnCreated       HookEvent = "spawn.created"
	HookSpawnParentStopped HookEvent = "spawn.parent_stopped"
	HookSpawnTTLExpired    HookEvent = "spawn.ttl_expired"
	HookSpawnReaped        HookEvent = "spawn.reaped"
)
const (
	HookTerminalOpened            HookEvent = "terminal.opened"
	HookTerminalClosed            HookEvent = "terminal.closed"
	HookTerminalCommandStarted    HookEvent = "terminal.command_started"
	HookTerminalCommandFinished   HookEvent = "terminal.command_finished"
	HookTerminalInputRequested    HookEvent = "terminal.input_requested"
	HookTerminalInputProvided     HookEvent = "terminal.input_provided"
	HookTerminalRecordingStarted  HookEvent = "terminal.recording_started"
	HookTerminalRecordingStopped  HookEvent = "terminal.recording_stopped"
	HookTerminalSubscriberEvicted HookEvent = "terminal.subscriber_evicted"
	HookTerminalLimitRejected     HookEvent = "terminal.limit_rejected"
)
const (
	HookWindowManagerLayoutApplied  HookEvent = "window_manager.layout.applied"
	HookWindowManagerDesktopCreated HookEvent = "window_manager.desktop.created"
	HookWindowManagerDesktopDeleted HookEvent = "window_manager.desktop.deleted"
	HookWindowManagerWindowMoved    HookEvent = "window_manager.window.moved"
	HookWindowManagerWindowOpened   HookEvent = "window_manager.window.opened"
	HookWindowManagerWindowClosed   HookEvent = "window_manager.window.closed"
	HookWindowManagerStackGrouped   HookEvent = "window_manager.stack.grouped"
	HookWindowManagerStackUngrouped HookEvent = "window_manager.stack.ungrouped"
	HookWindowManagerStackActivated HookEvent = "window_manager.stack.activated"
)
const (
	HookWorktreePreCreate HookEvent = "worktree.pre_create"
	HookWorktreePreRemove HookEvent = "worktree.pre_remove"
	HookWorktreeCreated   HookEvent = "worktree.created"
	HookWorktreeAdopted   HookEvent = "worktree.adopted"
	HookWorktreeRemoved   HookEvent = "worktree.removed"
)
const HookSessionAttentionChanged HookEvent = "session.attention.changed"

func AllHookEvents

func AllHookEvents() []HookEvent

AllHookEvents returns the full taxonomy in deterministic order.

func (HookEvent) Family

func (e HookEvent) Family() HookEventFamily

Family reports the taxonomy family for the event.

func (HookEvent) String

func (e HookEvent) String() string

String returns the literal hook event value.

func (HookEvent) SyncEligible

func (e HookEvent) SyncEligible() bool

SyncEligible reports whether the event accepts sync hooks.

func (HookEvent) Validate

func (e HookEvent) Validate() error

Validate ensures the event is part of the supported taxonomy.

type HookEventFamily

type HookEventFamily string

HookEventFamily groups hook events into the documented taxonomy families.

const (
	HookEventFamilySession       HookEventFamily = "session"
	HookEventFamilyInput         HookEventFamily = "input"
	HookEventFamilyPrompt        HookEventFamily = "prompt"
	HookEventFamilyEvent         HookEventFamily = "event"
	HookEventFamilyAutomation    HookEventFamily = "automation"
	HookEventFamilyAgent         HookEventFamily = "agent"
	HookEventFamilyTurn          HookEventFamily = "turn"
	HookEventFamilyMessage       HookEventFamily = "message"
	HookEventFamilyTool          HookEventFamily = "tool"
	HookEventFamilyPermission    HookEventFamily = "permission"
	HookEventFamilyContext       HookEventFamily = "context"
	HookEventFamilyCoordinator   HookEventFamily = "coordinator"
	HookEventFamilyTask          HookEventFamily = "task"
	HookEventFamilyTaskRun       HookEventFamily = "task.run"
	HookEventFamilyLoop          HookEventFamily = "loop"
	HookEventFamilySpawn         HookEventFamily = "spawn"
	HookEventFamilySubagent      HookEventFamily = "subagent"
	HookEventFamilyWindowManager HookEventFamily = "window_manager"
	HookEventFamilyWorktree      HookEventFamily = "worktree"
	HookEventFamilyTerminal      HookEventFamily = "terminal"
)

func (HookEventFamily) Validate

func (f HookEventFamily) Validate() error

Validate ensures the event family is part of the supported taxonomy.

type HookExecutorKind

type HookExecutorKind string

HookExecutorKind identifies the execution boundary for a hook.

const (
	HookExecutorNative     HookExecutorKind = "native"
	HookExecutorSubprocess HookExecutorKind = "subprocess"
	HookExecutorWASM       HookExecutorKind = "wasm"
)

func (HookExecutorKind) Validate

func (k HookExecutorKind) Validate() error

Validate ensures the executor kind is supported.

type HookMatcher

type HookMatcher struct {
	AgentName          string `json:"agent_name,omitempty"         yaml:"agent_name,omitempty"`
	AgentType          string `json:"agent_type,omitempty"         yaml:"agent_type,omitempty"`
	WorkspaceID        string `json:"workspace_id,omitempty"       yaml:"workspace_id,omitempty"`
	WorktreeID         string `json:"worktree_id,omitempty"        yaml:"worktree_id,omitempty"`
	WorkspaceRoot      string `json:"workspace_root,omitempty"     yaml:"workspace_root,omitempty"`
	SessionType        string `json:"session_type,omitempty"       yaml:"session_type,omitempty"`
	InputClass         string `json:"input_class,omitempty"        yaml:"input_class,omitempty"`
	ACPEventType       string `json:"acp_event_type,omitempty"     yaml:"acp_event_type,omitempty"`
	TurnID             string `json:"turn_id,omitempty"            yaml:"turn_id,omitempty"`
	ToolID             string `json:"tool_id,omitempty"            yaml:"tool_id,omitempty"`
	ToolName           string `json:"tool_name,omitempty"          yaml:"tool_name,omitempty"`
	ToolReadOnly       *bool  `json:"tool_read_only,omitempty"     yaml:"tool_read_only,omitempty"`
	DecisionClass      string `json:"decision_class,omitempty"     yaml:"decision_class,omitempty"`
	MessageRole        string `json:"message_role,omitempty"       yaml:"message_role,omitempty"`
	MessageDeltaType   string `json:"message_delta_type,omitempty" yaml:"message_delta_type,omitempty"`
	*CompactionMatcher `                                                     yaml:",inline,omitempty"`
	Autonomy           *AutonomyMatcher `json:"autonomy,omitempty"           yaml:"autonomy,omitempty"`
}

HookMatcher narrows when a hook is eligible to run.

func (HookMatcher) MatchesAgentLifecycle

func (m HookMatcher) MatchesAgentLifecycle(payload AgentLifecyclePayload) bool

MatchesAgentLifecycle matches spawned, crashed, and stopped agent hooks.

func (HookMatcher) MatchesAgentPreStart

func (m HookMatcher) MatchesAgentPreStart(payload AgentPreStartPayload) bool

MatchesAgentPreStart matches pre-start agent hooks.

func (HookMatcher) MatchesAutomation

func (m HookMatcher) MatchesAutomation(agentName string, workspaceID string) bool

MatchesAutomation matches automation lifecycle hooks.

func (HookMatcher) MatchesContextCompact

func (m HookMatcher) MatchesContextCompact(payload ContextCompactionPayload) bool

MatchesContextCompact matches context-compaction hooks.

func (HookMatcher) MatchesCoordinator

func (m HookMatcher) MatchesCoordinator(payload CoordinatorContext) bool

MatchesCoordinator matches coordinator-family hooks.

func (HookMatcher) MatchesEvent

func (m HookMatcher) MatchesEvent(payload EventRecordPayload) bool

MatchesEvent matches event-record-family hooks.

func (HookMatcher) MatchesInput

func (m HookMatcher) MatchesInput(payload InputPreSubmitPayload) bool

MatchesInput matches input-family hooks.

func (HookMatcher) MatchesLoop

func (m HookMatcher) MatchesLoop(payload LoopContext) bool

MatchesLoop matches loop-family hooks.

func (HookMatcher) MatchesMessage

func (m HookMatcher) MatchesMessage(payload MessagePayload) bool

MatchesMessage matches message-family hooks.

func (HookMatcher) MatchesPermissionDenied

func (m HookMatcher) MatchesPermissionDenied(payload PermissionDeniedPayload) bool

MatchesPermissionDenied matches denied permission hooks without exposing raw tool input.

func (HookMatcher) MatchesPermissionRequest

func (m HookMatcher) MatchesPermissionRequest(payload PermissionRequestPayload) bool

MatchesPermissionRequest matches permission-request hooks.

func (HookMatcher) MatchesPermissionResolution

func (m HookMatcher) MatchesPermissionResolution(payload PermissionResolutionPayload) bool

MatchesPermissionResolution matches resolved and denied permission hooks.

func (HookMatcher) MatchesPrompt

func (m HookMatcher) MatchesPrompt(payload PromptPayload) bool

MatchesPrompt matches prompt-family hooks.

func (HookMatcher) MatchesSession

func (m HookMatcher) MatchesSession(payload SessionContext) bool

MatchesSession matches session-family hooks.

func (HookMatcher) MatchesSpawn

func (m HookMatcher) MatchesSpawn(payload SpawnContext) bool

MatchesSpawn matches spawn-family hooks.

func (HookMatcher) MatchesTask

func (m HookMatcher) MatchesTask(payload TaskContext) bool

MatchesTask matches task-family hooks.

func (HookMatcher) MatchesTaskRun

func (m HookMatcher) MatchesTaskRun(payload TaskRunContext) bool

MatchesTaskRun matches task-run-family hooks.

func (HookMatcher) MatchesToolPostCall

func (m HookMatcher) MatchesToolPostCall(payload ToolPostCallPayload) bool

MatchesToolPostCall matches tool post-call hooks.

func (HookMatcher) MatchesToolPostError

func (m HookMatcher) MatchesToolPostError(payload ToolPostErrorPayload) bool

MatchesToolPostError matches tool post-error hooks.

func (HookMatcher) MatchesToolPreCall

func (m HookMatcher) MatchesToolPreCall(payload ToolPreCallPayload) bool

MatchesToolPreCall matches tool pre-call hooks.

func (HookMatcher) MatchesTurn

func (m HookMatcher) MatchesTurn(payload TurnPayload) bool

MatchesTurn matches turn-family hooks.

func (HookMatcher) MatchesWorktree

func (m HookMatcher) MatchesWorktree(payload WorktreeContext) bool

MatchesWorktree matches worktree lifecycle hooks.

type HookMode

type HookMode string

HookMode controls whether a hook runs inline or in the background.

const (
	HookModeSync  HookMode = "sync"
	HookModeAsync HookMode = "async"
)

func (HookMode) Validate

func (m HookMode) Validate() error

Validate ensures the mode is supported.

type HookPlacement

type HookPlacement struct {
	ProfileID          string   `json:"profile_id,omitempty" yaml:"profile_id,omitempty"`
	ShadowedWorkspaces []string `json:"-"                    yaml:"-"`
}

HookPlacement keeps optional projection scope outside the copied declaration value.

type HookRunOutcome

type HookRunOutcome string

HookRunOutcome classifies the result of one hook execution.

const (
	HookRunOutcomeApplied  HookRunOutcome = "applied"
	HookRunOutcomeDenied   HookRunOutcome = "denied"
	HookRunOutcomeFailed   HookRunOutcome = "failed"
	HookRunOutcomeSkipped  HookRunOutcome = "skipped"
	HookRunOutcomeDropped  HookRunOutcome = "dropped"
	HookRunOutcomeRejected HookRunOutcome = "rejected"
)

func (HookRunOutcome) Validate

func (o HookRunOutcome) Validate() error

Validate ensures the outcome is one of the documented execution results.

type HookRunRecord

type HookRunRecord struct {
	HookName      string          `json:"hook_name"`
	Event         HookEvent       `json:"event"`
	Source        HookSource      `json:"source"`
	Mode          HookMode        `json:"mode"`
	Duration      time.Duration   `json:"duration"`
	Outcome       HookRunOutcome  `json:"outcome"`
	DispatchDepth int             `json:"dispatch_depth"`
	PatchApplied  json.RawMessage `json:"patch_applied,omitempty"`
	Error         string          `json:"error,omitempty"`
	Required      bool            `json:"required,omitzero"`
	RecordedAt    time.Time       `json:"recorded_at"`
}

HookRunRecord captures one hook execution for observability and audit.

type HookRunWriter

type HookRunWriter interface {
	RecordHookRun(context.Context, HookRunRecord) error
}

HookRunWriter persists hook run records into an active session-scoped store.

func HookRunWriterFromContext

func HookRunWriterFromContext(ctx context.Context) HookRunWriter

HookRunWriterFromContext resolves the attached hook-run writer, if any.

type HookSkillSource

type HookSkillSource uint8

HookSkillSource captures the existing skill-registry precedence without importing internal/skills into the hooks base package.

const (
	HookSkillSourceUnset HookSkillSource = iota
	HookSkillSourceBundled
	HookSkillSourceMarketplace
	HookSkillSourceUser
	HookSkillSourceProfile
	HookSkillSourceAdditional
	HookSkillSourceWorkspace
	HookSkillSourceWorkspaceProfile
)

func (HookSkillSource) MarshalText

func (s HookSkillSource) MarshalText() ([]byte, error)

MarshalText encodes the skill source as its stable string value.

func (HookSkillSource) String

func (s HookSkillSource) String() string

String returns the stable text form for the skill source.

func (*HookSkillSource) UnmarshalText

func (s *HookSkillSource) UnmarshalText(text []byte) error

UnmarshalText decodes a stable skill-source string.

func (HookSkillSource) Validate

func (s HookSkillSource) Validate() error

Validate ensures the skill source is one of the documented values when set.

type HookSource

type HookSource uint8

HookSource identifies where a hook was declared.

const (
	HookSourceNative HookSource = iota
	HookSourceConfig
	HookSourceAgentDefinition
	HookSourceSkill
	HookSourceExtension
)

func (HookSource) MarshalText

func (s HookSource) MarshalText() ([]byte, error)

MarshalText encodes the source as a string.

func (HookSource) String

func (s HookSource) String() string

String returns the stable text form for the hook source.

func (*HookSource) UnmarshalText

func (s *HookSource) UnmarshalText(text []byte) error

UnmarshalText decodes the source from a string value.

func (HookSource) Validate

func (s HookSource) Validate() error

Validate ensures the source is one of the documented values.

type Hooks

type Hooks struct {
	// contains filtered or unexported fields
}

Hooks owns the hot-reloadable registry snapshot and typed dispatch surface.

func NewHooks

func NewHooks(opts ...Option) *Hooks

NewHooks constructs a hook dispatcher with an empty registry snapshot and a started async pool.

func (*Hooks) ApplyBindingState

func (h *Hooks) ApplyBindingState(state *BindingState, resourceRevision int64) error

ApplyBindingState atomically swaps a previously-built binding snapshot into the live runtime.

func (*Hooks) BuildBindingState

func (h *Hooks) BuildBindingState(decls []HookDecl) (*BindingState, error)

BuildBindingState validates declarations, binds executors, and computes the next registry snapshot without mutating the live runtime.

func (*Hooks) Catalog

func (h *Hooks) Catalog(filter CatalogFilter) ([]CatalogEntry, error)

Catalog returns the currently resolved hook catalog in deterministic pipeline order.

func (*Hooks) Close

func (h *Hooks) Close()

Close drains the async worker pool.

func (*Hooks) DispatchAgentCrashed

func (h *Hooks) DispatchAgentCrashed(ctx context.Context, payload AgentCrashedPayload) (AgentCrashedPayload, error)

DispatchAgentCrashed runs the agent.crashed hook pipeline.

func (*Hooks) DispatchAgentHeartbeatPolicyResolved

func (h *Hooks) DispatchAgentHeartbeatPolicyResolved(
	ctx context.Context,
	payload AgentHeartbeatPolicyResolvedPayload,
) (AgentHeartbeatPolicyResolvedPayload, error)

DispatchAgentHeartbeatPolicyResolved runs the agent.heartbeat.policy.resolved hook dispatch.

func (*Hooks) DispatchAgentHeartbeatWakeAfter

func (h *Hooks) DispatchAgentHeartbeatWakeAfter(
	ctx context.Context,
	payload AgentHeartbeatWakeAfterPayload,
) (AgentHeartbeatWakeAfterPayload, error)

DispatchAgentHeartbeatWakeAfter runs the agent.heartbeat.wake.after hook dispatch.

func (*Hooks) DispatchAgentHeartbeatWakeBefore

func (h *Hooks) DispatchAgentHeartbeatWakeBefore(
	ctx context.Context,
	payload AgentHeartbeatWakeBeforePayload,
) (AgentHeartbeatWakeBeforePayload, error)

DispatchAgentHeartbeatWakeBefore runs the agent.heartbeat.wake.before hook pipeline.

func (*Hooks) DispatchAgentPreStart

func (h *Hooks) DispatchAgentPreStart(ctx context.Context, payload AgentPreStartPayload) (AgentPreStartPayload, error)

DispatchAgentPreStart runs the agent.pre_start hook pipeline.

func (*Hooks) DispatchAgentSoulMutationAfter

func (h *Hooks) DispatchAgentSoulMutationAfter(
	ctx context.Context,
	payload AgentSoulMutationAfterPayload,
) (AgentSoulMutationAfterPayload, error)

DispatchAgentSoulMutationAfter runs the agent.soul.mutation.after hook dispatch.

func (*Hooks) DispatchAgentSoulSnapshotResolved

func (h *Hooks) DispatchAgentSoulSnapshotResolved(
	ctx context.Context,
	payload AgentSoulSnapshotResolvedPayload,
) (AgentSoulSnapshotResolvedPayload, error)

DispatchAgentSoulSnapshotResolved runs the agent.soul.snapshot.resolved hook dispatch.

func (*Hooks) DispatchAgentSpawned

func (h *Hooks) DispatchAgentSpawned(ctx context.Context, payload AgentSpawnedPayload) (AgentSpawnedPayload, error)

DispatchAgentSpawned runs the agent.spawned hook pipeline.

func (*Hooks) DispatchAgentStopped

func (h *Hooks) DispatchAgentStopped(ctx context.Context, payload AgentStoppedPayload) (AgentStoppedPayload, error)

DispatchAgentStopped runs the agent.stopped hook pipeline.

func (*Hooks) DispatchAutomationJobPostFire

func (h *Hooks) DispatchAutomationJobPostFire(
	ctx context.Context,
	payload AutomationJobPostFirePayload,
) (AutomationJobPostFirePayload, error)

DispatchAutomationJobPostFire runs the automation.job.post_fire hook dispatch.

func (*Hooks) DispatchAutomationJobPreFire

func (h *Hooks) DispatchAutomationJobPreFire(
	ctx context.Context,
	payload AutomationJobPreFirePayload,
) (AutomationJobPreFirePayload, error)

DispatchAutomationJobPreFire runs the automation.job.pre_fire hook pipeline.

func (*Hooks) DispatchAutomationRunCompleted

func (h *Hooks) DispatchAutomationRunCompleted(
	ctx context.Context,
	payload AutomationRunCompletedPayload,
) (AutomationRunCompletedPayload, error)

DispatchAutomationRunCompleted runs the automation.run.completed hook dispatch.

func (*Hooks) DispatchAutomationRunFailed

func (h *Hooks) DispatchAutomationRunFailed(
	ctx context.Context,
	payload AutomationRunFailedPayload,
) (AutomationRunFailedPayload, error)

DispatchAutomationRunFailed runs the automation.run.failed hook dispatch.

func (*Hooks) DispatchAutomationTriggerPostFire

func (h *Hooks) DispatchAutomationTriggerPostFire(
	ctx context.Context,
	payload AutomationTriggerPostFirePayload,
) (AutomationTriggerPostFirePayload, error)

DispatchAutomationTriggerPostFire runs the automation.trigger.post_fire hook dispatch.

func (*Hooks) DispatchAutomationTriggerPreFire

func (h *Hooks) DispatchAutomationTriggerPreFire(
	ctx context.Context,
	payload AutomationTriggerPreFirePayload,
) (AutomationTriggerPreFirePayload, error)

DispatchAutomationTriggerPreFire runs the automation.trigger.pre_fire hook pipeline.

func (*Hooks) DispatchContextPostCompact

func (h *Hooks) DispatchContextPostCompact(
	ctx context.Context,
	payload ContextPostCompactPayload,
) (ContextPostCompactPayload, error)

DispatchContextPostCompact runs the context.post_compact hook pipeline.

func (*Hooks) DispatchContextPreCompact

func (h *Hooks) DispatchContextPreCompact(
	ctx context.Context,
	payload ContextPreCompactPayload,
) (ContextPreCompactPayload, error)

DispatchContextPreCompact runs the context.pre_compact hook pipeline.

func (*Hooks) DispatchCoordinatorDecision

func (h *Hooks) DispatchCoordinatorDecision(
	ctx context.Context,
	payload CoordinatorDecisionPayload,
) (CoordinatorDecisionPayload, error)

DispatchCoordinatorDecision runs the coordinator.decision hook dispatch.

func (*Hooks) DispatchCoordinatorFailed

func (h *Hooks) DispatchCoordinatorFailed(
	ctx context.Context,
	payload CoordinatorFailedPayload,
) (CoordinatorFailedPayload, error)

DispatchCoordinatorFailed runs the coordinator.failed hook dispatch.

func (*Hooks) DispatchCoordinatorPreSpawn

func (h *Hooks) DispatchCoordinatorPreSpawn(
	ctx context.Context,
	payload CoordinatorPreSpawnPayload,
) (CoordinatorPreSpawnPayload, error)

DispatchCoordinatorPreSpawn runs the coordinator.pre_spawn hook pipeline.

func (*Hooks) DispatchCoordinatorSpawned

func (h *Hooks) DispatchCoordinatorSpawned(
	ctx context.Context,
	payload CoordinatorSpawnedPayload,
) (CoordinatorSpawnedPayload, error)

DispatchCoordinatorSpawned runs the coordinator.spawned hook dispatch.

func (*Hooks) DispatchCoordinatorStopped

func (h *Hooks) DispatchCoordinatorStopped(
	ctx context.Context,
	payload CoordinatorStoppedPayload,
) (CoordinatorStoppedPayload, error)

DispatchCoordinatorStopped runs the coordinator.stopped hook dispatch.

func (*Hooks) DispatchEventPostRecord

func (h *Hooks) DispatchEventPostRecord(
	ctx context.Context,
	payload EventPostRecordPayload,
) (EventPostRecordPayload, error)

DispatchEventPostRecord runs the event.post_record hook dispatch.

func (*Hooks) DispatchEventPreRecord

func (h *Hooks) DispatchEventPreRecord(
	ctx context.Context,
	payload EventPreRecordPayload,
) (EventPreRecordPayload, error)

DispatchEventPreRecord runs the event.pre_record hook dispatch.

func (*Hooks) DispatchInputPreSubmit

func (h *Hooks) DispatchInputPreSubmit(
	ctx context.Context,
	payload InputPreSubmitPayload,
) (InputPreSubmitPayload, error)

DispatchInputPreSubmit runs the input.pre_submit hook pipeline.

func (*Hooks) DispatchLoopGatePost

func (h *Hooks) DispatchLoopGatePost(
	ctx context.Context,
	payload LoopGatePostPayload,
) (LoopGatePostPayload, error)

DispatchLoopGatePost runs the loop.gate.post hook dispatch.

func (*Hooks) DispatchLoopGatePre

func (h *Hooks) DispatchLoopGatePre(
	ctx context.Context,
	payload LoopGatePrePayload,
) (LoopGatePrePayload, error)

DispatchLoopGatePre runs the loop.gate.pre hook pipeline.

func (*Hooks) DispatchLoopGenerationPost

func (h *Hooks) DispatchLoopGenerationPost(
	ctx context.Context,
	payload LoopGenerationPostPayload,
) (LoopGenerationPostPayload, error)

DispatchLoopGenerationPost runs the loop.generation.post hook dispatch.

func (*Hooks) DispatchLoopGenerationPre

func (h *Hooks) DispatchLoopGenerationPre(
	ctx context.Context,
	payload LoopGenerationPrePayload,
) (LoopGenerationPrePayload, error)

DispatchLoopGenerationPre runs the loop.generation.pre hook pipeline.

func (*Hooks) DispatchLoopNodeTerminal

func (h *Hooks) DispatchLoopNodeTerminal(
	ctx context.Context,
	payload LoopNodeTerminalPayload,
) (LoopNodeTerminalPayload, error)

DispatchLoopNodeTerminal runs the loop.node.terminal hook dispatch.

func (*Hooks) DispatchLoopStarted

func (h *Hooks) DispatchLoopStarted(
	ctx context.Context,
	payload LoopStartedPayload,
) (LoopStartedPayload, error)

DispatchLoopStarted runs the loop.started hook dispatch.

func (*Hooks) DispatchLoopTerminal

func (h *Hooks) DispatchLoopTerminal(
	ctx context.Context,
	payload LoopTerminalPayload,
) (LoopTerminalPayload, error)

DispatchLoopTerminal runs the loop.terminal hook dispatch.

func (*Hooks) DispatchMessageDelta

func (h *Hooks) DispatchMessageDelta(ctx context.Context, payload MessageDeltaPayload) (MessageDeltaPayload, error)

DispatchMessageDelta runs the message.delta hook dispatch.

func (*Hooks) DispatchMessageEnd

func (h *Hooks) DispatchMessageEnd(ctx context.Context, payload MessageEndPayload) (MessageEndPayload, error)

DispatchMessageEnd runs the message.end hook pipeline.

func (*Hooks) DispatchMessageStart

func (h *Hooks) DispatchMessageStart(ctx context.Context, payload MessageStartPayload) (MessageStartPayload, error)

DispatchMessageStart runs the message.start hook pipeline.

func (*Hooks) DispatchPermissionDenied

func (h *Hooks) DispatchPermissionDenied(
	ctx context.Context,
	payload PermissionDeniedPayload,
) (PermissionDeniedPayload, error)

DispatchPermissionDenied runs the permission.denied hook dispatch.

func (*Hooks) DispatchPermissionRequest

func (h *Hooks) DispatchPermissionRequest(
	ctx context.Context,
	payload PermissionRequestPayload,
) (PermissionRequestPayload, error)

DispatchPermissionRequest runs the permission.request hook pipeline.

func (*Hooks) DispatchPermissionResolved

func (h *Hooks) DispatchPermissionResolved(
	ctx context.Context,
	payload PermissionResolvedPayload,
) (PermissionResolvedPayload, error)

DispatchPermissionResolved runs the permission.resolved hook dispatch.

func (*Hooks) DispatchPromptPostAssemble

func (h *Hooks) DispatchPromptPostAssemble(ctx context.Context, payload PromptPayload) (PromptPayload, error)

DispatchPromptPostAssemble runs the prompt.post_assemble hook pipeline.

func (*Hooks) DispatchSessionAttentionChanged

func (h *Hooks) DispatchSessionAttentionChanged(
	ctx context.Context,
	payload SessionAttentionChangedPayload,
) (SessionAttentionChangedPayload, error)

DispatchSessionAttentionChanged dispatches session.attention.changed after its canonical commit.

func (*Hooks) DispatchSessionHealthUpdateAfter

func (h *Hooks) DispatchSessionHealthUpdateAfter(
	ctx context.Context,
	payload SessionHealthUpdateAfterPayload,
) (SessionHealthUpdateAfterPayload, error)

DispatchSessionHealthUpdateAfter runs the session.health.update.after hook dispatch.

func (*Hooks) DispatchSessionMessagePersisted

func (h *Hooks) DispatchSessionMessagePersisted(
	ctx context.Context,
	payload SessionMessagePersistedPayload,
) (SessionMessagePersistedPayload, error)

DispatchSessionMessagePersisted runs the session.message_persisted hook dispatch.

func (*Hooks) DispatchSessionPostCreate

func (h *Hooks) DispatchSessionPostCreate(
	ctx context.Context,
	payload SessionPostCreatePayload,
) (SessionPostCreatePayload, error)

DispatchSessionPostCreate runs the session.post_create hook pipeline.

func (*Hooks) DispatchSessionPostResume

func (h *Hooks) DispatchSessionPostResume(
	ctx context.Context,
	payload SessionPostResumePayload,
) (SessionPostResumePayload, error)

DispatchSessionPostResume runs the session.post_resume hook pipeline.

func (*Hooks) DispatchSessionPostStop

func (h *Hooks) DispatchSessionPostStop(
	ctx context.Context,
	payload SessionPostStopPayload,
) (SessionPostStopPayload, error)

DispatchSessionPostStop runs the session.post_stop hook pipeline.

func (*Hooks) DispatchSessionPreCreate

func (h *Hooks) DispatchSessionPreCreate(
	ctx context.Context,
	payload SessionPreCreatePayload,
) (SessionPreCreatePayload, error)

DispatchSessionPreCreate runs the session.pre_create hook pipeline.

func (*Hooks) DispatchSessionPreResume

func (h *Hooks) DispatchSessionPreResume(
	ctx context.Context,
	payload SessionPreResumePayload,
) (SessionPreResumePayload, error)

DispatchSessionPreResume runs the session.pre_resume hook pipeline.

func (*Hooks) DispatchSessionPreStop

func (h *Hooks) DispatchSessionPreStop(
	ctx context.Context,
	payload SessionPreStopPayload,
) (SessionPreStopPayload, error)

DispatchSessionPreStop runs the session.pre_stop hook pipeline.

func (*Hooks) DispatchSessionRuntimeRecoveryStarted

func (h *Hooks) DispatchSessionRuntimeRecoveryStarted(
	ctx context.Context,
	payload SessionRuntimeRecoveryStartedPayload,
) (SessionRuntimeRecoveryStartedPayload, error)

func (*Hooks) DispatchSpawnCreated

func (h *Hooks) DispatchSpawnCreated(
	ctx context.Context,
	payload SpawnCreatedPayload,
) (SpawnCreatedPayload, error)

DispatchSpawnCreated runs the spawn.created hook dispatch.

func (*Hooks) DispatchSpawnParentStopped

func (h *Hooks) DispatchSpawnParentStopped(
	ctx context.Context,
	payload SpawnParentStoppedPayload,
) (SpawnParentStoppedPayload, error)

DispatchSpawnParentStopped runs the spawn.parent_stopped hook dispatch.

func (*Hooks) DispatchSpawnPreCreate

func (h *Hooks) DispatchSpawnPreCreate(
	ctx context.Context,
	payload SpawnPreCreatePayload,
) (SpawnPreCreatePayload, error)

DispatchSpawnPreCreate runs the spawn.pre_create hook pipeline.

func (*Hooks) DispatchSpawnReaped

func (h *Hooks) DispatchSpawnReaped(
	ctx context.Context,
	payload SpawnReapedPayload,
) (SpawnReapedPayload, error)

DispatchSpawnReaped runs the spawn.reaped hook dispatch.

func (*Hooks) DispatchSpawnTTLExpired

func (h *Hooks) DispatchSpawnTTLExpired(
	ctx context.Context,
	payload SpawnTTLExpiredPayload,
) (SpawnTTLExpiredPayload, error)

DispatchSpawnTTLExpired runs the spawn.ttl_expired hook dispatch.

func (*Hooks) DispatchSubagentSettled

func (h *Hooks) DispatchSubagentSettled(
	ctx context.Context,
	payload SubagentSettledPayload,
) (SubagentSettledPayload, error)

func (*Hooks) DispatchTaskBlocked

func (h *Hooks) DispatchTaskBlocked(
	ctx context.Context,
	payload TaskBlockedPayload,
) (TaskBlockedPayload, error)

DispatchTaskBlocked runs the task.blocked hook dispatch.

func (*Hooks) DispatchTaskNeedsAttention

func (h *Hooks) DispatchTaskNeedsAttention(
	ctx context.Context,
	payload TaskNeedsAttentionPayload,
) (TaskNeedsAttentionPayload, error)

DispatchTaskNeedsAttention runs the task.needs_attention hook dispatch.

func (*Hooks) DispatchTaskRecovered

func (h *Hooks) DispatchTaskRecovered(
	ctx context.Context,
	payload TaskRecoveredPayload,
) (TaskRecoveredPayload, error)

DispatchTaskRecovered runs the task.recovered hook dispatch.

func (*Hooks) DispatchTaskRunCompleted

func (h *Hooks) DispatchTaskRunCompleted(
	ctx context.Context,
	payload TaskRunCompletedPayload,
) (TaskRunCompletedPayload, error)

DispatchTaskRunCompleted runs the task.run.completed hook dispatch.

func (*Hooks) DispatchTaskRunEnqueued

func (h *Hooks) DispatchTaskRunEnqueued(
	ctx context.Context,
	payload TaskRunEnqueuedPayload,
) (TaskRunEnqueuedPayload, error)

DispatchTaskRunEnqueued runs the task.run.enqueued hook dispatch.

func (*Hooks) DispatchTaskRunFailed

func (h *Hooks) DispatchTaskRunFailed(
	ctx context.Context,
	payload TaskRunFailedPayload,
) (TaskRunFailedPayload, error)

DispatchTaskRunFailed runs the task.run.failed hook dispatch.

func (*Hooks) DispatchTaskRunLeaseExpired

func (h *Hooks) DispatchTaskRunLeaseExpired(
	ctx context.Context,
	payload TaskRunLeaseExpiredPayload,
) (TaskRunLeaseExpiredPayload, error)

DispatchTaskRunLeaseExpired runs the task.run.lease_expired hook dispatch.

func (*Hooks) DispatchTaskRunLeaseExtended

func (h *Hooks) DispatchTaskRunLeaseExtended(
	ctx context.Context,
	payload TaskRunLeaseExtendedPayload,
) (TaskRunLeaseExtendedPayload, error)

DispatchTaskRunLeaseExtended runs the task.run.lease_extended hook dispatch.

func (*Hooks) DispatchTaskRunLeaseRecovered

func (h *Hooks) DispatchTaskRunLeaseRecovered(
	ctx context.Context,
	payload TaskRunLeaseRecoveredPayload,
) (TaskRunLeaseRecoveredPayload, error)

DispatchTaskRunLeaseRecovered runs the task.run.lease_recovered hook dispatch.

func (*Hooks) DispatchTaskRunPostClaim

func (h *Hooks) DispatchTaskRunPostClaim(
	ctx context.Context,
	payload TaskRunPostClaimPayload,
) (TaskRunPostClaimPayload, error)

DispatchTaskRunPostClaim runs the task.run.post_claim hook dispatch.

func (*Hooks) DispatchTaskRunPreClaim

func (h *Hooks) DispatchTaskRunPreClaim(
	ctx context.Context,
	payload TaskRunPreClaimPayload,
) (TaskRunPreClaimPayload, error)

DispatchTaskRunPreClaim runs the task.run.pre_claim hook pipeline.

func (*Hooks) DispatchTaskRunReleased

func (h *Hooks) DispatchTaskRunReleased(
	ctx context.Context,
	payload TaskRunReleasedPayload,
) (TaskRunReleasedPayload, error)

DispatchTaskRunReleased runs the task.run.released hook dispatch.

func (*Hooks) DispatchTaskStatusChanged

func (h *Hooks) DispatchTaskStatusChanged(
	ctx context.Context,
	payload TaskStatusChangedPayload,
) (TaskStatusChangedPayload, error)

DispatchTaskStatusChanged runs the task.status_changed hook dispatch.

func (*Hooks) DispatchTaskUnblocked

func (h *Hooks) DispatchTaskUnblocked(
	ctx context.Context,
	payload TaskUnblockedPayload,
) (TaskUnblockedPayload, error)

DispatchTaskUnblocked runs the task.unblocked hook dispatch.

func (*Hooks) DispatchTerminalClosed

func (h *Hooks) DispatchTerminalClosed(ctx context.Context, p TerminalClosedPayload) (TerminalClosedPayload, error)

func (*Hooks) DispatchTerminalCommandFinished

func (h *Hooks) DispatchTerminalCommandFinished(
	ctx context.Context,
	p TerminalCommandFinishedPayload,
) (TerminalCommandFinishedPayload, error)

func (*Hooks) DispatchTerminalCommandStarted

func (h *Hooks) DispatchTerminalCommandStarted(
	ctx context.Context,
	p TerminalCommandStartedPayload,
) (TerminalCommandStartedPayload, error)

func (*Hooks) DispatchTerminalInputProvided

func (h *Hooks) DispatchTerminalInputProvided(
	ctx context.Context,
	p TerminalInputProvidedPayload,
) (TerminalInputProvidedPayload, error)

func (*Hooks) DispatchTerminalInputRequested

func (h *Hooks) DispatchTerminalInputRequested(
	ctx context.Context,
	p TerminalInputRequestedPayload,
) (TerminalInputRequestedPayload, error)

func (*Hooks) DispatchTerminalLimitRejected

func (h *Hooks) DispatchTerminalLimitRejected(
	ctx context.Context,
	p TerminalLimitRejectedPayload,
) (TerminalLimitRejectedPayload, error)

func (*Hooks) DispatchTerminalOpened

func (h *Hooks) DispatchTerminalOpened(ctx context.Context, p TerminalOpenedPayload) (TerminalOpenedPayload, error)

func (*Hooks) DispatchTerminalRecordingStarted

func (h *Hooks) DispatchTerminalRecordingStarted(
	ctx context.Context,
	p TerminalRecordingStartedPayload,
) (TerminalRecordingStartedPayload, error)

func (*Hooks) DispatchTerminalRecordingStopped

func (h *Hooks) DispatchTerminalRecordingStopped(
	ctx context.Context,
	p TerminalRecordingStoppedPayload,
) (TerminalRecordingStoppedPayload, error)

func (*Hooks) DispatchToolPostCall

func (h *Hooks) DispatchToolPostCall(ctx context.Context, payload ToolPostCallPayload) (ToolPostCallPayload, error)

DispatchToolPostCall runs the tool.post_call hook pipeline.

func (*Hooks) DispatchToolPostError

func (h *Hooks) DispatchToolPostError(ctx context.Context, payload ToolPostErrorPayload) (ToolPostErrorPayload, error)

DispatchToolPostError runs the tool.post_error hook pipeline.

func (*Hooks) DispatchToolPreCall

func (h *Hooks) DispatchToolPreCall(ctx context.Context, payload ToolPreCallPayload) (ToolPreCallPayload, error)

DispatchToolPreCall runs the tool.pre_call hook pipeline.

func (*Hooks) DispatchTurnEnd

func (h *Hooks) DispatchTurnEnd(ctx context.Context, payload TurnEndPayload) (TurnEndPayload, error)

DispatchTurnEnd runs the turn.end hook pipeline.

func (*Hooks) DispatchTurnStart

func (h *Hooks) DispatchTurnStart(ctx context.Context, payload TurnStartPayload) (TurnStartPayload, error)

DispatchTurnStart runs the turn.start hook pipeline.

func (*Hooks) DispatchWindowManagerDesktopCreated

func (h *Hooks) DispatchWindowManagerDesktopCreated(
	ctx context.Context,
	payload WindowManagerDesktopCreatedPayload,
) (WindowManagerDesktopCreatedPayload, error)

DispatchWindowManagerDesktopCreated dispatches window_manager.desktop.created.

func (*Hooks) DispatchWindowManagerDesktopDeleted

func (h *Hooks) DispatchWindowManagerDesktopDeleted(
	ctx context.Context,
	payload WindowManagerDesktopDeletedPayload,
) (WindowManagerDesktopDeletedPayload, error)

DispatchWindowManagerDesktopDeleted dispatches window_manager.desktop.deleted.

func (*Hooks) DispatchWindowManagerLayoutApplied

func (h *Hooks) DispatchWindowManagerLayoutApplied(
	ctx context.Context,
	payload WindowManagerLayoutAppliedPayload,
) (WindowManagerLayoutAppliedPayload, error)

DispatchWindowManagerLayoutApplied dispatches window_manager.layout.applied.

func (*Hooks) DispatchWindowManagerStackActivated

func (h *Hooks) DispatchWindowManagerStackActivated(
	ctx context.Context,
	payload WindowManagerStackActivatedPayload,
) (WindowManagerStackActivatedPayload, error)

DispatchWindowManagerStackActivated dispatches window_manager.stack.activated.

func (*Hooks) DispatchWindowManagerStackGrouped

func (h *Hooks) DispatchWindowManagerStackGrouped(
	ctx context.Context,
	payload WindowManagerStackGroupedPayload,
) (WindowManagerStackGroupedPayload, error)

DispatchWindowManagerStackGrouped dispatches window_manager.stack.grouped.

func (*Hooks) DispatchWindowManagerStackUngrouped

func (h *Hooks) DispatchWindowManagerStackUngrouped(
	ctx context.Context,
	payload WindowManagerStackUngroupedPayload,
) (WindowManagerStackUngroupedPayload, error)

DispatchWindowManagerStackUngrouped dispatches window_manager.stack.ungrouped.

func (*Hooks) DispatchWindowManagerWindowClosed

func (h *Hooks) DispatchWindowManagerWindowClosed(
	ctx context.Context,
	payload WindowManagerWindowClosedPayload,
) (WindowManagerWindowClosedPayload, error)

DispatchWindowManagerWindowClosed dispatches window_manager.window.closed.

func (*Hooks) DispatchWindowManagerWindowMoved

func (h *Hooks) DispatchWindowManagerWindowMoved(
	ctx context.Context,
	payload WindowManagerWindowMovedPayload,
) (WindowManagerWindowMovedPayload, error)

DispatchWindowManagerWindowMoved dispatches window_manager.window.moved.

func (*Hooks) DispatchWindowManagerWindowOpened

func (h *Hooks) DispatchWindowManagerWindowOpened(
	ctx context.Context,
	payload WindowManagerWindowOpenedPayload,
) (WindowManagerWindowOpenedPayload, error)

DispatchWindowManagerWindowOpened dispatches window_manager.window.opened.

func (*Hooks) DispatchWorktreeAdopted

func (h *Hooks) DispatchWorktreeAdopted(
	ctx context.Context,
	payload WorktreeObservationPayload,
) (WorktreeObservationPayload, error)

func (*Hooks) DispatchWorktreeCreated

func (h *Hooks) DispatchWorktreeCreated(
	ctx context.Context,
	payload WorktreeObservationPayload,
) (WorktreeObservationPayload, error)

func (*Hooks) DispatchWorktreePreCreate

func (h *Hooks) DispatchWorktreePreCreate(
	ctx context.Context,
	payload WorktreePreCreatePayload,
) (WorktreePreCreatePayload, error)

func (*Hooks) DispatchWorktreePreRemove

func (h *Hooks) DispatchWorktreePreRemove(
	ctx context.Context,
	payload WorktreePreRemovePayload,
) (WorktreePreRemovePayload, error)

func (*Hooks) DispatchWorktreeRemoved

func (h *Hooks) DispatchWorktreeRemoved(
	ctx context.Context,
	payload WorktreeObservationPayload,
) (WorktreeObservationPayload, error)

func (*Hooks) OnAgentEvent

func (h *Hooks) OnAgentEvent(_ context.Context, _ SessionContext, _ any)

OnAgentEvent remains a compatibility no-op. The daemon translates streamed ACP events into concrete tool and permission hook payloads before dispatch.

func (*Hooks) Rebuild

func (h *Hooks) Rebuild(ctx context.Context) error

Rebuild reloads all declaration sources, validates the full snapshot, and swaps it atomically when the semantic contents changed.

func (*Hooks) Version

func (h *Hooks) Version() int64

Version returns the current registry snapshot version.

type InputAttachmentMetadata

type InputAttachmentMetadata struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	MIME  string `json:"mime"`
	Bytes int64  `json:"bytes"`
	Kind  string `json:"kind"`
}

InputAttachmentMetadata is the byte-free attachment view exposed to hooks.

type InputMentionKind

type InputMentionKind string

InputMentionKind is the closed mention kind vocabulary exposed to hooks.

const (
	InputMentionKindFile    InputMentionKind = "file"
	InputMentionKindFolder  InputMentionKind = "folder"
	InputMentionKindSession InputMentionKind = "session"
)

type InputMentionMetadata

type InputMentionMetadata struct {
	Kind   InputMentionKind `json:"kind"`
	Token  string           `json:"token"`
	Target string           `json:"target"`
	Label  string           `json:"label"`
	Start  int              `json:"start"`
	End    int              `json:"end"`
}

InputMentionMetadata is the verified @-mention view exposed to hooks. Target is relative to the session working directory (folders end in "/") or a session id; offsets are UTF-16 code units in Message, end exclusive.

func InputMentionsFromDomain

func InputMentionsFromDomain(mentions []mention.Mention) []InputMentionMetadata

InputMentionsFromDomain converts verified mentions into the hook wire DTO.

type InputPreSubmitPatch

type InputPreSubmitPatch struct {
	ControlPatch
	Message       *string        `json:"message,omitempty"`
	ContextBlocks []ContextBlock `json:"context_blocks,omitempty"`
}

InputPreSubmitPatch mutates or denies the submitted input.

type InputPreSubmitPayload

type InputPreSubmitPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	InputClass    string                    `json:"input_class,omitempty"`
	Message       string                    `json:"message,omitempty"`
	ContextBlocks []ContextBlock            `json:"context_blocks,omitempty"`
	Attachments   []InputAttachmentMetadata `json:"attachments,omitempty"`
	Mentions      []InputMentionMetadata    `json:"mentions,omitempty"`
}

InputPreSubmitPayload is delivered before prompt submission.

type LoopContext

type LoopContext struct {
	ProfileID       string `json:"profile_id,omitempty"`
	LoopRunID       string `json:"loop_run_id,omitempty"`
	ParentLoopRunID string `json:"parent_loop_run_id,omitempty"`
	WorkspaceID     string `json:"workspace_id,omitempty"`
	LoopName        string `json:"loop_name,omitempty"`
	Generation      int    `json:"generation,omitempty"`
	TaskID          string `json:"task_id,omitempty"`
	RunID           string `json:"run_id,omitempty"`
	RunKind         string `json:"run_kind,omitempty"`
	NodeID          string `json:"node_id,omitempty"`
	WorkflowID      string `json:"workflow_id,omitempty"`
	AgentName       string `json:"agent_name,omitempty"`
	SessionID       string `json:"session_id,omitempty"`
	ActorKind       string `json:"actor_kind,omitempty"`
	ActorID         string `json:"actor_id,omitempty"`
	OriginKind      string `json:"origin_kind,omitempty"`
	OriginRef       string `json:"origin_ref,omitempty"`
}

LoopContext carries identifiers shared by loop lifecycle hooks.

func (LoopContext) HookProfileID

func (c LoopContext) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

type LoopControlPatch

type LoopControlPatch struct {
	ControlPatch
}

LoopControlPatch denies sync loop control hooks.

type LoopGatePayload

type LoopGatePayload struct {
	PayloadBase
	LoopContext
	GateID string `json:"gate_id,omitempty"`
	// Outcome is the machine result already computed when the hook observes the gate.
	Outcome string `json:"outcome,omitempty"`
	// Score is the computed metric score, when the observed gate has a metric criterion.
	Score *float64 `json:"score,omitempty"`
	// BestGeneration is the durable best generation known when the hook observes the result.
	BestGeneration *int64          `json:"best_generation,omitempty"`
	Status         string          `json:"status,omitempty"`
	ReasonCode     string          `json:"reason_code,omitempty"`
	Details        json.RawMessage `json:"details,omitempty"`
	Denied         bool            `json:"denied,omitempty"`
	DenyReason     string          `json:"deny_reason,omitempty"`
}

LoopGatePayload is shared by gate decision hooks.

type LoopGatePostPayload

type LoopGatePostPayload = LoopGatePayload

LoopGatePostPayload is delivered after a loop gate decision is committed.

type LoopGatePrePatch

type LoopGatePrePatch = LoopControlPatch

LoopGatePrePatch denies a gate before the decision commits.

type LoopGatePrePayload

type LoopGatePrePayload = LoopGatePayload

LoopGatePrePayload is delivered before a loop gate decision is committed.

type LoopGenerationOrigin

type LoopGenerationOrigin string

LoopGenerationOrigin is the closed provenance vocabulary for generation boundary hooks.

const (
	LoopGenerationOriginInitial            LoopGenerationOrigin = "initial"
	LoopGenerationOriginStopWhen           LoopGenerationOrigin = "stop_when"
	LoopGenerationOriginReattempt          LoopGenerationOrigin = "reattempt"
	LoopGenerationOriginGateRevise         LoopGenerationOrigin = "gate_revise"
	LoopGenerationOriginGateNextGeneration LoopGenerationOrigin = "gate_next_generation"
	LoopGenerationOriginDoDRetry           LoopGenerationOrigin = "dod_retry"
	LoopGenerationOriginRatchetRestore     LoopGenerationOrigin = "ratchet_restore"
)

type LoopGenerationPayload

type LoopGenerationPayload struct {
	PayloadBase
	LoopContext
	// Origin is the closed loop-generation provenance value that explains why this generation exists.
	Origin           LoopGenerationOrigin `json:"origin"`
	ParentGeneration int64                `json:"parent_generation"`
	Status           string               `json:"status,omitempty"`
	ReasonCode       string               `json:"reason_code,omitempty"`
	Details          json.RawMessage      `json:"details,omitempty"`
	Denied           bool                 `json:"denied,omitempty"`
	DenyReason       string               `json:"deny_reason,omitempty"`
}

LoopGenerationPayload is shared by generation boundary hooks.

type LoopGenerationPostPayload

type LoopGenerationPostPayload = LoopGenerationPayload

LoopGenerationPostPayload is delivered after a loop generation plan is produced.

type LoopGenerationPrePatch

type LoopGenerationPrePatch = LoopControlPatch

LoopGenerationPrePatch denies a generation before planning.

type LoopGenerationPrePayload

type LoopGenerationPrePayload = LoopGenerationPayload

LoopGenerationPrePayload is delivered before a loop generation is planned.

type LoopLifecyclePayload

type LoopLifecyclePayload struct {
	PayloadBase
	LoopContext
	Status     string          `json:"status,omitempty"`
	Cause      string          `json:"cause,omitempty"`
	ReasonCode string          `json:"reason_code,omitempty"`
	Details    json.RawMessage `json:"details,omitempty"`
}

LoopLifecyclePayload is shared by loop started and terminal events.

type LoopNodeTerminalPayload

type LoopNodeTerminalPayload struct {
	PayloadBase
	LoopContext
	TaskStatus   string          `json:"task_status,omitempty"`
	RunStatus    string          `json:"run_status,omitempty"`
	FailureClass string          `json:"failure_class,omitempty"`
	Disposition  string          `json:"disposition,omitempty"`
	Attempt      int             `json:"attempt,omitempty"`
	Target       string          `json:"target,omitempty"`
	Error        string          `json:"error,omitempty"`
	Details      json.RawMessage `json:"details,omitempty"`
}

LoopNodeTerminalPayload is delivered after a loop node task run reaches a terminal state.

type LoopObservationPatch

type LoopObservationPatch = AutonomyObservationPatch

LoopObservationPatch is the observation patch surface for committed loop hooks.

type LoopStartedPayload

type LoopStartedPayload = LoopLifecyclePayload

LoopStartedPayload is delivered after a loop_run is created.

type LoopTerminalPayload

type LoopTerminalPayload = LoopLifecyclePayload

LoopTerminalPayload is delivered after a loop_run reaches a terminal state.

type MessageDeltaPatch

type MessageDeltaPatch = MessagePatch

MessageDeltaPatch is the message-delta patch surface.

type MessageDeltaPayload

type MessageDeltaPayload = MessagePayload

MessageDeltaPayload is delivered for streaming message deltas.

type MessageEndPatch

type MessageEndPatch = MessagePatch

MessageEndPatch is the message-end patch surface.

type MessageEndPayload

type MessageEndPayload = MessagePayload

MessageEndPayload is delivered when a message finishes.

type MessagePatch

type MessagePatch struct {
	ControlPatch
	Role      *string `json:"role,omitempty"`
	DeltaType *string `json:"delta_type,omitempty"`
	Text      *string `json:"text,omitempty"`
}

MessagePatch mutates or denies message-scoped operations.

type MessagePayload

type MessagePayload struct {
	PayloadBase
	SessionContext
	TurnContext
	MessageID string          `json:"message_id,omitempty"`
	Role      string          `json:"role,omitempty"`
	DeltaType string          `json:"delta_type,omitempty"`
	Text      string          `json:"text,omitempty"`
	Raw       json.RawMessage `json:"raw,omitempty"`
}

MessagePayload is shared by message start, delta, and end events.

type MessageStartPatch

type MessageStartPatch = MessagePatch

MessageStartPatch is the message-start patch surface.

type MessageStartPayload

type MessageStartPayload = MessagePayload

MessageStartPayload is delivered when a message begins.

type NativeExecutor

type NativeExecutor struct {
	// contains filtered or unexported fields
}

NativeExecutor runs hooks as direct Go callbacks.

func NewNativeExecutor

func NewNativeExecutor(callback NativeHookFunc) *NativeExecutor

NewNativeExecutor constructs a NativeExecutor bound to one callback.

func (*NativeExecutor) Execute

func (e *NativeExecutor) Execute(ctx context.Context, hook RegisteredHook, payload []byte) (result []byte, err error)

Execute invokes the configured Go callback directly.

func (*NativeExecutor) Kind

Kind returns the executor type.

type NativeHookFunc

type NativeHookFunc func(ctx context.Context, hook RegisteredHook, payload []byte) ([]byte, error)

NativeHookFunc executes an in-process hook without crossing a subprocess boundary.

type Option

type Option func(*Hooks)

Option customizes a Hooks dispatcher during construction.

func WithAgentDeclarationProvider

func WithAgentDeclarationProvider(provider DeclarationProvider) Option

WithAgentDeclarationProvider injects the agent-definition declaration source.

func WithAgentDeclarations

func WithAgentDeclarations(decls []HookDecl) Option

WithAgentDeclarations injects a static agent-definition declaration set.

func WithAsyncDrainTimeout

func WithAsyncDrainTimeout(timeout time.Duration) Option

WithAsyncDrainTimeout configures the async pool shutdown deadline.

func WithAsyncQueueCapacity

func WithAsyncQueueCapacity(capacity int) Option

WithAsyncQueueCapacity configures the async worker pool queue depth.

func WithAsyncWorkerCount

func WithAsyncWorkerCount(count int) Option

WithAsyncWorkerCount configures the async worker pool size.

func WithConfigDeclarationProvider

func WithConfigDeclarationProvider(provider DeclarationProvider) Option

WithConfigDeclarationProvider injects the config-hook declaration source.

func WithConfigDeclarations

func WithConfigDeclarations(decls []HookDecl) Option

WithConfigDeclarations injects a static config declaration set.

func WithDebugPatchAudit

func WithDebugPatchAudit(enabled bool) Option

WithDebugPatchAudit enables patch capture for non-security hook families.

func WithExecutorResolver

func WithExecutorResolver(resolve ExecutorResolver) Option

WithExecutorResolver injects the resolver used to bind declarations to executors during rebuild.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger injects the logger used for hook diagnostics.

func WithNativeDeclarationProvider

func WithNativeDeclarationProvider(provider DeclarationProvider) Option

WithNativeDeclarationProvider injects the native-hook declaration source.

func WithNativeDeclarations

func WithNativeDeclarations(decls []HookDecl) Option

WithNativeDeclarations injects a static native declaration set.

func WithNow

func WithNow(now func() time.Time) Option

WithNow injects the clock used by notifier payload construction.

func WithSkillDeclarationProvider

func WithSkillDeclarationProvider(provider DeclarationProvider) Option

WithSkillDeclarationProvider injects the skill-hook declaration source.

func WithSkillDeclarations

func WithSkillDeclarations(decls []HookDecl) Option

WithSkillDeclarations injects a static skill declaration set.

func WithTelemetrySink

func WithTelemetrySink(sink TelemetrySink) Option

WithTelemetrySink injects the persistence sink used when no active session-scoped writer is attached to the dispatch context.

type PayloadBase

type PayloadBase struct {
	Event     HookEvent `json:"event"`
	Timestamp time.Time `json:"timestamp"`
}

PayloadBase carries the common identifiers attached to every hook payload.

type PermissionDeniedPatch

type PermissionDeniedPatch struct{}

PermissionDeniedPatch is the denied patch surface.

type PermissionDeniedPayload

type PermissionDeniedPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	RequestID     string             `json:"request_id,omitempty"`
	Action        string             `json:"action,omitempty"`
	Resource      string             `json:"resource,omitempty"`
	Decision      string             `json:"decision,omitempty"`
	DecisionClass string             `json:"decision_class,omitempty"`
	ToolCall      PermissionToolCall `json:"tool_call"`
}

PermissionDeniedPayload is delivered after a permission denial resolves.

type PermissionOption

type PermissionOption struct {
	Decision string `json:"decision,omitempty"`
	OptionID string `json:"option_id,omitempty"`
	Kind     string `json:"kind,omitempty"`
	Label    string `json:"label,omitempty"`
}

PermissionOption carries one interactive permission option.

type PermissionRequestPatch

type PermissionRequestPatch struct {
	ControlPatch
	Decision      *string `json:"decision,omitempty"`
	DecisionClass *string `json:"decision_class,omitempty"`
	Reason        *string `json:"reason,omitempty"`
}

PermissionRequestPatch mutates or denies the permission-request surface.

type PermissionRequestPayload

type PermissionRequestPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	RequestID     string             `json:"request_id,omitempty"`
	Action        string             `json:"action,omitempty"`
	Resource      string             `json:"resource,omitempty"`
	Decision      string             `json:"decision,omitempty"`
	DecisionClass string             `json:"decision_class,omitempty"`
	ToolInput     json.RawMessage    `json:"tool_input,omitempty"`
	ToolCall      PermissionToolCall `json:"tool_call"`
	Options       []PermissionOption `json:"options,omitempty"`
}

PermissionRequestPayload is delivered before a permission decision resolves.

type PermissionResolutionPayload

type PermissionResolutionPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	RequestID     string             `json:"request_id,omitempty"`
	Action        string             `json:"action,omitempty"`
	Resource      string             `json:"resource,omitempty"`
	Decision      string             `json:"decision,omitempty"`
	DecisionClass string             `json:"decision_class,omitempty"`
	ToolInput     json.RawMessage    `json:"tool_input,omitempty"`
	ToolCall      PermissionToolCall `json:"tool_call"`
}

PermissionResolutionPayload is shared by resolved and denied events.

type PermissionResolvedPatch

type PermissionResolvedPatch struct{}

PermissionResolvedPatch is the resolved patch surface.

type PermissionResolvedPayload

type PermissionResolvedPayload = PermissionResolutionPayload

PermissionResolvedPayload is delivered after a permission decision resolves.

type PermissionSet

type PermissionSet struct {
	Tools          []string `json:"tools,omitempty"`
	Skills         []string `json:"skills,omitempty"`
	MCPServers     []string `json:"mcp_servers,omitempty"`
	WorkspacePaths []string `json:"workspace_paths,omitempty"`
}

PermissionSet captures concrete permission atoms that spawned children may only narrow.

type PermissionToolCall

type PermissionToolCall struct {
	ID        string         `json:"id,omitempty"`
	Kind      string         `json:"kind,omitempty"`
	Title     string         `json:"title,omitempty"`
	Status    string         `json:"status,omitempty"`
	Locations []ToolLocation `json:"locations,omitempty"`
}

PermissionToolCall carries the tool details attached to a permission request.

type PromptPatch

type PromptPatch struct {
	ControlPatch
	Prompt        *string        `json:"prompt,omitempty"`
	ContextBlocks []ContextBlock `json:"context_blocks,omitempty"`
}

PromptPatch mutates or denies the assembled prompt.

type PromptPayload

type PromptPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	InputClass    string         `json:"input_class,omitempty"`
	Prompt        string         `json:"prompt,omitempty"`
	ContextBlocks []ContextBlock `json:"context_blocks,omitempty"`
}

PromptPayload is delivered after prompt assembly.

type RegisteredHook

type RegisteredHook struct {
	Name      string
	ProfileID string
	Event     HookEvent
	Source    HookSource
	Mode      HookMode
	Required  bool
	Priority  int32
	Timeout   time.Duration
	Matcher   HookMatcher
	Executor  Executor
	Metadata  map[string]string
}

RegisteredHook is the normalized hook ready for dispatch.

func (RegisteredHook) Validate

func (h RegisteredHook) Validate() error

Validate ensures the registered hook satisfies the task-01 invariants.

type ResolvedHook

type ResolvedHook struct {
	RegisteredHook
	Decl HookDecl
}

ResolvedHook is the registry snapshot record with executor binding attached.

func NormalizeHookDecl

func NormalizeHookDecl(decl HookDecl, resolve ExecutorResolver) (ResolvedHook, error)

NormalizeHookDecl validates one declaration, applies defaults, and binds the executor.

func NormalizeHookDecls

func NormalizeHookDecls(decls []HookDecl, resolve ExecutorResolver) ([]ResolvedHook, error)

NormalizeHookDecls normalizes every declaration in order and stops at the first error.

func OrderedResolvedHooks

func OrderedResolvedHooks(hooks []*ResolvedHook) []*ResolvedHook

OrderedResolvedHooks returns a sorted copy of the slice.

func (*ResolvedHook) Validate

func (h *ResolvedHook) Validate() error

Validate ensures the resolved hook is internally consistent.

type SecretRefResolver

type SecretRefResolver interface {
	ResolveRef(context.Context, string) (string, error)
}

SecretRefResolver resolves env: and vault: refs for subprocess secret env bindings.

type SessionAttentionChangedPayload

type SessionAttentionChangedPayload struct {
	PayloadBase
	SessionContext
	From  string    `json:"from"`
	To    string    `json:"to"`
	Class string    `json:"class"`
	At    time.Time `json:"at"`
}

SessionAttentionChangedPayload observes one committed attention badge edge.

type SessionAttentionObservationPatch

type SessionAttentionObservationPatch struct{}

SessionAttentionObservationPatch is the no-op patch surface for attention observations.

type SessionContext

type SessionContext struct {
	ProfileID   string `json:"profile_id,omitempty"`
	SessionID   string `json:"session_id,omitempty"`
	SessionName string `json:"session_name,omitempty"`
	SessionType string `json:"session_type,omitempty"`
	AgentName   string `json:"agent_name,omitempty"`
	WorkspaceID string `json:"workspace_id,omitempty"`
	Workspace   string `json:"workspace,omitempty"`
	*SessionRuntimeContext
	State string `json:"state,omitempty"`
	*SessionSoulContext
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

SessionContext carries the common session-scoped hook attributes.

func SessionContextFromPayload

func SessionContextFromPayload(payload any) SessionContext

SessionContextFromPayload extracts the shared session context from a typed hook payload.

func (SessionContext) ACPSessionIDValue

func (c SessionContext) ACPSessionIDValue() string

ACPSessionIDValue returns the optional ACP session binding.

func (SessionContext) HookProfileID

func (c SessionContext) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

func (SessionContext) WorktreeIDValue

func (c SessionContext) WorktreeIDValue() string

WorktreeIDValue returns the optional worktree binding.

type SessionCreatePatch

type SessionCreatePatch struct {
	ControlPatch
	SessionName *string `json:"session_name,omitempty"`
	SessionType *string `json:"session_type,omitempty"`
	AgentName   *string `json:"agent_name,omitempty"`
	WorkspaceID *string `json:"workspace_id,omitempty"`
	Workspace   *string `json:"workspace,omitempty"`
}

SessionCreatePatch mutates or denies session lifecycle operations.

type SessionHealthUpdateAfterPayload

type SessionHealthUpdateAfterPayload struct {
	PayloadBase
	SessionContext
	Health              string    `json:"health,omitempty"`
	ActivePrompt        bool      `json:"active_prompt,omitempty"`
	Attachable          bool      `json:"attachable,omitempty"`
	EligibleForWake     bool      `json:"eligible_for_wake,omitempty"`
	IneligibilityReason string    `json:"ineligibility_reason,omitempty"`
	LastActivityAt      time.Time `json:"last_activity_at"`
	LastPresenceAt      time.Time `json:"last_presence_at"`
	LastError           string    `json:"last_error,omitempty"`
}

SessionHealthUpdateAfterPayload is delivered after metadata-only session health changes.

type SessionLifecyclePayload

type SessionLifecyclePayload struct {
	PayloadBase
	SessionContext
}

SessionLifecyclePayload is shared by post-create, resume, and stop events.

type SessionMessagePersistedPayload

type SessionMessagePersistedPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	MessageID       string          `json:"message_id,omitempty"`
	MessageSeq      int64           `json:"message_seq,omitempty"`
	Role            string          `json:"role,omitempty"`
	Text            string          `json:"text,omitempty"`
	Raw             json.RawMessage `json:"raw,omitempty"`
	Persisted       json.RawMessage `json:"persisted,omitempty"`
	RootSessionID   string          `json:"root_session_id,omitempty"`
	ParentSessionID string          `json:"parent_session_id,omitempty"`
	ActorKind       string          `json:"actor_kind,omitempty"`
	ActorID         string          `json:"actor_id,omitempty"`
}

SessionMessagePersistedPayload is delivered after an assistant message is durably persisted.

type SessionPostCreatePatch

type SessionPostCreatePatch = SessionCreatePatch

SessionPostCreatePatch is the post-create patch surface.

type SessionPostCreatePayload

type SessionPostCreatePayload = SessionLifecyclePayload

SessionPostCreatePayload is delivered after a session is created.

type SessionPostResumePatch

type SessionPostResumePatch = SessionCreatePatch

SessionPostResumePatch is the post-resume patch surface.

type SessionPostResumePayload

type SessionPostResumePayload = SessionLifecyclePayload

SessionPostResumePayload is delivered after a session resumes.

type SessionPostStopPatch

type SessionPostStopPatch = SessionCreatePatch

SessionPostStopPatch is the post-stop patch surface.

type SessionPostStopPayload

type SessionPostStopPayload = SessionLifecyclePayload

SessionPostStopPayload is delivered after a session stops.

type SessionPreCreatePayload

type SessionPreCreatePayload struct {
	PayloadBase
	SessionContext
}

SessionPreCreatePayload is delivered before a session is created.

type SessionPreResumePatch

type SessionPreResumePatch = SessionCreatePatch

SessionPreResumePatch is the pre-resume patch surface.

type SessionPreResumePayload

type SessionPreResumePayload = SessionLifecyclePayload

SessionPreResumePayload is delivered before a session resumes.

type SessionPreStopPatch

type SessionPreStopPatch = SessionCreatePatch

SessionPreStopPatch is the pre-stop patch surface.

type SessionPreStopPayload

type SessionPreStopPayload = SessionLifecyclePayload

SessionPreStopPayload is delivered before a session stops.

type SessionRuntimeContext

type SessionRuntimeContext struct {
	WorktreeID   string `json:"worktree_id,omitempty"`
	ACPSessionID string `json:"acp_session_id,omitempty"`
}

SessionRuntimeContext carries optional runtime bindings on session-scoped hooks. Embedding preserves the flat hook payload JSON contract.

func NewSessionRuntimeContext

func NewSessionRuntimeContext(worktreeID string, acpSessionID string) *SessionRuntimeContext

NewSessionRuntimeContext returns compact runtime bindings when either value is present.

type SessionRuntimeRecoveryExhaustedPayload

type SessionRuntimeRecoveryExhaustedPayload = SessionRuntimeRecoveryPayload

SessionRuntimeRecoveryExhaustedPayload is emitted after all recovery attempts fail.

type SessionRuntimeRecoveryPayload

type SessionRuntimeRecoveryPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	RunID         string `json:"run_id"`
	Attempt       int    `json:"attempt"`
	MaxAttempts   int    `json:"max_attempts"`
	Generation    int64  `json:"generation"`
	FailureKind   string `json:"failure_kind,omitempty"`
	FailureDetail string `json:"failure_detail,omitempty"`
}

SessionRuntimeRecoveryPayload reports one automatic runtime recovery lifecycle event.

type SessionRuntimeRecoveryStartedPayload

type SessionRuntimeRecoveryStartedPayload = SessionRuntimeRecoveryPayload

SessionRuntimeRecoveryStartedPayload is emitted before a bounded recovery attempt.

type SessionRuntimeRecoverySucceededPayload

type SessionRuntimeRecoverySucceededPayload = SessionRuntimeRecoveryPayload

SessionRuntimeRecoverySucceededPayload is emitted after the replacement runtime accepts the turn.

type SessionSoulContext

type SessionSoulContext struct {
	SoulSnapshotID string `json:"soul_snapshot_id,omitempty"`
	SoulDigest     string `json:"soul_digest,omitempty"`
}

SessionSoulContext carries optional authored Soul provenance on session-scoped hooks.

type SpawnContext

type SpawnContext struct {
	ProfileID        string `json:"profile_id,omitempty"`
	ParentSessionID  string `json:"parent_session_id,omitempty"`
	RootSessionID    string `json:"root_session_id,omitempty"`
	ChildSessionID   string `json:"child_session_id,omitempty"`
	WorkspaceID      string `json:"workspace_id,omitempty"`
	Workspace        string `json:"workspace,omitempty"`
	AgentName        string `json:"agent_name,omitempty"`
	SpawnRole        string `json:"spawn_role,omitempty"`
	SpawnDepth       int    `json:"spawn_depth,omitempty"`
	TTLSeconds       int64  `json:"ttl_seconds,omitempty"`
	AutoStopOnParent bool   `json:"auto_stop_on_parent,omitempty"`
	TaskID           string `json:"task_id,omitempty"`
	RunID            string `json:"run_id,omitempty"`
	WorkflowID       string `json:"workflow_id,omitempty"`
	SoulSnapshotID   string `json:"soul_snapshot_id,omitempty"`
	SoulDigest       string `json:"soul_digest,omitempty"`
	ParentSoulDigest string `json:"parent_soul_digest,omitempty"`
}

SpawnContext carries spawn identifiers shared across spawn lifecycle hooks.

func (SpawnContext) HookProfileID

func (c SpawnContext) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

type SpawnCreatePatch

type SpawnCreatePatch struct {
	ControlPatch
	AgentName        *string        `json:"agent_name,omitempty"`
	SpawnRole        *string        `json:"spawn_role,omitempty"`
	TTLSeconds       *int64         `json:"ttl_seconds,omitempty"`
	ChildPermissions *PermissionSet `json:"child_permissions,omitempty"`
}

SpawnCreatePatch mutates or denies child-session spawn requests.

type SpawnCreatedPayload

type SpawnCreatedPayload = SpawnLifecyclePayload

SpawnCreatedPayload is delivered after a child session is created.

type SpawnLifecyclePayload

type SpawnLifecyclePayload struct {
	PayloadBase
	SpawnContext
	ParentPermissions *PermissionSet `json:"parent_permissions,omitempty"`
	ChildPermissions  *PermissionSet `json:"child_permissions,omitempty"`
	StopReason        string         `json:"stop_reason,omitempty"`
	ReapReason        string         `json:"reap_reason,omitempty"`
	Error             string         `json:"error,omitempty"`
}

SpawnLifecyclePayload is shared by committed spawn lifecycle hooks.

type SpawnObservationPatch

type SpawnObservationPatch = AutonomyObservationPatch

SpawnObservationPatch is the observation patch surface for committed spawn lifecycle hooks.

type SpawnParentStoppedPayload

type SpawnParentStoppedPayload = SpawnLifecyclePayload

SpawnParentStoppedPayload is delivered when parent-stop reaps a child session.

type SpawnPreCreatePayload

type SpawnPreCreatePayload struct {
	Subagent *SubagentSpawnPayload `json:"subagent,omitempty"`
	PayloadBase
	SpawnContext
	ParentPermissions *PermissionSet `json:"parent_permissions"`
	ChildPermissions  *PermissionSet `json:"child_permissions"`
	Denied            bool           `json:"denied,omitempty"`
	DenyReason        string         `json:"deny_reason,omitempty"`
}

SpawnPreCreatePayload is delivered before a child session is created.

type SpawnReapedPayload

type SpawnReapedPayload = SpawnLifecyclePayload

SpawnReapedPayload is delivered after a child session is reaped.

type SpawnTTLExpiredPayload

type SpawnTTLExpiredPayload = SpawnLifecyclePayload

SpawnTTLExpiredPayload is delivered when TTL expiry reaps a child session.

type SubagentObservationPatch

type SubagentObservationPatch = AutonomyObservationPatch

type SubagentPullRequestPayload

type SubagentPullRequestPayload struct {
	URL    string `json:"url"`
	Number int    `json:"number"`
	State  string `json:"state"`
}

type SubagentRuntimePayload

type SubagentRuntimePayload struct {
	Provider string `json:"provider"`
	Model    string `json:"model"`
}

type SubagentSettledPayload

type SubagentSettledPayload struct {
	PayloadBase
	Isolation       string                   `json:"isolation"`
	Worktree        *SubagentWorktreePayload `json:"worktree,omitempty"`
	ProfileID       string                   `json:"profile_id,omitempty"`
	WorkspaceID     string                   `json:"workspace_id"`
	SubagentID      string                   `json:"subagent_id"`
	ParentSessionID string                   `json:"parent_session_id"`
	ChildSessionID  *string                  `json:"child_session_id"`
	Origin          string                   `json:"origin"`
	Status          string                   `json:"status"`
	Runtime         SubagentRuntimePayload   `json:"runtime"`
	DurationMS      int64                    `json:"duration_ms"`
}

func (SubagentSettledPayload) HookProfileID

func (p SubagentSettledPayload) HookProfileID() string

type SubagentSpawnPayload

type SubagentSpawnPayload struct {
	Isolation  string `json:"isolation"`
	WorktreeID string `json:"worktree_id,omitempty"`
	Title      string `json:"title"`
	Role       string `json:"role"`
	TaskChars  int    `json:"task_chars"`
}

type SubagentWorktreePayload

type SubagentWorktreePayload struct {
	ID                string                      `json:"id"`
	Name              string                      `json:"name"`
	Branch            string                      `json:"branch"`
	BaseRef           string                      `json:"base_ref"`
	BaseSHA           string                      `json:"base_sha,omitempty"`
	Path              string                      `json:"path"`
	HeadSHA           string                      `json:"head_sha,omitempty"`
	CommitsAhead      *int                        `json:"commits_ahead,omitempty"`
	DirtyFiles        *int                        `json:"dirty_files,omitempty"`
	ObservedAt        *time.Time                  `json:"observed_at,omitempty"`
	PullRequestStatus string                      `json:"pull_request_status,omitempty"`
	PullRequest       *SubagentPullRequestPayload `json:"pull_request,omitempty"`
}

type SubprocessExecutor

type SubprocessExecutor struct {
	// contains filtered or unexported fields
}

SubprocessExecutor runs hooks through a local shell command boundary.

func NewSubprocessExecutor

func NewSubprocessExecutor(command string, args []string, opts ...SubprocessExecutorOption) *SubprocessExecutor

NewSubprocessExecutor constructs a subprocess-backed executor.

func (*SubprocessExecutor) Execute

func (e *SubprocessExecutor) Execute(ctx context.Context, hook RegisteredHook, payload []byte) ([]byte, error)

Execute runs the configured command with the JSON payload on stdin and returns captured stdout.

func (*SubprocessExecutor) Kind

Kind returns the executor type.

type SubprocessExecutorOption

type SubprocessExecutorOption func(*SubprocessExecutor)

SubprocessExecutorOption mutates a subprocess executor during construction.

func WithSubprocessDir

func WithSubprocessDir(dir string) SubprocessExecutorOption

WithSubprocessDir configures the working directory for a subprocess hook.

func WithSubprocessEnv

func WithSubprocessEnv(env map[string]string) SubprocessExecutorOption

WithSubprocessEnv configures the explicit environment overrides for a hook.

func WithSubprocessProcessRegistry

func WithSubprocessProcessRegistry(registry *toolruntime.Registry) SubprocessExecutorOption

WithSubprocessProcessRegistry injects the shared process registry for subprocess hook commands.

func WithSubprocessRegistryTimeout

func WithSubprocessRegistryTimeout(timeout time.Duration) SubprocessExecutorOption

WithSubprocessRegistryTimeout bounds detached lifecycle writes to the process registry.

func WithSubprocessSecretEnv

func WithSubprocessSecretEnv(env map[string]string, resolver SecretRefResolver) SubprocessExecutorOption

WithSubprocessSecretEnv configures secret refs resolved immediately before a hook runs.

type TaskAttentionPayload

type TaskAttentionPayload struct {
	PayloadBase
	TaskContext
	Reason string    `json:"reason,omitempty"`
	Note   string    `json:"note,omitempty"`
	At     time.Time `json:"at,omitzero"`
}

TaskAttentionPayload is shared by task-level needs-attention lifecycle hooks.

type TaskBlockPayload

type TaskBlockPayload struct {
	PayloadBase
	TaskContext
	BlockID   string          `json:"block_id,omitempty"`
	Kind      string          `json:"kind,omitempty"`
	Reason    string          `json:"reason,omitempty"`
	Details   json.RawMessage `json:"details,omitempty"`
	ClearedAt time.Time       `json:"cleared_at,omitzero"`
	ClearNote string          `json:"clear_note,omitempty"`
}

TaskBlockPayload is shared by task block and unblock hooks.

type TaskBlockedPayload

type TaskBlockedPayload = TaskBlockPayload

TaskBlockedPayload is delivered after a task block is committed.

type TaskContext

type TaskContext struct {
	ProfileID      string `json:"profile_id,omitempty"`
	TaskID         string `json:"task_id,omitempty"`
	ParentTaskID   string `json:"parent_task_id,omitempty"`
	WorkspaceID    string `json:"workspace_id,omitempty"`
	WorkflowID     string `json:"workflow_id,omitempty"`
	AgentName      string `json:"agent_name,omitempty"`
	ActorKind      string `json:"actor_kind,omitempty"`
	ActorID        string `json:"actor_id,omitempty"`
	OriginKind     string `json:"origin_kind,omitempty"`
	OriginRef      string `json:"origin_ref,omitempty"`
	TaskStatus     string `json:"task_status,omitempty"`
	RunID          string `json:"run_id,omitempty"`
	ReleaseReason  string `json:"release_reason,omitempty"`
	ClaimTokenHash string `json:"claim_token_hash,omitempty"`
}

TaskContext carries task-level identifiers shared across task lifecycle hooks.

func (TaskContext) HookProfileID

func (c TaskContext) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

type TaskNeedsAttentionPayload

type TaskNeedsAttentionPayload = TaskAttentionPayload

TaskNeedsAttentionPayload is delivered after a task escalates to needs_attention.

type TaskObservationPatch

type TaskObservationPatch = AutonomyObservationPatch

TaskObservationPatch is the observation patch surface for committed task lifecycle hooks.

type TaskRecoveredPayload

type TaskRecoveredPayload = TaskAttentionPayload

TaskRecoveredPayload is delivered after a task leaves needs_attention.

type TaskRunClaimCriteria

type TaskRunClaimCriteria struct {
	RunID                string   `json:"run_id,omitempty"`
	RunKind              string   `json:"run_kind,omitempty"`
	WorkspaceID          string   `json:"workspace_id,omitempty"`
	TargetSessionID      string   `json:"target_session_id,omitempty"`
	ClaimerSessionID     string   `json:"claimer_session_id,omitempty"`
	AgentName            string   `json:"agent_name,omitempty"`
	RequiredCapabilities []string `json:"required_capabilities,omitempty"`
	PriorityMin          int      `json:"priority_min,omitempty"`
}

TaskRunClaimCriteria carries the mutable claim criteria exposed to task-run pre-claim hooks.

type TaskRunCompletedPayload

type TaskRunCompletedPayload = TaskRunLeasePayload

TaskRunCompletedPayload is delivered after a token-fenced task run completion.

type TaskRunContext

type TaskRunContext struct {
	ProfileID       string    `json:"profile_id,omitempty"`
	TaskID          string    `json:"task_id,omitempty"`
	RunID           string    `json:"run_id,omitempty"`
	RunKind         *string   `json:"run_kind,omitempty"`
	WakeID          string    `json:"wake_id,omitempty"`
	OwnerKey        string    `json:"owner_key,omitempty"`
	TargetSessionID string    `json:"target_session_id,omitempty"`
	LoopRunID       string    `json:"loop_run_id,omitempty"`
	WorkspaceID     string    `json:"workspace_id,omitempty"`
	WorkflowID      string    `json:"workflow_id,omitempty"`
	AgentName       string    `json:"agent_name,omitempty"`
	SessionID       string    `json:"session_id,omitempty"`
	ActorKind       string    `json:"actor_kind,omitempty"`
	ActorID         string    `json:"actor_id,omitempty"`
	OriginKind      string    `json:"origin_kind,omitempty"`
	OriginRef       string    `json:"origin_ref,omitempty"`
	TaskStatus      string    `json:"task_status,omitempty"`
	RunStatus       string    `json:"run_status,omitempty"`
	SoulSnapshotID  string    `json:"soul_snapshot_id,omitempty"`
	SoulDigest      string    `json:"soul_digest,omitempty"`
	Attempt         int       `json:"attempt,omitempty"`
	LeaseUntil      time.Time `json:"lease_until"`
	ReleaseReason   string    `json:"release_reason,omitempty"`
	Error           string    `json:"error,omitempty"`
}

TaskRunContext carries task-run identifiers shared across task-run hooks.

func (TaskRunContext) HookProfileID

func (c TaskRunContext) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

type TaskRunEnqueuedPayload

type TaskRunEnqueuedPayload struct {
	PayloadBase
	TaskRunContext
	IdempotencyKey string `json:"idempotency_key,omitempty"`
}

TaskRunEnqueuedPayload is delivered after a task run is enqueued and its audit event is committed.

type TaskRunFailedPayload

type TaskRunFailedPayload = TaskRunLeasePayload

TaskRunFailedPayload is delivered after a token-fenced task run failure.

type TaskRunLeaseExpiredPayload

type TaskRunLeaseExpiredPayload = TaskRunLeasePayload

TaskRunLeaseExpiredPayload is delivered after a task-run lease expires.

type TaskRunLeaseExtendedPayload

type TaskRunLeaseExtendedPayload = TaskRunLeasePayload

TaskRunLeaseExtendedPayload is delivered after a task-run lease is extended.

type TaskRunLeasePayload

type TaskRunLeasePayload struct {
	PayloadBase
	TaskRunContext
	PreviousRunStatus string `json:"previous_run_status,omitempty"`
	PreviousSessionID string `json:"previous_session_id,omitempty"`
	RecoveryAction    string `json:"recovery_action,omitempty"`
	RecoveryReason    string `json:"recovery_reason,omitempty"`
}

TaskRunLeasePayload is shared by committed task-run lease lifecycle hooks.

type TaskRunLeaseRecoveredPayload

type TaskRunLeaseRecoveredPayload = TaskRunLeasePayload

TaskRunLeaseRecoveredPayload is delivered after lease recovery commits.

type TaskRunObservationPatch

type TaskRunObservationPatch = AutonomyObservationPatch

TaskRunObservationPatch is the observation patch surface for committed task-run hooks.

type TaskRunPostClaimPayload

type TaskRunPostClaimPayload struct {
	PayloadBase
	TaskRunContext
	ClaimedAt time.Time `json:"claimed_at"`
}

TaskRunPostClaimPayload is delivered after a task run claim and audit event commit.

type TaskRunPreClaimPatch

type TaskRunPreClaimPatch struct {
	ControlPatch
	AddRequiredCapabilities []string `json:"add_required_capabilities,omitempty"`
	PriorityMin             *int     `json:"priority_min,omitempty"`
}

TaskRunPreClaimPatch denies or narrows task-run claim criteria.

type TaskRunPreClaimPayload

type TaskRunPreClaimPayload struct {
	PayloadBase
	*TaskRunContext
	Criteria   TaskRunClaimCriteria `json:"criteria"`
	Denied     bool                 `json:"denied,omitempty"`
	DenyReason string               `json:"deny_reason,omitempty"`
}

TaskRunPreClaimPayload is delivered before a task run claim commits.

type TaskRunReleasedPayload

type TaskRunReleasedPayload = TaskRunLeasePayload

TaskRunReleasedPayload is delivered after a task run lease is released.

type TaskStatusChangedPayload

type TaskStatusChangedPayload struct {
	PayloadBase
	TaskContext
	FromStatus string `json:"from_status"`
	ToStatus   string `json:"to_status"`
}

TaskStatusChangedPayload is delivered after a task status transition is committed.

type TaskUnblockedPayload

type TaskUnblockedPayload = TaskBlockPayload

TaskUnblockedPayload is delivered after a task block clear is committed.

type TelemetrySink

type TelemetrySink interface {
	WriteHookRecord(ctx context.Context, sessionID string, record HookRunRecord) error
}

TelemetrySink persists hook run records when no active writer is attached to the dispatch context.

type TerminalClosedPayload

type TerminalClosedPayload struct {
	PayloadBase
	TerminalContext
	Exit   TerminalExit `json:"exit"`
	Reason string       `json:"reason"`
}

type TerminalCommandFinishedPayload

type TerminalCommandFinishedPayload struct {
	PayloadBase
	TerminalContext
	CommandID  string  `json:"command_id"`
	ExitCode   *int    `json:"exit_code,omitempty"`
	Signal     *string `json:"signal,omitempty"`
	ExitCause  string  `json:"exit_cause"`
	DurationMS int64   `json:"duration_ms"`
	DetectedBy string  `json:"detected_by"`
	Approval   string  `json:"approval"`
}

type TerminalCommandStartedPayload

type TerminalCommandStartedPayload struct {
	PayloadBase
	TerminalContext
	CommandID  string `json:"command_id"`
	Command    string `json:"command"`
	Cwd        string `json:"cwd"`
	DetectedBy string `json:"detected_by"`
}

type TerminalContext

type TerminalContext struct {
	WorkspaceID string    `json:"workspace_id"`
	ProfileID   string    `json:"profile_id"`
	TerminalID  string    `json:"terminal_id,omitempty"`
	ActorKind   string    `json:"actor_kind"`
	ActorID     string    `json:"actor_id"`
	SessionID   string    `json:"session_id,omitempty"`
	RunID       string    `json:"run_id,omitempty"`
	Generation  int64     `json:"generation,omitempty"`
	At          time.Time `json:"at"`
}

TerminalContext carries the mandatory scope, actor, and correlation keys for terminal hooks.

func (TerminalContext) HookProfileID

func (c TerminalContext) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

type TerminalExit

type TerminalExit struct {
	Cause  string  `json:"cause"`
	Code   *int    `json:"code,omitempty"`
	Signal *string `json:"signal,omitempty"`
}

type TerminalInputProvidedPayload

type TerminalInputProvidedPayload struct {
	PayloadBase
	TerminalContext
	RequestID string `json:"request_id"`
	Redacted  bool   `json:"redacted"`
	Length    int    `json:"length"`
	Outcome   string `json:"outcome"`
}

type TerminalInputRequestedPayload

type TerminalInputRequestedPayload struct {
	PayloadBase
	TerminalContext
	RequestID string `json:"request_id"`
	Reason    string `json:"reason"`
	Redacted  bool   `json:"redacted"`
}

type TerminalLimitRejectedPayload

type TerminalLimitRejectedPayload struct {
	PayloadBase
	TerminalContext
	Limit   string `json:"limit"`
	Current int    `json:"current"`
	Max     int    `json:"max"`
}

type TerminalObservationPatch

type TerminalObservationPatch struct{}

type TerminalOpenedPayload

type TerminalOpenedPayload struct {
	PayloadBase
	TerminalContext
	Mode  string `json:"mode"`
	Cwd   string `json:"cwd"`
	Title string `json:"title,omitempty"`
}

type TerminalRecordingStartedPayload

type TerminalRecordingStartedPayload struct {
	PayloadBase
	TerminalContext
	RecordingID string `json:"recording_id"`
}

type TerminalRecordingStoppedPayload

type TerminalRecordingStoppedPayload struct {
	PayloadBase
	TerminalContext
	RecordingID string `json:"recording_id"`
	Digest      string `json:"digest"`
	Bytes       int64  `json:"bytes"`
	Reason      string `json:"reason"`
	Truncated   bool   `json:"truncated"`
}

type TerminalSubscriberEvictedPayload

type TerminalSubscriberEvictedPayload struct {
	PayloadBase
	TerminalContext
	Flow   string `json:"flow"`
	Reason string `json:"reason"`
}

type ToolCallPatch

type ToolCallPatch struct {
	ControlPatch
	ToolID    *string         `json:"tool_id,omitempty"`
	ReadOnly  *bool           `json:"read_only,omitempty"`
	ToolInput json.RawMessage `json:"tool_input,omitempty"`
}

ToolCallPatch mutates or denies tool invocation inputs.

type ToolCallRef

type ToolCallRef struct {
	ToolCallID string `json:"tool_call_id,omitempty"`
	ToolID     string `json:"tool_id,omitempty"`
	ReadOnly   bool   `json:"read_only,omitempty"`
}

ToolCallRef identifies a tool invocation in hook payloads.

type ToolLocation

type ToolLocation struct {
	Path      string `json:"path,omitempty"`
	StartLine int    `json:"start_line,omitempty"`
	EndLine   int    `json:"end_line,omitempty"`
}

ToolLocation captures one path-scoped tool location.

type ToolPostCallPayload

type ToolPostCallPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	ToolCallRef
	Title      string          `json:"title,omitempty"`
	ToolInput  json.RawMessage `json:"tool_input,omitempty"`
	ToolResult json.RawMessage `json:"tool_result,omitempty"`
}

ToolPostCallPayload is delivered after a tool completes successfully.

type ToolPostErrorPatch

type ToolPostErrorPatch = ToolResultPatch

ToolPostErrorPatch is the post-error patch surface.

type ToolPostErrorPayload

type ToolPostErrorPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	ToolCallRef
	Title     string          `json:"title,omitempty"`
	ToolInput json.RawMessage `json:"tool_input,omitempty"`
	Error     string          `json:"error,omitempty"`
}

ToolPostErrorPayload is delivered after a tool fails.

type ToolPreCallPayload

type ToolPreCallPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	ToolCallRef
	ToolInput json.RawMessage `json:"tool_input,omitempty"`
}

ToolPreCallPayload is delivered before a tool runs.

type ToolResultPatch

type ToolResultPatch struct {
	ControlPatch
	Title      *string         `json:"title,omitempty"`
	ToolResult json.RawMessage `json:"tool_result,omitempty"`
	Error      *string         `json:"error,omitempty"`
}

ToolResultPatch mutates or denies tool outputs.

type TurnContext

type TurnContext struct {
	TurnID string `json:"turn_id,omitempty"`
}

TurnContext carries the current turn identifier.

type TurnEndPatch

type TurnEndPatch = TurnPatch

TurnEndPatch is the turn-end patch surface.

type TurnEndPayload

type TurnEndPayload = TurnPayload

TurnEndPayload is delivered at turn end.

type TurnPatch

type TurnPatch struct {
	ControlPatch
	Labels map[string]string `json:"labels,omitempty"`
}

TurnPatch mutates or denies turn-scoped operations.

type TurnPayload

type TurnPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	InputClass  string `json:"input_class,omitempty"`
	UserMessage string `json:"user_message,omitempty"`
}

TurnPayload is shared by turn start and end events.

type TurnStartPatch

type TurnStartPatch = TurnPatch

TurnStartPatch is the turn-start patch surface.

type TurnStartPayload

type TurnStartPayload = TurnPayload

TurnStartPayload is delivered at turn start.

type TypedNativeExecutor

type TypedNativeExecutor[P any, R any] struct {
	// contains filtered or unexported fields
}

TypedNativeExecutor runs hooks as direct Go callbacks on typed payloads.

func NewTypedNativeExecutor

func NewTypedNativeExecutor[P any, R any](callback TypedNativeHookFunc[P, R]) *TypedNativeExecutor[P, R]

NewTypedNativeExecutor constructs a typed native executor for pipeline use.

func (*TypedNativeExecutor[P, R]) Execute

func (e *TypedNativeExecutor[P, R]) Execute(_ context.Context, hook RegisteredHook, _ []byte) ([]byte, error)

Execute preserves the Executor contract but the typed native path is expected to be invoked through pipeline.execute.

func (*TypedNativeExecutor[P, R]) ExecuteTyped

func (e *TypedNativeExecutor[P, R]) ExecuteTyped(
	ctx context.Context,
	hook RegisteredHook,
	payload P,
) (result R, err error)

ExecuteTyped invokes the configured typed Go callback directly.

func (*TypedNativeExecutor[P, R]) Kind

func (*TypedNativeExecutor[P, R]) Kind() HookExecutorKind

Kind returns the executor type.

type TypedNativeHookFunc

type TypedNativeHookFunc[P any, R any] func(ctx context.Context, hook RegisteredHook, payload P) (R, error)

TypedNativeHookFunc executes a typed in-process hook without crossing a serialization boundary.

type WasmExecutor

type WasmExecutor struct{}

WasmExecutor is the future execution seam for sandboxed hook runtimes.

func (*WasmExecutor) Execute

func (*WasmExecutor) Execute(_ context.Context, _ RegisteredHook, _ []byte) ([]byte, error)

Execute reports that the Wasm executor seam is not implemented yet.

func (*WasmExecutor) Kind

Kind returns the executor type.

type WindowManagerActor

type WindowManagerActor struct {
	Kind string `json:"kind,omitempty"`
	ID   string `json:"id,omitempty"`
}

WindowManagerActor identifies the command initiator.

type WindowManagerChanges

type WindowManagerChanges struct {
	DesktopIDs     []string `json:"desktop_ids,omitempty"`
	WindowIDs      []string `json:"window_ids,omitempty"`
	GroupIDs       []string `json:"group_ids,omitempty"`
	NodeIDs        []string `json:"node_ids,omitempty"`
	ClientIDs      []string `json:"client_ids,omitempty"`
	StackGrouped   []string `json:"stack_grouped,omitempty"`
	StackUngrouped []string `json:"stack_ungrouped,omitempty"`
}

WindowManagerChanges identifies entities changed by one committed command.

type WindowManagerDesktopCreatedPayload

type WindowManagerDesktopCreatedPayload = WindowManagerPayload

WindowManagerDesktopCreatedPayload observes a committed desktop creation.

type WindowManagerDesktopDeletedPayload

type WindowManagerDesktopDeletedPayload = WindowManagerPayload

WindowManagerDesktopDeletedPayload observes a committed desktop deletion.

type WindowManagerLayoutAppliedPayload

type WindowManagerLayoutAppliedPayload = WindowManagerPayload

WindowManagerLayoutAppliedPayload observes a committed layout application.

type WindowManagerObservationPatch

type WindowManagerObservationPatch struct{}

WindowManagerObservationPatch is the no-op patch surface for durable observations.

type WindowManagerPayload

type WindowManagerPayload struct {
	PayloadBase
	WorkspaceID string               `json:"workspace_id"`
	Revision    uint64               `json:"revision"`
	CommandID   string               `json:"command_id"`
	Changes     WindowManagerChanges `json:"changes"`
	Actor       WindowManagerActor   `json:"actor"`
	Origin      string               `json:"origin,omitempty"`
}

WindowManagerPayload observes one durable topology mutation.

type WindowManagerStackActivatedPayload

type WindowManagerStackActivatedPayload = WindowManagerPayload

WindowManagerStackActivatedPayload observes one durable stack activation.

type WindowManagerStackGroupedPayload

type WindowManagerStackGroupedPayload = WindowManagerPayload

WindowManagerStackGroupedPayload observes stack membership grouped in one revision.

type WindowManagerStackUngroupedPayload

type WindowManagerStackUngroupedPayload = WindowManagerPayload

WindowManagerStackUngroupedPayload observes stacks dissolved in one revision.

type WindowManagerWindowClosedPayload

type WindowManagerWindowClosedPayload = WindowManagerPayload

WindowManagerWindowClosedPayload observes every window removed by one close operation.

type WindowManagerWindowMovedPayload

type WindowManagerWindowMovedPayload = WindowManagerPayload

WindowManagerWindowMovedPayload observes a committed window move.

type WindowManagerWindowOpenedPayload

type WindowManagerWindowOpenedPayload = WindowManagerPayload

WindowManagerWindowOpenedPayload observes windows added by open or reopen.

type WorktreeContext

type WorktreeContext struct {
	ProfileID     string `json:"profile_id,omitempty"`
	WorktreeID    string `json:"worktree_id"`
	WorkspaceID   string `json:"workspace_id"`
	WorkspaceRoot string `json:"workspace_root,omitempty"`
	Name          string `json:"name"`
	Branch        string `json:"branch"`
	Path          string `json:"path"`
	Origin        string `json:"origin"`
	RunID         string `json:"run_id,omitempty"`
}

func (WorktreeContext) HookProfileID

func (c WorktreeContext) HookProfileID() string

HookProfileID returns the durable owner used to isolate profile-scoped declarations.

type WorktreeControlPatch

type WorktreeControlPatch struct {
	ControlPatch
}

type WorktreeObservationPatch

type WorktreeObservationPatch struct{}

type WorktreeObservationPayload

type WorktreeObservationPayload struct {
	PayloadBase
	WorktreeContext
}

type WorktreePreCreatePayload

type WorktreePreCreatePayload struct {
	PayloadBase
	WorktreeContext
	Denied     bool   `json:"denied,omitempty"`
	DenyReason string `json:"deny_reason,omitempty"`
}

type WorktreePreRemovePayload

type WorktreePreRemovePayload struct {
	PayloadBase
	Worktree   WorktreeContext `json:"worktree"`
	Force      bool            `json:"force"`
	Risk       WorktreeRisk    `json:"risk"`
	Denied     bool            `json:"denied,omitempty"`
	DenyReason string          `json:"deny_reason,omitempty"`
}

type WorktreeRisk

type WorktreeRisk struct {
	ChangedFiles    int  `json:"changed_files"`
	Insertions      int  `json:"insertions"`
	Deletions       int  `json:"deletions"`
	UnpushedCommits int  `json:"unpushed_commits"`
	ExistsOnRemote  bool `json:"exists_on_remote"`
}

Source Files

Jump to

Keyboard shortcuts

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