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

agent_dispatch-0.8.0/AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS.md
+
+Guidance for AI coding agents working on this repository.
+
+> **Using agent-dispatch** (not developing it)? Read [README.md](README.md) — it has the full setup path with verify steps and the complete MCP tool reference. This file is for contributing to the codebase.
+
+## What this project is
+
+MCP server + CLI that lets Claude Code agents delegate tasks to agents in other project directories. One sync core, two surfaces:
+
+| File | Role |
+|------|------|
+| `src/agent_dispatch/runner.py` | Sync subprocess wrapper around `claude -p` — the actual work |
+| `src/agent_dispatch/server.py` | Async FastMCP interface (19 MCP tools), wraps runner in `asyncio.to_thread` + semaphore |
+| `src/agent_dispatch/cli.py` | Click CLI: `init`, `add`, `update`, `remove`, `list`, `describe`, `test`, `doctor`, `jobs`, `job`, `cancel`, `gc`, `serve` |
+| `src/agent_dispatch/models.py` | Pydantic v2 models (`AgentConfig`, `Settings`, `DispatchResult`) |
+| `src/agent_dispatch/config.py` | YAML config load/save + project auto-description |
+| `src/agent_dispatch/cache.py` | Thread-safe in-memory TTL cache |
+| `src/agent_dispatch/jobs.py` | Persistent per-job JSON files for async dispatch |
+
+## Dev setup
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Gates — both must pass before a change is done (CI rejects otherwise)
+
+```bash
+ruff check src/ tests/
+python3 -m pytest tests/ -v   # 428 tests, ~2s — all subprocess calls are mocked
+```
+
+Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.which` + `subprocess.run`/`Popen`; server tests mock `_get_config` + `runner.dispatch`.
+
+## Non-obvious invariants (violating these breaks real behavior)
+
+- `allowed_tools` / `disallowed_tools` are **tri-state**: `None` = inherit settings defaults, `[]` = explicitly no tools, `[...]` = exactly these. Check with `is not None`, never `or` — `[]` is falsy but semantically distinct.
+- `denied_tools` non-empty + `is_error` ⇒ `error_type="permission"`, regardless of what the error text matches.
+- On failure, callers read `DispatchResult.error` + `error_type` — `result` holds the raw agent output even on errors.
+- `--session-id` and `--resume` conflict — never pass both to `claude`.
+- Valid permission modes: `default`, `plan`, `bypassPermissions` (`models.py: KNOWN_PERMISSION_MODES`).
+- `JobStore.finish`/`fail` refuse already-terminal jobs (returns `None`) — this closes the race with force-cancel; never "fix" it by overwriting.
+- Cancelling a *running* job requires the in-memory `_running_procs` registry (server.py) — the job is marked `cancelled` **before** the subprocess is killed. Don't persist PIDs to disk (PID reuse after restart could kill an unrelated process).
+- `max_budget_usd` is **post-hoc**: `_apply_budget` (runner.py) sets `budget_exceeded` + `hint` after the cost is known; it never fails the dispatch.
+
+## Conventions
+
+Python ≥ 3.10 · `from __future__ import annotations` everywhere · Pydantic v2 · Click (CLI) + FastMCP (server) · ruff, line length 100 · all MCP tools return JSON strings, errors as `{"error": "..."}`.
+
+## When adding a feature, check every layer
+
+`models.py` (data shape) → `runner.py` (dispatch mechanics) → `server.py` (MCP tool) → `cli.py` (CLI flag) → tests for each → `README.md` + `agents.example.yaml` (user docs).
+
+## More detail
+
+[README.md](README.md) documents every MCP tool with parameter tables, response shapes, and the error-recovery map — it doubles as the behavioral spec. The test suite (`tests/`, 428 tests) encodes the exact expected behavior of every layer: when in doubt, read the tests for the module you're touching (`test_runner.py`, `test_server.py`, `test_cli.py`, ...).

{agent_dispatch-0.5.0 → agent_dispatch-0.8.0}/CHANGELOG.md

@@ -7,6 +7,123 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-06-17
+
+Let agents declare what they are good at, so callers can pick the right one.
+
+### Added
+- **Declared capabilities.** `AgentConfig` gains `capabilities` and
+  `risky_capabilities` — short snake_case labels describing what an agent is
+  for (e.g. `docker_logs`, `restart_services`). They are descriptive metadata
+  only (never passed to the `claude` CLI): settable via `add_agent` /
+  `update_agent` (MCP) and `add` / `update` (CLI, `--capabilities` /
+  `--risky-capabilities`, `none` clears), and surfaced in `list_agents` /
+  `inspect_agent` so the calling agent can choose a target at a glance.
+  `risky_capabilities` flags higher-risk abilities for extra scrutiny.
+
+### Changed
+- `save_config` no longer writes empty `capabilities` / `risky_capabilities`
+  keys for agents that don't declare them, keeping `agents.yaml` clean.
+
+### Note
+- A keyword-scoring router (`recommend_agent` / `dispatch_auto` MCP tools and
+  `recommend` / `auto` CLI commands) was prototyped during this cycle and then
+  removed before release: a deterministic keyword scorer adds little over the
+  calling LLM's own judgment when there are only a handful of agents, and the
+  capability labels above cover the "what is this agent for" need without the
+  extra surface area or the risk of auto-dispatching to a wrong guess.
+
+## [0.7.0] - 2026-06-10
+
+Job control release: running jobs become cancellable, the budget field stops
+being decorative, and async jobs get a CLI.
+
+### Added
+- **Cancel running jobs.** `dispatch_cancel(job_id)` now kills a *running*
+  job's `claude` subprocess when the job was started by the same server
+  instance (in-memory process registry — no PID files, no risk of killing an
+  unrelated process after a restart). The job is marked `cancelled` *before*
+  the kill, and `JobStore.finish`/`fail` now refuse already-terminal jobs, so
+  the worker's trailing write can't resurrect it. New outcome:
+  `cancelled_running`. Jobs from a previous server run still report
+  `running` (cannot be killed safely).
+- **Budget visibility (post-hoc).** `max_budget_usd` was stored and displayed
+  but never checked. A dispatch whose `cost_usd` exceeds the agent's
+  `max_budget_usd` (or `settings.default_max_budget_usd`) now returns
+  `budget_exceeded: true` plus a `hint`. The dispatch is *not* failed — the
+  `claude` CLI has no spend cap, so by the time the cost is known the money is
+  spent; the flag makes runaway agents visible instead of silent.
+- **CLI for async jobs.** New commands: `agent-dispatch jobs [--status
+  --limit]` (list), `agent-dispatch job <id>` (detail with progress tail and
+  result preview), `agent-dispatch cancel <id>` (pending jobs; running jobs
+  belong to the MCP server process), `agent-dispatch gc [--days]` (purge old
+  terminal jobs).
+- **PyPI discoverability:** expanded package keywords (5 → 12).
+
+### Changed
+- `runner.dispatch_stream` accepts an `on_proc` callback (receives the Popen
+  handle right after spawn) — used by the async worker to register the
+  process for cancellation.
+- `JobStore.cancel` accepts `force=True` to cancel running jobs (callers must
+  kill the subprocess themselves); `finish`/`fail` return `None` for terminal
+  jobs instead of overwriting them.
+
+## [0.6.0] - 2026-06-04
+
+Reliability release: timeouts stop being fatal, permission-blocked "successes"
+become visible, async jobs show live progress.
+
+### Fixed
+- **`dispatch_stream` was broken on current claude CLIs** — they reject
+  `--print --output-format stream-json` without `--verbose` ("requires
+  --verbose"), so every stream dispatch (and CLI `test --stream`) failed
+  immediately. The runner now passes `--verbose`. Caught by live verification
+  against the real CLI before this release; without it the async-worker
+  switch to streaming (below) would have broken all `dispatch_async` jobs.
+
+### Added
+- **Per-call timeout override.** `dispatch`, `dispatch_session`,
+  `dispatch_stream`, and `dispatch_async` accept `timeout_seconds` (0 = agent
+  default, clamped to 10–7200); `dispatch_parallel` accepts it per item. Use
+  it for known-long tasks instead of editing the agent config. CLI:
+  `agent-dispatch test <name> --timeout N`.
+- **Resumable timeouts.** Fresh dispatches pre-assign a session UUID via
+  `--session-id`, so a timed-out dispatch still returns a `session_id` — the
+  partial transcript survives the kill. The timeout error now spells out the
+  recovery options: resume via `dispatch_session(..., session_id=...)`, retry
+  with `timeout_seconds`, or go async.
+- **Denied-tools visibility.** The claude CLI's `permission_denials` output is
+  parsed into `DispatchResult.denied_tools`. A dispatch that "succeeds" while
+  tools were blocked (the agent answers "I need permission for X") now carries
+  `denied_tools` + a `hint` that the result may be incomplete and how to grant
+  access. On `is_error` results, non-empty denials force
+  `error_type="permission"` even when the error text has no permission
+  keywords. CLI `test` prints the hint as a yellow note.
+- **Async job progress.** Async workers now run with streaming: the job file
+  keeps a rolling tail (last 20 lines, throttled to ~1 write/sec) of assistant
+  text and tool-use events. `dispatch_status` returns it as `progress` while
+  running (kept afterwards as a post-mortem trace); `dispatch_jobs` shows
+  `last_progress` for running jobs. New `JobStore.update_progress` (refuses
+  terminal jobs, so a trailing write can't resurrect a finished job).
+
+### Changed
+- Timeout error messages are actionable (mention `timeout_seconds`,
+  `dispatch_async`, `agent-dispatch update --timeout`, and the resumable
+  session) instead of just "increase timeout in agents.yaml".
+- Plain-text fallback successes now carry the generated `session_id`; the
+  stream "no result line" fallback does too (a crash mid-stream stays
+  resumable).
+- **Old-CLI self-healing**: if the installed claude CLI predates
+  `--session-id`, dispatch detects the "unknown option" rejection and retries
+  once without the flag (logged warning; timed-out dispatches lose
+  resumability) instead of failing every dispatch.
+- `dispatch_parallel` validates per-item `timeout_seconds` / `summary_chars`
+  numerically **up front** — a bad value rejects the whole call before any
+  dispatch runs, consistent with the structural validation contract.
+- `denied_tools` parsing is bounded (10 entries, 100 chars per name) — the
+  field comes from the dispatched subprocess's output, which is untrusted;
+  unbounded lists could inflate job files and `return_ref` payloads.
+
 ## [0.5.0] - 2026-06-01
 
 Security-hardening release. A multi-agent audit of the codebase surfaced
@@ -214,7 +331,8 @@ 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.5.0...HEAD
+[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/ginkida/agent-dispatch/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/ginkida/agent-dispatch/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/ginkida/agent-dispatch/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/ginkida/agent-dispatch/compare/v0.2.2...v0.3.0

{agent_dispatch-0.5.0 → agent_dispatch-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.5.0
+Version: 0.8.0
 Summary: MCP server that lets Claude Code agents delegate tasks to agents in other project directories
 Project-URL: Homepage, https://github.com/ginkida/agent-dispatch
 Project-URL: Repository, https://github.com/ginkida/agent-dispatch
@@ -8,7 +8,7 @@ Project-URL: Issues, https://github.com/ginkida/agent-dispatch/issues
 Author: ginkida
 License-Expression: MIT
 License-File: LICENSE
-Keywords: agent,claude,dispatch,mcp,multi-agent
+Keywords: agent,agent-orchestration,ai-agents,anthropic,claude,claude-code,delegation,dispatch,mcp,mcp-server,multi-agent,subagents
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -45,29 +45,61 @@ Each agent runs as a separate `claude -p` session in its own project directory
 
 Works with OAuth, API key, and Claude subscription authentication.
 
+> **AI agents:** this README is the canonical doc for *using* the tool — setup: [Quick Start](#quick-start) (every step has a deterministic verify), first call: [`dispatch`](#dispatch), tool selection: [Which Tool to Use](#which-tool-to-use), failure handling: [Error Recovery](#error-recovery). Working *on* this repo instead? See [AGENTS.md](AGENTS.md).
+
 ## Quick Start
 
+**Prerequisite:** the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) must be installed and authenticated. Check first:
+
 ```bash
-pip install agent-dispatch
+claude --version   # must print a version — if it fails, install Claude Code before continuing
+```
+
+Then:
 
-# Initialize: creates config + registers MCP server with Claude Code
+```bash
+pip install agent-dispatch   # or: pipx install agent-dispatch
+
+# 1. Create config + register the MCP server with Claude Code (user scope)
 agent-dispatch init
 
-# Add agents (description auto-generated from project files)
+# 2. Register project directories as agents — REPLACE the example paths with
+#    real directories on your machine; they must exist (~ is expanded, relative
+#    paths are resolved). Descriptions are auto-generated from project files.
+#    No second project handy? Use the zero-setup block below instead.
 agent-dispatch add infra ~/projects/infra
 agent-dispatch add backend ~/projects/backend
 
-# Test it works
+# 3. Smoke test — dispatches a real task to the agent added in step 2 and prints
+#    the answer; exit 0 on success. Default task when none given:
+#    "What project is this? Describe in one sentence."
 agent-dispatch test infra
 
-# If agents hit permission errors, grant tool access:
-agent-dispatch update infra --permission-mode bypassPermissions
-
-# If something doesn't work, run the diagnostic:
+# 4. Verify the whole install — prints "All checks passed." and exits 0 on success
 agent-dispatch doctor
 ```
 
-Done. Every Claude Code session now has access to all dispatch tools.
+**Zero-setup alternative** for steps 2–3 (no second project needed — registers the current directory):
+
+```bash
+agent-dispatch add self . && agent-dispatch test self "Say hello"
+```
+
+Every Claude Code session now has the dispatch tools. Independent check: `claude mcp list` must print a line starting with `agent-dispatch:`. From inside a Claude Code session, the first MCP calls are `list_agents()`, then [`dispatch(...)`](#dispatch).
+
+**If `init` fails to register the MCP server** (prints a warning instead of `Registered MCP server`), register manually:
+
+```bash
+claude mcp add-json agent-dispatch "{\"type\":\"stdio\",\"command\":\"$(which agent-dispatch)\",\"args\":[\"serve\"]}" --scope user
+```
+
+**If `test` fails with a permission error** (`error_type: "permission"`), grant tool access and re-test:
+
+```bash
+agent-dispatch update infra --allowed-tools "Bash,Read,Grep"      # least privilege
+# or, if the agent needs everything (see SECURITY.md for the trade-off):
+agent-dispatch update infra --permission-mode bypassPermissions
+```
 
 ## When to Dispatch
 
@@ -97,6 +129,8 @@ Lists all configured agents. **Call this first** to see what's available.
     "mcp_servers": ["portainer", "postgres"],
     "stacks": ["Python", "Docker"],
     "dbs": ["Alembic"],
+    "capabilities": ["docker_logs", "deploy_debug"],
+    "risky_capabilities": ["restart_services"],
     "permission_mode": "bypassPermissions",
     "allowed_tools": ["Bash", "Read", "Grep"]
   }
@@ -130,6 +164,18 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 | `response_format` | string | no | `"json"` to request a single JSON value; the parsed result lands in `parsed_result`. Empty = free-form text. |
 | `return_ref` | bool | no | When `true`, returns just a `ref` + summary preview instead of the full result text. Use `fetch_result(ref)` to load the full text on demand. |
 | `summary_chars` | int | no | Max chars of result text to include in the ref response (default 500). |
+| `timeout_seconds` | int | no | One-off timeout override for this call (0 = agent's configured timeout; clamped to 10–7200). No config edit needed for known-long tasks. |
+
+```python
+# Call — recommended form (always include caller and goal)
+dispatch(
+    agent="infra",                # must exist in list_agents()
+    task="Check container logs for errors related to the scheduler service",
+    context="Error: TypeError at scheduler.py:42",
+    caller="backend",             # your project/role
+    goal="debug production crash" # the broader objective
+)
+```
 
 ```json
 // Response (success)
@@ -155,6 +201,21 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 
 **`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `cli_error` (other failures). Permission errors include an actionable hint.
 
+**Resumable timeouts:** every fresh dispatch pre-assigns a session UUID (`--session-id`), so a timed-out dispatch still returns a `session_id` — the partial transcript survives the kill. The timeout error spells out the recovery: resume with `dispatch_session(agent, "Continue where you left off", session_id=...)`, retry with a bigger `timeout_seconds`, or use `dispatch_async`.
+
+**Denied-tools visibility:** in non-interactive mode the claude CLI auto-denies tools the agent isn't allowed to use — the agent then often "succeeds" with an answer like *"I need your permission for one read-only query"*. When that happens the response carries the deterministic signal: `denied_tools` (parsed from the CLI's `permission_denials`) plus a `hint` explaining the result may be incomplete and how to grant access. `success` stays `true` — it's a soft signal, not a failure.
+
+```json
+// Response (success, but a tool was blocked)
+{
+  "agent": "analysis",
+  "success": true,
+  "result": "Here is the offline mapping. To finish I'd need to run one read-only query...",
+  "denied_tools": ["Bash"],
+  "hint": "1 tool call(s) were denied by permissions: Bash. The result may be incomplete..."
+}
+```
+
 **Structured JSON output:** pass `response_format="json"` to ask the agent for a single JSON value. The runner appends an instruction footer ("respond with a single valid JSON value, no fences, no prose") and on success parses the response — the parsed value lands in `parsed_result`. The raw text is always in `result`. Parse failures leave `parsed_result=None` but don't fail the dispatch (soft mode).
 
 ```json
@@ -195,6 +256,9 @@ Multi-turn: continue a conversation with an agent. First call starts a session,
 | `context` | string | no | Extra context |
 | `caller` | string | no | Who is dispatching |
 | `goal` | string | no | Broader objective |
+| `timeout_seconds` | int | no | One-off timeout override (0 = agent default; clamped to 10–7200) |
+
+`dispatch_session` is also the **timeout recovery path**: a timed-out `dispatch` returns a `session_id` — pass it here with `task="Continue where you left off"` to salvage the partial work instead of restarting.
 
 ```
 Turn 1: dispatch_session("infra", "List running containers")
@@ -210,7 +274,7 @@ Run multiple tasks concurrently. Much faster than sequential `dispatch` calls.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `dispatches` | string (JSON) | yes | JSON array of `{"agent", "task", "context?", "caller?", "goal?"}` |
+| `dispatches` | string (JSON) | yes | JSON array of `{"agent", "task", "context?", "caller?", "goal?", "response_format?", "return_ref?", "summary_chars?", "timeout_seconds?"}` |
 | `aggregate` | string | no | Agent name to synthesize all results into one answer |
 
 **Important:** `dispatches` is a JSON string, not a list.
@@ -250,7 +314,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 identical to `dispatch`.
+Parameters are the same as `dispatch` except `return_ref`/`summary_chars` (streaming is incompatible with ref-mode).
 
 ### `dispatch_dialogue`
 
@@ -288,9 +352,10 @@ Register a new project directory as an agent. Description is auto-generated from
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `name` | string | yes | Agent name (letters, digits, hyphens, underscores) |
-| `directory` | string | yes | Absolute path to project directory |
+| `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) |
 | `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 |
@@ -304,6 +369,7 @@ 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) |
 | `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 |
@@ -344,15 +410,17 @@ Refs reuse the same storage as `dispatch_async` jobs (under `~/.config/agent-dis
 When a dispatched task is going to take a while, you don't want to block your own tool slot for minutes. Async dispatch returns a `job_id` immediately and lets you check back when you're ready.
 
 ```
-// 1. fire and forget
+// 1. fire and forget (timeout_seconds= works here too for known-long tasks)
 dispatch_async(agent="infra", task="audit every container log for OOM kills today")
   -> {"job_id": "8f3a...e1", "status": "pending", "agent": "infra"}
 
 // 2. do other work, then check progress (non-blocking)
+//    `progress` is a rolling tail of what the agent is doing right now
 dispatch_status(job_id="8f3a...e1")
-  -> {"id": "8f3a...e1", "status": "running", "started_at": 1730000123.4, ...}
+  -> {"id": "8f3a...e1", "status": "running", "started_at": 1730000123.4,
+      "progress": ["Using tool: Bash", "Scanning container logs for OOM events..."], ...}
 
-// 3. or block until done (with a timeout cap)
+// 3. or block until done (timeout_seconds default: 60, capped at 3600)
 dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
   -> {"id": "8f3a...e1", "status": "done", "result": {"agent": "infra", "success": true, ...}}
 
@@ -360,11 +428,13 @@ dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
   -> {"id": "...", "status": "running", "timed_out_waiting": true}
 ```
 
-`dispatch_cancel(job_id)` cancels a job that is still **pending** (before its subprocess starts) — a running job is left to finish, since its `claude` subprocess can't be safely interrupted. The response carries an `outcome` of `cancelled`, `running`, `already_terminal`, or `not_found`.
+`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`.
+
+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.
 
 `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 abandoned in `running` by a prior crashed instance as `failed`.
+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).
 
 | When to use async | When to use `dispatch` |
 |-------------------|------------------------|
@@ -372,14 +442,6 @@ Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `A
 | Several long tasks you'll collect later | Several short tasks → `dispatch_parallel` |
 | Don't care about caching (each call is a fresh job) | Cached by default — identical requests are free |
 
-### Error Responses
-
-All tools return errors as:
-
-```json
-{"error": "Unknown agent: 'foo'. Available: infra, db, monitoring"}
-```
-
 ## Which Tool to Use
 
 | Scenario | Tool |
@@ -392,6 +454,32 @@ All tools return errors as:
 | Need a combined summary from multiple agents | `dispatch_parallel` with `aggregate` |
 | Long task — don't block your tool slot | `dispatch_async` + `dispatch_wait` |
 | Check progress without blocking | `dispatch_status` |
+| Known-long task, one-off | any dispatch tool with `timeout_seconds=...` |
+| A dispatch timed out | `dispatch_session` with the `session_id` from the error |
+
+## Error Recovery
+
+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`. |
+| `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. |
+| `cli_error` | Anything else from the `claude` subprocess | Read the `error` text; run `agent-dispatch doctor` for environment issues; retry once if transient. |
+
+Three soft signals that arrive with `success: true`:
+
+- **`denied_tools` + `hint`** — the agent finished but some tool calls were blocked; the result may be incomplete. Grant access (see the `permission` row) and re-dispatch.
+- **`parsed_result: null` with `response_format="json"`** — the reply wasn't valid JSON; the raw text is still in `result`. Caveat: an agent that *can't* comply returns `{"error": "<reason>"}` — which parses successfully — so also check `parsed_result` for an `"error"` key.
+- **`budget_exceeded: true`** — `cost_usd` exceeded the agent's `max_budget_usd` (or the settings default). The dispatch is not failed — the money is already spent — but a runaway agent is now visible. Tighten the task, pick a cheaper model, or raise the budget.
+
+Tool-level errors (unknown agent, malformed input) return a plain envelope instead of a `DispatchResult`:
+
+```json
+{"error": "Unknown agent: 'foo'. Available: infra, db, monitoring"}
+```
 
 ## Configuration
 
@@ -403,9 +491,14 @@ agents:
     directory: ~/projects/infra
     description: "Infrastructure agent. MCP: portainer."
     timeout: 300            # seconds, default: 300
+    capabilities:           # capability labels, shown in list_agents
+      - docker_logs
+      - deploy_debug
+    risky_capabilities:     # high-risk labels, surfaced for visibility
+      - restart_services
     # model: sonnet         # optional model override
     # max_budget_usd: 1.0   # cost limit per dispatch
-    # permission_mode: auto # permission mode for the agent
+    # permission_mode: bypassPermissions  # one of: default | plan | bypassPermissions
     # allowed_tools:        # restrict which tools the agent can use
     #   - Read
     #   - Grep
@@ -440,6 +533,18 @@ Config is reloaded on every tool call — add agents without restarting.
 - Stack indicators — Docker, Rust, Go, Python, Node.js
 - DB indicators — Prisma, Alembic, migrations
 
+### Explicit Capabilities
+
+Auto-description is useful, but explicit `capabilities` make it clearer what each agent is for. Add short snake_case task labels to agents:
+
+```bash
+agent-dispatch update infra \
+  --capabilities docker_logs,deploy_debug \
+  --risky-capabilities restart_services
+```
+
+`list_agents` and `inspect_agent` surface `capabilities` and `risky_capabilities` so the caller can pick the right agent at a glance — `risky_capabilities` flags higher-risk abilities (e.g. restarting services) for extra scrutiny.
+
 ## How It Works
 
 ```
@@ -466,7 +571,7 @@ agent-dispatch MCP server
 - **Argument-injection guard** — structured CLI fields (`session_id`, `model`, `permission_mode`, tool names) that start with `-` are rejected so they can't smuggle extra `claude` flags.
 - **Path-traversal guard** — caller-supplied `job_id`/`ref` values are validated as 32-char hex before any filesystem access.
 - **Owner-only state** — job files (`0o600`) and `agents.yaml` (`0o600`) are written for the owner only; their directories are `0o700`.
-- **Cost control** — `max_budget_usd` per agent or globally.
+- **Cost visibility** — `max_budget_usd` per agent or globally; a dispatch whose cost exceeds it returns `budget_exceeded: true` + a hint (post-hoc — the `claude` CLI has no spend cap, so the overage can be flagged but not prevented).
 - **Concurrency** — `max_concurrency` (default: 5) caps parallel `claude -p` processes. Note: the sync and async dispatch paths use separate semaphores, so the worst-case total is `2 × max_concurrency`.
 - **Timeout** — per-agent or global (default: 300s). Orphaned processes are cleaned up.
 - **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only successes are cached. Sessions and dialogues are never cached.
@@ -485,12 +590,16 @@ See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassP
 | `agent-dispatch describe <name>` | Show full configuration for one agent (tri-state tools, project files) |
 | `agent-dispatch test <name> [task] [--stream]` | Test an agent with a dispatch (`--stream` for live progress) |
 | `agent-dispatch doctor` | Diagnose installation: claude CLI, MCP registration, agent health |
+| `agent-dispatch 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 serve` | Start MCP server (stdio, used by Claude Code) |
 
 ## Requirements
 
 - Python >= 3.10
-- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed, authenticated, and on `PATH` (verify: `claude --version`)
 
 ## License