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

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

@@ -28,7 +28,7 @@ pip install -e ".[dev]"
 
 ```bash
 ruff check src/ tests/
-python3 -m pytest tests/ -v   # 466 tests, ~2s — all subprocess calls are mocked
+python3 -m pytest tests/ -v   # 495 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`.
@@ -36,14 +36,20 @@ Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.whi
 ## Non-obvious invariants (violating these breaks real behavior)
 
 - `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.
+- Error-type precedence on an `is_error` payload (`_build_error_result`): the CLI's own budget stop wins, then `denied_tools` non-empty ⇒ `error_type="permission"` regardless of the error text, then text classification.
 - **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`).
-- `JobStore.finish`/`fail` refuse already-terminal jobs (returns `None`) — this closes the race with force-cancel; never "fix" it by overwriting.
+- `JobStore.finish`/`fail` refuse already-terminal jobs (returns `None`) — this closes the race with force-cancel; never "fix" it by overwriting. `mark_running` likewise refuses any job that isn't `pending`, so a stale or duplicate worker can't resurrect a finished one.
+- "Is this group member missing?" has exactly one implementation: `DispatchConfig.unknown_group_members()`. Any new surface that lists or validates membership calls it instead of re-deriving the check.
 - Cancelling a *running* job requires the in-memory `_running_procs` registry (server.py) — the job is marked `cancelled` **before** the subprocess is killed. Don't persist PIDs to disk (PID reuse after restart could kill an unrelated process).
-- `max_budget_usd` is **post-hoc**: `_apply_budget` (runner.py) sets `budget_exceeded` + `hint` after the cost is known; it never fails the dispatch.
+- `max_budget_usd` is enforced **by the claude CLI** (`_build_command` passes `--max-budget-usd`): a run stopped at the cap comes back `is_error` with no `result` text, and `_build_error_result` turns it into `error_type="budget"` + `budget_exceeded=True` + a resumable `session_id`. `_apply_budget` is the *secondary*, post-hoc signal for an overshoot that didn't stop the run; it never fails a dispatch.
+- A CLI error payload can have no `result` field at all — the reason lives in `errors` / `subtype`. Read it via `_cli_error_details`, never assume `result` is populated on failure.
+
+## Deliberately not built
+
+These were considered — some fully implemented — and cut on purpose: an agent router / auto-dispatch (`recommend_agent` / `dispatch_auto`, removed before 0.8.0 — a keyword scorer adds little over the calling LLM at a handful of agents, and auto-dispatch can spend money or mutate a repo on a guess); groups as an execution engine (they are a descriptive layer — no routing, no per-group settings); an agent-dispatch-side budget ledger across dispatches (the CLI's own `--max-budget-usd` covers a single run; anything cumulative would need state we deliberately don't keep). Please open an issue with the use case before adding any of them.
 
 ## Conventions
 
@@ -51,8 +57,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/`, 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`, ...).
+[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/`, 495 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.9.0 → agent_dispatch-0.11.0}/CHANGELOG.md

@@ -7,6 +7,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-07-27
+
+The spend cap was already real — now the result says so.
+
+### Added
+- **`error_type: "budget"`.** The `claude` CLI enforces the `--max-budget-usd`
+  value agent-dispatch has always passed: when the cap is reached it ends the
+  session and reports the failure with no `result` text. That payload used to
+  surface as the useless `"reported an error with no details"` fallback with
+  `error_type: "cli_error"`. It is now classified as `budget`, carries the
+  CLI's own reason (`Reached maximum budget ($X)`), sets
+  `budget_exceeded: true`, and spells out the recovery — raise the cap, pick a
+  cheaper model, or resume the partial session via the returned `session_id`.
+  `agent-dispatch test` prints a matching diagnosis.
+
+### Fixed
+- **Error details are no longer dropped.** CLI-level failures (budget
+  exhausted, max turns, execution errors) put their reason in `errors` /
+  `subtype` rather than `result`. Both `dispatch` and `dispatch_stream` now
+  read those fields when `result` is empty, so the error text names the actual
+  problem. Values are capped (5 entries × 300 chars) like every other field
+  read back from the subprocess.
+- **Job files can no longer be corrupted by a concurrent writer.** `JobStore`
+  wrote through a fixed `<id>.tmp` path; the in-process lock does not cover
+  the CLI (`cancel` / `gc`) and the MCP server writing the same job at the
+  same time, and the rename could publish interleaved JSON. Each write now
+  uses a unique temp name and cleans it up if the write fails.
+
+### Changed
+- The `is_error` handling in `dispatch` and `dispatch_stream` is now one
+  shared `_build_error_result()` with an explicit precedence: budget stop >
+  denied tools > text classification.
+- Documentation corrected throughout: `max_budget_usd` is enforced per
+  dispatch by the CLI, with the `budget_exceeded` flag as the secondary
+  post-hoc signal for a run that overshot without being stopped. Previous
+  releases described it as post-hoc only.
+
+## [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.
@@ -361,7 +426,11 @@ cache bounding, and stale-job recovery.
 - Dependabot for `pip` + `github-actions`, GitHub Actions pinned to
   commit SHAs for supply-chain integrity.
 
-[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/ginkida/agent-dispatch/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/ginkida/agent-dispatch/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/ginkida/agent-dispatch/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/ginkida/agent-dispatch/compare/v0.6.0...v0.8.0
 [0.6.0]: https://github.com/ginkida/agent-dispatch/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/ginkida/agent-dispatch/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/ginkida/agent-dispatch/compare/v0.3.0...v0.4.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.9.0
+Version: 0.11.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).
@@ -231,7 +233,7 @@ dispatch(
 }
 ```
 
-**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `cli_error` (other failures). Permission errors include an actionable hint.
+**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `budget` (the `claude` CLI stopped the session at `max_budget_usd`), `cli_error` (other failures). Permission and budget errors include an actionable hint.
 
 **Resumable timeouts:** every fresh dispatch pre-assigns a session UUID (`--session-id`), so a timed-out dispatch still returns a `session_id` — the partial transcript survives the kill. The timeout error spells out the recovery: resume with `dispatch_session(agent, "Continue where you left off", session_id=...)`, retry with a bigger `timeout_seconds`, or use `dispatch_async`.
 
@@ -501,13 +503,14 @@ Failures are deterministic: check `success`, then branch on `error_type`.
 | `timeout` | Process killed at the timeout | Resume the partial work: `dispatch_session(agent, "Continue where you left off", session_id=<from the error text>)`. Or retry with a bigger `timeout_seconds=`, or use `dispatch_async`. |
 | `not_found` | Agent directory or `claude` CLI missing | `list_agents()` → check `healthy`. Re-add the agent with an existing path, or run `agent-dispatch doctor` to find what's missing. |
 | `recursion` | Dispatch nesting exceeded `max_dispatch_depth` (default 3) | Don't dispatch from dispatched agents; if the nesting is intentional, raise `max_dispatch_depth` in settings. |
+| `budget` | The `claude` CLI ended the session at the `max_budget_usd` spend cap — the answer is incomplete | Raise the cap (`update_agent(name, max_budget_usd=2.0)`), switch to a cheaper `model`, or split the task. The partial session is resumable: `dispatch_session(agent, "Continue where you left off", session_id=<from the result>)`. |
 | `cli_error` | Anything else from the `claude` subprocess | Read the `error` text; run `agent-dispatch doctor` for environment issues; retry once if transient. |
 
 Three soft signals that arrive with `success: true`:
 
 - **`denied_tools` + `hint`** — the agent finished but some tool calls were blocked; the result may be incomplete. Grant access (see the `permission` row) and re-dispatch.
 - **`parsed_result: null` with `response_format="json"`** — the reply wasn't valid JSON; the raw text is still in `result`. Caveat: an agent that *can't* comply returns `{"error": "<reason>"}` — which parses successfully — so also check `parsed_result` for an `"error"` key.
-- **`budget_exceeded: true`** — `cost_usd` exceeded the agent's `max_budget_usd` (or the settings default). The dispatch is not failed — the money is already spent — but a runaway agent is now visible. Tighten the task, pick a cheaper model, or raise the budget.
+- **`budget_exceeded: true`** — `cost_usd` came in over the agent's `max_budget_usd` (or the settings default) without the CLI stopping the run (the final turn can overshoot the cap). The dispatch is not failed — the money is already spent — but a runaway agent is now visible. Tighten the task, pick a cheaper model, or raise the budget. A run the CLI *did* stop fails with `error_type: "budget"` instead.
 
 Tool-level errors (unknown agent, malformed input) return a plain envelope instead of a `DispatchResult`:
 
@@ -539,6 +542,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
@@ -605,10 +625,10 @@ agent-dispatch MCP server
 - **Argument-injection guard** — structured CLI fields (`session_id`, `model`, `permission_mode`, tool names) that start with `-` are rejected so they can't smuggle extra `claude` flags.
 - **Path-traversal guard** — caller-supplied `job_id`/`ref` values are validated as 32-char hex before any filesystem access.
 - **Owner-only state** — job files (`0o600`) and `agents.yaml` (`0o600`) are written for the owner only; their directories are `0o700`.
-- **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).
+- **Cost control** — `max_budget_usd` per agent or globally is passed to the `claude` CLI as `--max-budget-usd`, so a runaway dispatch is stopped at the cap and comes back as `error_type: "budget"` with a resumable `session_id`. An overshoot that lands over budget without stopping is flagged post-hoc with `budget_exceeded: true` + a hint.
 - **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).
 
@@ -621,9 +641,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.9.0 → agent_dispatch-0.11.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).
@@ -201,7 +203,7 @@ dispatch(
 }
 ```
 
-**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `cli_error` (other failures). Permission errors include an actionable hint.
+**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `budget` (the `claude` CLI stopped the session at `max_budget_usd`), `cli_error` (other failures). Permission and budget errors include an actionable hint.
 
 **Resumable timeouts:** every fresh dispatch pre-assigns a session UUID (`--session-id`), so a timed-out dispatch still returns a `session_id` — the partial transcript survives the kill. The timeout error spells out the recovery: resume with `dispatch_session(agent, "Continue where you left off", session_id=...)`, retry with a bigger `timeout_seconds`, or use `dispatch_async`.
 
@@ -471,13 +473,14 @@ Failures are deterministic: check `success`, then branch on `error_type`.
 | `timeout` | Process killed at the timeout | Resume the partial work: `dispatch_session(agent, "Continue where you left off", session_id=<from the error text>)`. Or retry with a bigger `timeout_seconds=`, or use `dispatch_async`. |
 | `not_found` | Agent directory or `claude` CLI missing | `list_agents()` → check `healthy`. Re-add the agent with an existing path, or run `agent-dispatch doctor` to find what's missing. |
 | `recursion` | Dispatch nesting exceeded `max_dispatch_depth` (default 3) | Don't dispatch from dispatched agents; if the nesting is intentional, raise `max_dispatch_depth` in settings. |
+| `budget` | The `claude` CLI ended the session at the `max_budget_usd` spend cap — the answer is incomplete | Raise the cap (`update_agent(name, max_budget_usd=2.0)`), switch to a cheaper `model`, or split the task. The partial session is resumable: `dispatch_session(agent, "Continue where you left off", session_id=<from the result>)`. |
 | `cli_error` | Anything else from the `claude` subprocess | Read the `error` text; run `agent-dispatch doctor` for environment issues; retry once if transient. |
 
 Three soft signals that arrive with `success: true`:
 
 - **`denied_tools` + `hint`** — the agent finished but some tool calls were blocked; the result may be incomplete. Grant access (see the `permission` row) and re-dispatch.
 - **`parsed_result: null` with `response_format="json"`** — the reply wasn't valid JSON; the raw text is still in `result`. Caveat: an agent that *can't* comply returns `{"error": "<reason>"}` — which parses successfully — so also check `parsed_result` for an `"error"` key.
-- **`budget_exceeded: true`** — `cost_usd` exceeded the agent's `max_budget_usd` (or the settings default). The dispatch is not failed — the money is already spent — but a runaway agent is now visible. Tighten the task, pick a cheaper model, or raise the budget.
+- **`budget_exceeded: true`** — `cost_usd` came in over the agent's `max_budget_usd` (or the settings default) without the CLI stopping the run (the final turn can overshoot the cap). The dispatch is not failed — the money is already spent — but a runaway agent is now visible. Tighten the task, pick a cheaper model, or raise the budget. A run the CLI *did* stop fails with `error_type: "budget"` instead.
 
 Tool-level errors (unknown agent, malformed input) return a plain envelope instead of a `DispatchResult`:
 
@@ -509,6 +512,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
@@ -575,10 +595,10 @@ agent-dispatch MCP server
 - **Argument-injection guard** — structured CLI fields (`session_id`, `model`, `permission_mode`, tool names) that start with `-` are rejected so they can't smuggle extra `claude` flags.
 - **Path-traversal guard** — caller-supplied `job_id`/`ref` values are validated as 32-char hex before any filesystem access.
 - **Owner-only state** — job files (`0o600`) and `agents.yaml` (`0o600`) are written for the owner only; their directories are `0o700`.
-- **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).
+- **Cost control** — `max_budget_usd` per agent or globally is passed to the `claude` CLI as `--max-budget-usd`, so a runaway dispatch is stopped at the cap and comes back as `error_type: "budget"` with a resumable `session_id`. An overshoot that lands over budget without stopping is flagged post-hoc with `budget_exceeded: true` + a hint.
 - **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).
 
@@ -591,9 +611,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.9.0 → agent_dispatch-0.11.0}/agents.example.yaml

@@ -10,6 +10,17 @@ agents:
       - 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
@@ -62,13 +73,28 @@ groups:
         use_for: orders/payments endpoints, migrations
       - agent: infra
         use_for: deploy, restart, container logs
-      # - agent: analytics   # a shared gateway agent could also live here
+      - 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_max_budget_usd: 1.0   # spend cap per dispatch, passed to claude as --max-budget-usd
+                                  # (a run stopped at the cap fails with error_type: budget)
   # default_permission_mode: bypassPermissions  # inherited by agents without override
   # default_allowed_tools:         # inherited by agents without override
   #   - Bash

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

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.9.0"
+version = "0.11.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.9.0 → agent_dispatch-0.11.0}/src/agent_dispatch/__init__.py

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

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

@@ -423,6 +423,12 @@ def test(name: str, task: str, stream: bool, timeout: int | None) -> None:
             click.echo(click.style("Diagnosis: timeout", fg="yellow"))
             click.echo(f"  agent-dispatch test {name} --timeout 600    # one-off")
             click.echo(f"  agent-dispatch update {name} --timeout 600  # permanent")
+        elif result.error_type == "budget":
+            click.echo()
+            click.echo(click.style("Diagnosis: spend cap reached", fg="yellow"))
+            click.echo("The claude CLI stopped the session at --max-budget-usd.")
+            click.echo(f"  agent-dispatch update {name} --max-budget-usd 2.0  # raise the cap")
+            click.echo(f"  agent-dispatch update {name} --model haiku         # cheaper model")
         raise SystemExit(1)
 
 
@@ -563,12 +569,13 @@ def group_list() -> None:
         click.echo(f"  {click.style(name, bold=True)} ({len(grp.members)} member(s))")
         if grp.description:
             click.echo(f"    desc: {grp.description}")
+        unknown_members = set(config.unknown_group_members(grp))
         rendered: list[str] = []
         for m in grp.members:
-            if m.agent in config.agents:
-                rendered.append(m.agent)
-            else:
+            if m.agent in unknown_members:
                 rendered.append(click.style(f"{m.agent}(unknown)", fg="red"))
+            else:
+                rendered.append(m.agent)
         if rendered:
             click.echo(f"    members: {', '.join(rendered)}")
         click.echo(f"    shared context: {'yes' if grp.shared_context.strip() else 'no'}")
@@ -593,8 +600,9 @@ def group_inspect(name: str) -> None:
         for line in grp.shared_context.splitlines():
             click.echo(f"    {line}")
     click.echo(f"  members ({len(grp.members)}):")
+    unknown_members = set(config.unknown_group_members(grp))
     for m in grp.members:
-        marker = "" if m.agent in config.agents else click.style(" (unknown)", fg="red")
+        marker = click.style(" (unknown)", fg="red") if m.agent in unknown_members else ""
         hint = f" — {m.use_for}" if m.use_for else ""
         click.echo(f"    - {m.agent}{marker}{hint}")
     if not grp.members:
@@ -750,6 +758,32 @@ def doctor() -> None:
             except OSError as e:
                 fail(f"{name}: directory unreadable - {e}")
 
+    section("Groups")
+    if config is None:
+        warn("Skipped (config could not be loaded)")
+    elif not config.groups:
+        ok("No groups configured")
+    else:
+        for name, group in config.groups.items():
+            unknown = config.unknown_group_members(group)
+            if unknown:
+                missing = ", ".join(unknown)
+                fail(f"{name}: unknown member(s): {missing}")
+                click.echo(
+                    f"    Fix by recreating: agent-dispatch group remove {name} && "
+                    f"agent-dispatch group add {name} --member ... (or edit agents.yaml)"
+                )
+            elif not group.members:
+                warn(f"{name}: no members configured")
+                click.echo(
+                    f"    Add members by recreating: agent-dispatch group remove {name} && "
+                    f"agent-dispatch group add {name} --member agent1 --member agent2"
+                )
+            else:
+                count = len(group.members)
+                suffix = "member" if count == 1 else "members"
+                ok(f"{name}: {count} {suffix}")
+
     section("Summary")
     issues = counters["issues"]
     warnings = counters["warnings"]

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

@@ -80,8 +80,13 @@ def _collect_mcp_servers(directory: Path) -> list[str]:
         if path.exists():
             try:
                 data = json.loads(path.read_text(encoding="utf-8"))
-                servers.extend(data.get("mcpServers", {}).keys())
-            except (json.JSONDecodeError, KeyError):
+                if not isinstance(data, dict):
+                    raise ValueError("top-level JSON value is not an object")
+                configured = data.get("mcpServers", {})
+                if not isinstance(configured, dict):
+                    raise ValueError("mcpServers is not an object")
+                servers.extend(str(name) for name in configured)
+            except (OSError, UnicodeDecodeError, json.JSONDecodeError, ValueError):
                 logger.debug("Failed to parse MCP config: %s", path)
     return list(dict.fromkeys(servers))  # deduplicate, preserve order
 
@@ -137,7 +142,12 @@ def auto_describe(directory: Path) -> str:
     claude_md = directory / "CLAUDE.md"
     if claude_md.exists():
         sentences: list[str] = []
-        for line in claude_md.read_text(encoding="utf-8").strip().splitlines()[:40]:
+        try:
+            lines = claude_md.read_text(encoding="utf-8").strip().splitlines()[:40]
+        except (OSError, UnicodeDecodeError):
+            logger.debug("Failed to read CLAUDE.md: %s", claude_md)
+            lines = []
+        for line in lines:
             stripped = line.strip()
             if stripped and not stripped.startswith("#") and not stripped.startswith("--"):
                 sentences.append(stripped)
@@ -150,7 +160,12 @@ def auto_describe(directory: Path) -> str:
     if not parts:
         readme = directory / "README.md"
         if readme.exists():
-            for line in readme.read_text(encoding="utf-8").strip().splitlines()[:20]:
+            try:
+                lines = readme.read_text(encoding="utf-8").strip().splitlines()[:20]
+            except (OSError, UnicodeDecodeError):
+                logger.debug("Failed to read README.md: %s", readme)
+                lines = []
+            for line in lines:
                 stripped = line.strip()
                 if (
                     stripped
@@ -165,9 +180,17 @@ def auto_describe(directory: Path) -> str:
     # pyproject.toml — project description
     pyproject = directory / "pyproject.toml"
     if pyproject.exists():
-        for line in pyproject.read_text(encoding="utf-8").splitlines():
+        try:
+            lines = pyproject.read_text(encoding="utf-8").splitlines()
+        except (OSError, UnicodeDecodeError):
+            logger.debug("Failed to read pyproject.toml: %s", pyproject)
+            lines = []
+        for line in lines:
             if line.strip().startswith("description"):
-                desc = line.split("=", 1)[1].strip().strip('"').strip("'")
+                _, separator, value = line.partition("=")
+                if not separator:
+                    continue
+                desc = value.strip().strip('"').strip("'")
                 if desc:
                     parts.append(desc)
                 break
@@ -177,9 +200,11 @@ def auto_describe(directory: Path) -> str:
     if pkg_json.exists():
         try:
             pkg = json.loads(pkg_json.read_text(encoding="utf-8"))
-            if pkg.get("description"):
-                parts.append(pkg["description"])
-        except (json.JSONDecodeError, KeyError):
+            if isinstance(pkg, dict):
+                desc = pkg.get("description")
+                if isinstance(desc, str) and desc.strip():
+                    parts.append(desc)
+        except (OSError, UnicodeDecodeError, json.JSONDecodeError):
             logger.debug("Failed to parse package.json: %s", pkg_json)
 
     # MCP servers — critical for understanding what tools this agent has

{agent_dispatch-0.9.0 → agent_dispatch-0.11.0}/src/agent_dispatch/jobs.py

@@ -99,10 +99,22 @@ class JobStore:
 
     def _write(self, job: Job) -> None:
         path = self._path(job.id)
-        tmp = path.with_suffix(".tmp")
-        tmp.write_text(job.model_dump_json(indent=2, exclude_none=True), encoding="utf-8")
-        _chmod_quiet(tmp, 0o600)  # owner-only before it becomes visible
-        os.replace(tmp, path)
+        # Unique temp name per write: `self._lock` only serializes writers inside
+        # one process, but the CLI (cancel/gc) and the MCP server touch the same
+        # files. A shared `<id>.tmp` could be written by both at once and the
+        # rename would publish interleaved, unparseable JSON.
+        tmp = path.with_name(f"{job.id}.{uuid.uuid4().hex}.tmp")
+        try:
+            tmp.write_text(job.model_dump_json(indent=2, exclude_none=True), encoding="utf-8")
+            _chmod_quiet(tmp, 0o600)  # owner-only before it becomes visible
+            os.replace(tmp, path)
+        except OSError:
+            # Don't leave a half-written temp file behind on a failed write.
+            try:
+                tmp.unlink(missing_ok=True)
+            except OSError:  # pragma: no cover - best effort
+                logger.debug("Failed to clean up temp file %s", tmp)
+            raise
 
     def create(
         self,
@@ -192,17 +204,18 @@ class JobStore:
     def mark_running(self, job_id: str) -> Job | None:
         """Mark a pending job as running.
 
-        Returns the updated job, or None if the job is missing OR has already
-        been cancelled. Refusing to run a cancelled job closes the race with
-        ``cancel()``: both take ``self._lock``, so whichever wins, the worker
-        either sees ``cancelled`` (and skips) or sets ``running`` first (and
-        cancel then refuses).
+        Returns the updated job, or None unless the job exists and is still
+        pending. Refusing every non-pending state prevents a duplicate worker
+        from resurrecting a completed/failed/cancelled job. It also closes the
+        race with ``cancel()``: both take ``self._lock``, so whichever wins,
+        the worker either sees ``cancelled`` (and skips) or sets ``running``
+        first (and cancel then refuses).
         """
         with self._lock:
             job = self.get(job_id)
             if job is None:
                 return None
-            if job.status == "cancelled":
+            if job.status != "pending":
                 return None
             job.status = "running"
             job.started_at = time.time()

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

@@ -158,6 +158,10 @@ class DispatchConfig(BaseModel):
             validate_agent_name(name)
         return self
 
+    def unknown_group_members(self, group: DispatchGroup) -> list[str]:
+        """Member agent names in `group` that aren't in `self.agents` (sorted, deduped)."""
+        return sorted({m.agent for m in group.members if m.agent not in self.agents})
+
 
 class DispatchResult(BaseModel):
     """Result of a dispatch call."""
@@ -170,7 +174,7 @@ class DispatchResult(BaseModel):
     duration_ms: int | None = None
     num_turns: int | None = None
     error: str | None = None
-    error_type: str | None = None  # permission, timeout, recursion, not_found, cli_error
+    error_type: str | None = None  # permission, timeout, recursion, not_found, budget, cli_error
     # Set when response_format="json" was requested AND the agent's result
     # parsed cleanly. None means: not requested, or requested but unparseable.
     parsed_result: Any | None = None