agent-dispatch 0.10.0__tar.gz → 0.11.0__tar.gz

{agent_dispatch-0.10.0 → agent_dispatch-0.11.0}/AGENTS.md

@@ -28,7 +28,7 @@ pip install -e ".[dev]"
 
 ```bash
 ruff check src/ tests/
-python3 -m pytest tests/ -v   # 466 tests, ~2s — all subprocess calls are mocked
+python3 -m pytest tests/ -v   # 495 tests, ~2s — all subprocess calls are mocked
 ```
 
 Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.which` + `subprocess.run`/`Popen`; server tests mock `_get_config` + `runner.dispatch`.
@@ -36,14 +36,20 @@ Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.whi
 ## Non-obvious invariants (violating these breaks real behavior)
 
 - `allowed_tools` / `disallowed_tools` are **tri-state**: `None` = inherit settings defaults, `[]` = explicitly no tools, `[...]` = exactly these. Check with `is not None`, never `or` — `[]` is falsy but semantically distinct.
-- `denied_tools` non-empty + `is_error` ⇒ `error_type="permission"`, regardless of what the error text matches.
+- Error-type precedence on an `is_error` payload (`_build_error_result`): the CLI's own budget stop wins, then `denied_tools` non-empty ⇒ `error_type="permission"` regardless of the error text, then text classification.
 - **Groups**: a group's `shared_context` is folded into the `context` *string* before the cache/runner calls (`_merge_group_context` in server.py) — runner.py and cache.py are untouched, the cache key disambiguates groups for free, and `group=""` is byte-identical to a plain dispatch. Membership is validated up front (`_validate_group_member`, separate from the pure merge so `dispatch_parallel`'s all-or-nothing pre-check holds). `DispatchConfig` validates only group *keys*, never member existence — a hard cross-ref check would brick config load when a shared gateway agent is removed; dangling refs are flagged (`unknown:true`) at read time instead.
 - On failure, callers read `DispatchResult.error` + `error_type` — `result` holds the raw agent output even on errors.
 - `--session-id` and `--resume` conflict — never pass both to `claude`.
 - Valid permission modes: `default`, `plan`, `bypassPermissions` (`models.py: KNOWN_PERMISSION_MODES`).
-- `JobStore.finish`/`fail` refuse already-terminal jobs (returns `None`) — this closes the race with force-cancel; never "fix" it by overwriting.
+- `JobStore.finish`/`fail` refuse already-terminal jobs (returns `None`) — this closes the race with force-cancel; never "fix" it by overwriting. `mark_running` likewise refuses any job that isn't `pending`, so a stale or duplicate worker can't resurrect a finished one.
+- "Is this group member missing?" has exactly one implementation: `DispatchConfig.unknown_group_members()`. Any new surface that lists or validates membership calls it instead of re-deriving the check.
 - Cancelling a *running* job requires the in-memory `_running_procs` registry (server.py) — the job is marked `cancelled` **before** the subprocess is killed. Don't persist PIDs to disk (PID reuse after restart could kill an unrelated process).
-- `max_budget_usd` is **post-hoc**: `_apply_budget` (runner.py) sets `budget_exceeded` + `hint` after the cost is known; it never fails the dispatch.
+- `max_budget_usd` is enforced **by the claude CLI** (`_build_command` passes `--max-budget-usd`): a run stopped at the cap comes back `is_error` with no `result` text, and `_build_error_result` turns it into `error_type="budget"` + `budget_exceeded=True` + a resumable `session_id`. `_apply_budget` is the *secondary*, post-hoc signal for an overshoot that didn't stop the run; it never fails a dispatch.
+- A CLI error payload can have no `result` field at all — the reason lives in `errors` / `subtype`. Read it via `_cli_error_details`, never assume `result` is populated on failure.
+
+## Deliberately not built
+
+These were considered — some fully implemented — and cut on purpose: an agent router / auto-dispatch (`recommend_agent` / `dispatch_auto`, removed before 0.8.0 — a keyword scorer adds little over the calling LLM at a handful of agents, and auto-dispatch can spend money or mutate a repo on a guess); groups as an execution engine (they are a descriptive layer — no routing, no per-group settings); an agent-dispatch-side budget ledger across dispatches (the CLI's own `--max-budget-usd` covers a single run; anything cumulative would need state we deliberately don't keep). Please open an issue with the use case before adding any of them.
 
 ## Conventions
 
@@ -55,4 +61,4 @@ Python ≥ 3.10 · `from __future__ import annotations` everywhere · Pydantic v
 
 ## More detail
 
-[README.md](README.md) documents every MCP tool with parameter tables, response shapes, and the error-recovery map — it doubles as the behavioral spec. The test suite (`tests/`, 466 tests) encodes the exact expected behavior of every layer: when in doubt, read the tests for the module you're touching (`test_runner.py`, `test_server.py`, `test_cli.py`, ...).
+[README.md](README.md) documents every MCP tool with parameter tables, response shapes, and the error-recovery map — it doubles as the behavioral spec. The test suite (`tests/`, 495 tests) encodes the exact expected behavior of every layer: when in doubt, read the tests for the module you're touching (`test_runner.py`, `test_server.py`, `test_cli.py`, ...).

{agent_dispatch-0.10.0 → agent_dispatch-0.11.0}/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-07-27
+
+The spend cap was already real — now the result says so.
+
+### Added
+- **`error_type: "budget"`.** The `claude` CLI enforces the `--max-budget-usd`
+  value agent-dispatch has always passed: when the cap is reached it ends the
+  session and reports the failure with no `result` text. That payload used to
+  surface as the useless `"reported an error with no details"` fallback with
+  `error_type: "cli_error"`. It is now classified as `budget`, carries the
+  CLI's own reason (`Reached maximum budget ($X)`), sets
+  `budget_exceeded: true`, and spells out the recovery — raise the cap, pick a
+  cheaper model, or resume the partial session via the returned `session_id`.
+  `agent-dispatch test` prints a matching diagnosis.
+
+### Fixed
+- **Error details are no longer dropped.** CLI-level failures (budget
+  exhausted, max turns, execution errors) put their reason in `errors` /
+  `subtype` rather than `result`. Both `dispatch` and `dispatch_stream` now
+  read those fields when `result` is empty, so the error text names the actual
+  problem. Values are capped (5 entries × 300 chars) like every other field
+  read back from the subprocess.
+- **Job files can no longer be corrupted by a concurrent writer.** `JobStore`
+  wrote through a fixed `<id>.tmp` path; the in-process lock does not cover
+  the CLI (`cancel` / `gc`) and the MCP server writing the same job at the
+  same time, and the rename could publish interleaved JSON. Each write now
+  uses a unique temp name and cleans it up if the write fails.
+
+### Changed
+- The `is_error` handling in `dispatch` and `dispatch_stream` is now one
+  shared `_build_error_result()` with an explicit precedence: budget stop >
+  denied tools > text classification.
+- Documentation corrected throughout: `max_budget_usd` is enforced per
+  dispatch by the CLI, with the `budget_exceeded` flag as the secondary
+  post-hoc signal for a run that overshot without being stopped. Previous
+  releases described it as post-hoc only.
+
 ## [0.10.0] - 2026-07-14
 
 `doctor` learns to check groups; three correctness fixes found in review.
@@ -389,7 +426,11 @@ cache bounding, and stale-job recovery.
 - Dependabot for `pip` + `github-actions`, GitHub Actions pinned to
   commit SHAs for supply-chain integrity.
 
-[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.11.0...HEAD
+[0.11.0]: https://github.com/ginkida/agent-dispatch/compare/v0.10.0...v0.11.0
+[0.10.0]: https://github.com/ginkida/agent-dispatch/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/ginkida/agent-dispatch/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/ginkida/agent-dispatch/compare/v0.6.0...v0.8.0
 [0.6.0]: https://github.com/ginkida/agent-dispatch/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/ginkida/agent-dispatch/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/ginkida/agent-dispatch/compare/v0.3.0...v0.4.0

{agent_dispatch-0.10.0 → agent_dispatch-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.10.0
+Version: 0.11.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
@@ -233,7 +233,7 @@ dispatch(
 }
 ```
 
-**`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.
+**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `budget` (the `claude` CLI stopped the session at `max_budget_usd`), `cli_error` (other failures). Permission and budget errors include an actionable hint.
 
 **Resumable timeouts:** every fresh dispatch pre-assigns a session UUID (`--session-id`), so a timed-out dispatch still returns a `session_id` — the partial transcript survives the kill. The timeout error spells out the recovery: resume with `dispatch_session(agent, "Continue where you left off", session_id=...)`, retry with a bigger `timeout_seconds`, or use `dispatch_async`.
 
@@ -503,13 +503,14 @@ Failures are deterministic: check `success`, then branch on `error_type`.
 | `timeout` | Process killed at the timeout | Resume the partial work: `dispatch_session(agent, "Continue where you left off", session_id=<from the error text>)`. Or retry with a bigger `timeout_seconds=`, or use `dispatch_async`. |
 | `not_found` | Agent directory or `claude` CLI missing | `list_agents()` → check `healthy`. Re-add the agent with an existing path, or run `agent-dispatch doctor` to find what's missing. |
 | `recursion` | Dispatch nesting exceeded `max_dispatch_depth` (default 3) | Don't dispatch from dispatched agents; if the nesting is intentional, raise `max_dispatch_depth` in settings. |
+| `budget` | The `claude` CLI ended the session at the `max_budget_usd` spend cap — the answer is incomplete | Raise the cap (`update_agent(name, max_budget_usd=2.0)`), switch to a cheaper `model`, or split the task. The partial session is resumable: `dispatch_session(agent, "Continue where you left off", session_id=<from the result>)`. |
 | `cli_error` | Anything else from the `claude` subprocess | Read the `error` text; run `agent-dispatch doctor` for environment issues; retry once if transient. |
 
 Three soft signals that arrive with `success: true`:
 
 - **`denied_tools` + `hint`** — the agent finished but some tool calls were blocked; the result may be incomplete. Grant access (see the `permission` row) and re-dispatch.
 - **`parsed_result: null` with `response_format="json"`** — the reply wasn't valid JSON; the raw text is still in `result`. Caveat: an agent that *can't* comply returns `{"error": "<reason>"}` — which parses successfully — so also check `parsed_result` for an `"error"` key.
-- **`budget_exceeded: true`** — `cost_usd` exceeded the agent's `max_budget_usd` (or the settings default). The dispatch is not failed — the money is already spent — but a runaway agent is now visible. Tighten the task, pick a cheaper model, or raise the budget.
+- **`budget_exceeded: true`** — `cost_usd` came in over the agent's `max_budget_usd` (or the settings default) without the CLI stopping the run (the final turn can overshoot the cap). The dispatch is not failed — the money is already spent — but a runaway agent is now visible. Tighten the task, pick a cheaper model, or raise the budget. A run the CLI *did* stop fails with `error_type: "budget"` instead.
 
 Tool-level errors (unknown agent, malformed input) return a plain envelope instead of a `DispatchResult`:
 
@@ -624,7 +625,7 @@ agent-dispatch MCP server
 - **Argument-injection guard** — structured CLI fields (`session_id`, `model`, `permission_mode`, tool names) that start with `-` are rejected so they can't smuggle extra `claude` flags.
 - **Path-traversal guard** — caller-supplied `job_id`/`ref` values are validated as 32-char hex before any filesystem access.
 - **Owner-only state** — job files (`0o600`) and `agents.yaml` (`0o600`) are written for the owner only; their directories are `0o700`.
-- **Cost visibility** — `max_budget_usd` per agent or globally; a dispatch whose cost exceeds it returns `budget_exceeded: true` + a hint (post-hoc — the `claude` CLI has no spend cap, so the overage can be flagged but not prevented).
+- **Cost control** — `max_budget_usd` per agent or globally is passed to the `claude` CLI as `--max-budget-usd`, so a runaway dispatch is stopped at the cap and comes back as `error_type: "budget"` with a resumable `session_id`. An overshoot that lands over budget without stopping is flagged post-hoc with `budget_exceeded: true` + a hint.
 - **Concurrency** — `max_concurrency` (default: 5) caps parallel `claude -p` processes. Note: the sync and async dispatch paths use separate semaphores, so the worst-case total is `2 × max_concurrency`.
 - **Timeout** — per-agent or global (default: 300s). Orphaned processes are cleaned up.
 - **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only successes are cached. Sessions and dialogues are never cached. A `group=` dispatch folds the group's `shared_context` into `context`, so different groups cache separately and a plain dispatch is unaffected.

{agent_dispatch-0.10.0 → agent_dispatch-0.11.0}/README.md

@@ -203,7 +203,7 @@ dispatch(
 }
 ```
 
-**`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.
+**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `budget` (the `claude` CLI stopped the session at `max_budget_usd`), `cli_error` (other failures). Permission and budget errors include an actionable hint.
 
 **Resumable timeouts:** every fresh dispatch pre-assigns a session UUID (`--session-id`), so a timed-out dispatch still returns a `session_id` — the partial transcript survives the kill. The timeout error spells out the recovery: resume with `dispatch_session(agent, "Continue where you left off", session_id=...)`, retry with a bigger `timeout_seconds`, or use `dispatch_async`.
 
@@ -473,13 +473,14 @@ Failures are deterministic: check `success`, then branch on `error_type`.
 | `timeout` | Process killed at the timeout | Resume the partial work: `dispatch_session(agent, "Continue where you left off", session_id=<from the error text>)`. Or retry with a bigger `timeout_seconds=`, or use `dispatch_async`. |
 | `not_found` | Agent directory or `claude` CLI missing | `list_agents()` → check `healthy`. Re-add the agent with an existing path, or run `agent-dispatch doctor` to find what's missing. |
 | `recursion` | Dispatch nesting exceeded `max_dispatch_depth` (default 3) | Don't dispatch from dispatched agents; if the nesting is intentional, raise `max_dispatch_depth` in settings. |
+| `budget` | The `claude` CLI ended the session at the `max_budget_usd` spend cap — the answer is incomplete | Raise the cap (`update_agent(name, max_budget_usd=2.0)`), switch to a cheaper `model`, or split the task. The partial session is resumable: `dispatch_session(agent, "Continue where you left off", session_id=<from the result>)`. |
 | `cli_error` | Anything else from the `claude` subprocess | Read the `error` text; run `agent-dispatch doctor` for environment issues; retry once if transient. |
 
 Three soft signals that arrive with `success: true`:
 
 - **`denied_tools` + `hint`** — the agent finished but some tool calls were blocked; the result may be incomplete. Grant access (see the `permission` row) and re-dispatch.
 - **`parsed_result: null` with `response_format="json"`** — the reply wasn't valid JSON; the raw text is still in `result`. Caveat: an agent that *can't* comply returns `{"error": "<reason>"}` — which parses successfully — so also check `parsed_result` for an `"error"` key.
-- **`budget_exceeded: true`** — `cost_usd` exceeded the agent's `max_budget_usd` (or the settings default). The dispatch is not failed — the money is already spent — but a runaway agent is now visible. Tighten the task, pick a cheaper model, or raise the budget.
+- **`budget_exceeded: true`** — `cost_usd` came in over the agent's `max_budget_usd` (or the settings default) without the CLI stopping the run (the final turn can overshoot the cap). The dispatch is not failed — the money is already spent — but a runaway agent is now visible. Tighten the task, pick a cheaper model, or raise the budget. A run the CLI *did* stop fails with `error_type: "budget"` instead.
 
 Tool-level errors (unknown agent, malformed input) return a plain envelope instead of a `DispatchResult`:
 
@@ -594,7 +595,7 @@ agent-dispatch MCP server
 - **Argument-injection guard** — structured CLI fields (`session_id`, `model`, `permission_mode`, tool names) that start with `-` are rejected so they can't smuggle extra `claude` flags.
 - **Path-traversal guard** — caller-supplied `job_id`/`ref` values are validated as 32-char hex before any filesystem access.
 - **Owner-only state** — job files (`0o600`) and `agents.yaml` (`0o600`) are written for the owner only; their directories are `0o700`.
-- **Cost visibility** — `max_budget_usd` per agent or globally; a dispatch whose cost exceeds it returns `budget_exceeded: true` + a hint (post-hoc — the `claude` CLI has no spend cap, so the overage can be flagged but not prevented).
+- **Cost control** — `max_budget_usd` per agent or globally is passed to the `claude` CLI as `--max-budget-usd`, so a runaway dispatch is stopped at the cap and comes back as `error_type: "budget"` with a resumable `session_id`. An overshoot that lands over budget without stopping is flagged post-hoc with `budget_exceeded: true` + a hint.
 - **Concurrency** — `max_concurrency` (default: 5) caps parallel `claude -p` processes. Note: the sync and async dispatch paths use separate semaphores, so the worst-case total is `2 × max_concurrency`.
 - **Timeout** — per-agent or global (default: 300s). Orphaned processes are cleaned up.
 - **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only successes are cached. Sessions and dialogues are never cached. A `group=` dispatch folds the group's `shared_context` into `context`, so different groups cache separately and a plain dispatch is unaffected.

{agent_dispatch-0.10.0 → agent_dispatch-0.11.0}/agents.example.yaml

@@ -93,7 +93,8 @@ settings:
   default_timeout: 300
   max_dispatch_depth: 3           # recursion protection: A -> B -> A
   max_concurrency: 5              # max parallel claude -p processes
-  # default_max_budget_usd: 1.0   # flags results over this cost (budget_exceeded + hint; post-hoc, can't prevent the spend)
+  # default_max_budget_usd: 1.0   # spend cap per dispatch, passed to claude as --max-budget-usd
+                                  # (a run stopped at the cap fails with error_type: budget)
   # default_permission_mode: bypassPermissions  # inherited by agents without override
   # default_allowed_tools:         # inherited by agents without override
   #   - Bash

{agent_dispatch-0.10.0 → agent_dispatch-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.10.0"
+version = "0.11.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.10.0 → agent_dispatch-0.11.0}/src/agent_dispatch/__init__.py

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

{agent_dispatch-0.10.0 → agent_dispatch-0.11.0}/src/agent_dispatch/cli.py

@@ -423,6 +423,12 @@ def test(name: str, task: str, stream: bool, timeout: int | None) -> None:
             click.echo(click.style("Diagnosis: timeout", fg="yellow"))
             click.echo(f"  agent-dispatch test {name} --timeout 600    # one-off")
             click.echo(f"  agent-dispatch update {name} --timeout 600  # permanent")
+        elif result.error_type == "budget":
+            click.echo()
+            click.echo(click.style("Diagnosis: spend cap reached", fg="yellow"))
+            click.echo("The claude CLI stopped the session at --max-budget-usd.")
+            click.echo(f"  agent-dispatch update {name} --max-budget-usd 2.0  # raise the cap")
+            click.echo(f"  agent-dispatch update {name} --model haiku         # cheaper model")
         raise SystemExit(1)
 
 

{agent_dispatch-0.10.0 → agent_dispatch-0.11.0}/src/agent_dispatch/jobs.py

@@ -99,10 +99,22 @@ class JobStore:
 
     def _write(self, job: Job) -> None:
         path = self._path(job.id)
-        tmp = path.with_suffix(".tmp")
-        tmp.write_text(job.model_dump_json(indent=2, exclude_none=True), encoding="utf-8")
-        _chmod_quiet(tmp, 0o600)  # owner-only before it becomes visible
-        os.replace(tmp, path)
+        # Unique temp name per write: `self._lock` only serializes writers inside
+        # one process, but the CLI (cancel/gc) and the MCP server touch the same
+        # files. A shared `<id>.tmp` could be written by both at once and the
+        # rename would publish interleaved, unparseable JSON.
+        tmp = path.with_name(f"{job.id}.{uuid.uuid4().hex}.tmp")
+        try:
+            tmp.write_text(job.model_dump_json(indent=2, exclude_none=True), encoding="utf-8")
+            _chmod_quiet(tmp, 0o600)  # owner-only before it becomes visible
+            os.replace(tmp, path)
+        except OSError:
+            # Don't leave a half-written temp file behind on a failed write.
+            try:
+                tmp.unlink(missing_ok=True)
+            except OSError:  # pragma: no cover - best effort
+                logger.debug("Failed to clean up temp file %s", tmp)
+            raise
 
     def create(
         self,

{agent_dispatch-0.10.0 → agent_dispatch-0.11.0}/src/agent_dispatch/models.py

@@ -174,7 +174,7 @@ class DispatchResult(BaseModel):
     duration_ms: int | None = None
     num_turns: int | None = None
     error: str | None = None
-    error_type: str | None = None  # permission, timeout, recursion, not_found, cli_error
+    error_type: str | None = None  # permission, timeout, recursion, not_found, budget, cli_error
     # Set when response_format="json" was requested AND the agent's result
     # parsed cleanly. None means: not requested, or requested but unparseable.
     parsed_result: Any | None = None

{agent_dispatch-0.10.0 → agent_dispatch-0.11.0}/src/agent_dispatch/runner.py

@@ -138,16 +138,146 @@ def _denial_hint(agent_name: str, denied_tools: list[str]) -> str:
     )
 
 
+def _effective_budget(agent: AgentConfig, settings: Settings) -> float | None:
+    """The spend cap for this dispatch: per-agent, else the settings default."""
+    return agent.max_budget_usd or settings.default_max_budget_usd
+
+
+# The claude CLI enforces `--max-budget-usd` itself: when the cap is reached it
+# ends the session and emits a result payload with `is_error: true`, NO `result`
+# field, `subtype: "error_max_budget_usd"`, `terminal_reason: "budget_exhausted"`
+# and the human-readable reason in `errors`. Verified against claude 2.1.220.
+_BUDGET_ERROR_SUBTYPE = "error_max_budget_usd"
+_BUDGET_TERMINAL_REASON = "budget_exhausted"
+
+# `errors` also comes from the untrusted subprocess — cap it like denied_tools.
+_MAX_ERROR_DETAILS = 5
+_MAX_ERROR_DETAIL_CHARS = 300
+
+
+def _is_budget_error(data: dict) -> bool:
+    """True when the CLI ended the session because the spend cap was reached."""
+    return (
+        data.get("subtype") == _BUDGET_ERROR_SUBTYPE
+        or data.get("terminal_reason") == _BUDGET_TERMINAL_REASON
+    )
+
+
+def _cli_error_details(data: dict) -> str:
+    """Best available failure text for an error payload that has no `result`.
+
+    CLI-level failures (budget exhausted, max turns, execution errors) carry no
+    `result` text — the reason lives in `errors` and `subtype`. Without this the
+    caller only ever saw "reported an error with no details".
+    """
+    errors = data.get("errors")
+    if isinstance(errors, list):
+        details = [
+            text[:_MAX_ERROR_DETAIL_CHARS]
+            for text in (str(item).strip() for item in errors[:_MAX_ERROR_DETAILS])
+            if text
+        ]
+        if details:
+            return "; ".join(details)
+    subtype = data.get("subtype")
+    if isinstance(subtype, str) and subtype.strip():
+        return f"claude CLI reported '{subtype.strip()[:_MAX_ERROR_DETAIL_CHARS]}'"
+    return ""
+
+
+def _budget_error_hint(agent_name: str, budget: float | None, session_uuid: str | None) -> str:
+    """Actionable hint for a dispatch the CLI stopped at the spend cap."""
+    cap = f"${budget:g}" if budget else "the configured cap"
+    msg = (
+        f"\n\nHint: the dispatch was stopped by the spend cap {cap} "
+        "(passed to claude as --max-budget-usd), so this answer is incomplete. "
+        f"Raise it (agent-dispatch update {agent_name} --max-budget-usd <amount>), "
+        "use a cheaper model, or split the task into smaller dispatches."
+    )
+    if session_uuid:
+        msg += (
+            f" Partial work may be resumable: dispatch_session(agent='{agent_name}', "
+            f"task='Continue where you left off', session_id='{session_uuid}')."
+        )
+    return msg
+
+
+def _build_error_result(
+    agent_name: str,
+    data: dict,
+    denied: list[str] | None,
+    agent: AgentConfig,
+    settings: Settings,
+    *,
+    session_fallback: str | None,
+    exit_code: int | None = None,
+) -> DispatchResult:
+    """Build the DispatchResult for a CLI payload with ``is_error: true``.
+
+    Shared by ``dispatch`` and ``dispatch_stream`` — the two paths differ only
+    in which session id they fall back to and whether an exit code is known.
+    Error-type precedence: budget (the CLI's own terminal reason) > denied tools
+    (a deterministic signal) > text classification.
+    """
+    raw_result = data.get("result", "")
+    result_text = str(raw_result) if raw_result else ""
+    detail = _cli_error_details(data)
+    if result_text:
+        error_text = result_text
+    elif detail:
+        error_text = f"Agent '{agent_name}' failed: {detail}"
+    else:
+        suffix = f" (exit code {exit_code})" if exit_code is not None else ""
+        error_text = f"Agent '{agent_name}' reported an error with no details{suffix}"
+
+    session_id = data.get("session_id") or session_fallback
+    budget_error = _is_budget_error(data)
+    if budget_error:
+        error_type = "budget"
+        error_text += _budget_error_hint(agent_name, _effective_budget(agent, settings), session_id)
+    elif denied:
+        # Denied tools are a stronger signal than substring matching.
+        error_type = "permission"
+        error_text += _permission_hint(agent_name)
+    else:
+        error_type = _classify_error(error_text)
+        if error_type == "permission":
+            error_text += _permission_hint(agent_name)
+
+    return _apply_budget(
+        DispatchResult(
+            agent=agent_name,
+            success=False,
+            result=result_text,
+            session_id=session_id,
+            cost_usd=data.get("total_cost_usd"),
+            duration_ms=data.get("duration_ms"),
+            num_turns=data.get("num_turns"),
+            error=error_text,
+            error_type=error_type,
+            denied_tools=denied,
+            # The cap was hit by definition — flag it even if the reported cost
+            # lands a hair under the budget after rounding.
+            budget_exceeded=True if budget_error else None,
+        ),
+        agent,
+        settings,
+    )
+
+
 def _apply_budget(result: DispatchResult, agent: AgentConfig, settings: Settings) -> DispatchResult:
     """Flag a result whose cost exceeded the configured budget (post-hoc).
 
-    ``claude -p`` has no spend-cap flag, so the budget cannot be enforced up
-    front — by the time the cost is known the money is already spent. The
-    result is therefore NOT failed; it gets ``budget_exceeded=True`` plus a
-    hint so callers notice runaway agents instead of the field being silently
-    ignored. Applied to error results too (a failed dispatch still costs).
+    The CLI's own ``--max-budget-usd`` stops a session once the cap is reached
+    (that path returns ``error_type="budget"``), but the last turn can still
+    overshoot, and the cap only covers a single dispatch. This adds the
+    post-hoc signal: ``budget_exceeded=True`` plus a hint, without failing the
+    result — the money is already spent. Applied to error results too.
     """
-    budget = agent.max_budget_usd or settings.default_max_budget_usd
+    budget = _effective_budget(agent, settings)
+    if result.error_type == "budget":
+        # Already flagged with a far more actionable message — don't double up.
+        return result
     if not budget or not result.cost_usd or result.cost_usd <= budget:
         return result
     result.budget_exceeded = True
@@ -510,36 +640,14 @@ def dispatch(
 
     is_error = data.get("is_error", False)
     if is_error:
-        raw_result = data.get("result", "")
-        error_text = (
-            str(raw_result)
-            if raw_result
-            else (
-                f"Agent '{agent_name}' reported an error with no details "
-                f"(exit code {proc.returncode})"
-            )
-        )
-        error_type = _classify_error(error_text)
-        if denied and error_type != "permission":
-            # Denied tools are a stronger signal than substring matching.
-            error_type = "permission"
-        if error_type == "permission":
-            error_text += _permission_hint(agent_name)
-        return _apply_budget(
-            DispatchResult(
-                agent=agent_name,
-                success=False,
-                result=str(raw_result) if raw_result else "",
-                session_id=data.get("session_id") or session_uuid,
-                cost_usd=data.get("total_cost_usd"),
-                duration_ms=data.get("duration_ms"),
-                num_turns=data.get("num_turns"),
-                error=error_text,
-                error_type=error_type,
-                denied_tools=denied,
-            ),
+        return _build_error_result(
+            agent_name,
+            data,
+            denied,
             agent,
             settings,
+            session_fallback=session_uuid,
+            exit_code=proc.returncode,
         )
 
     result_text = data.get("result", "")
@@ -749,32 +857,13 @@ def dispatch_stream(
         denied = _extract_denied_tools(result_data)
         is_error = result_data.get("is_error", False)
         if is_error:
-            raw_result = result_data.get("result", "")
-            error_text = (
-                str(raw_result)
-                if raw_result
-                else (f"Agent '{agent_name}' reported an error with no details")
-            )
-            error_type = _classify_error(error_text)
-            if denied and error_type != "permission":
-                error_type = "permission"
-            if error_type == "permission":
-                error_text += _permission_hint(agent_name)
-            return _apply_budget(
-                DispatchResult(
-                    agent=agent_name,
-                    success=False,
-                    result=str(raw_result) if raw_result else "",
-                    session_id=result_data.get("session_id") or new_session,
-                    cost_usd=result_data.get("total_cost_usd"),
-                    duration_ms=result_data.get("duration_ms"),
-                    num_turns=result_data.get("num_turns"),
-                    error=error_text,
-                    error_type=error_type,
-                    denied_tools=denied,
-                ),
+            return _build_error_result(
+                agent_name,
+                result_data,
+                denied,
                 agent,
                 settings,
+                session_fallback=new_session,
             )
         result_text = result_data.get("result", "")
         parsed = _parse_structured_response(result_text) if response_format == "json" else None

{agent_dispatch-0.10.0 → agent_dispatch-0.11.0}/tests/test_cli.py

@@ -969,6 +969,24 @@ class TestTestCommand:
         assert "Diagnosis: timeout" in result.output
         assert "--timeout 600" in result.output
 
+    def test_budget_error_shows_diagnosis(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.runner.dispatch") as mock_dispatch:
+            mock_dispatch.return_value = DispatchResult(
+                agent="proj",
+                success=False,
+                result="",
+                error="Agent 'proj' failed: Reached maximum budget ($0.10)",
+                error_type="budget",
+                budget_exceeded=True,
+            )
+            result = runner.invoke(cli, ["test", "proj"])
+        assert result.exit_code != 0
+        assert "Diagnosis: spend cap reached" in result.output
+        assert "--max-budget-usd" 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"