fiber

Extensions

What is true now about Fiber's extension system. Vocabulary is GLOSSARY.md. The seams are docs/architecture.md; the runtime choice and its reasoning are ADR 0006; the trust model is docs/permissions.md. The measurements behind all of it are in research/extension-runtime/ and research/extension-process/.

What an extension is

An extension is a package Fiber installs and loads. Its code runs with the account's full rights. It registers capabilities through the same three seams a built-in uses — tool, provider and hook — and a registration by an existing name replaces the built-in, recorded in the session log. An extension that registers a tool named read becomes the read tool; the loop never learns whether the answer came from Fiber or from the extension. It can also register watchers, which learn what happened without changing it, and commands, which a person or a driver invokes by name.

An extension is meant to build anything a person wants on top of a coding agent: a memory system, a connector to an outside service, a goal that keeps the agent working, a research prototype of a better compaction.

Its code runs in one of two ways, and a package may use both:

Both register the same things, receive the same calls and have the same host calls, with the same names and meaning. The only difference is what the operating system gives a process directly: files, sockets, timers and any library in its language, npm's included. A package that draws in the terminal also carries a TUI extension ("Commands and screens").

What a package holds

An extension is one directory. Its manifest, extension.json, states (docs/configuration.md, "An extension's manifest"):

Beside the manifest it may hold:

These live in fixed directories at the top of the package, so an author lists nothing in the manifest and an install finds them by looking:

DirectoryHolds
skills/one directory per skill, each with a SKILL.md
prompts/one directory per prompt template, in the same format; every skill here is one only a person runs, as if its header set disable-model-invocation: true
themes/one file per theme; a switched-off extension's themes are not listed or loaded
tui/the TUI extension's Lua scripts, entered at tui/init.lua

What a skill and a prompt template are, and where Fiber finds them besides packages, is docs/system-prompt.md, "Skills". A theme sets the terminal's colours and nothing else (docs/tui.md, "Themes").

A script loads another script with require. require finds files inside the extension's own directory and nowhere else, so one extension cannot load another's code by path. Code shared between extensions reaches an extension in one of two ways: the extension vendors a copy, or it depends on the extension that holds the code (see Shared dependency modules).

Shared dependency modules

An extension that needs another extension's Lua declares it in depends, a mapping of each dependency's name to the minimum version it runs with: "depends": { "example.com/acme/strings": "1.0" }. Installing the extension installs its dependencies beside it, at the lowest tags that meet every minimum: Fiber installs nothing newer than someone asked for, and a dependency's own depends resolves the same way.

A script loads a dependency's module with the dependency's name, a colon, and the module path: require("example.com/acme/strings:trim"). The module path works exactly as it does inside the dependency — dots become directory separators — and everything after the first colon is the path, so a second colon stays in the module. A name with no colon loads the extension's own file; a name nobody declared, an empty module, and a leading colon all fail the same way, naming the unknown dependency. The modules are available from the moment the extension starts, in a session and in the login-time provider that asks for credentials.

Each read canonicalizes the dependency's directory and serves only what stays under it: a link pointing outside the dependency is refused, and a dependency whose directory is missing names the dependency rather than reaching the file loader. A repository copy serves its own .fiber-depends before the personal install, so a copy's dependency answers even when a different version sits beside it, and a copy whose dependency is missing names it without reading Fiber home.

The binary for this platform installs as bin/<last segment of the manifest name>: with "name": "github.com/acme/fiber-acme" that is bin/fiber-acme on every platform. A binary installed before this change gets that name at the next fiber extension update. A native binary is run as a process extension, or through host.exec ("Host calls") as host.exec("bin/fiber-acme", args).

Lua extensions

Lua extensions are written in Lua 5.4, embedded through mlua (vendored, so Fiber's build compiles Lua's C itself and takes no system dependency). The choice and the alternatives weighed — JavaScript via QuickJS, Luau, Starlark, WASM, and full TypeScript — are in ADR 0006.

The embedding is bare. An extension sees a stripped standard library — table, string, math, utf8, coroutine — plus a require limited to its own directory and its declared dependencies, and nothing else. There is no io, no os, no package, no debug. Every capability reaches it through a host-provided global, and the host calls give it what a process has natively: files, programs, HTTP and timers. Routing them through the host lets Fiber stop them on cancel and at shutdown, which it cannot do to a blocking C call inside Lua.

This is not a security boundary. Per docs/permissions.md, an extension runs with the account's full rights; the stripped stdlib is a structural fact — the host owns I/O — not a sandbox. A hostile extension is contained the way npm install is contained: not at all at runtime, only by the decision to install it. Trust is resolved when an extension is installed or approved, not while it runs, and an approval holds only for the exact files approved. How that works is Distribution.

Process extensions

A process extension is a client of its session with extra rights. It is not an MCP server: MCP covers tools, questions to a person and model calls, and has nothing for hooks, watchers, state, providers or commands. An extension that only brings tools can still ship an MCP server (docs/mcp.md).

The session starts the program with pipes on its stdin and stdout, in the session's workspace. The pipe carries JSON lines with the event stream's envelope and schema_version (docs/events.md), and three kinds of traffic:

The extension's calls are driver commands. A registration, a host call or a state call is the command call, with args { "call": "<name>", "args": [ ... ] }: the name as Lua writes it, such as fiber.tool, host.http or state.set, and the Lua call's arguments as a JSON array. A key whose Lua value is a function, such as run, a computed effects, or a provider's sign or cost, is sent as true, and Fiber calls it with a request. A call is answered by command_accepted, whose result is { "value": <what the Lua call returns> }, with value absent when it returns nothing, or by command_rejected with the code and message a Lua call raises. A registration that would fail in Lua is rejected with the message its notice carries. host.after, host.every, host.utf8_lossy and host.drive are not calls: the program keeps its own timers and sends driver commands directly. The extension ends its registrations with the command ready, which takes no args. The startup deadline is met when ready arrives. A call made while answering a request names it with request_id in its args. Fiber treats it as made inside that request's callback, with every rule a Lua call in that callback follows: which calls it may make, what ran_by names, the timeout it counts against, whether a state write goes with a hook's change, and what is cancelled when the callback ends. A call with no request_id before ready is treated as made while the entry script runs. One after ready is treated as made from a timer with no timeout of its own. A call naming a request that is no longer pending, because it was answered, timed out or was cancelled, is rejected stale_request and runs nothing. When a request ends, each call still running under it is stopped as the Lua callback's would be, and answered stale_request.

Bytes are base64. JSON strings are text, so every position below that holds bytes in Lua carries them as a string of standard base64, both ways. Every other string is text, as JSON carries it.

CallBytes positions
host.httpopts.body; the result's body
host.oauth.pollbody
host.execopts.input; the result's stdout and stderr
host.fs.readits result
host.fs.writethe contents argument
host.sha256its argument (the result is hex text)
host.hmac_sha256both arguments and the result, so one result passes unchanged as the next call's key

A bytes position that is not valid base64 is rejected invalid_arguments, naming the call and the argument.

Functions are requests. A function passed as a value, whether a key such as run, sign, cost or a computed effects, or a positional argument such as host.oauth.refresh's, is sent as true. Fiber calls it with an extension_request. Its key is the key's name or, for a positional argument, its 1-based position as a string, such as "1". host.after, host.every, host.utf8_lossy and host.drive are not calls (above). The json helpers are available, but are not host calls.

JSON is exact. Lua cannot tell an empty object from an empty list (an empty table), and the rule that settles it in Lua ("json.encode({}) is {}") does not apply on the wire. What the extension sends is read as sent, and what Fiber sends is the value as recorded, so {} and [] stay distinct. A whole number Lua requires, such as a timeout, must be a JSON integer, and a fraction there is rejected as it is in Lua.

Size. Each line is bounded by the framing cap (64 MiB), counted after base64, which adds a third. A line the extension sends over the cap closes the pipe, as it closes a client's connection, and the extension counts as dead ("One that dies is restarted once"). A result Fiber cannot fit under the cap is answered command_rejected too_large in place of the result. The call's own limits still apply first, such as state_too_large.

Fiber's requests are lines the extension answers with reply. Each is an ephemeral line of kind extension_request, whose payload holds request_id, registration (the id of the call command that registered it), key (the function's key, such as run) and args (the arguments the Lua function receives, as a JSON array). The extension answers with reply: request_id and result (what the Lua function returns), or request_id and error, { code, message }, which fails the call as a Lua error does. Stream items, meaning hooks, watcher deliveries and commands, are sent one at a time, each after the reply to the last one. Tool calls are sent as they arrive, so several can be outstanding. A reply to a request that is no longer pending, such as one past its timeout, is rejected stale_request and changes nothing. That is how a late reply is dropped.

extension_hello is the first line Fiber sends, ephemeral, with payload keys session_id, reason (new, resume, fork, rewind, compaction, or call for a provider call outside a session, such as a call case or the credential precheck), workspace (the workspace root), data_dirs ({ machine, project }, the paths host.data_dir returns) and state (the extension's folded state, as state.get reads it). After a restart it is sent again, with the state as it stands in the session. With reason call, session_id is absent and state is {}. The extension has host.http, host.exec, host.oauth, host.secret, host.data_dir, host.log, host.fs reads, the hashes and json; any other host call raises not_available (<call>: not available here).

Every session starts its own process extensions, a delegate included, as it starts its own MCP servers. Nothing is shared between sessions (ADR 0009). They start at session start, in parallel with MCP servers, and must send their registrations within the same startup deadline: 5 seconds, which configuration can change per extension. One that misses it, or fails to start, is left out for the session and the log records a notice; one marked required makes that fatal, as a required MCP server does (docs/mcp.md, "Starting servers").

One that dies is restarted once, on its next call. If it dies again it stays dead for the session: its tools stay declared, so the prompt cache holds, and every call to them fails with code extension_unavailable. Its hooks then fail as their on_failure says.

A process extension that misses a hook's timeout is not stopped. The hook has failed ("When a hook fails"), and a late reply is dropped.

A process extension written in Node, Bun or Python costs a runtime: an idle Node process measured 40 MiB, Bun 20 MiB and Python 10 MiB, against about 120 to 150 KiB for a Lua extension (macOS arm64, research/extension-process/). A round trip over the pipe took 56 to 79 µs for 16 KiB, against under 10 µs into Lua. An extension too heavy to run once per session is its author's to make smaller.

How an extension runs

A Lua VM runs one piece of code at a time, so each Lua extension in a session has one thread and one inbox, created the first time it is used. A TUI extension runs on the terminal's own thread instead (docs/tui.md, "How a TUI extension runs"). Hook calls, watcher deliveries, command invocations, timer firings and replies to host calls all arrive there.

Session order is kept. Hooks, watcher deliveries and commands form one stream, in the order they happened in the session. Each finishes, including any host call it waits on, before the next starts, so a hook never sees state that misses an earlier event. Timers are not ordered against the session. They run in the gaps: when the stream is empty, or while its current item waits on a host call. A tool call runs in the gaps, as timers do, so a long tool never holds up the extension's hooks.

A host call that fails raises a Lua error whose value is { code, message }, which pcall catches. An uncaught one fails the callback, and the callback's own failure rule applies. state_too_large and closing reach Lua this way. host.drive raises the rejection's code and message on command_rejected, and returns the command's result, or true, on command_accepted.

A host call suspends the code that made it. Fiber runs every callback as a coroutine. A host call such as host.http or host.model suspends it until the reply arrives, and the thread serves other work meanwhile, as await does in JavaScript. So a timer that polls a slow service does not hold up the extension's hooks. Code that reads and writes the extension's own globals must expect another callback to have run in between.

Every callback declares its timeout, with no default. Tools, hooks, watchers, commands and timers alike. A timeout is in milliseconds, a whole number above 0. No single value fits every callback: a computation needs milliseconds, a notifier seconds and a test run minutes. A missing timeout fails once, at registration, with a notice naming it, where a wrong default would fail quietly: spurious failures when it is too short, a frozen session when it is too long. A hook's on_failure has no default for the same reason: non-blocking would let a forgotten guard fail open, and blocking would let a forgotten notifier stop a session. A hook's clock starts when Fiber asks, so time spent waiting behind earlier items in the stream counts against it. A callback past its timeout is stopped ("When an extension misbehaves"). When the interrupt cannot stop the VM, Fiber abandons the VM 1 second after the timeout.

Fiber runs a Lua extension's entry script, init.lua, when it creates the VM. Reading, compiling and running it is bounded at 2 seconds. A provider file, providers/<name>.lua, has the same bound, starting when Fiber asks to load it. These scripts are not callbacks, so they declare no timeout.

A process extension keeps the same order: Fiber sends it the stream's items one at a time and waits for each reply. How it schedules its own timers and background work is up to the program.

Fiber's own Rust code has no async runtime (ADR 0004). An extension's loop runs on the extension's thread, or in its own process.

What an extension can do

A Lua extension reaches everything through three globals: fiber to register, host for capabilities, and state for its state in the session. A process extension sends the same calls as messages.

Registering

fiber.tool(name, { description, input_schema, effects, timeout, run, keep? })
fiber.provider(name, { models, quota, credential, sign, cost })
fiber.harness(name, { auto, models, command, line, quota })
fiber.search_backend(name, { timeout, run })
fiber.hook(point, { phase, on_failure, timeout, run })
fiber.watch(kinds, { timeout, run })
fiber.command(name, { description, timeout, run })

fiber.harness is not built yet: see #545.

What a harness declares is docs/delegates.md, "Harness extensions".

A tool's effects is a table, { effects, paths?, reversible, hosts? } as docs/permissions.md, "Effects", and docs/tools.md, "What a tool declares", declare, or a function of the call's arguments that returns one. The function is bounded by the tool's timeout, and an error fails the call tool_error before it runs. run returns a string, one text part, or { content, details?, error = { code, message }?, control?, hosts_surfaced? }, where control and hosts_surfaced take what any tool may set (docs/tools.md, "What a result carries"). A raised error fails the call tool_error with its message. keep = { head, tail } is the byte counts of the start and of the end of a long result the model is sent: head maps to Bound.start and tail to Bound.end. Either may be omitted (0), both are whole numbers, and at least one is above 0. Absent keep means the first 16 KiB. It is a value, not a function of the call. Any other key, including start and end, fails registration with a message naming it. A configured tools."<name>".max_result_bytes still wins (docs/tools.md, "Bounded results"). When two extensions register one tool name, neither gets it, a notice names both, and configuration can leave one out (extensions."<name>".tools.disabled, docs/configuration.md).

A search backend's run takes one table, { query } with allowed_domains or blocked_domains when the call gave one, and returns a list of { title, url, snippet } results, every field a string. An empty list is a success; anything else fails the call tool_error, naming the backend, its extension and the result's position.

A tool, harness, search backend, hook or watcher registers before the session's tool set is fixed (docs/prompt-cache.md, "Tools"), which is why every enabled Lua extension with init.lua runs it at session start ("Loading, and cost when nothing is loaded"), except a lazy extension whose manifest declares commands: its init.lua runs on the first run of one of its commands ("Commands and screens"). A provider is the exception: its manifest declares it, so providers/<name>.lua waits for first use. That file registers exactly one provider, matching its filename, and nothing else. init.lua holds the other registrations. A fiber.provider call in init.lua refuses the whole extension with extension_failed; the message names the provider file it belongs in. At session start its data is refused with it. In a lazy extension the call fails the first command's start, every command of the extension rejects until reload, and its data stays until the next reload or session. Catching a forbidden or duplicate registration with pcall still fails the load. After a file finishes loading, fiber.command, fiber.hook and fiber.provider raise, including from a timer or callback.

Host calls

host.secret(name)                  -- the secret stored at credentials/<name>
host.http(opts)                    -- one HTTP request; returns { status, body }
host.model(opts)                   -- one model request; returns { text, usage }
host.exec(program, args, opts)     -- run a program; returns { exit_code, signal, stdout, stderr }
host.tool(name, args)              -- run a tool the session can call; returns its outcome
host.delegate(spec, { timeout, run })  -- start a delegate job; returns its job_id
host.fs.read / write / list / stat / mkdir / remove / rename
host.config.get(key) / host.config.set(key, value, scope)   -- scope: "machine" or "project"
host.data_dir(scope)               -- "machine" or "project"
host.after(ms, fn, opts) / host.every(ms, fn, opts)   -- timers; return a handle with :cancel()
host.drive(command, args)          -- send a driver command
host.ask(kind, spec)               -- raise an interaction; returns the answer, or declined
host.status(text) / host.widget(id, lines)
host.emit(data)                    -- data for this extension's own TUI extension
host.log(msg)                      -- write a diagnostic line (see below)
host.oauth.open(url)               -- open the browser at url, and show the URL to copy
host.oauth.show(url, code)         -- show the device code to enter at url; opens nothing
host.oauth.callback(opts)          -- serve one request on localhost; returns its query parameters
host.oauth.pkce()                  -- returns { verifier, challenge }
host.oauth.poll(opts)              -- poll a device-code token endpoint; returns the token reply
host.oauth.refresh(fn)             -- lock the call's stored credential file, re-read it, refresh once
host.sha256(bytes)                 -- SHA-256; returns hex
host.hmac_sha256(key, bytes)       -- HMAC-SHA256; returns raw bytes
host.utf8_lossy(bytes)             -- bytes as a string with each invalid UTF-8 sequence replaced by U+FFFD; only codemode's print capture calls it
json.decode(str [, { lenient }]) / json.encode(value)   -- JSON, host-provided (Lua has none built in); { lenient = true } escapes raw control characters inside strings, strict stays the default

Running a tool

host.tool(name, args) runs any tool the session can call: a built-in, an MCP server's tool or another extension's. It returns the call's outcome: status, content, artifact, and reason or error when the call did not complete. It carries no details or changes, which the model never sees. The outcome reaches the script whole: an inner call bypasses the loop's cut, and the read tool's own cut does not apply to it, while the outer call's own result to the model stays bounded (docs/tools.md, "Bounded results"). An inner shell call also bypasses the shell's spill, so its whole output reaches the script without a shell artifact. Direct shell calls retain the 1 MiB spill (docs/tools.md, "Shell", "Result and output"). A call that does not complete is an ordinary return, not a Lua error, so the extension decides what to do next. A codemode extension is built on it: the model sends one script, and the script calls tools, filters their output and returns only what the model needs (#445).

A call host.tool makes is an inner call. The extension's own tool call that is running when it makes one is the outer call.

host.tool is not a fence. host.exec, host.fs and host.delegate run with no judgement of their own, inside a tool call or outside one: an extension has the account's full rights, and a process extension can start programs unseen (#39). host.tool exists so that a well-behaved extension's tool runs get the same denies, hooks and log as the model's, not to contain an extension.

Code mode

codemode is a first-party Lua extension that registers one tool, codemode, which runs a Lua script. The script calls tools with host.tool ("Running a tool"), filters what they return and prints only what the model needs. Every other tool the session can call is reachable this way: a built-in, an MCP server's tool or another extension's. Its shipped manifest raises the Lua memory cap to 16 MiB so an inner result reaches the script whole up to what fits.

State

An extension keeps what it knows in four places, by what the thing describes.

What it describesWhere it livesA rewind or fork
What happened in this session: a goal, what an inbox delivered, a test countextension state, in the session's logfollows the key's fork rule
What a person set: enabled models, a workspace URLhost.config, in Fiber homeleaves it alone
A secret: an API keycredentials/ (docs/model-routing.md)leaves it alone
What it keeps across sessions: a memory store, an indexits data directories (docs/state.md, "What each part holds")leaves it alone

Lua globals are none of these. They are memory, lost when the process exits and never moved by a rewind. Use them for scratch and caches only.

Extension state

state.get(key)
state.set(key, value, { on_fork })   -- on_fork: "at_point" (default), "latest" or "fresh"
state.unset(key)
state.keys()

Keys are strings. state.get returns nil for an absent key. state.keys returns a Lua array of keys sorted by byte order. Unsetting an absent key does nothing and logs no line. Invalid arguments, including a nil value, raise invalid_arguments; use state.unset to remove a key.

What writing a provider looks like

A provider extension is mostly data: its name, how its credential is found, and its models, each with a protocol, a base URL, flags and metadata. The wire protocols are native Rust, so a provider never parses a stream. What a provider declares, and why, is docs/model-routing.md. The file is providers/<name>.json (docs/configuration.md, "A provider's data"). Its Lua lives beside it in providers/<name>.lua, even when the extension also ships tools or hooks.

A provider may have five pieces of Lua:

Each function is { timeout, run }, like fiber.command: timeout in milliseconds, run the function Fiber calls. Only sign() runs while a request is being sent. It sees the body's SHA-256, never the body, and the time in whole Unix seconds as time. A sign() that errors or returns unusable headers fails the call with credential_failed (docs/errors.md). Here is providers/acme.lua for a gateway that lists its models at /models:

fiber.provider("acme", {
  models = {
    timeout = 10000,
    run = function()
      local key = host.secret("acme.api_key")
      local reply = host.http({
        url = "https://api.acme.dev/v1/models",
        headers = { authorization = "Bearer " .. key },
      })
      local list = {}
      for _, m in ipairs(json.decode(reply.body).data) do
        table.insert(list, {
          id = m.id,
          protocol = m.id:find("^claude") and "anthropic-messages" or "openai-completions",
          base_url = "https://api.acme.dev/v1",
          context_window = m.context_length,
        })
      end
      return list
    end,
  },
})

In plain terms: Fiber calls models.run when it needs the model list. The function fetches the API key, asks the gateway for its models, and returns one entry per model, choosing each model's protocol from its name. Fiber caches the list on disk and refreshes it in the background at startup. The function never runs while a request is being sent.

The first-party provider extensions are the fuller examples, including credential() and sign().

Writing a tool or a hook has the same shape: register a name, receive a call, do pure work plus host calls, return. The hook points are Hooks.

Testing an extension

Run fiber extension test in a package directory, or pass the package path. The runner reads each *.json file directly inside tests/, in filename byte order. Each file is one case. Its optional name defaults to the file stem. Each case runs with a fresh Fiber home and workspace.

Before any case, the runner checks each provider that has a providers/<name>.json file against its Lua. It loads the package in a temporary Fiber home and reads which functions the provider registered; it calls none of them. If credential() is registered and the data declares neither login nor credential_label, or if credential_label is declared and credential() is not registered, the run prints one fiber: line on stderr for each mismatch, naming the field to add or remove, runs no case and exits 1. Malformed provider data or a provider script that fails to load fails the run the same way, with one line. A provider with no data file is exempt.

Session cases

A session case requires script, expect and exactly one of prompt and command. script uses the format in docs/model-routing.md, "The scripted provider". expect lists the complete ordered durable event stream. Each expected object checks only its fields, so {"kind":"turn_completed"} checks the event kind. Ephemeral lines are ignored. Objects match a subset of fields; arrays and scalar values match exactly. An expected null matches a missing field or a field set to null.

command is an object with name (string, required) and text (string, optional; omitted is the empty string). The runner sends it as the protocol's command driver command after extensions_loaded, as a person typing /name text. A command case requires until and has no default. until may name an ephemeral kind (extension_ui, notice) with nth. A rejected command (unknown_command, extension_failed) fails the case with its code and message. Giving both prompt and command, neither, or a command case with no until is a malformed case (FAIL <name>, exit 2).

{
  "script": {"steps": [{"text": "Hello."}]},
  "prompt": "hi",
  "expect": [
    {"kind": "session_started"},
    {"kind": "fiber_started"},
    {"kind": "extensions_loaded"},
    {"kind": "preamble_built"},
    {"kind": "opening_message"},
    {"kind": "turn_started"},
    {"kind": "step_started"},
    {"kind": "assistant_message_started"},
    {"kind": "text_completed", "payload": {"text": "Hello."}},
    {"kind": "usage_recorded"},
    {"kind": "assistant_message_completed"},
    {"kind": "turn_completed"},
    {"kind": "fiber_exited"}
  ]
}

A command case names no turn, so its stream has none. The lines below are the ones docs/events.md proves for a session that runs no turn: session_started is the log's first line, fiber_started follows it in a new session, extensions_loaded is written before the first model request, and fiber_exited is the last line the process writes. That is the whole durable stream the export command cases observe: no turn runs, so nothing writes between extensions_loaded and fiber_exited. The expect lists in extensions/export/tests/export-writes-no-durable-line.json and extensions/export/tests/export-text-reaches-the-extension.json pin this order under docs/testing.md, "What a test asserts" ("A test asserts an order or a count only where a doc promises it"): the promise is expect lists the complete ordered durable event stream above, and each position is proved by docs/events.md as the preceding sentences cite.

{
  "script": {"steps": [{"text": "unused"}]},
  "command": {"name": "export"},
  "until": {"kind": "extension_ui"},
  "expect": [
    {"kind": "session_started"},
    {"kind": "fiber_started"},
    {"kind": "extensions_loaded"},
    {"kind": "fiber_exited"}
  ]
}

A case may add config, written as the temporary home's global configuration. A case may add settings, an object keyed by extension name; each value is written as that extension's global settings file, config/<extension>.json, in the temporary home (docs/configuration.md, "Extension settings"). host.http and host.exec list requests and replies in order. An HTTP reply has status and body, or an error with code and message. An exec reply has stdout and stderr and either code or signal, an integer signal number the extension sees as a name such as SIGKILL. A reply of {"hang": true} stands for a process that never exits: the scripted exec parks on the case clock until the callback's deadline, as a real host.exec parks on the injected clock. Requests match the fields the case gives; a mismatch, an unscripted call or an unused reply fails the case. These host replies prevent network requests and program execution.

clock is a list of positive advance_ms values. An entry may use after to name the event kind and its optional 1-based nth occurrence. An entry may use hang to name the 1-based exec entry it waits for: the runner holds that advance until the entry has matched as a hang. The runner advances only when the operation is parked on that clock deadline. After the last entry, a hang still parked fails the case, naming the request, and the runner advances to its deadline to end the session. until selects the event after which the runner closes the session; for a prompt case, by default it closes after the first turn_completed or turn_failed. attended defaults to true; attended: false runs the session with nobody attached, as it does for a call case: a call that would escalate to a person is denied instead ("Testing a tool that executes").

Provider call cases

A call case invokes a provider function without starting a session. It requires call with provider, function and arg, plus exactly one of returns or error. The runner supports cost, models, quota, login, credential and sign. A cost return is null or a finite number at or above 0. models takes {} with an optional key (a string or null) and an optional placeholders (an object of strings) as its arg, and its return is the model list, matched as a session case's expect is: an object checks only the fields it gives, an array matches in full, and an expected null matches a missing field. An error checks its code and may also check its message. The case can script the same host replies as a session case. quota takes {}, with an optional label and key; its return is null or the table quota() returned, matched as expect is.

The credential functions take these arguments:

credentials maps <credential>/<label> to stored JSON, written before the first call. expect_credentials checks those files after the calls, using expect's matching rules. Set exact_credentials to true to compare each listed file as a whole JSON value instead. In exact mode, extra object fields at any depth fail, and a missing field differs from a field set to null. The field defaults to false. A seeded credential listed with its seeded value is unchanged when its stored value equals the seed; the bytes need not match. Files not listed in expect_credentials are not compared. attended: false runs with nobody attached.

Use calls instead of call for an ordered list on one provider instance in one Fiber home. A case cannot have both. Each entry has call and exactly one of returns or error. An entry's optional clock advances before its call. Call clocks cannot use after, because call cases have no event stream. The case's top-level clock advances while its first call is parked on the clock deadline, as in a session case.

A calls entry {"await":"credential_idle"} invokes no function. It waits for the case's pair to finish fetching a credential, with a wall-clock bound. At the bound the case fails, naming the await. Put it between a sign that starts a background refresh and a sign that must use the refreshed credential.

host.oauth scripts OAuth calls in order:

A mismatch, missing reply or unused OAuth entry fails the case, as for host.http. Interactive calls still fail when nobody is attached.

{
  "call": {
    "provider": "openrouter",
    "function": "cost",
    "arg": {
      "generation_id": "gen-abc",
      "base_url": "https://openrouter.ai/api/v1",
      "key": "sk-test"
    }
  },
  "host": {
    "http": [{
      "request": {
        "method": "GET",
        "url": "https://openrouter.ai/api/v1/generation?id=gen-abc",
        "headers": {"authorization": "Bearer sk-test"}
      },
      "reply": {
        "status": 200,
        "body": "{\"data\":{\"total_cost\":0.0000072}}"
      }
    }]
  },
  "returns": 0.0000072
}

A package with no case files fails the command. An invalid package path is a usage error. The runner reports each case and exits non-zero if any case fails (docs/invocation.md, "Commands and flags").

Testing a tool that executes

A call to a tool that declares executes goes to the reviewer, as every reviewed call does (docs/permissions.md, "The reviewer"). A case has no field that approves a call, so it approves one through configuration: config sets reviewer.model to scripted/script.json, and the script's first step carries the reviewer's reply.

A case writes exactly one file into its workspace, the session script, so the reviewer reads the same script.json from its own step 1. The allow case's first step therefore carries both halves: "text": "allow" answers the reviewer's first stage, and the tool_calls entry is the session's call. The reviewer takes the text and never sees a tool call, because a review request carries no tools. The expected stream records the reviewer's verdict as permission_resolved with decided_by: reviewer and decision: allow, and the call runs to tool_call_completed with status: completed.

With no reviewer.model the call cannot be allowed: a notice with code no_model is written and the failure escalates (docs/permissions.md, "How it runs"). The escalation goes to a person as permission_requested, so a session case with no reviewer waits for an answer instead of finishing. Where no person can answer, such as a headless run (docs/permissions.md, "Headless"), the same failure denies the call with decided_by: no_reviewer and it never runs, and tool_call_completed has status: denied.

The reviewer's first stage answers allow or check; a check goes to a second stage whose reply is a reason followed by allow or block (docs/permissions.md, "Its verdict"). The case below answers the first stage with allow.

The launch tool declares executes and returns without a host call:

fiber.tool("launch", {
  description = "Launches the job.",
  input_schema = { type = "object" },
  timeout = 2000,
  effects = { effects = { "executes" }, reversible = false },
  run = function() return "launched" end
})

tests/launch-allowed.json sets the reviewer through config and expects the allowed stream:

{
  "script": {"steps": [{"text": "allow", "tool_calls": [{"name": "launch", "arguments": {}}]}, {"text": "Launched."}]},
  "prompt": "launch it",
  "config": {"reviewer": {"model": "scripted/script.json"}},
  "expect": [
    {"kind": "session_started"},
    {"kind": "fiber_started"},
    {"kind": "extensions_loaded"},
    {"kind": "preamble_built"},
    {"kind": "opening_message"},
    {"kind": "turn_started"},
    {"kind": "step_started"},
    {"kind": "assistant_message_started"},
    {"kind": "text_completed", "payload": {"text": "allow"}},
    {"kind": "tool_call_requested"},
    {"kind": "usage_recorded"},
    {"kind": "assistant_message_completed"},
    {"kind": "usage_recorded"},
    {"kind": "permission_resolved", "payload": {"decided_by": "reviewer", "decision": "allow"}},
    {"kind": "tool_call_started"},
    {"kind": "tool_call_completed", "payload": {"status": "completed"}},
    {"kind": "step_started"},
    {"kind": "assistant_message_started"},
    {"kind": "text_completed", "payload": {"text": "Launched."}},
    {"kind": "usage_recorded"},
    {"kind": "assistant_message_completed"},
    {"kind": "turn_completed"},
    {"kind": "fiber_exited"}
  ]
}

tests/launch-denied.json sets no reviewer and attended: false, so the same call is denied: no reviewer can be set up and nobody can answer. The denial is recorded as permission_resolved with decided_by: no_reviewer and decision: deny, no permission_requested is written, and tool_call_completed has status: denied:

{
  "script": {"steps": [{"tool_calls": [{"name": "launch", "arguments": {}}]}, {"text": "Denied."}]},
  "prompt": "launch it",
  "attended": false,
  "expect": [
    {"kind": "session_started"},
    {"kind": "fiber_started"},
    {"kind": "extensions_loaded"},
    {"kind": "preamble_built"},
    {"kind": "opening_message"},
    {"kind": "turn_started"},
    {"kind": "step_started"},
    {"kind": "assistant_message_started"},
    {"kind": "tool_call_requested"},
    {"kind": "usage_recorded"},
    {"kind": "assistant_message_completed"},
    {"kind": "permission_resolved", "payload": {"decision": "deny", "decided_by": "no_reviewer"}},
    {"kind": "tool_call_completed", "payload": {"status": "denied"}},
    {"kind": "step_started"},
    {"kind": "assistant_message_started"},
    {"kind": "text_completed", "payload": {"text": "Denied."}},
    {"kind": "usage_recorded"},
    {"kind": "assistant_message_completed"},
    {"kind": "turn_completed"},
    {"kind": "fiber_exited"}
  ]
}

Hooks

A hook is asked at a fixed point in a session and may change what happens there. Fiber has eight hook points. Each one runs before the thing it changes is written to the session log or sent to the model, never after. That one rule keeps two settled promises: the log holds exactly what happened (ADR 0001), and no hook rewrites a message the model has already been sent (docs/prompt-cache.md, "Rules for other areas").

A hook only changes things. Something that only needs to know what happened, such as a job that writes a worklog when a session ends, is a watcher: it reads the event stream (docs/events.md) and has no hook point. How an extension watches is Watchers.

The tool hooks, before_tool and after_tool, run for an extension's inner calls exactly as for the model's ("Running a tool").

The hook points

Hook pointWhen it runsWhat the hook seesWhat it may return
session_startA session starts, resumes, forks or rewinds, before the first model request; and at each compaction, once the note is readywhy it started, the session's id and workspace rootcontext to add
before_messageA person's or a driver's message arrives, as a turn's input or as steering, before it is loggedthe message's text and images, and for a session message the sender's id and its parent's ida replacement message, a refusal with a reason, context to add
turn_startA turn has started, before its first model requestthe turn's input and what started itcontext to add
before_toolA call has passed its schema check and its effects function, before permission is decidedthe tool's name, the arguments, the declared effects, paths and reversibilityreplacement arguments, a refusal with a reason
before_model_callA step's model request is built and the budget allows it, before it is sent (docs/loop.md, "Spending budget")the model reference, and the session's usage so far, its delegates included (docs/events.md)a refusal with a reason
after_toolA call that ran has returned, before its output is cut, its artifact is written or it is logged (a tool that already wrote its output to the call's artifact file has cut it first); and each job delivery, before it joins the conversation or is loggedthe tool's name, the arguments, status, the full output, or the cut output with its artifact file's path and size when the tool already wrote that file, details, process, and delivery for a job deliveryreplacement content, replacement details, text for the artifact
turn_endThe model has replied without calling a tool, so the turn would complete, before turn_completed is writtenthe model's final replya message to continue the turn with
before_compactionA compaction has started, before the note requestthe trigger, the person's instructions, and the conversation as Fiber's messages of content parts, without the note requesta compaction note (a string)

Returning nothing leaves things as they were.

Context a hook adds is appended to the conversation as its own message and logged as context_added, naming the extension. An extension that delivers an inbox of messages from other agents does it this way, at session_start or turn_start. session_start runs again on every resume, and each time its context is appended again. The hook sees why the session started, so an extension that must not repeat itself keeps what it delivered in its extension state ("Extension state") and adds only what is new.

session_start also runs at every compaction, with reason compaction, so what an extension adds at start is not lost when the conversation restarts. Extension state carries across a compaction but the model's context does not, so an extension that keeps what it delivered sees compaction and delivers it again, as it is now. The hook sees the reason, as at every other start, and not the compaction note. Its context follows the new opening message, before the turn's input and the note (docs/compaction.md, "What the model sees after a compaction"). A non-blocking hook that fails there has its context dropped with a notice, and the compaction completes ("When a hook fails"). turn_start does not run again, because the turn has not restarted.

before_message covers every message a person or a driver sends, so a secret pasted into a prompt can be removed before anything records it. A refused message is neither logged nor sent, and the sender is told why.

before_tool may rewrite a call or refuse it, but never approve one. Approval is the permission decision's (docs/permissions.md). Fiber checks rewritten arguments against the tool's schema and runs its effects function again, so the permission decision judges the call that will run, not the one the model asked for. A refused call completes denied with reason hook and the extension's name, and never starts.

The model's call is sent back to it exactly as the model wrote it. What ran is stated in the result instead: Fiber begins the result's content with a line naming the extension and giving the arguments that ran. That line is part of content, so the tool's size cap applies to it. Editing the model's own call would tell the model it asked for something it did not, and a provider that signs the reasoning before a call may reject the edited request.

before_model_call is where an extension enforces a spending limit, such as one a central service keeps. A refusal fails the turn with budget_exceeded, naming the extension, exactly as budget.usd does. It runs before every step's model request, so it must answer fast: an extension that reports spend to a service does that from a watcher on usage_recorded ("Watchers"), keeps the service's verdict in its state ("Extension state"), and the hook only reads it. A reviewer's call, a compaction note request, a host.model call and a cache-warming refresh (docs/prompt-cache.md, "Warming while idle") are counted in usage but never reach this hook.

after_tool runs on every call that ran: completed, failed and cancelled alike, since a cancelled command's partial output can hold a secret too. It does not run on a call that never started. What the hook returns is what the rest of the pipeline sees: the size cap applies to the returned content (docs/tools.md, "Bounded results"), and the artifact holds the hook's artifact text when it returns one, or the returned output when it does not, unless the tool already wrote the artifact file, as below. So a redaction hook removes a secret from the model's view and from disk in one pass, and the original output is never stored.

A foreground shell call whose output passes 1 MiB has already written it to the call's artifact file (docs/tools.md, "Result and output"), so its original output is stored until a hook rewrites the file. The hook gets the cut output, as the model would be sent it, with the file's path and size, and rewrites the file through host.fs under the per-path lock or returns artifact text that replaces it, as for an output_file. Every hook in the chain gets the same path and size. The file is the call's artifact: with no artifact text returned it keeps what the tool or a hook wrote there, and a returned content over the cap is cut with a notice naming it.

after_tool also runs on every job delivery: a job's completion notice, each batch of a monitor's lines, and a delegate's full, unbounded final message (docs/tools.md, "Background jobs"). It gets the tool name of the call that started the job, and delivery says what arrived: completion, monitor or delegate. A job an extension started with host.delegate passes "" as the tool name. When a job ends, it runs once more on the job's whole output file, with delivery output_file, and the artifact text it returns replaces the file. A Fiber delegate's events.jsonl is another session's log, so the output_file pass skips it. delivery is absent for an ordinary call. A completion delivery hands the hook, as content, the notice as the model would be sent it, with the job's status. An output file of at most 1 MiB is handed as content; a larger one is handed as path and size, and the hook rewrites it through host.fs under the per-path lock or returns artifact text that replaces it. When an output_file hook fails blocking, the file is replaced with a one-line note that the output was withheld; a non-blocking failure keeps the file and gives a notice. Apart from that large-file case, a redaction hook can ignore delivery and treat every input alike, so job output takes the same path as every other tool output. Two windows remain: while a job runs, its output file is written directly by the program, so it holds raw output until the job ends; and a foreground shell call's artifact file holds raw output past 1 MiB until the hook runs. An extension that compacts build and test output returns a short summary as content and the full log as the artifact text. The hook cannot change status: whether a call succeeded is the tool's answer.

turn_end runs only when a turn would complete normally, not when it is cancelled or fails. A returned message joins the turn at the step boundary as a steering message would, and is logged as steering_applied with the extension as its source. The model then takes another step, and turn_end runs again when that step ends without a tool call. Fiber puts no limit on how often a hook continues a turn. An extension that does this should keep its own limit in its extension state, and a person can always end the turn with the cancel key. A goal that keeps the agent working until a condition is met is built on this point.

before_compaction lets an extension write the compaction note instead of the session's own model. When a hook returns a note, Fiber makes no note request. When none does, Fiber makes its own (docs/compaction.md, "The compaction note"). With several hooks, each sees the note the one before returned, and the last note wins; compaction_completed.extension names the extension whose note was used. The hook does not run for a compaction a tool started, which already has its note. The hook is handed the whole conversation, so a Lua extension that registers it raises memory_mib to fit the conversations it handles.

What a hook is given and returns

A Lua hook's run gets one table and returns nil or one table, with the keys below; values use the shapes of docs/events.md ("Content parts", "Declared effects").

Hook pointWhat run is givenWhat it may return
session_startreason, why the session started: start, resume, fork, rewind or compaction; session_id; workspace, the workspace rootcontext, a non-empty string to add
before_messagecontent, the message's content parts as logged; from_session_id, the sending session, and parent_session_id, its parent, for a session message, each absent otherwisecontent, a non-empty list of parts that replaces the message: text parts, and image or pdf parts the message holds; context, a non-empty string to add; or refuse, a non-empty string, alone
turn_startinput, the turn's input as the turn_started event logs itcontext, a non-empty string to add
before_tooltool; arguments; effects, a list of effect names; paths, absent when the call declares none; reversiblearguments, a table that replaces the arguments, or refuse, a non-empty string, alone
before_model_callmodel, the model reference; usage, the session's usage so far, its delegates included, with cost absent when unknownrefuse, a non-empty string, alone
after_tooltool; arguments; status; content, the output's text parts joined; details and process, each absent when the call has none; details never hold the reserved file_seen record (docs/tools.md, "Stale files"); what a job delivery is given is in the after_tool paragraph abovecontent, a string; details, any value; artifact, a string
turn_endreply, the model's final replymessage, a non-empty string to continue the turn with
before_compactiontrigger, what started the compaction: auto, person or overflow; instructions, absent when there were none; messages, the conversation as host.model takes it, without the note request; note, absent until a hook before this one returned onenote, a string with the compaction note

Returning nil or an empty table changes nothing; so does a before_compaction note that is empty after trimming. A key a hook returns is a change, even when its value is the one it was given, so a check hook that returns arguments, content or context has failed; a check hook refuses with refuse. Any other key, or a value of another kind, is the hook's failure, which its on_failure decides ("When a hook fails"). Lua cannot tell an empty table from an empty list: arguments = {} is an empty object, but an empty table inside it comes back as a list.

When several hooks share a point

Hooks at the same point run one after another, in three phases. A hook names its phase when it registers:

  1. sanitize makes the content safe to handle, such as removing a secret or masking personal data. Sanitize hooks run first, so every later hook, including one that calls a network service, sees the cleaned content.
  2. transform changes or adds to it, such as rewriting a call's arguments or adding context. A hook that names no phase is a transform hook.
  3. check refuses or lets it pass, without changing it. Check hooks run last, so a check judges what will actually happen. A check hook exists only at the points that can refuse: before_message, before_tool and before_model_call; one registered at any other point is not registered. A check hook that returns a change has failed, and its on_failure decides what happens ("When a hook fails").

Within a phase, configuration can set the order of extensions at each hook point (hooks.order, docs/configuration.md). Extensions it does not name run after those it does, ordered by name, and one extension's hooks at the same point and phase run in the order it registered them. Each hook sees what the one before it returned. A refusal ends the chain. At session_start, turn_start and turn_end every hook is shown the same input and every return is kept, in run order. The order is fixed so that the same inputs give the same result on every run.

The order is precedence, not protection. Every hook runs with the account's full rights, so a hook placed later could read a secret from wherever it came from. Phases exist so that well-meaning hooks run in the right order: a company's redaction hook, shipped with its repository, runs before a person's own notifier sees the text.

When a hook fails

Every hook declares two things when it registers, and neither has a default. A hook that leaves either out is not registered. Its phase is optional ("When several hooks share a point").

What a blocking failure stops, at each point:

Hook pointWhat happens
session_startThe session does not start. Fiber exits with error hook_failed, naming the extension.
session_start at a compactionThe compaction completes failed with code hook_failed, as for before_compaction. The session does not exit.
before_messageThe message is neither logged nor sent, and the sender gets hook_failed.
turn_startThe turn completes failed with code hook_failed, before any model request.
before_toolThe call completes failed with code hook_failed and never starts.
before_model_callThe request is not sent, and the turn completes failed with code hook_failed.
after_toolThe call keeps the status the tool reported, since it ran. Its only content is a line saying its output was withheld because the extension's hook failed, and no artifact is written. A job delivery is withheld the same way. A foreground shell call's artifact file is replaced with the same line, as an output_file is.
turn_endThe turn completes failed with code hook_failed.
before_compactionThe compaction completes failed with code hook_failed, as a failed note request does.

What a hook cannot do

Recording a change

The log holds what a hook returned, never what it was given. Each line a hook changed names the extensions that took attribution for the change in changed_by, so a reader can see that a message or result was rewritten and by whom (docs/events.md). A change no extension took attribution for carries no changed_by key.

Handing a value to a hook and taking its answer back is cheap next to the hook's own work. A 16 KiB tool result crosses into Lua and back in under 10 µs, and a 1 MiB one in about 50 µs (macOS arm64, research/hook-conversion-cost).

Hooks declared in configuration

A person can declare a hook or a watcher as a command in configuration, without writing an extension. The first-party hooks extension, github.com/aakshintala/fiber/extensions/hooks, reads the declarations and registers each one as a real hook or watcher, so a declared hook follows every rule on this page. Installing Fiber installs it ("A fresh install"), and it loads only in a session whose configuration has a hooks key.

If a person removed hooks and configuration still declares hooks, they are not silently dropped. When any entry is blocking, a headless run fails with extension_missing, and the terminal offers to install hooks before the session starts, so a guard never fails open. When every entry is non-blocking, the session starts and a notice names the missing extension. An entry that is not an object fails the session with config_invalid, naming it, whether or not hooks is installed. When several entries are malformed, the error names the first in sorted key order.

The terminal asks in an overlay (docs/tui.md, "Look", "Overlays"): the title "Install hooks?", then "Configuration declares blocking hooks: ." dim, the names sorted and comma-separated, then two choices, "Enter" to install and start and "Esc" to cancel, with Enter's focused. The footer reads "click a choice". Enter runs the install fiber extension install hooks, then starts the session. When the install fails, no session starts and the overlay is replaced by the failure, naming fiber extension install hooks. When the terminal cannot read the declarations, it shows the refusal without the offer, and no session starts. Esc, the ✕ and a click outside start no session, run no hook point, and show the message the terminal shows without the offer.

The declarations are the extension's settings (docs/configuration.md, "Extension settings"), under hooks, one entry per name, so each layer adds entries instead of replacing the list:

{
  "hooks": {
    "fmt": {
      "point": "after_tool", "tools": ["edit", "write"],
      "command": "cargo", "args": ["fmt"],
      "timeout": 30000, "on_failure": "non-blocking"
    },
    "main-checked-out": {
      "point": "session_start", "command": "scripts/warn-main.sh",
      "timeout": 2000, "on_failure": "non-blocking"
    },
    "done": {
      "watch": ["turn_completed"], "command": "notify-send", "args": ["turn done"],
      "timeout": 2000
    }
  }
}

The command runs as host.exec runs a program ("Host calls"): in the session's workspace, in its own process group, with the session's environment. The command's program resolves as follows: a bare name on PATH, a path containing / against the workspace (the command's working directory), an absolute path as written. The package-relative rule is for host.exec and process.program only. It runs once for each time its hook point or event comes round.

What the command reads. Standard input carries one JSON line: the table a Lua hook's run is given at that point ('What a hook is given and returns'), with point naming the hook point and schema_version, or, for a watcher, the event.

How the command answers. Standard output may carry, as one JSON line, the table a Lua hook may return at that point. Two shorthands keep a shell script short:

Any other exit, exit 2 at a point that cannot refuse, a signal or a timeout is a failure, which the entry's on_failure decides. A failure is never a pass, so a blocking guard fails closed. A watcher's answer is ignored.

The extension registers its entries in name order, so declared hooks at the same point and phase run in name order. hooks.order places the hooks extension among the others.

A repository may declare hooks in its layer of these settings. Each one runs only after a person approves it, pinned to its exact content ("Code a repository ships"); one nobody has approved is withheld from what the extension reads, so the person's entry of that name runs unchanged. An approved entry merges key by key in normal layer order: the person's project and run layers still beat it. A repository cannot set hooks.order or a hook timeout override, so the order within a phase and every timeout stay the person's; an entry-local timeout is the hook's own. A hook's command and args strings that name repository files run from the pinned copy in Fiber home, never the repository: Inside paths map to their pinned files, Outside strings (including absolute symlink spellings) and unmapped names, flags and missing paths stay exactly as written, and gathered Inside symlink resolutions stay frozen. Only approved entries are installed, each through a blocking copy that rebuilds a pruned copy; a copy that cannot be made fails only that hook, classified by the repository's required. A skipped, unapproved or failed replacement never removes a running snapshot: only an approved and materialized replacement swaps it, and the old copy stays held until then. Watchers use the same authorized mapping and holds. A pinned script runs in the workspace, reads live workspace files outside its copy, and sees none of its unpinned siblings.

Watchers

A watcher learns what happened in a session and changes nothing. A worklog, a memory written as a session ends, and a counter of test runs are watchers.

A Lua extension registers one with fiber.watch(kinds, { timeout, run }), naming the event kinds it wants (docs/events.md). A process extension already reads the whole event stream as a client does, and asks Fiber to send it the kinds it wants in the stream it answers in order ("How an extension runs").

A watcher that falls behind loses ephemeral events and never durable ones, as any watcher does (docs/architecture.md, "Streaming"). A watcher that fails or passes its timeout gives a notice naming the extension. There is no on_failure, because a watcher changes nothing.

Commands and screens

fiber.command(name, { description, timeout, run }) adds a command. A person types /name and any text after it, which reaches run as its arguments. A driver sends the command driver command (docs/invocation.md). Names are plain: /databricks-models, not /databricks:models. When two extensions register the same name, neither gets it, a notice names both, and configuration can rename one. An extension may replace a built-in command by name, as it may a tool.

A lazy extension's declared commands appear in the / list and the commands answer from its manifest, without starting its VM: each entry carries the manifest's name, description and argument hint, the extension's name as its tag, and extension set to true, and the manifest's description and hint win over any in the fiber.command call. A disabled extension lists none. Configuration's rename (extensions."<name>".commands."<command>", docs/configuration.md) applies to a declared name. A same-name clash between two declared commands, or between a declared command and one a session-start extension registers, follows the rule above: neither gets it, and a notice names both. The clash resolves when the list is fixed, after every non-lazy extension has started.

The command driver command is answered with command_accepted once it is admitted, before run runs, and run's return value is ignored. A command reports through host.status, host.widget, host.ask or host.emit, and a run that errors gives a notice naming the extension. A command is allowed during a turn and joins the extension's ordered stream in session order; a host.drive inside it follows each driver command's own rules.

Running one of a lazy extension's commands starts the extension first, under the 2 s init.lua bound ("How an extension runs"); command_accepted still comes before run runs. A start that fails or passes the bound rejects the command with extension_failed, and the extension stays unstarted for the session, as one that fails at session start does; reload tries again (docs/invocation.md). A declared command the started extension did not register is rejected extension_failed, naming the command. Concurrent first runs share one start: later commands wait for it, and there is one VM and one init.lua run. host.ask(kind, spec) takes the keys of interaction_requested for that kind (prompt, options, fields) and returns the answer keys of interaction_resolved (confirmed, labels, text, answers, note), or { declined = true }. When the callback's timeout passes while a host.ask is pending, the interaction is resolved declined with by fiber. So is a pending host.ask when the session exits: the VM that waited for the answer does not survive the exit.

A command may run tools with host.tool. The person or driver who invoked it is the admission, and each inner call names the command's invocation ("Running a tool"). While a turn runs, a command's inner call starts at the next step boundary, in the order the calls arrived; a step waiting on an interaction leaves it queued. The command's timeout covers the wait.

A command talks to the person through the closed interactions every client answers (docs/architecture.md, "Asking a human"): confirm, select, multi-select, text input and form, raised with host.ask. A model picker is a multi-select and a setup wizard is a series of forms. host.status sets one line of status and host.widget sets a named block of lines. Both are data: each client shows them or not, and a client that attaches late gets the latest of each. In a session nobody can answer, such as one started by fiber ask, host.ask returns declined.

A session never sends drawing code to a client. An extension that draws carries a TUI extension: Lua 5.4 scripts in its package that run in the terminal's process, with the same embedding as a Lua extension, and reach the session only as a client does. It reads the event stream, including its session half's extension state and what that half sends with host.emit, and sends driver commands, including its own extension's commands. A crash in a TUI extension cannot stop the session (docs/invocation.md, "Processes").

A TUI extension registers each slot it fills with fiber.slot(name, { timeout, render, animate, on_key, on_click }), the same shape as fiber.command above: timeout in milliseconds is required, render draws the slot, and animate is present only on a slot that animates (docs/tui.md, "Animation"). A missing timeout fails at registration, as a missing callback timeout does ("How an extension runs").

on_key and on_click are optional, and each is { timeout, run } with its own timeout. on_key acts only on a slot that takes focus: the input box, a view or an overlay. run receives session_id and one of three keys: { key = "ctrl+o" } for a named key in the canonical grammar of keys, { text = "a" } for typed text, and { paste = "…" } for a bracketed paste as one event holding the whole pasted text. on_click acts on any slot whose spans carry click ids, and run receives { session_id = "…", click = "<id>" }. Each returns true when it handled the input, as fiber.key's run does below. Enter on a click target that has focus in navigate mode calls on_click as a click does (docs/tui.md, "Input and focus").

on_key, on_click, fiber.key's run and fiber.command's run make no host call: the terminal needs each answer before the next input. A host call from one raises a Lua error.

fiber.on_focus({ timeout, run }) runs run when the session on screen changes, with { session_id = "…" }, or no session_id key on home. It runs as an event handler does and may call host.http; any other host call raises a Lua error, as it does from on_key. Its return value is ignored. An extension registers it once, and a second call records one rejection and is skipped.

A TUI extension adds a slash command with fiber.command(name, { description, timeout, run }) in tui/init.lua, and run runs in the terminal's VM. It receives { session_id = "…", args = "…" }: the session on screen, with no session_id key on home, and the text after the name, "" when there is none. Only a true, false or nil return is ignored; any other value is a wrong-shape failure. run makes no host call, as the key handler's does not. The terminal shows one / list, and a name registered twice, by either half of any extensions, follows the rule above: neither gets it, a notice names both, and the configuration rename applies. A TUI command never takes a built-in command's name, so /quit and /reload stay reachable. Naming one records one rejection and skips that registration.

An animated slot declares animate = { interval_ms = N }, a whole number of milliseconds above 0: below 120 ms the terminal fires at 120 ms instead. Any other shape fails registration, naming the slot. Each frame reaches render with frame counting in its input, alongside the session id and the width. A plain list or { lines } keeps animating; { lines, animate = false } draws once and stops until the input changes. Any other return is the usual wrong-shape failure, and a frame past its timeout switches the extension off until /reload, exactly as a still call does.

Whole-screen keys

A TUI extension binds whole-screen keys with fiber.key(name, spec), registered only while the extension loads, where spec is { timeout, run } or { action, variant }. run is a function taking exactly { session_id = "…" } and returning true when it handled the key; timeout is its whole milliseconds above 0. action is a built-in action id with its optional variant, as keys binds them (docs/tui.md, "Bindings"); clear_then_quit is never bindable. Any other shape records one rejection naming the offending field, skips that registration, and loads on. The same canonical names as keys apply: Ctrl+O reads as ctrl+shift+o with that modifier, while a second spelling of one key, such as control+o for ctrl+o, is a duplicate and keeps the first.

A TUI extension has the host calls that need no session: host.http, host.exec, host.fs, host.config, host.data_dir, host.after, host.every, host.drive, host.log, the hashes and json. It has no host.model, host.delegate, host.ask, host.emit or state.set, since each of those acts inside the session. There is no process TUI extension: a program that wants to draw everything itself is a separate client of the hub.

What a TUI extension may change on screen is docs/tui.md, "Extension seams": every slot the terminal draws, the root layout, the key map and the slash commands. A future GUI's extensions take the same shape.

Client halves

A TUI extension, or any other client's half of an extension, belongs to the client.

Loading, and cost when nothing is loaded

Each Lua extension gets its own Lua VM and thread. At session start, every installed Lua extension with init.lua that is enabled for the project runs it, except a lazy extension whose manifest declares commands ("Commands and screens"), because a tool, hook, watcher, harness or search backend must register before the session's tool set is fixed (docs/prompt-cache.md, "Tools"), and Fiber cannot know a non-provider extension's registrations without running it. Each started extension costs about 120 to 150 KiB and a thread for the whole session. These cost nothing at start:

A provider-only package starts no VM until its provider file is needed. First use loads the file into the extension's running VM, or creates one when none runs. Providers in one extension share that VM. Model discovery on a missing or stale list uses the same path; its VM is dropped after discovery unless another provider or the extension's hooks, tools or commands still hold it. Fresh cached lists are read without loading provider Lua and show models only for providers with credential presence (docs/model-routing.md, "Credentials"). Providers without presence never run discovery. A cached list is stale when its age is past model_cache_age or its provider's extension source is newer than the cache; equal source and cache mtimes read fresh, and an unreadable source reads stale. The cache-side time is reconstructed as the current time minus the cached age (cached_at); a source newer than cached_at is stale, regardless of whether it is future-dated relative to now. Provider data and credentialed discovery ignore extensions."<name>".enabled; in a disabled mixed package, init, commands and hooks still stay off, even when its provider Lua starts later.

A provider file runs at most once per VM, including when it fails. A load that expires while still queued has not run and can be retried. Pending loads run before queued jobs. A load error, wrong or missing registration, or the 2 s bound fails first use with extension_failed, naming the file and reason. The rest of the extension keeps running, and its tools are unchanged. The exception is a load stuck where the hook cannot stop it: after the timeout plus 1 second, Fiber abandons the VM. That extension's tools, hooks and commands are unavailable until restart; other providers and the session go on.

A process extension costs its process from session start, because it must register before the session's first request. A TUI extension's VM is created before the terminal's first frame, since a replaced layout or input box changes that frame (docs/tui.md, "How a TUI extension runs").

One VM per extension (rather than one shared VM for all) costs about 120 to 150 KiB per extension — measured, research/extension-runtime/vm-isolation/ — and buys real isolation: each extension has its own globals, its own garbage collector, a per-extension memory cap, and a crash or runaway allocation contained to that one VM. A shared VM with per-extension environments is leaner at large extension counts and is the documented fallback if that ever matters.

Each Lua extension's memory is capped at 1 MiB by default. Past the cap, an allocation fails with a Lua error in that extension's VM, and Fiber does not read a file larger than the cap. A Lua extension measures about 120 to 150 KiB, and the busy-session budget is 24 MiB (docs/performance.md), so a small default keeps one extension from using the budget. An extension that needs more sets memory_mib in its manifest (docs/configuration.md, "An extension's manifest"). The install summary shows a raised cap ("What an install shows").

The reload driver command (docs/invocation.md) reloads extensions. It is how a running session picks up an installed or updated extension. Each reloaded Lua extension with init.lua runs it again in a new VM before the new tool set is declared, except a lazy extension that never started, which stays unstarted, and each process extension is restarted. Both are handed their current state again, as it stands in the session.

When an extension misbehaves

When a session ends

Fiber closes extension state, writes the lines it holds, then writes fiber_exited. From that close, state.set and state.unset fail with code closing.

On a normal exit, when a session is idle with no client or has been sent close, Fiber delivers every remaining event to each watcher and waits for each to finish, within its timeout. That is where a worklog or a memory written at session end runs. It writes to the extension's data directory (docs/state.md, "What each part holds"), not to extension state: these deliveries come after fiber_exited, the last line the log takes, so state.set, state.unset, host.model and host.drive fail with code closing. host.delegate is refused to a watcher at any time, so there it fails with not_available, not closing. A process extension then has its manifest's exit_timeout_ms to finish, and after that gets the shutdown sequence every child gets: SIGTERM, 800 ms, then SIGKILL (docs/invocation.md, "Shutdown").

Before replaying, the drain waits until no watcher delivery is still queued or running: a durable delivery the live fan-out already covered runs first, so tearing the session down after the drain cannot lose it. The drain replays each watcher's (cursor, end] log range — every line at or after the registration end the live fan-out did not already offer — in extension-name order, then watcher registration order. Each watcher runs once per line within its declared timeout; one past it fails, and the stream continues with the next watcher. A failure never becomes a notice: the log already holds fiber_exited, so it is printed on stderr under it, in every session, naming the watcher and its failure. A log the drain cannot read, or a line it cannot read, is collected and printed the same way, naming the drain instead of a watcher. host.fs and host.data_dir keep working through the drain; host.model and host.drive answer closing, and host.delegate stays refused to watchers, as ever.

When a signal stops Fiber, no extension code runs, as no hook does. The 5-second shutdown bound has no room for it. A signal that stops the drain makes Fiber exit with the signal's code; fiber_exited keeps the line it already wrote. A signal after the drain finished changes nothing.

Notes for authors

The extension API version

An extension's manifest names the major version of the extension API it was written for, as api (docs/configuration.md, "An extension's manifest"). The API is everything an extension touches: the registrations, the host calls, the hook points and what each receives, and the terminal's slots, their inputs, the span shape and the theme's roles (docs/tui.md, "Extension seams"). One number covers both halves of a package, because they ship together.

The API starts at 1.

Distribution

Names

An extension's name is where it lives, as with Go modules: github.com/owner/repo/path. A dependency is written the same way. Any git host works, there is no registry, and two authors cannot claim the same name. A local path also works, for an extension under development.

Without a marker, the first three parts of a name are the repository and the rest is a path inside it. A name can mark where the repository ends with a .git suffix, as Go does, so a repository inside subgroups can be named: gitlab.com/group/subgroup/repo.git/path. A name whose repository or tag does not exist fails with extension_not_found.

Every first-party extension also has a short name: its last path segment. First-party means every extension Fiber builds and ships, so every package under providers/ or extensions/ in Fiber's own repository has one, and a new package adds one. fiber extension install openrouter means github.com/aakshintala/fiber/providers/openrouter. Today the provider short names are anthropic, openai, gemini, codex, openrouter, opencode, databricks, muse, bedrock, vertex and azure, and claude, cursor-agent, hooks, init, memory, export and codemode are short names for github.com/aakshintala/fiber/extensions/<name>. A harness's short name is the name it registers (docs/delegates.md, "Harness extensions"). azure, claude and cursor-agent are not built yet: see #224, #545 and #546. A short name also names the extension's directories in Fiber home (docs/state.md, "What each part holds").

The first-party provider extensions live in Fiber's own repository, one directory each under providers/, so muse is github.com/aakshintala/fiber/providers/muse. They are versioned by Fiber's release tags, and CI tests them against the binary built from the same commit.

Fiber fetches with the system git, so your SSH keys and credential helpers apply. If git is missing, the command fails with a stable error.

Versions

A version is a git tag, such as v1.4.0. When extensions depend on the same extension, Fiber installs the lowest version that meets every stated minimum. If openrouter needs oauth-helper 1.2 or later, databricks needs 1.4 or later, and 1.9 is the newest, Fiber installs 1.4. The same inputs always give the same result, so there is no lockfile and no solver. A newer version arrives only when something raises its minimum.

A git address a person installs by name gets the repository's newest version tag. A repository with no version tag cannot be installed from its git address: the install fails with extension_not_found. A local path install needs no tag.

A version a person installed or updated by name counts as one more minimum, and it stays until they remove that extension. So fiber extension update <name> on a dependency keeps the newer version, and the same installed set always gives the same result.

Updating everything, with fiber extension update and no name or with fiber update, moves every installed extension, dependencies included, to its newest tag within the major version every extension that needs it accepts. A dependency moved this way keeps the new version as a floor. Later installs and removals never resolve it lower, but a floor does not keep the extension installed: when the last extension that needs it is removed, the dependency and its floor go too.

Two extensions that need different major versions, such as 1.x and 2.x, stop the install with version_conflict, naming both. So does a minimum that no tag meets. A pre-release tag, such as v0.0.1-nightly.20261030, counts only when some minimum on that extension is itself a pre-release. It then counts like any other tag, and sorts below the stable release on its base.

Fiber records the exact commit it installed and loads only that. Nothing is signed. The fetch runs over TLS or SSH, and a binary is checked against the sha256 in its manifest. Fiber downloads only the binary for the platform it is running on. A download that connects to no address within 15 seconds, or receives nothing for 300 seconds, fails with fetch_failed.

Installing

CommandWhat it does
fiber extension install <name>Installs an extension and its dependencies. If any part fails, nothing is installed.
fiber extension update [<name>]Moves one extension, or every installed extension when no name is given, to its newest version and re-resolves dependencies. A version updated by name stays a minimum, and a dependency moved by updating everything keeps a floor (see Versions). It never touches a repository's extension.
fiber extension remove <name>Removes an extension, and any dependency nothing else uses. It fails with extension_not_installed when no directory exists under the name, and deletes nothing.
fiber extension reinstall <name>Removes an extension and installs it again. When its install record can be read, it installs the recorded source at the recorded commit. When the extension is damaged, it installs <name> as given, a short name or a git address.
fiber extension listLists installed extensions with their versions and commits, and each repository extension with its project, its path in the repository and the content it loads.
fiber approve [--yes]Shows everything the current repository declares and approves it ("Code a repository ships").

An install from a git address needs a version tag (see Versions).

In a terminal, install and update show a summary and ask before going ahead. The summary is the one in What an install shows, and on update it adds the diff since the installed version. Without a terminal they go ahead without asking, so scripts can set up a machine. Choosing a provider in the terminal's model picker installs it without asking: choosing it is the approval.

Each prints installed <name> on stderr for every extension it put in place.

Installing an extension that is already installed installs it again: a name at its newest version, a path from that path's current files. An extension installed from a path keeps its path, so fiber extension update on it installs again from that path, not from a tag. fiber extension list shows local in place of the commit for an extension installed from a path. The step runs at the extension's final path, never in a temporary directory, because a step such as creating a Python virtualenv records its own location.

Install refuses an extension whose manifest needs a newer Fiber than the one running, or a different extension API version, with extension_incompatible. Update fiber, or install a version of the extension that fits.

A fetch that fails, because git or the network failed, stops the install with fetch_failed. Neither it nor version_conflict is retried automatically.

Installed extensions live in Fiber home, one directory each, at extensions/<name>/.

A damaged extension does not block the others. Each extension's directory holds an install record, .fiber.json, which says what was installed and from where. A directory whose record is missing or cannot be read is damaged. It can be left by an install that was killed, a disk error, or a directory copied in by hand. Fiber treats it the same way in every command:

Every message names the extension and the fix: `opencode` is damaged; run `fiber extension reinstall opencode`. No operating-system error is shown for a damaged extension, and skipping one does not change a command's exit code.

Installing an extension runs none of its code, except an install step its manifest declares, such as npm ci. Fiber runs that step in the extension's directory at install and at every update. A step that runs longer than 1800 s, and a git call that runs longer than 300 s, is stopped and fails the install. Fiber does not pass --ignore-scripts, so a dependency's own install scripts run too, and the install summary says so. A pure-data provider is only ever read. A provider's providers/<name>.lua waits for first use or model discovery. Other enabled Lua extensions run init.lua at session start ("Loading, and cost when nothing is loaded").

A fresh install

A fresh install has every first-party extension: the ten built providers, the Claude Code and cursor-agent harnesses (not built yet: see #545 and #546), hooks, init (docs/system-prompt.md, "Skills"), memory (docs/memory.md), export and codemode ("Code mode"). They arrive in the release's extensions archive, which install.sh installs into Fiber home's extensions/ (docs/releasing.md), so a first run needs no git and no network beyond the download. They are ordinary extensions, recorded under their full names: nothing is compiled in, and fiber extension remove <name> removes any of them.

Installed is not switched on. A provider is switched on exactly when it has credential presence (docs/model-routing.md, "Credentials"). Without it, the provider shows no models and never refreshes its list. Login supplies a stored credential; removing the last one switches the provider off unless another source remains. Logout leaves the extension and model cache installed. External-source providers use their declared environment variables or paths, not fiber login. Presence checks do not validate or acquire credentials.

A provider, hooks, init, memory or export costs nothing in a session that does not use it. A provider that is pure data is only read, a Lua provider runs only to refresh a stale model list or when a session uses one of its models, and hooks loads only when configuration has a hooks key. init has no code, and its one prompt template is read only as a skill. memory has no code, and its opening-message section adds nothing while the store is empty. export runs nothing until the first run of /export.

A person who removed a provider can install it again with fiber extension install <name>, or by choosing it in the terminal's model picker. A headless run whose provider is not installed fails with extension_missing. Its message names the first-party extension that serves the provider, so opencode-go/<id> says to run fiber extension install opencode. For a provider no first-party extension serves, it says to install the extension that provides it, by name or URL. An extension a repository declares and nobody has approved is skipped, or fails the run when the repository marks it required ("Code a repository ships").

Staying current

fiber update updates the Fiber binary and every installed extension together, so a new Fiber and the extensions written for it arrive at the same time. The first-party extensions come from the same release's extensions archive, so they always match the binary. A repository's extensions are not among them: one changes only through a new offer ("Code a repository ships"). fiber extension update <name> updates one extension, and fiber extension update with no name updates every extension.

Nothing checks for updates on a timer. Extensions change only when someone runs one of these commands, so an idle Fiber does no work.

Code a repository ships

A repository can ship three kinds of code: extensions, hooks declared in configuration ("Hooks declared in configuration") and MCP servers (docs/mcp.md, "A repository's servers"). All three follow one rule: the repository declares the code, the session offers it, the person approves it, and the approval holds for the exact content, so a change brings a new offer. A cloned repository is someone else's text, read before anything is approved, so nothing it declares runs before a person has seen it.

Declaring. A repository lists the extension packages it ships in .fiber/config.json, under repository_extensions, each as a path inside the repository and whether the repository needs it (required) (docs/configuration.md). It declares hooks in the hooks extension's settings and MCP servers under mcp.servers. A package's client half never loads from a repository ("Client halves"): only its session half is offered.

Offering. Before its first model request, a session gathers everything its repository declares that has no approval for this project and this content, and raises one offer listing all of it, so approving costs no prompt-cache rebuild. Each item shows what an install shows ("What an install shows"), and an item whose content changed shows the diff against the copy approved before that is still kept, or none. For each item the person chooses: approve, skip for this session, or never. The offer is its own event pair, repository_code_offered and repository_code_resolved, never an interaction a model or an extension raises (docs/events.md, "Repository code"). Any client may answer, local or remote, and the first answer wins (docs/invocation.md, "Replying").

Whether the session waits depends on whether a client that can answer is connected, not on how the session started. A client that can answer is a full connection, direct or through the hub: the connections clients counts. A summary connection and the fiber ask door never are.

Approving outside a session. fiber approve, run in the repository, shows everything the repository declares now, as one offer would, and approves it. --yes approves without asking, for a script or a machine image. It is the only way to approve without a session, and only a person runs it: nothing in configuration or in a repository starts it. It prints each approval it records on stderr.

Pinning. An approval holds for one SHA-256 hash of the content:

A path counts as inside the repository after symbolic links are resolved, so a link that points out of the repository is not pinned. What a pinned program fetches or reads while it runs is not pinned: a server started with npx -y can run different code later under the same approval, and a hook script that reads other files of the repository reads them as they are now.

Approval pins the declaration and the repository files that a command or args entry names, and nothing else. A script that finds a file beside itself by its own path, such as $(dirname "$0")/lib.sh, does not find it in the pinned copy, because only the files named were copied. A path relative to the workspace reads the live file. A package extension pins all its files, so it has no such gap.

Every approved version is kept. All worktrees of a repository are one project, but each branch can carry its own version of a package. Each session loads the version that matches its own worktree's files, so two sessions on two branches each run their own, and switching back to a branch finds its version still approved. fiber sessions prune removes pinned copies that no worktree matches any more, and keeps their approvals (docs/invocation.md, "Deleting and pruning").

What an approved extension may do. Everything an installed one may. Its manifest declares the built-ins it replaces and the providers it registers, with their base URLs ("What a package holds"), and the offer states each in plain words, such as "replaces shell" or "registers provider acme at https://api.acme.dev/v1".

Scope. An approved repository extension loads in its project only. fiber update and fiber extension update never touch it: it changes only through a new offer. fiber extension remove <name>, run in the project, removes it and records never for that content, so it is not offered again until its content changes.

Where approvals live. An approval, or a never, is recorded per project and content for extensions and hooks, and per machine for an MCP server (docs/state.md, "What each part holds"). A repository cannot write or read them.

What a session checks at start. It hashes only the paths its repository declares, never the rest of the tree. One index in Fiber home records each declared path's size, modification time and hash, so a session reads an unchanged file only to compare those two (docs/performance.md).

A person can still install a repository's package as their own, with fiber extension install ./tools/fiber-lint. That is an ordinary install, global unless --project is given, and does not follow the repository's copy.

The same extension, declared and installed. When a repository declares an extension that the person also installed, under the same name and so the same git address, the repository's approved, pinned copy loads in that project and the personal install loads everywhere else. The order is the one skills use: repository before personal ("Skills" in docs/system-prompt.md). It holds for first-party extensions too. A notice with code extension_shadowed names both versions, so a personal install that is newer than the repository's copy is visible. When one load shadows several installs, the pass raises one grouped notice: its message gives the count and lists each install with both versions. Two repository copies of one name load the same way: the first declared loads, and the same notice names both versions.

Commands that read an approved copy. A session loads its project's approved, pinned copies. Three commands read the same set when run in the project: fiber models lists the providers the approved copies register and runs their model lists, fiber login logs into those providers, and fiber config checks a config set model reference against them and prints their load notices. Run outside the project, each reads the personal installs only. No other user-facing command reads approved copies: the hidden fiber refresh-model-lists child reloads the same set to refresh the providers' cached lists.

An extension can be scoped to projects. fiber extension install --project installs it for the current project only: it loads in that project's sessions and no others, except for provider data and discovery, whose switch is credential presence. In a mixed package, its non-provider init, commands and hooks remain project-scoped. Approved repository copies retain their existing project scope. The personal-install scope is the person's extensions."<name>".enabled key: false in the global configuration and true in the project's, both in Fiber home (docs/configuration.md). A repository cannot set it. For each extension the command installs for the first time, its dependencies included, it writes false globally and true for the project. For one already installed, it writes only the project's true, so it never turns off an extension that is on elsewhere. It writes the keys before it installs, so a failed install leaves nothing loading outside the project. A plain install, update or remove never writes or clears the key; fiber config set extensions."<name>".enabled true enables a scoped extension everywhere.

What an install shows

fiber extension install, fiber extension update and an offer ("Code a repository ships") show:

The summary shows what the manifest and the files tell. It does not list the new tools, hooks, watchers or commands an extension adds: a Lua extension registers those only when its script runs, and installing runs none of its code. The full source is one key away, so a person can read them. An offer lists each item's files; a client reads one with offered_file (docs/invocation.md, "Driver commands").

Comparisons with other tools, and the owner's usage, behind this area's rules: research/reference-comparisons/README.md.