hooks

package
v0.0.7 Latest Latest
Warning

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

 Go to latest Published: Jun 4, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package hooks defines the dependency-free core types for the AGH 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 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 is the no-op patch surface for authored-context observation hooks.

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 {
	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.

type AutomationJobPreFirePayload 

type AutomationJobPreFirePayload struct {
	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.

type AutomationObservationPatch 

type AutomationObservationPatch struct{}

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

type AutomationRunCompletedPayload 

type AutomationRunCompletedPayload struct {
	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.

type AutomationRunFailedPayload 

type AutomationRunFailedPayload struct {
	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.

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 {
	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.

type AutomationTriggerPreFirePayload 

type AutomationTriggerPreFirePayload struct {
	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.

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"`
	WorkflowID            string `json:"workflow_id,omitempty"             yaml:"workflow_id,omitempty"`
	CoordinationChannelID string `json:"coordination_channel_id,omitempty" yaml:"coordination_channel_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 {
	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 {
	Reason   string `json:"compaction_reason,omitempty"   yaml:"compaction_reason,omitempty"`
	Strategy string `json:"compaction_strategy,omitempty" yaml:"compaction_strategy,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 ContextCompactPayload 

type ContextCompactPayload struct {
	PayloadBase
	SessionContext
	TurnContext
	Reason        string         `json:"reason,omitempty"`
	Strategy      string         `json:"strategy,omitempty"`
	Summary       string         `json:"summary,omitempty"`
	ContextBlocks []ContextBlock `json:"context_blocks,omitempty"`
}

ContextCompactPayload is shared by context compaction hooks.

type ContextCompactionPatch 

type ContextCompactionPatch struct {
	ControlPatch
	Reason        *string        `json:"reason,omitempty"`
	Strategy      *string        `json:"strategy,omitempty"`
	ContextBlocks []ContextBlock `json:"context_blocks,omitempty"`
}

ContextCompactionPatch mutates or denies compaction behavior.

type ContextPostCompactPatch 

type ContextPostCompactPatch = ContextCompactionPatch

ContextPostCompactPatch is the post-compact patch surface.

type ContextPostCompactPayload 

type ContextPostCompactPayload = ContextCompactPayload

ContextPostCompactPayload is delivered after compaction.

type ContextPreCompactPatch 

type ContextPreCompactPatch = ContextCompactionPatch

ContextPreCompactPatch is the pre-compact patch surface.

type ContextPreCompactPayload 

type ContextPreCompactPayload = ContextCompactPayload

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 {
	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"`
	CoordinationChannelID string `json:"coordination_channel_id,omitempty"`
	Provider              string `json:"provider,omitempty"`
	Model                 string `json:"model,omitempty"`
}

CoordinatorContext carries the coordinator identifiers shared across coordinator hooks.

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 DispatchCorrelation 

type DispatchCorrelation struct {
	TaskID               string
	RunID                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"`
	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"`
	SkillSource  HookSkillSource   `json:"-"                       yaml:"-"`
	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"`
	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) EnabledValue 

func (d HookDecl) EnabledValue() bool

EnabledValue reports whether a declaration participates in dispatch.

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"

	HookSandboxPrepare    HookEvent = "sandbox.prepare"
	HookSandboxReady      HookEvent = "sandbox.ready"
	HookSandboxSyncBefore HookEvent = "sandbox.sync.before"
	HookSandboxSyncAfter  HookEvent = "sandbox.sync.after"
	HookSandboxStop       HookEvent = "sandbox.stop"

	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"

	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"

	HookSpawnPreCreate     HookEvent = "spawn.pre_create"
	HookSpawnCreated       HookEvent = "spawn.created"
	HookSpawnParentStopped HookEvent = "spawn.parent_stopped"
	HookSpawnTTLExpired    HookEvent = "spawn.ttl_expired"
	HookSpawnReaped        HookEvent = "spawn.reaped"

	HookNetworkThreadOpened     HookEvent = "network.thread.opened"
	HookNetworkDirectRoomOpened HookEvent = "network.direct_room.opened"
	HookNetworkMessagePersisted HookEvent = "network.message.persisted"
	HookNetworkWorkOpened       HookEvent = "network.work.opened"
	HookNetworkWorkTransitioned HookEvent = "network.work.transitioned"
	HookNetworkWorkClosed       HookEvent = "network.work.closed"
	HookNetworkPeerJoined       HookEvent = "network.peer.joined"
	HookNetworkPeerLeft         HookEvent = "network.peer.left"
)

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"
	HookEventFamilySandbox     HookEventFamily = "sandbox"
	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"
	HookEventFamilyTaskRun     HookEventFamily = "task.run"
	HookEventFamilySpawn       HookEventFamily = "spawn"
	HookEventFamilyNetwork     HookEventFamily = "network"
)

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"`
	WorkspaceRoot      string `json:"workspace_root,omitempty"     yaml:"workspace_root,omitempty"`
	SessionType        string `json:"session_type,omitempty"       yaml:"session_type,omitempty"`
	SandboxID          string `json:"sandbox_id,omitempty"         yaml:"sandbox_id,omitempty"`
	SandboxBackend     string `json:"sandbox_backend,omitempty"    yaml:"sandbox_backend,omitempty"`
	SandboxProfile     string `json:"sandbox_profile,omitempty"    yaml:"sandbox_profile,omitempty"`
	SyncDirection      string `json:"sync_direction,omitempty"     yaml:"sync_direction,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"`
	*NetworkMatcher    `                                                     yaml:",inline,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 ContextCompactPayload) 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) MatchesMessage 

func (m HookMatcher) MatchesMessage(payload MessagePayload) bool

MatchesMessage matches message-family hooks.

func (HookMatcher) MatchesNetwork 

func (m HookMatcher) MatchesNetwork(payload NetworkPayload) bool

MatchesNetwork matches network-family observation hooks.

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) MatchesSandboxPrepare 

func (m HookMatcher) MatchesSandboxPrepare(payload SandboxPreparePayload) bool

MatchesSandboxPrepare matches sandbox prepare hooks.

func (HookMatcher) MatchesSandboxReady 

func (m HookMatcher) MatchesSandboxReady(payload SandboxReadyPayload) bool

MatchesSandboxReady matches sandbox ready hooks.

func (HookMatcher) MatchesSandboxStop 

func (m HookMatcher) MatchesSandboxStop(payload SandboxStopPayload) bool

MatchesSandboxStop matches sandbox stop hooks.

func (HookMatcher) MatchesSandboxSyncAfter 

func (m HookMatcher) MatchesSandboxSyncAfter(payload SandboxSyncAfterPayload) bool

MatchesSandboxSyncAfter matches sandbox post-sync hooks.

func (HookMatcher) MatchesSandboxSyncBefore 

func (m HookMatcher) MatchesSandboxSyncBefore(payload SandboxSyncBeforePayload) bool

MatchesSandboxSyncBefore matches sandbox pre-sync 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) 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.

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 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,omitempty"`
	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 string

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

const (
	HookSkillSourceBundled     HookSkillSource = "bundled"
	HookSkillSourceMarketplace HookSkillSource = "marketplace"
	HookSkillSourceUser        HookSkillSource = "user"
	HookSkillSourceAdditional  HookSkillSource = "additional"
	HookSkillSourceWorkspace   HookSkillSource = "workspace"
)

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
)

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) 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) DispatchNetworkDirectRoomOpened 

func (h *Hooks) DispatchNetworkDirectRoomOpened(
	ctx context.Context,
	payload NetworkDirectRoomOpenedPayload,
) (NetworkDirectRoomOpenedPayload, error)

DispatchNetworkDirectRoomOpened runs the network.direct_room.opened hook dispatch.

func (*Hooks) DispatchNetworkMessagePersisted 

func (h *Hooks) DispatchNetworkMessagePersisted(
	ctx context.Context,
	payload NetworkMessagePersistedPayload,
) (NetworkMessagePersistedPayload, error)

DispatchNetworkMessagePersisted runs the network.message.persisted hook dispatch.

func (*Hooks) DispatchNetworkPeerJoined 

func (h *Hooks) DispatchNetworkPeerJoined(
	ctx context.Context,
	payload NetworkPeerJoinedPayload,
) (NetworkPeerJoinedPayload, error)

DispatchNetworkPeerJoined runs the network.peer.joined hook dispatch.

func (*Hooks) DispatchNetworkPeerLeft 

func (h *Hooks) DispatchNetworkPeerLeft(
	ctx context.Context,
	payload NetworkPeerLeftPayload,
) (NetworkPeerLeftPayload, error)

DispatchNetworkPeerLeft runs the network.peer.left hook dispatch.

func (*Hooks) DispatchNetworkThreadOpened 

func (h *Hooks) DispatchNetworkThreadOpened(
	ctx context.Context,
	payload NetworkThreadOpenedPayload,
) (NetworkThreadOpenedPayload, error)

DispatchNetworkThreadOpened runs the network.thread.opened hook dispatch.

func (*Hooks) DispatchNetworkWorkClosed 

func (h *Hooks) DispatchNetworkWorkClosed(
	ctx context.Context,
	payload NetworkWorkClosedPayload,
) (NetworkWorkClosedPayload, error)

DispatchNetworkWorkClosed runs the network.work.closed hook dispatch.

func (*Hooks) DispatchNetworkWorkOpened 

func (h *Hooks) DispatchNetworkWorkOpened(
	ctx context.Context,
	payload NetworkWorkOpenedPayload,
) (NetworkWorkOpenedPayload, error)

DispatchNetworkWorkOpened runs the network.work.opened hook dispatch.

func (*Hooks) DispatchNetworkWorkTransitioned 

func (h *Hooks) DispatchNetworkWorkTransitioned(
	ctx context.Context,
	payload NetworkWorkTransitionedPayload,
) (NetworkWorkTransitionedPayload, error)

DispatchNetworkWorkTransitioned runs the network.work.transitioned hook dispatch.

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) DispatchSandboxPrepare 

func (h *Hooks) DispatchSandboxPrepare(
	ctx context.Context,
	payload SandboxPreparePayload,
) (SandboxPreparePayload, error)

DispatchSandboxPrepare runs the sandbox.prepare hook pipeline.

func (*Hooks) DispatchSandboxReady 

func (h *Hooks) DispatchSandboxReady(
	ctx context.Context,
	payload SandboxReadyPayload,
) (SandboxReadyPayload, error)

DispatchSandboxReady runs the sandbox.ready hook dispatch.

func (*Hooks) DispatchSandboxStop 

func (h *Hooks) DispatchSandboxStop(
	ctx context.Context,
	payload SandboxStopPayload,
) (SandboxStopPayload, error)

DispatchSandboxStop runs the sandbox.stop hook pipeline.

func (*Hooks) DispatchSandboxSyncAfter 

func (h *Hooks) DispatchSandboxSyncAfter(
	ctx context.Context,
	payload SandboxSyncAfterPayload,
) (SandboxSyncAfterPayload, error)

DispatchSandboxSyncAfter runs the sandbox.sync.after hook dispatch.

func (*Hooks) DispatchSandboxSyncBefore 

func (h *Hooks) DispatchSandboxSyncBefore(
	ctx context.Context,
	payload SandboxSyncBeforePayload,
) (SandboxSyncBeforePayload, error)

DispatchSandboxSyncBefore runs the sandbox.sync.before hook pipeline.

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) 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) 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) 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) 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 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"`
}

InputPreSubmitPayload is delivered before prompt submission.

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 

func (*NativeExecutor) Kind() HookExecutorKind

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 NetworkDirectRoomOpenedPayload 

type NetworkDirectRoomOpenedPayload = NetworkPayload

NetworkDirectRoomOpenedPayload observes a newly opened direct room.

type NetworkMatcher 

type NetworkMatcher struct {
	Channel   string `json:"channel,omitempty"    yaml:"channel,omitempty"`
	Surface   string `json:"surface,omitempty"    yaml:"surface,omitempty"`
	Kind      string `json:"kind,omitempty"       yaml:"kind,omitempty"`
	Direction string `json:"direction,omitempty"  yaml:"direction,omitempty"`
	WorkState string `json:"work_state,omitempty" yaml:"work_state,omitempty"`
}

NetworkMatcher narrows network observation hooks by low-cardinality fields.

type NetworkMessagePersistedPayload 

type NetworkMessagePersistedPayload = NetworkPayload

NetworkMessagePersistedPayload observes a committed conversation message.

type NetworkObservationPatch 

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

NetworkObservationPatch captures optional labels for network observation hooks.

type NetworkPayload 

type NetworkPayload struct {
	PayloadBase
	WorkspaceID string     `json:"workspace_id,omitempty"`
	SessionID   string     `json:"session_id,omitempty"`
	Channel     string     `json:"channel,omitempty"`
	Surface     string     `json:"surface,omitempty"`
	ThreadID    string     `json:"thread_id,omitempty"`
	DirectID    string     `json:"direct_id,omitempty"`
	MessageID   string     `json:"message_id,omitempty"`
	Kind        string     `json:"kind,omitempty"`
	Direction   string     `json:"direction,omitempty"`
	WorkID      string     `json:"work_id,omitempty"`
	WorkState   string     `json:"work_state,omitempty"`
	PeerID      string     `json:"peer_id,omitempty"`
	PeerFrom    string     `json:"peer_from,omitempty"`
	PeerTo      string     `json:"peer_to,omitempty"`
	LastSeenAt  *time.Time `json:"last_seen_at,omitempty"`
	TraceID     string     `json:"trace_id,omitempty"`
	CausationID string     `json:"causation_id,omitempty"`
}

NetworkPayload is the shared observation payload for committed network conversation writes.

type NetworkPeerJoinedPayload 

type NetworkPeerJoinedPayload = NetworkPayload

NetworkPeerJoinedPayload observes a peer becoming visible on a runtime channel.

type NetworkPeerLeftPayload 

type NetworkPeerLeftPayload = NetworkPayload

NetworkPeerLeftPayload observes a peer leaving or expiring from a runtime channel.

type NetworkThreadOpenedPayload 

type NetworkThreadOpenedPayload = NetworkPayload

NetworkThreadOpenedPayload observes a newly opened public thread.

type NetworkWorkClosedPayload 

type NetworkWorkClosedPayload = NetworkPayload

NetworkWorkClosedPayload observes a terminal work lifecycle transition.

type NetworkWorkOpenedPayload 

type NetworkWorkOpenedPayload = NetworkPayload

NetworkWorkOpenedPayload observes a newly opened work item.

type NetworkWorkTransitionedPayload 

type NetworkWorkTransitionedPayload = NetworkPayload

NetworkWorkTransitionedPayload observes a work lifecycle transition.

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 = PermissionResolutionPayload

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"`
	NetworkChannels []string `json:"network_channels,omitempty"`
	SandboxProfiles []string `json:"sandbox_profiles,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
	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 SandboxObservationPatch 

type SandboxObservationPatch struct{}

SandboxObservationPatch is the no-op patch surface for sandbox observation hooks.

type SandboxPreparePatch 

type SandboxPreparePatch struct {
	ControlPatch
	EnvOverrides map[string]string `json:"env_overrides,omitempty"`
}

SandboxPreparePatch mutates or denies sandbox preparation.

type SandboxPreparePayload 

type SandboxPreparePayload struct {
	PayloadBase
	SessionContext
	SandboxID           string                `json:"sandbox_id,omitempty"`
	Backend             string                `json:"backend,omitempty"`
	Profile             SandboxProfilePayload `json:"profile"`
	LocalRootDir        string                `json:"local_root,omitempty"`
	LocalAdditionalDirs []string              `json:"local_additional_dirs,omitempty"`
	AgentCommand        string                `json:"agent_command,omitempty"`
	AgentEnv            []string              `json:"agent_env,omitempty"`
	Permissions         string                `json:"permissions,omitempty"`
	ResumeACPState      string                `json:"resume_acp_state,omitempty"`
	EnvOverrides        map[string]string     `json:"env_overrides,omitempty"`
	Denied              bool                  `json:"denied,omitempty"`
	DenyReason          string                `json:"deny_reason,omitempty"`
}

SandboxPreparePayload is delivered before a session sandbox is prepared.

type SandboxProfilePayload 

type SandboxProfilePayload struct {
	Profile        string            `json:"profile,omitempty"`
	Backend        string            `json:"backend,omitempty"`
	SyncMode       string            `json:"sync_mode,omitempty"`
	Persistence    string            `json:"persistence,omitempty"`
	RuntimeRootDir string            `json:"runtime_root,omitempty"`
	DestroyOnStop  bool              `json:"destroy_on_stop,omitempty"`
	Env            map[string]string `json:"env,omitempty"`
	SecretEnv      map[string]string `json:"secret_env,omitempty"`
}

SandboxProfilePayload is the sandbox profile snapshot exposed to sandbox hooks.

type SandboxReadyPatch 

type SandboxReadyPatch = SandboxObservationPatch

SandboxReadyPatch is the ready patch surface.

type SandboxReadyPayload 

type SandboxReadyPayload struct {
	PayloadBase
	SessionContext
	SandboxID             string   `json:"sandbox_id,omitempty"`
	Backend               string   `json:"backend,omitempty"`
	Profile               string   `json:"profile,omitempty"`
	InstanceID            string   `json:"instance_id,omitempty"`
	RuntimeRootDir        string   `json:"runtime_root,omitempty"`
	RuntimeAdditionalDirs []string `json:"runtime_additional_dirs,omitempty"`
}

SandboxReadyPayload is delivered after a sandbox has been prepared and synchronized.

type SandboxStopPatch 

type SandboxStopPatch struct {
	ControlPatch
}

SandboxStopPatch mutates or denies sandbox teardown.

type SandboxStopPayload 

type SandboxStopPayload struct {
	PayloadBase
	SessionContext
	SandboxID      string `json:"sandbox_id,omitempty"`
	Backend        string `json:"backend,omitempty"`
	Profile        string `json:"profile,omitempty"`
	InstanceID     string `json:"instance_id,omitempty"`
	RuntimeRootDir string `json:"runtime_root,omitempty"`
	StopReason     string `json:"stop_reason,omitempty"`
	WillDestroy    bool   `json:"will_destroy,omitempty"`
	Denied         bool   `json:"denied,omitempty"`
	DenyReason     string `json:"deny_reason,omitempty"`
}

SandboxStopPayload is delivered before sandbox teardown.

type SandboxSyncAfterPatch 

type SandboxSyncAfterPatch = SandboxObservationPatch

SandboxSyncAfterPatch is the sync-after patch surface.

type SandboxSyncAfterPayload 

type SandboxSyncAfterPayload struct {
	PayloadBase
	SessionContext
	SandboxID        string   `json:"sandbox_id,omitempty"`
	Backend          string   `json:"backend,omitempty"`
	Profile          string   `json:"profile,omitempty"`
	InstanceID       string   `json:"instance_id,omitempty"`
	RuntimeRootDir   string   `json:"runtime_root,omitempty"`
	Direction        string   `json:"direction,omitempty"`
	Reason           string   `json:"reason,omitempty"`
	FilesSynced      int      `json:"files_synced,omitempty"`
	BytesTransferred int64    `json:"bytes_transferred,omitempty"`
	DurationMS       int64    `json:"duration_ms,omitempty"`
	Errors           []string `json:"errors,omitempty"`
}

SandboxSyncAfterPayload is delivered after a sandbox sync operation finishes.

type SandboxSyncBeforePatch 

type SandboxSyncBeforePatch struct {
	ControlPatch
	ExcludePatterns []string `json:"exclude_patterns,omitempty"`
}

SandboxSyncBeforePatch mutates or denies sandbox sync.

type SandboxSyncBeforePayload 

type SandboxSyncBeforePayload struct {
	PayloadBase
	SessionContext
	SandboxID       string   `json:"sandbox_id,omitempty"`
	Backend         string   `json:"backend,omitempty"`
	Profile         string   `json:"profile,omitempty"`
	InstanceID      string   `json:"instance_id,omitempty"`
	RuntimeRootDir  string   `json:"runtime_root,omitempty"`
	Direction       string   `json:"direction,omitempty"`
	Reason          string   `json:"reason,omitempty"`
	FileCount       int      `json:"file_count,omitempty"`
	ExcludePatterns []string `json:"exclude_patterns,omitempty"`
	Denied          bool     `json:"denied,omitempty"`
	DenyReason      string   `json:"deny_reason,omitempty"`
}

SandboxSyncBeforePayload is delivered before a sandbox sync operation runs.

type SecretRefResolver 

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

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

type SessionContext 

type SessionContext struct {
	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"`
	ACPSessionID string `json:"acp_session_id,omitempty"`
	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.

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 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 {
	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"`
	CoordinationChannelID string `json:"coordination_channel_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.

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 {
	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 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 

func (*SubprocessExecutor) Kind() HookExecutorKind

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 WithSubprocessSecretEnv 

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

WithSubprocessSecretEnv configures secret refs resolved immediately before a hook runs.

type TaskRunClaimCriteria 

type TaskRunClaimCriteria struct {
	WorkspaceID           string   `json:"workspace_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"`
	CoordinationChannelID string   `json:"coordination_channel_id,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 {
	TaskID                string    `json:"task_id,omitempty"`
	RunID                 string    `json:"run_id,omitempty"`
	WorkspaceID           string    `json:"workspace_id,omitempty"`
	WorkflowID            string    `json:"workflow_id,omitempty"`
	CoordinationChannelID string    `json:"coordination_channel_id,omitempty"`
	NetworkChannel        string    `json:"network_channel,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.

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 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 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 

func (*WasmExecutor) Kind() HookExecutorKind

Kind returns the executor type.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.