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

{agent_dispatch-0.8.0 → agent_dispatch-0.10.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`).
@@ -50,8 +51,8 @@ Python ≥ 3.10 · `from __future__ import annotations` everywhere · Pydantic v
 
 ## When adding a feature, check every layer
 
-`models.py` (data shape) → `runner.py` (dispatch mechanics) → `server.py` (MCP tool) → `cli.py` (CLI flag) → tests for each → `README.md` + `agents.example.yaml` (user docs).
+`models.py` (data shape) → `config.py` (YAML round-trip + empty-collection pruning) → `runner.py` (dispatch mechanics) → `server.py` (MCP tool) → `cli.py` (CLI flag) → tests for each → `README.md` + `agents.example.yaml` (user docs).
 
 ## 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.10.0}/CHANGELOG.md

@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-07-14
+
+`doctor` learns to check groups; three correctness fixes found in review.
+
+### Added
+- **`agent-dispatch doctor` diagnoses group health.** A new "Groups" section
+  reports each group's member count, flags dangling members (agents removed
+  from config but still referenced) as a failure, and empty groups as a
+  warning — each with a concrete remediation command.
+
+### Fixed
+- `auto_describe()`: an empty `"description"` field in `package.json` (a
+  common `npm init` placeholder) was no longer being filtered out, producing
+  malformed generated descriptions like `" | Stack: Node.js"`. Empty/blank
+  descriptions are ignored again.
+- `doctor`'s group remediation hints pointed at `group update --members`,
+  a flag that doesn't exist (`group update` only edits `description` /
+  `shared_context`; membership is set via `group add --member`). Hints now
+  point at the working `group remove` + `group add --member` recreation path.
+- `JobStore.mark_running()` now refuses to start any job that isn't
+  `pending` (previously only refused `cancelled`), closing a race where a
+  stale/duplicate worker could resurrect an already-finished or failed job.
+
+### Changed
+- Consolidated the "unknown group member" check — previously duplicated
+  across five call sites in `cli.py` and `server.py` — into a single
+  `DispatchConfig.unknown_group_members()` helper.
+
+## [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.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.8.0
+Version: 0.10.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
@@ -43,6 +43,8 @@ Description-Content-Type: text/markdown
 
 Each agent runs as a separate `claude -p` session in its own project directory — inheriting that project's MCP servers, CLAUDE.md, and tools. The calling agent just gets the result back.
 
+Related projects can be bundled into a **[group](#groups)** — a shared brief plus a member list — so one session can coordinate work across them (e.g. code repos + an `infra`/Portainer gateway + an `analytics` gateway).
+
 Works with OAuth, API key, and Claude subscription authentication.
 
 > **AI agents:** this README is the canonical doc for *using* the tool — setup: [Quick Start](#quick-start) (every step has a deterministic verify), first call: [`dispatch`](#dispatch), tool selection: [Which Tool to Use](#which-tool-to-use), failure handling: [Error Recovery](#error-recovery). Working *on* this repo instead? See [AGENTS.md](AGENTS.md).
@@ -150,6 +152,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 +198,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 +308,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 +490,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
 
@@ -505,6 +541,23 @@ agents:
     # disallowed_tools:     # block specific tools
     #   - Write
 
+# Optional: bundle related agents into a cross-project working set.
+# A descriptive layer — no router; the orchestrating session coordinates
+# with the normal dispatch tools. See the Groups section above.
+groups:
+  shop:
+    # ORCHESTRATOR-facing: how to coordinate the group. Surfaced by
+    # list_groups/inspect_group, NEVER injected into a member's prompt.
+    description: "After a code change: deploy via infra, then verify via analytics."
+    # MEMBER-facing facts, auto-prepended to dispatch(..., group="shop").
+    shared_context: |
+      Prod runs in Portainer stack "shop". Metrica counter 12345.
+    members:                # reference agents above (many-to-many)
+      - agent: infra
+        use_for: deploy, restart, container logs
+      # - agent: backend
+      #   use_for: orders/payments endpoints
+
 settings:
   default_timeout: 300
   # default_permission_mode: bypassPermissions  # inherited by all agents
@@ -574,7 +627,7 @@ agent-dispatch MCP server
 - **Cost visibility** — `max_budget_usd` per agent or globally; a dispatch whose cost exceeds it returns `budget_exceeded: true` + a hint (post-hoc — the `claude` CLI has no spend cap, so the overage can be flagged but not prevented).
 - **Concurrency** — `max_concurrency` (default: 5) caps parallel `claude -p` processes. Note: the sync and async dispatch paths use separate semaphores, so the worst-case total is `2 × max_concurrency`.
 - **Timeout** — per-agent or global (default: 300s). Orphaned processes are cleaned up.
-- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only successes are cached. Sessions and dialogues are never cached.
+- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only successes are cached. Sessions and dialogues are never cached. A `group=` dispatch folds the group's `shared_context` into `context`, so different groups cache separately and a plain dispatch is unaffected.
 
 See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
 
@@ -587,9 +640,10 @@ See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassP
 | `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, etc.) |
 | `agent-dispatch remove <name>` | Remove an agent |
 | `agent-dispatch list` | List agents with health status and permissions |
+| `agent-dispatch group <add\|list\|inspect\|update\|remove>` | Manage [groups](#groups) — cross-project working sets of agents |
 | `agent-dispatch describe <name>` | Show full configuration for one agent (tri-state tools, project files) |
 | `agent-dispatch test <name> [task] [--stream]` | Test an agent with a dispatch (`--stream` for live progress) |
-| `agent-dispatch doctor` | Diagnose installation: claude CLI, MCP registration, agent health |
+| `agent-dispatch doctor` | Diagnose installation: Claude CLI, MCP registration, agent health, and group membership |
 | `agent-dispatch jobs [--status --limit]` | List async dispatch jobs (most recent first) |
 | `agent-dispatch job <id>` | Show one job: status, progress tail, result preview |
 | `agent-dispatch cancel <id>` | Cancel a pending job (running jobs: use the `dispatch_cancel` MCP tool) |

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

@@ -13,6 +13,8 @@
 
 Each agent runs as a separate `claude -p` session in its own project directory — inheriting that project's MCP servers, CLAUDE.md, and tools. The calling agent just gets the result back.
 
+Related projects can be bundled into a **[group](#groups)** — a shared brief plus a member list — so one session can coordinate work across them (e.g. code repos + an `infra`/Portainer gateway + an `analytics` gateway).
+
 Works with OAuth, API key, and Claude subscription authentication.
 
 > **AI agents:** this README is the canonical doc for *using* the tool — setup: [Quick Start](#quick-start) (every step has a deterministic verify), first call: [`dispatch`](#dispatch), tool selection: [Which Tool to Use](#which-tool-to-use), failure handling: [Error Recovery](#error-recovery). Working *on* this repo instead? See [AGENTS.md](AGENTS.md).
@@ -120,6 +122,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 +168,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 +278,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 +460,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
 
@@ -475,6 +511,23 @@ agents:
     # disallowed_tools:     # block specific tools
     #   - Write
 
+# Optional: bundle related agents into a cross-project working set.
+# A descriptive layer — no router; the orchestrating session coordinates
+# with the normal dispatch tools. See the Groups section above.
+groups:
+  shop:
+    # ORCHESTRATOR-facing: how to coordinate the group. Surfaced by
+    # list_groups/inspect_group, NEVER injected into a member's prompt.
+    description: "After a code change: deploy via infra, then verify via analytics."
+    # MEMBER-facing facts, auto-prepended to dispatch(..., group="shop").
+    shared_context: |
+      Prod runs in Portainer stack "shop". Metrica counter 12345.
+    members:                # reference agents above (many-to-many)
+      - agent: infra
+        use_for: deploy, restart, container logs
+      # - agent: backend
+      #   use_for: orders/payments endpoints
+
 settings:
   default_timeout: 300
   # default_permission_mode: bypassPermissions  # inherited by all agents
@@ -544,7 +597,7 @@ agent-dispatch MCP server
 - **Cost visibility** — `max_budget_usd` per agent or globally; a dispatch whose cost exceeds it returns `budget_exceeded: true` + a hint (post-hoc — the `claude` CLI has no spend cap, so the overage can be flagged but not prevented).
 - **Concurrency** — `max_concurrency` (default: 5) caps parallel `claude -p` processes. Note: the sync and async dispatch paths use separate semaphores, so the worst-case total is `2 × max_concurrency`.
 - **Timeout** — per-agent or global (default: 300s). Orphaned processes are cleaned up.
-- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only successes are cached. Sessions and dialogues are never cached.
+- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only successes are cached. Sessions and dialogues are never cached. A `group=` dispatch folds the group's `shared_context` into `context`, so different groups cache separately and a plain dispatch is unaffected.
 
 See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
 
@@ -557,9 +610,10 @@ See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassP
 | `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, etc.) |
 | `agent-dispatch remove <name>` | Remove an agent |
 | `agent-dispatch list` | List agents with health status and permissions |
+| `agent-dispatch group <add\|list\|inspect\|update\|remove>` | Manage [groups](#groups) — cross-project working sets of agents |
 | `agent-dispatch describe <name>` | Show full configuration for one agent (tri-state tools, project files) |
 | `agent-dispatch test <name> [task] [--stream]` | Test an agent with a dispatch (`--stream` for live progress) |
-| `agent-dispatch doctor` | Diagnose installation: claude CLI, MCP registration, agent health |
+| `agent-dispatch doctor` | Diagnose installation: Claude CLI, MCP registration, agent health, and group membership |
 | `agent-dispatch jobs [--status --limit]` | List async dispatch jobs (most recent first) |
 | `agent-dispatch job <id>` | Show one job: status, progress tail, result preview |
 | `agent-dispatch cancel <id>` | Cancel a pending job (running jobs: use the `dispatch_cancel` MCP tool) |

agent_dispatch-0.10.0/agents.example.yaml

@@ -0,0 +1,105 @@
+agents:
+  # Infrastructure agent — has Portainer MCP for container management
+  infra:
+    directory: ~/projects/infra
+    description: "Infrastructure agent. MCP servers: portainer. Can check container logs, restart services, inspect Docker state."
+    capabilities:
+      - docker_logs
+      - deploy_debug
+    risky_capabilities:
+      - restart_services
+    timeout: 300
+
+  # Analytics gateway — a browser + Yandex Metrica agent, no codebase of its own.
+  # Its value is its MCP servers + access, not its source. Shared across groups.
+  analytics:
+    directory: ~/projects/analytics
+    description: "Analytics gateway. MCP servers: browser, yandex-metrica. Pulls funnels, conversion, traffic. Read-only."
+    capabilities:
+      - funnel_report
+      - conversion_metrics
+    permission_mode: bypassPermissions  # runs non-interactively against read-only sources
+    timeout: 300
+
+  # Backend agent — source code, tests, database
+  backend:
+    directory: ~/projects/backend
+    description: "Backend API agent. Python, FastAPI, PostgreSQL. Can modify code, run tests, check migrations."
+    capabilities:
+      - code_debug
+      - run_tests
+      - inspect_migrations
+    timeout: 300
+    model: null  # use default model
+
+  # Agent with permission controls — useful when you want to restrict tool access
+  staging-db:
+    directory: ~/projects/staging-db
+    description: "Read-only database agent. Can query staging DB but not modify data."
+    timeout: 120
+    permission_mode: bypassPermissions  # skip permission prompts (agent runs non-interactively)
+    allowed_tools:                      # only these tools are available
+      - Read
+      - Grep
+      - Bash
+    # disallowed_tools:                 # alternatively, block specific tools
+    #   - Write
+    #   - Edit
+
+  # Frontend agent
+  # frontend:
+  #   directory: ~/projects/frontend
+  #   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
+        use_for: funnel + conversion verification
+
+  # A second product reusing the SHARED infra/analytics gateways. Membership is
+  # many-to-many — gateways are referenced, not owned, so one analytics/infra
+  # agent serves every product.
+  blog:
+    description: "Content site. Same deploy-then-verify loop via the shared gateways."
+    shared_context: |
+      Production runs in Portainer stack "blog". Metrica counter 67890.
+    members:
+      - agent: infra
+        use_for: deploy, logs
+      - agent: analytics
+        use_for: pageview + bounce-rate checks
+
+settings:
+  default_timeout: 300
+  max_dispatch_depth: 3           # recursion protection: A -> B -> A
+  max_concurrency: 5              # max parallel claude -p processes
+  # default_max_budget_usd: 1.0   # flags results over this cost (budget_exceeded + hint; post-hoc, can't prevent the spend)
+  # default_permission_mode: bypassPermissions  # inherited by agents without override
+  # default_allowed_tools:         # inherited by agents without override
+  #   - Bash
+  #   - Read
+  #   - Edit
+  cache:
+    enabled: true
+    ttl: 300                       # seconds; identical (agent, task, context) requests are cached
+    max_size: 1000                 # max cached entries; oldest is evicted first (FIFO)

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

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.8.0"
+version = "0.10.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.10.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.10.0"