@zenera/cli 1.1.24 → 1.1.26

package/templates/editor/.github/skills/zen-topology/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: zen-topology
+description: 'Use when designing, reviewing or auditing how a Zenera project divides work between agents - whether to hand off, fork one branch to delegate, fan out several branches, or keep the work in one conversation; which fork `context` to pick; what each choice costs in tokens, prompt cache and elapsed time; and how to read a recorded run for topology mistakes (missed fan-out, a forked sequence, an early or looping hand-off, a delegation that cost more than it saved). Load before adding or changing `handoffs:` or `fork:` in agents.yaml, before writing a prompt line that says when to delegate, and before grading Delegation or Forking in a run audit.'
+---
+
+# Agent topology
+
+Work moves between agents in exactly two ways, and both are tools the model
+calls: a **hand-off** (`transfer_to_<name>`) gives the conversation away, a
+**fork** (`fork`) sends work out and gets answers back. Everything else is one
+agent working in its own conversation. Both are opt-in per agent in
+`agents.yaml` - `handoffs:` and `fork:`, described key by key in §8.
+
+Whether a second agent should exist at all is copilot-instructions §6.1 - this
+skill starts once it does. The rules an agent reads at run time about forking
+are zen's own `agents/fork-instructions.md`; this skill is for whoever designs
+the project or judges a run against it, and never repeats that file's prose.
+
+## 1. The four shapes
+
+| Shape          | Control                      | The other side sees                      | Comes back                    | Use it when                                                                 |
+| -------------- | ---------------------------- | ---------------------------------------- | ----------------------------- | --------------------------------------------------------------------------- |
+| Keep it here   | stays                        | -                                        | -                             | steps depend on each other, one call does it, or you want to steer the work |
+| Hand-off       | moves, and **stays moved**   | the whole transcript                     | nothing, unless it hands back | another agent should own the conversation from now on                       |
+| Fork, 1 branch | returns to the forking agent | what `context` gives it + its assignment | that branch's answer only     | you want an answer from someone better suited, or to keep noise out         |
+| Fork, N        | returns to the forking agent | the same, per branch                     | N answers in one tool result  | N independent parts of one task, done at the same time                      |
+
+## 2. What a hand-off carries
+
+When the model calls `transfer_to_<name>`, the kernel records a `handoff` node
+(`from`, `to`, the optional `reason` argument), switches the current agent,
+appends a fresh `system_prompt` for the target, and rebuilds the tool list for
+it - its own tools, its hand-offs, its memory and skill tools, its `fork`.
+
+- **The target sees the entire transcript**, every tool call and result the
+  previous agent made included. The runtime can collapse the outgoing agent's
+  turns with a hand-off policy, but `zen` sets none, so nothing is summarised.
+  Do not write a prompt that assumes the target starts clean.
+- Only the newest system prompt is sent. The previous agent's role and house
+  rules are gone from the request; its words are not.
+- The target's `description:` is the whole of what the caller reads when
+  deciding, so it is a routing condition, not a title.
+- **Auto-recall fires again** for the target, with its own memory mask, against
+  the last user input - not against the `reason`.
+- Preloaded skills are applied for the target; the outgoing agent's skill tools
+  are not the target's.
+- **Nothing hands control back.** The target answers every later turn until it
+  hands off itself, which is why `zen check` warns `handoff.one-way` on any edge
+  with no path home.
+- A memory commit is due from the agent that did the work, **before** its
+  hand-off. The target holds only the transcript of it - see **zen-memory**.
+
+## 3. What a fork carries
+
+The model calls `fork` with `branches: [{name, instructions, agent?}]` and one
+`context` for the whole call. The agent must declare `fork:`; `fork.agents`
+reaches the model as an `enum`, and `fork.maxBranches` caps the array.
+
+**What a branch starts from:**
+
+| `context`           | The branch begins with                                                      |
+| ------------------- | --------------------------------------------------------------------------- |
+| `inherit` (default) | the parent's visible history up to the fork call, then its assignment       |
+| `compact`           | the same minus every `tool_call`, `tool_result` and `memory_recall`         |
+| `none`              | nothing: its agent's system prompt, then its instructions as a user message |
+
+Under `inherit` and `compact` the assignment arrives as the result of the
+inherited `fork` call, opening `You are branch "<name>" of the fork above`,
+naming its siblings. Skills another agent loaded are dropped from an inherited
+prefix, so a branch never reads instructions for tools it does not hold.
+
+**What comes back:** one tool result, holding each branch's final answer and
+status in declared order, never completion order. The branch's own steps are
+kept inside the `join` node for audit and are never shown to the parent. A
+failed branch is a row with `status: error`, not a failed run.
+
+**What outlives the branch:** files it wrote (branches share the workspace with
+the parent and each other) and anything it committed to memory. Nothing else.
+
+**Depth:** a branch may fork again while under the run's `maxForkDepth` (2 by
+default). At the cap the `fork` tool is withdrawn and so is
+`agents/fork-instructions.md`.
+
+## 4. What it costs - tokens, cache, time
+
+A provider caches the longest **repeated prefix** of a request - tool schemas,
+system prompt, then messages - and bills a cached token below an uncached one.
+The runtime keeps that prefix still: house rules first, the role file second,
+the tool array fixed for the agent's life, preloads at the head, auto-recall
+only at the start of a turn. So the question for every shape is: **are the
+first bytes the same as a request the provider has already seen?**
+
+| Shape                        | Tokens sent                                             | Prompt cache                                                                                       | Elapsed              |
+| ---------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------- |
+| Keep it here                 | the transcript, growing every call                      | hits on all of it but the newest tail                                                              | the sum of the steps |
+| Hand-off                     | the whole transcript, on every call the target makes    | **misses on the target's first call** - new system prompt and tools, so nothing after them matches | serial               |
+| Hand-off back                | the same                                                | the original agent's prefix up to its hand-off may still hit, within the provider's cache lifetime | serial               |
+| Fork, `inherit`, same agent  | per branch: the parent's history + brief + its own work | the inherited prefix is byte-identical up to the fork call, so it can hit                          | the slowest branch   |
+| Fork, `inherit`, other agent | the same                                                | misses: a different system prompt, so the whole history is paid uncached, once per branch          | the slowest branch   |
+| Fork, `compact`              | less history: decisions without tool traffic            | same agent: hits only up to the first dropped tool call; other agent: misses                       | the slowest branch   |
+| Fork, `none`                 | its agent's prompt + instructions + its own work        | nothing to share with the parent; same-agent branches share the system prompt with each other      | the slowest branch   |
+| The parent after a join      | two messages more: the call and one result              | unchanged - declared order makes the join deterministic                                            | -                    |
+
+What follows from the table:
+
+- **A fan-out buys time, not tokens.** N branches together usually send more
+  than doing the N parts in series, because every branch pays its own start.
+  The saving is the elapsed time of all but the slowest branch, and the
+  parent's context staying N answers long instead of N transcripts.
+- **A one-branch fork costs a whole conversation's start** to save the caller
+  some context. Worth it for a long, noisy job with a short verdict; a loss for
+  one read, one search or one command.
+- **Agents passing the conversation back and forth pay a cache miss on every
+  switch**, plus a recall each time, on a transcript that only grows.
+- **`inherit` versus `compact` is a trade, not a rule.** `compact` sends less;
+  `inherit` on the same agent can be served from cache. When most of the
+  history is tool traffic, `compact` wins; when it is mostly decided
+  conversation, `inherit` on the same agent can be cheaper. On a different
+  agent there is no cache to win, so the smaller prefix wins.
+- **Cached tokens are not shown in the run graph.** `zen inspect`'s `tokens`
+  row and each `llm` node's `in` count cached tokens as input. Reason about the
+  cache from the structure above; never report a hit or a miss as measured.
+
+## 5. Choosing - in this order
+
+Ask each question of the piece of work in front of you and stop at the first
+yes.
+
+1. **Does any part need another part's result?** Keep that sequence here. A
+   branch cannot see its siblings, cannot ask, and cannot be steered.
+2. **Is it one call, or one call that takes a list?** Keep it here. Pass the
+   list.
+3. **Should another agent answer the user from now on** - over several turns,
+   on its own model or tools? Hand off, and make sure a path leads back.
+4. **Do you want an answer and then carry on?** Fork one branch on the agent
+   that suits the job. Never a hand-off: that spends the conversation to get
+   the answer.
+5. **Are there N independent parts?** Fork N branches - one per item, or one
+   per trade, each on the agent that fits.
+
+Then pick `context`, cheapest first:
+
+1. `none`, when everything the branch needs can be written into its
+   instructions - paths included. Write it in and take `none`.
+2. `compact`, when it needs the plan and the decisions but not how they were
+   found, or when the branch runs a **different** agent.
+3. `inherit`, when it must see the work as it stands - reviewing what was just
+   written, continuing an investigation - and preferably on the **same** agent.
+
+## 6. Where each rule goes
+
+| Rule                                                              | Goes in                                                           |
+| ----------------------------------------------------------------- | ----------------------------------------------------------------- |
+| who may hand off to whom; who may fork, to which agents, how wide | `agents.yaml` - `handoffs:`, `fork: { agents, maxBranches }` (§8) |
+| what a hand-off target is for                                     | `agents.yaml` - the target's `description:`, as a condition       |
+| **when** to fork or hand off, in this domain's terms              | the deciding agent's prompt                                       |
+| which `context` this work wants                                   | the deciding agent's prompt                                       |
+| what a branch must return, and in which file                      | the forking agent's prompt, so it writes it into `instructions`   |
+| which hand-off ends a specialist's turn                           | the specialist's prompt                                           |
+| a forking policy for the whole project                            | `agents/fork-<topic>-instructions.md` - load **zen-instructions** |
+
+The domain-terms line is the one most often missing, and without it a weaker
+model works through a list serially and never calls `fork`: _"When the request
+covers more than one region, fork one branch per region with `context: none`,
+and tell each branch to return the region, the total and the top three
+findings."_
+
+Never edit `agents/fork-instructions.md` - it is zen's copy, `zen check --fix`
+replaces it, and an edit there is reported as `rules.stale`.
+
+## 7. Reading a run for topology
+
+Where the topology shows in `zen inspect graph` (load **zen-inspect** for the
+format):
+
+- `%% agent <last> · started as <first>` - a hand-off happened.
+- `@<agent>` on a node - the first node that agent owns.
+- `handoff <from> to <to>` - open it for `reason`.
+- `fork (<context> context) <branch>, <branch>` - the mode it chose.
+- the branch subgraphs, one marked `slowest`, and `join <branch>=ok, ...`.
+- `%% branches` - which join waited for which branches, with status.
+- `%% tools` - `fork xN` and how many research calls ran around it.
+
+| The graph shows                                                                     | Finding                                           | Fix goes in                                               | Next run should show                         |
+| ----------------------------------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------- |
+| research calls in series, none using an earlier result, `fork` in the agent's tools | missed fan-out                                    | the agent's prompt: the domain trigger of §6              | one `fork` with a branch per item            |
+| the same, `fork` not in the agent's tools                                           | missed fan-out                                    | `agents.yaml`: `fork:` on that agent                      | the same                                     |
+| a branch's instructions name a sibling's result, or read a file a sibling writes    | a sequence was forked                             | the forking agent's prompt                                | those steps in the trunk                     |
+| a one-branch fork whose branch made one or two calls                                | delegation that cost more than it saved           | the forking agent's prompt                                | the call made in the trunk                   |
+| after the join, the parent repeats calls a branch already made                      | the branch was not told what to return            | the forking agent's prompt: what each branch must return  | no repeat after the join                     |
+| a branch not `ok`                                                                   | an assignment missing a fact it could not ask for | the forking agent's prompt                                | that branch `ok`                             |
+| `slowest` far behind its siblings                                                   | an uneven division                                | the forking agent's prompt: split that part               | branch durations close together              |
+| two branches with the same calls on the same subjects                               | overlap, paid for twice                           | the forking agent's prompt: divide by subject             | disjoint subjects                            |
+| a wide fan-out to **another** agent with `inherit` and a long history               | the history paid uncached, once per branch        | the forking agent's prompt: `compact` or `none`           | `fork (compact context)` or `(none context)` |
+| a `handoff` before the agent's own part was done                                    | an early hand-off                                 | the outgoing agent's prompt                               | its own calls, then the hand-off             |
+| `handoff` A to B, then B to A, then A to B                                          | a loop - two prompts claim the same job           | both prompts, so one owns it                              | one hand-off, or none                        |
+| a hand-off for one question, then the target writes the final answer                | wanted an answer, spent the conversation          | the outgoing agent's prompt, and `fork:` in `agents.yaml` | a one-branch `fork` to that agent            |
+| a specialist exists in `agents.yaml`, and the agent did that job inline             | the prompt never said when to delegate            | the deciding agent's prompt                               | a `fork` or `handoff` to the specialist      |
+
+Price each finding honestly. A missed fan-out costs the elapsed time of every
+branch but the slowest - not tokens, which a fork usually raises. A forked
+sequence or an overlap costs the duplicated calls and their tokens. A
+needless hand-off or one-branch fork costs one conversation's start, uncached.
+
+To learn **why** the model chose the shape, ask the `llm` node that carries
+`calls transfer_to_<name>` or `calls fork`, or the first call of a serial run -
+load **zen-inspect-ask** for how to word it. First rule out the cheap causes:
+`fork` not in that call's tools (depth cap, or no `fork:`),
+`fork-instructions.md` not in its `system_prompt`, a specialist not in its
+`enum`.
+
+## 8. The keys in `agents.yaml`
+
+Both keys are per agent, and both only make a tool available. When the model
+uses it is the prompt's business (§6).
+
+### `handoffs:`
+
+```yaml
+agents:
+    - name: intake
+      description: Takes the first message and routes the case to the right desk.
+      handoffs: [billing, technical]
+    - name: billing
+      description: Answers invoice and refund questions from the written policy.
+      handoffs: [intake] # the way home
+    - name: technical
+      description: Diagnoses faults from the logs and says what to do next.
+      handoffs: [intake]
+```
+
+- A list of bare agent names. There is no object form and no per-edge
+  configuration.
+- Each name becomes one tool on this agent, `transfer_to_<name>`, described by
+  the **target's** `description:`. With none, the model gets a generic sentence
+  and `zen check` warns `agent.no-description`. Write it as a routing
+  condition, not a title: _"Applies the written peril policies to a claim and
+  explains the outcome"_, never _"The adjuster agent"_.
+- `handoff.unknown` (an agent not declared) and `handoff.self` are load errors.
+- `handoff.one-way` is a warning: an edge `A → B` with no path from B back to
+  A. Indirect counts - `B → C → A` is a way home - so every edge must lie on a
+  cycle. Without one, the first routed question is the last one routed.
+
+### `fork:`
+
+```yaml
+agents:
+    - name: trunk
+      fork: true # any declared agent, any number of branches
+
+    - name: sweep
+      fork:
+          agents: [sweep, prober] # who a branch may run - itself included
+          maxBranches: 6
+
+    - name: asker
+      fork: { agents: [prober], maxBranches: 1 } # delegation, never a fan-out
+```
+
+| Written            | Means                                                                                                                |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| absent, or `false` | no `fork` tool, and `agents/fork-instructions.md` never reaches this agent                                           |
+| `true`, or `{}`    | the tool, any declared agent, no cap                                                                                 |
+| `agents: [a, b]`   | a branch may run only these. The list is an `enum` on each branch's `agent` field, so another name cannot be decoded |
+| `maxBranches: n`   | at most `n` branches per call. `1` allows delegation and refuses fan-out                                             |
+
+- `agents` **may name the forking agent itself** - one role fanned out over
+  many items is the common shape, and unlike `handoffs:` it is not an error.
+- A branch that leaves `agent` out runs the forking agent - but only when the
+  forking agent is in `agents`. When it is not, the model must name one.
+- **A branch runs as its agent**: that agent's prompt, tools, memory binding,
+  skills, hand-offs and its own `fork:`. A hand-off inside a branch moves the
+  branch's conversation, never the parent's.
+- Depth is not a key here. `maxForkDepth` (2 by default) is a run option; at
+  the cap the `fork` tool is withdrawn, and `agents/fork-instructions.md` with
+  it.
+- Refused at load: `agents: []`, `maxBranches: 0`, and an `agents` entry not
+  declared (`fork.unknown`).
+- `fork.uninstructed` is an error: an agent can fork and
+  `agents/fork-instructions.md` is missing or empty. `zen check --fix` writes it
+  back. That file is zen's - an edit in it is reported as `rules.stale` and lost
+  at the next `--fix`; project policy on forking goes in
+  `agents/fork-<topic>-instructions.md` (load **zen-instructions**).

package/templates/editor/.vscode/settings.json

@@ -1,5 +1,6 @@
 {
     "chat.useNestedAgentsMdFiles": false,
+    "chat.agent.maxRequests": 250,
     "terminal.integrated.tabs.description": "Agent",
     "yaml.schemas": {
         "./.vscode/agents.schema.json": [

package/templates/project/agents/files-instructions.md

@@ -16,23 +16,35 @@ Check which tools you actually have:
 - If `write_file` and `apply_patch` are available, you may create and edit files
   under `/workspace`.
 
-## Discovery before assumption
+## Finding files
 
-Never guess a file's name, location, or contents.
+Never guess a file's name, location, or contents. Pick the tool by what you know:
 
-- Use `list_dir` to see directory contents and formats before opening files.
-- Use `find_files` to locate files by substring when the layout is unfamiliar.
-- Check whether a target file already exists before writing to it.
+- **The directory** → `list_dir { path }`. One level, not recursive. Each file shows
+  `format`, `bytes` and, for text, `lines`, so you can decide what to read and how much
+  without opening it. Omit `path` (or give `/`) to list the mounted trees.
+- **Part of the path** → `find_files { pattern, path? }`. `pattern` is **required**: a
+  plain, case-insensitive substring, never a glob or regex (`*.ts` matches nothing; write
+  `.ts`). It is matched against the path with its mount name (`/workspace`, `/assets`, …)
+  removed: `/workspace/src/a.ts` is matched as `src/a.ts`, so `src/` matches and
+  `/workspace/src` does not. To limit the search to one tree, pass it as `path`. Matches
+  come back as absolute paths.
+- **Neither** → `list_dir` the root, then descend.
+
+`find_files` matches paths, not contents. Both tools stop at 500 results and set
+`truncated`: narrow the `pattern` or `path` rather than repeating the call.
 
 ## Reading files
 
-- Use `read_file` to read text files.
-- For files longer than a few dozen lines, pass `start_line` and `end_line` (1-based, inclusive)
-  to read only the relevant section.
-- When `read_file` returns `truncated: true`, the read hit the size limit or range boundary.
-  Resume reading from `end_line + 1` if you need the remainder.
-- Non-text files (images, binaries, archives) cannot be read as text; `list_dir` reports
-  their format.
+- `read_file { path, start_line?, end_line? }`; lines are 1-based and inclusive. Read a
+  short file whole; for a long one (see `lines` from `list_dir`), read the range you need.
+- The result gives the file's total `lines` and the `start_line`/`end_line` returned.
+  `truncated: true` means more follows `end_line` (your range or the 256 KB cap); continue
+  from `end_line + 1` only if you need it.
+- A non-text file fails with its `format`. Do not retry; `copy_file` can still copy it.
+- Check whether a target exists before writing to it.
+
+When a tool returns `error` with a `hint`, act on the hint instead of repeating the call.
 
 ## Modifying files
 
@@ -71,14 +83,11 @@ Never use `write_file` to update an existing file when only a few lines need to
 
 ### Copying: `copy_file`
 
-Use `copy_file` to duplicate a file rather than reading it and writing it back out.
-The bytes go straight from one path to the other without passing through the
-conversation, so the size cap on `read_file` does not apply and a binary arrives
-intact.
+Use `copy_file` to duplicate a file, never `read_file` + `write_file`. The bytes skip the
+conversation, so there is no size cap and binaries arrive intact.
 
-- The source may be in a read-only mount; only the destination has to be writable.
-  This is how something under `/assets`, `/skills` or `/memory` is brought into
-  `/workspace`.
+- The source may be in a read-only mount; only the destination must be writable.
+  This is how something under `/assets`, `/skills` or `/memory` reaches `/workspace`.
 - Set `overwrite: true` only when intentionally replacing an existing destination.
 - Copying a directory and its contents requires `recursive: true`.
 
@@ -96,4 +105,4 @@ All file operations are confined to mounted trees:
   (such as `/workspace/src/main.ts`) are where project files reside.
 - `/assets`, `/skills`, `/memory`: Read-only mounts. You may read, list, and search them,
   but you cannot write, move, or delete files inside them.
-- Any attempt to reach outside these mounts fails with an containment error.
+- Any attempt to reach outside these mounts fails with a containment error.

package/templates/project/agents/fork-instructions.md

@@ -45,34 +45,31 @@ Every `fork` call takes an array under `branches`, even for a single branch:
 Never pass branch fields (`name`, `instructions`, `agent`) at the top level of
 the tool call.
 
-Do not fork a sequence. Branches run at once and can exchange nothing, so a step
-that needs the step before it has to stay in this conversation.
-
 ## When the assignment is yours
 
 These rules reach a branch as well as the agent that forked it, and a branch
-arrives in the middle of someone else's sentence. Your assignment comes to you
-as the result of a `fork` call, because that is how the runtime delivers it —
-and that is indistinguishable, in a transcript, from a fork you made yourself
-coming back with an answer.
+arrives in the middle of someone else's sentence. Under `inherit` or `compact`
+your assignment comes to you as the result of a `fork` call, because that is how
+the runtime delivers it — and that is indistinguishable, in a transcript, from a
+fork you made yourself coming back with an answer.
 
 It is not one. When a message begins "You are branch ... of the fork above", you
-are that branch and that text is your assignment:
+are that branch and that text is your assignment. Under `none` there is no such
+message, only the instructions as the first message of the conversation; when
+they say you are a branch, the same holds:
 
 - **Nothing has run yet.** There is no result in it and nothing to verify. The
   fork it names is above in the conversation you were forked out of, which is
   not the one you are in — yours begins with that message.
-- **Do the work yourself.** Never fork a branch to carry out the assignment you
-  were handed: that branch is you one level down holding the same instructions,
+- **Do the work yourself.** Never fork one branch holding your whole
+  assignment: that branch is you one level down holding the same instructions,
   it will read them the same way, and each level spends a whole system prompt to
   arrive back where it started. At the depth cap the tool is withdrawn and the
-  work comes back undone.
+  work comes back undone. If the assignment names two or more independent
+  deliverables, fork one branch for each, or do them all yourself.
 - **Do not go looking for proof it was already done.** An empty workspace is
   what an unstarted job looks like, not a sign that something failed upstream.
 
-Fork from inside a branch only for work that is genuinely divisible further and
-that you were not handed already divided.
-
 ## When it is worth it
 
 One question decides it: **could this be finished by someone who cannot ask you
@@ -82,7 +79,7 @@ no, the work stays here.
 | The work in front of you                                                                     | What it is                                               |
 | -------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
 | The same question asked of twenty things — files, endpoints, regions, candidate fixes        | A fan-out: one branch each, merged by you                |
-| One task whose parts need different skills and none of them the others                       | A fan-out too: each branch on the agent that fits        |
+| One task whose parts need different skills and no part needs another's result to start       | A fan-out too: each branch on the agent that fits        |
 | A job another agent is plainly better at                                                     | Delegation: one branch, on that agent                    |
 | Long and noisy with a short verdict — a build loop, a bisect, a survey that may find nothing | Delegation: you get the verdict, not the noise           |
 | Find the config, then change it, then test it                                                | Not a fork. Each step needs the one before it            |
@@ -92,6 +89,36 @@ no, the work stays here.
 | The assignment you were handed, whole                                                        | Not a fork. It is yours — see above                      |
 | Two jobs that would write the same file                                                      | Not a fork until they write different files — see below  |
 
+Do not fork a sequence. Branches run at once and can exchange nothing, so a step
+that needs the step before it has to stay in this conversation. A step depends
+on another only when it cannot be _written_ without that result. When that
+result can only be one of a few values known in advance, it is not a
+dependency: fork the step now for all of them, have it return its result keyed
+by value, and keep the one that applies after the join.
+
+Before a one-branch `fork`, list what the request asks you to hand back. If two
+or more of those items are independent — none needs another's result, and each
+takes more than one call — give each its own branch in the same call.
+
+## Hand-off or fork
+
+Both reach another agent; they differ in who holds the conversation afterwards.
+
+|                   | `transfer_to_<agent>`                                                 | `fork`                                             |
+| ----------------- | --------------------------------------------------------------------- | -------------------------------------------------- |
+| Control           | moves to the other agent and stays there; it answers every later turn | comes back to you at the join                      |
+| What it sees      | this whole conversation, every tool result included                   | what `context` gives it, plus your instructions    |
+| What you get back | nothing; you are done                                                 | its final message                                  |
+| Parallel          | no, one agent at a time                                               | yes, one branch per part                           |
+| Cost              | the whole transcript on every call it makes from now on; no merge     | each branch's own context, plus your turn to merge |
+
+Hand off when the rest of the conversation belongs to the other agent: the
+user's next question will be in its domain too, and you have nothing to add to
+its answer. Fork when you need the result back — to combine it with other parts,
+check it, or keep the conversation yourself. A request with two or more
+independent deliverables is a fork, even when one agent could do all of them: a
+hand-off cannot fan out and cannot come back.
+
 ## Fanning out
 
 Branches run at the same time, so a fan-out costs about as long as its slowest
@@ -139,30 +166,54 @@ whatever that branch needs, because a sibling's finding will never reach it.
 ## Choosing `context`
 
 `context` decides what each branch starts from. It is one setting for the whole
-call, chosen per call:
+call, chosen per call; leave it out and you get `inherit`, the most expensive:
 
 - `inherit` — everything said here so far. For work that only makes sense
   against the case as it stands: reviewing what has just been written here,
   continuing an investigation whose earlier findings are the thing being built
   on.
-- `compact` — the same, without the tool traffic: what was decided, not how it
-  was found out. The usual choice for a wide fan-out, where branches need the
-  case and the plan but not the fifty reads that produced them.
+- `compact` — the same, without tool calls, tool results or memory recalls:
+  what was decided, not how it was found out. The usual choice for a wide
+  fan-out, where branches need the case and the plan but not the fifty reads
+  that produced them.
 - `none` — nothing but its own instructions. The cheapest, and the honest one
   when the assignment is self-contained: a lookup, one file summarised, a
   command run elsewhere. Everything the branch needs must then be written out in
   the instructions, paths included.
 
-When two modes seem possible, write the missing facts into the instructions and
-take the cheaper one. Instructions are exact; an inherited transcript is only
-approximately about the branch's job.
+| What the branch starts with                        | `inherit`                            | `compact` | `none`                                      |
+| -------------------------------------------------- | ------------------------------------ | --------- | ------------------------------------------- |
+| Its own agent's system prompt and tools            | yes                                  | yes       | yes                                         |
+| The user's request and the messages here           | yes                                  | yes       | no                                          |
+| Tool calls, tool results, memory recalls           | yes                                  | no        | no                                          |
+| Results of earlier forks                           | yes                                  | yes       | no                                          |
+| Skills loaded here                                 | only if it runs on your agent        | the same  | no                                          |
+| Your whole `fork` call, siblings' instructions too | yes                                  | yes       | no                                          |
+| A fresh memory recall on its instructions          | no                                   | no        | if its agent recalls automatically          |
+| How its assignment arrives                         | "You are branch ...", siblings named | the same  | your instructions alone, as a plain message |
+
+A `none` branch is never told it is a branch. Its instructions must say so, what
+to return, and that only its final message comes back.
+
+When two modes seem possible, or branches would each want a different one, write
+the missing facts into the instructions and take the cheaper one. Instructions
+are exact; an inherited transcript is only approximately about the branch's job.
+
+Under `inherit` or `compact` a branch sees the user's whole request and will
+take all of it as its own. When it gets only part, its instructions must name
+the parts it does not own.
 
 ## What comes back, and what stays
 
-Only the answer comes back, and it is prose. Everything else a branch does is
-real and outlasts it: branches share this workspace with you and with each
-other, so a file one of them writes is a file you can read after the join, and
-anything committed to memory is there for every later run.
+Everything a branch does besides its answer is real and outlasts it: branches
+share this workspace with you and with each other, so a file one of them writes
+is a file you can read after the join, and anything committed to memory is there
+for every later run.
+
+The join is one result for your `fork` call: a `### name (status)` block per
+branch, in the order you declared them, each holding that branch's last message
+or, if it failed, its error. Anything a branch said before its last message is
+not in it.
 
 So decide, for each branch, which of the two carries its result:
 
@@ -187,8 +238,7 @@ builds, two branches reformatting the same tree.
 
 ## When a branch comes back wrong
 
-Each branch reports under its own name, with its status, and a failed one says
-why. What the final answer is remains your decision, not the join's.
+What the final answer is remains your decision, not the join's.
 
 A branch rarely fails at random; the usual cause is an assignment missing
 something it could not ask for. Re-running the same instructions gets the same