Module stage_hook 

Script-backed stage lifecycle hooks ([stages.<name>.hooks], issue #260).

Where a custom region’s script owns one region’s behaviour, these let a blueprint observe and steer the agent’s own lifecycle: what the context holds as a stage opens, what happens as it closes, and (in later hooks) what is about to be inferred or called.

Same shape as crate::region_hook, deliberately - a blueprint author who has written one has written the other:

• A return-value contract. Rhai passes arguments by value, so mutating ctx in place does nothing; the script returns its decision.
• Compiled once, at agent spawn, by the CLI. A missing or malformed script is a spawn error, not a runtime surprise.
• A fresh hardened engine per call (crate::harden): no filesystem, no network, no eval, operation-bounded.
• JSON at the boundary, so leviath-runtime interprets the outcome without depending on rhai.

The outcome contract

Every hook returns one of four things, and the same four everywhere, so a reader does not have to learn a vocabulary per hook:

script returns	meaning
(), true	HookOutcome::Allow - proceed unchanged
false	HookOutcome::Cancel with no reason given
#{ action: "allow" }	as above, written out
#{ action: "modify", value: ... }	HookOutcome::Modify - proceed with value
#{ action: "cancel", reason: "..." }	HookOutcome::Cancel
#{ action: "retry" }	HookOutcome::Retry

What Modify and Retry mean is the calling hook’s business - the shape of value differs between “the regions to write” and “the request to send”, and not every hook can honour Retry. This module decides only that the script returned a well-formed decision; the caller decides whether it is one it can act on. That split is why an unknown action is an error here (a typo’d "modfiy" must not read as Allow) while an unhonourable one is reported by the caller.

Structs

HookScript

A compiled stage-hook script, ready to call.

Enums

HookOutcome

What a hook decided.

Constants

HOOK_NAMES

The hooks this build implements, as the function names a script defines.

Functions

compile

Compile a stage-hook script and record which hooks it defines.

run

Call hook(ctx) and interpret the decision.