Module hook_host 

Hook host — pre-submit capability-bounded extension point.

Hook contract

Submit-side execution order:

Auth & Quota → Hook (extra_bytes only) → Policy re-validation → Build → Submit

A hook can mutate only the ExtraBytesBuilder — every other field of the in-flight submission (actor, verb, target, shell_id, principal) is opaque to the hook. Post-hook policy re-validation re-checks the same predicates as pre-hook — a hook that edits extra bytes in a way that changes policy outcome is rejected at the re-validation step (confused-deputy defense).

Two implementations

• NoopHookHost (always compiled): pass-through that returns Ok(()) without mutating extra bytes. Selected when the runtime does not opt in to a sandbox-backed hook.
• WasmtimeHookHost (feature tier-2-hook-host-v2): wasmtime preview-2 sandbox with fuel-metered execution, capability-token whitelist (arkhe:hook/{state, emit, fuel}), and 4-set host-fn surface enforcing E14.L2-Allow at runtime. See [wasmtime_host] (feature-gated) for the concrete sandbox host.

Both implement the HookHost trait, so submit-side callers stay agnostic of the active backend.

Spec anchor

• E14 Compute Determinism Closure — paired E14.L1-Deny (build-time AST deny-list) + E14.L2-Allow (runtime host-import allow-list, this module).
• Hook-host 3-tier ingestion — BLAKE3 digest pin (sigstore + cargo-vet attestation tiers route through [wasmtime_host::HookAttestationVerifier]).

Structs

ExtraBytesBuilder

Mutable extra-bytes accumulator threaded through hook invocations. Hooks may append; they cannot read prior policy-invariant fields. Wraps the existing bytes::BytesMut shape so the L1 builder can adopt it without re-allocating after the hook returns.

HookContext

Hook execution context — opaque to hooks themselves; managed by the host. Carries the capability set + the extra-bytes builder; sandbox- backed hosts (WasmtimeHookHost) thread these into a per-invocation wasmtime Store / Caller<'_, _> internally.

NoopHookHost

Pass-through host — returns Ok(()) without mutating extra bytes. The Hook host box in the contract diagram runs this implementation when the runtime is not configured for sandbox-backed hooks.

Enums

CapToken

Capability tokens an enabled hook may request from the host. Each token grants permission to call a single host-side function — non- whitelisted imports are rejected at module-load (E14.L2-Allow enforcement).

HookError

Hook execution outcome.

Traits

HookHost

Pre-submit hook host — the L2 service that runs registered hooks against an in-flight submission’s extra_bytes buffer.