Documentation
¶
Overview ¶
Package hooks owns the Pips-native Coding lifecycle hook configuration, trust records, and reviewed command protocol.
Index ¶
Constants ¶
const ( // Schema identifies the strict lifecycle hook configuration format. Schema = "pips.coding.hooks/v1alpha1" // InputSchema identifies the JSON object written to one hook command stdin. InputSchema = "pips.coding.hook-input/v1alpha1" // TrustSchema identifies the Pips-owned hook trust store format. TrustSchema = "pips.coding.hook-trust/v1alpha1" )
Variables ¶
var ( // ErrInvalid reports malformed hook configuration, protocol data, or options. ErrInvalid = errors.New("coding hooks: invalid") // ErrLimitExceeded reports one configured or runtime hook bound being exceeded. ErrLimitExceeded = errors.New("coding hooks: limit exceeded") // ErrUnsafeFile reports a hook configuration or trust file that cannot be trusted. ErrUnsafeFile = errors.New("coding hooks: unsafe file") // ErrUntrusted reports an attempted project action before workspace trust. ErrUntrusted = errors.New("coding hooks: workspace is not trusted") )
Functions ¶
This section is empty.
Types ¶
type Definition ¶
type Definition struct {
ID string
Reference string
Scope Scope
Source string
Visibility Visibility
Event Event
Matcher string
Command string
Timeout time.Duration
// contains filtered or unexported fields
}
Definition is one immutable, validated command handler.
func (Definition) EffectiveVisibility ¶
func (d Definition) EffectiveVisibility() Visibility
EffectiveVisibility normalizes the zero value to the legacy ambient policy.
func (Definition) Fingerprint ¶
func (d Definition) Fingerprint() string
Fingerprint returns the normalized semantic SHA-256 identity of Definition.
type Definitions ¶
type Definitions struct {
// contains filtered or unexported fields
}
Definitions is an immutable validated handler snapshot.
func Load ¶
func Load(ctx context.Context, options LoadOptions) (Definitions, error)
Load reads strict user and trusted-project lifecycle hook definitions. An untrusted project hook file is never inspected.
func (Definitions) List ¶
func (d Definitions) List() []Definition
List returns a defensive copy in source/event/group/handler order.
func (Definitions) Matching ¶
func (d Definitions) Matching(event Event, target string) []Definition
Matching returns definitions that match one event and event target.
type Diagnostic ¶
Diagnostic describes a non-fatal lifecycle hook suppression or command failure.
type Event ¶
type Event string
Event identifies one supported Coding lifecycle boundary.
const ( EventSessionStart Event = "SessionStart" EventUserPromptSubmit Event = "UserPromptSubmit" EventPreToolUse Event = "PreToolUse" EventPermissionRequest Event = "PermissionRequest" EventPostToolUse Event = "PostToolUse" EventPreCompact Event = "PreCompact" EventPostCompact Event = "PostCompact" EventSubagentStart Event = "SubagentStart" EventSubagentStop Event = "SubagentStop" EventStop Event = "Stop" EventSessionEnd Event = "SessionEnd" )
Supported lifecycle events.
type Invocation ¶
Invocation supplies one JSON payload to matching trusted command handlers.
type Limits ¶
type Limits struct {
MaxFileBytes int64
MaxHandlers int
MaxCommand int
MaxMatcher int
MaxInputBytes int
MaxOutputBytes int
MaxErrorBytes int
MaxContext int
MaxReason int
}
Limits bound untrusted hook configuration and trusted command protocol data.
func DefaultLimits ¶
func DefaultLimits() Limits
DefaultLimits returns the fixed V1 lifecycle hook bounds.
type LoadOptions ¶
type LoadOptions struct {
Paths paths.Layout
Tree *workspace.Tree
ProjectTrusted bool
Limits Limits
}
LoadOptions select user and optional trusted-project lifecycle hook files.
type Outcome ¶
type Outcome struct {
// Blocked is the event-specific Codex-style block decision. Runtime glue
// maps it to prompt/tool denial, tool feedback, or a continuation request.
Blocked bool
// Allowed is meaningful to PermissionRequest and PreToolUse. It never
// bypasses subsequent Pips policy, approval, or sandbox checks.
Allowed bool
// Stopped records a continue:false response. It takes precedence over a
// continuation request for events that support continuation control.
Stopped bool
Reason string
Context []string
// UpdatedInput is a validated replacement JSON arguments object for an
// allowed PreToolUse invocation.
UpdatedInput json.RawMessage
Diagnostics []Diagnostic
}
Outcome is the merged result of one hook invocation.
type ResolvedDefinition ¶
type ResolvedDefinition struct {
Definition Definition
Status Status
}
ResolvedDefinition attaches the effective local trust state.
type Runner ¶
Runner executes already-trusted command definitions for one Coding Runtime. It intentionally runs outside the model-tool sandbox: the command string is user-reviewed hook configuration, and model-controlled values reach it only through the JSON stdin payload.
func (Runner) Invoke ¶
func (r Runner) Invoke( ctx context.Context, definitions []Definition, invocation Invocation, ) (Outcome, error)
Invoke executes every matching trusted command concurrently and merges their event-scoped responses in Definition order.
type TrustStore ¶
type TrustStore struct {
// contains filtered or unexported fields
}
TrustStore records Pips-owned exact command-handler approvals outside a project-controlled hooks.json file.
func NewTrustStore ¶
func NewTrustStore(path string) *TrustStore
NewTrustStore returns a hook trust store backed by path.
func (*TrustStore) Path ¶
func (s *TrustStore) Path() string
Path returns the backing trust store path.
func (*TrustStore) Resolve ¶
func (s *TrustStore) Resolve( ctx context.Context, definitions Definitions, workspaceID string, ) ([]ResolvedDefinition, error)
Resolve attaches the effective trust status to each definition. workspaceID is required only for project definitions and must be the current filesystem identity key, not a user-controlled path.
func (*TrustStore) Trust ¶
func (s *TrustStore) Trust( ctx context.Context, definition Definition, workspaceID string, ) error
Trust records approval for Definition's current semantic fingerprint.
type Visibility ¶
type Visibility string
Visibility controls whether a trusted definition is mandatory ambient policy or can only be added to one exact custom child plan.
const ( // VisibilityAmbient makes a Hook mandatory ambient policy. VisibilityAmbient Visibility = "ambient" // VisibilityAgentPrivate makes a Hook selectable by exact custom child ID. VisibilityAgentPrivate Visibility = "agent_private" )
Source Files