LLeMbas-CLI/harness/team.md

# Teams

Spec 3.2.0. **Subagents that work together.** A session's agent — the **lead** — may add
**members**, background agents that each own a part of the work, and lead them as a manager: it
plans, splits the work, coordinates and reviews, and the members do it. Members talk to each other
and to their managers in the team's **room**. A member may itself lead an area with members of its
own, so a team grows from a few agents side by side into a small company with one goal. The same in
a chat on the server and in an agent session on a device, in both projects.

The tools are `tools/team_add.json`, `team_send.json`, `team_read.json`, `team_stop.json`; the texts
and numbers `loop.json` `team` (and the size notes in `context.note`); the prompt texts
`prompts/blocks/team_lead.md` and `team_member.md`; the cases `conformance/team.json`.

## 1. Words

- **Agent**: the lead or a member. Every agent has a **name**: the lead is `lead`; a member the name
  it was added under. Names are unique in the team.
- **Member**: an agent added with `team_add`, by the lead or by a member that leads. Its **manager**
  is the agent that added it. The members an agent added, and theirs, down the tree, are **under**
  it; with the agent itself they are its **subtree**.
- **Manager**: an agent with at least one member, and the lead from the start when the team's `min`
  is 2 or more (§2). A manager does not do the work (§6).
- **Team**: the lead and every member, one per lead session; **its size** is how many agents it has
  now (§3).
- **Room**: the team's messages, numbered from 1 in the order they were posted, each with `n`, `from`
  (a name), `to` (as addressed: names, or `all`), its recipients (resolved when it was posted), the
  text, the time, and whether it is a report.

## 2. The size setting, and when a team is offered

A chat has the setting **`agents: {min, max}`** — the agents the team may have, the lead included.

- `1 ≤ min ≤ max ≤ cap`. `cap` is the instance's (LLeMbas) or the global configuration's (the CLI),
  default `loop.json` `team.agents.cap` (32); a project's configuration never raises it. A value
  outside is refused where it is set, with what the bounds are, never clamped silently; a stored
  setting the cap was lowered under is read as `max = min(max, cap)`, `min = min(min, max)`.
- Defaults for a new chat: `min` 1, `max` 4 (`team.agents`) — the lead and up to three members. LLeMbas
  keeps a per-person default for new chats, seeded with those; the CLI reads them from its
  configuration.
- The setting is kept with the chat. A change during a session is told to the lead as a note on its
  next user message (`context.md` §10; `context.note.team`, below), never by changing the system
  prompt.

**A team is offered** — the setting shown, the team tools listed, `blocks/team_lead.md` in the
system prompt — when both hold, and only then:

1. Subagents are enabled for the session: LLeMbas — the instance allows them and the chat's model
   has its subagent tool; the CLI — its subagents are not switched off in the configuration.
2. **The chat's model serves at least two requests at once**: `capacity.parallel ≥ 2`, or neither
   `parallel` nor `single_session` is set (a hosted API; `models/schema.json`).

Both are fixed for as long as the system prompt is (`context.md` §10, rule 4: a model switch makes
a new prompt and a new list). Otherwise the setting is not shown and none of the four tools is
listed, and the session's `task` works as before.

While the tools are listed they need **`team`** (`requires`): met when `max ≥ 2` and the model still
serves two at once — or, for the lead, when its team still has a member (so a lead whose person
lowered `max` to 1 can still talk to, read and stop the members it has). A call while it is not
met answers, word for word, `team.unavailable.one_request` when the model's capacity no longer
allows a team (its metadata changed after the prompt was made), else `team.unavailable.one_agent`
— which is also the tools' own `unavailable` text.

The meaning of the setting:

- **`max = 1`**: one agent, no team, and no helper of any kind: `task` answers `one_agent` too
  (while the lead has no member; with members left from a larger setting, `full`).
- **`min ≥ 2`**: the lead works through a team from the start — it is a manager before its first
  member (§6), and the note asks for at least `min − 1` members.
- **`min = 1`, `max ≥ 2`**: the lead decides; a small job it may do alone. Once it has a member it is
  a manager.

## 3. Size, and what counts

**The size** of a team is: the lead, every member (whatever its state — a finished member can be
woken by a message, so it keeps its place), and every `task` helper running in the team, started by
any agent in it (the CLI's background `task` jobs and foreground ones alike, while they run).
A stopped member does not count: stopping is how room is made.

- **`team_add` is refused past `max`** — when the size would become more than `max`, with
  `team.texts.full`. So is `task`, while a team is offered: with `full`, or with `one_agent` when
  `max` is 1 and the lead has no member. A `job_send` that would start a finished background
  `task` helper again is refused the same way.
- **Lowering `max` stops nobody.** Members already there stay; nothing new is added until the size
  is under the new `max`.
- The size is across **the whole tree**: a member that leads adds within the same `max` as the lead.

## 4. Members

- `team_add` starts the member **at once, in the background**, under the caller: the existing job
  machinery (a hidden chat on LLeMbas with its `chat_jobs` row, a subagent job in the CLI), running
  unattended — no `ask_user`, the chat's own permission ceiling, its mode no looser than its
  manager's (`permission/modes.json`).
- **Its agent** is `general` (the default: it does the work) or `explore` (read-only); `model` is
  as `task`'s — a model the person may use, the default being the caller's.
- **Its tools** are those its agent gives a subagent, plus `team_send` and `team_read`; one added
  with `lead: true` also has `team_add` and `team_stop`. They are fixed when it is made (§10 rule 4:
  a subagent's narrowing). `report` (`offered: subagent`) sends its manager a message before its
  final reply: posted in the room to the manager, delivered with the message mark.
- **Its system prompt** is built once, when it is added: what a subagent of that agent gets, with
  `blocks/team_member.md` in place of `blocks/subagent.md` — its name, role, manager, the team's
  goal, the agent's own instructions, and for one with `lead: true` the whole of
  `blocks/team_lead.md`. Its first user message is its brief (`task`), as given.
- **The team's goal** is what a member is told the team is for: the `goal` the caller gave in
  `team_add`, else the caller's own goal. The lead's own goal is the last `goal` it gave; **the
  lead's first `team_add` must give one** (`team.texts.no_goal`). A member already working keeps the
  goal it was told; a new goal reaches it only as a message.
- **`team_add`'s refusals are checked in this order**, the first that applies answering:
  `unavailable` (§2); `all_name` (the name `all`); `bad_name` (not `team.names.pattern`); `taken`
  (the name of an agent on the team, `lead` included); `no_goal`; `full`. Then the member is added:
  `added`, or `added_waiting` when it has to wait for a slot (§8). An unknown `agent` or `model`
  answers as `task` does.
- **Members are not jobs to the model.** `job_list` does not show them and the `job_*` tools do not
  take them; the team tools do. (An implementation may run them on its job machinery.)
- **States**: `working` (a turn is running), `waiting` (it has work, and waits for a slot, §8),
  `finished` (its last turn ended; it can be woken). The lead is `working`, `waiting` or `idle`.
- A member's background commands stop when its turn ends (`loop.json` `jobs.lifecycle`). Deleting
  the lead's session stops the whole team.

## 5. The room: who receives what

- **`team_send`** posts one message: `to` a list of names, or `["all"]` (a lone string is read as a
  one-name list). Names are deduplicated, kept in the order given. `all` anywhere in the list means
  all, and the other names in it are ignored.
- **Recipients**: for named agents, exactly those named; for `all`, every agent of the team but the
  sender — the lead and every member, whoever manages them (the room is one channel for the whole
  company). Resolved when the message is posted: an agent added later does not get it.
- **Refused, and nothing posted**, checked in this order: `all` when nobody else is on the team
  (`nobody`); a name that is not on the team (`unknown`, the first such name in the order given);
  the sender's own name among them (`self`). The answer when
  posted: `team.texts.sent`, `to` as addressed.
- **What an agent receives** is only what is addressed to it, by name or as `all`, and — a manager
  — **the reports of its own members**. A manager is not sent its members' messages to each other;
  it reads them with `team_read`, on demand, so nothing floods its context.
- **A report**: a member's final reply, when its turn ends, is posted to its manager (`report`
  true) and delivered to it. An empty reply reads `team.texts.no_report`; a turn that ended
  otherwise than by the model stopping adds `team.texts.ended` (`steps`, `budget`, `error — <text>`),
  after a blank line. A sub-manager's final reply is likewise its report to its manager.
- **The person's** messages go to the lead as its user messages, not into the room; the lead's
  answers to the person are not room messages either. The person sees the whole room and the tree
  in the UI (LLeMbas: the Team panel; the CLI: `/team`), and can stop a member there — said to the
  lead as a note (`context.note.team_stopped`).
- **`team_read`** answers the tree — every agent, the whole team, in tree order: name, role, its
  manager, state, model, last activity — and the room's messages numbered above `since` (default 0)
  that the caller may see, oldest first, at most `team.read_max` (50), and how to read on. **Who may
  see a message**: the lead every one; any other agent those whose sender or one of whose recipients
  is in its subtree — for a member that leads nobody, what it sent and what it received.

## 6. A manager does not do the work

A manager's **work** calls are refused, before the permission check — nothing is asked — with
`team.texts.manager`, word for word:

> You lead a team: give this to a member (team_add or team_send).

**Work** is a call whose risk class (`risk`; an MCP tool's: `read` when it says `readOnlyHint`, else
`execute`) is `write` or `execute`, with two exceptions that stay a manager's:

- `job_stop` — managing what runs is not work;
- a `bash` call **the default rules alone allow in manual mode** (`permission/defaults.json`, the
  `permission` conformance area's evaluation with no rules of the person's): reading commands —
  `git status`, `git diff`, `cat`, `ls`, `grep` — for review.

So with the spec's tools: **refused** — `write`, `edit`, `multiedit`, `apply_patch`, `mkdir`, `mv`,
`rm`, `skill_manage` (write); `bash` beyond reading, `python`, `commit`, `branch`, `pr`, `merge`,
`tag`, `release` (execute); an MCP tool that does not say it only reads. **Kept** — every `read`
tool (`read`, `glob`, `grep`, `list`, `search`, `recall`, `web_search`, `web_fetch`, …), every
`interact` tool (`ask_user` for the lead, `plan_*`, `task`, `memory`, `show`, `job_send`, `report`,
the team tools, …) and `job_stop`. `team.work` lists the same, and a new tool is placed by its risk
class.

**The tool list does not change** when an agent becomes a manager (`context.md` §10, rule 4): the
same tools are listed and the refused ones answer the refusal. An agent is a manager while it has
a member — a finished one included; one whose members were all stopped is not, unless it is the
lead and `min ≥ 2` with the team offered. `task` stays: a one-off helper is delegation, and counts
toward the size (§3).

## 7. Delivery, and waking

A message or a report reaches its recipient **as a marked message** — the jobs mechanism
(`loop.json` `jobs`): while the recipient's turn runs, as a user message at its next step boundary
(which does not start a turn: `context.md` §8); otherwise it **wakes** the recipient — a finished
member, or the idle lead — as a new turn of its own, marked `machine`, with its context intact, as
`job_send` restarts a finished helper. A woken agent needs a slot (§8). Several waiting at one step
boundary go in one user message, in room order, separated by a blank line.

Every one begins with its mark, on a line of its own, then the text:

```
[Team message from parser to lead:]
The grammar is done; the tests are next.
```

- message: `[Team message from {{from}} to {{to}}:]` — `to` as addressed: the names joined with
  `, `, or `all`; the same for every recipient.
- report: `[Team report from {{from}} to {{to}}:]` — `to` the manager.

A session that is not open keeps them until it is resumed, as a job's note.

## 8. Capacity: a member waits for a slot

A model serves `parallel` requests at once (`models/schema.json`). **An agent holds a slot of its
model while its turn runs** — the lead, a member, a `task` helper. An agent with work (added, woken,
given a message while finished, the lead given the person's message) starts when its model has a
free slot and none of its `capacity.group`'s other models is busy; otherwise it is `waiting`.
`team_add` is never refused for capacity (only for size): its answer says the member waits.

Waiting agents start **in order**: the lead first (the person waits on it), then the others in the
order they began waiting. A slot frees when a turn ends or an agent is stopped. `task` keeps its own
rule (`loop.json` `capacity`: refused where its model is full), and its helper holds a slot.

## 9. Stopping

`team_stop` stops one member **and its whole subtree**, or with `all` every member under the caller:
their turns stop where they are, their background commands with them, messages waiting for them
are dropped, and they **leave the team** — the size drops, their slots free, their names may be
used again. No report comes back from a stopped member. Refused, in this order: `all` with nobody
under the caller (`nobody_to_stop`); a name not on the team (`unknown`); the caller itself or an
agent not under it (`not_yours`). The answer, `stopped`, names the stopped in tree order.

## 10. What the lead is told

- `blocks/team_lead.md` — constant, no numbers — is in the system prompt whenever the team tools
  are listed: how to lead.
- The size is in a **note** (`context.md` §10, `context.note`): on the first user message of the
  session, and on the next one after the setting changed — `team` (`min`, `max`), with `team_lead`
  after it when `min ≥ 2` (`members` = `min − 1`); when `max` is 1, `team_one` instead. One block.
  A member the person stopped is its own block, `team_stopped`, with the names. Members are told
  nothing of the size: `team_add`'s answer says how big the team is.

## 11. Over the link

An agent chat's team runs on the device, as its jobs do. Spec 3.2.0 does not carry the room over
ACP yet: a device with the `jobs` capability reports each member as a subagent job (`job` events,
`description` being `<name>: <role>`), so the client's job strip shows them, and the room is shown
on the device (`/team`). Carrying the room is a later spec's.