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
- A name, a description, and an input schema written in JSON Schema.
- An effects function. Fiber calls it with each call's arguments before
permission is decided; it returns the call's effects, whether it is
reversible, and the paths it touches, in the vocabulary of
docs/permissions.md. Classification is per call, not per tool (docs/permissions.md). It also returns the call's subject and the prefix a rule would offer (docs/permissions.md, "What a rule matches"). A tool whose section says nothing of a subject returns an empty one, and its rules match it by name. It may also return that the call is always reviewed (always_reviewed): such a call skips the fast path, session grants and standing allows, and still meets the credential deny and the standing deny and ask rules (docs/permissions.md, "The order a call is judged in"). Any tool may set it, an extension's included; it only makes the call stricter. A tool may also declare that confinement does not skip review for a call (review_when_confined): a confined fast path must not decide it, while session grants and standing allows still apply, as do the credential deny and the standing deny and ask rules (docs/permissions.md, "The order a call is judged in"). Any tool may set it; it only makes the call stricter. Today only the shell sets it, for its built-in destructive-command guard:rm -randrm -rf,git reset --hard,git clean,git checkout --git restoreandgit push, matched best effort by command text in any component of a multi-part command, whether or not the command parses (docs/permissions.md, "The destructive-command guard"). A shell call that ran inside the OS sandbox on Linux or macOS carriesconfined(docs/permissions.md, "Confinement"); the log records it (docs/events.md, "Declared effects"). A confined call takes the confined fast path unless the destructive-command guard matches it (docs/permissions.md, "Fast paths"). - The effects function may also return the network hosts the call contacts
(
hosts). A list, even an empty one, says the call contacts those hosts and no others; an empty list says it contacts no host the model chose, as a search through its fixed backend does. A call that returns no list has unknown hosts. Anetworkcall whose hosts are all known in the session takes the fast path (docs/permissions.md, "Fast paths"). - A call's result may list the hosts it surfaced (
hosts_surfaced), such as the hosts of a search's result URLs. Those hosts become known in the session. Any tool may return either list, an MCP or extension tool included; the loop reads them and never names a tool. - Optionally: guideline lines for the system prompt, for guidance that spans
calls, such as which tool to prefer for a job (
docs/system-prompt.md, "Tool guidelines"). - Optionally: a per-call review note, for what one call needs the reviewer
to know beyond its declared effects. The note is part of the one review
request, never the system prompt or a tool definition, so the session's
cache is untouched (
docs/permissions.md, "What it is shown"). Only the shell sets one today: when some commands in a call are read-only and others are not, it names the ones that were not (Not shown read-only: `npm test`; "Shell", "Effects"). In the reviewer item the note is its own line after theDeclared effects:line and before the rest. - Optionally: how a long result is cut, and its own size cap. By default a cut keeps the start; a tool may instead declare how many bytes of the start and of the end to keep, as the shell does.
- There is no read-only flag and no parallel-safety flag. Calls in a step run
concurrently; file safety comes from the per-path lock in
docs/architecture.md("Tool calls in a step"). - Adapting a schema to each wire protocol, and carrying images to a protocol
that cannot take them in a tool result, is the provider module's job, not the
tool's. It never rewrites a schema to fit strict mode. A tool is sent with
strict: trueonly when its schema fits the vendor's strict subset, and withstrict: falseotherwise, a built-in tool included (docs/model-routing.md, "Protocols and providers"). A model whose data setscompat.no_strictsends nostrictkey at all.
Before a call runs
- Arguments the model sent are repaired first, after following any
$refto its definition. Repairs need a single type, except for dropping nullable-union nulls. Three repairs are made. Anullsent for an optional property is dropped unless its type isnullalone or it has no type. A required property'snullis also dropped when every typed schema at that property joinsnullwith another type in a type list, and at least one has a type. The tool sees these nulls as absent. A lone"null"or["null"]keeps its null. A string holding a plain JSON number, such as5,-2.5or1e3, becomes a number where the type isnumber, and where the type isintegeronly if its value is whole, so5.0becomes5and5.5is left as sent; the stringtrueorfalsebecomes a boolean where the type isboolean. A string holding JSON is parsed where the type isarrayorobject, repaired the same way inside, and kept only if the result passes the check. UnderanyOforoneOfnothing is repaired, and the value passes the check as sent or fails it. A$refthat leads back to itself before reaching a type repairs nothing. Nothing else is repaired: JSON that does not parse, a misspelt or foreign tool name, and an unknown property all fail the check. A missing required property fails unless it meets the same nullable-union rule that permits dropping its null. Repair is the same for every protocol, model and tool, built-in, MCP or extension. The model is not told, and its call is sent back to it as written, except on the protocols whose tool-call input must be an object (anthropic-messagesandbedrock-converse): there a call whose arguments are not an object is sent back withinputof{}.tool_call_requestedrecords what was repaired (docs/events.md). Arguments abefore_toolhook rewrote are never repaired. The evidence: research/reply-faults, research/reply-repair-harvest. - Arguments are checked against the input schema before the effects function is
called. A call that fails the check completes as
failedwith codeinvalid_argumentsand never writestool_call_started, so the log proves it never ran. The model is told what is wrong, one line per bad field. When the model's call fails and its arguments fit exactly one other tool declared in full on the request, whose schema declares properties and requires one of them, a last line names that tool. An inner call's message has no such line. The call is not rerouted. A call whose arguments are not a JSON object fails the same way, and its failure quotes the arguments as the model sent them. - A call naming a tool that does not exist completes as
failedwith codeunknown_tool, never starts, and the model is told which names exist. - An effects function that itself errors (for example a bug in an extension)
fails closed: the call completes as
failedwith codetool_errorand never runs. - A
before_toolhook then sees the call and may rewrite its arguments or refuse it (docs/extensions.md, "Hooks"). Rewritten arguments go through the schema check and the effects function again. The model's call is sent back to it as written (as{}on the object-input protocols named above when its arguments are not an object), and the result'scontentbegins with a line giving the arguments that ran.
What a result carries
tool_call_completed carries, beside status, reason, error and process
(defined in docs/events.md):
content: text and image parts. It is exactly what the model is sent, except for atool_searchresult: each protocol renders that fromloaded("Tool search"), andcontentholds the text form. That holds after anafter_toolhook has rewritten it. The hook runs on the full output before the cut, so the completed line and the artifact both hold what the hook returned (docs/extensions.md, "Hooks"). A foregroundshellcall's output past 1 MiB is cut before the hook runs ("Result and output").details: JSON for clients, such as an edit's diff for the terminal to draw. It is never sent to the model and live control flow never reads it. A client that does not recognise a tool'sdetailsshowscontentinstead: tool identity is an opaque name and an extension can replace any tool, so no client may depend on one tool'sdetails. The history fold is the one exception: it reads only the reservedfile_seenobject the file tools write (docs/events.md,tool_call_completed), to rebuild what the model's context has seen ("Stale files"). A confined Linux shell result includesprotected_paths: { restored, failed }when it restores a protected path or cannot restore one. The shell names each changed path incontent; the loop also carries the report on the completion event.changes: the lines each file gained and lost, as{ path, added, removed }per file, on a call that changed files. It is the one tool-neutral account of a change: a client draws a group's "+442 −12" and the side panel's per-file counts from it, never fromdetails. Any tool that changes files sets it, an extension's included.artifact: the path to the full output, present when the result was cut or when anafter_toolhook returned text for the artifact.hosts_surfaced: the hosts the result surfaced, ashttporhttpsURLs, such as a search's result URLs ("What a tool declares"). Those hosts become known in the session ("Web fetch and web search", "Effects"). Anafter_toolhook that rewritescontentleaves it as the tool returned it.kept: on a cut result, the byte ranges of the full output thatcontentholds ("Bounded results"), so a client marks the edges of the model's view without reading the cut notice. The ranges index the text or raw stream the cut saw, after anyafter_toolhook replacedcontent. When a hook returns separate artifact text, the result carries nokept, since its ranges would not index that artifact.control: instructions to the loop, absent on most results. Four fields are defined.compact, a compaction note: the loop restarts the model's context from it at the step boundary (docs/compaction.md).questions, aquestionsarray: once every call in the step has completed, the turn endscompletedwith the questions of every call that set it, in call order, onturn_completed, after any compaction in the step.name, a session name: the loop writessession_namedjust before the call'stool_call_completed, or fails the callname_pinnedwhile the person's name pins it.skill, a skill the call loaded: the loop folds every completed call's into the skills the current context loaded ("Skills"). Any tool may set them; the loop acts on the fields, never on which tool set them.- Images are written to the session's
artifacts/(seedocs/state.md) as the processed file (docs/model-routing.md, "Image limits") and referenced by path, never inlined as base64 in the log. - The loop reads
status,error.code,controland the declared effects, nevercontentordetails, except that the history fold reads the reserveddetails.file_seen("Stale files") and that the loop dropsdetails.matcheswhen a hook rewrote the output (Shell, "Result and output"). A tool's prose cannot steer control flow. - A
failedstatus is sent to the provider as that protocol's error flag on the tool result. Afailedresult whose content holds no text is sent with itserror.messageas the text, so the provider never receives an empty error result. The log keepscontentas the tool wrote it.
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
- A tool that declares no cap is cut at 16 KiB of model-facing content. The
cut bounds what the model sees: an inner call's result reaches the calling
script whole — neither the loop's cut nor the read tool's own cut applies
on that path. An inner shell call also bypasses the shell's own spill; a
direct shell call still spills past 1 MiB ("Shell", "Result and output").
Image parts do not count toward the cap and are never cut; their limit is
docs/model-routing.md, "Image limits". Configuration can override any tool's cap (docs/configuration.md). A tool may declare a larger or smaller cap.readandweb_fetchkeep the 16 KiB default ("File tools", "Web fetch and web search"). - A cut result keeps what its tool declares (the start by default, or both
ends), a notice saying how many bytes were cut, and the artifact path. When
both ends are kept, the notice sits between them. A configured cap on such
a tool is divided in the tool's own start-to-end proportion: the end gets
its share rounded down, and the start gets the rest. Nothing is lost, only
moved out of the model's view. The full output is in the session's
artifacts/, and the result'skeptgives the byte ranges of it the model was sent.readis the exception: the file is the full output, so a cut read writes no artifact and its notice gives the offset to continue from. - The model reads the rest with the ordinary
readtool on that path. There is no dedicated tool for it. A read ofartifacts/has only thereadseffect, so it is never reviewed. - There is no cap across one step's results. When they overflow the context
window, the overflow rule in
docs/compaction.md("Overflow") moves them to the session'sartifacts/. - A cut read continues from an offset, a cut fetch leaves the whole page in the artifact, and search runs through the shell ("Search").
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
- Arguments:
path(required);offset, the first line to return, counted from 1;limit, the number of lines;pages, a page range such as1-5, for a PDF only. readis strict: its optional arguments are typed nullable and listed inrequired.- Text comes back as it is in the file, without line numbers and without a byte order mark. Nothing needs stripping before it is copied into an edit.
detailsis{ "start_line": N }on a text result, the number of the first line returned, so a client numbers the lines.- The cap is the 16 KiB default ("Bounded results"). A cut falls at a line
boundary, and the notice gives the lines shown, the file's total and the
offsetto continue from. No artifact is written. - A single line longer than the cap is cut inside the line. The notice gives
the byte where it was cut and says the rest needs a byte-range read through
the shell, such as
cut -cordd. - An
offsetpast the end of the file fails withinvalid_argumentsand gives the file's line count. - A PNG, JPEG, GIF or WebP file is processed once and comes back as an
image part (
docs/model-routing.md, "Image limits"). An image that cannot be read, or is over 50 megapixels, fails withunsupported_fileand the decoder's message (or the pixel count). A CMYK JPEG decodes and is accepted. The terminal displays a stored JPEG or WebP inline on kitty terminals by converting it withfiber image --png; read-side storage, naming, MIME and size behavior are unchanged. For a model that cannot take images, the image is left out and the result says so. On a protocol that cannot carry an image inside a tool result, the image goes in a user message right after the run of tool messages that holds its result, as rendered PDF pages do onopenai-completions, because nothing may come between the tool messages that answer one assistant turn. - A PDF comes back as a PDF part. One of more than 10 pages needs
pages, and a request takes at most 20 pages.pagesis a page or a range such as3or1-5, counted from 1. A PDF of more than 10 pages withoutpages, a range of more than 20 pages, andpageson a file that is not a PDF each fail withinvalid_arguments, the message saying which. A range past the end fails withinvalid_argumentsand names the page count, and an unreadable PDF fails withunsupported_fileand the message. A PDF of more than 100 MiB (104,857,600 bytes) fails withunsupported_file, naming the cap and the file's size;readchecks the file's size before the child loads it. The cap is a file-size limit, not a memory bound. While loading, the child also refuses any object or cross-reference stream that would decompress past 64 MiB (67,108,864 bytes), and any load error, including a dropped object that a page needs, fails the whole file. When rendering fails for another reason the part has nopagesand the result says why. The provider module sends the PDF natively where its protocol accepts a PDF in a tool result, and otherwise sends the pages rendered as images, which go through the same limits (docs/model-routing.md, "Image limits").readrenders the pages once, with poppler'spdftoppm, as the PDF enters, so a later model switch has them. Whenpdftoppmis not installed, the result says so and names the package, and a protocol that needs pages gets that sentence in their place.anthropic-messagestakes adocumentblock insidetool_result,openai-responsesaninput_filein thefunction_call_outputarray, andgoogle-generative-aianinlineDatapart infunctionResponse.parts.openai-completionsrejects a file part in a tool message, so it gets the pages rendered as images in a user message after the tool message.bedrock-conversegets the rendered pages too, and carries them, as it carries a result's images, asimageblocks right after thetoolResultin the same user message: Mistral and Qwen models on Bedrock refused an image inside it (docs/model-routing.md, "Bedrock Converse wire facts"). - A path that does not exist fails with
not_found. When the wanted name differs from an entry in the same directory only by Unicode spaces, the failure staysnot_foundand names the lookalike instead of opening anything: every character with the Unicode White_Space property (U+0020, U+00A0, U+202F, U+2003, U+2028, U+2029, tab, line feed, vertical tab, form feed, carriage return, next line and the other separator and control spaces) folds to U+0020 for the comparison, while a zero-width space (U+200B) does not fold and never matches. Entries of any kind — file, directory or symlink — report by basename only; nothing is opened, stated or followed. One match staysnot_found, names the one basename and says the names differ only in Unicode spaces. Several matches staynot_foundand list at most the first 10 sorted basenames plus how many more are not listed. The directory is read once, after the open failed, and never on a successful read; when it cannot be read, or the wanted name is not valid Unicode, the failure is the plainnot_found, byte for byte. - Any other file that is not UTF-8 text, and any directory or device, fails
with
unsupported_file, giving its size and detected type. - Effects:
reads, reversible, with the resolved path.
write
- Arguments:
pathandcontent, both required. - It creates the file, and any missing parent directories, or replaces an existing file.
- Replacing a file keeps that file's line-ending style (CRLF or LF) and its byte order mark. A new file is stored as given.
- The result says whether the file was created or replaced, with its size in
bytes and lines.
changesgives the lines added and removed: every line of a new file is added. - Effects: creating a file is a reversible
writes; replacing one is an irreversiblewrites. Both carry the resolved path.
edit
- Arguments:
pathandedits, a list of one or more blocks, each{ old_text, new_text }. There is no replace-all. - Every block is matched against the file as it was before the call. Each
old_textmust occur exactly once, and blocks may not overlap. Either every block applies and the file is written once, or nothing is written. - Matching is exact first. When a block's exact text is not found, it is matched again with trailing spaces on each line ignored and Unicode quotes, dashes and spaces folded to their ASCII forms. Only the lines a block touches take the new text; every other line keeps its original bytes. A block is unique if it is unique in the form it was matched in.
- Matching sets the byte order mark aside and treats line endings as LF. The
file is written back with its own line-ending style and byte order mark.
A byte order mark in a block's
new_textis kept as sent. - Failures: a block not found fails with
no_match; a block found more than once fails withambiguous_match, giving the count. Both name the block by its index. An emptyold_text, overlapping blocks, or edits that leave the file unchanged fail withinvalid_arguments. A file that does not exist fails withnot_found, and one that is not UTF-8 text withunsupported_file. - The result gives, for each block, the lines it replaced and the lines the new
text now occupies, and says when a block matched only after normalising.
The diff goes in
detailsas{ "diff": "<unified diff>" }for clients and is not sent to the model, andchangesgives the lines added and removed. - Effects: an irreversible
writes, with the resolved path.
Stale files
- An edit carries its own check: every block must still match the current file, and everything outside the blocks is kept.
- A
writethat would replace an existing file is refused withstale_fileunless this session has seen the file's current content. Seen means areadof the file (any range) or the session's ownwriteoredit. Fiber compares a hash of the whole file, taken when it was read or written, with a hash of the file now. Modification times are not used. - The message says the file changed or was never read, and to read it first. A file changed by the session's own shell command, such as a formatter, counts as changed.
- What was seen follows the model's context, not the process. Each successful
read,editandwritelogs the whole file's hash beside its resolved path, in the completion's reserveddetails.file_seen(docs/events.md,tool_call_completed); a resume, a fork and a rewind rebuild what was seen from the log, up to the point the context continues from. Anafter_toolhook is not givenfile_seenand cannot replace it. Nothing is re-hashed at startup, so a file changed while Fiber was down still meets the stored hash and is refused with the message that it changed since it was read. A log written before the field existed rebuilds nothing, as when the record started empty. - A compaction clears what was seen, because the new context has not seen the
file (
docs/compaction.md); awritethere is refused until the file is read again.
How a change lands
writeandeditwrite a temporary file in the same directory and rename it over the target, so a crash leaves the old file or the new one, never half of either. The file's permission bits are kept.- A file with more than one name on disk (a hard link) is written in place instead, so every name sees the change. A crash during that write can leave it partly written.
- Under the per-path lock (
docs/architecture.md, "Tool calls in a step"), just before writing, the path is resolved again. If a symbolic link now points somewhere other than the path permission judged, the call fails withpath_changedand nothing is written.
Search
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.
- The shell classifier already treats
grepandfindas read-only ("Shell", "Effects"), and the shell's cut bounds their output, so a tool would add neither. - A plain
grep -rwalks into.gitand build directories. In a large monorepo that is minutes of reading. The built-in search skips them.
How it runs
- Before each command, the shell tool defines two shell functions,
grepandfind, that run the Fiber binary's hiddengrepandfindsubcommands. The functions exist only in the model's own command line. A script or build the command starts gets the system tools, because shell functions are not passed to child processes. - The subcommands are hidden: undocumented for people and free to change.
command grep, or a full path such as/usr/bin/grep, runs the system tool.rgis not replaced; it already skips ignored files.- The search is ripgrep's own crates:
ignorewalks the tree, andgrep-searcherwithgrep-regexsearches each file (docs/dependencies.md).
Behaving like grep and find
- With no path and no
-r,grepreads its standard input, so a pipe such ascargo test | grep FAILEDworks as before. - Output is GNU
grep's, byte for byte:path:line:text,--between context groups, and the path shown when more than one file is searched or-rnames a directory.findprints one path per line. grep's exit codes are GNU's: 0 when something matched, 1 when nothing did, 2 on an error.findexits 0 when it finished, even with nothing printed, and 2 on an error.xargs grepandfind -exec greprun the systemgrep, because shell functions do not reach the programs they start.
Flags
- The built-in handles these flags:
-n,-r,-i,-v,-E,-F,-l,-c,-w,-o,-A,-B,-C,--includeand--excludeforgrep;-name,-iname,-path,-type,-maxdepth,-mindepthand-newerforfind. - A call with any other flag runs the system
greporfindunchanged.findwith-exec,-execdir,-okor-deletealways runs the systemfind, and the shell classifier already declares those callsexecutes. - Without
-Eor-F, a pattern is a basic regular expression, as in GNUgrep, and is translated to ripgrep's syntax before the search. With-Eit is an extended regular expression; with-F, a fixed string.
What it skips
- A directory walk skips what the workspace's ignore files exclude
(
.gitignore,.ignore, and git's global and repository excludes), and always skips.git,.svn,.hg,.bzr,.jjand.sl. - A path the model names is always searched, even if it is ignored, as ripgrep does. Ignore rules apply only to what the walk finds.
- Hidden files are searched. Binary files are skipped, as
grep -Idoes. - When a search finds nothing and skipped ignored directories on the way, it prints one line on standard error saying so and naming the directories skipped at the top level, so the model can search them by name. A search that finds matches prints nothing extra.
Other command-line tools
-
Every operand after the command and any subcommand path configured at
shell.read_onlyis a path. A flag written ending in=, such as--format=, takes a value, after the=or as the next word; any other flag takes none. -
An operand under
/proc/makes a call not read-only, so it goes to review. A process's environment there can hold a key from anenvcredential source (docs/configuration.md, "Secrets"). -
A flag that makes a recursive read follow symbolic links, such as
grep -R,rg -Lorfind -L, makes a call not read-only, so it goes to review: the credential deny sees only the paths a call names, never a link below them. Any read-only command added later follows the same rule.grep -rstays read-only, because it follows only links named on the command line, and the deny canonicalises those. The built-in list is under "Shell", "Effects". -
A tool that must stay warm between calls, such as an index kept current by a file watcher or a language server, is an extension that registers a tool (
docs/extensions.md). A command-line tool starts cold on every call. -
Any other search tool, such as
ast-grepor a tree-sitter query command, is a command-line program the person installs. It reaches the model through the person's instruction files (docs/system-prompt.md, "Instruction files"). Prose works best when it maps a habit the model already has onto the new tool. -
The person's configuration can add a command to the shell classifier's read-only list, with the flags it may take and stay read-only (
shell.read_onlyindocs/configuration.md). A call to that command with only those flags declaresreadsand skips review; any other flag makes itexecutes, as for the built-in list. A repository cannot add to the list. An entry for a command the built-in list already has adds its flags to the built-in ones; it cannot remove one. A command the built-ins accept only in an exact form, such asgit stash list, takes no added flags.
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
- The command runs as
/bin/bash -c <command>, orsh -cwhere/bin/bashdoes not exist. It gets the session's environment and reads no shell startup files (docs/invocation.md, "A session's environment"). That environment already holds thePATHand variables the person's startup files set; aliases and shell functions are not carried. - It runs in a new process session and its own process group, with no
controlling terminal, and standard input connected to nothing
(
/dev/null). Standard output and standard error are one stream, in the order they arrive. - With no terminal and nothing on standard input, a command that prompts
fails at once instead of waiting forever. Probed on macOS (2026-09-23):
readreturned an empty answer, opening/dev/ttyfailed with "Device not configured",sudofailed with "a terminal is required", git asking for HTTPS credentials failed in 1.9 s, and Python'sinput()raised EOFError. There is therefore no warning for a command waiting on a prompt. - Arguments:
command(required);workdir(optional; defaults to the workspace; a relative path is resolved against the workspace);timeout_ms(optional; for a monitor, its deadline);run_in_background(optional);tty(optional);monitor(optional; starts a monitor, "Background jobs");unconfined(optional; when true the call leaves the OS sandbox and is reviewed exactly as with the sandbox off);detach(optional; when true the command starts in a new session and process group, outside the OS sandbox, and the call returns at once with the job id and output-log path. Stop it withjobs stop("Background jobs").detachimplies unconfined: withdetachtrue,unconfined: falsefails withinvalid_arguments. Fiber never reruns a failed confined call outside its sandbox: the model retries explicitly withunconfined: trueas a new reviewed call. On macOS the confined shell prints a start marker before the user program runs; the call fails instead of ending normally when the marker never arrives. Each call starts fresh: acddoes not carry over to the next call. - When the session sandbox is on and available, the
shelldefinition carries one more sentence: the call runs confined with no sockets and writes limited to the workspace, temp and granted paths, and a call withunconfined: trueordetachset runs outside the sandbox and is reviewed as with the sandbox off. - Its optional arguments are typed nullable and listed in
required. Theminimumlimits put its schema outside the strict subset, so it is sent withstrict: false. - A monitor takes neither
ttynorrun_in_background. Each of these fails withinvalid_arguments, the message naming the argument. detachtakes neitherrun_in_background,tty,monitor, nor atimeout_msthat is not null. Each of these fails withinvalid_arguments, the message naming the argument.- A bare wait is rejected. When the call is not
run_in_backgroundand the first part of the command issleep Nwith N of 25 seconds or more, alone or followed by other commands, the call completes asfailedwith codeinvalid_argumentsand never starts. The message quotes the refused command and gives two copy-and-run rewrites: run the same command withrun_in_background, then wait withjobs wait, and a monitoruntilsnippet naming the check command when the command holds one, with the deadline rule. Refusingsleep 240; echo hisays: "sleep 240; echo hiwaits withsleepfor 25 seconds or more, so it never started. Run it in the background instead: callshellagain withrun_in_background: trueand the commandsleep 240; echo hi, then wait for it withjobs wait. To wait for a condition instead, start a monitor withmonitor: trueand a command likeuntil echo hi; do sleep 5; done; every monitor has a deadline, 5 minutes (300000 ms) by default, at most 30 minutes (1800000 ms), and at most 10 minutes (600000 ms) in a non-interactive run." When the command holds no usable check command — a baresleep 60, an empty, comment-only or separator-led rest, or a rest opening with a loop keyword — theuntilsnippet names<check command>instead. Asleepinside a loop is not the first part of the command and is allowed.
Timeout
timeout_msis the one thing that kills a command for running long. It counts from when the command started. There is no maximum, except a monitor's. For a monitor it is the deadline under "Background jobs", with that section's default and maximum.- A call with
run_in_backgroundtrue and notimeout_mshas no timeout. It runs until it exits, untiljobs stop, or until the session shuts down. - Any other call with no
timeout_msgets 600,000 (10 minutes). A foreground command's timeout stays with it after the command moves to the background. - A detached call takes no
timeout_msand has no timeout: neither the 600,000 default nor any other limit. A detached call with atimeout_msof any value, 0 included, fails withinvalid_argumentsand never starts. timeout_msis at least 1: the schema says"minimum": 1. A call with 0 fails the loop's schema check (docs/loop.md), endsfailedwith codeinvalid_arguments, and never starts.- The tool's description and the
timeout_msdescription state both rules: a background call with notimeout_mshas none, so a background call that should run until stopped leaves it out; andtimeout_msis at least 1. - This is where a hang is bounded: "Background jobs" has no cap on waiting.
A background command with no timeout is bounded by
jobs stop, by the model when a session about to end lists it, and by shutdown. - A command that times out ends
failedwith codetimeoutandprocess.timed_outtrue. - The unit is milliseconds.
Moving to the background
- A command moves to the background, becoming a job ("Background jobs"),
when any of these happens:
- It has run for 30 seconds.
- It was started with
run_in_background,ttyormonitor, in which case it moves at once. - A driver sends the
backgrounddriver command (docs/invocation.md).
- Moving never kills anything and never restarts anything. The tool call
completes with the job's receipt, which says the command is still
running, why it moved, the
job_idand the output file's path. When the job kept the command's timeout, the receipt ends with when Fiber stops it and how to keep a long-running process instead ("When a command ends"). A moved command with no timeout says nothing about a deadline. Output already produced and all later output go to the job's output file.
When a command ends
- A command with no job list (a run that cannot move) runs until its
process group is empty, not until its shell exits and not until its
output pipe closes. Fiber checks whether the group still has members
(
kill(-pgid, 0)). - A foreground
shellcall ends when its shell exits. If processes it started are still in the group, the call still completes at once, with the shell's output and exit code as for any command that finished ("Result and output"):completedfor 0,failedwithnonzero_exitotherwise. The leftovers are a side effect, not the work, so they are not a job: they get no timeout and no notice, and only a shutdown stops them. The result ends with one line after the closing line: how many processes are left running and the first three by name and process id (for example2 processes left running (first: sleep (12), sleep (13)).), the artifact file for what they print after the call returns, and the long-running-process hint (To keep a long-running process such as a server, start it with `run_in_background` and no timeout, or with `detach`.). When the group cannot be listed the line gives no count and says processes are still running in the group; when the session has no artifacts directory it says the output could not be saved, and that output is dropped. A shell that leaves nothing running ends with no such line. - Where the leftovers' output lands has three tiers. Output already delivered when the shell exits is in the result. Output still in flight at exit, or written before the call returns, may be in either place. Output written after the call returns is in the artifact file. A byte lands in one place only, and the artifact stops growing at the same cap as a job's output file. The file closes when the output pipe does, and Fiber takes the group off its list once the group is empty.
- A command still running after 30 seconds moves to the background as
"Moving to the background" says, and a move that kept a timeout ends its
receipt with the stop time in UTC, the timeout, and the
long-running-process hint, for example (
Fiber stops it at 2023-11-14T22:13:50Z (timeout_ms 60000). To keep a long-running process such as a server, start it with `run_in_background` and no timeout, or with `detach`.). - A process that left the group on purpose, for example with
setsid, is not tracked.nohupdoes not leave the group: the process stays in it, and a timeout, a cancellation, ajobs stopand a shutdown stop it with the rest.
Stopping a command
- A timeout, a cancellation and a
jobs stopall stop a command the same way: SIGTERM to the whole process group, then SIGKILL to the group 800 ms later if any member is still alive. 800 ms is the value from the archived Zig tree (fiber-zig). The grace period exists because programs clean up on SIGTERM: git, for example, removes itsindex.lockon SIGTERM and leaves it behind on SIGKILL. - After the kill, Fiber reads output for at most 2 seconds more. If output is still held open after that, for example by a
descendant that escaped the group, Fiber stops reading and the result is
failedwith codeindeterminate, nevercompleted. - A shutdown (
docs/invocation.md, "Shutdown") uses the same two values, on every group at once. - A timeout's receipt says Fiber stopped the whole process group ("Result and output").
- A detached process outlives its session. A timeout or cancellation of its
launch call does not stop it, and shutdown leaves it running. While the
session is active,
jobs stopstops it with the same TERM and KILL sequence as another job ("Background jobs").
Result and output
-
Exit code 0 is
completed. A nonzero exit isfailedwith codenonzero_exitandprocess.exit_code. A command killed by a signal Fiber did not send isfailedwith codesignalandprocess.signal. A timeout is as above; a cancellation iscancelled. -
The output the model reads ends with a closing line that says how the command ended. If the command's own output is non-empty and does not end in a newline, a newline goes first. An empty output gets the closing line alone. The closing line ends with a newline:
Exit code N.for an exit, 0 included;Killed by SIGNAME.for a signal;Timed out after N ms; Fiber stopped the whole process group.for a timeout; a moved job's timeout adds the long-running-process hint ("When a command ends"); a foreground or moved timeout whose command text holds a|adds (A pipeline stage that prints only when it exits (such as `| tail`) lost its output at the stop; rerun without it, or with `run_in_background`.). A completion the keeper writes after a restart carries no pipe sentence ("The keeper").The monitor's deadline of N ms passed; start it again if you still need it.for a monitor's deadline;Cancelled and stopped.for a cancellation;The command was stopped, and Fiber cannot tell whether it completed.forindeterminate.
A notice that the job could not be opened goes on the line before it. On an output Fiber kept whole,
Output was still held open.goes on the line after it. A shell that exited with processes left running adds its one leftover line after the closing line, on a whole and a spilled output alike ("When a command ends").processanddetailscarry the same facts for a client, which should read them there rather than parse the text. -
detailsis{ "command": "<command>", "exit_code": N }, or"signal"in place of"exit_code"when a signal killed it, so a client draws the command and how it ended. A confined Linux call that changes a protected path also addsprotected_paths: { restored, failed }; it lists restored paths and any restore failures. The shell names each changed path in its closing output, without changing the command's exit result. When the command is a single built-ingrepover files that prints lines ("Search"),detailsalso holds"matches": one{ "path", "lines" }per file in the order printed, each line a{ "line", "text", "spans" }: its line number, its text, and the[start, end]byte ranges of the matches in it, each widened to whole characters, and empty on a line that is not UTF-8 text, whosetextholds U+FFFD for bytes that are not, and empty on a context line, so a client draws matches by file with the matched text picked out. Agrepreading its standard input, or in a pipeline, adds none, as do-c,-l,-o,-vand a call the systemgrepruns. The built-ingrepwrites the matches to a temporary file per foreground call, named inFIBER_GREP_MATCHES, at most 1 MiB; the shell tool attaches them only when its parse finds one built-ingrepover files and never runs the search again. When anafter_toolhook rewrites the output and returns nodetails, the loop dropsmatches. -
Output follows "Bounded results": the default 16 KiB cap applies, and the shell keeps the first 8 KiB and the last 8 KiB. The start is where a command reports its setup, its first error or its first matches; the end is where it reports how it finished. The full output is in the session's
artifacts/, and output streams astool_call_deltawhile the call runs. After a move to the background, output goes to the job's output file. -
Up to 1 MiB of direct-call output, the shell holds it, and the loop cuts it and writes the artifact. Past 1 MiB, the shell writes the output, from its first byte, to the call's artifact file in the session's
artifacts/as it arrives, and holds only the first and the last 8 KiB, or the two ends of a configured cap ("Bounded results"). An inner shell call runs with no shell cap or spill artifact, so its complete output reaches the calling script; the outer result to the model remains bounded ("Bounded results"). The file ends with the result's closing lines, such asExit code 0.. The loop writes no second artifact, and theafter_toolhooks get the cut output with the file'spathandsize(docs/extensions.md, "Hooks"). When the file cannot be created or written, or its path is not UTF-8, the shell keeps only the two ends and the command runs on: the notice says the full output could not be saved, and the result names no artifact. A move to the background carries the file's output into the job's output file.
Terminal (tty)
- With
tty: truethe command runs in a pseudo-terminal instead of pipes, so a program that behaves differently on a terminal, or waits for typed input (a REPL,git rebase -i, a debugger), can be driven. It moves to the background at once; the receipt carries whatever output arrived in the first 250 ms. - The model types into it with the
jobsactionwrite("Background jobs"). Output is the terminal's raw bytes. Fiber keeps no screen model and runs no separate terminal host process. - Prompts do not fail at once on a terminal; that is the point of
tty. The timeout still bounds the command.
Effects
- The shell tool classifies each call (
docs/permissions.md, "Effects"). It parses the command with tree-sitter-bash (docs/dependencies.md) and checks each command in it against a list of read-only commands and the flags allowed for each: Fiber's own list, plus any the person's configuration adds ("Search", "Other command-line tools"). If every command is on the list, the call declaresreads, reversible, with the paths the command names, resolved againstworkdir. Otherwise it declaresexecutes, with no paths. A call that ran inside the OS sandbox on Linux or macOS carriesconfined(docs/permissions.md, "Confinement"); a call withunconfined: trueleaves the sandbox and is reviewed exactly as with the sandbox off. A detached call declaresalways_reviewed: the reviewer or the person sees it as an unconfined call, and it takes no protected-path transaction (docs/permissions.md, "Confinement"). - The recogniser accepts only a listed set of syntax: simple commands,
pipelines, lists joined by
&&,||and;, quoted and unquoted words, variable assignments before a command, and the redirects below. Any other node, and anyERRORorMISSINGnode the parser leaves, makes the callexecutes. That covers subshells( ), process substitution, heredocs, loops, functions, a trailing&, and variable expansion ($HOME,${x}). - The recogniser works within four bounds: commands of at most 10,000
bytes,
cdchains resolving against at most 32 directories, wrappers nested at most 4 deep, and.gitfiles of at most 512 bytes. Past any bound the call declaresexecutes, so the bounds never widen the fast path. - Command substitution (
$( )or backticks) makes the callexecutes, with one exception: a substitution whose whole content isgit merge-base <rev> <rev>reads as an operand of a listed git read, bare or composed with one..or...range against an outer plain revision, such as$(...)..HEAD. Each<rev>is a plain word of hex digits,HEADor a ref name, optionally followed by^,~<n>or^{commit}; any other inner command, includinggit rev-parse, and any flag keep the callexecutes. The inner command runs under the same repository checks as the outer read. It prints a commit id or nothing, so its output is never a path and never a flag. A substitution anywhere else — a command name, a flag value, a redirect target, an assignment value or acdtarget — keeps the callexecutes. Otherwise a substitution's arguments are known only when it runs, so the path checks cannot see them:cat $(echo ~/.ssh/id_rsa)reads the key while every command in it is read-only. - A read-only command stays read-only with only these redirects: output
sent to
/dev/null(>/dev/null,2>/dev/null), one stream merged into another (2>&1,>&2), and input read from a file (<file), whose path takes the same checks as any path the call reads. Any other redirect makes the callexecutes, including>or>>into a file and/dev/tcp/...or/dev/udp/...in either direction. - An entry on the list, built in or from
shell.read_only, is a command, an optional subcommand path such aspr view, and the flags allowed with it. A flag not listed makes the callexecutes. For a command whose entries name subcommands, a subcommand with no entry of its own does too, so allowinggh pr viewdoes not allowgh pr merge. cd <dir>is a read-only step, and its directory is a path the call reads. Paths in later commands joined by&&are resolved against the new directory. After;or||thecdmay have failed, so a later command's paths must pass the checks against both the old and the new directory. Acdinside a pipeline moves nothing. Acdwith no argument, with-, or with command substitution, and anycdfollowed later in the call bygit, make the callexecutes: the new directory can hold git hooks or configuration the person never saw.- A wrapper is classified by the command it runs.
timeout <duration> <command>andenv <assignments> <command>are read-only when the inner command is, and so isNAME=value <command>. An assignment is allowed only for a name on a fixed list of names that change no code a command runs, such asRUST_BACKTRACE,LANG,LC_ALL,TZ,TERM,CIandGIT_TERMINAL_PROMPT. Any other name, such asPATH,LD_PRELOAD,PAGERor aGIT_CONFIG_*variable, makes the callexecutes.envwith a flag of its own does too. xargsis read-only only when the command it runs is one ofecho,printf,wc,grep,headandtail, with that command's own allowed flags:git ls-files | xargs wc -ldeclaresreads.find -execandfind -deletedeclareexecutes(below).gh pr view,gh pr list,gh pr diff,gh pr checks,gh issue view,gh issue list,gh repo view,gh run viewandgh run listare read-only, each with only its listed flags, such as--json,--commentsand--repoforgh pr view.--jq <program>joins each listed read, but a program holdingenv,ENVorinputas a substring, matched case-sensitively, makes the callexecutes:ghevaluates--jqin-process with the process environment loaded, so a program naming the environment would print it into the result, the same leak the/proc/rule below blocks. Such a read declaresnetworkwith the default host, unless it is own: every repository it names belongs to an owner, an account or organisation, of one of the session workspace repository'sgithub.comremotes, and then it declaresreadswith the paths it names. A read names its repository with--repo/-R owner/repo, with ahttps://github.com/owner/repo/...operand, or by naming none, soghresolves it from the workspace's remotes; any other slash-bearing positional operand keeps the reviewed path. An unnamed read is own only when the call'sworkdiris the workspace root and the command holds nocd, while a named read is judged by its name alone whateverworkdirorcdsays. Owners come from the common directory's git config: the nearest.gitat or above the workspace root, or the common directory a worktree'sgitdir:andcommondirpointers name. The classifier reads at most 64 KiB of config and never followsinclude.path, counting onlyremote.<name>.urlvalues ongithub.comin the HTTPS and SSH forms, matched case-insensitively. A longer, unreadable or unparsable config, a workspace outside a git repository, a remote on another host, and a.gitorcommondirpointer past 512 bytes, symlinked, or pointing outside version control all leave no owners, so everyghread stays reviewed. A list read with--searchor-S, and anyghentry fromshell.read_only, is never own.gh apiandcurldeclareexecutes: a flag such as-fturns agh apiread into a write, and a GraphQL query can carry a mutation.- When some commands in a call are read-only and others are not, the
reviewer's prompt for that call names the ones that were not, as
Not shown read-only: `npm test`. The reviewer still gets the whole command (docs/permissions.md, "What it is shown"). The line is part of the one review request, never the system prompt or a tool definition, so the session's cache is untouched. sedis read-only with only-n,-E,-rand-e, where every script is addresses (line numbers,$,/regex/, ranges) followed byp. A short-flag cluster may hold only those letters, with-etaking the rest of its word as the script or the next word; any--longflag (including--in-placeand--expression=...), any other letter, a lone-, a flag after the first operand, and--followed by a word that is not a script all make the callexecutes. A script is one or more commands separated by;or a newline, each an optional one- or two-address range whose first address is never zero followed byp, with blanks allowed around the command but not inside an address or around,; a regex address is/.../where\escapes the next character. A script that is empty, a comment, or holds any other command letter (w,e,r,s,d,qand the rest), a write or execute, a GNU address extension, or anything the classifier cannot parse makes the callexecutes. The script is never a path; with-eevery operand is a file, otherwise the first operand is the script and the rest are files, and with no file the workdir is declared, ascatwith no operand does.git log,git show,git diff,git status,git rev-parse,git merge-base,git ls-files,git blameandgit branch --show-currentare read-only.git merge-basetakes no flags.git logalso accepts-<number>, such as-8.git diffalso accepts--check,--merge-base,-wand--ignore-all-space, plus--diff-filter=<value>with any value, and-U<n>and--unified=<n>with an all-digit<n>, such as-U80or--unified=5;git logandgit showaccept-U<n>and--unified=<n>too. A bare or separate-word--diff-filter,--unifiedor-U, and a non-digit unified value, make the callexecutes. A global flag before the subcommand (-c,--config-env,--exec-path,-p/--paginate,--git-dir,--work-tree), aGIT_CONFIG_*variable, a subcommand flag--ext-diff,--textconv,--outputor--output=<file>, any othergit branchform, and any other subcommand make the callexecutes. So does a git read in a bare repository, or where.gitis a file whose target Fiber cannot verify. Operands ofgit rev-parseandgit merge-baseare revisions, not paths, so they declare no paths.- Repository git config can make
diff,log -p,show,blameandstatusrun a program:core.fsmonitor,core.pageror afilter.*driver, including one reached throughinclude.path. Fiber neither reads that config nor rewrites the model's command, so such a call still takes the fast path. The agent's own writes under.git/are reviewed (docs/permissions.md, "Fast paths"); config already in place, or pulled in from a file outside.git/, runs unreviewed. echoreads a word as an option only when it is-followed by one or more ofn,e,E; every other word is text, and of the option words only-n(and clusters ofn, such as-nn) is accepted, soecho ---reads whileecho -edoes not.headandtailaccept-<number>, such ashead -20, besides-n <number>;tail -n +<number>, such astail -n +3 f, reads from that line on. An attached value, such ashead -n10, is not on the list, so the call declaresexecutes.nlis read-only with only the flags that change numbering or layout:-b,-n,-w,-s,-vand-i, each taking a separate value or the--long=valueform (--body-numbering,--number-format,--number-width,--number-separator,--starting-line-numberand--line-increment), and the standalone-ba. An attached value, such asnl -w3, and any other flag make the callexecutes. Every operand is a path, so the credential deny and the/proc/rule apply as they do forcat.trueand:are read-only only as bare commands, with no operands and no flags.findaccepts the selection operators-not,-a,-oand-prune: they only choose which paths print, so a call holding only them declaresreads.-exec,-execdir,-ok,-deleteand-fprint*still declareexecutes. The new forms run the systemfindunreviewed: the built-in search ("Search", "Flags") handles none of them, so the call runsfindunchanged while thereadsdeclaration skips review.- A command with a path under
/proc/, resolved againstworkdir, is not read-only, so the call is reviewed:/proc/<pid>/environholds the process's environment, a key from anenvsource among it (docs/configuration.md, "Secrets"). - Flags matter because read-only-looking commands have writing or
executing flags:
git diff --output=<file>writes a file,rg --pre <cmd>andfind -execrun programs,find -deletedeletes,sort -owrites. The list and its flag rules are part of building the shell tool. - A call declared
readstakes the permission fast path. - A call of one simple command, with nothing the recogniser does not
accept, has the command as its subject. The prefix offered is its first word, and
the second word too when it is a plain word, starting with no
-and holding no/,.,=or>:npm test -- --watchoffersnpm test, andrm -rf buildoffersrm. Any other command has no subject, so no allow rule or session grant matches it, and an approval of it cannot be remembered. A redirect stays in the subject as written. - The credential deny (
docs/permissions.md, "Credentials") sees paths only for commands the recogniser understands. A command it does not understand, such aspython -copening a file, declares no paths, so the deny cannot see it; it is still reviewed. A shell call runs with the account's full rights when the sandbox is off (docs/permissions.md, "Confinement"). - The read-only list is trusted. A command on it that writes after all, or
an entry in
shell.read_onlythat is wrong, writes without review. An entry is the person's statement that the command only reads. - The built-in shell is trusted to classify because it is compiled in. An
extension that replaces the shell classifies its own calls and is
believed, as
docs/permissions.mdalready states.
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
jobsregistry gives each tracked process onejob_id. Shell commands, monitors and delegates are jobs (docs/delegates.md). The registry also lists detached processes asdetachedentries. You can list or stop a detached entry;waitandwritedo not apply to it. Detached entries do not hold the session open. On resume, Fiber restores outstanding detachedjob_startedrows before exposing tools. A live group with confirmed identity stays listed, even when its log is missing or is not a regular file; Fiber never opens that log during restoration. A live group with missing or unreadable leader identity stays listed but requires review to stop. Rows without a process-group ID, dead groups, contradicted identities and rows completed later are dropped silently. Restore never signals. An approved stop rechecks identity, sends TERM, escalates after the grace period if needed; a group disappearing during that stop or on its own produces one failedindeterminateend. Detached ends stay in the registry but do not send a completion notice or writejob_completed. A process without a durablejob_startedrow is not restored; the unrecorded launch interval before that row is written remains outside resume recovery. -
The call that starts a job completes in its own turn with a receipt naming the
job_idand the path of the job's output file in the session'sartifacts/. A Fiber delegate's output file is its ownevents.jsonl(docs/delegates.md, "The tools"). There is no pending status. Every provider needs a tool result before the model's next step, so a call held open across turns would stall the turn. -
A job's output streams to that file. The model reads it with the ordinary
readtool ("Bounded results"). There is no output action. -
Its optional properties and the
minimumlimit put its schema outside the strict subset, so it is sent withstrict: false. -
delegate_spawn'smodelis neither required nor typed in its schema, because the tool checks it and lists the roles, up to 3 closest references, and namesdelegate_modelsfor the rest (docs/delegates.md, "Choosing a model"), sodelegate_spawnis sent withstrict: false. -
delegate_fork'stimeout_msis optional and carries aminimumlimit, sodelegate_forkis sent withstrict: false. -
delegate_models'sfilteris optional, sodelegate_modelsis sent withstrict: false. -
The model-facing tool is one
jobstool with actionslist,wait,stopandwrite.waitblocks up to a timeout. Cancelling a wait (for example because the turn is cancelled) stops only the wait and leaves the job running.writesends input to a job started withttyand returns the output that arrives within a wait after the write, 250 ms by default, at most 30 seconds. A write with no input waits at least 5 seconds.writeon a job not started withttyfails withinvalid_arguments. Awritecall declaresexecutes, because typed input can make the program do anything. Detached entries accept onlylistandstop;waitandwritereturnunknown_jobfor them.jobsonly sees and acts on processes the calling session started, so a delegate cannot stop its parent's work. -
Every delivery to the model, a completion or a monitor's batch, passes through the
after_toolhooks first, and so does the job's output file when the job ends (docs/extensions.md, "Hooks"). -
Completion reaches the model by waking it. If the loop is idle, a finished job starts a new turn whose input names the job or jobs. If a turn is running, the news joins it at the next step boundary, the way a steering message does. Jobs finishing together are delivered together in one turn, not one turn each. If a
jobs waitalready returned a job's final state to the model, no completion notice is sent for it. A job an extension started withhost.delegateis the exception: its end wakes nothing and starts no turn. The model does not see its completion notice, live or after a resume. Ajobs wait,jobs stoporjobs writeanswer still reports the final state, without the delegate's final message. Itsdelegate_finishedandjob_completedare written with no turn, after theafter_toolhooks (docs/extensions.md, "Host calls"). -
A
jobs waitthat returns a job's final state carries the sameoutput_tailas the completion notice, with the output path in the wait answer. A wait that ends at its deadline with the job still running reportsstill_runningwith no tail; a finished job whose output file is empty or missing carries no tail either. -
A monitor is a job running a watch command. The model starts one with a
shellcall that setsmonitor: true, so the command goes through the shell's classifier, permissions andworkdirlike any other. Lines on its standard output are delivered to the model in batches, the same way as a completion. Standard error goes to a separate file and never reaches the model. It ends when its command exits, it is stopped, or its deadline passes.- Batching: lines are joined into one delivery. Each line is cut at 500 characters and each delivery at 3,000 characters, with a marker saying it was cut. The full output stays in the job's output file.
- Rate: deliveries draw from a budget of 10, refilled one every 2 seconds. A delivery that finds the budget empty is dropped, and the model is later told how many were suppressed and that it should restart the monitor with a more selective filter. The monitor keeps running.
- Flood stop: after 30 seconds of continuous suppression the monitor is
stopped as
failedwith codeflooded, and the model is told to restart it with a more selective source. - Deadline: every monitor has a deadline, 5 minutes by default, at most
30 minutes, and at most 10 minutes in a non-interactive run. The model
may set a shorter or longer one within those limits with the call's
timeout_ms. At the deadline the monitor ends asfailedwith codetimeout, as a timed-out shell call does (process.timed_out). The model is told the monitor expired and can start it again. The deadline is what stops a forgotten monitor from holding a non-interactive run open under the "ending with jobs running" rule in this section. - Testing: timing-dependent behaviour is tested under an injected clock, never by waiting in real time.
-
A job whose output file passes 5 GB is stopped as
failedwith codeoutput_cap. -
Stopping one job uses the same mechanism as cancelling a tool call ("Shell", "Stopping a command"), except a Fiber delegate, which shuts down as
docs/delegates.md, "Lifetime", says. If a descendant that escaped the process group still holds the output pipe open past the bound, the job endsfailedwith codeindeterminate, nevercompleted. A detached process writes to its log file, not a pipe, so it endsindeterminatewhen its process group still answers the liveness check past the bound. A stopped job endscancelled. -
Jobs run under the session's keeper ("The keeper"), so they outlive a crash of their session and a resumed session gets their real results. A shutdown stops every job (
docs/invocation.md, "Shutdown"). -
When a session is about to end with jobs still running — a non-interactive run whose model has given its final answer,
closewithoutnow, or a delegate finishing its task — Fiber wakes the model once with a notice listing the running jobs, telling it to stop the ones it does not need and that the rest will be waited for. A process meant to outlive the session must be started withshellanddetach: true. Whatever is still running after that is waited for, and each completion wakes the model. Detached entries are not included in the notice or wait, so they do not hold the session open and send no completion notice. The session ends when it is idle with no session jobs running. The idle delay never ends a session with jobs running; a session left unattended with jobs running gets the jobs check instead (docs/invocation.md, "Lifecycle"). There is no cap on this wait: a hang is bounded at the command that hangs (the shell tool's timeout when it has one, "Timeout"), by the model, which the notice tells to stop what it does not need, and by the caller's SIGTERM (docs/invocation.md, "Shutdown"), because a cap on the waiter cannot tell a hang from long healthy work such as a CI watch. A job an extension started is not counted here: it holds no session open, is not in the ending notice or the jobs check, and a session that ends normally stops it. -
There is no cap on running jobs, except that a session runs at most 10 delegates at once (
docs/delegates.md, "Limits"). Parked threads are measured indocs/architecture.md("The threads"). -
A detached process has a
job_idand appears injobs listasdetached. Its durablejob_startedrow records the process group and leader start time. The call returns at once with a receipt such as:Started detached. Job j_abc123. Output: /home/a/.fiber/detached/d_48200_0.log. Stop it with
jobs stop j_abc123.jobs stopsends TERM, then KILL after the grace period if the group is still alive. A detached entry does not supportwaitorwrite, and its end does not writejob_completedor wake a turn. The launch call has no timeout; cancelling it or shutting down the session does not stop the process, so it keeps running after the session ends. The model reads the log with the ordinaryreadtool ("Bounded results"). -
A detached call's standard input is
/dev/null; its standard output and standard error go to the log, interleaved in arrival order. Each log lives under$FIBER_HOME/detached/, namedd_<fiber-pid>_<n>.logfrom 0 up, created mode 0600 in a directory mode 0700. The person owns deleting logs: Fiber never removes them, and a session's deletion or pruning never touches them. Logs hold command output, which may carry sensitive data, until the person deletes them.
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.
- One keeper per session, started with its first command. Any shell
command can become a job ("Moving to the background") and moving never
restarts it, so the keeper starts each of the session's shell commands
and delegates, and starts when the session first runs one. A session
that runs neither has no keeper. The keeper is the internal
fibercommand, started in a session of its own, so a signal to the session's process group does not reach it. It is the parent of every command's process group and of every delegate, and it reaps them. It lives until its session shuts down or, after a crash, by the rules below. One exception: a resumed session takes the jobs of a keeper that survived the crash but does not become that keeper's parent. The old keeper keeps running those jobs and exits when the last of them has ended and the session has written its end. A command the resumed session starts runs under a fresh keeper that is the session's child, so a session can hold jobs on more than one keeper. - A command that is not yet a job ends with the crash. When the session
dies, the keeper stops each command still running as a tool call, as a
shutdown does. The log already reads that call's outcome as unknown
(
docs/events.md, "Resume"). - A confined job keeps its baseline fixed. The keeper holds the active
lock for each confined command it runs, from its start to its end
(
docs/sandbox.md, "Protected paths"). It restores nothing. A keeper that dies leaves the active lock held until the confined command's last process exits, so the first confined call that finds no active holder, and so restores and reports as after a dead session, never runs while that command lives. - The keeper is tiny. It loads no provider, MCP server or model code,
and no extension but a harness's. It runs processes, holds their pipes and
terminals, writes each job's output file, enforces each job's deadline and
output cap, and appends to the session log. A harness written in Lua is
loaded when the session starts its first delegate on that harness, and the
keeper calls only its
line(docs/delegates.md, "Harness extensions"), at about 120 to 150 KiB (docs/extensions.md, "Process extensions"). Its memory has its own budget indocs/performance.md. - While the session lives, the session decides. The session asks its
keeper to start, stop or write to a job, and the keeper reports each exit.
The session writes every event, as it does without a keeper. The session
holds the keeper's stdin open as its lifeline, as a parent does a Fiber
delegate's (
docs/delegates.md, "Lifetime"). End of file on it means the session is gone. - A crash hands the log to the keeper. When its session dies without a
shutdown, the keeper takes the session's
session.lockand bindsrun/<session_id>, as any lock holder does (docs/state.md, "What each part holds"). While it holds the lock it appends to the session's log: akeeper_startedwhen the takeover opens the log and akeeper_boundonce its socket is bound and listening, then ajob_completedfor each job that ends, for a Fiber delegate thejob_completedits exit gives, and for a delegate on another harness the rule below. The keeper writes both markers only on a crash takeover, never on the normal path. It writes nooutput_tail,noticeorchanged_by, because it runs no hooks. It writes no file of its own, so the log stays the only state of record (docs/events.md, "The rule everything else follows from"). - The keeper waits 2 hours. If no session takes the log back within 2
hours of the crash, the keeper stops every job and delegate still running,
as a shutdown does, writes each one's
job_completedasfailedwith codekeeper_timeout, and exits. It exits sooner once its last job ends, and never holds a job past that bound.fiber stopand/close allstop it sooner, the same way (docs/invocation.md;docs/tui.md). - A resume takes the log back. A resuming process finds the lock held
and connects to
run/<session_id>. The keeper answers with the session's id, which is the proof of identity: Fiber never signals a recorded process id. The keeper finishes the line it is writing, unlinks the socket, releases the lock and acknowledges. The resumed session takes the lock, binds its socket, and keeps the connection to the keeper open as its lifeline. The jobs still running are its jobs again, with noorphaned. The keeper keeps writing each job's output file until the resumed session holds the lock, then sends that job's output to the session again. The session appends what it receives after the bytes the keeper wrote, so each byte of a job's output is in its file once, in order. A job that ends while the session takes over is ended by the session, which writes itsjob_completed; the keeper exits only after the session has written the last one. - A keeper keeps its binary through
fiber update, as a session does (docs/invocation.md, "Processes"). A resume whose build cannot read the keeper'sschema_versiondeclines withsession_heldand names the keeper's version. The keeper has written every result it holds, so a resume after it exits loses nothing. - What the keeper wrote reaches the model with the next turn. A resume
starts no turn of its own (
docs/events.md, "Resume"). Before the next turn's first step, the session runs theafter_toolhooks on each completion the keeper wrote and on its output file, as at a live job's end, and the turn'sturn_startedinput carries onemessageitem withsourcefiberholding those notices, withchanged_bywhen a hook changed one. - A keeper that dies leaves its jobs unaccounted for. If the keeper itself dies before
a job's
job_completedis written, the resumed session writes that joborphanedand touches no process. - Two keepers that lose their session together keep one. When a session
that holds jobs on an old keeper and a fresh one crashes, both keepers
take the log back at once, and only one can hold the lock. Either may win.
The winner keeps its jobs and serves the next resume. The other finds the
lock held, stops only the commands that were running as tool calls, writes
nothing, leaves the socket alone and exits. Its jobs go on running with
no keeper, and the next resume writes each of them
orphanedand touches no process. This is a known limit: such a job is lost to accounting, not to the log. - A delegate on another harness is kept. Not built yet: see #3904. The keeper holds its pipes and
writes each line it prints to its output file, as for any job. While the
session lives, the session reads the lines as they arrive. After a crash,
a harness written in Lua has each line handed to its
linein the keeper: the keeper closes the program's input after the final answer, as the session does, and writes the run'susage_recordedand itsjob_completed. A harness that is a process extension is not loaded: the keeper closes the program's input at the crash and writes itsjob_completedfrom the exit, and the resumed session runslineover the output file and writes theusage_recorded. Messages sent to the delegate while its parent is gone wait for the parent, which stands in for it (docs/delegates.md, "Delegates on another harness").
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
| Argument | Rule |
|---|---|
questions | 1 to 4 items |
question | the full question, with its context |
header | a short label, at most 12 characters |
options | none, for a free-text question, or 2 to 4, each a label and an optional description |
multiSelect | optional; the person may choose several options |
- There is no preview, no
requiredflag and no skip flag. Any question can be skipped. - The person can always type an answer, alone or with chosen options.
- The description tells the model to put a recommended option first, with "(Recommended)" in its label, and to ask with this tool rather than list choices in its reply.
- The definition is at most 1,200 bytes serialised, about 300 tokens, which a test checks, and counts toward the built-in budget ("Size budget in CI").
- The limits are in the schema (
minItems,maxItems,maxLength), so the tool is sent withstrict: false. - A call that breaks these rules fails with
invalid_arguments, as any call does ("Before a call runs"). - The tool declares no effect, so it never reaches a reviewer
(
docs/permissions.md, "Fast paths"). - It is declared in every session, including
fiber asksessions, forks and other delegates, so the tool set never differs between them.
When a person can answer
This is a session the hub started without supervised, which any client
may answer.
- One call raises one
forminteraction, with one field per question: select, multi-select or text input. Onereplyanswers the whole form. - It has no timeout. It lives like a pending approval: when
session.idle_exit_mspasses, the session exits on it withsuspended_on, and resuming raises it again (docs/invocation.md, "Lifecycle"). - The request and its answer are
interaction_requestedandinteraction_resolved(docs/events.md, "Interactions").
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.
- The turn ends
completed, with the questions onturn_completed. The call's result is one line saying the questions went to the driver.ask_userreturnscontrol.questions("What a result carries"). - A
closethat arrives while a question is pending ends the turn the same way. - The driver answers by resuming the session. The answers arrive as the next prompt.
- A delegate's parent reads the questions from
delegate_finished, which puts them in the wake. It answers withdelegate_message, or asks the person first with its ownask_user(docs/delegates.md, "Results"). fiber askexits 0 withquestionsonfiber_exited, and the caller resumes the session with the answers (docs/invocation.md, "What a caller gets back").- A supervisor reads the questions from
turn_completedon the event stream and sends the answers as its nextprompt.
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.
| Argument | Rule |
|---|---|
lines | the draft lines, one item per bullet or read-only entry |
topic | the heading the line belongs under: source_control, internal_hosts, internal_tools, routine_actions, never or read_only_commands |
layer | the layer the line belongs in: global or project |
text | the 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").
Web fetch and web search
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
- Arguments:
urlonly. There is no prompt and no second model over the page; the model reads the page itself. - The result begins with one line giving the final URL after redirects, the HTTP status and the content type. For an HTML page it also gives the path of the raw page.
- HTML is converted to markdown ("HTML to markdown"). Other text, JSON and XML come back as they are.
- Every HTML page is saved as downloaded to the session's
artifacts/, so the model can check a conversion that looks wrong withreadorgrep. - A PDF, or a PNG, JPEG, GIF or WebP image, is saved to the session's
artifacts/and the result gives its path. The model reads it withread, which already handles both ("File tools"). The saved file is the bytes as downloaded;readprocesses an image (docs/model-routing.md, "Image limits"). - Any other content type fails with
unsupported_file, giving its type and size. - The cap is the 16 KiB default ("Bounded results"). A cut keeps the start of the page, and the whole markdown is in the artifact.
- A download larger than 10 MiB fails with
too_large. - Each request times out after 60 seconds, and the whole fetch, redirects
included, after 5 minutes. Both fail with
timeout. - An address that does not accept a connection within 15 seconds is skipped
for the next; when none connects, the fetch fails with
connection_failed. - A status other than 2xx fails with
http_error, giving the status and the start of the body. - Redirects are followed, to any host, for at most 10 hops. Fiber judges only
the URL the model wrote, because the server chooses a redirect ("Effects").
An eleventh redirect, or one to a URL Fiber cannot parse, fails with
http_error. - A URL is fetched as written:
http://is not upgraded, so a server onlocalhostor an intranet host works. - Fetch refuses link-local addresses (
169.254.0.0/16,fe80::/10) and cloud metadata hosts such asmetadata.google.internal, and fails withblocked_host. Without a proxy, the check runs on every hop after the name is resolved, so a redirect or a DNS name cannot reach them. A metadata server hands out the machine's cloud credentials; loopback and private addresses are allowed, because reaching them is why fetch runs locally. - Through a proxy (
docs/dependencies.md, "Proxies"), the proxy resolves the name, so Fiber checks what it can see. The metadata host names are always refused. When the name also resolves on this machine, every address it resolves to must pass the check, or the fetch fails withblocked_host. A name that does not resolve on this machine goes to the proxy, so an intranet name only the proxy knows still works. What the proxy resolves a name to is the proxy's responsibility. - Writing to
artifacts/is part of the call. It is not awriteseffect.
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:
- Converted: headings, paragraphs, lists, links, images, emphasis, inline
code,
preblocks, block quotes and tables. - Dropped with everything inside them:
script,style,noscript,template,svg, and theheadapart from itstitle, which becomes a leading heading. - Everything else, including markup the converter does not know, passes its text through.
On any input, however malformed, the converter promises three things:
- No text a reader would see is lost, except inside the dropped elements.
- Its time grows in proportion to the page's size, except for a tag with a
very large number of attributes: checking each attribute against the
earlier ones takes time quadratic in their count, so a page that defeats
the converter this way fails the fetch with
timeout. - Its memory is bounded: deep nesting becomes neither recursion nor
unbounded indentation. Apart from the markdown it writes, the converter
holds 256 KiB of its own state, plus one byte per open hidden element
(
svg,noscriptandtemplate), whose stack holds at mostmax(64, 4 × open)bytes, plus the one token html5ever is reading. html5ever holds that token whole until it ends: a comment, an attribute value, or a tag with all its attributes, up to 3 bytes of decoded text per downloaded byte. A UTF-8 page-sized comment peaks at 17 MiB beside the output, and so does a UTF-8 page-sized attribute value. Each attribute of a tag held open holds about 45 bytes beside the output, about 40 bytes plus the attribute's name. The markdown is at most 14 times the decoded page, and decoding a character set writes at most 3 bytes of text per downloaded byte. The stop reaches the converter between 64 KiB pieces.
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
�.
web_search
- The model sees one tool,
web_search, whichever way it runs. - A hosted search is the vendor's own tool, sent as its type and name only. It has no description, and its settings, such as a domain list, are fixed in the request; the model's call carries only the query.
- Fiber's own tool, over a backend, takes
query(required), and eitherallowed_domainsorblocked_domains, never both. Its optional properties and theminLengthlimit put its schema outside the strict subset, so it is sent withstrict: false. web_searchhas a guideline line telling the model to end an answer that used search with a list of the sources it used, as markdown links (docs/system-prompt.md, "Tool guidelines"). It reaches the model whether the search is hosted or Fiber's own.- There is no limit on searches per turn or per session.
Hosted by the provider
- When the model's provider hosts a search, that search is used, even when a backend is also installed.
- Which models host a search, and which type each takes, is the model's
web_searchin the provider's extension: the vendor's own tool type, such asweb_search_20250305orgoogle_search(docs/model-routing.md, "Hosted web search"). Reading the hosted search's blocks is protocol code inanthropic-messages,openai-responses,openai-completionsandgoogle-generative-ai;openai-completionsreads them and sends back nothing. - Measured September 27, 2026: ChatGPT/codex, muse (only on its
/v1/responsesendpoint) and OpenCode (by passing Anthropic's and OpenAI's hosted tools through) host a search, and the OpenAI API, on the models marked. Measured October 18, 2026 onopenai/gpt-5.2:openrouter:web_searchonopenai-completionshosts a search, read fromresearch/web-tools/openrouter-web-search-probe-2026-10-18.json. Databricks does not: "Code interpreter and web search tools are not supported by Databricks." Which models accept the hosted search is research/web-tools/hosted-search.md. - The provider runs the search before Fiber sees it, so a hosted search is
never reviewed and cannot be refused. It writes
tool_call_startedandtool_call_completedlike any call, with the query and the result URLs. - Its raw blocks are logged exactly as they arrived, as the
provider_itemoftool_call_requested(the call) andtool_call_completed(the result) (docs/events.md). A call withprovider_itemis one the provider ran, so Fiber never reviews it, runs it, or gives it a result on resume. Itstool_call_completedcontent is the result URLs, one per line. A search that fails at the provider, such as Anthropic'sweb_search_tool_result_error, completesfailedwith the vendor's error code in the message. - The raw blocks are sent back unchanged only to the model that produced
them, the rule for reasoning state
(
docs/loop.md). Anthropic refuses a request whose encrypted search content was changed. After a switch to another model reference, the request leaves them out. Ongoogle-generative-ai, a request that declares function tools beside the hosted search setstoolConfig.includeServerSideToolInvocations; without it the request is refused. The search then arrives astoolCallandtoolResponsecontent parts, which replay with theirthoughtSignaturelike any signed part. The candidate'sgroundingMetadata, which no request field accepts, is logged in the last hosted result'sdetails: shown, but never sent back. Probed ongemini-3-flash-preview, October 9, 2026:groundingMetadataon a content or on a part is refused with 400 "Unknown name", and a follow-up turn without it searches again. - Whether a hosted search is declared is fixed when the preamble is built ("Which tools the model sees"). On Anthropic, turning it on or off changes the system prompt and so the cache.
usage_recordedcarries the number of searches when the provider reports it (docs/events.md), because hosted searches are billed per search.
Fiber's own, over a backend
- A search backend is an extension. Each search service has its own API, key and response shape. Fiber ships none installed.
- A backend registers with
fiber.search_backend(docs/extensions.md). Its function takes the query and the domain filter, and returns a list of results, each a title, a URL and a snippet. Fiber writes the result. - A backend's key is an extension secret, stored at
credentials/<backend>and read withhost.secret. - With one backend installed, it is used. With more than one,
web_search.backend(docs/configuration.md) names the one used. web_searchis not declared when the provider hosts no search and no backend is installed, when several are installed andweb_search.backendis unset, or when it names a backend that is not installed. In the last two cases anoticewith codeweb_search_unavailablenames the setting or the missing backend.- The cap is the 16 KiB default.
Effects
- Both tools declare
network. web_fetchdeclares the host of the URL as written inhosts. A search declares an emptyhostslist, because a query reaches only the search service, and its result lists the hosts of its result URLs inhosts_surfaced("What a tool declares").- So a search never reaches a reviewer or a person, and a fetch to a known
host takes the same fast path. Any other fetch is reviewed
(
docs/permissions.md, "Fast paths"). - A host is known in a session when it was named in one of the person's
messages or an instruction file, was listed in a result's
hosts_surfacedin the session, or was the host of a fetch a reviewer or a person allowed in the session. A host named only inside a fetched page is not known: otherwise an injected page could name its own host. - An instruction file the session's own calls changed makes no host known, in
any version: a file a
changesentry names, or one logged withown_edit(docs/events.md,instruction_file). Otherwise the model could write a fetched page's URL intoAGENTS.mdon the writes fast path and make its host known. - A host is named only by an
httporhttpsURL; a bare domain is not. Hosts match case-insensitively and exactly, with the port (the scheme's default when absent), so a subdomain is a different host. The result URLs of a hosted search make their hosts known, ashosts_surfaceddoes. - A query string does not make a fetch suspicious. A search on a known host, such as a Jira query URL, needs no review.
- What the reviewer is shown does not change: the person's messages, the replies they answer, and the
agent's tool calls, never a fetched page (
docs/permissions.md, "What it is shown"). - A standing deny still applies first, so the person can deny a host.
- A fetch's subject is its URL as parsed, whose path is at least
/, sohttps://example.comishttps://example.com/. The prefix it offers is the URL's scheme and host, ending in/. A search's subject is empty.
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.
- Argument:
name, 1 to 60 characters. An empty name fails withinvalid_arguments; only the person clears a name, with thenamecommand and empty text (docs/invocation.md, "What each command does"). - The description tells the model to name the session after the first prompt, and to rename it when the work's topic changes, a compaction included.
- A name the person set with the
namecommand pins it. While pinned, the call fails withname_pinnedand the message "the person named this session". Clearing the person's name unpins it. A rewind carries the name and its pin (docs/events.md, "Rewind"); a fork starts unnamed. - The tool declares no effect and never reaches a reviewer.
- It is declared in every session, so the tool set never differs between sessions. Its definition counts toward the built-in budget ("Size budget in CI").
- Each name is written as
session_named(docs/events.md). - The limits are
minLengthandmaxLengthin the schema, so the tool is sent withstrict: false. The call returnscontrol.name, and the loop writessession_namedand applies the pin.
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).
| Tool | Arguments | What it does |
|---|---|---|
session_list | none | Lists every running session of the account, delegates included. |
session_message | id, text | Sends 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:
unreachable: no running session has this id, whether it exited or never existedclosing: the target was sentcloseor is exiting (docs/invocation.md); afiber asksession is, from its startmessage_refused: the target'sbefore_messagerefused it, with the hook's reason (docs/extensions.md, "Hooks")tool_error: Fiber could not send the message because of a local I/O errorinvalid_arguments: the message's arguments did not fit the tool schemahook_failed: the target'sblockingbefore_messagefailed
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").
- Arguments:
text(required), matched as a literal, case-insensitive string;all_projects(optional, default false) searches every project in Fiber home instead of the session's own;limit(optional, default 20) is the most hits returned. - The session's own project is the sessions under
projects/<key>/whosesession_startedworkspace belongs to the same project as this session's, as resume checks it (docs/state.md, "Projects"); another project's sessions that share the key are searched only withall_projects. - It scans
events.jsonldirectly with the same ripgrep crates as the shell'sgrep("Search"). There is no index: the answer is always current, and nothing is written. A line that matches is decoded, and the text is matched against the decoded strings, so escaped newlines and quotes in the JSON never hide a match. The raw pass looks for the query as the log escapes it ("as\",\as\\, a newline as\n, other control characters as\u00XX), case-insensitively, so it selects every line whose decoded text could match. - It searches messages from the person and the model, the inputs of tool
calls, and their outputs, including the full outputs in
artifacts/. A search never returnssession_search's own calls or their results. - Each hit is labelled
message,tool_inputortool_output.messageis the text ofturn_startedmessage items,steering_applied,text_completed, and the answers ininteraction_resolved.tool_inputis theargumentsoftool_call_requested, and oftool_call_startedwhen a hook rewrote them, and thecommandofshell_command.tool_outputis thecontentoftool_call_completed, theoutputofshell_command,job_line,delegate_finishedandjob_completed'soutput_tailandnotice. No other event is searched, and reasoning is not. - Only text artifacts are searched. A hit in one is labelled
tool_outputand takes theseqof the line that names the artifact's path (artifactontool_call_completed,shell_commandordelegate_finished, or the job'sjob_startedfor a job's output file), and gives that path. When the same line also matched in its cut result, the result gives one hit, the artifact's. - Messages and tool inputs rank ahead of tool outputs, then newer before older, so a decision is not buried under every file read that mentioned the same name.
- Each hit carries the session id, its name as
session_statusgives it, the event'sseqand time,offset, the hit's line inevents.jsonl(seq+- for
read, the label, and a snippet of about 200 characters around the match. It never carries a whole event: the model reads around a hit withreadon the log, whose path the result gives.
- for
- The result is bounded like any other ("Bounded results").
- The tool declares
readsonprojects/<key>/, or onprojects/withall_projects, and is never reviewed. Neither is an ancestor ofcredentials/. Its definition never changes, so it is declared in every session, in full, and counts toward the built-in budget ("Size budget in CI"). - Its optional properties and the
minLengthandminimumlimits put its schema outside the strict subset, so it is sent withstrict: false. - Sessions are searched on parallel threads, at most as many as
std::thread::available_parallelismreports and never more than the sessions in scope, and every thread finishes before the call returns. - One scan of 1.3 GB of logs with no artifacts took 0.35 to 0.38 s warm on
macOS arm64 (11 cores); the same logs with a tool output in 25 saved as an
artifact took 1.0 to 1.1 s warm there. On a Linux x86_64 runner (ubuntu-24.04,
4 vCPUs), with the scan on parallel threads, the logs with no artifacts took
1.54 s warm and 3.05 s cold (cold eviction unconfirmed: no
fincoreon the runner). Timings and method: research/session-search.
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:
| Provider | Source | Reports |
|---|---|---|
| ChatGPT/codex | /wham/usage | percent used of a primary and a secondary window, with reset times |
| OpenCode | GET /zen/go/v1/usage | percent used of Go's rolling, weekly and monthly windows, with reset times; Zen reports none |
| OpenRouter | GET /api/v1/key | credit 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, Azure | none | no 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.
| Harness | Source | Reports |
|---|---|---|
| Claude Code | /api/oauth/usage with Claude Code's own login, and the rate_limit_event lines a running delegate prints | percent used of the five-hour and seven-day windows, with reset times |
| cursor-agent | none yet | no 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:
- windows, each with its name, percent used and reset time where the provider reports one
- credit remaining and the limit
no quota reported, for a provider or harness withoutquota()unreachable, when the fetch failed or timed out, with the last value and its age if there is oneno value yet, for a label whose first fetch is still in flight, with no last value
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:
- a model call to that provider
- a
delegate_modelscall - a keypress, or the terminal regaining focus
/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".
- Arguments:
name(required), a name from the skills listing. - The result is the body after the header, under the skill's path, so files the
skill refers to can be read with
read. A name that is not in the listing, a skill withdisable-model-invocation: true, or a skill switched off inskills.disabled(docs/system-prompt.md, "Skills"), fails withinvalid_arguments. - Its definition never lists skill names. The names are in the listing, so
adding or removing a skill never changes the tool set and the cached prefix
holds (
docs/prompt-cache.md). - Fiber records each load as the result's
control.skill, so it knows which skills the current context is working under. A compaction sends them again after the note (docs/compaction.md, "What the model sees after a compaction"), and the terminal shows each load as a skill, not as a file read. - It declares
readson the resolved target of the skill's file, and a link that changes before the read fails the call withpath_changed. It is never reviewed. It is declared in every session, in full, and counts toward the built-in budget ("Size budget in CI").
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:
- Provider quota: each provider reports it differently, and providers are already extensions, so the quota lookup lives in each provider's package ("Provider quota").
- Web search backends: each search service has its own API, key and response
shape. The
web_searchtool itself is compiled in ("Web fetch and web search"). - Compact build and test output (the owner's
structured_return): parsing depends on the person's toolchain, so it is an extension over an after-tool hook that replacescontent, with the full log in the artifact. - Delegate harnesses other than Fiber, such as Claude Code and cursor-agent:
each runs another vendor's agent program (
docs/delegates.md, "Harness 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
- A model's provider data says whether deferral works for it
(
docs/model-routing.md). It says so only after a probe shows a deferred tool loading through that provider (except the Databricks Claude rows set from theirproviders/anthropiccounterparts under RULING-4040-1 below), because support varies within a protocol: probed on September 24, 2026, Muse'sopenai-responsesendpoint deferred and kept the cache, while OpenRouter's accepted the same request for GPT-6 Luna, sent every definition in full and let the model call a deferred tool without loading it. - The probe is
cargo run -p provider --example probe -- PROTOCOL BASE_URL MODEL KEY [--bearer] [--store=false] [NAME:VALUE]...(docs/testing/fakes.md, "Jigs"). It sends the model one request with the probe's tools in full and two with them deferred, and printspassorfailforload(the model searches first, and calls the loaded tool only after the load) andcache(the request after the load reads cache tokens); a check the run did not establish printsfailwith the reason. It exits 0 when all pass, 1 when a check fails, 2 on a usage error, 3 when it cannot tell and 4 when the key is refused. A model's data setsdeferred_toolsonly for apassrecorded below, except the Databricks Claude rows set from theirproviders/anthropiccounterparts under RULING-4040-1 below. A row probed after this change carries its spend on the run's printed summary line. - The probe printed no spend for the 2026-11-03 runs: the only token figure it emitted was the final request's input count inside the cache detail, which covers one of three requests and no output tokens, so the spend for each row below is unknown and is not estimated.
- Probed 2026-11-03 on
https://api.anthropic.com/v1:anthropic/claude-fable-5pass, spend unknown;anthropic/claude-fable-5-1pass, spend unknown;anthropic/claude-haiku-4-5pass, spend unknown;anthropic/claude-haiku-4-5-20251001pass, spend unknown;anthropic/claude-haiku-5-5pass, spend unknown;anthropic/claude-opus-4-5pass, spend unknown;anthropic/claude-opus-4-5-20251101pass, spend unknown;anthropic/claude-opus-4-6pass, spend unknown;anthropic/claude-opus-4-7pass, spend unknown;anthropic/claude-opus-4-8pass, spend unknown;anthropic/claude-opus-5inconclusive (probe declined to answer: This request was blocked as it seems to violate Anthropic's Terms of Service restrictions on reverse engineering or duplicating model outputs. To learn more, visit https://www.anthropic.com/legal/commercial-terms. API integrators: you can reduce refusals for your users by configuring a fallback model — see https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback.), spend unknown;anthropic/claude-opus-5-5pass, spend unknown;anthropic/claude-sonnet-4-5pass, spend unknown;anthropic/claude-sonnet-4-5-20250929pass, spend unknown;anthropic/claude-sonnet-4-6pass, spend unknown;anthropic/claude-sonnet-5pass, spend unknown;anthropic/claude-sonnet-5-5pass., spend unknown - Probed 2026-11-03 on
https://api.openai.com/v1:openai/gpt-5.4pass, spend unknown;openai/gpt-5.4-minipass, spend unknown;openai/gpt-5.4-nanofail (load: HTTP 400: Tool 'tool_search' is not supported with gpt-5.4-nano.), spend unknown;openai/gpt-5.4-profail (cache: cache read 0 of 4354 input tokens), spend unknown;openai/gpt-5.5pass, spend unknown;openai/gpt-5.5-profail (cache: cache read 0 of 4598 input tokens), spend unknown;openai/gpt-5.6-lunapass, spend unknown;openai/gpt-5.6-solpass, spend unknown;openai/gpt-5.6-terrapass, spend unknown;openai/gpt-6-astrainconclusive (the model did not call the loaded tool), spend unknown;openai/gpt-6-lunapass, spend unknown;openai/gpt-6-solpass, spend unknown;openai/gpt-6.1-solinconclusive (the model did not call the loaded tool)., spend unknown - Probed 2026-11-03 on
https://api.openai.com/v1(repeat):openai/gpt-6-astrainconclusive (the model did not call the loaded tool), spend unknown;openai/gpt-6.1-solinconclusive (the model did not call the loaded tool), spend unknown. - Total spend for the 2026-11-03 probe runs: unknown.
- Probed 2026-11-04 on the Databricks AI gateway (
/ai-gateway/anthropic/v1):databricks/databricks-claude-opus-5-5pass, spend 19470 input and 153 output tokens. The run printed:probe: anthropic-messages databricks-claude-opus-5-5 load: pass (searched, loaded probe_calendar_create, then called it) cache: pass (cache read 6329 of 6524 input tokens) probe: pass spend: 19470 input, 153 output tokens - The other Databricks Claude rows follow their
providers/anthropiccounterparts: set when that row hasdeferred_tools, unset when unset or inconclusive (databricks-claude-opus-5);databricks-claude-opus-5-5is set from its direct 2026-11-04 probe. Exception: theclaude-sonnet-4-5/claude-sonnet-4-5-20250929Databricks rows do not follow their Anthropic counterparts — those Anthropic rows carrydeferred_tools, but the Databricks rows don't, because the gateway rejects their deferred load (probed 2026-11-11, #4617). Pass-through was proved only on that model; uniform handling across rows is assumed. - Anthropic and OpenAI Responses (gpt-5.4 and later) both defer natively.
openai-completionsandgoogle-generative-aido not. - On a model without deferral, every tool is declared in full and
tool_searchis not declared.
What is deferred by default
- Every tool declares whether it is deferred by default. Configuration can
override that for any tool (
docs/configuration.md), and an MCP server can be markeddeclare_in_full(docs/mcp.md). - MCP tools and
mcp_resourcesare deferred by default. Every other built-in is declared in full. - A tool the provider hosts is never deferred: it is sent as its type and name only, so there is nothing to load.
tools."<name>".deferredhas no effect on it. - A built-in is deferred by default only when it is used in under about 2% of the owner's sessions and is not part of how they direct delegates.
Tool search
tool_searchis a built-in tool the model calls to load deferred tools. It is declared, in full, only when the model supports deferral and at least one tool is deferred.tool_searchis never deferred;tools."tool_search".deferredhas no effect and is reported as anotice.- Fiber runs the search itself: BM25 over each deferred tool's
name, description and parameter names. It returns at most 8 tools by default;
the model may pass
limit. queryis required and not empty;limitis at least 1, with no maximum. A search runs over every deferred tool, loaded or not, andloadedlists its hits best first, ties by name. A search that matches nothing completes with an emptyloadedand says so in text. Several searches in one step are separate calls.- The result goes back in each protocol's native form:
tool_referenceblocks on Anthropic,tool_search_outputon OpenAI Responses. Fiber never uses a provider's own search, so every provider behaves the same and every search is on the log. The log records the result asloaded, the list of tool names, and each protocol renders its block from that list, so a resume sends the same bytes. - Its description lists the sources of the deferred tools (each MCP server's name), fixed when the preamble is built.
- A search is an ordinary tool call. A resume, fork or rewind re-sends its result byte for byte while the preamble defers the same tools; otherwise the result leaves out the names it no longer defers, as above.
- A cancelled search loads nothing; its result is the line "The search was cancelled; no tool was loaded."
- A loaded tool stays loaded until a compaction, which restarts the conversation after the preamble (
docs/compaction.md); after that the model searches again. A reload or a model switch keeps it: each request renders every search result fromloaded, leaving out names the preamble it sends does not defer, and on a model without deferral renders it as text naming the tools. - A call to a deferred tool that was never loaded runs like any other call, after the schema check.
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
/toolsin the terminal, and thetoolsdriver command (docs/invocation.md), list every declared tool with:- its source: built-in, extension or MCP server; an MCP tool's source also gives the server's own name for it, which the server's
tools.enabledandtools.disabledname - its state: full, deferred or loaded
- its approximate size in tokens
- its source: built-in, extension or MCP server; an MCP tool's source also gives the server's own name for it, which the server's
- A tool's size in tokens is estimated from its size in bytes. The
bytes-to-tokens rate comes from the session's own first request after the
last preamble build: every input token it reported in
usage_recorded, whether uncached, read from the cache or written to it, divided by the request's input size in bytes (input_bytesonusage_recorded,docs/events.md). A request that carries an image or PDF part (input_media) is skipped for the next one without, because those parts' bytes bear no relation to their tokens. A request that reported no input tokens, such as one that failed before the provider named its generation, is skipped the same way. Until a request gives a rate, sizes are shown in bytes. The rate updates just afterusage_recordedis written, so atoolsrequest sent the moment that event arrives can still show the previous rate. preamble_builtrecords, for each tool definition, whether it was deferred (docs/events.md).
Size budget in CI
- CI fails the build when the built-in tool definitions grow past a total budget in bytes. It serialises them in every protocol's request shape, and the budget limits the largest total. CI counts bytes because it cannot count tokens without calling a provider.
- The budget starts at the largest total at the commit that adds the check, with no headroom. Raising it is an explicit change in the same pull request that grows a definition.
- Every CI run that tests the
maincrate prints the size of each built-in definition in each protocol, so the tool that grew can be seen without reproducing the build.
Not settled here
- Each tool's own design: the tickets indexed in Epic: tools.
- Delegates are
docs/delegates.md, which lists what it leaves open. - Comparisons with other tools, and the owner's usage, behind this area's rules: research/reference-comparisons/README.md