Module hook_helpers 

Hook helpers for Lua integration.

Provides LuaHook (a Lua-backed Hook implementation), shorthand descriptor parsing, and HookContext ↔ Lua table conversion utilities.

orcs.hook() API

Two calling conventions:

-- Shorthand: "fql:hook_point"
orcs.hook("builtin::llm:request.pre_dispatch", function(ctx)
    ctx.payload.injected = true
    return ctx
end)

-- Table form (full control)
orcs.hook({
    fql      = "builtin::llm",
    point    = "request.pre_dispatch",
    handler  = function(ctx) return ctx end,
    priority = 50,   -- optional (default 100)
    id       = "my-hook",  -- optional
})

Return value conventions

Lua return	HookAction
nil	Continue(original_ctx)
context table (has hook_point)	Continue(parsed_ctx)
{ action = "continue", ctx = ... }	Continue(...)
{ action = "skip", result = ... }	Skip(value)
{ action = "abort", reason = "..." }	Abort { reason }
{ action = "replace", result = ... }	Replace(value)

Structs

HookLoadError

Error from loading a single hook definition.

HookLoadResult

Result of loading hooks from configuration.

LuaHook

A hook backed by a Lua function.

Functions

hook_context_to_lua

Converts a HookContext to a Lua value (table) via serde.

load_hooks_from_config

Loads hooks from a HooksConfig into a SharedHookRegistry.

lua_to_hook_context

Converts a Lua value (table) back to a HookContext via serde.

parse_hook_descriptor

Parses a hook descriptor shorthand into FQL pattern and HookPoint.

parse_hook_return

Parses the return value from a Lua hook handler into a HookAction.

register_hook_function

Registers the orcs.hook() function on the orcs global table.

register_hook_stub

Registers a default (deny) orcs.hook() stub.

register_unhook_function

Registers the orcs.unhook(id) function on the orcs global table.