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

{agent_dispatch-0.11.0 → agent_dispatch-0.12.1}/.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.11.0 → agent_dispatch-0.12.1}/.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.11.0 → agent_dispatch-0.12.1}/AGENTS.md

@@ -28,10 +28,10 @@ pip install -e ".[dev]"
 
 ```bash
 ruff check src/ tests/
-python3 -m pytest tests/ -v   # 495 tests, ~2s — all subprocess calls are mocked
+python3 -m pytest tests/ -v   # 578 tests, ~5s
 ```
 
-Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.which` + `subprocess.run`/`Popen`; server tests mock `_get_config` + `runner.dispatch`.
+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)
 
@@ -46,6 +46,21 @@ Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.whi
 - 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` — or a failed *write* — returns the `{"error": ...}` envelope instead of a raw traceback. The set of load errors lives in one place (`config.CONFIG_LOAD_ERRORS`) because three surfaces handle it: **`UnicodeDecodeError` is a `ValueError`, not an `OSError`**, and listing types per-site is exactly how a cp1251 config slipped past all three.
+
+- 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
 
@@ -61,4 +76,4 @@ Python ≥ 3.10 · `from __future__ import annotations` everywhere · Pydantic v
 
 ## More detail
 
-[README.md](README.md) documents every MCP tool with parameter tables, response shapes, and the error-recovery map — it doubles as the behavioral spec. The test suite (`tests/`, 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`, ...).
+[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/`, 578 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.11.0 → agent_dispatch-0.12.1}/CHANGELOG.md

@@ -7,6 +7,171 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.1] - 2026-07-30
+
+Two holes in 0.12.0's own "tools always return a clean error" fix.
+
+### Fixed
+- **A non-UTF-8 `agents.yaml` no longer crashes every surface.** `UnicodeDecodeError`
+  is a `ValueError`, not an `OSError`, so a config saved as cp1251/UTF-16 slipped
+  past all three handlers added in 0.12.0 and raised a bare traceback out of every
+  MCP tool, `agent-dispatch list` — and `doctor`, the command you run *because*
+  the config is broken. The set of load errors is now declared once
+  (`config.CONFIG_LOAD_ERRORS`) and shared by all three, and `doctor` reports the
+  encoding (and an unreadable file) as a normal FAIL with a fix. The shared set
+  lives in `config.CONFIG_LOAD_ERRORS`; the CLI still branches per type because
+  each one deserves a different remediation line.
+- **An undecodable byte from the `claude` CLI no longer kills a paid-for
+  dispatch.** `text=True` decodes strictly, so one invalid byte on stdout raised
+  `UnicodeDecodeError` — a `ValueError`, caught by nothing in the runner — out of
+  `dispatch`, `dispatch_stream`, the MCP tools and `agent-dispatch test`. Both
+  spawn sites now decode with `errors="replace"`, so a mangled byte becomes
+  U+FFFD instead of discarding the run. (Present since the initial commit.)
+- **`dispatch` classifies spawn failures like `dispatch_stream` already did.**
+  A directory that passes `is_dir()` but cannot be entered — or that vanishes
+  between the check and the spawn — made `subprocess.run` raise straight through
+  the `except subprocess.TimeoutExpired`. It now returns `not_found` /
+  `permission` / `cli_error` like the streaming path.
+- **The six job tools got the I/O envelope too.** `dispatch_status`, `_wait`,
+  `_cancel`, `_jobs`, `fetch_result` and `dispatch_gc` never load config, so they
+  carried no guard — an unwritable or misconfigured jobs directory raised out of
+  them. The guard is now split (`_io_guard` / `_config_guard`) and both halves
+  are applied where each is needed.
+- **`add_agent` reports an unresolvable path** (`~unknown-user`) as an error
+  envelope instead of raising `RuntimeError`.
+- **A failed config *write* is reported, not raised.** The same contract had the
+  other half missing: a full disk or a read-only volume made `save_config`
+  raise OSError straight out of `add_agent`/`update_agent`/`remove_agent` and out
+  of the matching CLI commands. Both surfaces now report it — the CLI adds that
+  the previous config is intact, which the atomic write guarantees.
+
+### Changed
+- Docs corrected against the code: stale-job recovery now documents the
+  `pending` sweep and its 24h threshold; the config-lock guarantee is stated as
+  best-effort (it proceeds unlocked after 10s rather than freezing the server);
+  `add_agent(timeout=0)` documents that it stores the literal 300, not
+  `settings.default_timeout`.
+
+## [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.
@@ -426,7 +591,9 @@ 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.11.0...HEAD
+[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.12.1...HEAD
+[0.12.1]: https://github.com/ginkida/agent-dispatch/compare/v0.12.0...v0.12.1
+[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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.11.0
+Version: 0.12.1
 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'
@@ -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`
 
@@ -388,11 +388,13 @@ Register a new project directory as an agent. Description is auto-generated from
 | `name` | string | yes | Agent name (letters, digits, hyphens, underscores) |
 | `directory` | string | yes | Path to an existing project directory (`~` is expanded, relative paths resolved) |
 | `description` | string | no | What this agent can do — auto-generated if empty |
-| `timeout` | int | no | Timeout in seconds (0 = use global default) |
-| `max_budget_usd` | float | no | Max cost in USD per dispatch (0 = no limit) |
+| `timeout` | int | no | Timeout in seconds (0 = 300; this is a literal default, not `settings.default_timeout`) |
+| `max_budget_usd` | float | no | Max cost in USD per dispatch (0 = inherit `settings.default_max_budget_usd`; no cap only when that is unset too) |
 | `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`
 
@@ -403,11 +405,15 @@ Update an existing agent's configuration. Only non-empty fields are changed. Pas
 | `name` | string | yes | Agent name to update |
 | `description` | string | no | New description |
 | `timeout` | int | no | New timeout (0 = don't change) |
-| `max_budget_usd` | float | no | New budget limit (0 = don't change, negative = clear the limit) |
+| `max_budget_usd` | float | no | New budget limit (0 = don't change; negative clears the *per-agent* cap, after which `settings.default_max_budget_usd` applies) |
 | `model` | string | no | Model override. `"none"` to clear |
 | `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`
 
@@ -468,7 +474,7 @@ Async workers run with streaming under the hood: the job file keeps a rolling ta
 
 `dispatch_jobs(status?)` lists recent jobs as summaries (filter by `pending` / `running` / `done` / `failed` / `cancelled`). `dispatch_gc(max_age_days=7)` purges terminal jobs older than the threshold — pending and running jobs are never deleted.
 
-Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `AGENT_DISPATCH_JOBS_DIR`). One JSON file per job, written owner-only (`0o600`) with atomic writes — safe to read or `ls` while jobs are in flight. Caller-supplied `job_id`s are validated as 32-char hex before any file access (no path traversal). On startup the server marks jobs left in `running` by a crashed instance as `failed` once they are stale (stuck for over an hour).
+Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `AGENT_DISPATCH_JOBS_DIR`). One JSON file per job, written owner-only (`0o600`) with atomic writes — safe to read or `ls` while jobs are in flight. Caller-supplied `job_id`s are validated as 32-char hex before any file access (no path traversal). On startup the server recovers jobs a crashed instance abandoned: `running` ones stuck over an hour, and `pending` ones over 24 hours, are marked `failed` so they stop being polled forever and become collectable by `dispatch_gc`. (The `pending` threshold is deliberately long — the jobs directory is shared by every running server, so a job queued behind another server's concurrency limit must not be swept.)
 
 | When to use async | When to use `dispatch` |
 |-------------------|------------------------|
@@ -500,7 +506,7 @@ 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>)`. |
@@ -627,8 +633,9 @@ agent-dispatch MCP server
 - **Owner-only state** — job files (`0o600`) and `agents.yaml` (`0o600`) are written for the owner only; their directories are `0o700`.
 - **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), so an interrupted write can never truncate it. Every mutation path (CLI and MCP server alike) also takes a cross-process advisory lock, so concurrent edits don't drop one another's agents. The lock is best-effort by design: after waiting 10 seconds it logs a warning and proceeds anyway, because a wedged lock holder must not freeze the MCP server — so on a heavily contended config a lost update is possible, while a truncated one is not.
 
 See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
 
@@ -648,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.11.0 → agent_dispatch-0.12.1}/README.md

@@ -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`
 
@@ -358,11 +358,13 @@ Register a new project directory as an agent. Description is auto-generated from
 | `name` | string | yes | Agent name (letters, digits, hyphens, underscores) |
 | `directory` | string | yes | Path to an existing project directory (`~` is expanded, relative paths resolved) |
 | `description` | string | no | What this agent can do — auto-generated if empty |
-| `timeout` | int | no | Timeout in seconds (0 = use global default) |
-| `max_budget_usd` | float | no | Max cost in USD per dispatch (0 = no limit) |
+| `timeout` | int | no | Timeout in seconds (0 = 300; this is a literal default, not `settings.default_timeout`) |
+| `max_budget_usd` | float | no | Max cost in USD per dispatch (0 = inherit `settings.default_max_budget_usd`; no cap only when that is unset too) |
 | `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`
 
@@ -373,11 +375,15 @@ Update an existing agent's configuration. Only non-empty fields are changed. Pas
 | `name` | string | yes | Agent name to update |
 | `description` | string | no | New description |
 | `timeout` | int | no | New timeout (0 = don't change) |
-| `max_budget_usd` | float | no | New budget limit (0 = don't change, negative = clear the limit) |
+| `max_budget_usd` | float | no | New budget limit (0 = don't change; negative clears the *per-agent* cap, after which `settings.default_max_budget_usd` applies) |
 | `model` | string | no | Model override. `"none"` to clear |
 | `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`
 
@@ -438,7 +444,7 @@ Async workers run with streaming under the hood: the job file keeps a rolling ta
 
 `dispatch_jobs(status?)` lists recent jobs as summaries (filter by `pending` / `running` / `done` / `failed` / `cancelled`). `dispatch_gc(max_age_days=7)` purges terminal jobs older than the threshold — pending and running jobs are never deleted.
 
-Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `AGENT_DISPATCH_JOBS_DIR`). One JSON file per job, written owner-only (`0o600`) with atomic writes — safe to read or `ls` while jobs are in flight. Caller-supplied `job_id`s are validated as 32-char hex before any file access (no path traversal). On startup the server marks jobs left in `running` by a crashed instance as `failed` once they are stale (stuck for over an hour).
+Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `AGENT_DISPATCH_JOBS_DIR`). One JSON file per job, written owner-only (`0o600`) with atomic writes — safe to read or `ls` while jobs are in flight. Caller-supplied `job_id`s are validated as 32-char hex before any file access (no path traversal). On startup the server recovers jobs a crashed instance abandoned: `running` ones stuck over an hour, and `pending` ones over 24 hours, are marked `failed` so they stop being polled forever and become collectable by `dispatch_gc`. (The `pending` threshold is deliberately long — the jobs directory is shared by every running server, so a job queued behind another server's concurrency limit must not be swept.)
 
 | When to use async | When to use `dispatch` |
 |-------------------|------------------------|
@@ -470,7 +476,7 @@ 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>)`. |
@@ -597,8 +603,9 @@ agent-dispatch MCP server
 - **Owner-only state** — job files (`0o600`) and `agents.yaml` (`0o600`) are written for the owner only; their directories are `0o700`.
 - **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), so an interrupted write can never truncate it. Every mutation path (CLI and MCP server alike) also takes a cross-process advisory lock, so concurrent edits don't drop one another's agents. The lock is best-effort by design: after waiting 10 seconds it logs a warning and proceeds anyway, because a wedged lock holder must not freeze the MCP server — so on a heavily contended config a lost update is possible, while a truncated one is not.
 
 See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
 
@@ -618,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.11.0 → agent_dispatch-0.12.1}/pyproject.toml

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

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

{agent_dispatch-0.11.0 → agent_dispatch-0.12.1}/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)