agent-dispatch 0.8.0__tar.gz → 0.9.0__tar.gz

{agent_dispatch-0.8.0 → agent_dispatch-0.9.0}/AGENTS.md

@@ -11,9 +11,9 @@ MCP server + CLI that lets Claude Code agents delegate tasks to agents in other
 | File | Role |
 |------|------|
 | `src/agent_dispatch/runner.py` | Sync subprocess wrapper around `claude -p` — the actual work |
-| `src/agent_dispatch/server.py` | Async FastMCP interface (19 MCP tools), wraps runner in `asyncio.to_thread` + semaphore |
-| `src/agent_dispatch/cli.py` | Click CLI: `init`, `add`, `update`, `remove`, `list`, `describe`, `test`, `doctor`, `jobs`, `job`, `cancel`, `gc`, `serve` |
-| `src/agent_dispatch/models.py` | Pydantic v2 models (`AgentConfig`, `Settings`, `DispatchResult`) |
+| `src/agent_dispatch/server.py` | Async FastMCP interface (21 MCP tools), wraps runner in `asyncio.to_thread` + semaphore |
+| `src/agent_dispatch/cli.py` | Click CLI: `init`, `add`, `update`, `remove`, `list`, `describe`, `test`, `doctor`, `jobs`, `job`, `cancel`, `gc`, `group` (add/list/inspect/update/remove), `serve` |
+| `src/agent_dispatch/models.py` | Pydantic v2 models (`AgentConfig`, `DispatchGroup`/`GroupMember`, `Settings`, `DispatchResult`) |
 | `src/agent_dispatch/config.py` | YAML config load/save + project auto-description |
 | `src/agent_dispatch/cache.py` | Thread-safe in-memory TTL cache |
 | `src/agent_dispatch/jobs.py` | Persistent per-job JSON files for async dispatch |
@@ -28,7 +28,7 @@ pip install -e ".[dev]"
 
 ```bash
 ruff check src/ tests/
-python3 -m pytest tests/ -v   # 428 tests, ~2s — all subprocess calls are mocked
+python3 -m pytest tests/ -v   # 466 tests, ~2s — all subprocess calls are mocked
 ```
 
 Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.which` + `subprocess.run`/`Popen`; server tests mock `_get_config` + `runner.dispatch`.
@@ -37,6 +37,7 @@ Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.whi
 
 - `allowed_tools` / `disallowed_tools` are **tri-state**: `None` = inherit settings defaults, `[]` = explicitly no tools, `[...]` = exactly these. Check with `is not None`, never `or` — `[]` is falsy but semantically distinct.
 - `denied_tools` non-empty + `is_error` ⇒ `error_type="permission"`, regardless of what the error text matches.
+- **Groups**: a group's `shared_context` is folded into the `context` *string* before the cache/runner calls (`_merge_group_context` in server.py) — runner.py and cache.py are untouched, the cache key disambiguates groups for free, and `group=""` is byte-identical to a plain dispatch. Membership is validated up front (`_validate_group_member`, separate from the pure merge so `dispatch_parallel`'s all-or-nothing pre-check holds). `DispatchConfig` validates only group *keys*, never member existence — a hard cross-ref check would brick config load when a shared gateway agent is removed; dangling refs are flagged (`unknown:true`) at read time instead.
 - On failure, callers read `DispatchResult.error` + `error_type` — `result` holds the raw agent output even on errors.
 - `--session-id` and `--resume` conflict — never pass both to `claude`.
 - Valid permission modes: `default`, `plan`, `bypassPermissions` (`models.py: KNOWN_PERMISSION_MODES`).
@@ -54,4 +55,4 @@ Python ≥ 3.10 · `from __future__ import annotations` everywhere · Pydantic v
 
 ## More detail
 
-[README.md](README.md) documents every MCP tool with parameter tables, response shapes, and the error-recovery map — it doubles as the behavioral spec. The test suite (`tests/`, 428 tests) encodes the exact expected behavior of every layer: when in doubt, read the tests for the module you're touching (`test_runner.py`, `test_server.py`, `test_cli.py`, ...).
+[README.md](README.md) documents every MCP tool with parameter tables, response shapes, and the error-recovery map — it doubles as the behavioral spec. The test suite (`tests/`, 466 tests) encodes the exact expected behavior of every layer: when in doubt, read the tests for the module you're touching (`test_runner.py`, `test_server.py`, `test_cli.py`, ...).

{agent_dispatch-0.8.0 → agent_dispatch-0.9.0}/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-06-30
+
+Coordinate a group of related projects from one session.
+
+### Added
+- **Project groups.** A new `groups` mapping in the config bundles related
+  agents — code repos plus capability gateways like infra (Portainer) or
+  analytics (browser / Yandex Metrica) — into a cross-project working set.
+  Each group has an orchestrator-facing `description` (how to coordinate, never
+  sent to members) and a member-facing `shared_context` of facts (stack names,
+  ids, conventions). Members reference agents by name; membership is
+  many-to-many (a shared gateway can belong to several groups). A group is a
+  *descriptive layer*, not an execution engine — there is no router; the
+  orchestrating LLM coordinates with the existing dispatch tools.
+- **`list_groups()` / `inspect_group(name)` MCP tools** — cheap, no-subprocess
+  readouts of groups, their briefs, and members (dangling member refs are
+  flagged, never crash). For a deep dive on a member, use `inspect_agent`.
+- **`group=` on `dispatch` and per-item in `dispatch_parallel`** — when set,
+  the agent must be a member of the group and the group's `shared_context` is
+  auto-prepended to the call's `context`. Folded into the context string, so
+  the cache key disambiguates groups automatically and `group=""` is byte-for-
+  byte identical to a plain dispatch. Parallel validates membership up front
+  (one bad item rejects the whole call before any subprocess runs).
+- **`agent-dispatch group` CLI** — `add` / `list` / `inspect` / `update` /
+  `remove` for managing groups, mirroring the agent commands.
+
+### Changed
+- `save_config` prunes an empty `groups` block and empty member lists so
+  group-less configs stay clean in YAML (same idiom as capabilities).
+
 ## [0.8.0] - 2026-06-17
 
 Let agents declare what they are good at, so callers can pick the right one.

{agent_dispatch-0.8.0 → agent_dispatch-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.8.0
+Version: 0.9.0
 Summary: MCP server that lets Claude Code agents delegate tasks to agents in other project directories
 Project-URL: Homepage, https://github.com/ginkida/agent-dispatch
 Project-URL: Repository, https://github.com/ginkida/agent-dispatch
@@ -150,6 +150,37 @@ Cheap detailed lookup — reads the agent's files without spawning a `claude` se
 
 Use this **before** `dispatch_async`/`dispatch` to confirm an agent has the tools and context for your task — much cheaper than a probe dispatch.
 
+### Groups
+
+A **group** bundles related agents into a cross-project working set — typically a few code repos plus capability gateways (an `infra` agent with a Portainer MCP, an `analytics` agent with a browser + Yandex Metrica). It lets one orchestrating session coordinate work that spans code, deploy, and verification.
+
+A group is a **descriptive layer, not an execution engine** — there is no router and no state machine. You pick members by reading their hints and coordinate with the normal dispatch tools. Two text fields target two audiences:
+
+- `description` — **orchestrator-facing**: how to coordinate the group (the order of steps, who to call for what). Surfaced by `list_groups`/`inspect_group`, **never** injected into a member's prompt.
+- `shared_context` — **member-facing facts** (stack names, counter ids, conventions) that hold regardless of which member reads them. Auto-prepended to a member's `context` when you pass `group=`.
+
+Members reference agents by name; membership is many-to-many (a shared gateway can belong to several groups). Manage groups with the `agent-dispatch group` CLI (`add`/`list`/`inspect`/`update`/`remove`) or by editing `agents.yaml`.
+
+**`list_groups()`** — cheap, no-subprocess readout of every group: description, member count, and each member's `use_for` hint + health. A member whose agent was removed is flagged `"unknown": true` rather than crashing.
+
+**`inspect_group(name)`** — one group's full brief: `description`, the complete `shared_context`, and the member list. For a deep dive on a specific member, call `inspect_agent(member)` — `inspect_group` deliberately stays a cheap membership readout.
+
+**Using a group** — pass `group=` to `dispatch` (or per-item in `dispatch_parallel`). The agent must be a member; its group's `shared_context` rides along automatically:
+
+```python
+# From the shop-web codebase, hand the deploy to the infra gateway.
+# The "shop" group's facts (stack name, counter id) are auto-attached.
+dispatch(
+    agent="infra",
+    task="Redeploy the shop-web container",
+    caller="shop-web",
+    goal="ship the checkout fix",
+    group="shop",
+)
+```
+
+`group=""` (the default) is byte-for-byte identical to a plain dispatch — the shared facts are folded into the `context` string, so the result cache disambiguates groups automatically and group-less calls are unaffected.
+
 ### `dispatch`
 
 One-shot task delegation. Results are cached — identical requests within TTL return instantly.
@@ -165,6 +196,7 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 | `return_ref` | bool | no | When `true`, returns just a `ref` + summary preview instead of the full result text. Use `fetch_result(ref)` to load the full text on demand. |
 | `summary_chars` | int | no | Max chars of result text to include in the ref response (default 500). |
 | `timeout_seconds` | int | no | One-off timeout override for this call (0 = agent's configured timeout; clamped to 10–7200). No config edit needed for known-long tasks. |
+| `group` | string | no | Group name (from `list_groups`). The agent must be a member; the group's `shared_context` (member-facing facts) is auto-prepended to `context`. Empty = plain dispatch. See [Groups](#groups). |
 
 ```python
 # Call — recommended form (always include caller and goal)
@@ -274,7 +306,7 @@ Run multiple tasks concurrently. Much faster than sequential `dispatch` calls.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `dispatches` | string (JSON) | yes | JSON array of `{"agent", "task", "context?", "caller?", "goal?", "response_format?", "return_ref?", "summary_chars?", "timeout_seconds?"}` |
+| `dispatches` | string (JSON) | yes | JSON array of `{"agent", "task", "context?", "caller?", "goal?", "response_format?", "return_ref?", "summary_chars?", "timeout_seconds?", "group?"}` (a per-item `group` validates membership up front and auto-injects its `shared_context`) |
 | `aggregate` | string | no | Agent name to synthesize all results into one answer |
 
 **Important:** `dispatches` is a JSON string, not a list.
@@ -456,6 +488,8 @@ Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `A
 | Check progress without blocking | `dispatch_status` |
 | Known-long task, one-off | any dispatch tool with `timeout_seconds=...` |
 | A dispatch timed out | `dispatch_session` with the `session_id` from the error |
+| Coordinating a set of related projects | define a [group](#groups), then `dispatch(..., group=name)` |
+| See which agents form a working set | `list_groups` / `inspect_group` |
 
 ## Error Recovery
 

{agent_dispatch-0.8.0 → agent_dispatch-0.9.0}/README.md

@@ -120,6 +120,37 @@ Cheap detailed lookup — reads the agent's files without spawning a `claude` se
 
 Use this **before** `dispatch_async`/`dispatch` to confirm an agent has the tools and context for your task — much cheaper than a probe dispatch.
 
+### Groups
+
+A **group** bundles related agents into a cross-project working set — typically a few code repos plus capability gateways (an `infra` agent with a Portainer MCP, an `analytics` agent with a browser + Yandex Metrica). It lets one orchestrating session coordinate work that spans code, deploy, and verification.
+
+A group is a **descriptive layer, not an execution engine** — there is no router and no state machine. You pick members by reading their hints and coordinate with the normal dispatch tools. Two text fields target two audiences:
+
+- `description` — **orchestrator-facing**: how to coordinate the group (the order of steps, who to call for what). Surfaced by `list_groups`/`inspect_group`, **never** injected into a member's prompt.
+- `shared_context` — **member-facing facts** (stack names, counter ids, conventions) that hold regardless of which member reads them. Auto-prepended to a member's `context` when you pass `group=`.
+
+Members reference agents by name; membership is many-to-many (a shared gateway can belong to several groups). Manage groups with the `agent-dispatch group` CLI (`add`/`list`/`inspect`/`update`/`remove`) or by editing `agents.yaml`.
+
+**`list_groups()`** — cheap, no-subprocess readout of every group: description, member count, and each member's `use_for` hint + health. A member whose agent was removed is flagged `"unknown": true` rather than crashing.
+
+**`inspect_group(name)`** — one group's full brief: `description`, the complete `shared_context`, and the member list. For a deep dive on a specific member, call `inspect_agent(member)` — `inspect_group` deliberately stays a cheap membership readout.
+
+**Using a group** — pass `group=` to `dispatch` (or per-item in `dispatch_parallel`). The agent must be a member; its group's `shared_context` rides along automatically:
+
+```python
+# From the shop-web codebase, hand the deploy to the infra gateway.
+# The "shop" group's facts (stack name, counter id) are auto-attached.
+dispatch(
+    agent="infra",
+    task="Redeploy the shop-web container",
+    caller="shop-web",
+    goal="ship the checkout fix",
+    group="shop",
+)
+```
+
+`group=""` (the default) is byte-for-byte identical to a plain dispatch — the shared facts are folded into the `context` string, so the result cache disambiguates groups automatically and group-less calls are unaffected.
+
 ### `dispatch`
 
 One-shot task delegation. Results are cached — identical requests within TTL return instantly.
@@ -135,6 +166,7 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 | `return_ref` | bool | no | When `true`, returns just a `ref` + summary preview instead of the full result text. Use `fetch_result(ref)` to load the full text on demand. |
 | `summary_chars` | int | no | Max chars of result text to include in the ref response (default 500). |
 | `timeout_seconds` | int | no | One-off timeout override for this call (0 = agent's configured timeout; clamped to 10–7200). No config edit needed for known-long tasks. |
+| `group` | string | no | Group name (from `list_groups`). The agent must be a member; the group's `shared_context` (member-facing facts) is auto-prepended to `context`. Empty = plain dispatch. See [Groups](#groups). |
 
 ```python
 # Call — recommended form (always include caller and goal)
@@ -244,7 +276,7 @@ Run multiple tasks concurrently. Much faster than sequential `dispatch` calls.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `dispatches` | string (JSON) | yes | JSON array of `{"agent", "task", "context?", "caller?", "goal?", "response_format?", "return_ref?", "summary_chars?", "timeout_seconds?"}` |
+| `dispatches` | string (JSON) | yes | JSON array of `{"agent", "task", "context?", "caller?", "goal?", "response_format?", "return_ref?", "summary_chars?", "timeout_seconds?", "group?"}` (a per-item `group` validates membership up front and auto-injects its `shared_context`) |
 | `aggregate` | string | no | Agent name to synthesize all results into one answer |
 
 **Important:** `dispatches` is a JSON string, not a list.
@@ -426,6 +458,8 @@ Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `A
 | Check progress without blocking | `dispatch_status` |
 | Known-long task, one-off | any dispatch tool with `timeout_seconds=...` |
 | A dispatch timed out | `dispatch_session` with the `session_id` from the error |
+| Coordinating a set of related projects | define a [group](#groups), then `dispatch(..., group=name)` |
+| See which agents form a working set | `list_groups` / `inspect_group` |
 
 ## Error Recovery
 

{agent_dispatch-0.8.0 → agent_dispatch-0.9.0}/agents.example.yaml

@@ -41,6 +41,29 @@ agents:
   #   description: "Frontend React app. Can modify components, run build, check TypeScript errors."
   #   timeout: 180
 
+# Groups bundle related agents (code repos + capability gateways like infra)
+# into a cross-project working set. A group is a *descriptive layer* — there is
+# no router and no execution engine; the orchestrating session coordinates with
+# the normal dispatch tools. `members` reference agents above (many-to-many: a
+# shared gateway can belong to several groups). Manage via `agent-dispatch
+# group add/list/inspect/update/remove`; read via the list_groups /
+# inspect_group MCP tools; auto-attach the brief via dispatch(..., group="shop").
+groups:
+  shop:
+    # description = ORCHESTRATOR-facing: how to coordinate the group.
+    # Surfaced by list_groups/inspect_group, never injected into a member.
+    description: "E-commerce team. After a code change: deploy via infra, then verify the checkout funnel via the analytics gateway before reporting done."
+    # shared_context = MEMBER-facing FACTS, auto-prepended to group dispatches.
+    shared_context: |
+      Production runs in Portainer stack "shop".
+      Conversion is tracked in Yandex Metrica counter 12345.
+    members:
+      - agent: backend
+        use_for: orders/payments endpoints, migrations
+      - agent: infra
+        use_for: deploy, restart, container logs
+      # - agent: analytics   # a shared gateway agent could also live here
+
 settings:
   default_timeout: 300
   max_dispatch_depth: 3           # recursion protection: A -> B -> A

{agent_dispatch-0.8.0 → agent_dispatch-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.8.0"
+version = "0.9.0"
 description = "MCP server that lets Claude Code agents delegate tasks to agents in other project directories"
 readme = "README.md"
 license = "MIT"

{agent_dispatch-0.8.0 → agent_dispatch-0.9.0}/src/agent_dispatch/__init__.py

@@ -1,3 +1,3 @@
 """agent-dispatch: Delegate tasks between Claude Code agents across projects."""
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"

{agent_dispatch-0.8.0 → agent_dispatch-0.9.0}/src/agent_dispatch/cli.py

@@ -15,7 +15,14 @@ from pydantic import ValidationError
 
 from .config import auto_describe, config_path, load_config, save_config
 from .jobs import JobStore, default_jobs_dir, is_valid_job_id
-from .models import AgentConfig, DispatchConfig, check_permission_mode, validate_agent_name
+from .models import (
+    AgentConfig,
+    DispatchConfig,
+    DispatchGroup,
+    GroupMember,
+    check_permission_mode,
+    validate_agent_name,
+)
 
 
 def _parse_csv(value: str | None) -> list[str] | None:
@@ -475,6 +482,176 @@ def describe(name: str) -> None:
         pass
 
 
+@cli.group("group")
+def group_cmd() -> None:
+    """Manage agent groups (cross-project working sets)."""
+
+
+@group_cmd.command("add")
+@click.argument("name")
+@click.option(
+    "-d",
+    "--description",
+    default="",
+    help="Orchestrator-facing brief: how to coordinate the group (not sent to members).",
+)
+@click.option(
+    "--shared-context",
+    default="",
+    help="Member-facing facts (stack names, ids) auto-injected into group dispatches.",
+)
+@click.option(
+    "--member",
+    "members",
+    multiple=True,
+    help="Agent name to include (repeatable). Must already exist.",
+)
+def group_add(name: str, description: str, shared_context: str, members: tuple[str, ...]) -> None:
+    """Create a group referencing existing agents."""
+    try:
+        validate_agent_name(name)
+    except ValueError as e:
+        click.echo(f"Error: {e}")
+        raise SystemExit(1) from None
+
+    config = _load_or_exit()
+    if name in config.groups:
+        click.echo(
+            f"Group '{name}' already exists. Use 'agent-dispatch group remove {name}' first."
+        )
+        raise SystemExit(1)
+
+    member_objs: list[GroupMember] = []
+    for agent_name in members:
+        if agent_name not in config.agents:
+            click.echo(
+                click.style(
+                    f"Error: agent '{agent_name}' not found. "
+                    "Add it first ('agent-dispatch add') or check the name.",
+                    fg="red",
+                )
+            )
+            raise SystemExit(1)
+        member_objs.append(GroupMember(agent=agent_name))
+
+    config.groups[name] = DispatchGroup(
+        description=description,
+        shared_context=shared_context,
+        members=member_objs,
+    )
+    save_config(config)
+    click.echo(f"Added group '{name}' ({len(member_objs)} member(s)).")
+    if not member_objs:
+        click.echo(
+            click.style(
+                "Warning: group has no members yet. Recreate with --member, "
+                "or add agents + use_for hints by editing agents.yaml.",
+                fg="yellow",
+            )
+        )
+
+
+@group_cmd.command("list")
+def group_list() -> None:
+    """List configured groups."""
+    config = _load_or_exit()
+    if not config.groups:
+        click.echo("No groups configured. Run: agent-dispatch group add <name> --member <agent>")
+        return
+
+    for name, grp in config.groups.items():
+        click.echo(f"  {click.style(name, bold=True)} ({len(grp.members)} member(s))")
+        if grp.description:
+            click.echo(f"    desc: {grp.description}")
+        rendered: list[str] = []
+        for m in grp.members:
+            if m.agent in config.agents:
+                rendered.append(m.agent)
+            else:
+                rendered.append(click.style(f"{m.agent}(unknown)", fg="red"))
+        if rendered:
+            click.echo(f"    members: {', '.join(rendered)}")
+        click.echo(f"    shared context: {'yes' if grp.shared_context.strip() else 'no'}")
+        click.echo()
+
+
+@group_cmd.command("inspect")
+@click.argument("name")
+def group_inspect(name: str) -> None:
+    """Show a group's brief, shared context, and members."""
+    config = _load_or_exit()
+    if name not in config.groups:
+        click.echo(f"Group '{name}' not found. Run 'agent-dispatch group list' to see groups.")
+        raise SystemExit(1)
+
+    grp = config.groups[name]
+    click.echo(click.style(name, bold=True))
+    if grp.description:
+        click.echo(f"  description:    {grp.description}")
+    if grp.shared_context:
+        click.echo("  shared_context:")
+        for line in grp.shared_context.splitlines():
+            click.echo(f"    {line}")
+    click.echo(f"  members ({len(grp.members)}):")
+    for m in grp.members:
+        marker = "" if m.agent in config.agents else click.style(" (unknown)", fg="red")
+        hint = f" — {m.use_for}" if m.use_for else ""
+        click.echo(f"    - {m.agent}{marker}{hint}")
+    if not grp.members:
+        click.echo(
+            click.style(
+                "    (no members — recreate with --member or edit agents.yaml)", fg="yellow"
+            )
+        )
+
+
+@group_cmd.command("update")
+@click.argument("name")
+@click.option("-d", "--description", default=None, help="New description (pass '' to clear).")
+@click.option("--shared-context", default=None, help="New shared context (pass '' to clear).")
+def group_update(name: str, description: str | None, shared_context: str | None) -> None:
+    """Update a group's description / shared_context.
+
+    These are plain text fields: a new value is stored literally (pass an empty
+    string to clear). Edit members by recreating the group or editing
+    agents.yaml.
+    """
+    config = _load_or_exit()
+    if name not in config.groups:
+        click.echo(f"Group '{name}' not found. Run 'agent-dispatch group list' to see groups.")
+        raise SystemExit(1)
+
+    grp = config.groups[name]
+    updated: list[str] = []
+    if description is not None:
+        grp.description = description
+        updated.append("description")
+    if shared_context is not None:
+        grp.shared_context = shared_context
+        updated.append("shared_context")
+
+    if not updated:
+        click.echo("Nothing to update. Pass --description and/or --shared-context.")
+        raise SystemExit(1)
+
+    save_config(config)
+    click.echo(f"Updated group '{name}': {', '.join(updated)}")
+
+
+@group_cmd.command("remove")
+@click.argument("name")
+def group_remove(name: str) -> None:
+    """Remove a group (does not touch the underlying agents)."""
+    config = _load_or_exit()
+    if name not in config.groups:
+        click.echo(f"Group '{name}' not found.")
+        raise SystemExit(1)
+
+    del config.groups[name]
+    save_config(config)
+    click.echo(f"Removed group '{name}'.")
+
+
 @cli.command()
 def doctor() -> None:
     """Diagnose the agent-dispatch setup and surface common issues."""

{agent_dispatch-0.8.0 → agent_dispatch-0.9.0}/src/agent_dispatch/config.py

@@ -54,6 +54,15 @@ def save_config(config: DispatchConfig, path: Path | None = None) -> None:
         for key in ("capabilities", "risky_capabilities"):
             if not agent_data.get(key):
                 agent_data.pop(key, None)
+    # `groups` also defaults to {} (not None), so exclude_none keeps it — prune
+    # the whole block when empty, and drop empty per-group member lists. Empty
+    # LISTS only, mirroring capabilities; empty strings (description /
+    # shared_context / use_for) are kept, like AgentConfig.description.
+    for group_data in data.get("groups", {}).values():
+        if not group_data.get("members"):
+            group_data.pop("members", None)
+    if not data.get("groups"):
+        data.pop("groups", None)
     p.write_text(
         yaml.dump(data, default_flow_style=False, allow_unicode=True, sort_keys=False),
         encoding="utf-8",

{agent_dispatch-0.8.0 → agent_dispatch-0.9.0}/src/agent_dispatch/models.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any
 
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
 
 _AGENT_NAME_PATTERN = r"^[a-zA-Z0-9][a-zA-Z0-9_-]*$"
 
@@ -97,12 +97,67 @@ def validate_agent_name(name: str) -> str:
     return name
 
 
+class GroupMember(BaseModel):
+    """One member of a dispatch group: a reference to an existing agent.
+
+    `agent` is the name of an agent in `DispatchConfig.agents`. `use_for` is a
+    short, group-contextual hint ("dispatch me when...") that helps the
+    orchestrating LLM route within the group. It is descriptive only — never
+    passed to the `claude` CLI.
+    """
+
+    agent: str
+    use_for: str = ""
+
+    @field_validator("agent")
+    @classmethod
+    def _valid_agent(cls, v: str) -> str:
+        return validate_agent_name(v)
+
+
+class DispatchGroup(BaseModel):
+    """A named, descriptive group of agents for coordinated cross-project work.
+
+    A group is a *layer*, not an execution engine: there is no router and no
+    state machine — the orchestrating LLM coordinates using the normal dispatch
+    tools. The two text fields target two different audiences:
+
+    - `description` is ORCHESTRATOR-facing (how to coordinate the group, who to
+      call for what). It is surfaced by list_groups/inspect_group but is NEVER
+      injected into a member's prompt.
+    - `shared_context` is MEMBER-facing FACTS (stack names, counter ids,
+      conventions) that hold regardless of which member reads them. It is
+      auto-injected into dispatches made with `group=`.
+
+    `members` reference agents by name. Membership is many-to-many: a shared
+    gateway agent (e.g. infra, analytics) can belong to several groups.
+    """
+
+    description: str = ""
+    shared_context: str = ""
+    members: list[GroupMember] = Field(default_factory=list)
+
+
 class DispatchConfig(BaseModel):
-    """Top-level config: agents + settings."""
+    """Top-level config: agents + groups + settings."""
 
     agents: dict[str, AgentConfig] = Field(default_factory=dict)
+    groups: dict[str, DispatchGroup] = Field(default_factory=dict)
     settings: Settings = Field(default_factory=Settings)
 
+    @model_validator(mode="after")
+    def _validate_group_names(self) -> DispatchConfig:
+        # Validate only the group KEYS (cheap, keeps prompt-label construction
+        # provably safe regardless of how the YAML was hand-authored).
+        # Deliberately does NOT check that each member's agent exists — gateway
+        # agents are shared and a hard cross-ref check would make removing one
+        # brick config load (every CLI command + MCP call dies in load_config).
+        # Dangling refs are flagged at read time (list_groups/inspect_group) and
+        # blocked at CLI mutation time instead.
+        for name in self.groups:
+            validate_agent_name(name)
+        return self
+
 
 class DispatchResult(BaseModel):
     """Result of a dispatch call."""