agent-dispatch 0.15.1__tar.gz → 0.17.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. agent_dispatch-0.17.0/.github/workflows/ci.yml +58 -0
  2. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/.gitignore +3 -0
  3. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/AGENTS.md +20 -12
  4. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/CHANGELOG.md +143 -1
  5. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/PKG-INFO +98 -20
  6. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/README.md +97 -19
  7. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/agents.example.yaml +7 -1
  8. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/pyproject.toml +7 -1
  9. agent_dispatch-0.17.0/scripts/check_install.py +116 -0
  10. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/__init__.py +1 -1
  11. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/cache.py +20 -9
  12. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/cli.py +314 -67
  13. agent_dispatch-0.17.0/src/agent_dispatch/concurrency.py +158 -0
  14. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/config.py +5 -0
  15. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/jobs.py +74 -31
  16. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/models.py +48 -5
  17. agent_dispatch-0.17.0/src/agent_dispatch/progress.py +43 -0
  18. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/runner.py +592 -52
  19. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/server.py +286 -160
  20. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/servers.py +5 -3
  21. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/src/agent_dispatch/usage.py +133 -8
  22. agent_dispatch-0.17.0/tests/conftest.py +136 -0
  23. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_cli.py +559 -7
  24. agent_dispatch-0.17.0/tests/test_concurrency.py +277 -0
  25. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_config.py +17 -0
  26. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_jobs.py +241 -0
  27. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_models.py +46 -1
  28. agent_dispatch-0.17.0/tests/test_progress.py +44 -0
  29. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_runner.py +949 -80
  30. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_server.py +706 -11
  31. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_usage.py +151 -0
  32. agent_dispatch-0.15.1/.coverage +0 -0
  33. agent_dispatch-0.15.1/.github/workflows/ci.yml +0 -34
  34. agent_dispatch-0.15.1/tests/conftest.py +0 -68
  35. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/.github/dependabot.yml +0 -0
  36. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/.github/workflows/publish.yml +0 -0
  37. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/LICENSE +0 -0
  38. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/SECURITY.md +0 -0
  39. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/assets/mascot.png +0 -0
  40. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/__init__.py +0 -0
  41. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_cache.py +0 -0
  42. {agent_dispatch-0.15.1 → agent_dispatch-0.17.0}/tests/test_servers.py +0 -0
@@ -0,0 +1,58 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ # Least privilege: CI only needs to read the repo.
10
+ permissions:
11
+ contents: read
12
+
13
+ jobs:
14
+ test:
15
+ runs-on: ubuntu-latest
16
+ strategy:
17
+ matrix:
18
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
19
+
20
+ steps:
21
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
22
+
23
+ - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
24
+ with:
25
+ python-version: ${{ matrix.python-version }}
26
+
27
+ - name: Install dependencies
28
+ run: pip install -e ".[dev]"
29
+
30
+ - name: Lint
31
+ run: ruff check src/ tests/ scripts/
32
+
33
+ - name: Test
34
+ run: pytest tests/ -v
35
+
36
+ installed-package:
37
+ runs-on: ubuntu-latest
38
+ timeout-minutes: 10
39
+ strategy:
40
+ matrix:
41
+ python-version: ["3.10", "3.13"]
42
+ steps:
43
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
44
+ - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
45
+ with:
46
+ python-version: ${{ matrix.python-version }}
47
+ - name: Build wheel and source distribution
48
+ run: |
49
+ python -m pip install build twine
50
+ python -m build
51
+ python -m twine check dist/*
52
+ - name: Install wheel into a clean environment
53
+ run: |
54
+ python -m venv "$RUNNER_TEMP/package-check"
55
+ "$RUNNER_TEMP/package-check/bin/python" -m pip install dist/*.whl
56
+ "$RUNNER_TEMP/package-check/bin/python" -m pip check
57
+ - name: Verify CLI and MCP transport from installed wheel
58
+ run: '"$RUNNER_TEMP/package-check/bin/python" -I scripts/check_install.py'
@@ -18,3 +18,6 @@ CLAUDE.md
18
18
  .claude/
19
19
  .mcp.json
20
20
  *.db
21
+ .coverage
22
+ .coverage.*
23
+ htmlcov/
@@ -11,13 +11,15 @@ MCP server + CLI that lets Claude Code agents delegate tasks to agents in other
11
11
  | File | Role |
12
12
  |------|------|
13
13
  | `src/agent_dispatch/runner.py` | Sync subprocess wrapper around `claude -p` — the actual work |
14
- | `src/agent_dispatch/server.py` | Async FastMCP interface (21 MCP tools), wraps runner in `asyncio.to_thread` + semaphore |
15
- | `src/agent_dispatch/usage.py` | Append-only dispatch journal (cost/duration/outcome) + aggregation for `stats` and the `typical` block |
14
+ | `src/agent_dispatch/server.py` | Async FastMCP interface (21 MCP tools), wraps runner in `asyncio.to_thread` with a shared process limit |
15
+ | `src/agent_dispatch/usage.py` | Append-only dispatch journal (cost/duration/outcome/tokens/model) + aggregation for `stats` and the `typical` block |
16
16
  | `src/agent_dispatch/servers.py` | Registry of live `serve` processes and the version each one runs (`doctor` reads it) |
17
17
  | `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` |
18
18
  | `src/agent_dispatch/models.py` | Pydantic v2 models (`AgentConfig`, `DispatchGroup`/`GroupMember`, `Settings`, `DispatchResult`) |
19
19
  | `src/agent_dispatch/config.py` | YAML config load/save + project auto-description |
20
20
  | `src/agent_dispatch/cache.py` | Thread-safe in-memory TTL cache |
21
+ | `src/agent_dispatch/concurrency.py` | Resizable process limit shared by async callers and background workers |
22
+ | `src/agent_dispatch/progress.py` | Bounded progress buffer, discarded when a streaming client disconnects |
21
23
  | `src/agent_dispatch/jobs.py` | Persistent per-job JSON files for async dispatch |
22
24
 
23
25
  ## Dev setup
@@ -29,11 +31,13 @@ pip install -e ".[dev]"
29
31
  ## Gates — both must pass before a change is done (CI rejects otherwise)
30
32
 
31
33
  ```bash
32
- ruff check src/ tests/
33
- python3 -m pytest tests/ -v # 714 tests, ~17s
34
+ ruff check src/ tests/ scripts/
35
+ python3 -m pytest tests/ -v
34
36
  ```
35
37
 
36
- 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.
38
+ Tests must **never** invoke the real `claude` CLI. Runner unit tests mock `shutil.which` + `_run_captured`/`Popen`; server tests mock `_get_config` + `runner.dispatch`. Pipe and decoding integration tests spawn short-lived *python* subprocesses: a pipe deadlock lives in the OS pipe buffer, so a mocked `Popen` structurally cannot reproduce it.
39
+
40
+ The autouse guard in `tests/conftest.py` rejects real Claude process launches when a test forgets its mock. Diagnostic tests must mock discovery or CLI probes too.
37
41
 
38
42
  ## Non-obvious invariants (violating these breaks real behavior)
39
43
 
@@ -45,32 +49,35 @@ Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.whi
45
49
  - Valid permission modes: `default`, `plan`, `bypassPermissions` (`models.py: KNOWN_PERMISSION_MODES`).
46
50
  - `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.
47
51
  - "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.
48
- - 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).
52
+ - Cancelling a *running* job requires the in-memory registry (server.py): `_owned_jobs` records ownership **before** `mark_running`, `_running_procs` the Popen once spawned — a cancel landing between the two is still honored, and the late process is killed on registration. The job is marked `cancelled` **before** the subprocess is killed. A job record that is merely *unreadable* at spawn is not treated as terminal. Don't persist PIDs to disk (PID reuse after restart could kill an unrelated process).
49
53
  - `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.
50
54
  - 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.
51
- - **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()`.
55
+ - **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). Ordinary `dispatch` uses `_run_captured` with two readers; binary `read1` retains flushed output even without a newline. Readers own their pipes, and stop retaining output when the caller returns. **Completion is stdout EOF + leader exit, never stderr EOF**: a stdio MCP server started by `claude` inherits fd 2 and outlives it, so waiting for stderr EOF turned every such dispatch into a full-timeout wait and a real CLI error into `error_type="timeout"`. stderr gets a short bounded join afterwards, then the leftover group is killed. `dispatch_stream` reads stdout through a reader thread too, so a descendant that *detached* from the group (unreachable by `killpg`) cannot park it forever once the run was killed.
52
56
  - **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.
53
- - **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.
57
+ - **The timeout must kill the process *tree*, not the child.** Both runners spawn 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 — and on `proc.returncode is None`: a reaped leader's PID may already belong to an unrelated group. So nothing may reap the leader (`poll()`/`wait()`) before the kill decision; `_wait_leader_exit` observes exit without reaping (`waitid(WNOWAIT)` on Linux, a kqueue exit watch on macOS). `_run_captured` drains pipes before reaping the leader, so its PID cannot be recycled before a timeout kill. Cleanup waits are bounded even when a descendant deliberately leaves the process group. A full CLI `type=result` JSON payload outranks the ordinary timeout too; incomplete output does not.
54
58
  - **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.
55
59
  - **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).
56
60
  - 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.
57
61
  - `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. For a *running* job, `started_at` alone does **not** prove abandonment — a dispatch may legitimately run to the 7200s timeout ceiling, so the file's own mtime is checked too (a live worker rewrites it on every progress flush). That check can only ever *skip* a recovery, never add one.
58
62
  - Deleting job records is **opt-in** (`settings.job_retention_days`, default `0` = off) and only ever happens at server start, never inside a tool. They are the user's dispatch history and the deletion is irreversible, so an unreadable config is treated as "do nothing" rather than falling back to a default retention.
59
- - `max_concurrency` must bound *subprocesses*, not coroutines. Cancelling a coroutine does not stop the thread behind `asyncio.to_thread`, so `async with sem:` gave the slot away while `claude` kept running and billing. Dispatches go through `_dispatch_guarded`, which releases from the future's done-callback and `shield`s the await. Never "simplify" it back to `async with`.
63
+ - `max_concurrency` must bound *subprocesses*, not coroutines. All dispatch paths share one `DispatchLimiter` per server, resized in place so changing the limit cannot erase occupied slots. Ordinary and streaming dispatches go through `_start_guarded`, which releases from the future's done-callback; awaits on that future are shielded. Background jobs hold the same limiter in their worker thread. The limiter is **FIFO across threads and coroutines** — a freed slot is handed to the head waiter in `release()`; otherwise parked job threads, woken in microseconds, starved a queued synchronous `dispatch` indefinitely. A waiter cancelled after its grant passes the slot on exactly once. Cancelling a coroutine does not stop its thread: never release its slot from an `async with` or caller-side `finally`.
60
64
  - Tool responses are serialized through `server._dumps`, never bare `json.dumps`: the stdlib default (`ensure_ascii=True`) turns every non-ASCII character into a `\uXXXX` escape, tripling the bytes and tokenizing badly, for no gain — the stdio transport emits raw UTF-8 via pydantic anyway. A real `list_groups()` carried 8520 escapes and weighed 59 KB instead of 25 KB.
61
65
  - `agents.yaml` is parsed with libyaml's `CSafeLoader` when available (`config._YamlLoader`), falling back to the pure-Python **safe** loader — never `yaml.Loader`. The config is re-read on every tool call, so this parse is on the hot path of all 21 tools *and* blocks the event-loop thread: 9.80 ms → 0.76 ms on a real 38 KB config.
62
66
  - 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`.
63
67
  - 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.
64
- - Anything that changes an agent's config must call `_invalidate_agent_cache` — the cache key holds the agent *name*, not its directory or permissions.
68
+ - Anything that changes an agent's config must call `_invalidate_agent_cache` to reclaim old entries. Cache lookups and writes also receive the same `_cache_config_key` snapshot, captured before awaiting work: this covers CLI/YAML/other-server edits and prevents an old worker from repopulating the current configuration's cache. Include new dispatch-affecting settings in this snapshot.
65
69
  - Only *clean* successes are cached: `cache.put` refuses failures, `denied_tools` results, `budget_exceeded` results, and results whose `outcome` is `partial`/`blocked`, so the documented "grant access / fix the cause, then re-dispatch" recovery is never short-circuited.
66
70
  - **Coerce every number read off disk through `usage.as_float`.** `float("abc")` raises **ValueError** — not `JSONDecodeError`, not `OSError` — so it escaped the per-line handler in `usage.load` and the sort key in `servers.live_servers`, turning `agent-dispatch stats --days 7` and `doctor` into tracebacks over one hand-edited character. Same escape route as the `UnicodeDecodeError`-is-a-`ValueError` round. A journal or registry field is untrusted input: skip the record or sort it last, never raise from the command someone ran *because* something is already wrong.
67
71
  - **`--json` output must be valid JSON on the empty path too.** `stats --json` printed prose when the journal had no records — i.e. on a fresh install, which is exactly when a script first pipes it somewhere.
68
72
  - **The usage journal is written by a decorator, not at each return.** `runner._journaled` wraps `dispatch`/`dispatch_stream` because each has a dozen early returns; instrumenting them one by one guarantees the next new return path goes unrecorded. It records the outermost call only (`_use_session_flag` is False on the stream's old-CLI retry, which would otherwise double-count one dispatch). It also swallows exceptions itself even though `usage.record` already does: the result in hand is billed, and the guarantee has to hold at the boundary that owns the damage rather than on another module's promise (`test_a_broken_journal_never_breaks_a_paid_dispatch` removes record()'s guard to prove it).
69
73
  - **A journal record is one `O_APPEND` write under `PIPE_BUF`**, never a locked read-modify-write: the CLI and every running server share one file, and this user has 14+ servers alive. Every field is capped so the line cannot approach 4096 bytes. Rotation is an atomic rename at ~2 MB, two generations kept.
74
+ - **`total_cost_usd` is per SESSION on `--resume`** (claude ≥ 2.1.277; verified live on 2.1.322: $0.0798, then $0.0953 after a resume that cost $0.0155). `runner._call_cost` turns it into the call's own cost by subtracting `usage.session_total(session_id)` — the newest journal record for that `sid` (`cum`, or `cost` for a session's first call) — read **before** the spawn, and carries the reported cumulative figure as `cum` in the journal telemetry. Amounts cannot tell cumulative from per-call reporting, so the CLI **version** decides (`_cli_reports_session_totals`: `claude --version` ≥ 2.1.277, memoized per binary+mtime, probe failure = do not adjust; `tests/conftest.py` stubs it to True). It subtracts only when the reported total is a finite number ≥ the prior total within `_COST_EPSILON` (the journal rounds to 6 places — without the tolerance an unchanged total was charged whole again), and not at all when the session is unknown to the journal or `usage_log` is off: those keep the reported figure. `session_total` reads the live generation before `.1` (the other order loses the newest records to a concurrent rotation) and never takes `cost` from a record that has a `cum` key. Known limits, accepted: two processes resuming one session at once can both subtract the same baseline; a costless record in between (timeout) folds its spend into the next call — the sum stays right, the split does not. `_apply_budget` therefore judges the call, not the session. Only `dispatch` resumes; `dispatch_stream` has no `session_id`.
75
+ - **Token usage is journal-only.** `DispatchResult.token_usage` has `exclude=True`: never expose it in tool payloads or job files. `runner._token_usage` extracts `in`/`out`/`cr`/`cw` and the highest-cost `model` from CLI results, including failures; `_journaled` passes it to `usage.record`, which revalidates counts in `[0, 10**12)` and caps model names at 60 characters. Cache hits have no tokens. `stats` reports separate token sums, measured `records`, cache-read share, and model counts; text shows combined input/cache percentages plus output totals and each agent's most frequent model (`+N more` when needed). Old records remain valid, disk counts go through `as_float` plus plausibility bounds, and `_profile` must not grow.
70
76
  - **Profiles are memoized on the journal's (path, size, mtime) and read a NARROWER tail than `stats`.** `list_agents`/`inspect_agent` run on the event-loop thread: a full 2 MB journal cost **24.8 ms** per discovery call at the 512 KB report window — 33x the config parse that 0.13.0 exists to have fixed. Now 3.3 ms cold, ~0 warm. Every profile consumer goes through `usage.profiles()`; never add a caller that re-parses per agent.
71
77
  - **`usage_limit` is its own error type** (observed live: `You've hit your session limit · resets 6pm`). It is checked *before* the permission patterns and its hint says the limit is account-wide, so "try another agent" is not a workaround. Text-classified errors attach their advisory through the single `_classification_hint`, not per site.
72
78
  - **Server liveness is an advisory lock, not a PID.** `servers.register` holds an exclusive `flock` on `<config dir>/servers/<pid>.json` for the process lifetime; a reader that *takes* that lock owns a dead entry and deletes it. `os.kill(pid, 0)` would believe a recycled PID and would never notice a SIGKILLed server. Never close that fd (re-registering closes the old one first).
73
- - **The dispatch protocol goes in the system prompt, not the task.** `_build_system_prompt` (runner.py) renders the protocol (non-interactive, time/spend budget, lead with the outcome, trailing `STATUS:` line) plus the agent's `instructions`, and `_build_command` passes it as `--append-system-prompt` — on `--resume` too, since the CLI re-applies an appended prompt on every launch. `_build_prompt` (the `-p` text) is unchanged, so the cache key is unchanged. The text always starts with a `##` header line so it can never be read as a flag. `settings.dispatch_protocol: false` turns the protocol off (for CLIs that predate the flag; `doctor` probes `claude --help` for it); per-agent `instructions` still go through when set.
79
+ - **Startup trims are opt-in flags, never defaults.** `AgentConfig.skills` (default true; false → `--disable-slash-commands`) and `strict_mcp` (default false; true → `--strict-mcp-config`, plus `--mcp-config <dir>/.mcp.json` when that file exists) come from `runner._startup_trim_flags`, are sent on `--resume` too, and are pruned from YAML at their defaults. `--mcp-config` is variadic in the CLI: keep a flag right after its path. Mutation is CLI-only (`update --no-skills/--skills`, `--strict-mcp/--no-strict-mcp`); `doctor` probes the flags only when some agent uses them. Measured basis (claude 2.1.322): a new task text re-creates ~32k preamble tokens per dispatch; a stable `--append-system-prompt` does not help. A resumed session, by contrast, re-reads its preamble from cache: live, a follow-up via `dispatch_session` cost $0.005–0.017 against $0.089 for a fresh dispatch of the same agent.
80
+ - **The dispatch protocol goes in the system prompt, not the task.** `_build_system_prompt` (runner.py) renders the protocol (non-interactive, time/spend budget, lead with the outcome, trailing `STATUS:` line) plus the agent's `instructions`, and `_build_command` passes it as `--append-system-prompt` — on `--resume` too, since the CLI re-applies an appended prompt on every launch. `_build_prompt` (the `-p` text) is unchanged. Standing instructions and protocol settings are captured separately in `_cache_config_key`. The text always starts with a `##` header line so it can never be read as a flag. `settings.dispatch_protocol: false` turns the protocol off (for CLIs that predate the flag; `doctor` probes `claude --help` for it); per-agent `instructions` still go through when set.
74
81
  - **`outcome` is lifted from the LAST line of the result** (`_split_outcome`), before JSON parsing, by the shared `_build_success_result` (the success-side twin of `_build_error_result` — both `dispatch` and `dispatch_stream` go through it) and by the plain-text fallback tier. A bare marker line is removed from `result`; a marker with a trailing reason stays. `outcome` never flips `success`; `partial`/`blocked` add a `hint` with the `dispatch_session(...)` continuation, after the denial hint. In JSON mode the protocol omits the STATUS instruction (the JSON footer governs), but a STATUS line that arrives anyway is still stripped so `parsed_result` survives.
75
82
  - 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.
76
83
  - The config error sets are declared **once** and in two halves: `config.CONFIG_LOAD_ERRORS` (read) and `config.CONFIG_SAVE_ERRORS` (write — `yaml.dump`'s `RepresenterError` is a `yaml.YAMLError`, therefore neither `OSError` nor `ConfigLoadError`, and used to escape both the MCP guard and the CLI's `_save_or_exit`). Two halves, not one set, because the remediations differ: a failed write is atomic so the old config survives, while a failed read needs the YAML fixed.
@@ -80,6 +87,7 @@ Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.whi
80
87
 
81
88
  - `mcp` is pinned **`>=1.2.0,<2`** deliberately: 2.0 removed `mcp.server.fastmcp`, which `server.py` imports, so an unbounded range gives every fresh install a dead `agent-dispatch serve`. Lifting the cap means porting to `mcp.server.mcpserver.MCPServer` — it is not a dependency bump.
82
89
  - Verify packaging in a **clean venv**, never the dev machine: build the wheel, install it fresh, import the server. A stale pin in local site-packages hides exactly the failure a new user hits first.
90
+ - CI's `installed-package` job builds wheel and sdist, checks metadata with twine, then installs only the wheel and runtime dependencies into a fresh venv on Python 3.10 and 3.13. Run `python -I scripts/check_install.py` with that venv's Python to verify the installed CLI and a real MCP stdio connection. The check isolates all state in a temporary directory and cannot discover Claude on PATH.
83
91
  - Run **`twine check dist/*`** before cutting the tag, with a *current* twine. The clean-venv check does not cover this: it proves the wheel installs, not that PyPI's uploader will accept its metadata. `python -m build` pulls the newest hatchling at build time, so the emitted `Metadata-Version` climbs on its own, and `pypa/gh-action-pypi-publish` is pinned to a SHA that bundles a fixed twine — v0.13.0's publish failed on exactly that mismatch (hatchling 1.32 → metadata 2.5; pinned twine 6.1.0 → "not a valid metadata version"). When it happens, bump the action pin rather than pinning the backend down.
84
92
 
85
93
  ## Deliberately not built
@@ -96,4 +104,4 @@ Python ≥ 3.10 · `from __future__ import annotations` everywhere · Pydantic v
96
104
 
97
105
  ## More detail
98
106
 
99
- [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/`, 714 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`, ...).
107
+ [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/`) 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`, ...).
@@ -7,6 +7,142 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.17.0] - 2026-11-10
11
+
12
+ The cost round, driven by measurements on the live CLI rather than by reading
13
+ code: what a dispatch pays for before the agent does anything, and what the
14
+ journal was getting wrong about resumed sessions.
15
+
16
+ ### Added
17
+ - Per-agent startup-context trims, both opt-in: `agent-dispatch update <name>
18
+ --no-skills` (sends `--disable-slash-commands`) and `--strict-mcp` (sends
19
+ `--strict-mcp-config` with the agent directory's own `.mcp.json`). A dispatch
20
+ with a new task re-writes the whole session preamble to the prompt cache —
21
+ about 32k tokens on claude 2.1.322 — and these cut the cold-start cost by 27%
22
+ and 11% (43% together) in a live measurement. `describe` and `inspect_agent`
23
+ show them when set; `doctor` checks that the installed CLI knows the flags.
24
+ Restart running sessions before enabling them: a server on an older release
25
+ drops keys it does not know the next time it saves the config.
26
+ - Usage journal records input, output, cache-read and cache-write tokens plus
27
+ the highest-cost model reported by the CLI, including failed and budget-stopped
28
+ runs. `agent-dispatch stats` shows token totals, cache percentages and each
29
+ agent's most frequent model; `--json` includes counts and measurement coverage.
30
+ Token metadata stays out of tool responses, job files and discovery profiles.
31
+
32
+ ### Fixed
33
+ - A resumed session's cost was counted again on every `dispatch_session`.
34
+ Since claude 2.1.277 `total_cost_usd` covers the whole session on `--resume`;
35
+ the result and the journal now carry the call's own cost (the difference from
36
+ the session's last journaled total), so `stats` no longer overstates spend and
37
+ a cheap follow-up no longer raises `budget_exceeded` on the session's history.
38
+ Sessions the journal has not seen, and runs with `usage_log: false`, keep the
39
+ reported figure.
40
+ - `return_ref` payloads dropped `budget_exceeded`.
41
+
42
+ ## [0.16.0] - 2026-09-30
43
+
44
+ The process-control round. One concurrency limit now covers every dispatch
45
+ path and serves callers in arrival order; ordinary dispatch runs on the same
46
+ bounded two-reader design as streaming; and a round of adversarial review
47
+ aimed at pipes, process groups and cancellation closed the cases where a
48
+ finished run waited out its whole timeout, a detached descendant hung a
49
+ dispatch forever, or a paid result was thrown away over optional metadata.
50
+ Scripts get machine-readable `doctor`, `jobs` and `job` output.
51
+
52
+ ### Added
53
+ - CI verifies clean wheel installation on Python 3.10 and 3.13, distribution
54
+ metadata, and a real MCP stdio connection. `scripts/check_install.py` checks
55
+ CLI/MCP interoperability and full-result export with isolated temporary data.
56
+ - `doctor --json` emits a versioned diagnostic report with checks, severity,
57
+ counts, and remediation details. `--strict` makes warnings fail the command,
58
+ for installation checks in scripts.
59
+ - `agent-dispatch jobs --json` exports compact summaries; `job <id> --json`
60
+ exports the full record, including untruncated results and session metadata.
61
+ - Filter job history by exact agent name with `jobs --agent NAME` or
62
+ `dispatch_jobs(agent="NAME")`, including history for removed agents.
63
+ - Preview history cleanup with `agent-dispatch gc --dry-run` and
64
+ `dispatch_gc(dry_run=True)`. Both use the same eligibility rules as deletion.
65
+
66
+ ### Fixed
67
+ - Non-finite budgets are rejected before CLI/MCP mutations and during YAML
68
+ loading. Invalid numeric fields in parallel dispatch return an error before
69
+ any task starts, including values that overflow integer conversion.
70
+ - Ordinary dispatch now kills the process group on timeout, stopping descendants
71
+ that could continue work after the call failed. Pipe reads are concurrent and
72
+ cleanup is bounded even when a descendant detaches from the group.
73
+ - A complete CLI result from ordinary dispatch survives a cleanup timeout,
74
+ preserving the paid answer, cost, session and error classification. Partial
75
+ output still returns a resumable timeout.
76
+ - Running-job cancellation kills the process group, including descendants
77
+ holding output pipes open. A compatibility retry racing cancellation is
78
+ stopped too; the cancelled state is persisted before any kill.
79
+ - Streaming ignores malformed progress events without losing the final paid
80
+ result. Failed process registration cleans up the child and its pipes.
81
+ - Cache keys include the agent configuration and dispatch defaults. Edits from
82
+ the CLI, another server, or YAML cannot reuse an old answer, and workers
83
+ finishing under an older configuration cannot overwrite current answers.
84
+ - The process-tree timeout regression test synchronizes subprocess setup before
85
+ its one-second deadline, avoiding startup-related failures on busy machines.
86
+ - Non-finite and overflowing numeric metadata no longer poison usage reports
87
+ or crash server diagnostics. Invalid optional result costs are omitted while
88
+ preserving the dispatch output; journal records omit non-finite costs.
89
+ - Doctor's server counts and version drift now use one registry snapshot,
90
+ avoiding inconsistent totals when servers start or exit during a check.
91
+ - Two diagnostic tests now mock Claude discovery; a shared test guard rejects
92
+ accidental launches of the real Claude CLI.
93
+ - Streaming progress uses a bounded tail instead of an unlimited queue.
94
+ Slow clients receive an explicit omitted-message count; disconnected clients
95
+ stop retaining progress. Full dispatch results remain intact.
96
+ - All dispatch paths now share `max_concurrency` within a server process.
97
+ Mixing ordinary and background jobs no longer allows twice the configured
98
+ number of subprocesses. Changing the limit preserves occupied slots.
99
+ - Cancelling a streaming tool call keeps its concurrency reservation until the
100
+ worker finishes, just like an ordinary dispatch.
101
+ - Damaged job records cannot redirect status updates or stale recovery to a
102
+ different job: all reads verify the internal ID against the filename.
103
+ - Invalid and non-finite job timestamps are rejected at the read boundary.
104
+ Unreadable records are preserved, including during history cleanup.
105
+ - Job IDs with trailing newlines are rejected before file access.
106
+ - Agent and group name validation rejects trailing newlines instead of accepting
107
+ a partial regular-expression match.
108
+ - Ordinary dispatch completes when the CLI exits and its stdout closes, instead
109
+ of waiting for stderr. A stdio MCP server that inherited stderr no longer
110
+ turns a finished run into a full-timeout wait, and a real CLI error (for
111
+ example a usage limit) is no longer reported as a timeout.
112
+ - Streaming dispatch and running-job cancellation are bounded even when a
113
+ descendant leaves the process group while holding stdout; the concurrency
114
+ slot is released.
115
+ - A process group is never signalled after its leader was reaped, so a recycled
116
+ PID cannot direct the kill at an unrelated process group.
117
+ - The shared concurrency limit serves waiters in arrival order. Background jobs
118
+ queued later can no longer starve an ordinary, streaming or parallel call.
119
+ - Cancelling an owned job between its start and its process spawn now cancels
120
+ it instead of reporting it as belonging to another server. A job record that
121
+ cannot be read at spawn no longer makes the worker kill its own process.
122
+ - Malformed `duration_ms`, `num_turns` or `session_id` in CLI output no longer
123
+ discard the paid result; a bad session id falls back to the generated one.
124
+ - Usage reports ignore implausible journal values, so totals cannot overflow;
125
+ `stats --json` never prints `Infinity`.
126
+ - `doctor` survives non-UTF-8 `claude mcp list` output and an unreadable config
127
+ directory (JSON is still emitted). Its old-CLI warning accounts for
128
+ `dispatch_protocol` and per-agent instructions, so applying its remedy clears
129
+ it under `--strict`.
130
+ - `gc`, `gc --dry-run` and `cancel` report job-storage errors instead of
131
+ printing a traceback.
132
+ - The test guard against launching the real Claude CLI now fails the test even
133
+ when the launch happens in a background worker thread.
134
+ - A failing progress callback (for example a full disk while an async job
135
+ writes its progress) no longer kills the run or discards its paid result and
136
+ session. If the reader threads cannot be started, the spawned process is
137
+ killed instead of running unsupervised.
138
+ - `dispatch_cancel` reports `already_terminal` when this server's own job
139
+ finishes during the cancel, instead of claiming another server owns it.
140
+ - A lone surrogate escape in an agent's answer (typically a hand-escaped emoji
141
+ in a `response_format="json"` reply) no longer makes `dispatch`,
142
+ `dispatch_session`, `dispatch_stream` or `return_ref` raise instead of
143
+ answering, and no longer costs an async job its paid result. It is replaced
144
+ with U+FFFD where the CLI output is parsed.
145
+
10
146
  ## [0.15.1] - 2026-09-09
11
147
 
12
148
  Three defects in 0.15.0's own new code, found by re-auditing it the way this
@@ -802,7 +938,13 @@ cache bounding, and stale-job recovery.
802
938
  - Dependabot for `pip` + `github-actions`, GitHub Actions pinned to
803
939
  commit SHAs for supply-chain integrity.
804
940
 
805
- [Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.12.1...HEAD
941
+ [Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.17.0...HEAD
942
+ [0.17.0]: https://github.com/ginkida/agent-dispatch/compare/v0.16.0...v0.17.0
943
+ [0.16.0]: https://github.com/ginkida/agent-dispatch/compare/v0.15.1...v0.16.0
944
+ [0.15.1]: https://github.com/ginkida/agent-dispatch/compare/v0.15.0...v0.15.1
945
+ [0.15.0]: https://github.com/ginkida/agent-dispatch/compare/v0.14.0...v0.15.0
946
+ [0.14.0]: https://github.com/ginkida/agent-dispatch/compare/v0.13.0...v0.14.0
947
+ [0.13.0]: https://github.com/ginkida/agent-dispatch/compare/v0.12.1...v0.13.0
806
948
  [0.12.1]: https://github.com/ginkida/agent-dispatch/compare/v0.12.0...v0.12.1
807
949
  [0.12.0]: https://github.com/ginkida/agent-dispatch/compare/v0.11.0...v0.12.0
808
950
  [0.11.0]: https://github.com/ginkida/agent-dispatch/compare/v0.10.0...v0.11.0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: agent-dispatch
3
- Version: 0.15.1
3
+ Version: 0.17.0
4
4
  Summary: MCP server that lets Claude Code agents delegate tasks to agents in other project directories
5
5
  Project-URL: Homepage, https://github.com/ginkida/agent-dispatch
6
6
  Project-URL: Repository, https://github.com/ginkida/agent-dispatch
@@ -301,6 +301,8 @@ Check container logs for recent errors related to the scheduler service
301
301
 
302
302
  That last line is lifted out of `result` into **`outcome`** — the agent's own verdict, deterministic to check: `"done"` means complete; `"partial"` / `"blocked"` mean the agent says the work is unfinished, the result names what is missing, and a `hint` spells out the continuation (usually `dispatch_session(..., session_id=...)`). Read `outcome` before reading the text. It never flips `success`, `partial` / `blocked` results are **not cached**, and a `dispatch_parallel(..., aggregate=...)` labels such members for the aggregator so a blocked report is not synthesized as a finished one. Absent when the agent did not report one — the protocol is off (`settings.dispatch_protocol: false`), `response_format="json"` was requested (the JSON footer governs the reply shape there), or the agent simply skipped it.
303
303
 
304
+ **Startup cost.** Each dispatch is a fresh `claude` session, and a session's preamble — the project's `CLAUDE.md`, the skill listing, MCP server instructions and tool names — is written to the prompt cache again for every new task text (the task sits in front of it, so two different tasks share none of it). Measured on claude 2.1.322 in a gateway directory: ~32k tokens per dispatch before the agent does anything, which is most of what a short run costs. Two opt-in per-agent switches trim it — `agent-dispatch update <name> --no-skills` (no skill/command listing, user-level skills included: −27% in that measurement) and `--strict-mcp` (only the directory's own `.mcp.json`, no user-scope servers or connectors: −11%; the agent then cannot dispatch others, and loses any tool it got from a user-scope server). Check what an agent actually uses before turning either on; `--skills` / `--no-strict-mcp` undo them. A follow-up to the same agent is the opposite case: `dispatch_session` with the `session_id` from the previous result re-reads that preamble from cache (measured: $0.005–0.017 per follow-up against $0.089 for a fresh dispatch), so continue a session rather than re-dispatching when the question builds on the last answer. The larger levers stay outside this tool: a cheaper `model` for gateway agents and a shorter agent `CLAUDE.md`.
305
+
304
306
  **Standing orders.** Per-agent `instructions` (set via `add_agent` / `update_agent` or `agent-dispatch update <name> --instructions "..."`) follow the protocol in the same system prompt on **every** dispatch — "read-only SQL only", "never restart a stack unless the task says so", "answer with exact log lines". Unlike `context`, which is per call, and unlike the project's own `CLAUDE.md`, which is written for an interactive session, these are the rules for *being dispatched*.
305
307
 
306
308
  ```json
@@ -385,6 +387,13 @@ Run multiple tasks concurrently. Much faster than sequential `dispatch` calls.
385
387
 
386
388
  Same as `dispatch` but shows live progress while the agent works. Use for long-running tasks. Not cached.
387
389
 
390
+ Progress notifications keep the latest 100 pending messages, capped at 300
391
+ characters each. If output arrives faster than the client can receive it,
392
+ older notifications are omitted with a count; the final result is unaffected.
393
+ Disconnecting or cancelling the tool call discards pending notifications and
394
+ stops buffering new ones. The worker still holds its concurrency slot until it
395
+ finishes.
396
+
388
397
  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`).
389
398
 
390
399
  ### `dispatch_dialogue`
@@ -426,7 +435,7 @@ Register a new project directory as an agent. Description is auto-generated from
426
435
  | `directory` | string | yes | Path to an existing project directory (`~` is expanded, relative paths resolved) |
427
436
  | `description` | string | no | What this agent can do — auto-generated if empty |
428
437
  | `timeout` | int | no | Timeout in seconds (0 = 300; this is a literal default, not `settings.default_timeout`) |
429
- | `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) |
438
+ | `max_budget_usd` | float | no | Finite max cost in USD per dispatch (0 = inherit `settings.default_max_budget_usd`; no cap only when that is unset too) |
430
439
  | `permission_mode` | string | no | Permission mode (e.g. `default`, `plan`, `bypassPermissions`) |
431
440
  | `allowed_tools` | string | no | Comma-separated allowed tools (e.g. `"Bash,Read,Edit"`) |
432
441
  | `disallowed_tools` | string | no | Comma-separated disallowed tools |
@@ -452,7 +461,7 @@ Update an existing agent's configuration. Only non-empty fields are changed. Pas
452
461
  | `risky_capabilities` | string | no | Comma-separated. `"none"` to clear |
453
462
  | `instructions` | string | no | Standing orders for every dispatch (replaces the text). `"none"` to clear |
454
463
 
455
- 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`.
464
+ Changing an agent's config through an MCP mutation tool drops its cached results immediately. Cache keys also include the agent configuration and dispatch defaults, so edits through the CLI, another server, or YAML take effect on the next request. A worker finishing with an older configuration cannot overwrite answers for the new configuration. Unchanged agents keep their cache.
456
465
 
457
466
  ### `remove_agent`
458
467
 
@@ -507,11 +516,11 @@ dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
507
516
  -> {"id": "...", "status": "running", "timed_out_waiting": true}
508
517
  ```
509
518
 
510
- `dispatch_cancel(job_id)` cancels a **pending** job, and also kills a **running** job's `claude` subprocess when the job was started by the same server instance (the job is marked `cancelled` first, so the worker's trailing write can't undo it; partial work is lost but the progress tail is preserved). A running job started by a *previous* server run can't be killed safely and is left to finish. The response carries an `outcome` of `cancelled`, `cancelled_running`, `running` (not owned by this server), `already_terminal`, or `not_found`.
519
+ `dispatch_cancel(job_id)` cancels a **pending** job, and also kills a **running** job's `claude` process group when the job was started by the same server instance (the job is marked `cancelled` first, so the worker's trailing write can't undo it; partial work is lost but the progress tail is preserved). On POSIX, descendants in that process group are killed too, releasing inherited pipes and the concurrency slot. A cancel that lands after the job was claimed but before its process spawned is honored too: the process is killed as soon as it starts. A compatibility retry that races cancellation is killed when it registers. A running job started by a *previous* server run can't be killed safely and is left to finish. The response carries an `outcome` of `cancelled`, `cancelled_running`, `running` (not owned by this server), `already_terminal`, or `not_found`.
511
520
 
512
521
  Async workers run with streaming under the hood: the job file keeps a rolling tail (last 20 lines, ~1 write/sec) of assistant text and tool-use events. `dispatch_status` shows it as `progress` while the job runs and keeps it afterwards as a post-mortem trace; `dispatch_jobs` shows `last_progress` for running jobs.
513
522
 
514
- `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.
523
+ `dispatch_jobs(status?, limit=50, agent?)` lists recent jobs as summaries (filter by `pending` / `running` / `done` / `failed` / `cancelled`). `agent` matches an exact name, including agents since removed from configuration; both filters apply before the limit. `dispatch_gc(max_age_days=7)` purges terminal jobs older than the threshold — pending and running jobs are never deleted. Use `dry_run=True` to preview eligible job IDs without deleting them.
515
524
 
516
525
  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.)
517
526
 
@@ -545,7 +554,7 @@ Failures are deterministic: check `success`, then branch on `error_type`.
545
554
  | `error_type` | Meaning | Recovery |
546
555
  |--------------|---------|----------|
547
556
  | `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. |
548
- | `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=` — once the journal has history the error names the value that would have covered this agent's p90 — or use `dispatch_async`. A *streaming* dispatch that produced its answer before the deadline returns that answer with a `hint` instead of failing. |
557
+ | `timeout` | Process group 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=` — once the journal has history the error names the value that would have covered this agent's p90 — or use `dispatch_async`. Both ordinary and streaming dispatches preserve a complete CLI result received before termination; a successful result includes a cleanup `hint`. Partial output remains a timeout. |
549
558
  | `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. |
550
559
  | `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. |
551
560
  | `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>)`. |
@@ -580,6 +589,8 @@ agents:
580
589
  - deploy_debug
581
590
  risky_capabilities: # high-risk labels, surfaced for visibility
582
591
  - restart_services
592
+ # skills: false # no skill/command listing at startup (cheaper dispatches)
593
+ # strict_mcp: true # load only this directory's .mcp.json, no user-scope MCP servers
583
594
  # instructions: | # standing orders, appended to the system prompt on every dispatch
584
595
  # Read-only: never restart or redeploy unless the task says so.
585
596
  # Quote exact log lines with timestamps.
@@ -617,7 +628,7 @@ settings:
617
628
  # - Read
618
629
  # - Edit
619
630
  max_dispatch_depth: 3 # recursion protection
620
- max_concurrency: 5 # max parallel claude -p processes (per dispatch path)
631
+ max_concurrency: 5 # max parallel claude -p processes per server, across all tools
621
632
  # dispatch_protocol: true # send every agent the dispatch protocol (non-interactive,
622
633
  # # time budget, STATUS line → `outcome`). false = raw claude -p.
623
634
  # usage_log: true # record every dispatch in usage.jsonl (cost, duration, outcome).
@@ -636,7 +647,11 @@ Config is reloaded on every tool call — add agents without restarting.
636
647
 
637
648
  Every dispatch appends one line to `~/.config/agent-dispatch/usage.jsonl`
638
649
  (override with `AGENT_DISPATCH_USAGE_LOG`): agent, success, cost, duration,
639
- turns, `outcome`, error type, caller. Cache hits are recorded too, flagged
650
+ turns, `outcome`, error type, caller, plus token counts and the model when the
651
+ CLI reports them. Token fields are `in` (uncached input), `out` (output),
652
+ `cr` (cache read), and `cw` (cache write). `model` is the highest-cost model
653
+ in that dispatch's `modelUsage` (first on ties or when no cost is reported).
654
+ Cache hits are recorded too, flagged
640
655
  `cached`, so the report can show what the cache saves.
641
656
 
642
657
  ```console
@@ -644,18 +659,33 @@ $ agent-dispatch stats --days 7
644
659
  Usage (last 7 day(s))
645
660
  dispatches: 33, 1 served from cache
646
661
  spend: $13.0390
662
+ tokens: in 1.2M (cache read 62%, cache write 35%), out 310k
647
663
  duration: median 87s, p90 2m40s, max 10m00s
648
664
  outcomes: blocked 1, done 27, partial 3
649
665
  failures: timeout 1, usage_limit 1
650
666
 
651
667
  Per agent
652
668
  analytic 18 runs $ 8.9441 median 2m04s p90 2m51s
669
+ tokens: in 800k (cache read 62%, cache write 35%), out 210k
670
+ model: claude-fable-5-2 +1 more
653
671
  done 15, partial 3
654
672
  gitlab 12 runs $ 3.7949 median 60s p90 86s
673
+ tokens: in 400k (cache read 62%, cache write 35%), out 100k
674
+ model: claude-fable-5-2
655
675
  done 12 | 1 cached
656
676
  ```
657
677
 
658
678
  `--agent NAME` narrows it, `--json` emits the same report as JSON.
679
+ The text's `in` includes uncached input, cache reads, and cache writes; its
680
+ percentages use that combined input. JSON keeps those counts separate in
681
+ `tokens: {input, output, cache_read, cache_write, records}`, adds
682
+ `cache_read_share` rounded to three decimals when total input is nonzero,
683
+ and counts dispatches by primary model in `models`. `records` counts live
684
+ dispatches with valid token measurements; older records and cache hits do
685
+ not dilute the share. Each agent's text shows its most frequent model and
686
+ how many other models were recorded. Runs that fail or reach the spend cap
687
+ still contribute their reported usage. Token telemetry is journal-only:
688
+ tool responses, job files, and discovery's `typical` block stay compact.
659
689
 
660
690
  The journal is what makes three other things work: the `typical` block in
661
691
  `list_agents` / `inspect_agent`, the timeout error naming a value derived from
@@ -689,8 +719,19 @@ past dispatches and deleting them cannot be undone. Pending and running jobs are
689
719
  never touched.
690
720
 
691
721
  `agent-dispatch gc --days N` and the `dispatch_gc` tool apply the same rule as a
692
- one-off. Both *delete* immediately and report the count; neither previews, so
693
- check what is there first with `agent-dispatch jobs`.
722
+ one-off. Preview eligible records before deleting them:
723
+
724
+ ```bash
725
+ agent-dispatch gc --days 30 --dry-run
726
+ agent-dispatch gc --days 30
727
+ ```
728
+
729
+ `--dry-run` also works with `--all`. The MCP equivalent is
730
+ `dispatch_gc(max_age_days=30, dry_run=True)`, returning `dry_run: true`,
731
+ `purged: 0`, `would_purge`, `job_ids`, and `max_age_days`.
732
+ A preview is a snapshot; deletion checks eligibility again, so its count can
733
+ change as jobs finish. Unreadable records, invalid timestamps, and records whose
734
+ internal ID differs from their filename are skipped and preserved for inspection.
694
735
 
695
736
  ### Auto-Description
696
737
 
@@ -725,8 +766,8 @@ Your Claude Code session
725
766
  ▼
726
767
  agent-dispatch MCP server
727
768
  ├─ cache check → hit? return cached result
728
- ├─ semaphore → limit concurrent processes
729
- └─ subprocess.run("claude -p ...", cwd=~/projects/infra/)
769
+ ├─ shared process limit → bound concurrency across all dispatch tools
770
+ └─ subprocess.Popen(["claude", "-p", ...], cwd=~/projects/infra/)
730
771
  │
731
772
  ▼
732
773
  New Claude Code session in ~/projects/infra/
@@ -745,9 +786,9 @@ agent-dispatch MCP server
745
786
  - **Path-traversal guard** — caller-supplied `job_id`/`ref` values are validated as 32-char hex before any filesystem access.
746
787
  - **Owner-only state** — job files, `agents.yaml`, the usage journal and the server registry are all written `0o600`; their directories are `0o700`.
747
788
  - **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.
748
- - **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`.
749
- - **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.
750
- - **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`, results flagged `budget_exceeded`, and results the agent itself reported as `partial` / `blocked` 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.
789
+ - **Concurrency** — `max_concurrency` (default: 5) caps parallel `claude -p` processes across all dispatch tools within one server process. Ordinary, streaming, and background dispatches share the same limit, and waiting calls are served in arrival order, so a queue of background jobs cannot starve an interactive call. Cancelling a waiting call never starts its process; cancelling an already-started ordinary or streaming call keeps its slot occupied until the worker ends. Reloading a changed limit preserves occupied slots: lowering it lets existing work finish and holds new launches until capacity is available. Separate server processes each have their own limit.
790
+ - **Timeout** — per-agent or global (default: 300s). Both ordinary and streaming dispatches run the agent in its own process group. On POSIX, the deadline kills that group, including descendants that inherited output pipes. Ordinary dispatch also bounds cleanup to one additional second if a descendant deliberately detached from the group; that detached process is outside the group's reach. A complete CLI result survives cleanup timeout, with a hint on successful results.
791
+ - **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests under the same agent configuration and dispatch defaults return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only clean successes are cached: failures, results with `denied_tools`, results flagged `budget_exceeded`, and results the agent itself reported as `partial` / `blocked` 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.
751
792
  - **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.
752
793
 
753
794
  See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
@@ -758,20 +799,57 @@ See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassP
758
799
  |---------|-------------|
759
800
  | `agent-dispatch init` | Create config + register MCP server with Claude Code |
760
801
  | `agent-dispatch add <name> <dir>` | Add an agent (auto-generates description) |
761
- | `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, `--instructions`, etc.) |
802
+ | `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, `--instructions`, `--no-skills`, `--strict-mcp`, etc.) |
762
803
  | `agent-dispatch remove <name>` | Remove an agent |
763
804
  | `agent-dispatch list` | List agents with health status and permissions |
764
805
  | `agent-dispatch group <add\|list\|inspect\|update\|remove>` | Manage [groups](#groups) — cross-project working sets of agents |
765
806
  | `agent-dispatch describe <name>` | Show full configuration for one agent (tri-state tools, project files) |
766
807
  | `agent-dispatch test <name> [task] [--stream]` | Test an agent with a dispatch (`--stream` for live progress) |
767
808
  | `agent-dispatch stats [--days N --agent X --json]` | What dispatches cost: spend, durations, outcomes and failures per agent |
768
- | `agent-dispatch doctor` | Diagnose installation: Claude CLI (incl. `--append-system-prompt` support), running servers on stale code, MCP registration, agent health, and group membership |
769
- | `agent-dispatch jobs [--status --limit]` | List async dispatch jobs (most recent first) |
770
- | `agent-dispatch job <id>` | Show one job: status, progress tail, result preview |
809
+ | `agent-dispatch doctor [--json --strict]` | Diagnose installation, stale servers, MCP registration, agent health, and group membership; `--strict` also fails on warnings |
810
+ | `agent-dispatch jobs [--status STATUS --agent NAME --limit N --json]` | List recent job summaries, including results stored with `return_ref` |
811
+ | `agent-dispatch job <id> [--json]` | Show one job; `--json` exports the full record without truncation |
771
812
  | `agent-dispatch cancel <id>` | Cancel a pending job (running jobs: use the `dispatch_cancel` MCP tool) |
772
- | `agent-dispatch gc [--days N \| --all]` | Purge terminal jobs older than N days (default 7; `--all` purges every age) |
813
+ | `agent-dispatch gc [--days N \| --all] [--dry-run]` | Purge terminal jobs older than N days (default 7; `--all` purges every age); `--dry-run` previews without deleting |
773
814
  | `agent-dispatch serve` | Start MCP server (stdio, used by Claude Code) |
774
815
 
816
+ To check an installation from a script:
817
+
818
+ ```bash
819
+ agent-dispatch doctor --json --strict > diagnostics.json
820
+ ```
821
+
822
+ The report contains `schema_version: 1`, overall `status` (`ok`, `warn`, or
823
+ `fail`), `issues` and `warnings` counts, and a `checks` array. Each check has a
824
+ `section`, `status`, `message`, and `details` array containing any remediation
825
+ steps or supporting information. JSON is emitted even when checks fail.
826
+ Failures exit with code 1; warnings exit with code 0 unless `--strict` is set.
827
+ The same checks and exit policy apply to the normal human-readable output.
828
+ This checks installation and configuration; it does not run a paid dispatch.
829
+
830
+ To inspect history from scripts or save a full result:
831
+
832
+ ```bash
833
+ agent-dispatch jobs --agent infra --status failed --limit 10 --json
834
+ agent-dispatch job <job_id> --json > job.json
835
+ ```
836
+
837
+ `jobs --json` returns an array of compact summaries in the same format as
838
+ `dispatch_jobs`, or `[]` if no jobs match. Each summary includes the ID, agent,
839
+ status, first 120 task characters, and timestamps; result cost, success, outcome,
840
+ error type, and latest running progress are included when available.
841
+ `job --json` returns the full stored job, including task/context, progress,
842
+ result text, structured result, session ID, and recovery hints when present.
843
+ Both formats preserve Unicode. Reading a failed job still exits successfully:
844
+ check its `status` and `result.success` to determine the dispatch outcome.
845
+ Missing/invalid job IDs and storage-open failures return `{"error": "..."}`
846
+ with exit code 1. Invalid command-line options are reported by Click on stderr.
847
+
848
+ Invalid or non-finite cost metadata is treated as unknown and omitted from
849
+ result exports; it does not hide the stored result text. Usage summaries ignore
850
+ unusable numeric measurements, and doctor omits uptime when a server's start
851
+ timestamp is unreadable.
852
+
775
853
  ## Requirements
776
854
 
777
855
  - Python >= 3.10