@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/docs/extensions/session-bus.md

@@ -0,0 +1,285 @@
+# session-bus — coordinate parallel Pi sessions
+
+A local coordination bus for Pi sessions on the same machine and repository:
+sessions discover each other, exchange short messages and events, consume an
+inbox, and claim paths before editing. A session joins explicitly, so the
+board opens empty and a peer never appears because the package loaded. Delivery is pull-based, and a session that
+joined listens for new mail — a report at its next turn, or,
+with `wake`, one raised turn as soon as the agent is idle, including right after
+a running turn settles. There is no network service and no hidden context.
+
+<img src="../../assets/screens/session.png" alt="The /sessions screen: a counts summary, session rows with unread and claim counts, and the focused session's cwd, claims, and identity" width="100%">
+
+## Capabilities
+
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Membership | `session join [label]`, `/team join [<label>]`, the board's `w` | The join: this session is on the bus under a stable label peers address, and listens for mail unless told not to. A label given to `session join` or `/team join` is also Pi's session name, so the footer and `/resume` agree with the record; `w` joins under the name the bus derives and writes nothing to Pi. | Unreleased |
+| Peer discovery | `session status` | Every active session with its unread count and claims, plus this session's identity, in one read. | Shipped |
+| Live board | `/sessions` | Sessions, this session's unread mail, and every claim held on the repository, on one screen. | Shipped |
+| Board actions | `/sessions` (`w`, `x`) | Start or stop listening from the board, or release an own claim behind a confirmation, without leaving it. | Shipped |
+| Short messages | `session send` | One message per recipient, addressed by label or id, with a broadcast for events. | Shipped |
+| Message kinds | `session send` with `kind` | A `message`, `event`, `ask`, or `handoff` keeps its meaning; `ask` does not block the sender, and a `handoff` is named as the work it assigns. | Shipped |
+| Message paths | `session send` with `paths` | A message can name the repository paths it concerns, echoed in the inbox row. | Shipped |
+| Inbox on demand | `session inbox` | Up to `limit` messages, oldest first, consumed only when the model asks. | Shipped |
+| Listening | `session join` | New mail reported at the next turn; `join({wake: true})` raises one turn once the agent is idle, and `join({listen: false})` stops it. | Unreleased |
+| Path claims | `session claim`, `session release` | A file or directory prefix held by one session at a time. | Shipped |
+
+## Quickstart
+
+```bash
+pi --extension ./extensions/session-bus   # load just this extension
+pi -e .                                   # load the whole package
+pi install ./                             # install the package for a user
+```
+
+```text
+/sessions                                       # open the board: empty until this session joins
+session({action:"join", label:"billing-core"})  # join, name this session for Pi, and listen for mail
+```
+
+Nothing joins on `session_start`, in any mode: the board and `status` only read, so
+a fresh session sees an empty board and a peer's session is not listed until it
+joins. `join` is the join — it puts this session on the bus, names it when a label
+is given, and starts listening — and so is the first action that needs you to be
+addressable: `send`, `inbox`, `claim`, or `release`.
+
+## Tool
+
+`session` — `exposure: "direct"` (the default), `executionMode: "sequential"`,
+read-write and closed-world. One action-shaped tool keeps the prompt surface
+small: each action takes only the parameters it needs, and the result is one
+collapsed line that expands to the board's rows.
+
+| Action | Inputs | Result |
+|---|---|---|
+| `status` | — | Active sessions with unread counts, claims, and this session's identity. Prunes stale records. A read: it never adds this session to the bus. |
+| `send` | `to`, `text`, optional `kind`, optional `paths` | Writes one message per recipient. `to: "*"` is only valid with `kind: "event"`. |
+| `inbox` | optional `limit` | Returns and deletes up to `limit` messages, oldest first (default 20, max 50). |
+| `claim` | `paths` | Claims repository-relative files or directory prefixes; returns conflicts with their owner. |
+| `release` | `paths` | Removes claims owned by this session; reports paths owned by someone else. |
+| `join` | optional `label`, `wake`, `listen` | Joins the bus, names this session on it and in Pi when a label is given — the same path and uniqueness rule as `/team join`, so the footer and `/resume` agree with the record peers address — and starts listening for mail. `wake: true` raises one turn per burst once the agent is idle; `wake: false` reports at the next turn; `listen: false` joins without listening. A label a live session holds is refused with its owner named, and the refusal leaves both names and the watch alone. The result reports the label the bus settled on and whether mail will reach this session. |
+
+A claim is all-or-nothing: if one path conflicts, nothing is claimed. A claim on
+a directory conflicts with claims below it and above it, so `src/api` and
+`src/api/routes.ts` cannot be held by different sessions. There is no `force`
+takeover; wait for the owner, ask it to release, or let the session expire.
+
+Paths resolve against the caller's working directory and are stored relative to
+its repository root; a path outside the repository is refused.
+
+`wake` is the mode, not an arm-time switch: `join({ wake: true })` raises a turn
+for a session that was reporting at the next turn, and `join({ wake: false })` —
+or a plain `join` — sets it back. The board's `w` starts and stops listening,
+and it starts a plain watch; set `wake` with the tool. Nothing joins or listens on
+`session_start`; a session that never asks stays pull-only and off the bus.
+
+## Commands
+
+`/sessions` is the human surface: in `tui` mode it opens the live board described
+in [the board](#the-sessions-board), and every other mode prints the compact
+listing. It takes no argument, and it joins nothing — the board's `w` is the one
+act there that puts this session on the bus.
+
+| Command | Effect |
+|---|---|
+| `/sessions` | Open the board: `Tab` cycles Sessions, Inbox, and Claims. `Enter` opens the focused row, `w` starts or stops listening, and in Claims `x` releases a claim you hold after a y/N confirmation. A non-TUI caller prints the listing. |
+
+Labels are how another session addresses you. Name one by the outcome it owns
+(`billing-core`, `integrator`, `verify-billing`), not by a layer or a role;
+duplicate labels get a short id suffix automatically.
+
+A label is also Pi's session name, so the footer's `[label]` and `/resume` agree
+with the bus. Because the bus derives a joining session's label from that name, a
+named session comes back under the same label after a resume.
+
+The tool's `join` action is the same join from the model's side, so a `board` or a
+`team` call can put a session on the bus without the user naming it, and
+`/team join [<label>]` is that join from the terminal.
+
+## Behaviour by mode
+
+| Mode | Behaviour |
+|---|---|
+| `tui` | Does not join on start. `/sessions` opens the board: sessions, this session's unread mail, and every claim, with `Tab` between them, and lists nobody in this session until it joins. |
+| `rpc`, `json`, `print` | Same rule: `/sessions` and `status` are reads, and the first addressable action joins. This is how a subagent or an RPC-driven session opts in. |
+| WeChat peer | Same as `rpc`: the peer is a separate AgentSession in the bridge process and joins only on explicit use. Messages are read by that peer’s model; the bridge does not forward them to the phone. |
+
+Every mode can join and listen; the notice is a visible transcript message, so
+a `wake` raises that session’s own turn, not a phone notification.
+
+## Configuration
+
+None in v1. The heartbeat (10 s), watch poll (2 s), session TTL (10 min), message
+TTL (24 h), text cap, inbox limit, and preview cap are fixed, not configurable.
+The bus lives under the agent directory, not the project, so it is never committed.
+
+## Parallel workflow
+
+1. The user joins each session (`/team join <label>`, or `w` on the board), and the
+   contract (OpenAPI, schema, or types) is written before parallel work starts.
+2. Each session claims its paths before touching them, then implements its side.
+3. A contract, build, or test change goes out as an event:
+   `session({action:"send", to:"*", kind:"event", text:"contract v2: ..."})`.
+4. Other sessions consume `inbox` at the start of their next turn, or join with
+   `session({action:"join", wake:true})` so a message raises their turn as soon
+   as they are idle; a wake that arrives mid-turn is raised once that run
+   settles, never pushed into the running turn.
+5. Whoever integrates merges the worktrees and runs the project's full check.
+
+The bus carries coordination, not authority. The plan, todo list, contract, and
+git branch remain the source of truth.
+
+## The /sessions board
+
+The TUI opens the board; RPC, JSON, and print print the compact listing. `Tab`
+cycles Sessions, Inbox, and Claims, `Enter` opens the focused row, and `Esc` goes
+back from a row's pane. `↑`/`↓` and `PgUp`/`PgDn` scroll a list; a pane adds
+`g`/`G` for its ends.
+
+The board changes only this session's own state: `w` starts or stops listening and
+`x` releases a claim it holds. Mail is previewed, not consumed — `session inbox`
+consumes it — and no view shows another session's inbox or releases its claims.
+
+## Message kinds
+
+Message kinds are `message` (default), `event`, `ask`, and `handoff`. An `ask` is
+still a message: it does not block or wait for a reply. Text is capped at 4,000
+characters.
+
+A `handoff` is the one kind that assigns work, so it is the one kind the notice
+treats as an instruction: the waking turn is headlined `1 handoff`, the preview
+keeps 800 characters so the card, its paths, and the next step survive, and the
+hint says the work is yours — read it with `session inbox`, record the plan, and
+start. Nothing else changes: a handoff still waits in the inbox, and the recipient's
+listening watch is what raises the turn.
+
+## Limitations
+
+- **Same machine, same OS user.** Any process with that user’s file access can
+  read or write the bus; there is no authentication between sessions.
+- **Pull-based by default.** A message does not reach a session that has not
+  joined and is not listening. Agents must call `inbox` at coordination points, and
+  joining listens unless `join({ listen: false })` says otherwise.
+- **A reader is not a member.** `/sessions` and `session status` never add this
+  session to the bus, so an unjoined session reads a board it is not on until it
+  joins or acts.
+- **Membership is per session and session-only.** It survives neither a resume nor a
+  new process; unread mail is previewed once more after `/resume`, and the record
+  goes when the session stops.
+- **The board acts on your own state only.** `w` starts or stops listening and `x`
+  releases a claim it holds. Mail is a preview, not a consume: the board never
+  deletes a message, never marks one reported, and never touches a peer's inbox or
+  claim.
+- **Two listening peers can ping-pong.** Each reply wakes the other as soon as it is
+  idle. A wake raises one turn per burst, and `inbox` consumes, so the loop needs
+  both sides to keep replying; the answer is to stop listening on one of them.
+- **No broadcast history.** A broadcast reaches the sessions active at send time;
+  a session that joins later does not receive it.
+- **No forced claims.** A crashed owner blocks its paths until the session TTL
+  expires. This is deliberate; stealing a claim is worse than waiting.
+- **Bounded by TTL.** An idle session with a stopped heartbeat is pruned after
+  ten minutes; its record, its claims, and an inbox directory left empty go with
+  it, and its unread mail expires after 24 hours. A claim belongs to a record
+  that was read from disk, not to the reader's idea of who is active, so a peer
+  that claimed in the middle of someone else's prune keeps it.
+- **One session id, one record.** Resuming a session in a second pane gives two
+  processes the same id, and the record names the process that owns it: the older
+  pane's shutdown leaves the record and the claims to the newer one instead of
+  releasing them. Listening is still per process, so the survivor's watch is the
+  survivor's.
+- **A message file that does not parse is dropped.** The board's read never
+  consumes mail, but it does delete a file it cannot validate, so a truncated
+  message cannot linger on the bus.
+- **No network.** It is not a distributed bus and does not synchronize machines.
+
+## Pi integration
+
+| Point | Detail |
+|---|---|
+| Tools | `session` — one action-shaped tool; `readOnlyHint: false`, `destructiveHint: true`, `openWorldHint: false`, `executionMode: "sequential"`. |
+| Commands | `/sessions` — the board in `tui`, the listing elsewhere; no arguments and no sub-commands. |
+| UI | `tui` mounts `SessionListComponent` through `withPolledScreen` (rails suppressed, a 1 s read-only poll of `snapshot()` + `peek()`); every other mode prints through `ctx.ui.notify`. No status chip, so listening never changes the footer. |
+| Events | `session_start` resolves the repository and arms the mail trigger, without joining; `before_agent_start` reports queued non-wake mail at the next turn, `agent_settled` retries a wake the run suppressed, and `context` prunes stale notices; `session_shutdown` clears the heartbeat, the watch ticker, and the record. The seven hooks are `lib/report.ts`'s `registerPendingChannel`, not a local copy. |
+| State | Files under `<agent-dir>/session-bus/<repo-key>/`; nothing in the session branch. Listening is session-only. `/resume` re-registers the same session id. |
+| Lifecycle | The factory only registers. The runtime starts on `session_start`; heartbeat, watch ticker, and cleanup belong to it. Disabling `session-bus` through `PI_DISABLED_EXTENSIONS` registers nothing. |
+| Mode | Uses `ctx.mode` to decide whether `/sessions` mounts the board and how a label is derived; nothing joins at start in any mode; `askHuman` is not involved and no status chip is published. |
+
+## Design notes
+
+- **Common git dir as the key.** `git rev-parse --git-common-dir` gives all
+  worktrees of one repository the same bus; `--show-toplevel` normalizes claim
+  paths within each worktree. Non-repository sessions fall back to their cwd.
+- **One path, one claim.** The cwd is canonicalized at join and every claim or
+  release is re-keyed by its real target, so a working directory reached through
+  a symlink still resolves inside its own repository, a link inside the repository
+  and the file it names are the same claim, and a link that leaves the repository
+  is refused. The automatic label is the real basename of the cwd, so a session
+  started through a link named differently is named after the directory it is
+  actually in. An absolute path argument that sits outside the repository is
+  refused before it is re-keyed, and a relative one whose target leaves the
+  repository is refused by the re-keying itself.
+- **One file per item.** Sessions never append to a shared registry: each session
+  writes its own record, each message is its own file, and a claim is a temp file
+  hard-linked into place — an exclusive create no reader can see half-written.
+  This avoids a cross-process lock for the common path.
+- **Lazy join.** Loading a package extension must not make every subagent and
+  WeChat peer a team member. Nothing joins at start, in any mode; a session opts
+  in by joining, or by the first action that needs it to be addressable.
+- **Listening is on the record.** `join` writes this session's watch state onto its
+  own record, so a peer's `status` read says whether mail will reach it without
+  asking it anything. The field is absent when the session is not listening — which
+  is also how a record written before the field existed reads, and neither is a
+  claim about a peer that has since gone quiet.
+- **Sanitized at the boundary.** Messages are model-authored and are sanitized
+  before rendering, like other untrusted text in the transcript.
+- **Poll, not `fs.watch`.** The listening watch reads this session's inbox directory
+  with one `readdir` every 2 s, the same trade `watch` makes for a file tail, so
+  it does not depend on a platform's event API or a filename in the event. Only
+  a listening session polls.
+- **Read the board, prune on the next call.** The open board polls a read-only
+  `snapshot()` and `peek()` that hide a session past the TTL, a claim held by one,
+  and consume nothing. The physical prune, and the claim release that goes with
+  it, happen on the next `status` or `claim` call — which is the call that reader
+  is about to make.
+- **Release by the stored path.** A claim is stored relative to the repo root of
+  the session that took it, so releasing one resolves nothing: re-resolving it
+  against a cwd below that root would target `src/src/api`. The screen refuses a
+  peer's claim before asking the store, which checks the owner again.
+- **A pane is a log or prose.** `DetailContents.text` wraps at the render width
+  and `tail: false` opens it at the top, so a message reads as prose while a job
+  log keeps following its tail.
+- **The notice reuses the shared report channel.** `lib/report.ts` already owns
+  whether an outcome may raise a turn; the bus supplies the pending mail and the
+  text, and bytefly renders the notice like a `job` or `watch` one.
+
+## Files
+
+| File | Responsibility |
+|---|---|
+| `index.ts` | Disable guard, registration, the pending-report channel, and the session hooks. |
+| `join-request.ts` | The `board`/`team` join request: one `bus.join` answer, and the label it settles becomes Pi's session name. |
+| `runtime.ts` | Lifecycle, repo key, joining, heartbeat, and the session's own reads and writes. |
+| `mail-watch.ts` | The armed inbox watch: the poll, the not-yet-reported queue, and its state. |
+| `store.ts` | Atomic JSON files, inbox, peek, claims, pruning, and the one release loop. |
+| `protocol.ts` | Pure labels, targets, paths, validation, conflict rules. |
+| `overlap.ts` | The one "do these paths collide?" predicate: `claimsConflict`, which normalizes both spellings of a claim path first. |
+| `resolve.ts` | `resolveClaimPaths` and `claimPathMessage`: a claim path made repository-relative, posix, and canonical through its real target, or the refusal naming why. |
+| `types.ts` | The stored shapes — session record, message, claim — and the tool's `details`. |
+| `tui.ts` | The `/sessions` board, its scopes, and the pane over one row; the row grammar is in `rows.ts`. |
+| `rows.ts` | The session/claim/message row builders and summaries shared by the board and the transcript. |
+| `result.ts` | The `session` tool's expanded result block and its collapsed line. |
+| `notice.ts` | The mail notice's model text and renderer details. |
+| `tools.ts` | The `session` tool and its renderer. |
+| `commands.ts` | `/sessions`. |
+| `format.ts` | Model-facing listing and result text. |
+
+## Testing
+
+The capability suites — `format`, `protocol`, `store`, `runtime`, `tui`, `tools`,
+`overlap`, `resolve`, and `extension` — are declared in `test/suite-manifest.ts`.
+They build a bus in a temp directory with a fixed clock, so none needs a live peer; `runtime.test.ts`
+puts its real-repository cases behind `runSlowSuites`, which skips unless `CI` or
+`PI_SLOW_TESTS=1` is set.

package/{extensions/subagent/README.md → docs/extensions/subagent.md}

@@ -6,49 +6,52 @@ exploration or parallel work does not fill the main conversation. A single run
 can also start in the background and be inspected, collected, or cancelled with
 `/agents`.
 
+## Capabilities
+
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Isolated context | `subagent` | Each task runs in its own process with its own transcript, and only its final reply returns to the caller. | Shipped |
+| Explicit tool allowlist | `--tools` for every child | An agent gets only its declared tools, not the parent's ambient extensions; `worker` cannot recurse into `subagent`. | Shipped |
+| Read-only delegation | `subagent` (`readOnly: true`) | Every spawned agent runs with a reader-only tool set, enforced at the process boundary. | Shipped |
+| Plan-mode guard | `subagent`, plan mode | Plan mode forces every call read-only and refuses `/agents` until the plan is approved. | Shipped |
+| Project-agent trust gate | `agentScope` with the trust gate | A `.pi/agents` file loads only when the project is trusted or confirmed, so a repository cannot inject a prompt by adding a file. | Shipped |
+| Three delegation modes | `subagent` (`agent` + `task`, `tasks[]`, `chain[]`) | One agent, an independent batch, or an ordered chain whose steps receive `{previous}`. | Shipped |
+| Parallel and chain bounds | `tasks[]`, `chain[]` | Parallel accepts up to 8 tasks with 4 running at once; a chain accepts up to 8 steps and stops at the first failure. | Shipped |
+| Per-step working directory | `cwd` | A single run, each parallel task, or each chain step can name its working directory; a relative path resolves against the active root. | Shipped |
+| Built-in agents | `subagent` (`agent`) | Recon, planning, review, implementation, research, testing, debugging, and docs work without writing an agent file. | Shipped |
+| External agents | `subagent` (`agentScope`) | Markdown agents from the user directory and the nearest `.pi/agents`, opt-in per scope and never replacing a built-in silently. | Shipped |
+| Background runs | `subagent` (`background: true`), `/agents` | A single run continues after the call returns and is inspected, collected, or cancelled from the board. | Shipped |
+| Background concurrency cap | `backgroundMax` | At most four background children run at once; finished runs release their slot. | Shipped |
+| Session-owned background run | `background: true` | `/tree` does not move the run and a restart cannot resume it; an unfinished start shows as `interrupted`. | Shipped |
+| Live progress | `subagent` | Tool calls and progress update in the transcript while the child runs, with a `↳ N` footer chip and a finish notice. | Shipped |
+| Bounded runs | `timeoutMs` | A child that hangs is killed at the deadline and reported as a failed run rather than rejecting the whole call. | Shipped |
+| Optional transcripts | `transcripts` | Per-run streams under `.pi/subagents/`, written by the parent and pruned by age and count. | Shipped |
+| Inherited model | `subagent` | Children use the dispatching session's model and thinking level unless an agent overrides them. | Shipped |
+
+## Quickstart
+
 ```bash
 pi --extension ./extensions/subagent    # load just this extension
 pi -e .                                 # load the whole @gavin-hu/my-pi-agent package
-pi install ./                           # install the package
+pi install ./                           # install the package for a user
 ```
 
-## Tool rendering
+```text
+subagent({ agent: "explorer", task: "Find every place the HTTP client is retried" })
+/agents                                 # inspect, collect, or cancel background runs
+```
 
-How the `subagent` call and its result look in the transcript — the call line as a headline and the body indented under it:
+## Tool
 
 <img src="../../assets/tools/subagent.png" alt="The subagent tool's call and result: the call line and an indented body with the two tasks, each agent's section rule, its summary, and the usage total" width="100%">
 
-## Screens
-
-<img src="../../assets/agents.png" alt="The /agents screen: running and finished background helpers with status, task, elapsed time, and usage" width="100%">
-
-## What it does
-
-- **Isolated context.** Each subagent is a separate `pi` process with its own
-  transcript; only its final reply is returned to the caller.
-- **Built-in agents.** `explorer`, `planner`, `reviewer`, `worker`,
-  `researcher`, `tester`, `debugger`, and `documenter` ship with the extension.
-- **External agents.** Optionally load markdown agents from `~/.pi/agents`
-  (user) and the nearest `.pi/agents` (project). They are opt-in per scope and
-  never replace the built-ins silently.
-- **Three modes, plus background.** One agent, a parallel batch, or a sequential
-  chain; a single run can also continue after the tool returns and be collected
-  from `/agents`. A running helper adds a `↳ N` footer chip, and a finish notice
-  points back at `/agents`.
-- **Streaming.** Tool calls and progress update live in the transcript while the
-  subagent runs; the `app.tools.expand` key (`ctrl+o` by default) expands the
-  full task, tool calls, Markdown output, and usage.
-- **Bounded runs.** A per-run deadline kills a child that hangs, and reports it
-  as a failed run instead of rejecting the whole call.
-- **Optional transcripts.** Opt-in per-run stream under `.pi/subagents/`,
-  written by the parent and pruned by age and count.
-- **Inherited model.** Subagents use the dispatching session's model and thinking
-  level unless an agent overrides them (none do).
-
-## Tool
-
-`subagent` takes exactly one mode. Every call also accepts `agentScope` and
-`readOnly`.
+`subagent` — `exposure: "direct"` (the default), read-write, open-world,
+destructive, and parallel across calls: only a chain orders itself. A call takes
+exactly one mode, plus `agentScope`, `readOnly`, and `cwd`. A call with no mode,
+or with two, is refused before any process starts, and an unknown agent name is
+refused with the resolved roster.
 
 | Field | Value |
 |---|---|
@@ -59,78 +62,38 @@ How the `subagent` call and its result look in the transcript — the call line
 | `cwd` | Optional working directory for the spawned process (single mode; per-step for the others). A relative path resolves against the active root. |
 | `agentScope` | `user` (default), `project`, or `both` — which external agent directories to load. |
 | `readOnly` | `true` forces every spawned agent to a reader-only tool set; plan mode sets it automatically. |
-| `exposure` | `direct`, active by default. |
-| `annotations` | `readOnlyHint: false`, `openWorldHint: true`. |
-
-## Behaviour by mode
-
-### Single
-
-```json
-{ "agent": "explorer", "task": "Find every place the HTTP client is retried", "cwd": "." }
-```
-
-### Background
-
-```json
-{ "agent": "explorer", "task": "Map the auth module", "background": true }
-```
-
-The tool returns immediately with a run id such as `a2`. `/agents` lists every
-run with its status, elapsed time, and usage; `Enter` opens the run, `c` collects
-a finished result into the conversation, and `x` cancels a running one. While a
-run is active, its detail pane follows a bounded preview of the latest output,
-and a `↳ N` chip in the footer counts running helpers. A finish notice points
-back at `/agents`; the finalized result replaces the preview when the run
-finishes. A background run is session-owned and is bounded by the same timeout
-and transcript settings as a foreground run.
-
-### Parallel
-
-Runs up to 8 tasks, at most 4 at once. Independent tasks only.
-
-```json
-{
-  "tasks": [
-    { "agent": "explorer", "task": "Map the auth module" },
-    { "agent": "explorer", "task": "Map the billing module" }
-  ]
-}
-```
 
-Each task's output is capped at 50 KiB in the model-facing reply; the complete
-output remains in the tool details.
-
-### Chain
-
-Runs steps in order. `{previous}` in a step's `task` is replaced by the prior
-step's final output. The chain stops at the first failing step, and a chain has
-at most 8 steps (like the parallel task cap).
-
-```json
-{
-  "chain": [
-    { "agent": "explorer", "task": "Find the config loader" },
-    { "agent": "planner", "task": "Using this context, plan a refactor:\n\n{previous}" },
-    { "agent": "worker", "task": "Implement the plan:\n\n{previous}" }
-  ]
-}
-```
+## Commands
 
-## Command
+<img src="../../assets/screens/agents.png" alt="The /agents screen: running and finished background helpers with status, task, elapsed time, and usage" width="100%">
 
 | Command | What it does |
 |---|---|
 | `/agents` | Open the background-run board: inspect, collect, or cancel. |
 
 The board is TUI-only for actions; RPC, print, and JSON print the run list.
-Collecting sends the result as a user message, which starts the next turn.
+`Enter` opens the run, `c` collects a finished result into the conversation, and
+`x` cancels a running one. Collecting sends the result as a user message, which
+starts the next turn. Plan mode refuses the command until the plan is approved.
+
+## Behaviour by mode
+
+The tool and its background runs work in every mode; only the run board is a
+terminal surface.
+
+- In `tui` mode `/agents` opens the board, the footer carries a `↳ N` chip while
+  helpers run, and a finish notice points back at `/agents`.
+- In RPC, print, and JSON `/agents` reports the same runs as a notification — a
+  count, then one line per run with agent, task, status, elapsed time, and usage
+  — and there is no board and no action.
+- In plan mode `subagent` stays active but every call is forced read-only, and
+  `/agents` refuses until the plan is approved.
 
 ## Configuration
 
 Read from the shared `bytefly.json` section `subagent` (global then project),
 once per session. Keys and bounds live in the
-[configuration page](../../docs/configuration.md#subagent--delegated-runs);
+[configuration page](../configuration.md#subagent--delegated-runs);
 the behaviour is here.
 
 - **`timeoutMs`** (default ten minutes, `0` disables) bounds one child run. The
@@ -186,18 +149,75 @@ confirmation before running them in an interactive session; without a UI it
 refuses instead of running them silently. The gate is driven only by the
 project's trusted state — the model cannot turn it off.
 
+## Delegation modes
+
+One mode per call, with a single `background` run available on the single-agent
+shape.
+
+### Single
+
+```json
+{ "agent": "explorer", "task": "Find every place the HTTP client is retried", "cwd": "." }
+```
+
+### Background
+
+```json
+{ "agent": "explorer", "task": "Map the auth module", "background": true }
+```
+
+The tool returns immediately with a run id such as `a2`. `/agents` lists every
+run with its status, elapsed time, and usage. While a run is active, its detail
+pane follows a bounded preview of the latest output, and a `↳ N` chip in the
+footer counts running helpers. A finish notice points back at `/agents`; the
+finalized result replaces the preview when the run finishes. A background run is
+session-owned and is bounded by the same timeout and transcript settings as a
+foreground run.
+
+### Parallel
+
+Runs up to 8 tasks, at most 4 at once. Independent tasks only.
+
+```json
+{
+  "tasks": [
+    { "agent": "explorer", "task": "Map the auth module" },
+    { "agent": "explorer", "task": "Map the billing module" }
+  ]
+}
+```
+
+Each task's output is capped at 50 KiB in the model-facing reply; the complete
+output remains in the tool details.
+
+### Chain
+
+Runs steps in order. `{previous}` in a step's `task` is replaced by the prior
+step's final output. The chain stops at the first failing step, and a chain has
+at most 8 steps (like the parallel task cap).
+
+```json
+{
+  "chain": [
+    { "agent": "explorer", "task": "Find the config loader" },
+    { "agent": "planner", "task": "Using this context, plan a refactor:\n\n{previous}" },
+    { "agent": "worker", "task": "Implement the plan:\n\n{previous}" }
+  ]
+}
+```
+
 ## Built-in agents
 
 | Agent | Tools | Purpose |
 |---|---|---|
-| `explorer` | `read, grep, find, ls` | Fast codebase recon; returns files + line ranges, key code, architecture, and where to start. |
-| `planner` | `read, grep, find, ls` | Delegated planning in an isolated context (headless/chain); never edits. |
-| `reviewer` | `read, grep, find, ls, bash` | Reviews for bugs, security, and maintainability; bash limited to read-only `git diff/log/show`. |
-| `worker` | `read, write, edit, bash, grep, find, ls` | General-purpose executor; reports what changed. |
-| `researcher` | `read, grep, find, ls, web_search, web_fetch` | Investigates external questions and returns sourced findings with confidence. |
-| `tester` | `read, write, edit, grep, find, ls, bash` | Adds or updates tests and runs them; never weakens assertions to pass. |
-| `debugger` | `read, grep, find, ls, bash` | Root-causes a failure from evidence; read-only plus running tests/builds. |
-| `documenter` | `read, write, edit, grep, find, ls, bash` | Updates READMEs, docs, and changelogs to match the code. |
+| `explorer` | `read, grep, find, ls, read_doc` | Fast codebase recon; returns files + line ranges, key code, architecture, and where to start. |
+| `planner` | `read, grep, find, ls, read_doc` | Delegated planning in an isolated context (headless/chain); never edits. |
+| `reviewer` | `read, grep, find, ls, read_doc, bash` | Reviews for bugs, security, and maintainability; bash limited to read-only `git diff/log/show`. |
+| `worker` | `read, write, edit, bash, grep, find, ls, read_doc` | General-purpose executor; reports what changed. |
+| `researcher` | `read, grep, find, ls, read_doc, web_search, web_fetch` | Investigates external questions and returns sourced findings with confidence. |
+| `tester` | `read, write, edit, grep, find, ls, read_doc, bash` | Adds or updates tests and runs them; never weakens assertions to pass. |
+| `debugger` | `read, grep, find, ls, read_doc, bash` | Root-causes a failure from evidence; read-only plus running tests/builds. |
+| `documenter` | `read, write, edit, grep, find, ls, read_doc, bash` | Updates READMEs, docs, and changelogs to match the code. |
 
 Each agent's system prompt is appended to the subprocess, and its tool list is
 passed as `--tools`. Every built-in has an explicit allowlist, so an agent never
@@ -210,7 +230,7 @@ for another agent (typically `worker`) to execute, and it works headlessly. It
 returns the plan as text and writes nothing. For **interactive** planning where
 the user reviews and approves a saved plan, use the plan-mode extension instead
 (`enter_plan_mode` / `write_plan` / `exit_plan_mode`), which operates on the
-main session and persists to `.pi/plans`. Plan mode keeps `subagent` available
+main session and persists to the agent directory. Plan mode keeps `subagent` available
 for exploration but forces it read-only, so delegated recon is safe mid-plan.
 
 ## External agents
@@ -259,9 +279,9 @@ is the safe way to delegate exploration, and plan mode sets it automatically.
 
 The child is restricted at the process boundary, not by its prompt: the tool
 list passed as `--tools` is the intersection of the agent's tools with
-`read`, `grep`, `find`, `ls`, `web_search`, and `web_fetch`. An agent with no
-reader tools (or no `tools` declaration) gets the full reader set instead. So
-`worker` cannot write under `readOnly`, and an external agent file that
+`read`, `grep`, `find`, `ls`, `read_doc`, `web_search`, and `web_fetch`. An agent
+with no reader tools (or no `tools` declaration) gets the full reader set
+instead. So `worker` cannot write under `readOnly`, and an external agent file that
 customizes a built-in cannot widen it. A short read-only note is appended to the
 child's system prompt for behavior; the tool list is the enforcement.
 
@@ -314,6 +334,19 @@ with `{previous}` left in place, rather than the substituted prior output that
 was actually sent to the child; that output is already shown as the previous
 step's `Output`.
 
+## Limitations
+
+- Background runs are single-mode only. Parallel and chain calls wait as before.
+- A background run is session-owned: `/tree` does not move it, and a process
+  restart cannot resume it. A start entry without a finish is shown as
+  `interrupted`.
+- The collected output is capped at 50 KiB; the optional transcript keeps the
+  full stream. The `/agents` detail keeps only a bounded live preview, and a
+  finished run keeps its bounded output in the session record rather than the
+  child's full result.
+- A finish notice appears in the TUI, but there is no OS notification; the run
+  remains listed in `/agents`.
+
 ## Non-goals
 
 - **No ambient external agents.** User agents load only when an explicit
@@ -340,29 +373,19 @@ step's `Output`.
   per process: a resumed session starts from zero, and a run that never produced
   an assistant message publishes nothing.
 
-## Limitations
-
-- Background runs are single-mode only. Parallel and chain calls wait as before.
-- A background run is session-owned: `/tree` does not move it, and a process
-  restart cannot resume it. A start entry without a finish is shown as
-  `interrupted`.
-- The collected output is capped at 50 KiB; the optional transcript keeps the
-  full stream. The `/agents` detail keeps only a bounded live preview, and a
-  finished run keeps its bounded output in the session record rather than the
-  child's full result.
-- A finish notice appears in the TUI, but there is no OS notification; the run
-  remains listed in `/agents`.
-
 ## Pi integration
 
 | Aspect | Detail |
 |---|---|
 | Tool | `subagent` |
 | Exposure | `direct`, active by default |
-| Annotations | `readOnlyHint: false`, `openWorldHint: true` |
+| Execution mode | none: sibling calls are independent, each spawning its own child, so they stay parallel |
+| Annotations | `readOnlyHint: false`, `destructiveHint: true`, `openWorldHint: true` |
 | Output schema | none; the full result lives in tool-result `details` |
 | Execution | spawns `pi --mode json` subprocesses; external agents discovered from `<agent-dir>/agents` and `.pi/agents` |
+| Command | `/agents` |
 | State storage | tool-result `details`; optional per-run transcripts under `.pi/subagents/`; background start/finish entries (`subagent-background`) on the session branch |
+| Event | `my-pi-agent/subagent-finished` (`SUBAGENT_FINISHED_CHANNEL` in `lib/events.ts`) once per finished child |
 | Lifecycle | `session_start` loads the config, prunes expired transcripts, and attaches the footer chip; `session_shutdown` aborts every live background child and clears the chip |
 
 ## Design notes
@@ -442,6 +465,30 @@ step's `Output`.
 | `background-tui.ts` | The `/agents` board: a `DockListScreen` with a live output pane and width-aware facts. |
 | `commands.ts` | The `/agents` command. |
 | `ui.ts` | The running-count footer chip and finish notices. |
+| `accounting.ts` | The `subagent-finished` event payload built from a result (pure). |
 | `format.ts` | Token/usage/total line and tool-call formatting (pure, money-free). |
 | `render.ts` | `renderCall` / `renderResult` transcript rendering. |
 | `types.ts` | Shared result and process types. |
+
+## Testing
+
+```bash
+bun test extensions/subagent
+```
+
+Four co-located suites, declared in `test/suite-manifest.ts`:
+
+- `agents.test.ts` — the built-in registry, markdown discovery and pool
+  resolution, config normalisation, the parameter schema, `resolveMode`,
+  subprocess argument construction, invocation, and the finished event.
+- `run.test.ts` — the stream helpers, the concurrency limiter, `runSingleAgent`
+  against a scripted child, transcripts and pruning, the background runtime, and
+  the board component.
+- `render.test.ts` — the call and result blocks in every mode, collapsed and
+  expanded, the failure text, and component reuse.
+- `extension.test.ts` — registration, run settings, mode validation, all three
+  modes, the project-agent gate, accounting, `/agents`, the footer chip, and the
+  formatters.
+
+`runSingleAgent` takes an injectable `SpawnFn`, so no suite launches `pi` or
+spends tokens.