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

agent_dispatch-0.3.0/CHANGELOG.md

@@ -0,0 +1,98 @@
+# 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.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.3.0...HEAD
+[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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.2.2
+Version: 0.3.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.
@@ -389,7 +392,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.3.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.
@@ -359,7 +362,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.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.2.2"
+version = "0.3.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.3.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.3.0"

{agent_dispatch-0.2.2 → agent_dispatch-0.3.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) — identical requests within
+    the TTL window return the cached result without spawning a new subprocess.
+    `caller` and `goal` 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,34 @@ 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,
+    ) -> str:
         canonical = json.dumps(
-            {"agent": agent, "task": task, "context": context or ""},
+            {
+                "agent": agent,
+                "task": task,
+                "context": context or "",
+                "caller": caller or "",
+                "goal": goal 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,
+    ) -> DispatchResult | None:
+        key = self._make_key(agent, task, context, caller, goal)
         with self._lock:
             entry = self._store.get(key)
             if entry is None:
@@ -56,10 +78,12 @@ class DispatchCache:
         task: str,
         result: DispatchResult,
         context: str | None = None,
+        caller: str | None = None,
+        goal: 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)
         with self._lock:
             self._store[key] = (time.monotonic(), result)
 

{agent_dispatch-0.2.2 → agent_dispatch-0.3.0}/src/agent_dispatch/cli.py

@@ -1,8 +1,9 @@
-"""CLI: init, add, remove, list, test, serve."""
+"""CLI: init, add, remove, list, update, test, describe, doctor, serve."""
 
 from __future__ import annotations
 
 import json
+import re
 import shutil
 import subprocess
 from pathlib import Path
@@ -295,7 +296,11 @@ def update(
 @cli.command()
 @click.argument("name")
 @click.argument("task", default="What project is this? Describe in one sentence.")
-def test(name: str, task: str) -> None:
+@click.option(
+    "--stream", "stream", is_flag=True,
+    help="Show live progress (assistant text + tool use) while the agent works.",
+)
+def test(name: str, task: str, stream: bool) -> None:
     """Test an agent by dispatching a task."""
     config = _load_or_exit()
     if name not in config.agents:
@@ -307,9 +312,18 @@ def test(name: str, task: str) -> None:
     click.echo(f"Task: {task}")
     click.echo("---")
 
-    from .runner import dispatch
+    if stream:
+        from .runner import dispatch_stream
+
+        def _on_progress(msg: str) -> None:
+            click.echo(click.style(f"  -> {msg}", fg="cyan"), err=True)
 
-    result = dispatch(name, task, agent, config.settings)
+        result = dispatch_stream(
+            name, task, agent, config.settings, on_progress=_on_progress,
+        )
+    else:
+        from .runner import dispatch
+        result = dispatch(name, task, agent, config.settings)
 
     if result.success:
         click.echo(result.result)
@@ -330,6 +344,177 @@ def test(name: str, task: str) -> None:
         raise SystemExit(1)
 
 
+@cli.command()
+@click.argument("name")
+def describe(name: str) -> None:
+    """Show full configuration for a single agent."""
+    config = _load_or_exit()
+    if name not in config.agents:
+        click.echo(f"Agent '{name}' not found. Run 'agent-dispatch list' to see agents.")
+        raise SystemExit(1)
+
+    agent = config.agents[name]
+    try:
+        if agent.directory.is_dir():
+            status_label, status_color = "OK", "green"
+        else:
+            status_label, status_color = "NOT FOUND", "red"
+    except OSError:
+        status_label, status_color = "UNREADABLE", "red"
+    status = click.style(status_label, fg=status_color)
+
+    def _render_tools(tools: list[str] | None) -> str:
+        if tools is None:
+            return click.style("(inherit defaults)", fg="cyan")
+        if not tools:
+            return click.style("(none — explicit override)", fg="yellow")
+        return ", ".join(tools)
+
+    click.echo(f"{click.style(name, bold=True)} [{status}]")
+    click.echo(f"  directory:        {agent.directory}")
+    click.echo(f"  description:      {agent.description}")
+    click.echo(f"  timeout:          {agent.timeout}s")
+    if agent.model:
+        click.echo(f"  model:            {agent.model}")
+    if agent.max_budget_usd is not None:
+        click.echo(f"  max_budget_usd:   ${agent.max_budget_usd}")
+    if agent.permission_mode:
+        click.echo(f"  permission_mode:  {agent.permission_mode}")
+    click.echo(f"  allowed_tools:    {_render_tools(agent.allowed_tools)}")
+    click.echo(f"  disallowed_tools: {_render_tools(agent.disallowed_tools)}")
+
+    # Surface project files used by auto_describe so the user can verify
+    # what context the dispatched agent will actually inherit.
+    try:
+        files: list[str] = []
+        for fname in ("CLAUDE.md", ".mcp.json", "README.md", "pyproject.toml", "package.json"):
+            if (agent.directory / fname).exists():
+                files.append(fname)
+        if files:
+            click.echo(f"  project files:    {', '.join(files)}")
+    except OSError:
+        pass
+
+
+@cli.command()
+def doctor() -> None:
+    """Diagnose the agent-dispatch setup and surface common issues."""
+    counters = {"issues": 0, "warnings": 0}
+
+    def section(title: str) -> None:
+        click.echo(f"\n{click.style(title, bold=True)}")
+
+    def ok(msg: str) -> None:
+        click.echo(f"  [{click.style('OK', fg='green')}] {msg}")
+
+    def warn(msg: str) -> None:
+        counters["warnings"] += 1
+        click.echo(f"  [{click.style('WARN', fg='yellow')}] {msg}")
+
+    def fail(msg: str) -> None:
+        counters["issues"] += 1
+        click.echo(f"  [{click.style('FAIL', fg='red')}] {msg}")
+
+    section("Environment")
+    claude_path = shutil.which("claude")
+    if claude_path:
+        ok(f"claude CLI: {claude_path}")
+    else:
+        fail("claude CLI not found on PATH")
+        click.echo("    Install: https://docs.anthropic.com/en/docs/claude-code")
+
+    ad_path = shutil.which("agent-dispatch")
+    if ad_path:
+        ok(f"agent-dispatch CLI: {ad_path}")
+    else:
+        warn(
+            "agent-dispatch not on PATH "
+            "(MCP server still works via absolute path)"
+        )
+
+    section("Config")
+    cp = config_path()
+    config: DispatchConfig | None = None
+    if not cp.exists():
+        warn(f"Config not found: {cp}")
+        click.echo("    Run: agent-dispatch init")
+    else:
+        try:
+            config = load_config()
+            n = len(config.agents)
+            suffix = "agent" if n == 1 else "agents"
+            ok(f"Config: {cp} ({n} {suffix})")
+        except ValidationError as e:
+            fail(f"Config schema invalid: {cp}")
+            click.echo(f"    {e}")
+        except yaml.YAMLError as e:
+            fail(f"Config not valid YAML: {cp}")
+            click.echo(f"    {e}")
+
+    section("MCP registration")
+    if claude_path is None:
+        warn("Skipped (claude CLI missing)")
+    else:
+        try:
+            result = subprocess.run(
+                [claude_path, "mcp", "list"],
+                capture_output=True, text=True, timeout=10,
+            )
+            # Match the server name at the start of any line — `claude mcp list`
+            # prints `<name>: <command> - <status>`, and we want to avoid false
+            # positives from "agent-dispatch" appearing in command paths.
+            entry_re = re.compile(r"^agent-dispatch[:\s]", re.MULTILINE)
+            if result.returncode == 0 and entry_re.search(result.stdout):
+                ok("agent-dispatch is registered with Claude Code")
+            else:
+                warn("agent-dispatch is not registered with Claude Code")
+                click.echo("    Run: agent-dispatch init")
+        except subprocess.TimeoutExpired:
+            warn("Could not check MCP registration: claude mcp list timed out")
+        except (FileNotFoundError, PermissionError, OSError) as e:
+            warn(f"Could not check MCP registration: {e}")
+
+    section("Agents")
+    if config is None:
+        warn("Skipped (config could not be loaded)")
+    elif not config.agents:
+        warn("No agents configured. Add one: agent-dispatch add <name> <directory>")
+    else:
+        for name, agent in config.agents.items():
+            try:
+                if agent.directory.is_dir():
+                    extras: list[str] = []
+                    if (agent.directory / "CLAUDE.md").exists():
+                        extras.append("CLAUDE.md")
+                    if (agent.directory / ".mcp.json").exists():
+                        extras.append(".mcp.json")
+                    suffix = f" [{', '.join(extras)}]" if extras else ""
+                    ok(f"{name}: {agent.directory}{suffix}")
+                else:
+                    fail(f"{name}: directory missing - {agent.directory}")
+            except OSError as e:
+                fail(f"{name}: directory unreadable - {e}")
+
+    section("Summary")
+    issues = counters["issues"]
+    warnings = counters["warnings"]
+    if issues == 0 and warnings == 0:
+        click.echo(click.style("All checks passed.", fg="green"))
+    else:
+        parts: list[str] = []
+        if issues:
+            parts.append(click.style(
+                f"{issues} issue{'s' if issues != 1 else ''}", fg="red",
+            ))
+        if warnings:
+            parts.append(click.style(
+                f"{warnings} warning{'s' if warnings != 1 else ''}", fg="yellow",
+            ))
+        click.echo(", ".join(parts))
+        if issues > 0:
+            raise SystemExit(1)
+
+
 @cli.command()
 def serve() -> None:
     """Start the MCP server (stdio transport)."""

{agent_dispatch-0.2.2 → agent_dispatch-0.3.0}/src/agent_dispatch/server.py

@@ -102,14 +102,28 @@ async def list_agents(ctx: Context | None = None) -> str:
 
     agents = []
     for name, agent in config.agents.items():
-        healthy = agent.directory.is_dir()
+        # is_dir() can raise OSError (PermissionError, network FS hiccup, etc.).
+        # Fall back to "UNREADABLE" so a single broken agent doesn't crash the
+        # whole listing — per CLAUDE.md's documented response shape.
+        try:
+            healthy: bool | str = agent.directory.is_dir()
+            has_claude_md = (
+                (agent.directory / "CLAUDE.md").exists() if healthy else False
+            )
+            has_mcp_config = (
+                (agent.directory / ".mcp.json").exists() if healthy else False
+            )
+        except OSError:
+            healthy = "UNREADABLE"
+            has_claude_md = False
+            has_mcp_config = False
         entry: dict = {
             "name": name,
             "directory": str(agent.directory),
             "description": agent.description,
             "healthy": healthy,
-            "has_claude_md": (agent.directory / "CLAUDE.md").exists() if healthy else False,
-            "has_mcp_config": (agent.directory / ".mcp.json").exists() if healthy else False,
+            "has_claude_md": has_claude_md,
+            "has_mcp_config": has_mcp_config,
         }
         if agent.permission_mode:
             entry["permission_mode"] = agent.permission_mode
@@ -151,10 +165,11 @@ async def dispatch(
     if err := _validate_agent(config, agent):
         return err
 
-    # Check cache
+    # Check cache. caller/goal are part of the key because they change the
+    # prompt sent to Claude and therefore the response.
     cache = _get_cache(config)
     if cache:
-        cached = cache.get(agent, task, context or None)
+        cached = cache.get(agent, task, context or None, caller or None, goal or None)
         if cached:
             if ctx:
                 await ctx.info(f"Cache hit for {agent} — returning cached result")
@@ -180,7 +195,7 @@ async def dispatch(
 
     # Populate cache
     if cache:
-        cache.put(agent, task, result, context or None)
+        cache.put(agent, task, result, context or None, caller or None, goal or None)
 
     return result.model_dump_json(indent=2, exclude_none=True)
 
@@ -291,9 +306,9 @@ async def dispatch_parallel(
         item_caller = item.get("caller") or None
         item_goal = item.get("goal") or None
 
-        # Check cache
+        # Check cache (caller/goal are part of the key — see dispatch())
         if cache:
-            cached = cache.get(name, task, item_context)
+            cached = cache.get(name, task, item_context, item_caller, item_goal)
             if cached:
                 d = json.loads(cached.model_dump_json(exclude_none=True))
                 d["cached"] = True
@@ -313,7 +328,7 @@ async def dispatch_parallel(
             )
 
         if cache:
-            cache.put(name, task, result, item_context)
+            cache.put(name, task, result, item_context, item_caller, item_goal)
 
         return json.loads(result.model_dump_json(exclude_none=True))
 

{agent_dispatch-0.2.2 → agent_dispatch-0.3.0}/tests/test_cache.py

@@ -53,6 +53,48 @@ class TestCacheBasics:
         cache.put("a", "task", _fail_result())
         assert cache.get("a", "task") is None
 
+    def test_caller_affects_key(self):
+        """Different caller → different prompt → must not collide in cache."""
+        cache = DispatchCache(ttl=60)
+        cache.put("a", "task", _ok_result(text="for-frontend"), caller="frontend")
+        cache.put("a", "task", _ok_result(text="for-backend"), caller="backend")
+        assert cache.get("a", "task", caller="frontend").result == "for-frontend"
+        assert cache.get("a", "task", caller="backend").result == "for-backend"
+        # Different caller from what was stored → miss
+        assert cache.get("a", "task", caller="other") is None
+
+    def test_goal_affects_key(self):
+        """Different goal → different prompt → must not collide in cache."""
+        cache = DispatchCache(ttl=60)
+        cache.put("a", "task", _ok_result(text="for-debug"), goal="debug crash")
+        cache.put("a", "task", _ok_result(text="for-perf"), goal="optimize perf")
+        assert cache.get("a", "task", goal="debug crash").result == "for-debug"
+        assert cache.get("a", "task", goal="optimize perf").result == "for-perf"
+
+    def test_caller_and_goal_combined(self):
+        cache = DispatchCache(ttl=60)
+        cache.put(
+            "a", "task", _ok_result(text="A"),
+            caller="frontend", goal="debug",
+        )
+        # Same caller, different goal → miss
+        assert cache.get("a", "task", caller="frontend", goal="optimize") is None
+        # Same goal, different caller → miss
+        assert cache.get("a", "task", caller="backend", goal="debug") is None
+        # Both match → hit
+        assert cache.get(
+            "a", "task", caller="frontend", goal="debug",
+        ).result == "A"
+
+    def test_caller_none_vs_empty_string_collide(self):
+        """caller=None and caller="" canonicalize the same — both mean
+        'no caller specified'. Document the behavior so future changes
+        don't silently break the contract."""
+        cache = DispatchCache(ttl=60)
+        cache.put("a", "task", _ok_result(text="anon"), caller=None)
+        assert cache.get("a", "task", caller="") is not None
+        assert cache.get("a", "task", caller=None) is not None
+
 
 class TestCacheTTL:
     def test_expired_entry_returns_none(self):

{agent_dispatch-0.2.2 → agent_dispatch-0.3.0}/tests/test_cli.py

@@ -364,6 +364,297 @@ class TestInit:
         assert "Failed to register" in result.output
 
 
+class TestDescribe:
+    """Tests for `agent-dispatch describe <name>` command."""
+
+    def test_describe_basic(self, tmp_path: Path):
+        agent_dir = tmp_path / "proj"
+        agent_dir.mkdir()
+        runner.invoke(cli, [
+            "add", "proj", str(agent_dir),
+            "-d", "My agent",
+            "--timeout", "600",
+            "--model", "sonnet",
+            "--max-budget", "1.5",
+            "--permission-mode", "bypassPermissions",
+            "--allowed-tools", "Bash,Read",
+        ])
+        result = runner.invoke(cli, ["describe", "proj"])
+        assert result.exit_code == 0
+        assert "proj" in result.output
+        assert "OK" in result.output
+        assert "My agent" in result.output
+        assert "600s" in result.output
+        assert "sonnet" in result.output
+        assert "$1.5" in result.output
+        assert "bypassPermissions" in result.output
+        assert "Bash, Read" in result.output
+
+    def test_describe_nonexistent(self):
+        result = runner.invoke(cli, ["describe", "nonexistent"])
+        assert result.exit_code != 0
+        assert "not found" in result.output
+
+    def test_describe_inherit_vs_explicit_empty(self, _isolated_config: Path, tmp_path: Path):
+        """Tools field should distinguish None (inherit) from [] (override)."""
+        agent_dir = tmp_path / "proj"
+        agent_dir.mkdir()
+        # Explicit empty list (override defaults)
+        _isolated_config.parent.mkdir(parents=True, exist_ok=True)
+        import yaml as _yaml
+        _yaml.safe_dump({
+            "agents": {
+                "proj": {
+                    "directory": str(agent_dir),
+                    "description": "Test",
+                    "allowed_tools": [],         # explicit override
+                    # disallowed_tools omitted → None → inherit
+                },
+            },
+        }, _isolated_config.open("w"))
+        result = runner.invoke(cli, ["describe", "proj"])
+        assert result.exit_code == 0
+        # allowed_tools=[] → "(none — explicit override)"
+        assert "explicit override" in result.output
+        # disallowed_tools=None → "(inherit defaults)"
+        assert "inherit defaults" in result.output
+
+    def test_describe_missing_directory_shows_not_found(self, _isolated_config: Path):
+        _isolated_config.parent.mkdir(parents=True, exist_ok=True)
+        _isolated_config.write_text(
+            "agents:\n"
+            "  proj:\n"
+            "    directory: /nonexistent/xyz\n"
+            "    description: Test\n"
+        )
+        result = runner.invoke(cli, ["describe", "proj"])
+        assert result.exit_code == 0
+        assert "NOT FOUND" in result.output
+
+    def test_describe_lists_project_files(self, tmp_path: Path):
+        agent_dir = tmp_path / "proj"
+        agent_dir.mkdir()
+        (agent_dir / "CLAUDE.md").write_text("# Proj")
+        (agent_dir / "README.md").write_text("# Proj README")
+        (agent_dir / ".mcp.json").write_text("{}")
+        runner.invoke(cli, ["add", "proj", str(agent_dir), "-d", "Test"])
+        result = runner.invoke(cli, ["describe", "proj"])
+        assert "CLAUDE.md" in result.output
+        assert "README.md" in result.output
+        assert ".mcp.json" in result.output
+
+
+class TestDoctor:
+    """Tests for `agent-dispatch doctor` diagnostic command."""
+
+    def _patch_claude_mcp_list(
+        self, *, registered: bool = True, fail: bool = False, stdout: str | None = None,
+    ):
+        """Helper: patch subprocess.run for `claude mcp list` calls.
+
+        Mirrors the real CLI output format:
+            agent-dispatch: /path/to/agent-dispatch serve - Connected
+        """
+        if fail:
+            return patch(
+                "agent_dispatch.cli.subprocess.run",
+                side_effect=FileNotFoundError("no claude"),
+            )
+        if stdout is None:
+            if registered:
+                stdout = (
+                    "agent-dispatch: /opt/homebrew/bin/agent-dispatch serve - Connected\n"
+                    "foo: /usr/bin/foo serve - Connected\n"
+                )
+            else:
+                stdout = "foo: /usr/bin/foo serve - Connected\n"
+        return patch(
+            "agent_dispatch.cli.subprocess.run",
+            return_value=subprocess.CompletedProcess(
+                args=[], returncode=0, stdout=stdout, stderr="",
+            ),
+        )
+
+    def test_all_ok(self, tmp_path: Path):
+        agent_dir = tmp_path / "proj"
+        agent_dir.mkdir()
+        runner.invoke(cli, ["add", "proj", str(agent_dir), "-d", "Test"])
+        with (
+            patch("agent_dispatch.cli.shutil.which", side_effect=lambda x: f"/usr/bin/{x}"),
+            self._patch_claude_mcp_list(registered=True),
+        ):
+            result = runner.invoke(cli, ["doctor"])
+        assert result.exit_code == 0, result.output
+        assert "claude CLI" in result.output
+        assert "All checks passed" in result.output
+        assert "FAIL" not in result.output
+
+    def test_claude_cli_missing(self, tmp_path: Path):
+        with patch("agent_dispatch.cli.shutil.which", return_value=None):
+            result = runner.invoke(cli, ["doctor"])
+        assert result.exit_code != 0
+        assert "claude CLI not found" in result.output
+        assert "FAIL" in result.output
+
+    def test_agent_dispatch_not_on_path_warns(self, tmp_path: Path):
+        def which(name: str):
+            return None if name == "agent-dispatch" else f"/usr/bin/{name}"
+
+        with (
+            patch("agent_dispatch.cli.shutil.which", side_effect=which),
+            self._patch_claude_mcp_list(registered=True),
+        ):
+            result = runner.invoke(cli, ["doctor"])
+        assert "agent-dispatch not on PATH" in result.output
+        assert "WARN" in result.output
+
+    def test_config_missing_warns(self, _isolated_config: Path):
+        """No config file → WARN, exit 0."""
+        assert not _isolated_config.exists()
+        with (
+            patch("agent_dispatch.cli.shutil.which", side_effect=lambda x: f"/usr/bin/{x}"),
+            self._patch_claude_mcp_list(registered=True),
+        ):
+            result = runner.invoke(cli, ["doctor"])
+        assert result.exit_code == 0  # warnings don't fail
+        assert "Config not found" in result.output
+        assert "agent-dispatch init" in result.output
+
+    def test_config_invalid_yaml_fails(self, _isolated_config: Path):
+        _isolated_config.parent.mkdir(parents=True, exist_ok=True)
+        _isolated_config.write_text("agents: [not a dict\n")
+        with (
+            patch("agent_dispatch.cli.shutil.which", side_effect=lambda x: f"/usr/bin/{x}"),
+            self._patch_claude_mcp_list(registered=True),
+        ):
+            result = runner.invoke(cli, ["doctor"])
+        assert result.exit_code != 0
+        assert "not valid YAML" in result.output
+
+    def test_config_invalid_schema_fails(self, _isolated_config: Path):
+        _isolated_config.parent.mkdir(parents=True, exist_ok=True)
+        _isolated_config.write_text("agents: 42\nsettings: {}\n")
+        with (
+            patch("agent_dispatch.cli.shutil.which", side_effect=lambda x: f"/usr/bin/{x}"),
+            self._patch_claude_mcp_list(registered=True),
+        ):
+            result = runner.invoke(cli, ["doctor"])
+        assert result.exit_code != 0
+        assert "schema invalid" in result.output
+
+    def test_mcp_not_registered_warns(self, tmp_path: Path):
+        agent_dir = tmp_path / "proj"
+        agent_dir.mkdir()
+        runner.invoke(cli, ["add", "proj", str(agent_dir), "-d", "Test"])
+        with (
+            patch("agent_dispatch.cli.shutil.which", side_effect=lambda x: f"/usr/bin/{x}"),
+            self._patch_claude_mcp_list(registered=False),
+        ):
+            result = runner.invoke(cli, ["doctor"])
+        assert result.exit_code == 0
+        assert "not registered with Claude Code" in result.output
+        assert "WARN" in result.output
+
+    def test_mcp_check_avoids_false_positive_in_path(self, tmp_path: Path):
+        """A line mentioning 'agent-dispatch' only in a path/command — but no
+        MCP server entry by that name — should NOT be treated as registered."""
+        agent_dir = tmp_path / "proj"
+        agent_dir.mkdir()
+        runner.invoke(cli, ["add", "proj", str(agent_dir), "-d", "Test"])
+        # Notice: 'agent-dispatch' appears only as a path component of another server
+        misleading = "other-server: /opt/bin/agent-dispatch-helper - Connected\n"
+        with (
+            patch("agent_dispatch.cli.shutil.which", side_effect=lambda x: f"/usr/bin/{x}"),
+            self._patch_claude_mcp_list(stdout=misleading),
+        ):
+            result = runner.invoke(cli, ["doctor"])
+        assert "not registered with Claude Code" in result.output
+
+    def test_mcp_check_handles_timeout(self, tmp_path: Path):
+        agent_dir = tmp_path / "proj"
+        agent_dir.mkdir()
+        runner.invoke(cli, ["add", "proj", str(agent_dir), "-d", "Test"])
+        with (
+            patch("agent_dispatch.cli.shutil.which", side_effect=lambda x: f"/usr/bin/{x}"),
+            patch(
+                "agent_dispatch.cli.subprocess.run",
+                side_effect=subprocess.TimeoutExpired(cmd="claude", timeout=10),
+            ),
+        ):
+            result = runner.invoke(cli, ["doctor"])
+        assert result.exit_code == 0
+        assert "timed out" in result.output
+
+    def test_missing_agent_directory_fails(self, _isolated_config: Path):
+        """Agent's directory was deleted after `add` → FAIL exit."""
+        # Write config pointing at a directory that doesn't exist
+        _isolated_config.parent.mkdir(parents=True, exist_ok=True)
+        _isolated_config.write_text(
+            "agents:\n"
+            "  proj:\n"
+            "    directory: /nonexistent/path/xyz\n"
+            "    description: Test\n"
+        )
+        with (
+            patch("agent_dispatch.cli.shutil.which", side_effect=lambda x: f"/usr/bin/{x}"),
+            self._patch_claude_mcp_list(registered=True),
+        ):
+            result = runner.invoke(cli, ["doctor"])
+        assert result.exit_code != 0
+        assert "directory missing" in result.output
+
+    def test_unreadable_directory_fails(self, tmp_path: Path):
+        agent_dir = tmp_path / "proj"
+        agent_dir.mkdir()
+        runner.invoke(cli, ["add", "proj", str(agent_dir), "-d", "Test"])
+        with (
+            patch("agent_dispatch.cli.shutil.which", side_effect=lambda x: f"/usr/bin/{x}"),
+            self._patch_claude_mcp_list(registered=True),
+            patch(
+                "agent_dispatch.cli.Path.is_dir",
+                side_effect=PermissionError("denied"),
+            ),
+        ):
+            result = runner.invoke(cli, ["doctor"])
+        assert result.exit_code != 0
+        assert "unreadable" in result.output
+
+    def test_no_agents_warns(self, _isolated_config: Path):
+        """Config exists but has no agents → WARN, exit 0."""
+        _isolated_config.parent.mkdir(parents=True, exist_ok=True)
+        _isolated_config.write_text("agents: {}\nsettings: {}\n")
+        with (
+            patch("agent_dispatch.cli.shutil.which", side_effect=lambda x: f"/usr/bin/{x}"),
+            self._patch_claude_mcp_list(registered=True),
+        ):
+            result = runner.invoke(cli, ["doctor"])
+        assert result.exit_code == 0
+        assert "No agents configured" in result.output
+
+    def test_lists_claude_md_and_mcp_json(self, tmp_path: Path):
+        agent_dir = tmp_path / "proj"
+        agent_dir.mkdir()
+        (agent_dir / "CLAUDE.md").write_text("# Proj")
+        (agent_dir / ".mcp.json").write_text("{}")
+        runner.invoke(cli, ["add", "proj", str(agent_dir), "-d", "Test"])
+        with (
+            patch("agent_dispatch.cli.shutil.which", side_effect=lambda x: f"/usr/bin/{x}"),
+            self._patch_claude_mcp_list(registered=True),
+        ):
+            result = runner.invoke(cli, ["doctor"])
+        assert result.exit_code == 0
+        assert "CLAUDE.md" in result.output
+        assert ".mcp.json" in result.output
+
+    def test_summary_singular_plural(self, tmp_path: Path):
+        """One issue should say 'issue' not 'issues'."""
+        with patch("agent_dispatch.cli.shutil.which", return_value=None):
+            result = runner.invoke(cli, ["doctor"])
+        # Exactly one FAIL (claude CLI missing)
+        assert "1 issue" in result.output
+        assert "1 issues" not in result.output
+
+
 class TestTestCommand:
     def test_success(self, tmp_path: Path):
         agent_dir = tmp_path / "proj"
@@ -413,3 +704,47 @@ class TestTestCommand:
         assert result.exit_code != 0
         assert "Diagnosis: timeout" in result.output
         assert "--timeout 600" in result.output
+
+    def test_stream_uses_dispatch_stream(self, tmp_path: Path):
+        """--stream should call dispatch_stream, not dispatch, and forward progress."""
+        agent_dir = tmp_path / "proj"
+        agent_dir.mkdir()
+        runner.invoke(cli, ["add", "proj", str(agent_dir), "-d", "Test"])
+
+        def _fake_stream(name, task, agent, settings, on_progress=None, **_kw):
+            assert on_progress is not None
+            on_progress("Reading file foo.py")
+            on_progress("Using tool: Edit")
+            return DispatchResult(
+                agent=name, success=True, result="done",
+                cost_usd=0.01, num_turns=1,
+            )
+
+        with (
+            patch("agent_dispatch.runner.dispatch_stream", side_effect=_fake_stream),
+            patch("agent_dispatch.runner.dispatch") as plain_dispatch,
+        ):
+            result = runner.invoke(cli, ["test", "proj", "--stream"])
+        assert result.exit_code == 0
+        assert "done" in result.output
+        # Progress goes to stderr, captured into result.output by CliRunner
+        assert "Reading file foo.py" in result.output
+        assert "Using tool: Edit" in result.output
+        # Non-stream path must NOT be invoked
+        plain_dispatch.assert_not_called()
+
+    def test_no_stream_uses_dispatch(self, tmp_path: Path):
+        """Default (no --stream) should call dispatch, not dispatch_stream."""
+        agent_dir = tmp_path / "proj"
+        agent_dir.mkdir()
+        runner.invoke(cli, ["add", "proj", str(agent_dir), "-d", "Test"])
+        with (
+            patch("agent_dispatch.runner.dispatch") as mock_dispatch,
+            patch("agent_dispatch.runner.dispatch_stream") as mock_stream,
+        ):
+            mock_dispatch.return_value = DispatchResult(
+                agent="proj", success=True, result="ok",
+            )
+            runner.invoke(cli, ["test", "proj"])
+        mock_dispatch.assert_called_once()
+        mock_stream.assert_not_called()

{agent_dispatch-0.2.2 → agent_dispatch-0.3.0}/tests/test_server.py

@@ -199,6 +199,51 @@ class TestDispatchCaching:
             result = json.loads(raw)
             assert result.get("cached") is True
 
+    @pytest.mark.asyncio
+    async def test_cache_differentiates_callers(self, tmp_path: Path):
+        """Same (agent, task) but different caller should dispatch fresh —
+        caller/goal change the prompt, so the cached result is not equivalent."""
+        config = _make_config(tmp_path)
+        call_count = 0
+
+        def fake_dispatch(name, task, agent_config, settings, context=None, **kw):
+            nonlocal call_count
+            call_count += 1
+            return _ok_dispatch_result(name)
+
+        with (
+            patch.object(server, "_get_config", return_value=config),
+            patch("agent_dispatch.server.runner.dispatch", side_effect=fake_dispatch),
+        ):
+            await server.dispatch("infra", "check pods", caller="frontend")
+            assert call_count == 1
+            # Same task, different caller → must miss the cache and dispatch again
+            await server.dispatch("infra", "check pods", caller="backend")
+            assert call_count == 2
+            # Same caller again → hit
+            raw = await server.dispatch("infra", "check pods", caller="frontend")
+            assert call_count == 2
+            assert json.loads(raw).get("cached") is True
+
+    @pytest.mark.asyncio
+    async def test_cache_differentiates_goals(self, tmp_path: Path):
+        """Different goal → different prompt → cache miss."""
+        config = _make_config(tmp_path)
+        call_count = 0
+
+        def fake_dispatch(name, task, agent_config, settings, context=None, **kw):
+            nonlocal call_count
+            call_count += 1
+            return _ok_dispatch_result(name)
+
+        with (
+            patch.object(server, "_get_config", return_value=config),
+            patch("agent_dispatch.server.runner.dispatch", side_effect=fake_dispatch),
+        ):
+            await server.dispatch("infra", "check pods", goal="debug crash")
+            await server.dispatch("infra", "check pods", goal="optimize perf")
+            assert call_count == 2
+
     @pytest.mark.asyncio
     async def test_cache_disabled(self, tmp_path: Path):
         config = _make_config(tmp_path, cache_enabled=False)
@@ -628,6 +673,66 @@ class TestListAgentsPermissions:
         assert agents[0]["disallowed_tools"] == []
 
 
+class TestListAgentsHealth:
+    """Health-check edge cases — directory missing, unreadable, etc."""
+
+    @pytest.mark.asyncio
+    async def test_list_handles_unreadable_directory(self, tmp_path: Path):
+        """One agent with PermissionError on is_dir() should NOT crash the
+        whole listing — that agent gets healthy='UNREADABLE', others OK."""
+        good = tmp_path / "good"
+        good.mkdir()
+        bad = tmp_path / "bad"
+        bad.mkdir()
+        config = DispatchConfig(
+            agents={
+                "good": AgentConfig(directory=good, description="ok"),
+                "bad": AgentConfig(directory=bad, description="unreadable"),
+            }
+        )
+        mock_ctx = AsyncMock()
+
+        original_is_dir = Path.is_dir
+
+        def selective_is_dir(self):
+            if self == bad:
+                raise PermissionError("denied")
+            return original_is_dir(self)
+
+        with (
+            patch.object(server, "_get_config", return_value=config),
+            patch.object(Path, "is_dir", selective_is_dir),
+        ):
+            raw = await server.list_agents(ctx=mock_ctx)
+        agents = json.loads(raw)
+        # Both agents present — one bad agent does not poison the list
+        assert len(agents) == 2
+        by_name = {a["name"]: a for a in agents}
+        assert by_name["good"]["healthy"] is True
+        assert by_name["bad"]["healthy"] == "UNREADABLE"
+        assert by_name["bad"]["has_claude_md"] is False
+        assert by_name["bad"]["has_mcp_config"] is False
+
+    @pytest.mark.asyncio
+    async def test_list_handles_nonexistent_directory(self, tmp_path: Path):
+        """Directory that doesn't exist → healthy=False, child checks=False."""
+        # Note: AgentConfig auto-resolves but doesn't require existence
+        config = DispatchConfig(
+            agents={
+                "ghost": AgentConfig(
+                    directory=tmp_path / "does-not-exist",
+                    description="missing",
+                ),
+            }
+        )
+        mock_ctx = AsyncMock()
+        with patch.object(server, "_get_config", return_value=config):
+            raw = await server.list_agents(ctx=mock_ctx)
+        agents = json.loads(raw)
+        assert agents[0]["healthy"] is False
+        assert agents[0]["has_claude_md"] is False
+
+
 class TestAddRemoveAgent:
     @pytest.mark.asyncio
     async def test_add_agent(self, tmp_path: Path):