agent-dispatch 0.13.0__tar.gz → 0.14.0__tar.gz

{agent_dispatch-0.13.0 → agent_dispatch-0.14.0}/AGENTS.md

@@ -28,7 +28,7 @@ pip install -e ".[dev]"
 
 ```bash
 ruff check src/ tests/
-python3 -m pytest tests/ -v   # 578 tests, ~5s
+python3 -m pytest tests/ -v   # 637 tests, ~15s
 ```
 
 Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.which` + `subprocess.run`/`Popen`; server tests mock `_get_config` + `runner.dispatch`. The one exception is `TestStreamPipeHandling`, which spawns a short-lived *python* subprocess: a pipe deadlock lives in the OS pipe buffer, so a mocked `Popen` structurally cannot reproduce it.
@@ -60,7 +60,9 @@ Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.whi
 - Pydantic does **not** validate on assignment. `Field(ge=...)` guards only the *load* path; every mutation surface (CLI `add`/`update`, MCP `add_agent`/`update_agent`) needs its own boundary check, or the bound escapes as a raw `ValidationError`.
 - Every state file (`agents.yaml`, job files) is written **temp file + `os.replace`**, never in place, and every load/mutate/save is wrapped in `config.ProcessLock` — the CLI and the MCP server are separate processes writing the same files, so a thread lock alone loses updates.
 - Anything that changes an agent's config must call `_invalidate_agent_cache` — the cache key holds the agent *name*, not its directory or permissions.
-- Only *clean* successes are cached: `cache.put` refuses failures, `denied_tools` results, and `budget_exceeded` results, so the documented "grant access, then re-dispatch" recovery is never short-circuited.
+- Only *clean* successes are cached: `cache.put` refuses failures, `denied_tools` results, `budget_exceeded` results, and results whose `outcome` is `partial`/`blocked`, so the documented "grant access / fix the cause, then re-dispatch" recovery is never short-circuited.
+- **The dispatch protocol goes in the system prompt, not the task.** `_build_system_prompt` (runner.py) renders the protocol (non-interactive, time/spend budget, lead with the outcome, trailing `STATUS:` line) plus the agent's `instructions`, and `_build_command` passes it as `--append-system-prompt` — on `--resume` too, since the CLI re-applies an appended prompt on every launch. `_build_prompt` (the `-p` text) is unchanged, so the cache key is unchanged. The text always starts with a `##` header line so it can never be read as a flag. `settings.dispatch_protocol: false` turns the protocol off (for CLIs that predate the flag; `doctor` probes `claude --help` for it); per-agent `instructions` still go through when set.
+- **`outcome` is lifted from the LAST line of the result** (`_split_outcome`), before JSON parsing, by the shared `_build_success_result` (the success-side twin of `_build_error_result` — both `dispatch` and `dispatch_stream` go through it) and by the plain-text fallback tier. A bare marker line is removed from `result`; a marker with a trailing reason stays. `outcome` never flips `success`; `partial`/`blocked` add a `hint` with the `dispatch_session(...)` continuation, after the denial hint. In JSON mode the protocol omits the STATUS instruction (the JSON footer governs), but a STATUS line that arrives anyway is still stripped so `parsed_result` survives.
 - Remediation text is a contract: a hint that names a flag must name one that exists (`test_printed_budget_hint_is_a_runnable_command` feeds the printed flags back into the CLI). Run the command you print.
 - The config error sets are declared **once** and in two halves: `config.CONFIG_LOAD_ERRORS` (read) and `config.CONFIG_SAVE_ERRORS` (write — `yaml.dump`'s `RepresenterError` is a `yaml.YAMLError`, therefore neither `OSError` nor `ConfigLoadError`, and used to escape both the MCP guard and the CLI's `_save_or_exit`). Two halves, not one set, because the remediations differ: a failed write is atomic so the old config survives, while a failed read needs the YAML fixed.
 - MCP tools that load config carry `@_config_guard` under `@mcp.tool()` so a broken `agents.yaml` — or a failed *write* — returns the `{"error": ...}` envelope instead of a raw traceback. The set of load errors lives in one place (`config.CONFIG_LOAD_ERRORS`) because three surfaces handle it: **`UnicodeDecodeError` is a `ValueError`, not an `OSError`**, and listing types per-site is exactly how a cp1251 config slipped past all three.
@@ -85,4 +87,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/`, 578 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/`, 637 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.13.0 → agent_dispatch-0.14.0}/CHANGELOG.md

@@ -7,6 +7,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-09-08
+
+The delegation round: what a dispatched agent is *told*, and what it tells
+back. Until now `claude -p` was launched with the task and nothing else — it
+did not know it was being driven by another agent, that nobody would answer a
+question, how long it had, or how to report an unfinished job. The failure
+mode was concrete and billed: an ambiguous task ended in *"Could you clarify
+which service you mean?"*, `success: true`, cached for the whole TTL.
+
+### Added
+- **The dispatch protocol.** Every dispatch now appends a short system prompt
+  (`--append-system-prompt`, never mixed into the task text) telling the agent
+  that it is non-interactive and dispatched by `caller`, that it must state
+  assumptions instead of asking, that a denied tool is something to report and
+  work around rather than stop on, what its time budget (and spend cap) is, to
+  lead with the outcome — which is what makes a `return_ref` summary, the
+  *head* of the text, worth reading — and to end with one line:
+  `STATUS: done | partial | blocked`. Passed on `--resume` too. Verified live
+  against claude 2.1.263 (`agent-dispatch test <agent> --stream`).
+- **`DispatchResult.outcome`** — that trailing line, lifted out of `result`
+  into a field: `done`, `partial` or `blocked`, or absent when the agent did
+  not report one. It never flips `success`. `partial`/`blocked` come with a
+  `hint` carrying the exact `dispatch_session(..., session_id=...)` call to
+  continue, ride the `return_ref` payload and `dispatch_jobs` summaries, are
+  shown by `agent-dispatch test` / `job <id>`, are labelled for the
+  `dispatch_parallel` aggregator so a blocked member is not synthesized as a
+  finished one — and are **not cached**: whatever the agent was missing is not
+  in the cache key, so a retry after fixing it must run fresh.
+- **Per-agent `instructions`** — standing orders appended after the protocol
+  on every dispatch ("read-only SQL only", "never restart a stack unless the
+  task says so"). `add_agent`/`update_agent` (`"none"` clears), CLI `add` /
+  `update --instructions` (`none` clears), shown by `inspect_agent` and
+  `describe`, pruned from YAML when empty. Changing them invalidates the
+  agent's cache entries like any other config change.
+- **`settings.dispatch_protocol`** (default `true`) — set to `false` for a raw
+  `claude -p` (a CLI that predates `--append-system-prompt`, or an A/B). The
+  protocol and the instructions share one flag, so instructions still go
+  through when set. `doctor` now probes `claude --help` for the flag and warns
+  with the exact remediation when it is missing.
+
+### Changed
+- In `response_format="json"` mode the protocol omits the "lead with the
+  outcome" and STATUS bullets — the JSON footer governs the reply shape. A
+  STATUS line that arrives anyway is still stripped before parsing, so
+  `parsed_result` survives it.
+- `dispatch` and `dispatch_stream` build their success result through one
+  `_build_success_result`, the twin of `_build_error_result`.
+
+
 ## [0.13.0] - 2026-08-13
 
 An efficiency round, measured against a real 38 KB config (4 agents, 6 groups),

{agent_dispatch-0.13.0 → agent_dispatch-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-dispatch
-Version: 0.13.0
+Version: 0.14.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
@@ -220,7 +220,8 @@ dispatch(
   "session_id": "sess-abc-123",
   "cost_usd": 0.02,
   "duration_ms": 5000,
-  "num_turns": 2
+  "num_turns": 2,
+  "outcome": "done"
 }
 
 // Response (failure — error_type helps you handle programmatically)
@@ -278,6 +279,30 @@ Error: TypeError at scheduler.py:42
 Check container logs for recent errors related to the scheduler service
 ```
 
+**The dispatch protocol and `outcome`.** `claude -p` on its own does not know it is being driven by another agent: given an ambiguous task it will happily end with *"Could you clarify which service you mean?"* — a billed run that answered nothing, and one that a plain cache would then serve again for the whole TTL. So every dispatch also appends a short **dispatch protocol** to the agent's system prompt (`--append-system-prompt`, never mixed into your task text):
+
+- it is running non-interactively, dispatched by `caller`, and nobody will answer a question or approve an action — state the assumption and proceed, take the safer reading when two differ;
+- a denied tool or a missing thing is something to report, not something to stop on — finish everything else that is possible;
+- its time budget is about the agent's timeout (and its spend cap, if one is set) — scope the work to fit; a complete partial answer beats an unfinished perfect one;
+- lead with the outcome, then the evidence; list what could not be done and why (this is what makes a `return_ref` summary — the **head** of the text — worth reading);
+- end with one line, `STATUS: done`, `STATUS: partial` or `STATUS: blocked`.
+
+That last line is lifted out of `result` into **`outcome`** — the agent's own verdict, deterministic to check: `"done"` means complete; `"partial"` / `"blocked"` mean the agent says the work is unfinished, the result names what is missing, and a `hint` spells out the continuation (usually `dispatch_session(..., session_id=...)`). Read `outcome` before reading the text. It never flips `success`, `partial` / `blocked` results are **not cached**, and a `dispatch_parallel(..., aggregate=...)` labels such members for the aggregator so a blocked report is not synthesized as a finished one. Absent when the agent did not report one — the protocol is off (`settings.dispatch_protocol: false`), `response_format="json"` was requested (the JSON footer governs the reply shape there), or the agent simply skipped it.
+
+**Standing orders.** Per-agent `instructions` (set via `add_agent` / `update_agent` or `agent-dispatch update <name> --instructions "..."`) follow the protocol in the same system prompt on **every** dispatch — "read-only SQL only", "never restart a stack unless the task says so", "answer with exact log lines". Unlike `context`, which is per call, and unlike the project's own `CLAUDE.md`, which is written for an interactive session, these are the rules for *being dispatched*.
+
+```json
+// Response (success, but the agent says it did not finish)
+{
+  "agent": "infra",
+  "success": true,
+  "result": "Restarted horizon. Could not verify the queue drained: the redis container is not reachable from here.",
+  "session_id": "sess-abc-123",
+  "outcome": "partial",
+  "hint": "The agent reports its work is PARTIAL — read the result for what is missing, then continue in the same session via dispatch_session(agent='infra', task='Continue where you left off', session_id='sess-abc-123') or re-dispatch with what it needed."
+}
+```
+
 ### `dispatch_session`
 
 Multi-turn: continue a conversation with an agent. First call starts a session, pass `session_id` back to continue. Never cached.
@@ -395,6 +420,7 @@ Register a new project directory as an agent. Description is auto-generated from
 | `disallowed_tools` | string | no | Comma-separated disallowed tools |
 | `capabilities` | string | no | Comma-separated capability labels (e.g. `"docker_logs,deploy_debug"`) |
 | `risky_capabilities` | string | no | Comma-separated high-risk labels (e.g. `"restart_services"`) |
+| `instructions` | string | no | Standing orders appended to the agent's system prompt on every dispatch (see [the dispatch protocol](#dispatch)) |
 
 ### `update_agent`
 
@@ -412,6 +438,7 @@ Update an existing agent's configuration. Only non-empty fields are changed. Pas
 | `disallowed_tools` | string | no | Comma-separated. `"none"` to clear |
 | `capabilities` | string | no | Comma-separated. `"none"` to clear |
 | `risky_capabilities` | string | no | Comma-separated. `"none"` to clear |
+| `instructions` | string | no | Standing orders for every dispatch (replaces the text). `"none"` to clear |
 
 Changing an agent's config drops that agent's cached results — the cache key holds the agent *name*, so a re-pointed or re-permissioned agent would otherwise keep answering from the previous config for the rest of the TTL. The same applies to `add_agent` and `remove_agent`.
 
@@ -515,6 +542,7 @@ Failures are deterministic: check `success`, then branch on `error_type`.
 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.
+- **`outcome: "partial"` / `"blocked"`** — the agent's own verdict that it did not finish; the result names what is missing and the `hint` carries the `dispatch_session(...)` call to continue in the same session. Not cached, so a re-dispatch after fixing the cause runs fresh.
 - **`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` 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.
 
@@ -539,6 +567,9 @@ agents:
       - deploy_debug
     risky_capabilities:     # high-risk labels, surfaced for visibility
       - restart_services
+    # instructions: |       # standing orders, appended to the system prompt on every dispatch
+    #   Read-only: never restart or redeploy unless the task says so.
+    #   Quote exact log lines with timestamps.
     # model: sonnet         # optional model override
     # max_budget_usd: 1.0   # cost limit per dispatch
     # permission_mode: bypassPermissions  # one of: default | plan | bypassPermissions
@@ -574,6 +605,8 @@ settings:
   #   - Edit
   max_dispatch_depth: 3     # recursion protection
   max_concurrency: 5        # max parallel claude -p processes (per dispatch path)
+  # dispatch_protocol: true # send every agent the dispatch protocol (non-interactive,
+  #                         # time budget, STATUS line → `outcome`). false = raw claude -p.
   # job_retention_days: 30  # 0 (default) = never prune. See "Job retention" below.
   cache:
     enabled: true
@@ -646,8 +679,9 @@ agent-dispatch MCP server
        ▼
      New Claude Code session in ~/projects/infra/
        ├─ Inherits: CLAUDE.md, .mcp.json, project tools
+       ├─ System prompt += dispatch protocol + the agent's standing `instructions`
        ├─ Receives structured prompt with goal/caller/context/task
-       └─ Returns result → cached for future identical requests
+       └─ Returns result (+ its own STATUS → `outcome`) → cached when complete
 ```
 
 ## Safety
@@ -659,7 +693,7 @@ agent-dispatch MCP server
 - **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). A streaming dispatch runs the agent in its own process group, so the deadline kills the whole tree: a process the agent left running in the background can't hold the dispatch (and its concurrency slot) open past the timeout.
-- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only clean successes are cached: failures, results with `denied_tools`, and results flagged `budget_exceeded` are not, so the documented "grant access / raise the cap, then re-dispatch" recovery is never served a stale crippled answer. Changing an agent's config invalidates its entries. 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.
+- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only clean successes are cached: failures, results with `denied_tools`, results flagged `budget_exceeded`, and results the agent itself reported as `partial` / `blocked` are not, so the documented "grant access / raise the cap, then re-dispatch" recovery is never served a stale crippled answer. Changing an agent's config invalidates its entries. 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.
 - **Durable config** — `agents.yaml` is written atomically (temp file + rename), so an interrupted write can never truncate it. Every mutation path (CLI and MCP server alike) also takes a cross-process advisory lock, so concurrent edits don't drop one another's agents. The lock is best-effort by design: after waiting 10 seconds it logs a warning and proceeds anyway, because a wedged lock holder must not freeze the MCP server — so on a heavily contended config a lost update is possible, while a truncated one is not.
 
 See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
@@ -670,13 +704,13 @@ See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassP
 |---------|-------------|
 | `agent-dispatch init` | Create config + register MCP server with Claude Code |
 | `agent-dispatch add <name> <dir>` | Add an agent (auto-generates description) |
-| `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, etc.) |
+| `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, `--instructions`, etc.) |
 | `agent-dispatch remove <name>` | Remove an agent |
 | `agent-dispatch list` | List agents with health status and permissions |
 | `agent-dispatch group <add\|list\|inspect\|update\|remove>` | Manage [groups](#groups) — cross-project working sets of agents |
 | `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, and group membership |
+| `agent-dispatch doctor` | Diagnose installation: Claude CLI (incl. `--append-system-prompt` support), MCP registration, agent health, and group membership |
 | `agent-dispatch jobs [--status --limit]` | List async dispatch jobs (most recent first) |
 | `agent-dispatch job <id>` | Show one job: status, progress tail, result preview |
 | `agent-dispatch cancel <id>` | Cancel a pending job (running jobs: use the `dispatch_cancel` MCP tool) |

{agent_dispatch-0.13.0 → agent_dispatch-0.14.0}/README.md

@@ -190,7 +190,8 @@ dispatch(
   "session_id": "sess-abc-123",
   "cost_usd": 0.02,
   "duration_ms": 5000,
-  "num_turns": 2
+  "num_turns": 2,
+  "outcome": "done"
 }
 
 // Response (failure — error_type helps you handle programmatically)
@@ -248,6 +249,30 @@ Error: TypeError at scheduler.py:42
 Check container logs for recent errors related to the scheduler service
 ```
 
+**The dispatch protocol and `outcome`.** `claude -p` on its own does not know it is being driven by another agent: given an ambiguous task it will happily end with *"Could you clarify which service you mean?"* — a billed run that answered nothing, and one that a plain cache would then serve again for the whole TTL. So every dispatch also appends a short **dispatch protocol** to the agent's system prompt (`--append-system-prompt`, never mixed into your task text):
+
+- it is running non-interactively, dispatched by `caller`, and nobody will answer a question or approve an action — state the assumption and proceed, take the safer reading when two differ;
+- a denied tool or a missing thing is something to report, not something to stop on — finish everything else that is possible;
+- its time budget is about the agent's timeout (and its spend cap, if one is set) — scope the work to fit; a complete partial answer beats an unfinished perfect one;
+- lead with the outcome, then the evidence; list what could not be done and why (this is what makes a `return_ref` summary — the **head** of the text — worth reading);
+- end with one line, `STATUS: done`, `STATUS: partial` or `STATUS: blocked`.
+
+That last line is lifted out of `result` into **`outcome`** — the agent's own verdict, deterministic to check: `"done"` means complete; `"partial"` / `"blocked"` mean the agent says the work is unfinished, the result names what is missing, and a `hint` spells out the continuation (usually `dispatch_session(..., session_id=...)`). Read `outcome` before reading the text. It never flips `success`, `partial` / `blocked` results are **not cached**, and a `dispatch_parallel(..., aggregate=...)` labels such members for the aggregator so a blocked report is not synthesized as a finished one. Absent when the agent did not report one — the protocol is off (`settings.dispatch_protocol: false`), `response_format="json"` was requested (the JSON footer governs the reply shape there), or the agent simply skipped it.
+
+**Standing orders.** Per-agent `instructions` (set via `add_agent` / `update_agent` or `agent-dispatch update <name> --instructions "..."`) follow the protocol in the same system prompt on **every** dispatch — "read-only SQL only", "never restart a stack unless the task says so", "answer with exact log lines". Unlike `context`, which is per call, and unlike the project's own `CLAUDE.md`, which is written for an interactive session, these are the rules for *being dispatched*.
+
+```json
+// Response (success, but the agent says it did not finish)
+{
+  "agent": "infra",
+  "success": true,
+  "result": "Restarted horizon. Could not verify the queue drained: the redis container is not reachable from here.",
+  "session_id": "sess-abc-123",
+  "outcome": "partial",
+  "hint": "The agent reports its work is PARTIAL — read the result for what is missing, then continue in the same session via dispatch_session(agent='infra', task='Continue where you left off', session_id='sess-abc-123') or re-dispatch with what it needed."
+}
+```
+
 ### `dispatch_session`
 
 Multi-turn: continue a conversation with an agent. First call starts a session, pass `session_id` back to continue. Never cached.
@@ -365,6 +390,7 @@ Register a new project directory as an agent. Description is auto-generated from
 | `disallowed_tools` | string | no | Comma-separated disallowed tools |
 | `capabilities` | string | no | Comma-separated capability labels (e.g. `"docker_logs,deploy_debug"`) |
 | `risky_capabilities` | string | no | Comma-separated high-risk labels (e.g. `"restart_services"`) |
+| `instructions` | string | no | Standing orders appended to the agent's system prompt on every dispatch (see [the dispatch protocol](#dispatch)) |
 
 ### `update_agent`
 
@@ -382,6 +408,7 @@ Update an existing agent's configuration. Only non-empty fields are changed. Pas
 | `disallowed_tools` | string | no | Comma-separated. `"none"` to clear |
 | `capabilities` | string | no | Comma-separated. `"none"` to clear |
 | `risky_capabilities` | string | no | Comma-separated. `"none"` to clear |
+| `instructions` | string | no | Standing orders for every dispatch (replaces the text). `"none"` to clear |
 
 Changing an agent's config drops that agent's cached results — the cache key holds the agent *name*, so a re-pointed or re-permissioned agent would otherwise keep answering from the previous config for the rest of the TTL. The same applies to `add_agent` and `remove_agent`.
 
@@ -485,6 +512,7 @@ Failures are deterministic: check `success`, then branch on `error_type`.
 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.
+- **`outcome: "partial"` / `"blocked"`** — the agent's own verdict that it did not finish; the result names what is missing and the `hint` carries the `dispatch_session(...)` call to continue in the same session. Not cached, so a re-dispatch after fixing the cause runs fresh.
 - **`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` 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.
 
@@ -509,6 +537,9 @@ agents:
       - deploy_debug
     risky_capabilities:     # high-risk labels, surfaced for visibility
       - restart_services
+    # instructions: |       # standing orders, appended to the system prompt on every dispatch
+    #   Read-only: never restart or redeploy unless the task says so.
+    #   Quote exact log lines with timestamps.
     # model: sonnet         # optional model override
     # max_budget_usd: 1.0   # cost limit per dispatch
     # permission_mode: bypassPermissions  # one of: default | plan | bypassPermissions
@@ -544,6 +575,8 @@ settings:
   #   - Edit
   max_dispatch_depth: 3     # recursion protection
   max_concurrency: 5        # max parallel claude -p processes (per dispatch path)
+  # dispatch_protocol: true # send every agent the dispatch protocol (non-interactive,
+  #                         # time budget, STATUS line → `outcome`). false = raw claude -p.
   # job_retention_days: 30  # 0 (default) = never prune. See "Job retention" below.
   cache:
     enabled: true
@@ -616,8 +649,9 @@ agent-dispatch MCP server
        ▼
      New Claude Code session in ~/projects/infra/
        ├─ Inherits: CLAUDE.md, .mcp.json, project tools
+       ├─ System prompt += dispatch protocol + the agent's standing `instructions`
        ├─ Receives structured prompt with goal/caller/context/task
-       └─ Returns result → cached for future identical requests
+       └─ Returns result (+ its own STATUS → `outcome`) → cached when complete
 ```
 
 ## Safety
@@ -629,7 +663,7 @@ agent-dispatch MCP server
 - **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). A streaming dispatch runs the agent in its own process group, so the deadline kills the whole tree: a process the agent left running in the background can't hold the dispatch (and its concurrency slot) open past the timeout.
-- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only clean successes are cached: failures, results with `denied_tools`, and results flagged `budget_exceeded` are not, so the documented "grant access / raise the cap, then re-dispatch" recovery is never served a stale crippled answer. Changing an agent's config invalidates its entries. 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.
+- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only clean successes are cached: failures, results with `denied_tools`, results flagged `budget_exceeded`, and results the agent itself reported as `partial` / `blocked` are not, so the documented "grant access / raise the cap, then re-dispatch" recovery is never served a stale crippled answer. Changing an agent's config invalidates its entries. 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.
 - **Durable config** — `agents.yaml` is written atomically (temp file + rename), so an interrupted write can never truncate it. Every mutation path (CLI and MCP server alike) also takes a cross-process advisory lock, so concurrent edits don't drop one another's agents. The lock is best-effort by design: after waiting 10 seconds it logs a warning and proceeds anyway, because a wedged lock holder must not freeze the MCP server — so on a heavily contended config a lost update is possible, while a truncated one is not.
 
 See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
@@ -640,13 +674,13 @@ See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassP
 |---------|-------------|
 | `agent-dispatch init` | Create config + register MCP server with Claude Code |
 | `agent-dispatch add <name> <dir>` | Add an agent (auto-generates description) |
-| `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, etc.) |
+| `agent-dispatch update <name>` | Update agent config (permissions, timeout, model, `--instructions`, etc.) |
 | `agent-dispatch remove <name>` | Remove an agent |
 | `agent-dispatch list` | List agents with health status and permissions |
 | `agent-dispatch group <add\|list\|inspect\|update\|remove>` | Manage [groups](#groups) — cross-project working sets of agents |
 | `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, and group membership |
+| `agent-dispatch doctor` | Diagnose installation: Claude CLI (incl. `--append-system-prompt` support), MCP registration, agent health, and group membership |
 | `agent-dispatch jobs [--status --limit]` | List async dispatch jobs (most recent first) |
 | `agent-dispatch job <id>` | Show one job: status, progress tail, result preview |
 | `agent-dispatch cancel <id>` | Cancel a pending job (running jobs: use the `dispatch_cancel` MCP tool) |

{agent_dispatch-0.13.0 → agent_dispatch-0.14.0}/agents.example.yaml

@@ -9,6 +9,13 @@ agents:
     risky_capabilities:
       - restart_services
     timeout: 300
+    # Standing orders, appended to the agent's system prompt on EVERY dispatch
+    # (after the dispatch protocol). Unlike `context`, which is per call, and
+    # unlike the project's CLAUDE.md, which is written for an interactive
+    # session, these are the rules for being dispatched.
+    instructions: |
+      Read-only unless the task explicitly asks to restart or redeploy.
+      Quote exact log lines with timestamps; never paraphrase an error.
 
   # Analytics gateway — a browser + Yandex Metrica agent, no codebase of its own.
   # Its value is its MCP servers + access, not its source. Shared across groups.
@@ -93,6 +100,12 @@ settings:
   default_timeout: 300
   max_dispatch_depth: 3           # recursion protection: A -> B -> A
   max_concurrency: 5              # max parallel claude -p processes
+  # dispatch_protocol: true        # Append the dispatch protocol to every agent's system
+                                   # prompt: it is non-interactive (never end with a
+                                   # question), its time/spend budget, lead with the
+                                   # outcome, end with `STATUS: done|partial|blocked`
+                                   # (→ DispatchResult.outcome). false = raw claude -p;
+                                   # needed only for CLIs without --append-system-prompt.
   # 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

{agent_dispatch-0.13.0 → agent_dispatch-0.14.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.13.0"
+version = "0.14.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.13.0 → agent_dispatch-0.14.0}/src/agent_dispatch/__init__.py

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

{agent_dispatch-0.13.0 → agent_dispatch-0.14.0}/src/agent_dispatch/cache.py

@@ -102,6 +102,12 @@ class DispatchCache:
             # serve the same crippled answer back for the whole TTL and make that
             # recovery a no-op (the permission config is not part of the key).
             return
+        if result.outcome in ("partial", "blocked"):
+            # The agent itself says the work is unfinished. Whatever it was
+            # missing (a service that was down, a file that did not exist yet)
+            # is not in the key either, so a retry after fixing it would be
+            # served the same unfinished answer for the whole TTL.
+            return
         key = self._make_key(agent, task, context, caller, goal, response_format)
         with self._lock:
             # Bound memory: when at capacity and inserting a new key, evict the

{agent_dispatch-0.13.0 → agent_dispatch-0.14.0}/src/agent_dispatch/cli.py

@@ -101,6 +101,22 @@ def _check_timeout_or_exit(timeout: int | None) -> None:
         raise SystemExit(1)
 
 
+def _claude_supports_flag(claude_path: str, flag: str) -> bool | None:
+    """Whether `claude --help` lists *flag*; None when the probe itself failed."""
+    try:
+        proc = subprocess.run(
+            [claude_path, "--help"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=10,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    return flag in (proc.stdout or "") + (proc.stderr or "")
+
+
 def _load_or_exit() -> DispatchConfig:
     """Load config, exiting with a friendly error on malformed YAML or schema."""
     try:
@@ -233,6 +249,11 @@ def init() -> None:
     default=None,
     help="Comma-separated risky capabilities (e.g. restart_services).",
 )
+@click.option(
+    "--instructions",
+    default=None,
+    help="Standing orders appended to the agent's system prompt on every dispatch.",
+)
 def add(
     name: str,
     directory: str,
@@ -245,6 +266,7 @@ def add(
     disallowed_tools: str | None,
     capabilities: str | None,
     risky_capabilities: str | None,
+    instructions: str | None,
 ) -> None:
     """Add an agent. Auto-generates description from project files if omitted."""
     try:
@@ -281,6 +303,7 @@ def add(
             disallowed_tools=_parse_csv(disallowed_tools),
             capabilities=_parse_csv(capabilities) or [],
             risky_capabilities=_parse_csv(risky_capabilities) or [],
+            instructions=(instructions or "").strip(),
         )
         if warning := check_permission_mode(permission_mode):
             click.echo(click.style(f"Warning: {warning}", fg="yellow"))
@@ -388,6 +411,11 @@ def list_agents() -> None:
     default=None,
     help="Comma-separated risky capabilities. Use 'none' to clear.",
 )
+@click.option(
+    "--instructions",
+    default=None,
+    help="Standing orders for every dispatch (replaces the text). Use 'none' to clear.",
+)
 @click.pass_context
 def update(
     ctx: click.Context,
@@ -401,6 +429,7 @@ def update(
     disallowed_tools: str | None,
     capabilities: str | None,
     risky_capabilities: str | None,
+    instructions: str | None,
 ) -> None:
     """Update an existing agent's configuration."""
     _check_timeout_or_exit(timeout)
@@ -424,6 +453,7 @@ def update(
             disallowed_tools=disallowed_tools,
             capabilities=capabilities,
             risky_capabilities=risky_capabilities,
+            instructions=instructions,
         )
 
         if not updated:
@@ -446,6 +476,7 @@ def _apply_cli_updates(
     disallowed_tools: str | None,
     capabilities: str | None,
     risky_capabilities: str | None,
+    instructions: str | None = None,
 ) -> list[str]:
     """Apply `update`'s explicitly-passed options in place; return the fields touched."""
     updated: list[str] = []
@@ -493,6 +524,10 @@ def _apply_cli_updates(
         else:
             agent.risky_capabilities = _parse_csv(risky_capabilities) or []
         updated.append("risky_capabilities")
+    if instructions is not None:
+        stripped = instructions.strip()
+        agent.instructions = "" if stripped.lower() == "none" else stripped
+        updated.append("instructions")
 
     return updated
 
@@ -551,7 +586,11 @@ def test(name: str, task: str, stream: bool, timeout: int | None) -> None:
             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}")
+            tail = f"\n--- Cost: ${result.cost_usd:.4f} | Turns: {result.num_turns}"
+            if result.outcome:
+                color = "green" if result.outcome == "done" else "yellow"
+                tail += f" | Outcome: {click.style(result.outcome, fg=color)}"
+            click.echo(tail)
     else:
         click.echo(click.style(f"Error: {result.error}", fg="red"))
         if result.error_type == "permission":
@@ -614,6 +653,11 @@ def describe(name: str) -> None:
         click.echo(f"  capabilities:     {', '.join(agent.capabilities)}")
     if agent.risky_capabilities:
         click.echo(f"  risky_caps:       {', '.join(agent.risky_capabilities)}")
+    if agent.instructions:
+        first, *rest = agent.instructions.splitlines()
+        click.echo(f"  instructions:     {first}")
+        for line in rest:
+            click.echo(f"                    {line}")
     click.echo(f"  allowed_tools:    {_render_tools(agent.allowed_tools)}")
     click.echo(f"  disallowed_tools: {_render_tools(agent.disallowed_tools)}")
 
@@ -828,6 +872,15 @@ def doctor() -> None:
     claude_path = shutil.which("claude")
     if claude_path:
         ok(f"claude CLI: {claude_path}")
+        supported = _claude_supports_flag(claude_path, "--append-system-prompt")
+        if supported is True:
+            ok("claude CLI supports --append-system-prompt (dispatch protocol)")
+        elif supported is False:
+            warn("claude CLI predates --append-system-prompt: every dispatch will fail")
+            click.echo("    Upgrade claude, or set `settings.dispatch_protocol: false` and")
+            click.echo("    clear orders orders: agent-dispatch update <name> --instructions none")
+        else:
+            warn("Could not run `claude --help` to check --append-system-prompt support")
     else:
         fail("claude CLI not found on PATH")
         click.echo("    Install: https://docs.anthropic.com/en/docs/claude-code")
@@ -1048,6 +1101,9 @@ def job_show(job_id: str) -> None:
             click.echo(f"  cost_usd:   ${job.result.cost_usd:.4f}")
         if job.result.budget_exceeded:
             click.echo(click.style("  budget:     EXCEEDED", fg="yellow"))
+        if job.result.outcome:
+            color = "green" if job.result.outcome == "done" else "yellow"
+            click.echo(f"  outcome:    {click.style(job.result.outcome, fg=color)}")
         if job.result.result:
             preview = job.result.result[:2000]
             truncated = len(job.result.result) > 2000

{agent_dispatch-0.13.0 → agent_dispatch-0.14.0}/src/agent_dispatch/config.py

@@ -222,7 +222,7 @@ def save_config(config: DispatchConfig, path: Path | None = None) -> None:
     # won't drop them — prune empties so agents that never declare capabilities
     # stay clean in YAML instead of growing two empty-list keys on every save.
     for agent_data in data.get("agents", {}).values():
-        for key in ("capabilities", "risky_capabilities"):
+        for key in ("capabilities", "risky_capabilities", "instructions"):
             if not agent_data.get(key):
                 agent_data.pop(key, None)
     # `groups` also defaults to {} (not None), so exclude_none keeps it — prune

{agent_dispatch-0.13.0 → agent_dispatch-0.14.0}/src/agent_dispatch/models.py

@@ -53,6 +53,12 @@ class AgentConfig(BaseModel):
     disallowed_tools: list[str] | None = None
     capabilities: list[str] = Field(default_factory=list)
     risky_capabilities: list[str] = Field(default_factory=list)
+    # Standing orders for this agent whenever it is dispatched ("read-only SQL
+    # only", "never restart a stack unless the task says so"). Appended to the
+    # claude system prompt via --append-system-prompt, after the dispatch
+    # protocol — so they hold across every task, unlike `context`, which is
+    # per call. Empty = nothing appended. Pruned from YAML when empty.
+    instructions: str = ""
 
     @field_validator("directory", mode="before")
     @classmethod
@@ -107,6 +113,12 @@ class Settings(BaseModel):
     # must be an explicit choice rather than something a version bump starts
     # doing to an existing install.
     job_retention_days: int = Field(default=0, ge=0)
+    # Send every dispatched agent the dispatch protocol as an appended system
+    # prompt: it is running non-interactively, nobody will answer a question,
+    # its time/spend budget, lead with the outcome, end with a STATUS line
+    # (parsed into DispatchResult.outcome). Off = raw `claude -p` behaviour,
+    # for CLIs that predate --append-system-prompt or for A/B comparison.
+    dispatch_protocol: bool = True
 
 
 def validate_agent_name(name: str) -> str:
@@ -214,3 +226,8 @@ class DispatchResult(BaseModel):
     # default). Post-hoc only — the money is already spent, the dispatch is
     # NOT failed for it. None means: no budget configured, or within budget.
     budget_exceeded: bool | None = None
+    # The agent's own verdict on its work, from the trailing `STATUS:` line the
+    # dispatch protocol asks for: "done", "partial" or "blocked". None when the
+    # agent did not report one (protocol off, JSON mode, or it just didn't).
+    # Descriptive: never flips `success`. partial/blocked are not cached.
+    outcome: str | None = None