Module hooks 

Hook system: extension points for the agent main loop.

Abstraction layers

• HookStep: interception points called by the main loop at step boundaries (bucketed by event name)
• StepHandler: a single executor (implemented in submodules as Builtin / Command / Prompt)
• HookMatcher: matching conditions for a single hook (filtering by tool / glob / safety)
• HookEngine: the dispatcher the main loop interacts with; holds a HandlerTable, executes the pipeline, and merges verdicts

Default implementations

NoopHookEngine: all fire calls return Pass directly, observe calls are discarded; used when no explicit hook engine is provided during session/turn assembly, preserving “no hook configured = main loop behavior unchanged”.

DefaultHookEngine: holds the handler table via arc_swap::ArcSwap, dispatches serially according to the pipeline semantics; matcher, timeout, and panic capture are handled per the degradation table.

Modules

builtin

Builtin hook handlers.

command

Command hook handler — feeds the step envelope JSON to an external subprocess. The IO protocol passes stdout through as verdict JSON.

prompt

Prompt hook handler — feeds a step envelope into a single LLM call.

step

Hook step-context: typestate + envelope.

Structs

DefaultHookEngine

Default hook engine: serial dispatch following the pipeline semantics.

HandlerTable

A handler table bucketed by step event_name.

HookCtx

A lightweight context shared with the handler.

HookMatcher

Matching conditions for a single hook.

NoopHookEngine

Default hook engine: dispatch uses the trait’s default implementation (Proceed, i.e., no-op).

StepHandlerEntry

A fully assembled step handler: name, matcher, handler, and per-entry timeout.

Enums

HookError

Reasons for handler failure.

Constants

ANONYMOUS_HOOK_NAME

Placeholder name used in tracing for unnamed hooks.

Traits

HookEngine

Dispatcher for the main loop (step model).

StepHandler

Step model handler (migration target). The engine gives it an input envelope for a mount point (produced by step::HookStep::to_envelope), and it produces a verdict JSON — the engine then applies the verdict back to the step via step::HookStep::apply_verdict. Both hook types implement this: internal Rust hooks compute the verdict directly; command/prompt hooks feed the envelope to a subprocess/LLM and parse the output into a verdict.