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

{agent_dispatch-0.10.0 → agent_dispatch-0.12.0}/.github/workflows/ci.yml

@@ -18,9 +18,9 @@ jobs:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
 
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: ${{ matrix.python-version }}
 

{agent_dispatch-0.10.0 → agent_dispatch-0.12.0}/.github/workflows/publish.yml

@@ -15,9 +15,9 @@ jobs:
       id-token: write   # OIDC token for PyPI Trusted Publisher
       contents: read    # checkout the tagged source
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
 
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: "3.12"
 

agent_dispatch-0.12.0/AGENTS.md

@@ -0,0 +1,79 @@
+# AGENTS.md
+
+Guidance for AI coding agents working on this repository.
+
+> **Using agent-dispatch** (not developing it)? Read [README.md](README.md) — it has the full setup path with verify steps and the complete MCP tool reference. This file is for contributing to the codebase.
+
+## What this project is
+
+MCP server + CLI that lets Claude Code agents delegate tasks to agents in other project directories. One sync core, two surfaces:
+
+| File | Role |
+|------|------|
+| `src/agent_dispatch/runner.py` | Sync subprocess wrapper around `claude -p` — the actual work |
+| `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 |
+
+## Dev setup
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Gates — both must pass before a change is done (CI rejects otherwise)
+
+```bash
+ruff check src/ tests/
+python3 -m pytest tests/ -v   # 561 tests, ~4s
+```
+
+Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.which` + `subprocess.run`/`Popen`; server tests mock `_get_config` + `runner.dispatch`. The one exception is `TestStreamPipeHandling`, which spawns a short-lived *python* subprocess: a pipe deadlock lives in the OS pipe buffer, so a mocked `Popen` structurally cannot reproduce it.
+
+## 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.
+- 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. `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 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.
+- **Both subprocess pipes must be drained concurrently.** `dispatch_stream` reads stdout in a loop while a daemon thread drains stderr; reading stderr only after the loop deadlocks any child that writes more than ~64 KiB to it (the child blocks in `write(2)`, never emits its result, and the dispatch dies at the timeout). `dispatch()` is immune only because `subprocess.run(capture_output=True)` uses `communicate()`.
+- **A received `result` event outranks the timeout flag.** The agent finished and was billed; a lingering process is a cleanup problem, reported as a `hint`, not a failure.
+- **The timeout must kill the process *tree*, not the child.** `dispatch_stream` spawns with `start_new_session=True` and `_kill_process_tree` sends SIGKILL to the group: a grandchild that inherited stdout keeps the read loop parked long past the deadline otherwise. `killpg` is guarded on a positive pid — `killpg(0)` would signal the dispatcher's own group.
+- **Never `close()` a pipe another thread may still be reading.** `close()` waits on the reader's buffer lock with *no timeout*, so it would hang the dispatch forever — the bounded `join()` before it buys nothing. `dispatch_stream` skips the stderr close while the drain thread is alive and lets the daemon reader + Popen finalizer release the fd. This is not hypothetical: a stdio MCP server inherits the child's `stderr`, so the pipe often has no EOF even after `claude` exits cleanly.
+- **No `await` inside `config_lock()`.** `ProcessLock`'s in-process guard is a `threading.RLock` — re-entrant per *thread* — and every MCP tool coroutine runs on the one event-loop thread. Suspending in the critical section lets a second coroutine re-enter the "held" lock and interleave its own load/mutate/save. Collect warnings as data, emit them after the `with` block (`test_no_await_inside_the_config_lock` enforces this by AST).
+- Cross-process locks are acquired with a **bounded** wait, never a blocking `flock`: the server takes them on its event-loop thread, so a wedged holder would freeze every tool. After the deadline it proceeds unlocked and logs — a possible lost update beats a permanent freeze.
+- `recover_stale` sweeps `pending` on a **much longer** threshold than `running`: the jobs directory is shared by every `agent-dispatch serve`, so an hours-old pending job may still be queued behind another live server's semaphore.
+- Pydantic does **not** validate on assignment. `Field(ge=...)` guards only the *load* path; every mutation surface (CLI `add`/`update`, MCP `add_agent`/`update_agent`) needs its own boundary check, or the bound escapes as a raw `ValidationError`.
+- Every state file (`agents.yaml`, job files) is written **temp file + `os.replace`**, never in place, and every load/mutate/save is wrapped in `config.ProcessLock` — the CLI and the MCP server are separate processes writing the same files, so a thread lock alone loses updates.
+- Anything that changes an agent's config must call `_invalidate_agent_cache` — the cache key holds the agent *name*, not its directory or permissions.
+- Only *clean* successes are cached: `cache.put` refuses failures, `denied_tools` results, and `budget_exceeded` results, so the documented "grant access, then re-dispatch" recovery is never short-circuited.
+- Remediation text is a contract: a hint that names a flag must name one that exists (`test_printed_budget_hint_is_a_runnable_command` feeds the printed flags back into the CLI). Run the command you print.
+- MCP tools that load config carry `@_config_guard` under `@mcp.tool()` so a broken `agents.yaml` returns the `{"error": ...}` envelope instead of a raw traceback.
+
+- Tests must not touch anything outside `tmp_path`. `test_server.py`'s autouse `_reset_globals` and `test_cli.py`'s `_isolated_config` redirect **both** `AGENT_DISPATCH_CONFIG` and `AGENT_DISPATCH_JOBS_DIR`: a mutation tool that bails out early (unknown agent) still takes `config_lock()` first, which would otherwise create a lock file beside the developer's real config.
+
+## 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
+
+Python ≥ 3.10 · `from __future__ import annotations` everywhere · Pydantic v2 · Click (CLI) + FastMCP (server) · ruff, line length 100 · all MCP tools return JSON strings, errors as `{"error": "..."}`.
+
+## When adding a feature, check every layer
+
+`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/`, 561 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.10.0 → agent_dispatch-0.12.0}/CHANGELOG.md

@@ -7,6 +7,163 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-07-29
+
+Reliability pass over the streaming path, config durability, and the tool
+boundary — found by an exhaustive audit of every module.
+
+### Fixed
+- **`mcp` is capped below 2.0.** The dependency was declared as
+  `mcp[cli]>=1.2.0` with no upper bound, and `mcp` 2.0 removed
+  `mcp.server.fastmcp` (FastMCP became `mcp.server.mcpserver.MCPServer`). Any
+  fresh install therefore resolved 2.x and died with
+  `ModuleNotFoundError: No module named 'mcp.server.fastmcp'` the moment
+  `agent-dispatch serve` started — i.e. **0.11.0 was broken for new installs**.
+  Pinned to `>=1.2.0,<2` (verified against 1.29.0); the cap lifts when
+  `server.py` is ported to the 2.x API.
+- **A timeout now actually bounds a streaming dispatch.** The timer killed only
+  the direct `claude` process. Any grandchild that inherited its stdout — a
+  backgrounded dev server, a `run_in_background` Bash call, a watcher — kept
+  that pipe from reaching EOF, so the read loop stayed parked for the
+  grandchild's entire lifetime: the deadline was ignored, the concurrency slot
+  stayed held, and `dispatch_cancel` could not free it. The child is now spawned
+  in its own process group and the timeout kills the whole tree (measured on a
+  reproduction: 20.4s → 3.0s for a 3s timeout).
+- **Streaming no longer deadlocks on a chatty agent.** `dispatch_stream` opened
+  `stderr` as a pipe but only read it *after* the stdout loop finished. Once the
+  child wrote more than one pipe buffer (~64 KiB) of stderr — node deprecation
+  warnings, MCP server startup noise, a tool dumping a stack trace — it blocked
+  in `write(2)`, never emitted its result line, and the dispatch burned its
+  entire timeout before coming back as a bogus `error_type: "timeout"`. stderr
+  is now drained concurrently by a daemon reader. This affected the
+  `dispatch_stream` tool, `agent-dispatch test --stream`, **and every async job**
+  (the worker dispatches through the streaming runner). The pipe is never closed
+  while that reader is still blocked on it — a stdio MCP server inherits the
+  child's `stderr` and can outlive it, and `close()` waits on the reader's buffer
+  lock *without a timeout*, which would hang the dispatch outright.
+- **A completed streaming result is no longer thrown away.** `dispatch_stream`
+  checked the timeout flag before the received result, so an agent that
+  answered — and was billed — but whose process lingered past the deadline came
+  back as a failed timeout. The result now wins; when the process had to be
+  killed after answering, that is reported as a `hint`, not a failure.
+- **`dispatch(return_ref=True)` now honors `return_ref` on a cache hit.** It
+  returned the full cached result text inline instead of a compact ref —
+  exactly the context blow-up the caller asked to avoid. (`dispatch_parallel`
+  already handled this correctly.)
+- **`agents.yaml` is written atomically.** `save_config` truncated the live file
+  and rewrote it in place, so an interrupted write (disk full, quota, SIGKILL)
+  left a half-written config that no longer parses — losing every agent and
+  group at once. It now writes a temp file and renames, like `JobStore`.
+- **Concurrent config edits no longer lose each other.** Every mutation is a
+  load / mutate / save-whole-file cycle, and the CLI and the MCP server edit the
+  same file: two overlapping writers each saved their own stale snapshot, so one
+  agent silently disappeared. All mutation sites now hold a cross-process
+  advisory lock (`flock`, degrading to thread-only where unavailable). The same
+  lock now guards job-file transitions, so a CLI `cancel` can no longer be
+  overwritten by the server's `finish`. The lock is taken with a bounded wait
+  (10s) rather than a blocking `flock`, because the MCP server acquires it on
+  its event-loop thread — one wedged holder would otherwise freeze every tool;
+  no mutation suspends while holding it (the in-process guard is re-entrant per
+  *thread*, so an `await` inside the critical section would let a second
+  coroutine walk straight through it).
+- **A symlinked `agents.yaml` keeps its symlink.** The atomic rename would have
+  replaced the link itself, silently orphaning the real file in a dotfiles repo;
+  the link is resolved before the swap.
+- **A malformed `agents.yaml` no longer crashes every MCP tool.** A YAML syntax
+  error or a schema violation escaped as a raw protocol-level exception with no
+  remediation — including from the read-only tools an agent would use to
+  diagnose it. Tools now return the documented `{"error": ..., "hint": ...}`
+  envelope. A non-path `directory:` value raised a bare `TypeError` out of the
+  field validator (breaking the CLI too); it is now a normal validation error.
+- **Stale results are no longer served after an agent's config changes.** The
+  cache key contains the agent *name*, not its directory, permission set or
+  model — so the documented remove-and-re-add flow kept serving the previous
+  project's answers for the rest of the TTL. `add_agent` / `update_agent` /
+  `remove_agent` now invalidate that agent's cached results.
+- **Successful-but-degraded results are no longer cached.** A dispatch that
+  answered with `denied_tools` (or over budget) was cached for the full TTL,
+  which made the documented "grant access, then re-dispatch" recovery a no-op.
+- **`agent-dispatch gc --days 0` (or negative) no longer silently purges every
+  terminal job** — including `return_ref` results a caller was about to fetch.
+  It is rejected, matching the `dispatch_gc` MCP tool; use the new `--all` flag
+  to purge everything on purpose.
+- **The budget hints now name a flag that exists.** Both the runner's
+  `error_type: "budget"` hint and `agent-dispatch test` told the user to run
+  `agent-dispatch update <name> --max-budget-usd`, but the option was
+  `--max-budget`, so the copy-pasted command failed. `--max-budget-usd` is now
+  an accepted alias on `add` and `update`.
+- **A negative timeout can no longer brick an agent.** `-5` was written straight
+  to `agents.yaml`, reached `subprocess.run(timeout=-5)`, and made every
+  dispatch fail instantly with a nonsensical "timed out after -5s". Rejected now
+  at the model, the MCP tool, and the CLI; negative budgets likewise, on both
+  `add` and `update` (they put a token starting with `-` on the `claude` command
+  line, and pydantic does not validate on assignment — the boundary checks are
+  what actually guard the mutation paths).
+- **Jobs stuck in `pending` are recovered.** `recover_stale` only swept
+  `running`, and `gc` only deletes terminal jobs — so a job whose worker never
+  started (server killed while it was queued) stayed pending forever: an eternal
+  poll target and permanent disk growth. Pending uses a far longer threshold
+  (24×) than running: the jobs directory is shared by every `agent-dispatch
+  serve`, and an hours-old pending job may still be queued in another live
+  server.
+- **`dispatch` survives an unexpected CLI payload.** A non-object JSON body, or
+  a `result` field that is not a string, raised out of the runner instead of
+  returning a `DispatchResult`. Exit code 0 with no output at all is now a
+  failure rather than a cached empty success.
+- **`dispatch_parallel` returns an error envelope for a non-string `agent` or
+  `task`** instead of raising `TypeError`, and the aggregator now receives a
+  `return_ref` item's summary (labelled as a preview) instead of an empty body.
+- The prompt is no longer scanned when locating flags: a task whose text is
+  exactly `--output-format` or `--session-id` rewrote the prompt instead of the
+  flag. The cache also hands back a copy, so a caller mutating a result cannot
+  corrupt the entry for everyone else.
+
+### Added
+- `agent-dispatch gc --all` — purge every terminal job regardless of age.
+- `--max-budget-usd` as an alias for `--max-budget` on `add` and `update`.
+- `DispatchCache.invalidate_agent(name)` and `config.ProcessLock` /
+  `config.config_lock()`.
+- 66 tests (561 total), including real-subprocess regression tests for the
+  stderr deadlock, the inherited-pipe hang and the process-tree timeout — a
+  mocked `Popen` structurally cannot reproduce any of them.
+
+## [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.
@@ -389,7 +546,12 @@ 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.12.0...HEAD
+[0.12.0]: https://github.com/ginkida/agent-dispatch/compare/v0.11.0...v0.12.0
+[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.10.0 → agent_dispatch-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.10.0
+Version: 0.12.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
@@ -20,7 +20,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.10
 Requires-Dist: click>=8.0
-Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: mcp[cli]<2,>=1.2.0
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
@@ -233,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`.
 
@@ -348,7 +348,7 @@ Run multiple tasks concurrently. Much faster than sequential `dispatch` calls.
 
 Same as `dispatch` but shows live progress while the agent works. Use for long-running tasks. Not cached.
 
-Parameters are the same as `dispatch` except `return_ref`/`summary_chars` (streaming is incompatible with ref-mode).
+Parameters are the same as `dispatch` except `return_ref`/`summary_chars` (streaming is incompatible with ref-mode) and `group` (group context injection is supported only on `dispatch` and per-item in `dispatch_parallel`).
 
 ### `dispatch_dialogue`
 
@@ -393,6 +393,8 @@ Register a new project directory as an agent. Description is auto-generated from
 | `permission_mode` | string | no | Permission mode (e.g. `default`, `plan`, `bypassPermissions`) |
 | `allowed_tools` | string | no | Comma-separated allowed tools (e.g. `"Bash,Read,Edit"`) |
 | `disallowed_tools` | string | no | Comma-separated disallowed tools |
+| `capabilities` | string | no | Comma-separated capability labels (e.g. `"docker_logs,deploy_debug"`) |
+| `risky_capabilities` | string | no | Comma-separated high-risk labels (e.g. `"restart_services"`) |
 
 ### `update_agent`
 
@@ -408,6 +410,10 @@ Update an existing agent's configuration. Only non-empty fields are changed. Pas
 | `permission_mode` | string | no | Permission mode. `"none"` to clear |
 | `allowed_tools` | string | no | Comma-separated. `"none"` to clear |
 | `disallowed_tools` | string | no | Comma-separated. `"none"` to clear |
+| `capabilities` | string | no | Comma-separated. `"none"` to clear |
+| `risky_capabilities` | string | no | Comma-separated. `"none"` to clear |
+
+Changing an agent's config drops that agent's cached results — the cache key holds the agent *name*, so a re-pointed or re-permissioned agent would otherwise keep answering from the previous config for the rest of the TTL. The same applies to `add_agent` and `remove_agent`.
 
 ### `remove_agent`
 
@@ -500,16 +506,17 @@ Failures are deterministic: check `success`, then branch on `error_type`.
 | `error_type` | Meaning | Recovery |
 |--------------|---------|----------|
 | `permission` | A tool call was denied | `update_agent(name, allowed_tools="Bash,Read")` (least privilege) or `update_agent(name, permission_mode="bypassPermissions")`, then re-dispatch. The `error` text includes a hint with the exact fix. |
-| `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`. |
+| `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`. A *streaming* dispatch that produced its answer before the deadline returns that answer with a `hint` instead of failing. |
 | `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`:
 
@@ -624,10 +631,11 @@ 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. A `group=` dispatch folds the group's `shared_context` into `context`, so different groups cache separately and a plain dispatch is unaffected.
+- **Timeout** — per-agent or global (default: 300s). A streaming dispatch runs the agent in its own process group, so the deadline kills the whole tree: a process the agent left running in the background can't hold the dispatch (and its concurrency slot) open past the timeout.
+- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only clean successes are cached: failures, results with `denied_tools`, and results flagged `budget_exceeded` are not, so the documented "grant access / raise the cap, then re-dispatch" recovery is never served a stale crippled answer. Changing an agent's config invalidates its entries. 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.
+- **Durable config** — `agents.yaml` is written atomically (temp file + rename), and every mutation path (CLI and MCP server alike) holds a cross-process advisory lock, so concurrent edits cannot truncate the file or silently drop one another's agents.
 
 See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
 
@@ -647,7 +655,7 @@ See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassP
 | `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 gc [--days]` | Purge terminal jobs older than N days (default 7) |
+| `agent-dispatch gc [--days N \| --all]` | Purge terminal jobs older than N days (default 7; `--all` purges every age) |
 | `agent-dispatch serve` | Start MCP server (stdio, used by Claude Code) |
 
 ## Requirements

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

@@ -203,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`.
 
@@ -318,7 +318,7 @@ Run multiple tasks concurrently. Much faster than sequential `dispatch` calls.
 
 Same as `dispatch` but shows live progress while the agent works. Use for long-running tasks. Not cached.
 
-Parameters are the same as `dispatch` except `return_ref`/`summary_chars` (streaming is incompatible with ref-mode).
+Parameters are the same as `dispatch` except `return_ref`/`summary_chars` (streaming is incompatible with ref-mode) and `group` (group context injection is supported only on `dispatch` and per-item in `dispatch_parallel`).
 
 ### `dispatch_dialogue`
 
@@ -363,6 +363,8 @@ Register a new project directory as an agent. Description is auto-generated from
 | `permission_mode` | string | no | Permission mode (e.g. `default`, `plan`, `bypassPermissions`) |
 | `allowed_tools` | string | no | Comma-separated allowed tools (e.g. `"Bash,Read,Edit"`) |
 | `disallowed_tools` | string | no | Comma-separated disallowed tools |
+| `capabilities` | string | no | Comma-separated capability labels (e.g. `"docker_logs,deploy_debug"`) |
+| `risky_capabilities` | string | no | Comma-separated high-risk labels (e.g. `"restart_services"`) |
 
 ### `update_agent`
 
@@ -378,6 +380,10 @@ Update an existing agent's configuration. Only non-empty fields are changed. Pas
 | `permission_mode` | string | no | Permission mode. `"none"` to clear |
 | `allowed_tools` | string | no | Comma-separated. `"none"` to clear |
 | `disallowed_tools` | string | no | Comma-separated. `"none"` to clear |
+| `capabilities` | string | no | Comma-separated. `"none"` to clear |
+| `risky_capabilities` | string | no | Comma-separated. `"none"` to clear |
+
+Changing an agent's config drops that agent's cached results — the cache key holds the agent *name*, so a re-pointed or re-permissioned agent would otherwise keep answering from the previous config for the rest of the TTL. The same applies to `add_agent` and `remove_agent`.
 
 ### `remove_agent`
 
@@ -470,16 +476,17 @@ Failures are deterministic: check `success`, then branch on `error_type`.
 | `error_type` | Meaning | Recovery |
 |--------------|---------|----------|
 | `permission` | A tool call was denied | `update_agent(name, allowed_tools="Bash,Read")` (least privilege) or `update_agent(name, permission_mode="bypassPermissions")`, then re-dispatch. The `error` text includes a hint with the exact fix. |
-| `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`. |
+| `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`. A *streaming* dispatch that produced its answer before the deadline returns that answer with a `hint` instead of failing. |
 | `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`:
 
@@ -594,10 +601,11 @@ 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. A `group=` dispatch folds the group's `shared_context` into `context`, so different groups cache separately and a plain dispatch is unaffected.
+- **Timeout** — per-agent or global (default: 300s). A streaming dispatch runs the agent in its own process group, so the deadline kills the whole tree: a process the agent left running in the background can't hold the dispatch (and its concurrency slot) open past the timeout.
+- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only clean successes are cached: failures, results with `denied_tools`, and results flagged `budget_exceeded` are not, so the documented "grant access / raise the cap, then re-dispatch" recovery is never served a stale crippled answer. Changing an agent's config invalidates its entries. 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.
+- **Durable config** — `agents.yaml` is written atomically (temp file + rename), and every mutation path (CLI and MCP server alike) holds a cross-process advisory lock, so concurrent edits cannot truncate the file or silently drop one another's agents.
 
 See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
 
@@ -617,7 +625,7 @@ See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassP
 | `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 gc [--days]` | Purge terminal jobs older than N days (default 7) |
+| `agent-dispatch gc [--days N \| --all]` | Purge terminal jobs older than N days (default 7; `--all` purges every age) |
 | `agent-dispatch serve` | Start MCP server (stdio, used by Claude Code) |
 
 ## Requirements

{agent_dispatch-0.10.0 → agent_dispatch-0.12.0}/agents.example.yaml

@@ -93,7 +93,8 @@ 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.10.0 → agent_dispatch-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.10.0"
+version = "0.12.0"
 description = "MCP server that lets Claude Code agents delegate tasks to agents in other project directories"
 readme = "README.md"
 license = "MIT"
@@ -32,7 +32,11 @@ classifiers = [
     "Topic :: Software Development :: Libraries",
 ]
 dependencies = [
-    "mcp[cli]>=1.2.0",
+    # Upper bound is load-bearing: mcp 2.0 removed `mcp.server.fastmcp` (FastMCP
+    # was replaced by `mcp.server.mcpserver.MCPServer`), which server.py imports.
+    # Without the cap a fresh install resolves 2.x and `agent-dispatch serve`
+    # dies with ModuleNotFoundError. Lift it only together with the port.
+    "mcp[cli]>=1.2.0,<2",
     "pyyaml>=6.0",
     "click>=8.0",
 ]

{agent_dispatch-0.10.0 → agent_dispatch-0.12.0}/src/agent_dispatch/__init__.py

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

{agent_dispatch-0.10.0 → agent_dispatch-0.12.0}/src/agent_dispatch/cache.py

@@ -26,7 +26,10 @@ class DispatchCache:
     def __init__(self, ttl: int = 300, max_size: int = 1000) -> None:
         self._ttl = ttl
         self._max_size = max_size
-        self._store: dict[str, tuple[float, DispatchResult]] = {}
+        # value = (stored_at, agent_name, result). The agent name is kept
+        # alongside the hashed key so invalidate_agent() can drop exactly one
+        # agent's entries when its config changes.
+        self._store: dict[str, tuple[float, str, DispatchResult]] = {}
         self._lock = threading.Lock()
         self._hits = 0
         self._misses = 0
@@ -69,13 +72,16 @@ class DispatchCache:
             if entry is None:
                 self._misses += 1
                 return None
-            ts, result = entry
+            ts, _agent, result = entry
             if time.monotonic() - ts > self._ttl:
                 del self._store[key]
                 self._misses += 1
                 return None
             self._hits += 1
-            return result
+            # Hand back a copy: the stored result is shared by every caller of
+            # this key, and a caller that mutates what it got (adding a flag,
+            # truncating text) would silently corrupt the entry for everyone.
+            return result.model_copy(deep=True)
 
     def put(
         self,
@@ -89,6 +95,13 @@ class DispatchCache:
     ) -> None:
         if not result.success:
             return  # don't cache failures
+        if result.denied_tools or result.budget_exceeded:
+            # Successful but degraded: the agent answered with tools blocked, or
+            # the run cost more than its cap. The documented recovery is "grant
+            # access / raise the budget, then re-dispatch" — caching this would
+            # serve the same crippled answer back for the whole TTL and make that
+            # recovery a no-op (the permission config is not part of the key).
+            return
         key = self._make_key(agent, task, context, caller, goal, response_format)
         with self._lock:
             # Bound memory: when at capacity and inserting a new key, evict the
@@ -100,7 +113,22 @@ class DispatchCache:
                 oldest = min(self._store, key=lambda k: self._store[k][0])
                 del self._store[oldest]
                 self._evictions += 1
-            self._store[key] = (time.monotonic(), result)
+            self._store[key] = (time.monotonic(), agent, result)
+
+    def invalidate_agent(self, agent: str) -> int:
+        """Drop every cached result for *agent*. Returns the number removed.
+
+        Called whenever an agent's config changes: the cache key is
+        (agent, task, context, caller, goal, response_format), so it cannot tell
+        that the name now points at a different directory, permission set or
+        model. Without this, ``remove_agent`` + ``add_agent`` under the same name
+        keeps serving the previous project's answers for the rest of the TTL.
+        """
+        with self._lock:
+            stale = [k for k, (_ts, name, _r) in self._store.items() if name == agent]
+            for k in stale:
+                del self._store[k]
+            return len(stale)
 
     def clear(self) -> int:
         with self._lock:
@@ -114,7 +142,7 @@ class DispatchCache:
     def evict_expired(self) -> int:
         now = time.monotonic()
         with self._lock:
-            expired = [k for k, (ts, _) in self._store.items() if now - ts > self._ttl]
+            expired = [k for k, (ts, _n, _r) in self._store.items() if now - ts > self._ttl]
             for k in expired:
                 del self._store[k]
             return len(expired)