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
- A delegate is an agent session a session starts to do part of the work. It runs Fiber or another harness, such as Claude Code or cursor-agent. Another harness is not built yet: see #545.
- Every delegate is a job. It gets a receipt, an output file, a wake on
completion, and is listed, waited for and stopped with
jobs. A delegate always runs in the background; no call blocks until a delegate finishes. A parent that needs the answer at once callsjobs wait. - A delegate is its own session, with its own
session_idand its own log. Itssession_startedrecords the parent'ssession_idand its delegate id. That is how any code tells a delegate from a top-level session. - The session that starts a delegate is its parent.
Harnesses
- The Fiber harness is built in.
- Every other harness is an extension: data plus Lua, as a provider is. What it declares is Harness extensions.
- Fiber ships the Claude Code and cursor-agent harnesses. codex and others follow, unless adding them is trivial. Not built yet: see #545 and #546.
- A harness loads whatever the person configured for it: their hooks, plugins, skills, MCP servers, instructions and memory. Fiber passes only the flags that drive the program.
- The delegate tools belong to Fiber. Another harness's own subagents stay
switched on, inside its process and under its own limits, and so does any
delegation tool the person configured for it. Fiber's depth cap and
concurrency limit do not reach inside another harness. Fiber serves no MCP
for delegating to Fiber
(ADR 0005). Any
harness can run
fiber askfrom its shell.
The tools
| Tool | Arguments | What it does |
|---|---|---|
delegate_spawn | description, prompt, model, isolation, workspace, timeout_ms | Starts a delegate. Returns a receipt with the delegate id and the output path. |
delegate_fork | description, prompt, isolation, timeout_ms | Starts a Fiber delegate from the parent's conversation. No model or thinking level: see "Forks". |
delegate_message | id, message | Steers a running delegate, or resumes a finished one. |
delegate_models | filter (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. |
jobs | as docs/tools.md | Lists, waits for and stops delegates. |
descriptionis a short label for people.isolationisnone(the default) orworktree.workspacedefaults to the parent's workspace. A delegate started inside a worktree delegate defaults to that worktree. Every delegate the session starts, forks included, also runs with the parent's added folders as they are when it starts. Before its first request, it records each one its own history does not already hold asdirectory_added(docs/events.md). A fresh spawn lists those folders in its opening without separate folder-added messages. A fork usually writes no duplicate events; if a folder was added after its point, it records that folder and its normal message follows the byte-identical prefix. The delegate tools take no new argument for them.timeout_msis optional, with no default. At the deadline, the delegate is stopped like any job and endsfailedwith codetimeout. A delegate has no other deadline: a Fiber delegate's shell commands carry their owntimeout_ms, and another harness is bounded bytimeout_ms,jobs stop,job_stop, or the caller's SIGTERM.- The output path is the delegate's own
events.jsonlfor a Fiber delegate, and the harness's raw stream in the parent'sartifacts/for any other. - A Fiber delegate's final message is in its own session's
artifacts/final.md, and the wake andjobs waitname that path. - If a Fiber delegate fails before its session exists,
jobs listshows its error and omits the missing log path. - Every tool is declared from the first request of a session and never removed. A tool that cannot be used, such as a delegate tool at the depth cap, fails its call with a stable code.
Choosing a model
modelis a configured role name, or a full referenceharness:provider/model:level, such asclaude:opus:high,fiber:openai/gpt-5.6:xhighorcursor-agent:composer-2.5. The last part is the harness's own word: for Fiber it is a thinking level (docs/model-routing.md, "Thinking"), for another harness it is passed to that harness's flag, such as Claude Code's--effort(cursor-agent writes it inside its model name).- A bare
provider/modelreference resolves tofiber:provider/model; only switched-on providers count. - It is required and checked when the call is made. The schema leaves it
optional and untyped, so a missing or wrong value reaches that check. An
invalid value fails with
invalid_argumentsand lists the roles in full on one line, up to 3 closest references nearest-first with ties in sorted order, and namesdelegate_modelsfor the rest. - A thinking level the model does not take fails the same way, and its reason names the levels that model takes before the roles line.
- A model refusal names at most 3 suggested references and one model's thinking levels. Apart from the names it echoes, such as roles, the model asked for and suggested model ids, which print in full, it stays within 2 KB.
- Neither the roles nor the references appear in any tool definition or the
system prompt. They change when config changes, when a provider withdraws a
model, or when model discovery refreshes, and a tool definition that changes
during a session misses the whole prompt cache.
delegate_modelsreturns them as a tool result instead. delegate_modelslists references only from switched-on providers (docs/model-routing.md, "Credentials"). A role targeting a logged-out provider is marked(unavailable). Naming that role or the provider's model in a delegate call fails before any process starts.- The switched-on rule is the session's (
docs/model-routing.md, "Naming a model"): only switched-on providers count when a bare id resolves, and a delegate call applies the same narrowing to a full reference. - A role is a name for a model reference, for example
deepforclaude:opus:high. A role may also name a credential label, so one project's delegates can run on different subscriptions of one provider (docs/model-routing.md, "Which credential a session uses"). A delegate started with a full reference uses the provider's configured label. The model sees only role names, never labels. Written instructions such as skills, prompt templates and AGENTS.md name roles, so they survive a model being withdrawn and work on any machine. Remapping a role changes nothing the model sees. - The model is fixed when the delegate starts and never changes.
- A reload refreshes the parent's lookup and catalogue, so later spawns
see the reloaded models; a running delegate keeps the model it
started with. Start-time and background refresh use the configured
model_lists.refresh_afterage and the provider-source mtime; reload refreshes only when the source is newer than the cached copy, with no maximum age.
Talking to a delegate
delegate_messageto a running delegate whose harness takes messages while running (Fiber and Claude Code) sends a steering message. It joins the delegate's turn at its next step boundary.- To a running delegate whose harness cannot take one, the message is queued and delivered as a resume when the delegate finishes.
- To a finished delegate, it resumes it. A Fiber delegate exits as soon as its run finishes ("Lifetime"), so most messages to a finished delegate are resumes.
- The receipt says which of these happened.
delegate_messagewith an empty message, or one of only whitespace, failsinvalid_argumentsand sends nothing.- A person reaches a delegate on its own connection: a client that opens a
delegate subscribes to it through the hub and sends it
steerthere, as to any session. No session forwards a command to another. How the terminal shows and steers delegates isdocs/tui.md. delegate_messageacts only on the caller's own delegates, asjobsdoes.- Any session reaches any running delegate, a sibling included, with
session_message(docs/tools.md, "Messaging other sessions"). A Fiber delegate takes it on its own socket. A delegate on another harness takes it through its parent ("Delegates on another harness").
Identity and resume
- A delegate has one id for life, which is its
job_id. - Each run writes one
job_startedand onejob_completedunder that id. A resume is a new run of the same job. - A resume continues the delegate's own session and goes back into its kept worktree.
Results
- When a delegate finishes, the parent is woken as for any job. A Fiber
delegate's final message is written whole, whatever its length, to
artifacts/final.mdin the delegate's own session directory, and the wake and thejobs waitresult both name that file by its absolute path. The wake carries the message bounded asdocs/tools.md, "Bounded results", says: the first 16 KiB, with the notice naming the file when the message is cut. A delegate the parent settles from its own log after a resume carries the same bounded final message, and its file is written then. The parent, or another delegate, reads the rest with the ordinaryreadtool on that path. jobs waitreturns the final message as the delegate wrote it; the file holds it after the session's hooks, so the two can differ when a hook changed it.- A delegate that asks with
ask_userends its turn, and the wake carries its questions fromdelegate_finished. The parent answers withdelegate_message, which resumes the delegate, or asks the person first (docs/tools.md, "Asking the person"). - There is no status field beyond
job_completed'scompleted,failedandcancelled. - A failed delegate's job report adds the
Provider said:line perdocs/errors.md, "The shape". - The wake is built only from logged fields. Nothing in it is rendered from the clock.
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".
delegate_startedis written afterjob_started, for each run.delegate_finishedis written just beforejob_completed, except for a delegate that ended while its parent was gone: the keeper wrote itsjob_completed, and the resumed parent writesdelegate_finishedwhen it delivers the result.- The usage totals are output, never a source, as
fiber_exited's copy of the final text is. For a Fiber delegate, the cost ledger is the fold over the delegate's ownusage_recordedlines, and a cost that settles after the delegate finishes appears only in the delegate's log. Another harness has no Fiber log, so the parent writes oneusage_recordedper run in its own log, naming the harness, from the usage the harness reports at the end of the run. - A delegate's
session_startedcarriesparent { session_id, delegate_id }and, for a fork,forked_from { session_id, seq }.
Streams
- Each delegate's stream is its own. A parent reads its Fiber delegate's stream as an ordinary client of the delegate's socket. Nothing a delegate emits is relayed onto its parent's stream, and nothing is forwarded down the tree.
- One kind is copied: each
usage_recordeda parent receives from a delegate is copied into the parent's own log withorigin_session_id, and a fold counts one line pergeneration_id, so a call is counted once. A grandchild's lines reach the root through its parent's log. The root's log then holds the whole tree's spend (docs/loop.md, "Spending budget"). - A client shows a delegate's card from that delegate's
session_status, read over asummaryconnection, and its conversation over afullone when the person opens it (docs/tui.md). - Another harness's raw stream goes to the job's output file.
Permissions
- Every delegate runs in
auto, as every session does (docs/permissions.md). delegate_spawn,delegate_forkanddelegate_messagedeclareexecutesandalways_reviewed(docs/tools.md, "What a tool declares"), so they are always judged by the parent's reviewer: no fast path, session grant or standing allow skips them. The parent's reviewer judges what the parent's model tells a delegate against the parent's own person's messages, because the delegate's reviewer reads that prompt and those messages as the human's.- A Fiber delegate has its own reviewer. An escalation from it is a block, as for any unattended run, and the delegate carries on. No model answers a delegate's approval, its parent's included, and nothing relays it to a person.
- Another harness runs in its own auto mode and is judged by its own rules ("Harness extensions"). A harness and model are offered as a delegate only when their auto mode is declared to work.
Limits
- Depth is capped at 2: the root session is depth 0, its delegates depth 1,
theirs depth 2. At depth 2, the delegate tools stay declared and fail with
depth_exceeded. - A session runs at most 10 delegates at once. The eleventh start fails with a message saying so; nothing is queued.
- Both limits are local. A delegate is told its depth when it starts, and each session counts only its own delegates, so no state is shared across the tree. The worst case for one root is 10 + 100 = 110 delegates.
Lifetime
- A delegate survives cancellation of its parent's turn, as every job does.
A delegate never waits on a person: an escalation is a block and an
ask_userquestion ends its turn ("Results"). - A Fiber delegate exits as soon as its run finishes: its final answer is
written and its own jobs are done. It does not wait for
session.idle_exit_ms(docs/invocation.md, "Lifecycle"). - A delegate that finishes its task with jobs of its own still running follows
the rule for a session about to end (
docs/tools.md): it is woken once, then waited for. - Stopping a delegate (
jobs stop,job_stop) stops its own jobs and delegates as its shutdown does (docs/invocation.md, "Shutdown"), so a stop reaches every descendant. Its keeper waits for it to exit, up to the shutdown bound, before sending SIGKILL. - Every delegate is a child process of its parent session's keeper
(
docs/tools.md, "The keeper"). A Fiber delegate runs the internal session command (ADR 0009). Its parent is an ordinary client over its socket and drives it only through the driver commands and events, so no delegate has a path a supervisor lacks. - A Fiber delegate's stdin is a lifeline. The keeper holds it open and never
writes to it. End of file on it means the keeper is gone, however it died,
and the delegate shuts down within the bound (
docs/invocation.md, "Shutdown"). A dropped socket connection is only a client leaving: the parent reconnects and the delegate carries on. - After
fiber_exited, the runner starts no further watch. - A Fiber delegate starts its own MCP servers and process extensions, as
every session does (
docs/mcp.md, "Where servers run"). It never raises a repository's offer: code its repository declares loads only if a person already approved that content, and is otherwise skipped, or fails the delegate when markedrequired(docs/extensions.md, "Code a repository ships"). - How a stopped Fiber delegate is ended is the stop rule above.
- If a parent's process dies without a shutdown, each Fiber delegate carries
on and finishes its task, as it would with its parent connected. When it
exits, the parent's keeper writes its
job_completedin the parent's log. A delegate still running when the keeper's 2 hours pass is stopped as a shutdown stops it (docs/tools.md, "The keeper"). A delegate on another harness carries on the same way, and the keeper records its end by the rule indocs/tools.md, "The keeper". - A resumed parent connects to each delegate still running, as after a
dropped connection. For each delegate that ended while it was gone, it
writes the
delegate_finishedfrom the delegate's own log when it delivers the result, and it reads each delegate's log for theusage_recordedlines it is missing. - Before marking a delegate job orphaned, the resumed parent reads its
session log. When the log's latest run holds
fiber_exited, the parent settles the job from it: its exit code, its outcome, its final message and, for an isolated delegate, its worktree, as a live finish would. Only a delegate whose log's latest run has nofiber_exitedis marked orphaned. Shell jobs are unchanged. - A crash of any kind in a delegate, in Rust or in Lua's C code, ends that
delegate
failedand nothing else.
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.
isolation: worktreemakes a new branch from the HEAD of the delegate'sworkspace, in a worktree under~/.fiber/projects/<key>/worktrees/<id>. Fiber runs thegitprogram; no git library is linked in.- At the end of a run, a worktree with nothing uncommitted and no commits beyond
its base is removed. Otherwise it is kept. Uncommitted follows git: files the
repository ignores, such as build output, are not changes. Fiber never removes a kept
worktree on its own;
fiber sessions pruneremoves one that holds nothing to lose, or any with--force(docs/invocation.md, "Deleting and pruning"). delegate_finishedreports the path, the branch and whether it is dirty. On a settled finish thedirtyread is taken at settle time, which is later than the live path's: it may describe a worktree that has since changed or been removed.- A resume goes back into the kept worktree, or gets a fresh one from the
current HEAD if it was removed. It reads the delegate's worktree record and
run boundary from the delegate's project, including when
workspaceselected a different repository from the parent's. A removed worktree starts from its recorded repository, then is recreated at the same path and branch beforefiber_started. The resumed session removes a clean recreated worktree and keeps a dirty one; the parent reports its state without removing it again. - If neither the workspace nor its recorded repository is available, resume
fails before launch with
io_failed, naming the missing workspace. Without a recorded worktree, a missing workspace fails the same way. An unreadable worktree record or run boundary fails closed withtool_error. A message to a live delegate steers it without checking workspace or repository existence. worktreeoutside a git repository fails withinvalid_arguments.- Each Fiber delegate inherits the parent's effective sandbox settings at launch. Fresh spawns, forks and resumes take a new snapshot, including settings changed during the session. Delegate tool calls stay reviewed ("Permissions").
- A confined delegate can commit and create local branches in its worktree.
Git grants cover its git directory and the shared
objects/,refs/andlogs/subdirectories, even outside the delegate workspace. All ofrefs/is writable so a mistaken branch move is recoverable from the reflog. These grants give no socket access for pushes;git pushstays reviewed (docs/permissions.md, "The destructive-command guard"). - On Linux, delegates use the same project baseline as the parent's
worktrees. Fiber records and restores shared config and hooks, worktree
.gitpointers, git directorycommondirfiles and workspace-local.fiber/, reporting changes after each call. The supervisor restores outside confinement; restoration is not a write grant. On macOS, the policy denies writes to those paths while granting the same Git data (docs/sandbox.md, "Protected paths").
Forks
-
delegate_forkstarts a Fiber delegate whose history is its parent's conversation up to the fork, then its own events. -
It is recorded as a pointer:
forked_from { session_id, seq }on the delegate'ssession_started. The fork's history is the parent's log folded to thatseq. Nothing is copied: the parent's log is append-only, so the shared part is never written again. This is copy-on-write where the write never happens, as with a git branch or a ZFS clone. -
A session some fork points at cannot be deleted on its own. Deleting it is refused, as
zfs destroyrefuses a snapshot with clones, unless the person passes--cascade, which deletes its forks too (docs/invocation.md, "Deleting and pruning"). -
A fork exists to share its parent's prompt cache. Its first request must match the parent's byte for byte up to the new content, so:
- It takes no model or thinking level. It runs on the parent's model and thinking level, and every request setting that changes the prefix.
- It sends the parent's latest preamble before its point, as logged in
preamble_built, so its tool set, system prompt and request settings match (docs/prompt-cache.md, "The preamble"). - Its identity and task go in its first user message as the
fork_tasktext, naming the parent session and the depth, never the system prompt. - The
seqis the position just before the assistant message that calleddelegate_fork, so no tool call is left without a result. - Every provider's cache key is the root session's id, shared by the whole
lineage (
docs/prompt-cache.md, "Cache markers and keys"). - A call whose ancestry reaches a command root is refused: the point walk
stops at a root call with
ran_by.command_id, and the call fails withinvalid_arguments.
-
With
isolation: worktree, the fork records its own worktree onsession_started, separately from the worktree in its inherited history. It shares both worktree locks for its life. Its parent releases the new worktree's transfer share only after the durablesession_startedacknowledges adoption; failed startup retains that share through child exit. -
When the fork's workspace differs from its parent's, its first user message includes this paragraph before the unattended instruction and task:
Your workspace is {workspace}, a worktree of {parent_workspace}. Paths above under {parent_workspace} are at the same place under yours; work only in yours.
Equal workspaces add no paragraph. The inherited prefix stays byte-identical.
session_startcontext and other first-turn items keep their normal place between that prefix and the fork's first user message. -
Other harnesses have no fork: a Fiber conversation cannot be handed to them.
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:
- the flags that run the harness in its own auto mode
- whether it takes messages while running
- whether SIGTERM stops it cleanly, so it gets the shutdown wait
(
docs/invocation.md, "Shutdown")
As data, for each model:
- its price per token, where the harness reports no cost of its own
- whether the harness's
automode works on it, declared only after a probe
As Lua, none of which runs on a model request:
command(spec)returns the program, arguments and environment for a start or a resume.speccarries the prompt, the model reference, the workspace, and the harness session id.line(text)is called with each line the harness prints, and returns what that line carries, if anything: the final answer, usage, quota, or a failure.models()returns the harness's model references. It is cached and refreshed as a provider's model discovery is (docs/model-routing.md, "Model discovery").quota(), optional, returns quota in the provider shape (docs/model-routing.md, "Quota").
How Fiber runs it
- Configuration. The harness loads the person's configuration for it.
commandpasses only what drives the program: print mode, the JSON output stream, the session id, the model and its effort flag, the auto-mode flags, resume, and where the harness takes one per run,fiber mcp serve("Delegates on another harness"). - Session id. Fiber fixes the harness's session id before the program
starts, so a delegate stopped before its first line can still be resumed.
It is the delegate's
session_idondelegate_started. - Worktree.
isolation: worktreeis always Fiber's own worktree ("Worktrees"), and the harness runs with it as its working directory. A harness's own worktree option is never used. - Output. Every line goes to the job's output file. Fiber hands each line
to
lineand keeps the last final answer, usage and failure it returns. The run ends when the program exits. - Messages while running. A harness that takes them gets each
delegate_messageas a line on its input. Fiber closes its input after the final answer, so the program exits. For any other harness the message waits and is delivered as a resume ("Talking to a delegate"). - Usage. The parent writes one
usage_recordedper run, from the usagelinereturned. Its cost is the harness's own where it reports one, or computed from the declared prices. It carriessubscriptionwhen the harness ran on a subscription login, and the parent's budget then skips it (docs/loop.md, "Spending budget"). - Quota.
quota()runs whendelegate_modelsneeds it, as a provider's does (docs/tools.md, "Provider quota"). Quota thatlinereturns from a running delegate replaces the stored value, with no fetch. - Program missing. A harness whose program is not installed lists no
models in
delegate_models.
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"):
- The parent binds its socket. It binds
~/.fiber/run/<session_id>when each of the delegate's runs starts and unlinks it when the run ends. It removes a stale socket first, as a lock holder does (docs/state.md, "What each part holds").session_listlists the delegate like any other. The socket accepts onlymessage(docs/invocation.md). After the parent is sentclose, it is rejectedclosing. - A message in is delivered as
delegate_messagedelivers one. A harness that takes messages while running gets it as a line on its input. For any other harness it waits and is delivered as a resume ("Talking to a delegate"). The parent frames it with the sender's id and name. - The delegate sends through
fiber mcp serve. It is a stdio MCP server offeringsession_listandsession_message, which work as the built-in tools do, with the delegate's id as the sender. The server lists no tools unless its environment names a Fiber delegate, so it is inert anywhere else. - The harness judges the send. Calling
session_messageis a tool call inside the harness, judged in the harness's own mode, as its other calls are ("Permissions"). Fiber's reviewer andbefore_messagedo not reach inside another harness. The target session applies both on its side. - How each harness loads the server is in its table below.
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:
- A message from another Claude Code session, sent with
SendMessageto a session started withcrossSessionInboundaccept, joined the running turn. Its frame is one JSON line withmsgV,msg_id,typeuser,message,priorityandfrom. - The same frame from a process that was not Claude Code was not delivered,
with no token, with the
CLAUDE_CODE_MESSAGING_TOKENvalue as a first line, or with it as JSON. How the socket authenticates a sender is undocumented. - An MCP server declaring
claude/channelpushednotifications/claude/channelduring a running tool call, under both--channelsand--dangerously-load-development-channels. The model never saw it.
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.
| What | How |
|---|---|
| Start | claude -p --output-format stream-json --verbose --input-format stream-json --session-id <uuid> --model <model> --effort <effort> --permission-mode auto |
| Resume | the same, with --resume <session-id> in place of --session-id |
| Auto mode | --permission-mode auto, declared per model |
| Messages while running | yes, 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, cost | the result line: result, usage and total_cost_usd |
| Subscription | the system init line's apiKeySource: none is the subscription login, and total_cost_usd is then an API-price estimate |
| Quota | rate_limit_event lines while running, and quota() from /api/oauth/usage with Claude Code's own stored login |
| SIGTERM | stops cleanly, so it gets the shutdown wait |
Probed on Claude Code 2.1.284:
- With no isolation flags, a delegate loaded the person's hooks, plugins, MCP servers, user instructions, output style and auto-memory. That is what the person configured, so it stays.
- With no
--permission-mode, a Sonnet delegate ran in the person's configuredauto. A Haiku delegate reporteddefault, which is whyautois declared per model. - A message sent while a Bash call was running joined the same turn, and
the run ended with one
result. set_permission_modeswitched a running session toplan, confirmed by astatusline.--bareand a cleanCLAUDE_CONFIG_DIRboth fail with "Not logged in", because neither reads the subscription login.- On 2.1.285 with a Max login, the
initline hadapiKeySourcenoneand theresultline still hadtotal_cost_usd, 0.0228 for one Haiku reply. The value with an API key was not probed.
cursor-agent
Not built yet: see #546.
| What | How |
|---|---|
| Start | cursor-agent -p --output-format stream-json --trust --approve-mcps --model '<model>[effort=<effort>]' --auto-review |
| Resume | the same, with --resume <chat-id> |
| Session id | cursor-agent create-chat before the first run |
| Auto mode | --auto-review |
| Messages while running | none: delivered as a resume |
| Session messages out | an 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, usage | the result line: result and usage, which has tokens and no cost |
| Cost | computed from the declared prices |
| SIGTERM | not probed, so it gets SIGKILL at 800 ms like any command |
Probed on cursor-agent 2026.09.26:
--trustand--approve-mcpsanswer prompts that would otherwise stop a run with nobody to answer them.- It loads the person's skills, including
~/.claude/skills, their plugins' MCP servers and their user rules. Itsinitline names none of them. - It has no channel for approvals. With no mode flag it follows the person's
approvalMode.
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.