## Documentation index This index lists every available documentation page and its Markdown source. - [Documentation](https://rienda.varavel.com/docs/index.md) - [Installation](https://rienda.varavel.com/docs/installation/index.md) - [Advanced](https://rienda.varavel.com/docs/advanced/index.md) - [Tools](https://rienda.varavel.com/docs/advanced/tools/index.md) - [Hooks](https://rienda.varavel.com/docs/advanced/hooks/index.md) ## Documentation content The complete documentation for this website follows, reproduced verbatim from every page. --- # Documentation Rienda is a simple, declarative, multi-agent LLM harness. You describe an agent in a Markdown file, Rienda runs it against the provider you configure, and the whole conversation is stored as a session you can reopen. ## How to read this documentation Start with installation, then read the advanced section only when you want to extend Rienda beyond its built-in behavior: 1. [Installation](/docs/installation/) covers the installers, the prebuilt binaries, the Docker image, and building from source. 2. [Advanced](/docs/advanced/) explains the JavaScript extensions: the tools the model can call and the hooks that run at fixed points of a run. ## The three moving parts Everything in Rienda reduces to three inputs, and it helps to keep them separate in your head from the beginning: - **Provider modules** (`~/.rienda/providers//index.js`) are JavaScript functions returning a canonical declaration of the connection and the model roster of the provider; the ones built in ship inside the binary, and a user module of the same name replaces them. `rienda auth` stores the keys the modules ask for. Declare nothing twice: models are not listed in a config file, and an agent does not name a model either. - **Agent definitions** (`~/.rienda/agents/*.md`) are Markdown files whose YAML frontmatter declares the description and the tools and hooks the agent may use, and whose body is the system prompt. Agents never name a model: a session picks the model it runs, and `ctrl+x m` or `ctrl+x t` switch it or its thinking mode while the conversation goes. An agent is the unit you run. - **Sessions** (`~/.rienda/sessions`) are the transcripts Rienda writes as you work. They are what the start list offers back, and they let a conversation be continued, branched, or read again later. The rest of this documentation is what those three statements mean in practice. ## Where to go next - New here? Go through [Installation](/docs/installation/). - Want to extend Rienda without touching Go? Read [Advanced](/docs/advanced/). --- # Installation Rienda ships as a single self-contained executable: the terminal interface, the non-interactive commands, and the embedded JavaScript runtime are all inside it. There is nothing else to install at runtime, no service to connect and no database to run. Pick the flavor that fits your machine: - **The installers** are the quickest path on Linux, macOS and Windows. - **The Docker image** is useful when you want Rienda isolated from the host. - **The source** is there when you want to build it yourself or follow the project. ## Install with the shell installer On Linux and macOS, the installer downloads the right binary for your platform, verifies its SHA-256 checksum, and installs it into `/usr/local/bin`: ```bash curl -fsSL https://get.varavel.com/rienda | sh ``` Verify the installation with `rienda --help`, which prints the command usage. The installer accepts a few options through environment variables: ```bash # Install a specific version curl -fsSL https://get.varavel.com/rienda | VERSION=vx.x.x sh # Install into a user directory, without sudo curl -fsSL https://get.varavel.com/rienda | INSTALL_DIR=$HOME/.local/bin sh # Suppress all output curl -fsSL https://get.varavel.com/rienda | QUIET=true sh ``` When `VERSION` is not set, the installer resolves the latest release. If the target directory is not writable and a terminal is available, the installer falls back to `sudo`; point `INSTALL_DIR` somewhere writable to avoid that entirely. ## Install with Homebrew On macOS or Linux with Homebrew, install the formula from the Varavel tap: ```bash brew install varavelio/tap/rienda ``` Upgrading follows the usual Homebrew flow: ```bash brew update && brew upgrade rienda ``` Stable releases also publish a pinned versioned formula, so you can hold an exact version with `brew install varavelio/tap/rienda@x.x.x` style commands when you need to. Pre-releases are only reachable through the moving `rienda-next` formula. ## Install on Windows The PowerShell installer downloads the Windows binary, verifies its SHA-256 checksum, installs it into your local programs directory, and adds it to your user `PATH`: ```powershell irm https://get.varavel.com/rienda.ps1 | iex ``` Verify the installation by opening a new terminal and running `rienda --help`. The installer accepts the same `VERSION`, `INSTALL_DIR`, and `QUIET` options as the shell installer, set as environment variables before the command. If your execution policy blocks the one-liner, run it with an explicit bypass: ```powershell powershell -ExecutionPolicy ByPass -Command "irm https://get.varavel.com/rienda.ps1 | iex" ``` ## Download the binaries directly Every release publishes prebuilt archives for `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`, `windows/amd64`, and `windows/arm64`, plus `checksums.txt` and `manifest.json`: ```text https://github.com/varavelio/rienda/releases ``` Each archive contains the binary, the readme, and the license. Verify a download against the release checksums before trusting it: ```bash sha256sum --check checksums.txt --ignore-missing ``` ## Run with Docker The same image is published to two registries: ```text docker.io/varavel/rienda: ghcr.io/varavelio/rienda: ``` Both are multi-arch manifests covering `linux/amd64` and `linux/arm64`. Version tags follow the releases, and the `latest` tag only tracks stable releases, so pinning an exact version keeps your upgrades deliberate. The image runs as an unprivileged user with UID and GID 65532, sessions run in `/workspace`, and the state lives under `/home/nonroot/.rienda`, which is declared as a volume. Mount it to keep your configuration, agents, and sessions across containers: ```bash docker run -it --rm \ -v rienda-home:/home/nonroot/.rienda \ -v "$PWD:/workspace" \ varavel/rienda ``` The container needs an interactive terminal, so run it with `-it`. The non-interactive command is the same binary with an argument: ```bash docker run --rm \ -v rienda-home:/home/nonroot/.rienda \ -v "$PWD:/workspace" \ varavel/rienda run -a my-agent -p "summarize this repository" ``` Rienda reads the provider credentials from `config.yaml`, so mount the same configuration you use on the host, or build derived images that bake it in. The container needs network access to reach the providers, and the home volume keeps the API keys out of the image itself. ## Build from source If you prefer to build the binary yourself, all you need is Go: ```bash git clone https://github.com/varavelio/rienda.git cd rienda go build -o ./dist/rienda ./cmd/rienda/. ``` To install it straight into your `GOPATH/bin` (or `GOBIN`) with a single command, from any directory, use `go install`: ```bash go install github.com/varavelio/rienda/cmd/rienda@latest ``` The repository also defines a Taskfile with the same commands plus its development checks. Use the production task to get the same optimized binary the official artifacts ship: ```bash task build:prod ``` ## First steps Rienda reads its configuration from `~/.rienda/config.yaml` and its agent definitions from `~/.rienda/agents`. The configuration file must declare at least one provider, and an agent must declare a model that the configuration holds. `--config` and the `RIENDA_CONFIG` environment variable point Rienda at a configuration file somewhere else. Open the interactive interface by running the binary with no arguments: ```bash rienda ``` The interface starts a new session or continues a previous one of the workspace, and it is the default mode. The non-interactive `rienda run` command runs an agent once and prints its answer, which is what scripts and CI use. Continue with [Advanced](/docs/advanced/) when you want to add your own tools and hooks. ## Upgrades Installing a newer version is replacing the binary or the image tag. The state under `~/.rienda` carries forward, so your configuration, agents, and sessions survive an upgrade untouched. To install a specific version with the installers, set `VERSION=vx.x.x` as shown above; with Homebrew, upgrade as usual; with Docker, change the tag. --- # Advanced Rienda is extended in JavaScript, without touching its source and without compiling anything. Two kinds of extension exist: - A **tool** is a capability the model can invoke during a conversation, such as reading a project file or calling an internal API. - A **hook** is your code running at a fixed point of a run, so you can inspect it, gate it, or change what happens. Start with [Tools](/docs/advanced/tools/) and continue with [Hooks](/docs/advanced/hooks/). Both pages share the same runtime and the same `ctx` object, so everything you learn on the first applies to the second. ## Nothing extra to install The JavaScript engine is embedded in the binary. Rienda runs your scripts with [goja](https://github.com/dop251/goja), a pure Go implementation of JavaScript, so there is no Node.js, no npm, and no dependency to install: write an `index.js` file, start a session, and it is there. That also means the language you write is not the one your editor may assume. The engine implements **ECMAScript 5.1 in full**, plus some features of **ECMAScript 6**: the newer revision is still work in progress upstream, so treat ES5.1 as the language you can always rely on. In practice: - Everything of ES5 works: `var`, functions, prototypes, closures, `Object` utilities, `JSON`, regular expressions, `try`/`catch`, and strict mode. - A good part of ES6 works: `let` and `const`, arrow functions, classes with `extends`, template literals, destructuring, default and rest parameters, the spread operator, `for...of`, `Map`, `Set`, `Symbol`, `Promise`, generators, getters and setters, and the additions to the standard library such as `Object.entries`, `Object.assign`, `Array.prototype.includes` and `String.prototype.padStart`. - Not everything does. There is **no module loader**, so `import` and `export` do not exist and a script assigns `module.exports` instead. Async iteration (`for await...of`) and async generators are unsupported, and the engine does not provide the host globals a browser or Node.js would, such as `setTimeout`, `fetch`, `URL`, `Buffer`, or `console`: the `ctx` object is what replaces them. When in doubt, write ES5-compatible code, which always runs. The example pages use nothing beyond what the engine supports. ## How the runtime behaves Four rules explain almost everything about writing an extension: 1. **One call, one fresh runtime.** Every invocation of a tool or a hook starts with a clean engine, so nothing is remembered between calls. To keep something, write it to a file. 2. **No event loop.** The runtime is synchronous: `setTimeout`, `setInterval`, `process`, and `require` do not exist, and nothing waits for a callback that would fire later. A `Promise` resolves only after your function has already returned, so a result you need must be produced by the code you return from directly. 3. **No timeout.** A tool or a hook runs until it returns or the run is interrupted, so you own the timeouts of anything slow you call. 4. **`ctx` is the surface.** Everything Rienda offers a script, from reading a file to asking the user a question, is a member of the `ctx` object. The [Tools](/docs/advanced/tools/#the-context) page documents it completely, and hooks receive the same one. ### Provider modules A provider is a directory with an `index.js` under `~/.rienda/providers`. The built ones ship inside the binary; a user module of the same name replaces the built one entirely. Every module exports one synchronous function receiving the same `ctx` a hook receives and returning the canonical declaration of the provider: ```js module.exports = function(ctx) { var catalogue = JSON.parse( ctx.http.fetch("https://models.dev/api.json").body, ); // pick the models of the provider you serve, filter to the adapters // Rienda speaks, and return the declaration: return { name: "My Provider", protocol: "openai_chat_completions", // one of openai_responses, // openai_chat_completions, anthropic base_url: "https://opencode.ai/zen/go/v1", session_header: "x-opencode-session", headers: {}, auth: "api_key", models: [{ id: "kimi-k2", context_window: 128000, reasoning: false }], }; }; ``` `name` is the display name the interface shows the provider by in the header and the model picker; it is optional and falls back to the directory name, just like a model falls back to its `id`. The declarations that reach the modules are the roster the picker offers and the connections every run uses; the module owns its catalog, and the caches it writes sit beside its declaration, inside its own directory. Keys travel through `rienda auth`, which stores them at `~/.rienda/credentials.json`. --- # Tools A tool is a capability the model can invoke during a conversation. Rienda ships one built-in tool (`shell`), and you can add your own in JavaScript. A custom tool lives in its own directory under `~/.rienda/tools`: ```text ~/.rienda/tools//index.js ``` The directory name is the tool name the model calls, so `~/.rienda/tools/word-count` defines a tool called `word-count`. Tools are global: they are read from `~/.rienda` and never from a workspace, so a tool changes Rienda everywhere. A user tool that shares a name with a built-in shadows it, which is how you tune or replace built-in behavior. Because a tool runs with your privileges on your machine, it is trusted. Rienda does not sandbox extension scripts: install only tools you trust. ## Your first tool ```js // ~/.rienda/tools/word-count/index.js module.exports = { description: "Counts the words of a file in the workspace.", parameters: { type: "object", properties: { path: { type: "string", description: "Path relative to the workspace." }, }, required: ["path"], additionalProperties: false, }, execute: function(ctx, args) { const text = ctx.file.read(args.path); return String(text.trim().split(/\s+/).length); }, }; ``` For the model to use it, an agent must declare the tool in its definition: ```yaml --- description: A careful agent. model: openai/gpt-4o tools: - word-count --- ``` ## Anatomy A tool file exports a single object with three fields. | Field | Type | Required | Purpose | | ------------- | -------- | -------- | ----------------------------------------------------------------- | | `description` | string | yes | What the tool does and when to use it. Shown to the model. | | `parameters` | object | yes | A JSON Schema for the arguments. Passed to the provider verbatim. | | `execute` | function | yes | Runs one invocation. See below. | A file that is missing any of these is skipped, and the problem is reported as a diagnostic. It never crashes a run. ## `execute(ctx, args)` `execute` is called once per invocation. It receives the runtime context `ctx` (see [The context](#the-context)) and `args`, the arguments the model sent, already decoded from JSON into a plain object that matches `parameters`. It must return one of two shapes: | Return | Result the model reads | | ------------------------------------- | ------------------------------------------------- | | a string | that text, as a successful result | | `{ text: string, isError?: boolean }` | `text`, marked as an error when `isError` is true | Anything else (a number, a boolean, an array, `null`, an object without a `text` string) is treated as an error, so a mistake is reported instead of reaching the model as a surprising value. To return structured data, serialize it yourself: ```js return JSON.stringify({ count: words, file: args.path }); ``` A `throw` fails the invocation, never the run: the model receives the error text and the conversation continues. ## The context Every tool and hook receives the same `ctx`. It groups its capabilities in namespaces and exposes a few top-level values. ### Top level | Member | Type | Description | | ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ctx.workdir` | string | Absolute workspace directory. The base for every relative path. | | `ctx.session` | object | `{ id, agentId, modelId, workdir }` of the current run. | | `ctx.agent` | object | The running agent: `name` (its id) plus its whole frontmatter (`description`, `model`, `tools`, `hooks`, `config`) and `systemPrompt` (the Markdown body). Per-agent settings live under `ctx.agent.config`. | | `ctx.config` | object | The global `config.yaml`, read-only. Put custom settings under its `config` block, keyed by tool or hook name. | | `ctx.log(text)` | | Streams `text` to the front end. Not capped. | | `ctx.sleep(ms)` | | Sleeps for `ms` milliseconds, or returns early when the run is interrupted. | | `ctx.confirm({ title, body })` | boolean | Asks the user a yes/no question. Blocks until they answer; returns `true` on approval, `false` on refusal. In the terminal it opens a screen of its own: the question, its body, and `Approve`/`Deny` choices moved with the arrows and taken with `enter` (`esc` denies). | | `ctx.notify({ title, body })` | | Shows a non-blocking notice to the user. | ### `ctx.file` Reads and writes the file system. Relative paths resolve against `ctx.workdir`. | Member | Description | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ctx.file.read(path, opts?)` | Returns the file content as text. `opts = { encoding? }` (only `"utf8"` for now). Invalid UTF-8 is replaced, never raised. | | `ctx.file.write(path, data, opts?)` | Writes `data`, creating parent directories. `opts = { append? }`: by default the file is truncated. | | `ctx.file.exists(path)` | Returns whether the path exists, file or directory. | | `ctx.file.list(path, opts?)` | Lists a directory as `[{ name, path, isDir }]`. `opts = { recursive?, respectIgnoreFiles? }`, both `true` by default. `respectIgnoreFiles` honors the `.gitignore` and `.ignore` of the tree. | ### `ctx.env` | Member | Description | | ------------------- | ------------------------------------------------------------------------- | | `ctx.env.get(name)` | Returns the value of an environment variable, or `null` when it is unset. | ### `ctx.http` | Member | Description | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ctx.http.fetch(url, opts?)` | Sends an HTTP request and returns `{ status, headers, body }`. `opts = { method?, headers?, body?, timeout_ms? }`. The response is returned whatever the status, so you decide how to handle it. `headers` is a flat string map and `body` a string sent as-is. | ### `ctx.system` | Member | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ctx.system.exec(command, opts?)` | Runs `command` through the shell. `opts = { cwd?, timeout_ms?, env? }`. Returns `{ code, stdout, stderr }` (`code` is `-1` when a signal or a timeout ended the process). Output is streamed to the front end live, like the built-in `shell` tool. | | `ctx.system.which(name)` | Returns the absolute path of an executable, or `null` when it is not on `PATH`. | ## Examples Read a JSON file and return one field: ```js module.exports = { description: "Reads a field from a JSON file in the workspace.", parameters: { type: "object", properties: { path: { type: "string" }, field: { type: "string" } }, required: ["path", "field"], additionalProperties: false, }, execute: function(ctx, args) { const data = JSON.parse(ctx.file.read(args.path)); return JSON.stringify(data[args.field]); }, }; ``` Ask the user before doing something risky: ```js module.exports = { description: "Publishes the current branch.", parameters: { type: "object", properties: {}, additionalProperties: false }, execute: function(ctx) { if (!ctx.confirm({ title: "Publish", body: "Push the current branch?" })) { return { text: "cancelled by the user", isError: true }; } const result = ctx.system.exec("git push"); return result.code === 0 ? "pushed" : { text: result.stderr, isError: true }; }, }; ``` Call an API with `ctx.http.fetch`: ```js module.exports = { description: "Returns the latest release tag of a GitHub repository.", parameters: { type: "object", properties: { repo: { type: "string" } }, required: ["repo"], additionalProperties: false, }, execute: function(ctx, args) { const res = ctx.http.fetch( "https://api.github.com/repos/" + args.repo + "/releases/latest", ); if (res.status !== 200) { return { text: "HTTP " + res.status, isError: true }; } return JSON.parse(res.body).tag_name; }, }; ``` ## Behavior and limits - **Live output.** Output written with `ctx.log` and everything a `ctx.system.exec` command prints reaches the front end while the tool runs, so a long tool shows progress instead of looking frozen. - **Typed returns.** `execute` must return a string or `{ text, isError }`; anything else becomes an error result. There is no implicit serialization. - **Output cap.** The text `execute` returns is capped (256 KiB, cut on a rune boundary). Streamed output is never capped. - **No timeout.** A tool runs until it returns or the run is interrupted. Controls such as `timeout_ms` in `ctx.system.exec` are yours to add. - **Fresh state.** Every invocation runs in a fresh runtime, so nothing persists in memory between calls. To remember something, write a file. - **Name rules.** A tool name is 1 to 64 characters of letters, digits, underscores or hyphens. - **Strict options.** Every `opts` object rejects a field it does not document, so a typo raises instead of being silently ignored. Fields reserved for the future (`opts.encoding` values beyond `"utf8"`, `opts.onOutput`) raise until they are implemented. - **Asking the user.** In the terminal, `ctx.confirm` opens a prompt. In a non-interactive run it answers `false`, unless the run started with `--auto-approve` (`-y`), which answers `true` to everything. - **Load problems are diagnostics.** A tool that cannot load is skipped and reported once per run as `tool "": `, on standard error in the CLI and as a notice in the TUI. An agent that declares a tool that did not load fails the run, the same way an unknown tool does. --- # Hooks A hook runs your code at fixed points of a run, so you can inspect, gate or change what happens without touching Rienda's source. A hook lives in its own directory under `~/.rienda/hooks`: ```text ~/.rienda/hooks//index.js ``` The directory name is the hook name, so `~/.rienda/hooks/guard` defines a hook called `guard`. Hooks are global: they are read from `~/.rienda` and never from a workspace. They run with your privileges and are trusted: install only hooks you trust. ## Your first hook A hook file exports one function per point it handles. It may implement any subset of the points. ```js // ~/.rienda/hooks/guard/index.js module.exports = { beforeToolExecute: function(ctx, call) { if ( call.name === "shell" && /\brm\s+-rf\b/.test(call.arguments.command || "") ) { if ( !ctx.confirm({ title: "Dangerous command", body: call.arguments.command, }) ) { return { allow: false, reason: "refused by the user" }; } } }, afterRun: function(ctx, event) { ctx.notify({ title: "rienda", body: "run finished: " + event.reason }); }, }; ``` For the hook to run, an agent must declare it. The list order is the execution order: ```yaml --- description: A careful agent. model: openai/gpt-4o tools: - shell hooks: - guard - audit --- ``` An agent that declares no `hooks` runs with no hooks. A declared hook that does not exist fails the run, the same way an unknown tool does. ## The points Every point is named ``, where the phase is `before` or `after`. A hook receives `ctx` (identical to the one tools get; see [Tools](/docs/advanced/tools/)) and the payload described below. Returning nothing means "no opinion" and changes nothing. | Point | Runs | Receives | May return | | -------------------- | -------------------------------------------------------- | --------------------------------------------------- | --------------------------------- | | `beforeRun` | Once, at the start of a run. | `{ sessionId, agentId, modelId }` | nothing | | `afterRun` | Once, when the run ends, for any reason. | `{ reason }` (`end_turn`, `interrupted` or `error`) | nothing | | `beforeModelRequest` | Every turn, just before the provider call. | `{ system, model, messages }` | `{ system? }` | | `afterModelResponse` | Every turn, after the model answers, before it is saved. | `{ text, thinking, toolCalls }` | `{ text?, thinking? }` | | `beforeToolExecute` | Before a tool runs, once per call. | `{ id, name, arguments }` | `{ allow?, reason?, arguments? }` | | `afterToolExecute` | After a tool returns, once per call. | `{ id, name, arguments }` and `{ text, isError }` | `{ text?, isError? }` | `beforeModelRequest.messages` and `afterModelResponse.toolCalls` are read-only today. ## What each return does ### `beforeModelRequest` The common use is adding context to the system prompt. `system` replaces the system prompt for this turn only. It is not saved and does not carry over to the next turn, so a hook that injects a date injects it again on every turn and the prompt the model finally sees is always the current one. Build it from `request.system` to add to what the agent already declares. ```js beforeModelRequest: function (ctx, request) { const today = new Date().toISOString().slice(0, 10); return { system: request.system + "\n\nToday is " + today + "." }; } ``` `request.messages` is a read-only snapshot of the conversation (`[{ role, text }]`), useful to decide what to inject without reading the session file. ### `afterModelResponse` Rewrites the assistant's own text before it enters the conversation. Useful to redact secrets or normalize output. ```js afterModelResponse: function (ctx, response) { return { text: response.text.replace(/\b\d{16}\b/g, "[redacted]") }; } ``` ### `beforeToolExecute` Gates a call, rewrites its arguments, or both. - `allow: false` refuses the call. The model receives an error result carrying `reason`, and no tool runs. The remaining hooks are not consulted for that call. - `arguments` replaces the arguments the next hook and the tool see. ```js beforeToolExecute: function (ctx, call) { if (call.name !== "http") return; return { arguments: { ...call.arguments, url: call.arguments.url.replace("http://", "https://") } }; } ``` ### `afterToolExecute` Rewrites the result the model reads. ```js afterToolExecute: function (ctx, call, result) { return { text: result.text.toUpperCase() }; } ``` ## Chaining and order - Hooks run in the order their extensions are listed in the agent. - Within a point, one hook's output is the next hook's input: a rewrite chains, and the last writer wins. - Every field you return is optional and replaces only itself. A field you leave out, or return as `undefined` or `null`, keeps its current value. - `beforeToolExecute`: on the first `allow: false`, the call is refused and no further hook is consulted for that call. - A hook that throws is reported as a notice and skipped. It never crashes the run. ## The context Hooks use the exact same `ctx` as tools: `ctx.workdir`, `ctx.session`, `ctx.agent`, `ctx.config`, `ctx.file`, `ctx.env`, `ctx.http`, `ctx.system`, `ctx.log`, `ctx.confirm` and `ctx.notify`. See [Tools](/docs/advanced/tools/#the-context) for the full list. `ctx.confirm` is the human-in-the-loop primitive: it blocks until the user answers. In the terminal it opens a prompt; in a non-interactive run it answers `false`, unless the run started with `--auto-approve` (`-y`), which answers `true` to everything. ## Behavior and limits - **No timeout.** A hook runs until it returns or the run is interrupted. - **Fresh state.** Every invocation runs in a fresh runtime, so nothing persists in memory between calls. To remember something, write a file. - **Errors are non-fatal.** A broken hook is reported as a diagnostic when the extension is loaded, and a throwing handler is reported as a notice while the run continues as if the hook had returned nothing. Neither fails the run. - **Live output.** `ctx.log` reaches the front end while the hook runs, so a hook that does something slow can say what it is doing.