fiber

The loop

What one turn does, from its input arriving to turn_completed. This is what is true now, not a plan. It is settled by The turn: what one run of the agent loop does; that ticket's resolution holds the rationale and the rejected alternatives. How reference agents run a turn is research/the-turn/README.md.

Vocabulary is GLOSSARY.md. Turn, step, action, tool call and event mean what it says there and nothing else. The threads and the inbox are docs/architecture.md, "Concurrency"; the events are docs/events.md.

Starting a turn

When the loop is idle, the first thing to arrive in its inbox starts a turn: a person's or a driver's message, or news that a job finished (docs/tools.md, "Background jobs"). Everything waiting in the inbox at that moment is the turn's input, in the order it arrived, so three messages sent together start one turn, not three.

before_message runs on each message before it is logged. Then turn_started is written, and turn_start runs before the first model request (docs/extensions.md, "Hooks"). A process's first turn first runs session_start hooks, after the opening message and before turn_started; a process that never takes a turn runs none (docs/extensions.md, "The hook points").

One step

A step is one round-trip to the model. Each step does this, in order:

  1. Write step_started (docs/events.md, "Session and turn"). Drain the inbox. Every steering message and every job notice waiting joins the conversation, in arrival order, each job notice after the after_tool hooks have run on it (docs/extensions.md, "Hooks"); each steering message is logged as its own steering_applied. Nothing is held back for a later step.
  2. Check how full the context is, and compact if it is past the threshold (docs/compaction.md, "Triggers").
  3. Build the request: the preamble (docs/prompt-cache.md) followed by the conversation ("What the model is sent"). Then check the budget and run before_model_call ("Spending budget").
  4. Send it and stream the reply, emitting its actions as they arrive. A tool call's arguments stream as raw text in tool_call_arguments_delta (docs/events.md) and are parsed once, when the model finishes emitting the call. A failed call is retried as docs/model-routing.md, "When a model call fails", says.
  5. For each tool call in the reply, in the order the model emitted them: check the tool exists and the arguments match its schema, run its effects function, run before_tool, then decide permission (docs/permissions.md). Every call is decided before any runs.
  6. Run the approved calls concurrently, one thread each (docs/architecture.md, "Tool calls in a step"). after_tool runs on each call that ran.
  7. Return every result to the model in the order the calls were requested, and take the next step.

A reply with no tool call ends the step without a next one ("Ending a turn").

During a turn the loop reads its inbox at three points: at a step boundary (step 1 above, and the check before a turn ends), while it waits for a person's reply to an approval, and while it waits for its calls to return, for session messages only. While it sends a request and streams the reply, nothing reads the inbox. A steer is queued and steering_queue written at once, and a steer_drop takes effect at once, at any point in the turn: the thread reading the connection does both (docs/architecture.md, "One inbox"). While it waits on an approval, everything else that arrives is answered at once: a compact is accepted, a second reply is rejected stale_request, and a close ends the wait with the request unanswerable (docs/permissions.md, "Headless"). What these queue (steering messages, a compaction, job notices) joins the conversation at the next step boundary. Commands answered during a turn, such as job_stop, shell, tools and history, are answered at once by the door, without the inbox (docs/invocation.md). A cancel ends the turn ("Interrupt").

Tool calls that do not run

A call the loop cannot run fails, and the turn continues. The model is told why, in words it can act on:

CauseStatusCode
No tool has that namefailedunknown_tool
The arguments are not JSON, or do not match the schemafailedinvalid_arguments
Permission refused itdenied
The reply was cut off ("A reply cut off by the output limit")failedoutput_truncated

A denied call does not stop the calls beside it: they run, and the turn continues. A person who wants the turn to stop sends cancel; reply has no option that does both.

A reply paused by a hosted tool

An anthropic-messages reply stops with pause_turn when a long-running hosted tool, such as the hosted web_search ("Web search" in docs/tools.md), is paused by the provider. The reply is not the end of the turn and is not a failure. The loop continues it inside the same step's turn: it sends the request again with the paused reply appended as the last assistant message, unchanged, as Anthropic documents (docs/model-routing.md, "Anthropic messages wire facts"). Each continuation is a model call like any other: it is logged, counted against the budget and retried as docs/model-routing.md, "When a model call fails", says. The paused reply's text and actions are kept.

A turn continues a paused reply at most 5 times in a row. The number is picked, not measured. If the reply is still paused after that, the turn fails with paused_too_long, and the message carries pause_turn.

A reply cut off by the output limit

When a reply stops because it reached the request's output-token limit, its text is kept and none of its tool calls runs, however many there are. Each fails with output_truncated, and its result tells the model its arguments may be incomplete and to re-issue the call, split into smaller calls if it was large. The turn continues.

If the next reply is cut off too, the turn completes failed with code output_truncated. A model that cannot fit a call in its output limit would otherwise pay for that limit on every step, with nothing to stop it.

Fiber does not resend the same request after a cut-off. The same request tends to stop at the same place.

Ending a turn

A turn ends in one of three ways:

Before a reply with no tool call completes the turn, the loop drains its inbox once more. Anything waiting, such as a steering message sent while the model wrote its final reply, or a job that finished meanwhile, continues the same turn with another step. Only when nothing is waiting does turn_end run, and a message it returns also continues the turn. When turn_end returns nothing, turn_completed is written. A one-turn fiber ask therefore includes a job that finished during its last reply.

A reply with no text and no tool call is a reply with no tool call: the turn completes normally.

There is no limit on steps per turn. Spending too much is the concern of a budget ("Spending budget"), not a step count, and a caller can always send cancel.

Spending budget

Settled by Token and cost display, and spending budgets; that ticket's resolution holds the rationale and the rejected alternatives.

budget.usd caps what a session spends, in US dollars billed per token (docs/configuration.md, "Keys"). It is unset by default, and unset means no limit. The spend it counts is the usage fold (docs/events.md) over the session's own log, which holds its own usage_recorded lines and a copy of each one its delegates sent it, and theirs. A parent writes a copy of each usage_recorded it receives from a delegate into its own log, naming the delegate in origin_session_id, and the fold counts one line per generation_id. A resumed parent reads the log of each delegate that ran while it was gone, or that it marks orphaned, and writes any copies it is missing. A call with subscription does not count, because a subscription bills nothing per call; its own limit ends it as quota_exceeded. A cost still null counts as zero until it settles.

Once each step's model request is built, before it is sent, the loop checks the budget and then runs before_model_call hooks (docs/extensions.md, "The hook points"). When the spend has reached budget.usd, or a hook refuses, the request is not sent:

The budget is also checked whenever a delegate's usage_recorded arrives, because a session waiting in jobs wait makes no model request of its own. When that line reaches the limit, the thread reading the delegate stops the running delegates at once, outside the inbox, as cancellation is (docs/architecture.md, "One inbox"). The loop's next request is refused budget_exceeded as above.

The reviewer checks the budget too, before each reviewer request (docs/permissions.md, "The reviewer"). A tool call that needs review once the spend has reached budget.usd is denied without another reviewer request. That holds even when the call's own first stage spent the last of the budget and its second stage is refused. Its permission_resolved has decided_by: budget and no reviewer, and the call completes denied with reason budget_exceeded. The next step's check then ends the turn as above.

A call that crosses the limit completes, so the tree overshoots by at most one call in flight per running session in it, or by one run of a delegate on another harness, which reports its cost only when the run ends. A delegate checks no budget of its own; its parent's covers it. To continue, the person raises budget.usd and reloads (/settings does both), or resumes with -c budget.usd=… (docs/configuration.md, "When Fiber reads configuration"), then sends a message.

Interrupt

A cancel stops the model request or the running tool calls (docs/tools.md, "Cancellation"). Before turn_completed is written with outcome interrupted, every tool call in the step that has no tool_call_completed gets one with status cancelled: calls waiting for approval, calls not yet started, and calls stopped mid-run. A call waiting for approval, or on a question, first gets its request's resolved line (docs/architecture.md, "Cancellation"). The log therefore never ends a turn with a call or a request left open. Queued steering messages then start the next turn.

What the model is sent

The conversation in each request is built from the session log's durable events, the only state of record (ADR 0001). The loop keeps it in memory as the turn goes, and never re-reads the file to build a request. Deltas are ephemeral, so partial text from an interrupted reply is never sent.

Every tool call is sent with a result, because every provider refuses a request that has a call without one. A call with no tool_call_completed, which only a crash can leave (docs/events.md, "Resume"), is sent with a fixed result: that it never ran when the log shows no tool_call_started, or that its outcome is unknown when it does. Fiber never runs such a call again; the model may make it again (docs/events.md, "Resume"). The unknown-outcome result tells the model to check for the call's effects in the workspace, in git and in any outside service it reaches before making it again.

The reasoning state a provider returns with a reply, such as Anthropic's signed thinking blocks, OpenAI's encrypted reasoning and Gemini's thought signatures, is logged exactly as the provider returned it, and sent back unchanged to the model that produced it. The provider checks only the opaque part, the signature or encrypted content, and refuses a request in which it was changed. Leaving reasoning out is accepted but loses the prompt cache from that point on. Gemini is the exception for tool calls: it refuses a replayed functionCall that has no thought signature. Reasoning is never sent back as plain assistant text, on any protocol or after a model switch. What a provider cannot take in its own form is left out.

A reply is logged as its items in the order the model produced them: each text part, each piece of reasoning and each tool call is its own item (docs/events.md, text_completed). A text part keeps its own thought signature or other opaque data. The reply is rebuilt for a request from those items in that order, so every part, a repeated text included, goes back to the model that produced it unchanged. A text part's opaque data goes only to the model that produced it; its words go to every model.

Each reasoning item goes only to the model that produced it, by its whole model reference, provider/model (docs/model-routing.md). After /model or the model command switches to another model reference, a request leaves out every reasoning item another one produced: both the opaque part and its readable text. A change of thinking level alone keeps the model, so its items are still sent. A fork keeps its parent's model and sends them unchanged. Probed on Sonnet 5, Haiku 4.5 and GPT-6 Luna: research/reasoning-resume/.

Tool calls and their results are not reasoning, so they are always sent. Most protocols take a call another model reference made in its native form. google-generative-ai does not, because the call carries no thought signature from that model. On that protocol, a call and its result that another model reference made are sent as plain text: the tool's name, its arguments and the result. The model's own calls stay native and keep their signatures (docs/model-routing.md, "Google Generative AI wire facts").

What the loop does not do