The Group tool — who reports to whom
The Group tool: the one record of which session reports to which, the named group a mission works in, the place block each session opens with, and how a session starts workers that report back to it.
On this page
What it is
A mission is several Claude Code sessions working toward one outcome: a lead, the workers it starts, and sometimes workers of their own. The Group tool is the one record of that tree. It answers three questions every other tool asks: who does this session report to, who reports to it, and what is the chain up to the owner.
A group can also be named. A named group carries a short outcome ("Every supplier invoice lands in the ledger the day it arrives"), an optional document set, and up to twelve read-first files. Every session at or below the group's root is in it automatically; there is no join step.
How a session ends up in a group
When it is started. A session that starts another can say
reportTo: "me", and the new session is linked under it before its first turn. A session that is already in a group links what it starts to itself by default;reportTo: "owner"opts out.When a mission starts. Starting a mission from the Overseers screen names a group rooted at the mission's overseer.
When a session is handed over. A session replaced by a fresh one (its memory filled up, or it was replaced on purpose) passes its place in the tree to its successor.
When a replacement is recorded by hand. If the replacement already happened outside the app — an older session was retired and a new one started in its place — the owner records it with
POST /group/succeed { from, to }, and everything that follows a hand-over moves at once: the place in the tree, the review clock, the messages nobody answered, the held queue, open tasks, wake schedules, worktrees, standing permissions, owner cards and the keep-alive mark, with the successor told in one note what it now holds. The session being replaced may already be archived; that is the case it is for, while the session taking over must still be running. Sending the same pair again is safe and finishes anything that stopped half-way, and the call answers what moved and what did not.When it is moved on purpose. A lead can re-point a session below it at a new parent — for example a crew's workers moved under their foremen — and the owner can move any session. The session keeps working; from its next turn its reports go to the new parent. Each move is kept in a history with who made it and why.
A link is written once. After that, only a hand-over or a deliberate move changes it, and nothing edits it by hand.
What it changes for the sessions in it
- Reports go up, not to the inbox. A linked session's finished turn, its questions and its owner cards go to the nearest live session above it (report routing). The owner sees them only when nobody above is left.
- A clear opening note. A session started under another is told that its final message reaches its parent automatically, and that it must not archive itself — the parent archives it once it has the result.
- A place block. Each session in a group opens with a short block saying where it stands: the
group's name and outcome, its chain up to the owner, and the group's documents. Asking for the
brief (
GET /group/brief) is what adds who works beside and under it, and what shows the picture as it stands now rather than when the session started. - A private name stays private. A session in a private project, a hidden one, or one read before the app has finished working out which coaching library belongs to this account reports its state but not its title. The read never waits for that lookup; it withholds the name until the lookup completes.
- The parent can tidy up. A session can archive any session below it with its own key.
Ending a group
Ending a group is a person's action, from the mission screen's End button. It stops every session in the group and refuses new members. No agent can end a group.