Module step 

Hook step-context: typestate + envelope.

One-liner

Each mount point gets its own dedicated step type (typestate). The same step state is consumed by two kinds of hooks — internal Rust hooks work directly with the strong type and mutate fields; user-configured hooks observe the world through the JSON envelope produced by HookStep::to_envelope and apply output back via HookStep::apply_verdict. Equal capability, identical surface — only the medium of expression differs.

Two axioms

1. Typestate: Instead of one large enum with a variant field, each mount point is a concrete struct. The surface is locked at compile time; Option presence/absence encodes “already produced / will produce” — filling a “will produce” Option means short-circuit.
2. Call vs mutation asymmetry: Call-type steps (Generate / ToolApply / Permission) fill an Option to skip; mutation-type steps (Compact / Ingest) degrade to veto/rewrite, without the “fill Option” path.

Scope (Step 1)

This module delivers types + envelope + unit tests, with no mount points wired in (call-site integration is a follow-up PR). Currently implements the base infrastructure (HookControl / HookStep / envelope conventions) plus 3 representative steps: BeforeTurnEnd (fork control), BeforeToolApply (call-type short-circuit), AfterGenerate (observation). The remaining 10 steps are mechanical fill-ins of the same shape.

Structs

AfterCompact

after Compact: compression is complete. Injection / observation only.

AfterGenerate

after Generate: the LLM call has returned. Observational — usage / stop / error are all present (non-Option), with no room to “fill in” outputs; to influence the next round, use BeforeTurnEnd. Only Break and observation are meaningful.

AfterIngest

after Ingest: input has been merged into history. Injection only.

AfterPermission

after Permission: authorization result is determined. Observation only.

AfterSessionEnter

after session enter: the session scope has been entered. Allows injecting a system suffix or rejecting with Break.

AfterToolApply

after ToolApply (per-tool): the tool has produced a result. Supports injection (appending to tool_result) or Break.

AfterToolBatch

after ToolBatch: a full batch of parallel tools has finished. Can inject / Break (graceful).

AfterTurnEnter

after turn enter: the turn scope has been entered, but input for this round has not yet been consumed. Injection or Break can reject this turn.

BeforeCompact

before Compact: runs before compaction. Mutation type — short-circuit = Skip (vetoes this compaction), no “fill result”.

BeforeGenerate

before Generate: runs before the LLM call. Call-site hook — can modify request fields, or set assistant_text to short-circuit (skip the real LLM call with a synthetic reply).

BeforeIngest

before Ingest: called before ingesting the current turn’s input. Can rewrite the entire pending input or Break to reject the turn.

BeforePermission

before Permission: invoked before requesting user authorization. Currently only stubs observe — the resolved fallback is not yet wired (policy remains the authority for allow/deny). Stub is in place for future use.

BeforeToolApply

Entry point for call-type transformations, invoked before each ToolApply.

BeforeTurnEnd

before turn-end: the turn’s only voluntary exit point. Defaults to Break — “do nothing” = let it stop.

SyntheticToolResult

A synthetic tool result produced by a hook — setting BeforeToolApply::result effectively “intercepts” the tool.

ToolBatchEntry

A summary entry for a batch of parallel tool results (for envelope use).

Enums

HookControl

A hook’s instruction for control flow (axis two). Data injection (axis one) goes through the step’s &mut fields, not here.

IngestSource

The source of the input to be ingested in the current turn.

SessionSource

The source of the session: new or resumed.

VerdictError

Errors when parsing an envelope verdict.

Constants

ALL_EVENT_NAMES

The single source of truth for all mount-point event_names (snake_case) — used by the config layer for event-name validation and by the CLI for bucket assembly.

Traits

HookStep

The step state for a mount point. Consumed by two kinds of hooks:

Functions

is_known_event

Whether an event name is a known mount point. The config layer uses this to fail-fast on misspelled event keys.

run_step_pipeline

Applies a sequence of handler verdicts to the same step in declaration order, producing the final HookControl.