agent-dispatch 0.2.1__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.1 → agent_dispatch-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.2.1
+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.1 → 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.1 → agent_dispatch-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.2.1"
+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.1 → 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.1"
+__version__ = "0.3.0"

{agent_dispatch-0.2.1 → 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.1 → 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
@@ -202,10 +203,12 @@ def list_agents() -> None:
             click.echo(f"    config: {', '.join(extras)}")
         if agent.permission_mode:
             click.echo(f"    permission_mode: {agent.permission_mode}")
-        if agent.allowed_tools:
-            click.echo(f"    allowed_tools: {', '.join(agent.allowed_tools)}")
-        if agent.disallowed_tools:
-            click.echo(f"    disallowed_tools: {', '.join(agent.disallowed_tools)}")
+        if agent.allowed_tools is not None:
+            rendered = ", ".join(agent.allowed_tools) if agent.allowed_tools else "(none)"
+            click.echo(f"    allowed_tools: {rendered}")
+        if agent.disallowed_tools is not None:
+            rendered = ", ".join(agent.disallowed_tools) if agent.disallowed_tools else "(none)"
+            click.echo(f"    disallowed_tools: {rendered}")
         click.echo()
 
 
@@ -293,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:
@@ -305,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)
@@ -328,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.1 → agent_dispatch-0.3.0}/src/agent_dispatch/server.py

@@ -102,20 +102,35 @@ 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
-        if agent.allowed_tools:
+        # Include when explicitly set (even []) to distinguish from inheriting defaults
+        if agent.allowed_tools is not None:
             entry["allowed_tools"] = agent.allowed_tools
-        if agent.disallowed_tools:
+        if agent.disallowed_tools is not None:
             entry["disallowed_tools"] = agent.disallowed_tools
         agents.append(entry)
     if ctx:
@@ -150,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")
@@ -179,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)
 
@@ -290,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
@@ -312,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.1 → 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):