> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/conversations-and-orchestration/group-conversations.md).

# Group Conversations

> Multi-agent structured discussions with moderator synthesis.

## Overview

Group Conversations enable multiple agents to discuss a question. Each agent participates through its normal pipeline — agents are group-unaware by default. A `GroupConversationService` orchestrates the discussion through configurable phases.

## Discussion Styles

| Style            | Flow                                                           | Best For                                          |
| ---------------- | -------------------------------------------------------------- | ------------------------------------------------- |
| `ROUND_TABLE`    | Opinion × N → Synthesis                                        | Brainstorming, open-ended exploration             |
| `PEER_REVIEW`    | Opinion → Critique → Revision → Synthesis                      | Code review, document review                      |
| `DEVIL_ADVOCATE` | Opinion → Challenge → Defense → Synthesis                      | Risk assessment, stress-testing                   |
| `DELPHI`         | Anonymous rounds → convergence → Synthesis                     | Forecasting, reducing groupthink                  |
| `DEBATE`         | Pro → Con → Rebuttals → Judge                                  | Trade-off analysis, comparisons                   |
| `TASK_FORCE`     | Plan → Execute → Verify → Synthesis                            | Structured task decomposition, parallel execution |
| `NEGOTIATION`    | Positions → Proposals → Bargaining → (Arbitration) → Synthesis | Surfacing trade-offs, drafting compromises        |
| `CUSTOM`         | Define your own phases                                         | Any workflow                                      |

## Quick Start (MCP)

```
# 1. Discover available styles
describe_discussion_styles

# 2. Create a group
create_group(
  name="Architecture Review",
  memberAgentIds="expert-1,expert-2,expert-3",
  memberDisplayNames="Backend Expert,Frontend Expert,DevOps Expert",
  moderatorAgentId="moderator-agent",
  style="PEER_REVIEW"
)

# 3. Run a discussion
discuss_with_group(groupId="<id>", question="Should we use microservices?")
```

## Quick Start (REST)

```bash
# Create group config
curl -X POST /groupstore/groups \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Architecture Panel",
    "members": [
      {"agentId": "expert-1", "displayName": "Backend Expert", "speakingOrder": 1},
      {"agentId": "expert-2", "displayName": "Frontend Expert", "speakingOrder": 2}
    ],
    "moderatorAgentId": "moderator-agent",
    "style": "ROUND_TABLE",
    "maxRounds": 2
  }'

# Start discussion
curl -X POST /groups/<groupId>/conversations \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the best architecture for our new service?"}'
```

**Save-time limits** (a config over any of them is rejected with `400`): at most 100 members, `maxRounds` at most 50, `maxTurns` at most 1000, `maxReworks` 0 to 5.

**One agent, one seat.** A member is addressed everywhere by its `agentId` — its member conversation, display name, vote weight, `participants` lists and the facilitator all key on it — so listing the same agent twice does not give the group two panelists: both seats would speak through *one* member conversation, and the "independent" second answer would read the first as its own history. A group config that repeats a member (same `agentId`, whatever the member type — the runtime keys every seat by the id alone) is rejected, naming both positions: REST `POST`/`PUT /groupstore/groups` answer **`400`**, and the MCP tools `create_group`, `update_group` and `create_group_from_template` return the same message as a JSON error payload (`{"error": "<tool> failed: members[1] repeats members[0] …"}`) — MCP tool calls have no HTTP status of their own. For a second seat with the same behaviour, duplicate the agent and add the copy. A group **already stored** with a repeated member still loads: each repeat is dropped on read — the first seat wins, with its display name, role and speaking order — and a warning is logged; saving the group once stores the cleaned list. One case needs a roster change first: if the dropped seat held a role a preset style is built on — typically one agent seated as both `PRO` and `CON` in a `DEBATE` — the save is refused with the ordinary role message naming the missing role (that group never had two sides; one conversation argued both). The warning logged on read names the dropped role; put a second agent in that seat and save.

## Member Roles

Some styles require specific roles. A preset `DEBATE` group without at least one `PRO` and one `CON` member, or a preset `DEVIL_ADVOCATE` group without a `DEVIL_ADVOCATE` member, is rejected at save time — the engine would otherwise fall back to ALL members and the style would silently become something else. (Groups with explicit `phases` route roles themselves and are not checked.)

| Role             | Used By               | Purpose                  |
| ---------------- | --------------------- | ------------------------ |
| `DEVIL_ADVOCATE` | DEVIL\_ADVOCATE style | Argues against consensus |
| `PRO`            | DEBATE style          | Argues in favor          |
| `CON`            | DEBATE style          | Argues against           |

```
create_group(
  name="Debate Panel",
  memberAgentIds="agent-a,agent-b",
  memberRoles="PRO,CON",
  moderatorAgentId="judge-agent",
  style="DEBATE"
)
```

### Debate verdicts

When a DEBATE has **two sides and an impartial judge** — i.e. members carry at least two distinct roles *and* `moderatorAgentId` names an agent that is not one of the debaters — the judgment phase returns a structured verdict alongside its prose, on the conversation's `decision` field:

```json
"decision": {
  "type": "VERDICT",
  "winner": "CON",
  "tally": { "PRO": 4.0, "CON": 9.0 },
  "outcome": "CON wins (PRO 4/10, CON 9/10) — PRO asserted; CON cited.",
  "method": "debate-judgment",
  "decidedAtPhase": "Judgment",
  "dissents": []
}
```

`winner` is `null` for a tie (the tie is stated in `outcome`). The judge is asked to score argument quality and factual support, and explicitly *not* assertiveness or fluency.

Any of these leaves `decision` unset and the conclusion as ordinary prose — none of them is an error:

* **No roles on the members.** Nothing argued PRO, so a PRO-vs-CON score would be invented rather than measured.
* **No moderator.** The stand-in synthesizer is one of the debaters, and a partisan's call is not the group's finding.
* **A phase `inputTemplate` of your own.** Your instruction wins; set one if you want a debate to conclude in plain prose.
* **A judgment the parser cannot read.** The prose conclusion is kept as-is.

## Agent-filed tasks

Work an agent *discovers* mid-discussion — a missing migration, an untested edge case — would otherwise die in prose: the shared task list is written only by the PLAN phase and by config. Turning on `taskListConfig` gives members two tools, `addGroupTask` and `listGroupTasks`, and a filed task is picked up by the next execution wave with no other changes.

```json
"taskListConfig": {
  "allowAgentTaskCreation": true,
  "maxAgentAddedTasksPerDiscussion": 20,
  "maxPerTurn": 3
}
```

**Off by default, and absent rather than refusing when off.** A tool that is not assembled costs no prompt tokens and cannot be argued with; one that exists and always says no invites retries. The tools appear only when the turn belongs to a live group discussion whose config sets `allowAgentTaskCreation: true` — a standalone agent, a paused discussion, or an unreadable config all yield no tools.

`addGroupTask(subject, description, dependsOnSubjects?, priority?, assignToRole?)`

* **`dependsOnSubjects`** names other tasks by their *subject*, as `listGroupTasks` prints them. An unknown name is refused, not dropped — silently filing a task without its dependency schedules it immediately, which is the opposite of what was asked.
* **`assignToRole`** takes `"ROLE:Reviewer"` or a member's exact name, and files the task already assigned. Omitting it (or passing `"ALL"`) round-robins the task to the next member through the same resolver the PLAN phase uses — every filed task gets an owner, and filing is refused outright if the team has nobody to own it. An unmatched role is refused with the available roles named.
* Refusals are sentences aimed at the model: duplicate subject, unknown dependency, circular dependency, subject over 200 chars, description over 4,000, and either cap being reached.

Both caps are enforced independently: `maxPerTurn` bounds a runaway single turn, `maxAgentAddedTasksPerDiscussion` bounds slow drift across a long discussion. The discussion cap counts only agent-filed tasks, so a large planned backlog does not exhaust it. It counts what members file with the task tool in this discussion, not tasks the run starts with, so a standing team's backlog task another team's agent handed off does not count although the run keeps that agent as its creator (see [Signed contributions](#signed-contributions)). A rejected call does not consume the per-turn budget.

**No claim or complete tools.** The wave loop owns every task-state transition; a second writer racing it would corrupt the state machine that decides what runs next. Filing is the only agent-side write.

## Transcript windowing

A `FULL`- or `ANONYMOUS`-scope discussion phase re-feeds the transcript to every member every turn, so a long discussion grows roughly quadratically in prompt tokens. `contextWindow` bounds what each turn *renders* — the stored transcript is never modified, and [peer verification](#signed-contributions) still runs on the raw entries:

```json
"contextWindow": {
  "enabled": true,
  "maxRecentEntries": 30,
  "summarizeOverflow": true,
  "llmProvider": "openai",
  "llmModel": "gpt-4o-mini",
  "inputPricePer1M": 0.15,
  "outputPricePer1M": 0.60
}
```

When the scope-filtered context exceeds `maxRecentEntries`, the older entries collapse into a single leading block: a rolling **summary** (extended incrementally at phase boundaries via the shared summarization service — never per member turn), or, with `summarizeOverflow: false`, a plain `[n earlier entries omitted]` marker that costs no LLM call. A summarization failure never blocks the discussion — the turn renders with the truncation marker and the next boundary catches up.

* Applies to `FULL` and `ANONYMOUS` scopes only. The `ANONYMOUS` variant keeps its own summary, built from the same `"Anonymous"` labels the scope filter produces — the summary can never de-anonymize a peer.
* `llmProvider`/`llmModel` name the summarizer; without them, overflow falls back to the truncation marker (a save-time warning says so).
* The optional prices attribute the summarizer's own spend to the discussion's cost ledger, where `maxCostPerDiscussion` sees it — and it is charged to the tenant's monthly budget like any other spend ([Model Pricing](https://docs.labs.ai/agent-configuration/model-cascade/model-pricing.md#for-other-features-spend-attribution)).
* The convergence judge's input is not windowed — it is already bounded to the last two rounds.

## Member stances (the overview dashboard)

The Manager and the Workforce board can render a discussion as an **overview** instead of a transcript — a phase rail, a members x phases matrix, and a roster of one-line positions. The roster's lines are *member stances*, and they always exist: by default each is the **lead sentence of that member's newest contribution**, which costs nothing and is the member's own words.

`stanceSummary` upgrades that to an LLM summary of everything the member has said:

```json
"stanceSummary": {
  "maxChars": 160,
  "llmProvider": "openai",
  "llmModel": "gpt-4o-mini",
  "inputPricePer1M": 0.15,
  "outputPricePer1M": 0.60,
  "maxInputChars": 8000,
  "maxEntryChars": 2000
}
```

* **The summarizer's input is bounded.** It reads the member's **newest** contributions within `maxInputChars` (default 8,000, ceiling 32,000), each cut to `maxEntryChars` (default 2,000, ceiling 8,000), with an `[N earlier contribution(s) omitted]` marker — a stance is where the member stands now, and the whole history re-sent at every boundary eventually overflows the summarizer's context window. Non-positive values take the default.
* **There is no `enabled` flag**, unlike `contextWindow`. Stances exist either way, so the only thing a flag could have meant is "may this spend money?" — which is already what naming a provider and a model means.
* Stances are recomputed at **phase boundaries**, and only for a member whose stored stance no longer covers **their own** contributions. A member who stayed silent through a phase costs nothing — coverage is counted per member, not against the transcript length, or one member speaking would re-bill everyone.
* The summarizer is **optional spend and obeys `maxCostPerDiscussion`**, like the window summarizer and the convergence judge. Past the ceiling it downgrades to extraction rather than stopping the phase.
* A summarizer failure **degrades to lead-sentence extraction**, never to a blank roster, and never fails the discussion.
* The UI distinguishes the two producers — an extracted line is shown as a quotation, a generated one as a summary — because presenting a paraphrase the way a quotation is presented would misattribute it.
* Extraction skips the entry types that carry a **JSON contract** (`VOTE`, `BID`, `RETRO`, `PLAN`, `TASK_RESULT`, `VERIFICATION`) and quotes the newest prose entry instead — the lead "sentence" of a ballot is an opening brace, and it would otherwise replace a member's real position after every vote. The LLM summarizer still reads them.
* The optional prices attribute stance spend to the same cost ledger `maxCostPerDiscussion` bounds, under a `system:stance:*` key.
* Naming only one of `llmProvider`/`llmModel` (or prices with neither) produces a save-time warning: that config intends to spend and silently will not.

Both surfaces stream two events for this view: `cost_updated` after every cost attribution (carrying the key's *cumulative* spend, so a redelivered frame is idempotent) and `stance_updated` whenever a stance's text changes.

## Voting

A `VOTE` phase collects **explicit ballots** instead of another round of prose. LLM ballots are correlated (shared priors, sycophancy) — the durable value is the auditable artifact: the weighted tally, every raw ballot, and the losing side's statements recorded as dissents on the `DecisionRecord`.

```json
{
  "name": "Ballot", "type": "VOTE",
  "turnOrder": "PARALLEL", "contextScope": "NONE",
  "voteConfig": {
    "method": "MAJORITY",
    "optionsSource": "EXPLICIT",
    "options": ["Adopt PostgreSQL", "Stay on MongoDB"],
    "quorum": 0.5,
    "weights": { "senior-architect": 2.0 },
    "weightByConfidence": false,
    "tiePolicy": "MODERATOR_DECIDES"
  }
}
```

**Independence is enforced structurally, not advised.** Save-time validation rejects a VOTE phase that is not `PARALLEL` + `contextScope: NONE`; ballots are cast blind against the pre-fan-out snapshot, and `VOTE` entries stay peer-hidden until their phase completes (commit-reveal).

* **Ballot contract:** `{"vote": "<exact option text>", "confidence": <0..1>, "statement": "..."}` (`APPROVAL` uses `"votes": [...]`). Three-tier parse: strict JSON → JSON embedded in prose → a reply naming exactly one option's text. Anything else is a non-ballot and **counts against quorum** — as do abstentions; a mostly-silent team has not reached quorum, and that is signal.
  * **Only what was cast counts.** For a JSON ballot, only the `vote`/`votes` values are read, never the free-text `statement`. A cast in a shape the method did not ask for still counts when it names exactly one option (the approval array `{"votes": ["X"]}` under `MAJORITY`, a string `"votes": "X"` under `APPROVAL`).
  * **An empty ballot is a non-vote.** `"votes": []`, `"vote": null` or a JSON ballot with no vote field at all counts against quorum — even if its statement mentions an option.
  * **Options are matched as words.** In prose ballots (and the moderator's tiebreak reply) an option must appear as a whole word or phrase, case-insensitively: option `No` is not found inside "not" or "know". The boundary applies only between words of scripts written with spaces — in Chinese, Japanese, Thai and similar scripts a plain substring match is used, so "我支持方案A。" is a vote for `方案A`.
* **Options:** `EXPLICIT` is the reliable path. `LAST_SYNTHESIS` extracts `Option A: …` lines from the newest synthesis — instruct that synthesis to emit them (the default synthesis prompt does not). The line may be written the way models write it: `**Option A:** …`, `- Option B: …`, `1. Option C) …`, `Option D. …`, in any letter case.
* **Ties and quorum failures** go to `tiePolicy`: `MODERATOR_DECIDES` runs one moderator turn choosing among the unresolved options (method `vote+moderator-tiebreak`); `NO_DECISION` (default) records an honest `type: NONE` and the discussion continues. `HUMAN_DECIDES` pauses the discussion until a named person picks one of the tied options (method `vote+human-tiebreak`) — see [Group Human Decisions](https://docs.labs.ai/conversations-and-orchestration/group-conversations/group-human-decisions.md#tie-breaks).
* The result fires the `decision_reached` SSE event (which this feature also wires for debate verdicts) and renders a tally block in Slack.

## Humans as group members (I6)

Real deployments are hybrid teams: a `memberType: "HUMAN"` member sits in the roster like any agent, but their turn **pauses the discussion** (`AWAITING_HUMAN_INPUT`) until they answer.

```json
{
  "members": [
    { "agentId": "agent-1", "displayName": "Analyst", "speakingOrder": 1 },
    { "agentId": "gregor@example.com", "displayName": "Gregor", "speakingOrder": 2, "memberType": "HUMAN" }
  ],
  "humanMemberConfig": { "turnTimeout": "PT4H", "onTimeout": "SKIP_TURN" }
}
```

* The human's `agentId` is their **principal id** — the identity that may submit their turns; `displayName` is required at save time.
* Their prompt is rendered exactly like an agent's and persisted on the conversation (`pendingHumanInput.renderedPrompt`); the `human_input_requested` SSE event (and a Slack notice) says who is up.
* Submission: `POST /groups/{groupId}/conversations/{id}/human-input` `{memberId, content}` or MCP `submit_group_human_input`. **Only the member's own principal (or an admin) may submit** — an `eddi-approver` may decide approvals, but speaking as another human is impersonation, not review. The answer is recorded as the phase's natural entry type (a human OPINION is an OPINION) and the discussion resumes from the next speaker. The response is the group conversation for its owner or an admin; any other submitter (the member themselves) gets `{groupConversationId, accepted, state}` — submitting a turn does not grant the full view the status endpoint withholds from them.
* This is deliberately NOT the approval surface: approve/reject endpoints never accept free text, and the pending-approvals inbox marks these entries `pauseType: "HUMAN_TURN"` with the member's id, so a human sees their own pending turns without owning the conversation.
* **Timeouts** (`humanMemberConfig`): `turnTimeout` (ISO-8601; unset = wait indefinitely) with `onTimeout: SKIP_TURN` (a SKIPPED entry — "no response from within " — and the discussion moves on) or `ABORT` (graceful cancel). Timeout schedules survive restarts via the HITL crash-recovery sweep.
* **PARALLEL phases**: agents fan out first; humans are then prompted one at a time against the *pre-fan-out* snapshot, so an independent round stays independent — a human answering after the agents cannot read their answers.
* **In Workforce** the board shows the pending turn with its rendered prompt and a box to answer ([Workforce guide](https://docs.labs.ai/protocols-and-integration/workforce-guide.md#a-team)). It says "It's your turn" to the member and whose turn it is to anyone else, and a refused submission (`403`) is explained in those words. The client compares the signed-in username or e-mail with the member's `agentId` only to choose the wording; whether a submission is accepted is the server's check above.
* **Task forces**: a HUMAN member may execute task-force tasks it is explicitly assigned — one pause per task, after the agents' waves — but may not plan or verify; see [Group Human Decisions](https://docs.labs.ai/conversations-and-orchestration/group-conversations/group-human-decisions.md#humans-as-task-force-executors).
* **Bounds (save-time rejected)**: no HUMAN members in `targetEachPeer` phases, a group containing humans cannot be nested as a GROUP member, and a HUMAN planner/verifier is refused in a group with PLAN or VERIFY phases. A human **moderator** is otherwise allowed — every synthesis then waits on that person (the save warns about it).

## Facilitator with bounded moves (I12)

Orchestration is static choreography; nothing reacts ("we've agreed — stop", "we need a specialist — recruit"). A full LLM orchestrator conflicts with deterministic governance, so the facilitator chooses among **config-enumerated moves** — validated, capped, audit-logged:

```json
{
  "facilitator": {
    "enabled": true,
    "agentId": "facilitator-agent",
    "allowedMoves": ["CONTINUE", "CALL_VOTE", "ESCALATE_HUMAN"],
    "checkAfter": "EACH_PHASE",
    "maxMovesPerDiscussion": 10,
    "escalateTo": "gregor@example.com"
  }
}
```

At each checkpoint (`EACH_PHASE` default, or `EACH_REPEAT`) the facilitator agent receives a **compact briefing** — phase/repeat position, budget arithmetic, roster, entry counts, capped excerpts, *never the full transcript* — and replies `{"move", "args", "reason"}`. Moves v1:

* `CONTINUE` — the ambient no-op and every failure's fallback. Silent.
* `END_PHASE` / `EXTEND_PHASE` — skip the remaining repeats / add one (≤2 extensions per phase, still bounded by `maxTurns`). They act mid-phase, so the save **rejects** them unless `checkAfter: EACH_REPEAT`. A convergence exit is never overruled.
* `CALL_VOTE` — inserts a one-off VOTE phase next (`args.options`, 2–10), built to I14's enforced PARALLEL+NONE shape by construction.
* `RECRUIT` — brings a deployed agent in (`args.agentId`), the same validation path as I7's `recruitAgent` tool.
* `ESCALATE_HUMAN` — pauses the discussion (`AWAITING_HUMAN_INPUT`) for the configured `escalateTo` principal with the facilitator's question, riding I6's pending-input machinery whole; the answer records as a peer-visible `FOLLOW_UP` and the discussion resumes.

**Bounds and honesty.** The consult itself is a real LLM turn (counted, cost on the I1 ledger, skipped once either budget is gone). Executed non-CONTINUE moves are capped by `maxMovesPerDiscussion` (default 10) and each lands as a peer-hidden `FACILITATION` entry + audit event + the `eddi_group_facilitator_moves_total{move,outcome}` counter. Anything unparseable, disallowed or invalid-in-context degrades to CONTINUE **and is recorded as a rejected attempt** — the audit trail must show the model tried. Facilitator failure never fails a discussion.

**Runtime phase divergence.** CALL\_VOTE and EXTEND\_PHASE mutate a runtime copy of the phase list, persisted on the conversation (schema v4). Every resume path — approval, human turn, timeout skip — executes and drift-checks against that list, so a pause taken inside an inserted phase resumes correctly. The divergence is one-off: completion (and every new round) starts from the config again.

## Negotiation (I11)

EDDI's other decision forms are win/lose; `NEGOTIATION` is the **trade** form — a process for surfacing trade-offs whose output is a drafted compromise with an explicit **concession ledger** for human sign-off.

The preset: ① *Positions & Interests* (parallel, context-free — interests enable integrative trades) ② *Opening Proposals* ③ *Bargaining* (repeats = `maxRounds`, exits early on agreement) ④ *Arbitration* (moderator; **skipped entirely** when an agreement was reached — `skipIf: "AGREEMENT_REACHED"`, the single deterministic skip condition) ⑤ *Synthesis*.

* A **BARGAIN** turn is a typed move: `{"accept": "<proposalId>"|null, "proposal": {"terms": "..."}|null, "concessions": [{"gaveUp": "...", "inReturnFor": "..."}]}` plus free-text reasoning. Three-tier parse; an unreadable turn is prose with no state effect.
* The typed structure is the anti-sycophancy mechanism: an acceptance must name a specific proposal id, a concession that names nothing in return is **not recorded**, and the open proposals + ledger are quoted into every turn — the record the outcome will cite.
* A new proposal supersedes the mover's own open one (one live offer per agent); the proposer signs their own terms implicitly.
* **Agreement** = every non-moderator participant signed the same open proposal. The bargaining phase ends its repeats early and the conversation carries `decision: {type: "AGREEMENT", method: "negotiation"}` whose `tally.signedAcceptances` maps each signatory to the transcript index of their signed acceptance entry — the (already signed) entries are the co-signatures; no new crypto.
* No agreement → the arbitration runs and its conclusion becomes `decision: {type: "VERDICT", method: "arbitration"}`.
* **The ledger is bounded** — it is an LLM write surface quoted into every later turn. One BARGAIN turn records at most `maxConcessionsPerMove` concessions (default 5, ceiling 20; each side of a concession is stored truncated to 600 characters), the ledger stops at `maxLedgerConcessions` (default 50, ceiling 500 — the earliest are kept, they are the record the outcome quotes; further concessions are not recorded but counted, and the agreement outcome says "N further concession(s) not recorded (ledger full)" and carries `tally.concessionsNotRecorded`), and a turn's prompt quotes only the newest `maxRenderedConcessions` (default 20, ceiling 100) with an "(N earlier concession(s) omitted)" line. `negotiationConfig` is a default, not a switch: without it the defaults apply.

```json
"negotiationConfig": { "maxConcessionsPerMove": 5, "maxLedgerConcessions": 50, "maxRenderedConcessions": 20 }
```

## Retro → group memory

A `RETRO` phase stops discussions from evaporating: the group reviews how it worked and distills lessons that persist as **team-owned group memory**, then surface as `{properties.*}` in every member's later discussions — institutional knowledge that compounds run-over-run.

```json
{ "name": "Retro", "type": "RETRO", "participants": "MODERATOR" },
"retroConfig": { "maxLessonsPerRun": 3, "maxStoredLessons": 50, "maxLessonChars": 1000 }
```

* The built-in template asks for `{"lessons": [{"lesson": "...", "context": "..."}]}`; parsing is three-tier (strict JSON → embedded JSON → nothing) and the per-run cap is enforced at parse time whatever the model produced.
* Lessons are stored under the synthetic owner `group:<groupId>` with `group` visibility — they belong to the team, not to whichever human ran the discussion, and survive that human's GDPR erasure without carrying their identity. The idempotency key `retro:<hash(lesson)>` makes re-running the same retro a no-op.
* **Bounded growth is non-negotiable:** the stored set FIFOs at `maxStoredLessons` — storing past the cap evicts the oldest, ordered by *creation* time, so re-harvesting an old lesson cannot shield it from eviction. Both caps are clamped to hard ceilings (20 per run, 500 stored) no config can exceed: an LLM-driven write surface with an operator-supplied ceiling is only as bounded as the operator's typing.
* `maxLessonsPerRun` bounds the whole harvest, not each contribution — a RETRO phase with several participants or repeats cannot multiply it.
* `maxLessonChars` (default 1000 — the same default as an agent's `memoryGuardrails.maxValueLength`; ceiling 4000) bounds one stored lesson value, lesson plus its "applies:" context. Longer lessons are truncated, the context first; the idempotency key still hashes the untruncated lesson.
* A team's lessons can also be read by teams it agrees to share with, and merged or retired by a scheduled, cost-capped job that keeps what it removes: see [Team Learning Loop → Lessons](https://docs.labs.ai/conversations-and-orchestration/group-conversations/team-learning-loop.md#lessons).
* Member conversations already load group-visible entries at init, so recall needs no new namespace. The `retro_recorded` SSE event reports each harvest.

## Standing Teams (I13)

A group *conversation* is an episode; a **team** persists. The `GroupWorkspace` (one document per group, own collection — stored under the group's own id, so two pods creating it at once end up with exactly one, see below) holds what survives between episodes: a **backlog** (a `SharedTaskList`, so pulled tasks flow straight into the task-force machinery), **cadences** that pull from it on a schedule, and the team's running **metrics** — deliberately thin glue over the existing schedulers, I1's cost ledger and I8's retro memory.

```
POST /groupstore/groups/{groupId}/workspace/backlog   {"subject": "...", "description": "...", "priority": 5}
POST /groupstore/groups/{groupId}/workspace/cadences  {"cronExpression": "0 9 * * 1", "maxBacklogTasksPerRun": 5, "maxCostPerRun": 2.50}
GET  /groupstore/groups/{groupId}/workspace
```

`cronExpression` is a **5-field Unix cron** (`min hour day month weekday`), not 6-field Quartz — `"0 0 3 * * ?"` is rejected. The error message says so, but the example above is the one to copy.

MCP: `add_team_task`, `list_team_backlog`. The backlog caps at 200 with an actionable error — it is a working set, not an archive.

**Cadence fires ride the schedule machinery whole** (`SchedulePollerService` claim/lease/retry/dead-letter; the executor branches on `teamCadenceType: "team_cadence"` exactly like Dream consolidation). Each fire:

1. **Reconcile** — a finished previous run is written back first; one still in flight skips the fire. A run paused at an HITL gate is *not* terminal, so it holds the claim — but only up to a TTL (see **Stale claims** below).
2. **Pull** — top-N *executable* backlog tasks by priority; an empty pull skips, logged.
3. **Run** — the discussion is started first, so the claim can carry its real id. Pulled tasks are injected as a runtime copy of `config.tasks` (the stored config is never written) and the cadence's `maxCostPerRun` rides the inherited-ceiling slot: dollar-primary, per the Dream precedent. The discussion runs under the cadence *creator's* identity.
4. **Claim** — a conditional store write on `runningDiscussionId`, taken before any task turn can complete and without any in-JVM lock. Two pods firing concurrently both start a discussion; the one that loses the CAS cancels its just-started discussion before its first turn, so only one fire does work.

**Writeback** happens at the next fire (or on a workspace read — read-repair), never from inside the discussion thread, so a pod crash mid-discussion loses nothing. It also means a fire's `COMPLETED` status says the discussion was *started*, not that its tasks are done: backlog statuses change only once that writeback has run. VERIFIED outcomes stay VERIFIED on the backlog and credit the assignee's `perMemberStats`; anything else returns to PENDING with the reviewer's feedback kept for it — **the cross-run retry loop**. The next run quotes that feedback after the task's description (the workspace's `backlogFeedback`, each item with the agent that wrote it, capped at the last 8 runs per task). Once a member, the moderator or an enabled facilitator requires peer verification, a run quotes only feedback no agent wrote, or feedback that verified when it was kept from an agent that still signs verifiably; the rest is counted as withheld. Feedback a workspace from before this field appended to the description stays part of the description. A FAILED, REJECTED or CANCELLED discussion returns every pulled task untouched. Retro lessons flow through I8 unchanged (no duplication).

**Human approval as done.** A team gated by a person instead of a VERIFY phase — `hitlConfig.granularity: TASK` with a `requiresApproval` EXECUTE phase — ends each run with its approved tasks `COMPLETED`, not `VERIFIED`, so by the rule above they return to `PENDING` and the next fire runs them again (for a team that publishes, it posts the same thing twice). Set `hitlConfig.approvalCompletesBacklogTask: true` to keep them done:

```json
"hitlConfig": {
  "granularity": "TASK",
  "timeoutPolicy": "WAIT_INDEFINITELY",
  "approvalCompletesBacklogTask": true
}
```

A task a person approved then lands on the backlog as `COMPLETED` (not `VERIFIED` — nobody verified it) with the approved result, which is the approver's edit when `review.allowResultEdits` was used, and is counted in `metrics.tasksApproved` and the member's `perMemberStats.tasksApproved` rather than `tasksVerified`. Only an approval somebody gave counts: the task list records each approval's decider (`taskList.approvals`), and a timeout auto-approval (`decidedBy: system:timeout`, under `timeoutPolicy: AUTO_APPROVE`) is a decision nobody made, so its tasks return to `PENDING` as before — the same line earned-autonomy evidence draws. A task that completed in an ungated phase, or that a later VERIFY phase failed, also returns to `PENDING`. The switch defaults to `false`, so stored configs behave exactly as before; it is read from the group's current version at writeback, and an unreadable config falls back to the default (logged).

**Stale claims are reclaimed.** The default group HITL timeout policy is `WAIT_INDEFINITELY`, so a pause nobody resolves never reaches a terminal state: without a backstop the claim would be held forever, every subsequent fire skipped as "still running", and the pulled backlog tasks stuck `IN_PROGRESS`. A claim older than `eddi.groups.cadence.claim-ttl` (default `PT24H`) is reclaimed — the stranded discussion is cancelled and put through the *ordinary* failure writeback, so pulled tasks return to `PENDING` and the claim clears. Cancel happens before release, so a reclaimed run cannot keep spending against a budget nobody is tracking. Set the TTL non-positive to disable reclaiming, for an operator who would rather wedge than risk abandoning a pause; the counter is `eddi_team_cadence_claims_reclaimed_total`. Creating a cadence on a group that combines `requiresApproval` phases with `WAIT_INDEFINITELY` logs a warning — that combination is what makes the backstop reachable — but is not rejected: it is legitimate for a team whose approver really is always available.

**Monthly budget.** A team can also carry a calendar-month dollar cap, `teamBudget`, that covers its cadence runs and its ad-hoc discussions alike: a fire of a team whose budget is spent is skipped (not failed), and the run that reaches the cap finishes through the synthesis exemption when the group's cost policy is `SYNTHESIZE_NOW`; under `ABORT` it stops instead. See [Team Budgets](https://docs.labs.ai/security-and-compliance/tenant-quotas/team-budgets.md).

**Creation is atomic.** The workspace is created on first use, and that first use can happen on several pods at once (two backlog adds, a cadence fire and a read). It is written with an insert-only write under the group's id, so the database's primary key admits one creator and every other caller adopts that document. Up to 6.5.0 each creator inserted its own document and they converged afterwards on the lexicographically smallest id — which is not the first insert (ObjectIds are minted client-side, UUIDs are random), so a caller could get back a document that later reads did not elect, and a backlog task it wrote there reported success and vanished. Workspaces created by earlier releases keep their generated id and are still found by their `groupId`.

Per-member stats are reliability **recording only** — nothing routes or weights on them in v1. A *permanent* group deletion cascades to the workspace; a soft (versioned) delete keeps it, because the group can come back. Another team or a standalone agent can file tasks into a workspace: see [Cross-Team Handoff](https://docs.labs.ai/conversations-and-orchestration/group-conversations/team-handoff.md). A backlog task can be a **bet** (hypothesis, metric, review date) and a team can record the real-world **outcomes** of its work: see [Team Learning Loop](https://docs.labs.ai/conversations-and-orchestration/group-conversations/team-learning-loop.md). Not in v1: reputation weighting.

## Shared artifacts (blackboard-lite)

Without artifacts, the transcript is the only medium — every structured thing an agent produces is prose the next agent re-parses. `artifactConfig` gives members four tools to **create together**: `createArtifact(name, type, content)`, `readArtifact(nameOrId)`, `proposeArtifactUpdate(nameOrId, content, expectedVersion, markFinal?)` and `listArtifacts()`. Artifacts are typed documents (`TEXT`, `MARKDOWN`, `JSON`) in their own collection, listed on the discussion's REST/MCP status payload as `artifacts`, and announced over SSE and Slack as `artifact_updated` events.

```json
"artifactConfig": {
  "allowArtifactTools": true,
  "maxArtifactsPerDiscussion": 5,
  "validators": [
    { "kind": "JSON_SCHEMA", "spec": "{\"type\":\"object\",\"required\":[\"title\"]}" },
    { "kind": "MAX_LENGTH", "spec": "20000" }
  ]
}
```

**Concurrency is deterministic compare-and-set, not an LLM merge.** Every update presents the version it read; a stale writer is told *"artifact changed since you read it (now v3); re-read and merge your change"* and retries against fresh content. The failure mode is a retry, never a silent bad merge.

**Validators are declarative only** — `JSON_SCHEMA`, `REGEX` (content must contain a match), `MAX_LENGTH` (characters) — never code. Specs are checked at config save time; at write time a failing validator refuses the write with its message and stores nothing. Content is additionally capped at 256 KB per artifact, and `maxArtifactsPerDiscussion` at 1000 (a larger value is refused on save). A `JSON_SCHEMA` spec must be self-contained: a `$ref` may point inside the schema (`#/$defs/...`) or at a bundled JSON Schema meta-schema, never at an `http(s):`, `file:` or other external location — such a spec is refused at save time, and nothing is fetched or read.

Off by default with the same absence discipline as the task tools: no opt-in means the tools are never assembled. The member agent's own `enableBuiltInTools` switch still applies — a member whose LLM task does not set it takes part **without** the tools, and saving a group that enables artifacts, agent task creation or dynamic agents logs that prerequisite. So does its explicit tool selection: a member whose `builtInToolsWhitelist` is non-empty receives the artifact tools only if the list names `artifacts`, and the task tools only if it names `group_tasks` — a group opt-in never widens a whitelist the member's own configuration narrowed. An omitted or empty whitelist admits both, as before. When upgrading, add the two slugs to any member whitelist that should keep these tools; the Manager's tool picker offers both. Artifact, task and dynamic-agent tool results are never served from the tool cache: every member runs as the same user, so a cached `listArtifacts()` would hide a peer's new artifact. `markFinal: true` freezes an artifact — FINAL artifacts accept no further updates. Artifacts are not signed, so a member with `security.requirePeerVerification` (or whose setting cannot be read) is not given the artifact tools: they would hand it any member's text as stored ([Signed contributions](#signed-contributions)). Artifacts are deleted with their discussion (close/delete cascade) and by GDPR erasure; the durable trace of the work is the transcript.

People read artifacts in Workforce's side panel on the team board, with each version the `history` still holds (current first, then up to `ARTIFACT_HISTORY_CAP` = 10 earlier ones, each with its editor and time); the Manager's discussion view lists them too. Both are read-only, since no REST endpoint lets a person write an artifact. Content is rendered by type: MARKDOWN through the shared markdown renderer with raw HTML escaped, JSON pretty-printed, TEXT as plain text. The panel follows a running discussion through the polled status read, which carries `artifacts`; the `artifact_updated` event itself has metadata only.

## Preset Templates (I10)

Enterprises understand "research pod" and "decision board", not `contextScope: OWN_FEEDBACK`. Packaged templates ship complete, validated group configs whose member slots are **named roles** — instantiation just assigns agents (or human principals) to them and saves through the normal store path, so every save-time validation applies.

```
GET  /groupstore/templates                       → manifests (id, title, roles)
GET  /groupstore/templates/{id}                  → manifest + full config
POST /groupstore/templates/{id}/instantiate      {"name": "...", "roleAssignments": {"researcher1": "<agentId>", ...}}
```

MCP: `list_group_templates`, `create_group_from_template`. Missing or unknown roles fail loudly, naming the template's real roles. The group is saved through the normal store path, so an assigned agent you may not use is refused there, exactly as for a hand-written config: `403` over REST, and `"errorCode": "FORBIDDEN"` from the MCP tool.

| Template            | Style               | What it packages                                                                                                                          |
| ------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `research-pod`      | DELPHI-style CUSTOM | Blind estimates → anonymous convergence rounds (I2) → synthesis → retro into team memory (I8), windowed context (I9), dollar ceiling (I1) |
| `editorial-team`    | CUSTOM              | Writer drafts a shared artifact (I17), editors propose CAS-guarded updates, dissents recorded (I4)                                        |
| `ops-task-force`    | TASK\_FORCE         | Bid-based assignment (I18), agent-filed tasks (I5), specialist recruitment (I7), ceiling                                                  |
| `decision-board`    | CUSTOM              | Hybrid board with a HUMAN director (I6) deliberating and voting (I14); options distilled by the chair, ties to the chair                  |
| `negotiation-table` | NEGOTIATION         | Typed two-party bargaining with concession ledger (I11); the arbiter role may be a human principal                                        |

## Attachments

A discussion can carry shared files. `POST /groups/{groupId}/conversations` (and the `/stream` variant) accepts an `attachments` array alongside `question`, in two shapes — hosted (`mimeType` + `url`) and inline (`mimeType` + `data`, optionally `fileName`):

```json
{
  "question": "Review the attached architecture proposal.",
  "attachments": [
    { "mimeType": "application/pdf", "url": "https://example.com/proposal.pdf" },
    { "mimeType": "image/png", "fileName": "diagram.png", "data": "iVBOR..." }
  ]
}
```

Inline `data` is stored in the blob store owned by the group conversation, so it is granted to members and reaped with the conversation. Hosted `url` references pass through as-is. A ref carrying neither is skipped, as is a `url` ref with no `mimeType`.

**How members receive them.** On a member's **first** turn the orchestrator grants that member's private conversation access to the group's blobs and injects them as `attachment_*` context — from there the ordinary single-agent attachment path applies (multimodal forwarding for vision models, PDF/text extraction otherwise). On **later** turns the member's own conversation history carries them: `AttachmentForwarder` notes the earlier attachments and the `readAttachment` tool is auto-enabled for any conversation that has them, independently of `builtInToolsWhitelist`. A recruited member gets the same grant on its own first turn, and a nested `GROUP` member propagates the whole set down.

**Bounds worth knowing:**

* The per-turn forwarding cap (`eddi.attachments.max-per-turn`, default 5) applies to each member turn. A discussion sharing more than that will have the surplus dropped for that turn, reported in the member's `attachments:errors` — visible in that member's conversation, **not** in the group transcript.
* `url`-only attachments are not blob-backed and are not re-hydrated after a HITL resume; blob-backed ones are.
* Inline files are held to the 1:1 limits — `eddi.attachments.max-size-bytes` per file, `max-per-conversation` and `max-total-bytes-per-conversation` per discussion, and the owner's per-user quotas — and a refusal answers `400` before the discussion runs. Deleting the discussion deletes its blobs.

## Nested Groups (Group-of-Groups)

Members can be other groups. The sub-group runs its own discussion and its synthesized answer becomes the member's response.

```
# Create sub-groups
create_group(name="Team A", memberAgentIds="a1,a2", style="PEER_REVIEW")  → g1
create_group(name="Team B", memberAgentIds="a3,a4", style="DEBATE")       → g2

# Create meta-group with GROUP members
create_group(
  name="Tournament",
  memberAgentIds="g1,g2",
  memberTypes="GROUP,GROUP",
  moderatorAgentId="judge-agent",
  style="ROUND_TABLE"
)
```

Depth tracking prevents infinite recursion (`eddi.groups.max-depth`, default: 3). A group that would contain itself through its GROUP members (directly or via other groups) is rejected when it is saved.

## Custom Phases

For full control, define phases directly:

```json
{
  "name": "Custom Panel",
  "style": "CUSTOM",
  "phases": [
    {
      "name": "Independent Opinions",
      "type": "OPINION",
      "participants": "ALL",
      "turnOrder": "PARALLEL",
      "contextScope": "NONE"
    },
    {
      "name": "Peer Critique",
      "type": "CRITIQUE",
      "participants": "ALL",
      "targetEachPeer": true,
      "contextScope": "FULL"
    },
    {
      "name": "Final Synthesis",
      "type": "SYNTHESIS",
      "participants": "MODERATOR",
      "contextScope": "FULL"
    }
  ]
}
```

A `CRITIQUE` phase with `targetEachPeer: true` has every member critique each peer in turn. Without it, each member reviews all peers' latest responses in one turn.

### Per-phase controls

Beyond `type`/`participants`/`turnOrder`/`contextScope`, a phase carries four controls that shape *when it stops* and *what it costs*:

```json
{
  "name": "Estimates",
  "type": "OPINION",
  "repeats": 3,
  "requiresApproval": false,
  "allowAbstention": true,
  "convergence": { "enabled": true, "minRepeats": 2, "threshold": 0.8, "judge": "MODERATOR" }
}
```

**`repeats`** runs the same phase N times over the growing transcript — the mechanism behind DELPHI's rounds.

**`requiresApproval`** pauses the discussion at the phase boundary until a human approves or rejects (see [HITL](https://docs.labs.ai/conversations-and-orchestration/hitl.md); with `hitlConfig.review.allowResultEdits` the approver may also edit a task's result or a synthesis — see [HITL Review & Audit](https://docs.labs.ai/conversations-and-orchestration/hitl/hitl-review-and-audit.md#group-task-and-synthesis-edits)). A pause can show the approver the draft, the claims or the objection that matter with `hitlConfig.approvalContext` — see [HITL Approval Card Context](https://docs.labs.ai/conversations-and-orchestration/hitl/hitl-approval-context.md). At `TASK` granularity on an `EXECUTE` phase it pauses per submitted task instead.

**`onApproved`** (EXECUTE phases with `requiresApproval` at `TASK` granularity) makes one configured `httpcalls` call with each task a person approves — the approved, possibly edited result goes out exactly as approved, with no member turn in between. It is how a team publishes only human-approved text (a member's own gated tool call is rejected inside a group turn). Exactly-once rules, credentials and a GitHub-comment example: [Group Approved-Result Actions](https://docs.labs.ai/conversations-and-orchestration/group-conversations/group-approved-result-actions.md).

```json
{ "name": "Draft", "type": "EXECUTE", "requiresApproval": true,
  "onApproved": { "action": { "uri": "eddi://ai.labs.apicalls/apicallstore/apicalls/<id>?version=1", "call": "postIssueComment" },
                  "onFailure": "FAIL_TASK" } }
```

**`convergence` (I2)** ends a repeating phase early once the round stopped producing movement, so a group that agreed after round 2 does not pay for round 5. A judge compares this round's contributions against the previous round's and scores similarity against `threshold`; `minRepeats` (minimum 2 — one round has nothing to compare against) guards against calling convergence before there is evidence. `judge` selects who scores it: `MODERATOR` runs the moderator agent as the judge (in its own conversation, so the judge's JSON-only prompts never leak into a later SYNTHESIS turn). `SERVICE` with a `service` model makes one cheap direct model call instead, needs no moderator, and books its spend as `system:judge:*` — see [Group Convergence Judge: SERVICE](https://docs.labs.ai/conversations-and-orchestration/group-conversations/group-service-judge.md); without a `service` model it falls back to the moderator path with a warning. A `MODERATOR` judge in a group with no moderator is skipped and the phase simply keeps going. Converging is a *real completed repeat*: it still persists, still fires `onPhaseComplete`, and still runs the phase's decision block.

**`convergence.mode`** selects what the judge decides. `"SIMILARITY"` (default) is the agreement score above. `"VERDICT"` (E2) has the moderator *review* the latest repeat's result against the discussion's question instead: the judge answers `{"passed": true|false, "feedback": "..."}` and the phase stops repeating as soon as it passes. `threshold` is not used, and because nothing is compared, `minRepeats` may be `1` (absent means 1: the check runs after every repeat). A refinement phase, where each repeat improves the draft on the table, is the case for it:

```json
{
  "name": "Draft",
  "type": "REVISION",
  "repeats": 4,
  "convergence": { "enabled": true, "mode": "VERDICT" }
}
```

Either mode costs one moderator call per checked repeat, counted against `maxTurns` and stopped by the cost ceiling, and neither ends a phase on doubt: an unparseable reply or a judge failure keeps it going. What stops it differs. `SIMILARITY` stops once the agreement score reaches `threshold`. `VERDICT` stops only on a JSON boolean `"passed": true`; prose or a string `"true"` keeps it going. The verdict is recorded as a `CONVERGENCE` transcript entry (`Verdict: passed — …` or `Verdict: not passed — …`), which, like the similarity verdict, is not shown to the members. An unknown `mode` is refused at save time.

**`allowAbstention` (I4)** appends an instruction telling members they may reply with the single token `PASS` when they have nothing to add. A passing member produces an `ABSTAINED` entry carrying no content: peers, the synthesizer and the convergence judge never see it, so a late DELPHI round costs one short call instead of three agents restating agreement in prose. The entry is still *counted* — a round in which every scheduled participant abstained ends the phase through the unanimous-abstention exit. Task phases never advertise the token — the detector and the prompt read the same switch, so they cannot disagree.

### Dissent (I4)

`"recordDissents": true` on the group gives every participant who did *not* write a synthesis one short turn to state where they still materially disagree. Non-`PASS` replies become public `DISSENT` transcript entries and populate `decision.dissents`.

It is opt-in because it costs one extra short call per non-synthesizer. It is nonetheless the honest design: the alternative is asking the synthesizer to report the objections to its own synthesis, which is precisely the failure mode a minority report exists to prevent.

### Phase Types

| Type        | Purpose                                             |
| ----------- | --------------------------------------------------- |
| `OPINION`   | Share perspective on the question                   |
| `CRITIQUE`  | Review another member's response                    |
| `REVISION`  | Revise own response based on feedback               |
| `CHALLENGE` | Argue against consensus (devil's advocate)          |
| `DEFENSE`   | Defend position against challenges                  |
| `ARGUE`     | Present argument for a side (debate)                |
| `REBUTTAL`  | Counter opposing arguments                          |
| `PLAN`      | Decompose the question into sub-tasks               |
| `EXECUTE`   | Work on assigned sub-task                           |
| `VERIFY`    | Review and validate another member's work           |
| `SYNTHESIS` | Moderator produces balanced conclusion              |
| `VOTE`      | Collect explicit ballots and tally a decision (I14) |
| `PROPOSAL`  | State an opening offer in a negotiation (I11)       |
| `BARGAIN`   | Counter, concede, or sign an acceptance (I11)       |
| `RETRO`     | Draw process lessons into team memory (I8)          |

### Context Scopes

| Scope            | What the agent sees                                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `NONE`           | Only the question (independent)                                                                                                                  |
| `FULL`           | All previous transcript entries                                                                                                                  |
| `LAST_PHASE`     | The previous phase's entries **and the current phase's so far** — in a sequential phase, that is what lets the second speaker react to the first |
| `ANONYMOUS`      | Previous entries with speaker names removed                                                                                                      |
| `OWN_FEEDBACK`   | Only feedback addressed to this agent                                                                                                            |
| `TASK_ONLY`      | Only this agent's assigned task from the plan                                                                                                    |
| `TASK_WITH_DEPS` | Assigned task plus outputs from dependency tasks                                                                                                 |

### TASK\_FORCE Configuration

The TASK\_FORCE style uses a 4-phase pipeline: **Plan → Execute → Verify → Synthesize**.

1. **PLAN** — The moderator decomposes the goal into actionable tasks and assigns each to an agent
2. **EXECUTE** — Agents execute their assigned tasks in parallel (each sees only `TASK_ONLY` or `TASK_WITH_DEPS` context). A member turn that produces no result — skipped (timed out, unavailable, paused) or errored under `onAgentFailure: SKIP` — **fails** its task rather than completing it empty, so tasks that depend on it do not run without its output. Under `ABORT` the member's remaining tasks in that wave are not started.
3. **VERIFY** — The moderator reviews each task result against the original goal
4. **SYNTHESIS** — The moderator combines all verified results into a coherent final deliverable

A HUMAN member can execute tasks too, when a task is assigned to them explicitly — see [humans as task-force executors](https://docs.labs.ai/conversations-and-orchestration/group-conversations/group-human-decisions.md#humans-as-task-force-executors).

#### Rework within a run (`maxReworks`)

By default a task that fails VERIFY is `FAILED`, which is final. With `maxReworks` on the group, the verifier's verdict becomes a request for another attempt:

```json
{ "style": "TASK_FORCE", "maxReworks": 2, "protocol": { "maxTurns": 40 } }
```

Inside the VERIFY phase, every task that failed goes back to `ASSIGNED` with the verifier's `feedback` as its `verificationNote`. The EXECUTE phase before VERIFY runs it again, and the member's input ends with *"Reviewer feedback on the previous attempt (address this): …"*, the same channel `onTaskRejection: RETRY` uses for a human reviewer's note. VERIFY then checks the new result. Each task is reworked at most `maxReworks` times in a run; after that it stays `FAILED`. A dependent task that was waiting on a reworked one runs in the same wave once its dependency completes, and is verified with it.

| Field        | Type              | Default | Description                                                                                      |
| ------------ | ----------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `maxReworks` | integer, `0`..`5` | `0`     | Reworks per task within one run. `0` keeps a failed verification final, the behaviour before 6.6 |

* **Budgets.** A rework round needs one turn per reworked task plus one for the verifier. When `protocol.maxTurns` has no room for that, or the cost ceiling is reached, the tasks stay `FAILED` and the transcript says *"Rework stopped: …"*. A rework that was scheduled but could not run ends `FAILED` too, never stranded `ASSIGNED`.
* **Human approval wins.** When the EXECUTE phase gates tasks for approval (`hitlConfig.granularity: TASK` and `requiresApproval`), `maxReworks` is not applied (a warning is logged): the human's decision on each task is the check, and `onTaskRejection: RETRY` is how a person asks for another attempt.
* **Records.** Every return is a `VERIFICATION` transcript entry, *"Returned for rework (1/2): — the verifier's feedback is on the task"*, and is counted by `eddi_group_task_reworks_total`. The note does not quote the feedback: it is the engine's, and every member is shown it, including one that requires peer verification of a verifier whose entry does not verify. The per-task counts are stored with the discussion (`taskList.reworkCounts`), so the bound holds across a pause.
* **Feedback is model text.** The verifier's feedback reaches the member as part of its input, as every group member already reads its peers' contributions. It is never template source.

**An unparseable verdict** (the verifier did not return the JSON array) still auto-verifies every task of that pass, as before. The verdict is the first balanced JSON array in the reply that parses, so prose around it — including bracketed asides such as `Checked [details]: [...]` — no longer makes it unparseable. It is no longer silent: it is logged as a warning naming the group and counted by `eddi_group_verify_unparseable_total`. A steady rate means the moderator's model ignores the verdict format.

#### Pre-Configured Tasks

Pass a `tasks` array to skip the PLAN phase entirely — useful for deterministic, repeatable workflows:

```json
{
  "name": "Documentation Team",
  "style": "TASK_FORCE",
  "moderatorAgentId": "moderator-id",
  "members": [
    {"agentId": "researcher-id", "displayName": "Researcher"},
    {"agentId": "writer-id", "displayName": "Writer"}
  ],
  "tasks": [
    {
      "subject": "Research topic",
      "description": "Research the key trends and data points.",
      "assignToRole": "Researcher",
      "priority": 0
    },
    {
      "subject": "Write article",
      "description": "Using the research findings, write a 500-word article.",
      "assignToRole": "Writer",
      "dependsOn": ["Research topic"],
      "priority": 1
    }
  ]
}
```

When `tasks` is provided, the system posts `[System] "Pre-configured task plan: N tasks"` instead of invoking the moderator's LLM. A `CUSTOM` group whose phases include `EXECUTE` but no `PLAN` gets the same materialization at the start of `EXECUTE`. A `requiresApproval` gate on a PLAN phase does not apply there, because there is no plan phase to pause after.

#### Task Dependencies

Use `dependsOn` to create sequential execution chains. Each entry references a task `subject`:

* Tasks with no dependencies execute in **parallel**
* Tasks with dependencies wait for their predecessors to complete
* Dependent tasks receive their predecessor's output via the `TASK_WITH_DEPS` context scope
* **Cycle detection** prevents circular dependency chains (fails fast at planning time)

#### Task Statuses

| Status              | Meaning                                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
| `PENDING`           | Waiting for dependencies or execution                                                                      |
| `ASSIGNED`          | Assigned to an agent, waiting to start                                                                     |
| `IN_PROGRESS`       | Currently being executed by an agent                                                                       |
| `COMPLETED`         | Agent produced output                                                                                      |
| `VERIFIED`          | Moderator verified the result                                                                              |
| `BLOCKED`           | Reserved for dependency/resource blocking — recognized as non-terminal, but the engine does not set it yet |
| `AWAITING_APPROVAL` | Result submitted, waiting on a human (TASK-granularity HITL)                                               |
| `FAILED`            | Agent or verification failed                                                                               |

### Bid-based assignment (I18, CNP-lite)

The planner cannot know members' actual fit or load. Setting `assignmentMode: "BID"` — per task on a `TaskDefinition`, or as the group default on `taskListConfig` — leaves those tasks unassigned at PLAN time; the execution wave **announces** them to eligible members in blind, parallel bid turns and **awards** each to the highest self-assessed confidence:

```json
"taskListConfig": { "assignmentMode": "BID" },
"tasks": [
  { "subject": "Write the migration", "description": "...", "assignmentMode": "BID" }
]
```

* Members reply `{"bids": [{"subject", "confidence": 0..1, "estimatedComplexity": "XS|S|M|L", "rationale"}]}` — three-tier parse; prose casts no bids; bids on unannounced tasks are dropped; confidence is clamped.
* **Blind**: the bid prompt carries the announced tasks and nothing else — no transcript, no peer bids. Bid replies land as `BID` transcript entries (peer-hidden while the phase runs, auditable afterwards).
* **Deterministic award**: highest confidence; ties break by speaking order, then agent id. The winning bid is recorded per task (`taskList.awardedBids[taskId] = {agentId, confidence, estimatedComplexity, rationale}`).
* **Never stalls a wave**: a task nobody bid on falls back to the ROLE path, and the auction skips itself entirely (logged) when it cannot beat its own overhead — fewer than 2 eligible bidders or fewer than 2 unassigned tasks — or when the remaining turn budget cannot cover one bid turn per member.
* Bid turns are real member turns: they count toward the turn budget and their cost lands in the discussion's cost attribution.

### Dynamic Agents

During TASK\_FORCE (or any group) discussions, agents with the appropriate LLM tools can **create, recruit, and delegate to new agents at runtime**:

| Tool                         | Purpose                                                    |
| ---------------------------- | ---------------------------------------------------------- |
| `CreateSubAgentTool`         | Create a new ephemeral agent with a specific system prompt |
| `ConverseWithAgentTool`      | Delegate a sub-task to an existing deployed agent          |
| `FindAgentsByCapabilityTool` | Discover agents by capability keywords                     |
| `RecruitAgentTool`           | Bring a discovered agent into the discussion as a member   |
| `TeardownAgentTool`          | Clean up dynamically created agents                        |

The model calls them by their method names (`createSubAgent`, `converseWithAgent`, `findAgentsByCapability`, `recruitAgent`, `teardownAgent`, plus `retainAgent` / `unretainAgent` on the teardown tool). They need the member's `enableBuiltInTools`, and a member whose `builtInToolsWhitelist` is non-empty receives each only if the list names its slug: `create_sub_agent`, `converse_with_agent`, `find_agents_by_capability`, `recruit_agent`, `teardown_agent`.

#### Recruitment

Discovery and recruitment are two halves of one capability, and both are gated by `allowRecruitment`. `findAgentsByCapability` locates a specialist; `recruitAgent(agentId, role, reason)` brings it in.

A recruit **joins from the next round**, never mid-round — a roster that changed while a round was running would move the speaker index a paused discussion resumes from, and change the denominator the convergence and unanimity checks already computed for the round in flight. The recruitment is recorded as a `FACILITATION` transcript entry naming the recruiter, the recruit, the role and the reason, so the rest of the team can see why the roster changed.

Recruitment is refused, with an actionable message, when the agent is not deployed, is already a member, is the recruiter itself, when `maxRecruitedAgentsPerDiscussion` is reached, or when the discussion's owner may not use the agent. A recruit speaks as that owner and at their cost, so with workspaces enforced it has to be an agent the owner could have started a conversation with: their own, one shared with them directly, or a published one. Team shares do not count here — the member turn runs without the owner's token, so their team memberships are unknown. An owner who holds `eddi-admin` on the request that drives the turn is admitted, as they are everywhere else. The access check runs before the deployment check, so a refusal never reveals whether an off-limits agent is deployed.

**Recruits are never torn down.** They are pre-existing deployed agents the discussion borrowed, so `TeardownAgentTool` and end-of-discussion cleanup leave them alone — undeploying one would take it away from every other conversation using it. Only agents the discussion *created* are cleaned up.

#### DynamicAgentConfig

Guardrails for dynamic agent creation are configured per-group via `AgentGroupConfiguration.dynamicAgents`:

```json
{
  "dynamicAgents": {
    "enabled": true,
    "allowCreation": true,
    "allowRecruitment": true,
    "allowDelegation": true,
    "maxCreatedAgentsPerDiscussion": 5,
    "maxRecruitedAgentsPerDiscussion": 10,
    "maxDelegationsPerTask": 3,
    "lifecyclePolicy": "ephemeral",
    "inheritParentModel": true,
    "allowedProviders": ["anthropic", "openai"],
    "allowedModels": {
      "anthropic": ["claude-sonnet-4-6"],
      "openai": ["gpt-4o"]
    }
  }
}
```

| Setting                           | Default                     | Purpose                                                                                                                                                                                                                                                |
| --------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled`                         | `false`                     | Master switch for dynamic agent capabilities                                                                                                                                                                                                           |
| `allowCreation`                   | `false`                     | Allow creating new agents (vs. only recruiting existing)                                                                                                                                                                                               |
| `allowRecruitment`                | `false`                     | Allow recruiting already-deployed agents into the discussion                                                                                                                                                                                           |
| `allowDelegation`                 | `true`                      | Allow delegating sub-tasks to other agents                                                                                                                                                                                                             |
| `maxCreatedAgentsPerDiscussion`   | `5`                         | Cap on new agents created per discussion — counted across **all** members, not per member; a torn-down agent frees its slot                                                                                                                            |
| `maxRecruitedAgentsPerDiscussion` | `10`                        | Cap on recruited agents per discussion                                                                                                                                                                                                                 |
| `delegationTimeoutSeconds`        | `60`                        | How long a delegating agent waits for its delegate's turn. Non-positive falls back to the default                                                                                                                                                      |
| `maxDelegationsPerTask`           | `3`                         | Cap on delegations per task                                                                                                                                                                                                                            |
| `maxDelegationDepth`              | `3`                         | How deep a delegation chain may nest before it is refused. The ceiling travels with the chain: each hop applies the stricter of its own limit and the one it was handed, so a delegate with a higher limit cannot extend a chain the originator capped |
| `allowedDelegationTargets`        | `null` (any deployed agent) | Whitelist of agent ids a member may delegate to                                                                                                                                                                                                        |
| `lifecyclePolicy`                 | `ephemeral`                 | `ephemeral`, `keep-deployed`, `undeploy-only`, or `agent-decides` (stored and returned in this form; upper-case `KEEP_DEPLOYED` is accepted on input too)                                                                                              |
| `inheritParentModel`              | `true`                      | Created agents inherit the parent's provider, model and API-key **reference** — see below                                                                                                                                                              |
| `allowedProviders`                | `null` (any)                | Whitelist of LLM providers                                                                                                                                                                                                                             |
| `allowedModels`                   | `null` (any)                | Per-provider model whitelist                                                                                                                                                                                                                           |

Dynamic agents are tracked in `GroupConversation.dynamicMembers`, `createdAgentIds`, and `retainedAgentIds`.

**Dynamic agents cannot sign.** `create_sub_agent` creates an agent with no identity, and a new agent cannot be created with `signInterAgentMessages` on. In a group where any member, the moderator or the facilitator requires peer verification, a created agent's contributions are therefore withheld from the verifying readers as `UNSIGNED`, and its ballots, proposals, lessons and task results count for nothing in the group's records ([Signed contributions](#signed-contributions)). In such a group, leave `dynamicAgents.allowCreation` off and recruit existing agents that have keys instead.

**What the tools may touch.**

* `teardown_agent` undeploys (and optionally deletes) only an agent that is both in the conversation's created list **and** carries a `dynamicOrigin` in its own configuration naming the calling conversation or its discussion. `create_sub_agent` stamps that marker on the agent's first version; an agent a person built has none, so it can never be torn down by a tool. Only the engine writes the marker: an agent update (`PUT`, a merge import, an upgrade) keeps the stored value whatever the body says, and a duplicate or a ZIP import that creates a new agent drops it.
* End-of-discussion cleanup applies the same marker: it deletes only agents whose `dynamicOrigin` names this discussion, leaves agents marked for another one alone, and only **undeploys** — never deletes — an agent with no marker (one created before markers existed, or never created by `create_sub_agent`).
* An undeploy by either of them is a real undeploy, as over REST: the agent's `production` deployment records are marked undeployed, so neither the deployment sweep nor a restart brings it back, and in a cluster every node undeploys it.
* Retain flags set by the `retainAgent` tool persist across turns; `unretainAgent` removes them for good.
* `converse_with_agent` continues only a conversation owned by the same user the calling conversation belongs to (a conversation of another user, or one that records no owner, is refused). Every delegation — a new conversation or a continued one — requires that user to be allowed to use the target agent, the same rule as recruitment above; agents this conversation or its discussion created are exempt — "created" meaning tracked **and** carrying a `dynamicOrigin` that names this conversation or its discussion.

#### Model and credential inheritance

`createSubAgent` takes `provider` and `model` as optional arguments. What is not given is inherited from the creating agent, in this order:

1. **Provider** — the parent's, when `inheritParentModel` is on.
2. **Model** — the parent's, but only if the effective provider is *still* the parent's. An anthropic parent creating an `ollama` sub-agent does not hand it a Claude model name.
3. **API key** — the parent's `${vault:...}` **reference**, again only when the provider matches, because a vault reference names one provider's secret.

**Only a vault reference is inherited, never a plaintext key.** When the vault is unconfigured, `vaultApiKey` falls back to storing the key in clear; copying such a value into a second config would multiply that fallback's blast radius. A parent whose key is plaintext therefore inherits nothing, and creation fails with the ordinary "API key is required" error.

**The allow-lists are checked against the&#x20;*****effective*****&#x20;provider and model** — the values after inheritance and defaults are applied, not the raw arguments. Omitting `provider` does not skip `allowedProviders`. For `allowedModels`:

* **Provider named** (or inherited): an absent or empty entry for that provider means *no restriction for that provider*.
* **No provider named**: the model is about to be paired with the default provider, so that provider must itself appear in `allowedModels`. A config restricting `openai` to `gpt-4o-mini` will not silently build an *anthropic* agent running `gpt-4o-mini`.

### Tenant Quota Enforcement

If tenant quotas are enabled, `QuotaExceededException` is propagated regardless of the group's `onAgentFailure` policy — quota violations always abort the discussion to prevent runaway resource consumption.

## Protocol Configuration

```json
{
  "protocol": {
    "agentTimeoutSeconds": 180,
    "onAgentFailure": "SKIP",
    "maxRetries": 2,
    "onMemberUnavailable": "SKIP",
    "maxTurns": 50,
    "maxCostPerDiscussion": 5.00,
    "onCostExceeded": "SYNTHESIZE_NOW"
  }
}
```

| Setting                | Options                                                                                                                           | Default          |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `agentTimeoutSeconds`  | Any positive integer                                                                                                              | 180              |
| `onAgentFailure`       | `SKIP`, `RETRY`, `ABORT`                                                                                                          | `SKIP`           |
| `maxRetries`           | 0+                                                                                                                                | 2                |
| `onMemberUnavailable`  | `SKIP`, `FAIL`                                                                                                                    | `SKIP`           |
| `maxTurns`             | A positive integer up to 1000 (0 → default; negative or above 1000 is refused on save). A phase's `repeats` is capped at 1000 too | 50               |
| `maxCostPerDiscussion` | Dollars, or `null` for unlimited                                                                                                  | `null`           |
| `onCostExceeded`       | `SYNTHESIZE_NOW`, `ABORT`                                                                                                         | `SYNTHESIZE_NOW` |

**The two ceilings are different instruments.** `maxTurns` bounds *how many member turns* a discussion may spend — it is the structural stop that keeps a recruiting, extending, re-planning discussion finite. `maxCostPerDiscussion` bounds *dollars*, which is what actually differs between a cheap 40-turn round table and an expensive 8-turn one with large contexts. Hitting the cost ceiling under `SYNTHESIZE_NOW` skips the remaining discussion phases and jumps straight to synthesis, so the caller still gets an answer for what was already spent; `ABORT` fails the discussion instead. The skipped phases' `requiresApproval` gates are skipped with them — and so is that of the phase in which the ceiling tripped — but a synthesis phase that runs keeps its own: its answer is paused for approval as usual. Every LLM call in the discussion is attributed, including the facilitator's, the convergence judge's, and the summarizer's.

> The defaults above apply when the `protocol` block is **omitted entirely**, not only when an individual setting is. Nothing backfills a stored config, so a group saved without a `protocol` block runs on exactly these values.

> **Timeout guidance**: 180s covers thinking models (e.g. `claude-sonnet-5`) and synthesis phases comfortably. For tool-calling agents with multiple tool loops, consider `300`–`600`. The timeout is per agent turn, not per phase.

## REST API

| Method   | Path                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST`   | `/groupstore/groups`                                     | Create group config                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `GET`    | `/groupstore/groups/descriptors`                         | List group configs (`filter`, `index`, `limit`)                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `GET`    | `/groupstore/groups/{id}`                                | Read group config                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `PUT`    | `/groupstore/groups/{id}`                                | Update group config                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `POST`   | `/groupstore/groups/{id}?version=`                       | Duplicate a group config (new id)                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `DELETE` | `/groupstore/groups/{id}`                                | Delete group config (`?permanent=true` also deletes the standing-team workspace)                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `GET`    | `/groupstore/groups/styles`                              | List discussion styles                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `POST`   | `/groups/{groupId}/conversations`                        | Start discussion                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `GET`    | `/groups/{groupId}/conversations/{id}`                   | Read transcript                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `GET`    | `/groups/{groupId}/conversations`                        | List conversations (`index`, `limit`). A non-admin sees their own; `mine=true` restricts an admin to their own as well (since 6.7.0). Each member's private conversation records the discussion as `groupConversationId` on its conversation descriptor, and `GET /conversationstore/conversations?excludeGroupMembers=true` leaves those out                                                                                                                                                                 |
| `DELETE` | `/groups/{groupId}/conversations/{id}`                   | Delete (artifacts + ephemeral agents; members **ended**)                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `GET`    | `/groupstore/groups/jsonSchema`                          | JSON schema for the group config                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `POST`   | `/groups/{groupId}/conversations/stream`                 | Start discussion, stream events over SSE                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `POST`   | `/groups/{groupId}/conversations/{id}/followup`          | Ask one member a follow-up. Like a continuation it needs the transcript's owner (or an admin) **and** current USE on the group: owning the transcript does not keep a member runnable after the group was unshared (`403`; the MCP `followup_with_member` refuses the same way). A follow-up is a paid member turn: it is refused (`409`) once the discussion has spent its `maxCostPerDiscussion`, its cost is added to the discussion's total, and sub-agents it creates are cleaned up with the discussion |
| `POST`   | `/groups/{groupId}/conversations/{id}/continue`          | Continue with a new question (same transcript)                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `POST`   | `/groups/{groupId}/conversations/{id}/continue/stream`   | Continue, streaming                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `POST`   | `/groups/{groupId}/conversations/{id}/close`             | Close the conversation to further rounds                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `POST`   | `/groups/{groupId}/conversations/{id}/cancel`            | Cancel a running or paused discussion. A caller who is only an `eddi-approver` may cancel only a paused one and gets the resulting state, not the transcript — see [HITL](https://docs.labs.ai/conversations-and-orchestration/hitl.md#who-may-decide)                                                                                                                                                                                                                                                        |
| `POST`   | `/groups/{groupId}/conversations/{id}/approve`           | Approve/reject a HITL pause. Returns as soon as the decision is recorded — the resumed run continues asynchronously, so the response typically shows `IN_PROGRESS`; poll the conversation or use `/approve/stream`                                                                                                                                                                                                                                                                                            |
| `POST`   | `/groups/{groupId}/conversations/{id}/approve/stream`    | Approve and stream the resumed run                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `POST`   | `/groups/{groupId}/conversations/{id}/human-input`       | Submit a HUMAN member's turn (I6). Asynchronous like `/approve`: the discussion resumes in the background (`IN_PROGRESS`). The owner or an admin gets the conversation back; any other submitter only `{groupConversationId, accepted, state}` (the MCP `submit_group_human_input` likewise). The resumed discussion does not carry a non-owner submitter's identity                                                                                                                                          |
| `GET`    | `/groups/{groupId}/conversations/{id}/approval-status`   | Pause coordinates (`detail=full` for approvers)                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `GET`    | `/groups/{groupId}/conversations/pending-approvals`      | This group's discussions awaiting a decision                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `GET`    | `/groups/pending-approvals`                              | Every group discussion awaiting a decision, across all groups                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `GET`    | `/groupstore/templates`                                  | List preset templates (I10)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `GET`    | `/groupstore/templates/{templateId}`                     | Read one template                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `POST`   | `/groupstore/templates/{templateId}/instantiate`         | Create a group from a template                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `GET`    | `/groupstore/groups/{id}/workspace`                      | Read the standing-team workspace (I13)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `GET`    | `/groupstore/groups/{id}/workspace/backlog`              | Read the team backlog                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `POST`   | `/groupstore/groups/{id}/workspace/backlog`              | File a backlog task                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `POST`   | `/groupstore/groups/{id}/workspace/cadences`             | Add a cron cadence (409 if the workspace keeps changing under three revision-checked attempts; the schedule it created is deleted again)                                                                                                                                                                                                                                                                                                                                                                      |
| `DELETE` | `/groupstore/groups/{id}/workspace/cadences/{cadenceId}` | Remove a cadence, then its schedule (409 as above; cadence and schedule then both stay)                                                                                                                                                                                                                                                                                                                                                                                                                       |

The bet-review endpoints (`/workspace/backlog/due-reviews`, `/workspace/backlog/{taskId}/bet/review`), team outcomes (`/groupstore/groups/{groupId}/outcomes`) and lessons (`/groupstore/groups/{groupId}/lessons`) are listed in [Team Learning Loop](https://docs.labs.ai/conversations-and-orchestration/group-conversations/team-learning-loop.md); team budgets in [Team Budgets](https://docs.labs.ai/security-and-compliance/tenant-quotas/team-budgets.md).

## SSE Events

`POST /groups/{groupId}/conversations/stream` (and the `continue`/`approve` streaming variants) emit these events. A client that only cares about the answer can watch `group_complete`; a UI rendering the discussion live wants the speaker and phase pairs.

| Event                                         | Fires when                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `group_start`                                 | The discussion begins (carries group id and question)                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `phase_start` / `phase_complete`              | A phase opens / closes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `round_start`                                 | A continuation round (round 2+) of the whole discussion begins — see `POST .../continue`. Phase repeats fire `phase_start` instead                                                                                                                                                                                                                                                                                                                                                                                                |
| `speaker_start` / `speaker_complete`          | A member's turn opens / closes. `complete` carries the content, or — when the turn produced none — no content and an `outcome` of `TIMEOUT`, `SKIPPED` or `ERROR`. Every started turn is closed, including a parallel member released by the batch deadline                                                                                                                                                                                                                                                                       |
| `token`                                       | Declared but never emitted today: member turns are not streamed, so a client sees a member's answer whole in `speaker_complete`. Do not build on it                                                                                                                                                                                                                                                                                                                                                                               |
| `synthesis_start` / `synthesis_complete`      | The synthesis phase opens / closes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `convergence_checked` / `convergence_reached` | A convergence judge ran / declared the phase converged (I2)                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `decision_reached`                            | A `DecisionRecord` was set — vote tally, debate verdict, or negotiation agreement (I14/I11)                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `task_plan_created` / `task_verified`         | TASK\_FORCE planned its backlog / verified a task                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `retro_recorded`                              | A RETRO phase finished, with the number of lessons stored (I8)                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `artifact_updated`                            | A shared artifact was created or revised (I17)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `team_handoff`                                | A handoff attempt to another team, from a member's `handoff_to_team` call or an `onDecision` rule: `{handoffId, targetAlias, targetGroupId, outcome, mode, trigger, subject}`. Refusals that reach the filing service are announced too (`outcome` is e.g. `NOT_ACCEPTED`); a call rejected earlier by the tool itself (unknown alias, per-turn limit exceeded) emits no event. Never carries the description. See [Cross-Team Handoff](https://docs.labs.ai/conversations-and-orchestration/group-conversations/team-handoff.md) |
| `member_tool_call`                            | A member's tool loop is about to run a tool: `{agentId, displayName, tool}`. Name only, never arguments (the same rule as the 1:1 `tool_call`). A best-effort liveness signal while the member's non-streamed turn is running; the engine skips it for a speaker the orchestrator has cancelled, but cancellation or a timeout can race with the notification, so it may trail `speaker_complete` of a turn already closed                                                                                                        |
| `cost_updated`                                | A cost attribution landed in the discussion ledger: `{attributionKey, displayName, attributedCost, totalCost}`. `attributedCost` is that key's cumulative cost, so a consumer overwrites per key rather than adding. Also fires for system spend (`system:...` keys that name no member)                                                                                                                                                                                                                                          |
| `stance_updated`                              | A member's one-line stance was recomputed at a phase boundary: `{agentId, displayName, stance, llmGenerated, coveredContributions}`. Fires only when the text changed                                                                                                                                                                                                                                                                                                                                                             |
| `human_input_requested`                       | A HUMAN member's turn is pending (I6)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `awaiting_approval` / `hitl_resume`           | A HITL pause was committed / released                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `member_pause_skipped`                        | A member turn was skipped rather than paused                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `cancelled`                                   | The discussion was cancelled                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `group_complete`                              | Terminal — carries the final state and the synthesized answer                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `group_error`                                 | Terminal failure, with a curated (never raw) message                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

These events belong to the stream of the request that started or continued the discussion. To learn about a discussion without holding that stream open — it started, it ended, it waits for a human member (`yourTurn: true` for the person it waits for), or it paused at an approval gate — the owner and the `HUMAN` members can hold the per-user stream [`GET /me/events`](https://docs.labs.ai/conversations-and-orchestration/user-events.md) instead: `team.started`, `team.waiting_for_human`, `team.ended` and `approval.pending`, with ids only.

## MCP Tools

Group-related tools live in two classes: the group tools below, plus six group-scoped tools provided by the HITL tool set (marked) — three that act on a pause and three that find one. Both are exposed on the same MCP server; the split is internal.

| Tool                               | Description                                                                                                              |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `describe_discussion_styles`       | Rich descriptions of all styles                                                                                          |
| `list_groups`                      | List group configs                                                                                                       |
| `read_group`                       | Read group config                                                                                                        |
| `create_group`                     | Create group (name, members, style, roles, types)                                                                        |
| `update_group`                     | Update group config JSON                                                                                                 |
| `delete_group`                     | Delete group config                                                                                                      |
| `discuss_with_group`               | Start discussion, return transcript                                                                                      |
| `read_group_conversation`          | Read conversation transcript                                                                                             |
| `list_group_conversations`         | List past discussions for a group, with state and timestamps                                                             |
| `start_group_discussion`           | Start a discussion asynchronously (returns immediately). Poll with `read_group_conversation`                             |
| `delete_group_conversation`        | Delete a group conversation. Artifacts and ephemeral agents are deleted; member conversations are **ended**, not deleted |
| `followup_with_member`             | Ask a single member a follow-up on a finished discussion                                                                 |
| `continue_group_discussion`        | Continue a discussion with a new question                                                                                |
| `close_group_conversation`         | Close a conversation to further rounds                                                                                   |
| `list_group_pending_approvals`     | List one group's discussions awaiting a decision — HITL tool set                                                         |
| `list_all_group_pending_approvals` | The cross-group approval inbox — HITL tool set                                                                           |
| `get_group_approval_status`        | Pause coordinates for one discussion — HITL tool set                                                                     |
| `submit_group_human_input`         | Submit a HUMAN member's turn (I6) — HITL tool set                                                                        |
| `approve_group_phase`              | Approve or reject a HITL pause — HITL tool set                                                                           |
| `cancel_group_discussion`          | Cancel a running discussion — HITL tool set                                                                              |
| `add_team_task`                    | File a task on a standing team's backlog (I13)                                                                           |
| `list_team_backlog`                | Read a standing team's backlog                                                                                           |
| `list_group_templates`             | List the preset group templates (I10)                                                                                    |
| `create_group_from_template`       | Create a group from a template + role assignments                                                                        |

`discuss_with_group`, `start_group_discussion`, `followup_with_member` and `continue_group_discussion` hold their arguments to the REST request ceilings: a question is required and at most 50,000 characters, and `userId` and `targetAgentId` at most 256. A refusal is `{"error": "…", "errorCode": "BAD_REQUEST"}`, returned before anything is read or run.

## Slack Integration

Group discussions integrate natively with Slack. See [slack-integration.md](https://docs.labs.ai/protocols-and-integration/slack-integration.md) for full setup instructions.

### UX Pattern: Header + Thread

All discussion styles use the same rendering pattern in Slack:

1. **Start Banner** — posted in the user's thread with style name, agent count, and question
2. **Agent Headers** — each agent's first contribution is a channel-level message with a short preview
3. **Full Content** — the complete response is posted as a thread reply under the agent's header
4. **Peer Feedback** — feedback threads under the target agent's header message
5. **Revisions** — revised contributions thread under the agent's own header
6. **Synthesis** — moderator's synthesis gets its own channel-level header + thread

### Discussion Styles in Slack

| Style               | Phase Flow in Slack                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------- |
| **ROUND\_TABLE**    | Each agent posts → Moderator synthesizes                                                     |
| **PEER\_REVIEW**    | Agents post → Critiques thread under targets → Revisions thread under own → Synthesis        |
| **DEVIL\_ADVOCATE** | Agent posts → Challenger threads challenges → Agent threads defense → Synthesis              |
| **DEBATE**          | PRO agent posts → CON agent posts → Rebuttals thread under opponents → Judge synthesizes     |
| **DELPHI**          | Round 1 agents post → Round 2 agents post (convergence) → Synthesis                          |
| **TASK\_FORCE**     | Moderator posts plan → Agents post task results → Verifiers thread under targets → Synthesis |

### Trigger Keywords

Configure trigger keywords in `ChannelIntegrationConfiguration` to route to specific groups:

```
@EDDI panel: Should we adopt microservices?     → GROUP target "panel"
@EDDI debate: REST vs GraphQL                   → GROUP target "debate"
@EDDI peer: Review this architecture             → GROUP target "peer"
```

### Follow-up Conversations

After a discussion, users can reply in any agent's thread to ask follow-up questions. The system injects the agent's discussion context (contribution + peer feedback received) into the prompt for a contextual response.

## Signed contributions

An agent with `security.signInterAgentMessages` signs every transcript entry it writes, once an admin has generated its signing key ([architecture → Cryptographic Agent Identity](https://docs.labs.ai/architecture-and-concepts/architecture.md#cryptographic-agent-identity)). A member with `security.requirePeerVerification` checks those signatures before each of its turns:

```json
"security": {
  "signInterAgentMessages": true,
  "requirePeerVerification": true
}
```

* The signature covers the entry's content, type, speaker id and display name, target, error reason, round, phase index and name, and key version, the group conversation it belongs to, and its own nonce and signing time. An entry with any of those changed in the store (edited or retyped), copied into another discussion, moved to another phase, or repeated does not verify. The entry's stored `timestamp` is not covered: changing it is not detected, and the changed value is what `groupTranscript` carries.
* Round placement is checked in two ways: an entry of the current round must sit after the round's start, and an earlier round's entry before it, and signed rounds may never go backwards along the transcript. Within the earlier rounds nothing more is checked, so a store writer can move a signed round-1 entry past the round-2 question (but not past a signed round-2 entry) and it still verifies. Moving an entry between repeats of one phase within a round is not detected either.
* **Withheld for a member that verifies.** Every entry another agent wrote that does not verify, or that carries no signature or names a key its speaker does not declare, reaches a member with `requirePeerVerification` as `[withheld: this message could not be verified, because ...]` in its phase prompt and its `groupTranscript` context, named by the speaker's agent id and with no phase name, since the stored display name and phase name are unverified text too; the engine's other prompts for it read the transcript the same way (next item). It is not a blanket fail-closed: a member without the setting (the default) is shown the stored transcript with nothing checked and nothing logged, entries no agent wrote are shown to a verifying member too, unauthenticated (labelled, below), and the texts that still reach it without a signature of their own are listed under [Not yet supported](#not-yet-supported). So every agent that writes to the discussion should sign: each member, and the moderator or synthesizer too when it is not a member, or its synthesis is withheld from verifying members.
* **Every prompt, not only phase turns.** The prompts the engine writes for a role turn read the transcript the same way, as the agent taking the turn may see it: the convergence judge (the moderator; the `SERVICE` judge is no agent and reads the round as the engine's own records count it, below), a dissenter, the facilitator's briefing, a follow-up's `groupTranscript`, and a nested group's question, which is filtered when any agent of the nested group verifies (a member, its moderator or its facilitator, or one of a group nested in it), since that prompt becomes the question each of them works from; a nested group that cannot be read counts as verifying. A dissenter that verifies is not asked to react to a synthesis that does not verify for it.
* **Task forces.** The task records are agent text too: a verifying executor, verifier or bidder is shown a task's result only when a verified entry of the assignee holds exactly that text (an unsigned result, or one edited in the store, reads `[withheld: this text could not be verified]`). Its own results are checked the same way when it signs; one that does not sign is shown its own results as its entries hold them. A result an approver edited when approving it is the reviewer's text, not the agent's, and is shown, as a reviewer's synthesis edit is. A task's subject and description are withheld when they come from a plan that does not verify, or from another member's task tool while that member does not sign verifiably (it has no key, signing is off, or its key is revoked or outside its window). The engine records a tool-filed task under the member whose turn filed it, so a signing member's task is shown as its text and done by a verifying assignee. A standing team's backlog task another team's agent handed off (a `handoff_to_team` call with `AUTO` intake) is that agent's text the same way: the cadence keeps the agent as the run's task's creator, so it is shown, and done, only while that agent signs verifiably. A team with such a member therefore never runs one it could not verify: an `AUTO` handoff from an agent that does not sign verifiably goes to the intake inbox for a person to accept, and a backlog task whose agent stops signing waits on the backlog, not pulled, so no member fails it, is charged for it or is quoted it. Such a task stays `PENDING`; a cadence fire that it leaves with nothing to run records why in the schedule's fire history, naming the agents. To free it, give the agent a signing key again (or turn its signing back on), or delete the task and file it again. Configured tasks and the user's own are shown, and so is a handoff a person accepted from the intake inbox. A store edit to a task's subject or description is not detected, here or for configured tasks. A verification note is withheld when it comes from a verifier entry that does not verify. A verifying member whose own task's text does not verify is not asked to do it: the task fails with "Its task text could not be verified". That uses no turn and is no failure of the member, so under `onAgentFailure: ABORT` the discussion goes on. A verifying verifier judges only the tasks whose text and result it may see: the others stay `COMPLETED`, unverified, with a note giving their count, and with none left it gets no turn, so a verdict that cannot be parsed never auto-verifies work it was not shown. A bidder is announced, and can win, only the tasks whose text it may see, and `listGroupTasks` lists each subject as the calling member may see it.
* **The engine's own records.** Once any member, the moderator or the facilitator (an enabled one: a facilitator that is switched off reads nothing and counts for nothing) requires verification, what the engine records for everyone counts only entries that verify for all of them: the `SERVICE` convergence judge's input, the negotiation table (proposals and concessions), the vote (its options and ballots: a synthesis that does not verify offers no options, so the vote does not run, and an unsigned ballot is not counted, also when a `HUMAN_DECIDES` tie is resumed by the person or, on timeout, by the moderator), an arbitration verdict, the lessons a retrospective stores in team memory, and the feedback a standing team's cadence carries into a backlog task's description, which the next run shows as configured task text. A facilitator's `CALL_VOTE` options are its own text, so in such a group the move is refused unless the facilitator signs verifiably.
* **User memories.** A group- or global-visible user memory whose value another agent wrote carries no signature, so an agent that requires verification neither loads it as a `{properties.key}` at conversation start nor gets it from the memory tool's recall or search, in any conversation. What counts is who last wrote the value, since a global entry keeps its creator as owner when another agent writes it; the store leaves these entries out before the recall limit, so its own memories, the ones the user or an admin wrote and the team's lessons are all shown. A `longTerm` property it sets for a global key is written as any agent's is, replacing such a value, and makes it the value's writer, so it is shown the value again (see [User Memory](https://docs.labs.ai/architecture-and-concepts/user-memory.md)). (The flag is read from the deployed agent version.)
* **Entries the engine writes for an agent are signed for it.** A follow-up answer, the readable summary of a task-force verification, the facilitator's notes (an escalation dropped for an approval gate or a tie-break included) and a recruitment note are signed with the agent's key when it signs, so a verifying member sees them, and are named by the agent: each carries the agent's own text, which recorded as the engine's would pass for engine text. A task-failure note is the engine's own and is recorded as such, with the member as its target.
* A record with no content (a skipped turn, an error, a pass) is written by the engine unsigned, so nothing vouches for its text either. A verifying member's `groupTranscript` keeps it in place with its speaker id, type, phase index and target, named like a withheld entry, but without its reason, display name or phase name. Its own such records are no exception.
* A member that signs has its own entries checked like a peer's, since every honest one is signed: an answer planted under its id, or its own answer edited in the store, is withheld rather than quoted back to it as the answer it revises or defends. So is its own entry that went out unsigned (a signing failure, or an answer from before signing was switched on), as it already is for every verifying peer. A verifying member that does not sign has nothing to check its own entries against: it is shown them as stored, unchecked. They are still unsigned for the engine's records, so once anyone verifies, its proposals, ballots and (as moderator) synthesis do not count there: a verifying moderator that does not sign leaves a vote on its synthesis without options. An agent that verifies should sign too.
* A revoked key vouches for nothing, whenever an entry claims to have been signed. A key's `validFromMs`/`validUntilMs` window is checked against the time the signer wrote into the entry, so it limits honest use but does not stop a leaked key: revoke that one. Revocation applies to every prompt built after it. An entry a member was already shown while the key was valid stays in that member's own conversation history, which its model is shown again on later turns until the history window drops it; to keep a leaked key's text away from the members, start a new discussion.
* An agent that has been deleted vouches for nothing either, whether it was deleted for good or can still be restored. An entry under its id is withheld from a verifying member, signed or not, when the discussion shows an agent wrote it: the entry carries a signature, which only agents give, or an agent turn of this discussion ran under its speaker id. Its placeholder is named by that id followed by `(not an agent, unverified)`, since no agent store vouches for the id any more. Other ids that name no agent (a human member, a nested group, a reviewer) are shown labelled as below. So revoking a compromised agent's key and then deleting the agent keeps its entries withheld. A facilitator's notes are recognised by their type, since only the facilitator, or a member recruiting someone, records a `FACILITATION` note under an agent id: a facilitator that is not a member runs its turns under a conversation of their own.
* Entries no agent wrote are not signed: the user's question and follow-ups, a human member's turn, a reviewer's edit, the engine's own notes and a nested group's answer. They are not authenticated: whoever can write the group-conversation store can add one, or re-attribute an agent's entry to a non-agent speaker id. A verifying member is therefore shown them under a name no member agent has: `User`, `System`, or the stored name followed by `(not an agent, unverified)`. Under `ANONYMOUS` scope, where every speaker is `Anonymous`, such an entry is `Anonymous (not an agent, unverified)`. A group save refuses those names for an agent member (400, ignoring case). Member display names must also be unique within a group (a save with two equal names, ignoring case, is refused with 400), and an agent member may not be named `Moderator` while the moderator is not a member, nor `Facilitator` while an enabled facilitator is another agent: the engine signs those roles' entries under these names. So two verified voices never share one name either, with one exception: a group saved before these checks still loads with the names it has, so its two members can share a name until the group is corrected and saved again.
* A synthesis under the engine's or the user's name (speaker id `system`, `user` or none) is withheld from a verifying member: the engine never records one there, and a synthesis is quoted by its type, without its speaker. Other unsigned syntheses (a reviewer's edit, a human or nested-group moderator's) are shown, labelled as above, and stay unauthenticated.
* The stored window summary is free text no signature covers, so a verifying member never gets it: in a windowed discussion it is shown the truncation marker instead.
* A ballot lists the options in the latest synthesis as the voter sees it, so a verifying voter is offered none from a synthesis that does not verify for it.
* If a member's configuration cannot be read, the setting this node last read for it applies; if it never read one, the member's turn is recorded `SKIPPED`.
* The stored transcript is unchanged. Members that do not verify, the Manager, SSE and the REST and MCP readers see every entry as stored.
* Each withheld entry is logged at ERROR the first time, with its index and the reason (`UNSIGNED`, `UNKNOWN_KEY`, `REVOKED`, `OUT_OF_WINDOW`, `BAD_SIGNATURE`, `WRONG_ROUND`, `DUPLICATE`, `ENGINE_SYNTHESIS`, `NO_SUCH_AGENT`).
* **Cost.** A verifying member checks every agent entry before each turn, but each Ed25519 check is remembered on the node, so an entry costs one check per node, not one per turn. Each pass still reads each distinct speaker's current agent version from the store, and every member, verifying or not, reads its own once per pass (two passes per turn: prompt and context).

## Restarts

A discussion's leg runs in the JVM that started or resumed it, and nothing picks it up after that process dies. On a single node (`eddi.messaging.type=in-memory`) the startup HITL crash recovery therefore **cancels** every discussion still `IN_PROGRESS` or `SYNTHESIZING` that was last written before the process started, so it does not sit in a running state that `continue` and `followup` refuse. Paused discussions are not affected: their timeout schedules are re-armed instead. Details, and when to turn it off (`eddi.hitl.crash-recovery.recover-in-progress`), are in [HITL → Crash Recovery](https://docs.labs.ai/conversations-and-orchestration/hitl.md#crash-recovery). In NATS cluster mode an interrupted discussion still needs a manual cancel — or, for a standing team, the claim TTL (see [Standing Teams](#standing-teams-i13)).

## Not yet supported

Known bounds, so they are not discovered at runtime:

| Area                                      | Behaviour today                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Member-level tool approval**            | A member agent's `hitlConfig.toolApprovals` does not gate inside a group. The framework auto-rejects the gated call (`system:group`) and the member produces a tool-less contribution — see [hitl.md → Group members](https://docs.labs.ai/conversations-and-orchestration/hitl.md#group-members). `inGroupTurns: "INBOX"` is reserved and rejected at save time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **Nested pauses**                         | A sub-group that pauses for approval or a human turn is cancelled and its member turn recorded `SKIPPED`. Nested HITL is not supported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **Groups over the OpenAI-compatible API** | `/v1` exposes deployed *agents* as models. A group is not addressable there; use the REST or MCP surfaces.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **Groups over A2A**                       | An A2A peer can invoke an agent, not a group.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **Peer verification: what is not signed** | Every prompt a verifying member receives is filtered (see [Signed contributions](#signed-contributions)), but some texts reach it without a signature of their own. The engine's notes are shown to it as the engine's, unauthenticated: a rework or task-failure note names a task's subject only as the group's records count it (`[withheld: this text could not be verified]` once a reader verifies and the subject comes from a plan or task tool that does not verify for every reader), and a verifying facilitator's briefing leaves out the convergence check's reason, which is the judge's reply; the note that a human-assigned task is not reworked still quotes its subject as stored. A task a member files with its task tools, or another team's agent hands off, is not signed: its text is that agent's as the engine recorded it, shown when that agent signs verifiably. A handoff an `onDecision` rule files renders the source team's decision record and names no agent, and one a person accepted from the intake inbox is the reviewer's to vouch for: both reach the run as configured task text. The cadence question quotes the pulled tasks under the user's name, marked as handed off where they were; a handed-off one a verifying member could not take as its agent's is not pulled (it goes to the intake inbox when filed, and waits on the backlog if its agent stops signing). So a team whose members require verification should accept handoffs with `REVIEW` intake, where a person approves the text first. Shared artifacts are not signed, so a member that requires verification gets no artifact tools. Lessons are read back as stored: a team's own lessons stored while none of its readers required verification, the lessons other teams share with it (quoted in its RETRO prompt), and the lessons the team scorecard tool returns for the team and the teams it oversees, which were checked only against the storing team's records rule; reading another team's lessons trusts that team's verification setting. A nested group's answer is shown relabelled, not verified. An agent `create_sub_agent` creates has no signing key and cannot be given one while it runs, so with any verifying reader its contributions are withheld as `UNSIGNED` and count for nothing in the group's records (see [Dynamic Agents](#dynamic-agents)). |
| **Cross-node tool availability**          | The task, artifact and recruit tools resolve the running discussion from an in-process registry. Member turns always run in the same JVM as their orchestrator, so this holds — but a discussion is only "live" on the node running it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

## Configuration

```properties
# application.properties
eddi.groups.max-depth=3             # Max recursion depth for nested groups
eddi.groups.cadence.claim-ttl=PT24H # Standing-team claim TTL; non-positive disables reclaiming
eddi.attachments.max-per-turn=5     # Attachments forwarded per member turn
```

A sub-agent that inherits a parent's vault reference must itself be granted that secret, or — under the default `eddi.vault.grant-enforcement=enforce` — it will not deploy. See [secrets-vault.md → Agent Grants](https://docs.labs.ai/security-and-compliance/secrets-vault.md#agent-grants-allowedagents).
