agent-dispatch 0.6.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.6.0 → agent_dispatch-0.8.0}/CHANGELOG.md

@@ -7,6 +7,67 @@ 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"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.6.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
+claude --version   # must print a version — if it fails, install Claude Code before continuing
+```
+
+Then:
+
 ```bash
-pip install agent-dispatch
+pip install agent-dispatch   # or: pipx install agent-dispatch
 
-# Initialize: creates config + registers MCP server with Claude Code
+# 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"]
   }
@@ -132,6 +166,17 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 | `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)
 {
@@ -307,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 |
@@ -323,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 |
@@ -373,7 +420,7 @@ dispatch_status(job_id="8f3a...e1")
   -> {"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, ...}}
 
@@ -381,13 +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` |
 |-------------------|------------------------|
@@ -395,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 |
@@ -418,6 +457,30 @@ All tools return errors as:
 | 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
 
 Config at `~/.config/agent-dispatch/agents.yaml` (override: `AGENT_DISPATCH_CONFIG` env var):
@@ -428,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
@@ -465,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
 
 ```
@@ -491,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.
@@ -510,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
 

{agent_dispatch-0.6.0 → agent_dispatch-0.8.0}/README.md

@@ -15,29 +15,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
+claude --version   # must print a version — if it fails, install Claude Code before continuing
+```
+
+Then:
+
 ```bash
-pip install agent-dispatch
+pip install agent-dispatch   # or: pipx install agent-dispatch
 
-# Initialize: creates config + registers MCP server with Claude Code
+# 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
 
@@ -67,6 +99,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"]
   }
@@ -102,6 +136,17 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 | `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)
 {
@@ -277,9 +322,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 |
@@ -293,6 +339,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 |
@@ -343,7 +390,7 @@ dispatch_status(job_id="8f3a...e1")
   -> {"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, ...}}
 
@@ -351,13 +398,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` |
 |-------------------|------------------------|
@@ -365,14 +412,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 |
@@ -388,6 +427,30 @@ All tools return errors as:
 | 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
 
 Config at `~/.config/agent-dispatch/agents.yaml` (override: `AGENT_DISPATCH_CONFIG` env var):
@@ -398,9 +461,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
@@ -435,6 +503,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
 
 ```
@@ -461,7 +541,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.
@@ -480,12 +560,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