fiber

Tools

What every tool shares: what it declares, how a call is checked and bounded, and what its result carries on the log and to the model. This is what is true now, not a plan. It is settled by The tool contract: what every tool shares; that ticket's resolution holds the rationale and the rejected alternatives.

The first-party codemode extension adds one tool that runs a script calling the session's other tools (docs/extensions.md, "Code mode").

Vocabulary is GLOSSARY.md. Tool call, effect, artifact, participant, seam, extension and event mean what it says there and nothing else. How effects are judged is docs/permissions.md; the events themselves are docs/events.md.

What a tool declares

Before a call runs

What a result carries

tool_call_completed carries, beside status, reason, error and process (defined in docs/events.md):

What a result proves

Content states what was observed, never "success": the lines an edit changed, a command's exit code, the bytes written. Each tool's specification carries this as an acceptance criterion; nothing can check it mechanically. Whether a call ran at all is proved by the log structure (docs/events.md, resume table), not by content.

Bounded results

Progress

While a call runs, it may stream output and progress as tool_call_delta, which is ephemeral. Fiber paces updates to at most one every max(100 ms, encoded bytes ÷ 100 KiB/s); the first change after idle goes out immediately, held changes collapse to the latest, held output is capped at its newest 64 KiB, and completion forces a final flush.

Cancellation

cancelled means the tool stopped. Fiber interrupts every kind of tool itself rather than asking it to stop: it kills a process's process group ("Shell", "Stopping a command"); it raises an error inside running Lua through mlua's instruction hook (Lua::set_hook, whose documentation says the error "will be propagated through the Lua code that was executing"); it closes the socket of a network call made through the host, as it does for a model request; and a built-in Rust tool checks for cancellation between chunks of work. The loop writes tool_call_completed with status: cancelled only after the tool has returned, so the log never calls a call cancelled while it can still change something. The one wait it cannot cut short is a read blocked in the kernel, such as on a hung network filesystem. The second is an MCP call, which Fiber can only ask to stop: it ends failed with code mcp_cancel_requested, never cancelled (docs/mcp.md, "Calls").

File tools

Settled by File tools: read, write and edit; that ticket's resolution holds the rationale and the rejected alternatives. How reference agents do it is research/file-tools/reference-agents.md; the owner's usage is research/file-tools/usage.md.

There are three: read, write and edit. There is no listing tool, and read on a directory fails with unsupported_file and points to the shell. Search runs through the shell ("Search").

A relative path is resolved against the workspace. A symbolic link is resolved to its target, and the target is the path the call declares, so permission and the credential deny (docs/permissions.md) judge where the bytes really go.

A file tool's subject is that resolved path, and the prefix it offers is the path's directory, ending in /.

read

write

edit

Stale files

How a change lands

Settled by Search: built-in tools or the shell?; that ticket's resolution holds the rationale and the rejected alternatives. How reference agents search is research/search/reference-agents.md; the owner's usage is research/search/usage.md.

There is no tool for searching code. The model searches with grep and find in the shell, and inside the shell tool those two names run a search built into Fiber.

How it runs

Behaving like grep and find

Flags

What it skips

Other command-line tools

Shell

Settled by Shell: running a command, and when it becomes a job; that ticket's resolution holds the rationale and the rejected alternatives.

Running a command

Timeout

Moving to the background

When a command ends

Stopping a command

Result and output

Terminal (tty)

Effects

Background jobs

Settled by Background jobs: one killable object; that ticket's resolution holds the rationale and the rejected alternatives. The kinds are docs/events.md.

The keeper

Settled by Background jobs and delegates survive a session crash.

A keeper is the process that runs a session's jobs, so they outlive a crash of the session. The tree stays a tree: the session, then its keeper, then its jobs and delegates. No hub is involved, so a headless run needs no hub.

Asking the person

Settled by Asking the person a question; that ticket's resolution holds the rationale and the rejected alternatives.

The model asks with ask_user. The question goes to whoever drives the session. A person answers it through a form interaction. A program answers by resuming the session.

How a session started decides who drives it. A session the hub started is driven by a person until it is sent close, unless it was started supervised. Every other session is driven by a program, such as a delegate (a fork included), a supervised session or a fiber ask session.

The call

ArgumentRule
questions1 to 4 items
questionthe full question, with its context
headera short label, at most 12 characters
optionsnone, for a free-text question, or 2 to 4, each a label and an optional description
multiSelectoptional; the person may choose several options

When a person can answer

This is a session the hub started without supervised, which any client may answer.

When a program drives the session

This is every session the hub did not start, such as a delegate (a fork included) or a fiber ask session, a supervised session, and a session that has been sent close.

A child's question goes to its parent, never straight to the person. The parent wrote the child's brief and can usually answer, and the person is never interrupted by a session they did not start. An approval is different: no model may answer one, so a delegate's or a supervised session's escalation is a block (docs/permissions.md, "Delegates", "Supervised sessions").

The result

For each question, one line: <header>: followed by the chosen labels, the typed text in quotes, or skipped. A note: line follows when the person added a note to the whole form. Several labels are separated by , ; typed text follows the labels as a JSON string, and the note is a JSON string too. A header or label is written with JSON's escapes but no quotes, so every question stays on one line. A cancelled form is the single line declined.

A declined form is an answer, not a failure: the call completes with status completed. The structured answers are on interaction_resolved.

Saving reviewer notes

The model saves reviewer notes with reviewer_notes_save. It drafts the notes as lines: one item per bullet or read-only entry.

ArgumentRule
linesthe draft lines, one item per bullet or read-only entry
topicthe heading the line belongs under: source_control, internal_hosts, internal_tools, routine_actions, never or read_only_commands
layerthe layer the line belongs in: global or project
textthe bullet text, or the entry line for read_only_commands

Read-only command lines under the read_only_commands topic parse as entries; every other topic merges its sent lines into its layer's notes: what the layer owns less what was sent is struck, what was sent is added, for that topic only.

Before anything is written, the call reads both layers and raises one confirm carrying the diff and the entries it would write. Entries identical to the layer's own table converge and are left out; a changed entry, an unparseable read-only line or a malformed table fails before the confirm. The confirm never suspends: the person is already deciding. On yes the call writes the files of the layers that changed and names each written file with its added and removed counts; on no, or when nothing changed, it reports unchanged and writes nothing. A declined confirm is the single line declined.

The tool needs the person's confirm, so in a program-driven session it refuses naming fiber ask. The tool declares no effect, so it never reaches a reviewer (docs/permissions.md, "Fast paths").

reviewer_notes_save is strict: its schema uses only the strict keywords. Its serialized definition stays under 1200 bytes, and it counts toward the built-in budget ("Size budget in CI").

Settled by Web fetch and web search; that ticket's resolution holds the rationale and the rejected alternatives. How reference agents do it is research/web-tools/reference-agents.md; which providers host a search, and the search services a backend can call, is research/web-tools/providers.md.

There are two tools. web_fetch is compiled in and runs on this machine for every provider. web_search is a provider's hosted search where the model's provider offers one, and otherwise Fiber's own tool over an installed search backend.

web_fetch

HTML to markdown

Fiber converts a page in one pass: html5ever's tokenizer, with no document tree, feeds Fiber's own single-pass writer (docs/dependencies.md, "Runtime dependencies"). Every character reference is decoded per the HTML standard. It handles a stated subset of HTML, not the WHATWG parsing algorithm:

On any input, however malformed, the converter promises three things:

Formatting may come out wrong, such as a complex table or a misnested list. That is accepted, because the raw page is in artifacts/.

Before converting, Fiber decodes the page by its declared character set, from the Content-Type header or the page's <meta charset>, with encoding_rs (the WHATWG Encoding Standard). A page with no character set, or one Fiber does not know, is read as UTF-8, and bytes that are not valid UTF-8 become �.

Hosted by the provider

Fiber's own, over a backend

Effects

Naming the session

The model names the session with name_session, so the session list, the terminal's header and its title show what the work is about rather than the first prompt.

Messaging other sessions

Settled by Intercom: messaging a session you did not start; that ticket's resolution holds the probes and the rejected alternatives.

A session sends a session message to another running session of the same account: one it did not start, a sibling delegate, or a session in another project. Messaging a session's own delegates is delegate_message (docs/delegates.md).

ToolArgumentsWhat it does
session_listnoneLists every running session of the account, delegates included.
session_messageid, textSends a session message to one running session.

session_list shows running sessions only. Each entry has the session's id, its name, its workspace, and its parent's id when it is a delegate. A session is running when it answers a summary subscription on its socket with its latest session_status (docs/events.md), which is also where its name, workspace and parent come from. A socket whose lock a keeper holds is no session: the call does not connect to it, so a keeper that kept its jobs after a crash is never listed (docs/invocation.md, "Processes"). The list includes the calling session, marked as itself, so the model can see its own id and name. The tool declares reads. The call connects to every session's socket at once and waits at most 2 s in all, for up to 1,000 running sessions (docs/performance.md). A session that accepted the connection but sent no session_status in time is listed by id with answering: false.

session_message addresses a session by its full id. The model lists sessions first, so a name or a prefix would add ambiguity and save nothing. The text is plain text; a session message carries no images.

A session message reaches only a running session. The sender connects to the target's socket, sends the driver command message, reads the answer and closes the connection at once, so it never keeps the target alive (docs/invocation.md, "Lifecycle"). The target runs before_message before it answers, so the call answers delivered only once the target has taken the message and its hook has passed. delivered means the target took the message. A shutdown or a rewind of the target before it runs the message drops it, as it drops queued steers, and so does a close that fails the target's run while a required repository item is unanswered. Otherwise it fails with one of:

A session may message itself. The message arrives as steering at its own next step, which lets a test drive the whole path with one session.

A message for a session that has exited belongs on the ticket or with whoever orchestrates the work. Fiber keeps no mailbox. An extension that runs persistent seats replaces session_list and session_message with its own, and keeps what mail it needs (docs/extensions.md, "Registering").

The target takes it as it takes any message. It enters the loop's inbox (docs/architecture.md, "One inbox"). During a turn it is a steering message and joins at the next step boundary. Between turns it starts a turn (docs/loop.md, "Starting a turn"). before_message runs on it with the sender's id and its parent's id, so an extension can rewrite or refuse it, or refuse every message from outside its own tree. It is logged with source session (docs/events.md, "Where a message came from"). A session message is not a person's or a driver's prompt, so it never makes an unattended session attended (docs/invocation.md, "Lifecycle"). The model sees it framed with the sender's id and name. The name is the one the sender was given: the latest session_named in the sender's log, read from the end of the log backwards, set by the model or the person. A sender with no name, or whose log the target cannot read, is given by its id alone, never by its first prompt, which is long text written for a different session. The target reads the name as the message arrives and logs the framed text, so a resume sends the model the same bytes. The framing is a fixed template in crates/loop/prompt/messages.md (docs/system-prompt.md, "The texts").

A session message is not the person's voice. The target's reviewer never reads one as the person's instructions (docs/permissions.md, "The reviewer"). It is a request from another session, and the target's own reviewer judges what it does about it.

Sending declares writes, not reversible. It changes what another session does, so the sender's reviewer judges the send.

Nothing limits how many messages sessions exchange. Two sessions can wake each other indefinitely while no person watches. An extension can refuse messages in before_message, and budget.usd stops each session once it has spent its limit (docs/loop.md, "Spending budget"). On a subscription the budget counts nothing, so only the subscription's own limit ends the pair.

Delegates on another harness receive through their parent. The parent binds the delegate's socket and delivers what arrives; the delegate sends through fiber mcp serve (docs/delegates.md, "Delegates on another harness").

Both tools are declared in every session, so they never differ between sessions. Their definitions count toward the built-in budget ("Size budget in CI").

Searching past sessions

session_search finds text in the logs of this project's sessions, past and running, so the model can find earlier work: what was decided, which command ran, which file changed, or where an error appeared. fiber sessions search runs the same search for a person (docs/invocation.md, "Commands and flags").

Provider quota

Settled by Provider quota the model can see; that ticket's resolution holds the rationale and the rejected alternatives.

The model sees how much quota each provider has left, so it can choose a delegate's model with that in mind. It only reads quota. The session's own model is the person's to choose (docs/model-routing.md, "Choosing the model"), and Fiber never switches it on the model's behalf.

Where it comes from

A provider supplies quota through an optional Lua quota() function (docs/model-routing.md, "Quota"). It is called once per credential label, because each label is its own account (docs/model-routing.md, "Credentials"). A provider without one reports no quota. Of the first-party providers:

ProviderSourceReports
ChatGPT/codex/wham/usagepercent used of a primary and a secondary window, with reset times
OpenCodeGET /zen/go/v1/usagepercent used of Go's rolling, weekly and monthly windows, with reset times; Zen reports none
OpenRouterGET /api/v1/keycredit remaining and the limit, for a key with a limit; a key without one reports none
Anthropic, OpenAI, Gemini API, Databricks, muse, AWS Bedrock, Google Vertex, Azurenoneno quota reported

muse's x-ratelimit-remaining-* headers are a per-minute rate limit, not quota. No provider's quota is read from response headers.

A harness extension may declare quota() in the same shape (docs/delegates.md, "Harness extensions"). It is the only source for quota that no Fiber provider can see, such as the Claude subscription, which Fiber reaches only by running Claude Code.

HarnessSourceReports
Claude Code/api/oauth/usage with Claude Code's own login, and the rate_limit_event lines a running delegate printspercent used of the five-hour and seven-day windows, with reset times
cursor-agentnone yetno quota reported

What the model sees

delegate_models returns one quota entry per provider credential label and per harness beside the models it lists (docs/delegates.md, "The tools"). There is no separate quota tool. Each entry is one of:

Until the loader has checked every provider for quota(), the quota section is the one line Quota: loading. Once it has, a session with no credentialed label reads Quota: none.

A window whose reset time has passed shows as reset. Quota never appears in a tool definition or the system prompt (docs/prompt-cache.md, "Tools").

The notice

When a window crosses quota.notice_at percent used (default 80), one line naming the provider, the credential label, the window and its reset time goes into the model's next turn input. It fires once per crossing, and again for that window only after it resets (its reset time has passed, or a later reading is below quota.notice_at). A credit with a positive limit counts as the window credit, at 100 × (limit − remaining) / limit percent used. It has no reset time, so it fires again only after a reading below quota.notice_at. The line leaves out the reset time when there is none: for a credit, and for a window whose provider reports no reset time. The notice is the durable event quota_noticed (docs/events.md, "Usage and notices"). An OpenRouter key without a limit reports no quota, so it never gives a notice.

Fetching

Each provider credential label has one cache holding its last value, when it was fetched, and any fetch in flight. Concurrent readers share one fetch. What the person is shown reads the same cache, and shows no age.

The first quota driver command or delegate_models call starts a loader on its own thread. It starts providers that have a credential label and checks whether they register quota() before reading any key. Each label's key is read once per process, as a model switch to that label reads it. A provider whose quota() is asked for at least one label stays loaded for the rest of the process. A provider without quota(), or whose every label's key read failed, is unloaded at once. A failed read reports unreachable, while the other labels still answer. Shutdown ends the reads; a read already in flight finishes and its result is dropped. The loader starts a quota fetch for each label whose read succeeded. Without fetch, the command answers from the caches at once, without waiting for loading, credential reads or fetches.

A fetch runs off the request path when the cache is older than 5 minutes and one of these happens:

/quota always fetches. Nothing refetches on a timer, so an idle Fiber does no work, and a person returning to the terminal gets a fresh figure on focus. A fetch times out after 8 seconds. A failure is reported as unreachable, never as an error.

Skills

skill loads one skill for the model: the name goes in, and the skill's SKILL.md body comes out, read from disk at that moment. What a skill is, where Fiber finds skills and how the listing is built are docs/system-prompt.md, "Skills".

Built in or extension

A first-party tool is compiled in unless its behaviour depends on a vendor or on the person's environment. Read, write, edit, shell, background jobs, the Fiber delegate harness, asking the person, web fetch, the web_search tool compact (docs/compaction.md), name_session, reviewer_notes_save, session_list, session_message, session_search and skill behave the same for everyone and are compiled in, as is the search behind the shell's grep and find ("Search"). The default tool set therefore never needs a Lua VM, and a headless run never fails with extension_missing for one of them. Built-ins register through the tool seam exactly as an extension does and can be replaced by name (docs/architecture.md, "Tool seam").

The MCP client is compiled in too. Each tool an MCP server offers registers through the tool seam as mcp__<server>__<tool> and can be replaced by name like any built-in. How MCP tools are named, declare effects and fail is docs/mcp.md.

Four kinds ship as extensions:

Which tools the model sees

Settled by Which tools the model sees, and when; that ticket's resolution holds the rationale and the rejected alternatives.

Every tool is declared on every request, in full or deferred. A deferred tool is declared with defer_loading. The model sees its name and description until it loads the tool. The model loads the full definition when it needs it, and the definition is appended to the conversation, so the cached prefix holds (docs/prompt-cache.md, "Deferred tools"). The tool set, and which of its tools are deferred, change only when the preamble is built.

Deferral is a property of the model

What is deferred by default

Size warning

When the definitions declared in full take more than 10% of the model's context window, the preamble build is followed by a notice with code tool_definitions_large. It names the largest sources and the configuration that disables tools. When deferral is off for the model (provider data that does not set deferred_tools, or a protocol that cannot defer; "Deferral is a property of the model"), the notice also says so: "Deferral is off for this model, so every tool is declared in full." The session runs anyway.

Seeing the tools

Size budget in CI

Not settled here