agent-dispatch 0.5.0__tar.gz → 0.6.0__tar.gz

{agent_dispatch-0.5.0 → agent_dispatch-0.6.0}/CHANGELOG.md

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-06-04
+
+Reliability release: timeouts stop being fatal, permission-blocked "successes"
+become visible, async jobs show live progress.
+
+### Fixed
+- **`dispatch_stream` was broken on current claude CLIs** — they reject
+  `--print --output-format stream-json` without `--verbose` ("requires
+  --verbose"), so every stream dispatch (and CLI `test --stream`) failed
+  immediately. The runner now passes `--verbose`. Caught by live verification
+  against the real CLI before this release; without it the async-worker
+  switch to streaming (below) would have broken all `dispatch_async` jobs.
+
+### Added
+- **Per-call timeout override.** `dispatch`, `dispatch_session`,
+  `dispatch_stream`, and `dispatch_async` accept `timeout_seconds` (0 = agent
+  default, clamped to 10–7200); `dispatch_parallel` accepts it per item. Use
+  it for known-long tasks instead of editing the agent config. CLI:
+  `agent-dispatch test <name> --timeout N`.
+- **Resumable timeouts.** Fresh dispatches pre-assign a session UUID via
+  `--session-id`, so a timed-out dispatch still returns a `session_id` — the
+  partial transcript survives the kill. The timeout error now spells out the
+  recovery options: resume via `dispatch_session(..., session_id=...)`, retry
+  with `timeout_seconds`, or go async.
+- **Denied-tools visibility.** The claude CLI's `permission_denials` output is
+  parsed into `DispatchResult.denied_tools`. A dispatch that "succeeds" while
+  tools were blocked (the agent answers "I need permission for X") now carries
+  `denied_tools` + a `hint` that the result may be incomplete and how to grant
+  access. On `is_error` results, non-empty denials force
+  `error_type="permission"` even when the error text has no permission
+  keywords. CLI `test` prints the hint as a yellow note.
+- **Async job progress.** Async workers now run with streaming: the job file
+  keeps a rolling tail (last 20 lines, throttled to ~1 write/sec) of assistant
+  text and tool-use events. `dispatch_status` returns it as `progress` while
+  running (kept afterwards as a post-mortem trace); `dispatch_jobs` shows
+  `last_progress` for running jobs. New `JobStore.update_progress` (refuses
+  terminal jobs, so a trailing write can't resurrect a finished job).
+
+### Changed
+- Timeout error messages are actionable (mention `timeout_seconds`,
+  `dispatch_async`, `agent-dispatch update --timeout`, and the resumable
+  session) instead of just "increase timeout in agents.yaml".
+- Plain-text fallback successes now carry the generated `session_id`; the
+  stream "no result line" fallback does too (a crash mid-stream stays
+  resumable).
+- **Old-CLI self-healing**: if the installed claude CLI predates
+  `--session-id`, dispatch detects the "unknown option" rejection and retries
+  once without the flag (logged warning; timed-out dispatches lose
+  resumability) instead of failing every dispatch.
+- `dispatch_parallel` validates per-item `timeout_seconds` / `summary_chars`
+  numerically **up front** — a bad value rejects the whole call before any
+  dispatch runs, consistent with the structural validation contract.
+- `denied_tools` parsing is bounded (10 entries, 100 chars per name) — the
+  field comes from the dispatched subprocess's output, which is untrusted;
+  unbounded lists could inflate job files and `return_ref` payloads.
+
 ## [0.5.0] - 2026-06-01
 
 Security-hardening release. A multi-agent audit of the codebase surfaced
@@ -214,7 +270,8 @@ 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.5.0...HEAD
+[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.6.0...HEAD
+[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
 [0.3.0]: https://github.com/ginkida/agent-dispatch/compare/v0.2.2...v0.3.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.5.0
+Version: 0.6.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
@@ -130,6 +130,7 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 | `response_format` | string | no | `"json"` to request a single JSON value; the parsed result lands in `parsed_result`. Empty = free-form text. |
 | `return_ref` | bool | no | When `true`, returns just a `ref` + summary preview instead of the full result text. Use `fetch_result(ref)` to load the full text on demand. |
 | `summary_chars` | int | no | Max chars of result text to include in the ref response (default 500). |
+| `timeout_seconds` | int | no | One-off timeout override for this call (0 = agent's configured timeout; clamped to 10–7200). No config edit needed for known-long tasks. |
 
 ```json
 // Response (success)
@@ -155,6 +156,21 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 
 **`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `cli_error` (other failures). Permission errors include an actionable hint.
 
+**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`.
+
+**Denied-tools visibility:** in non-interactive mode the claude CLI auto-denies tools the agent isn't allowed to use — the agent then often "succeeds" with an answer like *"I need your permission for one read-only query"*. When that happens the response carries the deterministic signal: `denied_tools` (parsed from the CLI's `permission_denials`) plus a `hint` explaining the result may be incomplete and how to grant access. `success` stays `true` — it's a soft signal, not a failure.
+
+```json
+// Response (success, but a tool was blocked)
+{
+  "agent": "analysis",
+  "success": true,
+  "result": "Here is the offline mapping. To finish I'd need to run one read-only query...",
+  "denied_tools": ["Bash"],
+  "hint": "1 tool call(s) were denied by permissions: Bash. The result may be incomplete..."
+}
+```
+
 **Structured JSON output:** pass `response_format="json"` to ask the agent for a single JSON value. The runner appends an instruction footer ("respond with a single valid JSON value, no fences, no prose") and on success parses the response — the parsed value lands in `parsed_result`. The raw text is always in `result`. Parse failures leave `parsed_result=None` but don't fail the dispatch (soft mode).
 
 ```json
@@ -195,6 +211,9 @@ Multi-turn: continue a conversation with an agent. First call starts a session,
 | `context` | string | no | Extra context |
 | `caller` | string | no | Who is dispatching |
 | `goal` | string | no | Broader objective |
+| `timeout_seconds` | int | no | One-off timeout override (0 = agent default; clamped to 10–7200) |
+
+`dispatch_session` is also the **timeout recovery path**: a timed-out `dispatch` returns a `session_id` — pass it here with `task="Continue where you left off"` to salvage the partial work instead of restarting.
 
 ```
 Turn 1: dispatch_session("infra", "List running containers")
@@ -210,7 +229,7 @@ Run multiple tasks concurrently. Much faster than sequential `dispatch` calls.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `dispatches` | string (JSON) | yes | JSON array of `{"agent", "task", "context?", "caller?", "goal?"}` |
+| `dispatches` | string (JSON) | yes | JSON array of `{"agent", "task", "context?", "caller?", "goal?", "response_format?", "return_ref?", "summary_chars?", "timeout_seconds?"}` |
 | `aggregate` | string | no | Agent name to synthesize all results into one answer |
 
 **Important:** `dispatches` is a JSON string, not a list.
@@ -250,7 +269,7 @@ Run multiple tasks concurrently. Much faster than sequential `dispatch` calls.
 
 Same as `dispatch` but shows live progress while the agent works. Use for long-running tasks. Not cached.
 
-Parameters are identical to `dispatch`.
+Parameters are the same as `dispatch` except `return_ref`/`summary_chars` (streaming is incompatible with ref-mode).
 
 ### `dispatch_dialogue`
 
@@ -344,13 +363,15 @@ Refs reuse the same storage as `dispatch_async` jobs (under `~/.config/agent-dis
 When a dispatched task is going to take a while, you don't want to block your own tool slot for minutes. Async dispatch returns a `job_id` immediately and lets you check back when you're ready.
 
 ```
-// 1. fire and forget
+// 1. fire and forget (timeout_seconds= works here too for known-long tasks)
 dispatch_async(agent="infra", task="audit every container log for OOM kills today")
   -> {"job_id": "8f3a...e1", "status": "pending", "agent": "infra"}
 
 // 2. do other work, then check progress (non-blocking)
+//    `progress` is a rolling tail of what the agent is doing right now
 dispatch_status(job_id="8f3a...e1")
-  -> {"id": "8f3a...e1", "status": "running", "started_at": 1730000123.4, ...}
+  -> {"id": "8f3a...e1", "status": "running", "started_at": 1730000123.4,
+      "progress": ["Using tool: Bash", "Scanning container logs for OOM events..."], ...}
 
 // 3. or block until done (with a timeout cap)
 dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
@@ -362,6 +383,8 @@ dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
 
 `dispatch_cancel(job_id)` cancels a job that is still **pending** (before its subprocess starts) — a running job is left to finish, since its `claude` subprocess can't be safely interrupted. The response carries an `outcome` of `cancelled`, `running`, `already_terminal`, or `not_found`.
 
+Async workers run with streaming under the hood: the job file keeps a rolling tail (last 20 lines, ~1 write/sec) of assistant text and tool-use events. `dispatch_status` shows it as `progress` while the job runs and keeps it afterwards as a post-mortem trace; `dispatch_jobs` shows `last_progress` for running jobs.
+
 `dispatch_jobs(status?)` lists recent jobs as summaries (filter by `pending` / `running` / `done` / `failed` / `cancelled`). `dispatch_gc(max_age_days=7)` purges terminal jobs older than the threshold — pending and running jobs are never deleted.
 
 Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `AGENT_DISPATCH_JOBS_DIR`). One JSON file per job, written owner-only (`0o600`) with atomic writes — safe to read or `ls` while jobs are in flight. Caller-supplied `job_id`s are validated as 32-char hex before any file access (no path traversal). On startup the server marks jobs abandoned in `running` by a prior crashed instance as `failed`.
@@ -392,6 +415,8 @@ All tools return errors as:
 | Need a combined summary from multiple agents | `dispatch_parallel` with `aggregate` |
 | Long task — don't block your tool slot | `dispatch_async` + `dispatch_wait` |
 | Check progress without blocking | `dispatch_status` |
+| Known-long task, one-off | any dispatch tool with `timeout_seconds=...` |
+| A dispatch timed out | `dispatch_session` with the `session_id` from the error |
 
 ## Configuration
 

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

@@ -100,6 +100,7 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 | `response_format` | string | no | `"json"` to request a single JSON value; the parsed result lands in `parsed_result`. Empty = free-form text. |
 | `return_ref` | bool | no | When `true`, returns just a `ref` + summary preview instead of the full result text. Use `fetch_result(ref)` to load the full text on demand. |
 | `summary_chars` | int | no | Max chars of result text to include in the ref response (default 500). |
+| `timeout_seconds` | int | no | One-off timeout override for this call (0 = agent's configured timeout; clamped to 10–7200). No config edit needed for known-long tasks. |
 
 ```json
 // Response (success)
@@ -125,6 +126,21 @@ One-shot task delegation. Results are cached — identical requests within TTL r
 
 **`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `cli_error` (other failures). Permission errors include an actionable hint.
 
+**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`.
+
+**Denied-tools visibility:** in non-interactive mode the claude CLI auto-denies tools the agent isn't allowed to use — the agent then often "succeeds" with an answer like *"I need your permission for one read-only query"*. When that happens the response carries the deterministic signal: `denied_tools` (parsed from the CLI's `permission_denials`) plus a `hint` explaining the result may be incomplete and how to grant access. `success` stays `true` — it's a soft signal, not a failure.
+
+```json
+// Response (success, but a tool was blocked)
+{
+  "agent": "analysis",
+  "success": true,
+  "result": "Here is the offline mapping. To finish I'd need to run one read-only query...",
+  "denied_tools": ["Bash"],
+  "hint": "1 tool call(s) were denied by permissions: Bash. The result may be incomplete..."
+}
+```
+
 **Structured JSON output:** pass `response_format="json"` to ask the agent for a single JSON value. The runner appends an instruction footer ("respond with a single valid JSON value, no fences, no prose") and on success parses the response — the parsed value lands in `parsed_result`. The raw text is always in `result`. Parse failures leave `parsed_result=None` but don't fail the dispatch (soft mode).
 
 ```json
@@ -165,6 +181,9 @@ Multi-turn: continue a conversation with an agent. First call starts a session,
 | `context` | string | no | Extra context |
 | `caller` | string | no | Who is dispatching |
 | `goal` | string | no | Broader objective |
+| `timeout_seconds` | int | no | One-off timeout override (0 = agent default; clamped to 10–7200) |
+
+`dispatch_session` is also the **timeout recovery path**: a timed-out `dispatch` returns a `session_id` — pass it here with `task="Continue where you left off"` to salvage the partial work instead of restarting.
 
 ```
 Turn 1: dispatch_session("infra", "List running containers")
@@ -180,7 +199,7 @@ Run multiple tasks concurrently. Much faster than sequential `dispatch` calls.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `dispatches` | string (JSON) | yes | JSON array of `{"agent", "task", "context?", "caller?", "goal?"}` |
+| `dispatches` | string (JSON) | yes | JSON array of `{"agent", "task", "context?", "caller?", "goal?", "response_format?", "return_ref?", "summary_chars?", "timeout_seconds?"}` |
 | `aggregate` | string | no | Agent name to synthesize all results into one answer |
 
 **Important:** `dispatches` is a JSON string, not a list.
@@ -220,7 +239,7 @@ Run multiple tasks concurrently. Much faster than sequential `dispatch` calls.
 
 Same as `dispatch` but shows live progress while the agent works. Use for long-running tasks. Not cached.
 
-Parameters are identical to `dispatch`.
+Parameters are the same as `dispatch` except `return_ref`/`summary_chars` (streaming is incompatible with ref-mode).
 
 ### `dispatch_dialogue`
 
@@ -314,13 +333,15 @@ Refs reuse the same storage as `dispatch_async` jobs (under `~/.config/agent-dis
 When a dispatched task is going to take a while, you don't want to block your own tool slot for minutes. Async dispatch returns a `job_id` immediately and lets you check back when you're ready.
 
 ```
-// 1. fire and forget
+// 1. fire and forget (timeout_seconds= works here too for known-long tasks)
 dispatch_async(agent="infra", task="audit every container log for OOM kills today")
   -> {"job_id": "8f3a...e1", "status": "pending", "agent": "infra"}
 
 // 2. do other work, then check progress (non-blocking)
+//    `progress` is a rolling tail of what the agent is doing right now
 dispatch_status(job_id="8f3a...e1")
-  -> {"id": "8f3a...e1", "status": "running", "started_at": 1730000123.4, ...}
+  -> {"id": "8f3a...e1", "status": "running", "started_at": 1730000123.4,
+      "progress": ["Using tool: Bash", "Scanning container logs for OOM events..."], ...}
 
 // 3. or block until done (with a timeout cap)
 dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
@@ -332,6 +353,8 @@ dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
 
 `dispatch_cancel(job_id)` cancels a job that is still **pending** (before its subprocess starts) — a running job is left to finish, since its `claude` subprocess can't be safely interrupted. The response carries an `outcome` of `cancelled`, `running`, `already_terminal`, or `not_found`.
 
+Async workers run with streaming under the hood: the job file keeps a rolling tail (last 20 lines, ~1 write/sec) of assistant text and tool-use events. `dispatch_status` shows it as `progress` while the job runs and keeps it afterwards as a post-mortem trace; `dispatch_jobs` shows `last_progress` for running jobs.
+
 `dispatch_jobs(status?)` lists recent jobs as summaries (filter by `pending` / `running` / `done` / `failed` / `cancelled`). `dispatch_gc(max_age_days=7)` purges terminal jobs older than the threshold — pending and running jobs are never deleted.
 
 Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `AGENT_DISPATCH_JOBS_DIR`). One JSON file per job, written owner-only (`0o600`) with atomic writes — safe to read or `ls` while jobs are in flight. Caller-supplied `job_id`s are validated as 32-char hex before any file access (no path traversal). On startup the server marks jobs abandoned in `running` by a prior crashed instance as `failed`.
@@ -362,6 +385,8 @@ All tools return errors as:
 | Need a combined summary from multiple agents | `dispatch_parallel` with `aggregate` |
 | Long task — don't block your tool slot | `dispatch_async` + `dispatch_wait` |
 | Check progress without blocking | `dispatch_status` |
+| Known-long task, one-off | any dispatch tool with `timeout_seconds=...` |
+| A dispatch timed out | `dispatch_session` with the `session_id` from the error |
 
 ## Configuration
 

{agent_dispatch-0.5.0 → agent_dispatch-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.5.0"
+version = "0.6.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.5.0 → agent_dispatch-0.6.0}/src/agent_dispatch/__init__.py

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

{agent_dispatch-0.5.0 → agent_dispatch-0.6.0}/src/agent_dispatch/cli.py

@@ -303,7 +303,11 @@ def update(
     "--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:
+@click.option(
+    "--timeout", "timeout", default=None, type=int,
+    help="One-off timeout override in seconds (does not change the agent config).",
+)
+def test(name: str, task: str, stream: bool, timeout: int | None) -> None:
     """Test an agent by dispatching a task."""
     config = _load_or_exit()
     if name not in config.agents:
@@ -311,6 +315,8 @@ def test(name: str, task: str, stream: bool) -> None:
         raise SystemExit(1)
 
     agent = config.agents[name]
+    if timeout is not None and timeout > 0:
+        agent = agent.model_copy(update={"timeout": timeout})
     click.echo(f"Dispatching to '{name}' ({agent.directory})...")
     click.echo(f"Task: {task}")
     click.echo("---")
@@ -330,6 +336,9 @@ def test(name: str, task: str, stream: bool) -> None:
 
     if result.success:
         click.echo(result.result)
+        if result.hint:
+            click.echo()
+            click.echo(click.style(f"Note: {result.hint}", fg="yellow"))
         if result.cost_usd is not None:
             click.echo(f"\n--- Cost: ${result.cost_usd:.4f} | Turns: {result.num_turns}")
     else:
@@ -343,7 +352,8 @@ def test(name: str, task: str, stream: bool) -> None:
         elif result.error_type == "timeout":
             click.echo()
             click.echo(click.style("Diagnosis: timeout", fg="yellow"))
-            click.echo(f"  agent-dispatch update {name} --timeout 600")
+            click.echo(f"  agent-dispatch test {name} --timeout 600    # one-off")
+            click.echo(f"  agent-dispatch update {name} --timeout 600  # permanent")
         raise SystemExit(1)
 
 

{agent_dispatch-0.5.0 → agent_dispatch-0.6.0}/src/agent_dispatch/jobs.py

@@ -59,6 +59,11 @@ class Job(BaseModel):
     completed_at: float | None = None
     result: DispatchResult | None = None
     error: str | None = None
+    # Rolling tail of progress lines (assistant text / tool-use events) from
+    # the worker's streaming dispatch. None until the first event arrives.
+    # Kept after completion as a post-mortem trace of what the agent did.
+    progress: list[str] | None = None
+    progress_updated_at: float | None = None
 
     def is_terminal(self) -> bool:
         return self.status in _TERMINAL_STATUSES
@@ -194,6 +199,22 @@ class JobStore:
             self._write(job)
             return job
 
+    def update_progress(self, job_id: str, lines: list[str]) -> Job | None:
+        """Replace a running job's progress tail. No-op for terminal jobs.
+
+        Returns the updated job, or None if missing/terminal (a worker's
+        trailing progress write can race a concurrent cancel/finish — refusing
+        to touch terminal jobs keeps their final state authoritative).
+        """
+        with self._lock:
+            job = self.get(job_id)
+            if job is None or job.is_terminal():
+                return None
+            job.progress = lines
+            job.progress_updated_at = time.time()
+            self._write(job)
+            return job
+
     def cancel(self, job_id: str) -> tuple[Job | None, str]:
         """Attempt to cancel a job.
 

{agent_dispatch-0.5.0 → agent_dispatch-0.6.0}/src/agent_dispatch/models.py

@@ -113,3 +113,10 @@ class DispatchResult(BaseModel):
     # 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
+    # Tools the claude CLI refused to run (from `permission_denials` in its
+    # JSON output). Non-empty even on success=True — the agent may have
+    # completed with an incomplete answer because a tool was blocked.
+    denied_tools: list[str] | None = None
+    # Advisory, non-fatal guidance (e.g. "result may be incomplete, grant X").
+    # Errors stay in `error`; hint is for successful-but-degraded results.
+    hint: str | None = None