fiber

Delegates

How a session hands part of its work to another agent session, talks to it, and gets its result. This is what is true now, not a plan. It is settled by Subagents and delegates: one delegate, on one stream; that ticket's resolution holds the rationale and the rejected alternatives.

Vocabulary is GLOSSARY.md. Delegate, harness, fork, job, session, steering message and step boundary mean what it says there and nothing else. Job behaviour is docs/tools.md, "Background jobs"; the events are docs/events.md.

What a delegate is

Harnesses

The tools

ToolArgumentsWhat it does
delegate_spawndescription, prompt, model, isolation, workspace, timeout_msStarts a delegate. Returns a receipt with the delegate id and the output path.
delegate_forkdescription, prompt, isolation, timeout_msStarts a Fiber delegate from the parent's conversation. No model or thinking level: see "Forks".
delegate_messageid, messageSteers a running delegate, or resumes a finished one.
delegate_modelsfilter (optional)Returns the session's own model first, then the configured roles, what each maps to now, the references available grouped by provider with counts, and the quota of each provider credential label and harness (docs/tools.md, "Provider quota"). filter keeps only references containing it.
jobsas docs/tools.mdLists, waits for and stops delegates.

Choosing a model

Talking to a delegate

Identity and resume

Results

Events

The job_* kinds are unchanged. A delegate adds two kinds keyed by job_id, as job_line is for monitors: delegate_started, naming the delegate's session, harness, model, workspace and worktree, and delegate_finished, carrying its final message, any questions, usage totals and worktree state. Their keys are docs/events.md, "Jobs".

Streams

Permissions

Limits

Lifetime

Worktrees

A malformed isolation or workspace fails with invalid_arguments before model or credential lookup. With well-formed arguments and no worktree, the child launch reports its own failure. With worktree isolation, a non-git path is invalid_arguments and a git failure is io_failed.

Forks

Harness extensions

Not built yet: see #545.

Settled by Harness extensions: running another agent as a delegate; that ticket's resolution holds the probes and the rejected alternatives.

A harness extension registers with fiber.harness(name, { ... }) (docs/extensions.md, "Registering"). The name is the first part of every model reference on it, such as claude in claude:opus:high.

What it declares

As data, for the harness:

As data, for each model:

As Lua, none of which runs on a model request:

How Fiber runs it

Delegates on another harness

Not built yet: see #545 and #547.

A delegate on another harness has no socket of its own, so its parent stands in for it in session messaging (docs/tools.md, "Messaging other sessions"):

Each tool's description says what it reaches. The harness's own tools stay switched on: Claude Code's SendMessage and ListAgents reach its own subagents and other Claude Code sessions, and session_message reaches the sessions session_list shows, by a Fiber session id.

The parent stays on the receiving path because it holds the one input the harness documents. Probed on Claude Code 2.1.285, headless:

If Claude Code documents its inbound socket, a Claude Code delegate could take session messages directly and the parent would drop out of the path.

Claude Code

Not built yet: see #545.

WhatHow
Startclaude -p --output-format stream-json --verbose --input-format stream-json --session-id <uuid> --model <model> --effort <effort> --permission-mode auto
Resumethe same, with --resume <session-id> in place of --session-id
Auto mode--permission-mode auto, declared per model
Messages while runningyes, as a user line on its input; it joins the turn at the next step boundary
Session messages out--mcp-config naming fiber mcp serve, which adds it for the run and keeps the person's own servers
Final answer, usage, costthe result line: result, usage and total_cost_usd
Subscriptionthe system init line's apiKeySource: none is the subscription login, and total_cost_usd is then an API-price estimate
Quotarate_limit_event lines while running, and quota() from /api/oauth/usage with Claude Code's own stored login
SIGTERMstops cleanly, so it gets the shutdown wait

Probed on Claude Code 2.1.284:

cursor-agent

Not built yet: see #546.

WhatHow
Startcursor-agent -p --output-format stream-json --trust --approve-mcps --model '<model>[effort=<effort>]' --auto-review
Resumethe same, with --resume <chat-id>
Session idcursor-agent create-chat before the first run
Auto mode--auto-review
Messages while runningnone: delivered as a resume
Session messages outan entry for fiber mcp serve in ~/.cursor/mcp.json, which has no per-run flag. Fiber asks the person once, the first time a cursor-agent delegate starts, and remembers the answer. With no entry, a cursor-agent delegate receives session messages but cannot send them
Final answer, usagethe result line: result and usage, which has tokens and no cost
Costcomputed from the declared prices
SIGTERMnot probed, so it gets SIGKILL at 800 ms like any command

Probed on cursor-agent 2026.09.26:

Not yet probed: create-chat, which is from --help; whether --auto-review overrides the person's approvalMode; what SIGTERM does; and where its quota comes from. Until its quota is known, the cursor-agent harness declares no quota().

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