agent-dispatch 0.2.2__tar.gz → 0.4.0__tar.gz

agent_dispatch-0.4.0/CHANGELOG.md

@@ -0,0 +1,161 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-05-15
+
+### Added
+- Result references — `dispatch(..., return_ref=True)` and per-item in
+  `dispatch_parallel` now return a compact `{ref, agent, success, size,
+  summary, summary_chars, cost_usd, ...}` payload instead of the full
+  result text. The full DispatchResult is persisted to disk (reusing the
+  async JobStore) and can be loaded on demand via the new
+  `fetch_result(ref, max_chars=0)` MCP tool. Saves caller context when
+  the result is large; the JSON parsed_result (small by nature) is still
+  inlined alongside the ref. fetch_result also works on any
+  `dispatch_async` job_id — the storage is shared.
+- `JobStore.create_completed(...)` — persists an already-finished
+  DispatchResult as a Job in terminal state. Used by ref mode; future
+  iterations can use it for result archival.
+- Structured JSON response support — `dispatch`, `dispatch_session`,
+  `dispatch_async`, `dispatch_stream`, and per-item in `dispatch_parallel`
+  now accept `response_format="json"`. When set, the runner appends a clear
+  "respond with a single JSON value, no prose, no fences" footer to the
+  prompt and attempts to parse the agent's response (tolerating ```json
+  fences). The parsed value lands in a new `DispatchResult.parsed_result`
+  field — `None` when not requested or unparseable (soft mode: parse
+  failure does NOT mark the dispatch as failed). Cache key now includes
+  `response_format` so JSON and text requests for the same task don't
+  collide.
+- `list_agents` MCP tool now surfaces `mcp_servers`, `stacks`, and `dbs`
+  per agent (when present) — the same structured data `auto_describe`
+  already collects from `.mcp.json`, `Dockerfile`, `pyproject.toml`,
+  `package.json`, `Cargo.toml`, `go.mod`, `prisma/`, `alembic.ini`, etc.
+  Calling agents no longer need to dispatch a probe just to learn what
+  tools the target has.
+- New `inspect_agent(name, preview_lines=40)` MCP tool — cheap detailed
+  lookup without a `claude` subprocess. Returns the agent's full config
+  fields (timeout, model, budget, permission_mode, tool lists), detected
+  MCP/stacks/DBs, plus short previews of `CLAUDE.md` and `README.md` so
+  the caller can confirm capabilities before spending a real dispatch.
+- `config.collect_mcp_servers()`, `config.detect_stacks()`, and
+  `config.detect_dbs()` are now public helpers (the previous private
+  `_collect_mcp_servers` remains as an alias for compatibility).
+- Async dispatch with a `job_id` pattern — five new MCP tools let calling
+  agents fire-and-forget long-running tasks without blocking their own tool
+  slot:
+  - `dispatch_async(agent, task, ...)` — start a dispatch in the background,
+    returns `{job_id, status: "pending", agent}` immediately.
+  - `dispatch_status(job_id)` — read the current state of a job without
+    blocking (pending / running / done / failed) including the
+    `DispatchResult` once complete.
+  - `dispatch_wait(job_id, timeout_seconds=60)` — block until terminal or
+    until the timeout fires (capped at 3600s). Returns the same shape as
+    `dispatch_status` plus `timed_out_waiting: true` on timeout — the job
+    keeps running and the caller can poll/wait again.
+  - `dispatch_jobs(status?, limit=50)` — list recent jobs as summaries,
+    optionally filtered by status (most recent first).
+  - `dispatch_gc(max_age_days=7)` — purge terminal jobs older than the
+    threshold. Pending and running jobs are never touched.
+- Job state persists to disk as one JSON file per job under
+  `~/.config/agent-dispatch/jobs/` (override via `AGENT_DISPATCH_JOBS_DIR`).
+  Atomic writes via `os.replace()` so partial files never appear, and jobs
+  survive across server restarts (existing terminal jobs remain queryable,
+  in-flight jobs are abandoned on restart — to be addressed in a future
+  iteration with PID tracking).
+
+## [0.3.0] - 2026-05-08
+
+### Added
+- `agent-dispatch doctor` CLI command — diagnoses installation issues:
+  checks `claude` CLI on PATH, `agent-dispatch` on PATH, config validity,
+  MCP registration with Claude Code, and per-agent directory health.
+  Exits non-zero if any blocking issue is found.
+- `agent-dispatch describe <name>` CLI command — show one agent's full
+  configuration: directory, description, timeout, model, budget, permission
+  mode, tri-state tool fields (`(inherit defaults)` vs `(none — explicit
+  override)` vs explicit list), and which project files would be inherited.
+- `--stream` flag for `agent-dispatch test` — surfaces live progress
+  (assistant text + tool use) while the agent works, useful for long
+  tasks where you'd otherwise see nothing until completion.
+
+### Fixed
+- `list_agents` MCP tool no longer crashes the entire response when one
+  agent's directory is unreadable (`PermissionError`, network FS hiccup,
+  etc.). The bad agent now reports `healthy: "UNREADABLE"` and the rest
+  of the listing succeeds — matching the documented response shape.
+- Dispatch cache key now includes `caller` and `goal`. Previously two
+  requests with the same `(agent, task, context)` but different framing
+  (e.g. `caller="frontend"` vs `caller="backend"`) would collide and the
+  second request would receive the cached response from the first — even
+  though the structured prompt sent to Claude is materially different.
+
+## [0.2.2] - 2026-04-17
+
+### Fixed
+- `agent-dispatch list` now distinguishes `allowed_tools: None` (inherit
+  from settings defaults) from `allowed_tools: []` (explicitly no tools).
+  Previously both were rendered identically.
+
+## [0.2.1] - 2026-04-17
+
+### Fixed
+- 13 bugs across the runner, server, CLI, config, and models:
+  - Runner: defensive coercion in `_classify_error` for non-string inputs;
+    fallback messages when `is_error=True` produces empty `result`;
+    correct error_type classification on plain-text stdout fallbacks;
+    orphan subprocess cleanup on stream exit paths.
+  - Server: up-front validation in `dispatch_parallel` (rejects bad items
+    before any dispatch runs); `dispatch_dialogue` surfaces per-turn errors;
+    `cache_stats` evicts expired entries before reporting.
+  - CLI: friendly error messages on malformed YAML / invalid schema;
+    `list` handles `OSError` from unreachable directories;
+    sentinel patterns for `update` to clear fields (`"none"` / `""`).
+  - Config: deduplication when collecting MCP servers from multiple paths.
+  - Models: tighter validation bounds (`ge=0`, `ge=1`).
+
+## [0.2.0] - 2026-04-16
+
+### Added
+- Error classification — `DispatchResult.error_type` now reports
+  `permission`, `timeout`, `recursion`, `not_found`, or `cli_error`.
+  Permission errors include an actionable hint with suggested fixes.
+- Permission management — agents and global settings support
+  `permission_mode`, `allowed_tools`, and `disallowed_tools`. Tool lists
+  use tri-state semantics: `None` inherits from defaults, `[]` overrides
+  to "no tools", a list specifies the allowed/disallowed set.
+- `update_agent` MCP tool — modify an existing agent's configuration
+  without remove + re-add. CLI parity via `agent-dispatch update`.
+- CLI tests for `init` and `test` commands.
+
+## [0.1.0] - 2026-04-10
+
+### Added
+- Initial release.
+- 11 MCP tools: `list_agents`, `add_agent`, `remove_agent`, `dispatch`,
+  `dispatch_session`, `dispatch_parallel` (with optional aggregation),
+  `dispatch_stream`, `dispatch_dialogue`, `cache_stats`, `cache_clear`.
+- CLI: `init`, `add`, `remove`, `list`, `test`, `serve`.
+- Recursion protection via `AGENT_DISPATCH_DEPTH` env var.
+- In-memory TTL cache (thread-safe).
+- Concurrency control via `asyncio.Semaphore` (default: 5 parallel
+  `claude -p` processes).
+- Auto-description from `CLAUDE.md`, `README.md`, `pyproject.toml`,
+  `package.json`, `.mcp.json`, and stack/DB indicators.
+- PyPI publishing via Trusted Publisher (OIDC).
+- CI matrix on Python 3.10, 3.11, 3.12, 3.13.
+- Dependabot for `pip` + `github-actions`, GitHub Actions pinned to
+  commit SHAs for supply-chain integrity.
+
+[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.4.0...HEAD
+[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
+[0.2.2]: https://github.com/ginkida/agent-dispatch/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/ginkida/agent-dispatch/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/ginkida/agent-dispatch/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/ginkida/agent-dispatch/releases/tag/v0.1.0

{agent_dispatch-0.2.2 → agent_dispatch-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.2.2
+Version: 0.4.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
@@ -62,6 +62,9 @@ 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:
+agent-dispatch doctor
 ```
 
 Done. Every Claude Code session now has access to all dispatch tools.
@@ -82,7 +85,7 @@ Done. Every Claude Code session now has access to all dispatch tools.
 Lists all configured agents. **Call this first** to see what's available.
 
 ```json
-// Response (permission fields shown only when configured)
+// Response (capability + permission fields shown only when populated)
 [
   {
     "name": "infra",
@@ -91,12 +94,28 @@ Lists all configured agents. **Call this first** to see what's available.
     "healthy": true,
     "has_claude_md": true,
     "has_mcp_config": true,
+    "mcp_servers": ["portainer", "postgres"],
+    "stacks": ["Python", "Docker"],
+    "dbs": ["Alembic"],
     "permission_mode": "bypassPermissions",
     "allowed_tools": ["Bash", "Read", "Grep"]
   }
 ]
 ```
 
+`mcp_servers`, `stacks`, and `dbs` are detected from the agent's project files (`.mcp.json`, `Dockerfile`, `pyproject.toml`, `Cargo.toml`, `prisma/`, `alembic.ini`, etc.) so callers can pick the right agent without dispatching a probe.
+
+### `inspect_agent`
+
+Cheap detailed lookup — reads the agent's files without spawning a `claude` session. Returns the full config (timeout, model, budget, permission mode, allowed/disallowed tools), detected MCP/stacks/DBs, plus short previews of `CLAUDE.md` and `README.md` when present.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | yes | Agent name from `list_agents` |
+| `preview_lines` | int | no | Max lines of CLAUDE.md/README.md (default 40, max 200, 0 disables) |
+
+Use this **before** `dispatch_async`/`dispatch` to confirm an agent has the tools and context for your task — much cheaper than a probe dispatch.
+
 ### `dispatch`
 
 One-shot task delegation. Results are cached — identical requests within TTL return instantly.
@@ -108,6 +127,9 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 | `context` | string | no | Extra context: error messages, code snippets, stack traces |
 | `caller` | string | no | Your project/role — helps the agent understand who's asking |
 | `goal` | string | no | Broader objective — helps the agent make better trade-offs |
+| `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). |
 
 ```json
 // Response (success)
@@ -133,6 +155,18 @@ 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.
 
+**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
+// Response with response_format="json"
+{
+  "agent": "infra",
+  "success": true,
+  "result": "{\"errors\": 3, \"first_at\": \"14:02\"}",
+  "parsed_result": {"errors": 3, "first_at": "14:02"}
+}
+```
+
 **Always pass `caller` and `goal`** — the dispatched agent sees a structured prompt:
 
 ```markdown
@@ -287,6 +321,55 @@ Remove an agent from config.
 
 View cache hit rate and size, or clear all cached results.
 
+### Result references — `return_ref` + `fetch_result`
+
+For dispatches whose result text is large (audits, log dumps, code searches), passing the full text back inflates the calling agent's context. Use `return_ref=True` to get just a small reference instead:
+
+```
+dispatch(agent="infra", task="audit every container", return_ref=True, summary_chars=200)
+  -> {"ref": "8f3a...e1", "agent": "infra", "success": true,
+      "size": 14823, "summary_chars": 200,
+      "summary": "Inspected 32 containers. Found 3 OOM kills in the last hour:\n- worker-3...",
+      "cost_usd": 0.08, "duration_ms": 9200}
+
+// Later, when you actually need to read the result:
+fetch_result(ref="8f3a...e1")              -> full DispatchResult JSON
+fetch_result(ref="8f3a...e1", max_chars=2000)  -> truncated, plus {"truncated": true, "full_size": 14823}
+```
+
+Refs reuse the same storage as `dispatch_async` jobs (under `~/.config/agent-dispatch/jobs/`), so any `job_id` returned by `dispatch_async` is also a valid `ref` for `fetch_result`. `parsed_result` (when `response_format="json"` is set) is small and is always inlined directly in the ref response — no second fetch needed.
+
+### Async dispatch — `dispatch_async`, `dispatch_status`, `dispatch_wait`, `dispatch_jobs`, `dispatch_gc`
+
+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
+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)
+dispatch_status(job_id="8f3a...e1")
+  -> {"id": "8f3a...e1", "status": "running", "started_at": 1730000123.4, ...}
+
+// 3. or block until done (with a timeout cap)
+dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
+  -> {"id": "8f3a...e1", "status": "done", "result": {"agent": "infra", "success": true, ...}}
+
+// If the timeout fires, the job keeps running:
+  -> {"id": "...", "status": "running", "timed_out_waiting": true}
+```
+
+`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, atomic writes — safe to read or `ls` while jobs are in flight.
+
+| When to use async | When to use `dispatch` |
+|-------------------|------------------------|
+| Long task (minutes) — you want to keep working | Short task — you need the answer right now |
+| 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:
@@ -305,6 +388,8 @@ All tools return errors as:
 | Long task, want to see progress | `dispatch_stream` |
 | Two agents need to collaborate | `dispatch_dialogue` |
 | 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` |
 
 ## Configuration
 
@@ -389,7 +474,9 @@ agent-dispatch MCP server
 | `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, etc.) |
 | `agent-dispatch remove <name>` | Remove an agent |
 | `agent-dispatch list` | List agents with health status and permissions |
-| `agent-dispatch test <name> [task]` | Test an agent with a dispatch |
+| `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 serve` | Start MCP server (stdio, used by Claude Code) |
 
 ## Requirements

{agent_dispatch-0.2.2 → agent_dispatch-0.4.0}/README.md

@@ -32,6 +32,9 @@ 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:
+agent-dispatch doctor
 ```
 
 Done. Every Claude Code session now has access to all dispatch tools.
@@ -52,7 +55,7 @@ Done. Every Claude Code session now has access to all dispatch tools.
 Lists all configured agents. **Call this first** to see what's available.
 
 ```json
-// Response (permission fields shown only when configured)
+// Response (capability + permission fields shown only when populated)
 [
   {
     "name": "infra",
@@ -61,12 +64,28 @@ Lists all configured agents. **Call this first** to see what's available.
     "healthy": true,
     "has_claude_md": true,
     "has_mcp_config": true,
+    "mcp_servers": ["portainer", "postgres"],
+    "stacks": ["Python", "Docker"],
+    "dbs": ["Alembic"],
     "permission_mode": "bypassPermissions",
     "allowed_tools": ["Bash", "Read", "Grep"]
   }
 ]
 ```
 
+`mcp_servers`, `stacks`, and `dbs` are detected from the agent's project files (`.mcp.json`, `Dockerfile`, `pyproject.toml`, `Cargo.toml`, `prisma/`, `alembic.ini`, etc.) so callers can pick the right agent without dispatching a probe.
+
+### `inspect_agent`
+
+Cheap detailed lookup — reads the agent's files without spawning a `claude` session. Returns the full config (timeout, model, budget, permission mode, allowed/disallowed tools), detected MCP/stacks/DBs, plus short previews of `CLAUDE.md` and `README.md` when present.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | yes | Agent name from `list_agents` |
+| `preview_lines` | int | no | Max lines of CLAUDE.md/README.md (default 40, max 200, 0 disables) |
+
+Use this **before** `dispatch_async`/`dispatch` to confirm an agent has the tools and context for your task — much cheaper than a probe dispatch.
+
 ### `dispatch`
 
 One-shot task delegation. Results are cached — identical requests within TTL return instantly.
@@ -78,6 +97,9 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 | `context` | string | no | Extra context: error messages, code snippets, stack traces |
 | `caller` | string | no | Your project/role — helps the agent understand who's asking |
 | `goal` | string | no | Broader objective — helps the agent make better trade-offs |
+| `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). |
 
 ```json
 // Response (success)
@@ -103,6 +125,18 @@ 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.
 
+**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
+// Response with response_format="json"
+{
+  "agent": "infra",
+  "success": true,
+  "result": "{\"errors\": 3, \"first_at\": \"14:02\"}",
+  "parsed_result": {"errors": 3, "first_at": "14:02"}
+}
+```
+
 **Always pass `caller` and `goal`** — the dispatched agent sees a structured prompt:
 
 ```markdown
@@ -257,6 +291,55 @@ Remove an agent from config.
 
 View cache hit rate and size, or clear all cached results.
 
+### Result references — `return_ref` + `fetch_result`
+
+For dispatches whose result text is large (audits, log dumps, code searches), passing the full text back inflates the calling agent's context. Use `return_ref=True` to get just a small reference instead:
+
+```
+dispatch(agent="infra", task="audit every container", return_ref=True, summary_chars=200)
+  -> {"ref": "8f3a...e1", "agent": "infra", "success": true,
+      "size": 14823, "summary_chars": 200,
+      "summary": "Inspected 32 containers. Found 3 OOM kills in the last hour:\n- worker-3...",
+      "cost_usd": 0.08, "duration_ms": 9200}
+
+// Later, when you actually need to read the result:
+fetch_result(ref="8f3a...e1")              -> full DispatchResult JSON
+fetch_result(ref="8f3a...e1", max_chars=2000)  -> truncated, plus {"truncated": true, "full_size": 14823}
+```
+
+Refs reuse the same storage as `dispatch_async` jobs (under `~/.config/agent-dispatch/jobs/`), so any `job_id` returned by `dispatch_async` is also a valid `ref` for `fetch_result`. `parsed_result` (when `response_format="json"` is set) is small and is always inlined directly in the ref response — no second fetch needed.
+
+### Async dispatch — `dispatch_async`, `dispatch_status`, `dispatch_wait`, `dispatch_jobs`, `dispatch_gc`
+
+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
+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)
+dispatch_status(job_id="8f3a...e1")
+  -> {"id": "8f3a...e1", "status": "running", "started_at": 1730000123.4, ...}
+
+// 3. or block until done (with a timeout cap)
+dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
+  -> {"id": "8f3a...e1", "status": "done", "result": {"agent": "infra", "success": true, ...}}
+
+// If the timeout fires, the job keeps running:
+  -> {"id": "...", "status": "running", "timed_out_waiting": true}
+```
+
+`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, atomic writes — safe to read or `ls` while jobs are in flight.
+
+| When to use async | When to use `dispatch` |
+|-------------------|------------------------|
+| Long task (minutes) — you want to keep working | Short task — you need the answer right now |
+| 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:
@@ -275,6 +358,8 @@ All tools return errors as:
 | Long task, want to see progress | `dispatch_stream` |
 | Two agents need to collaborate | `dispatch_dialogue` |
 | 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` |
 
 ## Configuration
 
@@ -359,7 +444,9 @@ agent-dispatch MCP server
 | `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, etc.) |
 | `agent-dispatch remove <name>` | Remove an agent |
 | `agent-dispatch list` | List agents with health status and permissions |
-| `agent-dispatch test <name> [task]` | Test an agent with a dispatch |
+| `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 serve` | Start MCP server (stdio, used by Claude Code) |
 
 ## Requirements

{agent_dispatch-0.2.2 → agent_dispatch-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.2.2"
+version = "0.4.0"
 description = "MCP server that lets Claude Code agents delegate tasks to agents in other project directories"
 readme = "README.md"
 license = "MIT"

{agent_dispatch-0.2.2 → agent_dispatch-0.4.0}/src/agent_dispatch/__init__.py

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

{agent_dispatch-0.2.2 → agent_dispatch-0.4.0}/src/agent_dispatch/cache.py

@@ -16,8 +16,11 @@ logger = logging.getLogger(__name__)
 class DispatchCache:
     """Thread-safe TTL cache for dispatch results.
 
-    Keyed on (agent, task, context) — identical requests within the TTL
-    window return the cached result without spawning a new subprocess.
+    Keyed on (agent, task, context, caller, goal, response_format) — identical
+    requests within the TTL window return the cached result without spawning a
+    new subprocess. ``caller``/``goal``/``response_format`` all affect the
+    prompt sent to the agent, so they must be part of the key: otherwise two
+    requests with different framing would collide and return the wrong response.
     """
 
     def __init__(self, ttl: int = 300) -> None:
@@ -28,15 +31,37 @@ class DispatchCache:
         self._misses = 0
 
     @staticmethod
-    def _make_key(agent: str, task: str, context: str | None) -> str:
+    def _make_key(
+        agent: str,
+        task: str,
+        context: str | None,
+        caller: str | None = None,
+        goal: str | None = None,
+        response_format: str | None = None,
+    ) -> str:
         canonical = json.dumps(
-            {"agent": agent, "task": task, "context": context or ""},
+            {
+                "agent": agent,
+                "task": task,
+                "context": context or "",
+                "caller": caller or "",
+                "goal": goal or "",
+                "response_format": response_format or "",
+            },
             sort_keys=True,
         )
         return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
 
-    def get(self, agent: str, task: str, context: str | None = None) -> DispatchResult | None:
-        key = self._make_key(agent, task, context)
+    def get(
+        self,
+        agent: str,
+        task: str,
+        context: str | None = None,
+        caller: str | None = None,
+        goal: str | None = None,
+        response_format: str | None = None,
+    ) -> DispatchResult | None:
+        key = self._make_key(agent, task, context, caller, goal, response_format)
         with self._lock:
             entry = self._store.get(key)
             if entry is None:
@@ -56,10 +81,13 @@ class DispatchCache:
         task: str,
         result: DispatchResult,
         context: str | None = None,
+        caller: str | None = None,
+        goal: str | None = None,
+        response_format: str | None = None,
     ) -> None:
         if not result.success:
             return  # don't cache failures
-        key = self._make_key(agent, task, context)
+        key = self._make_key(agent, task, context, caller, goal, response_format)
         with self._lock:
             self._store[key] = (time.monotonic(), result)