> ## Documentation Index
> Fetch the complete documentation index at: https://agents.concierca.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Missions

> Mission CRUD, runs, steps, drafts, diagnostics, runtime control, and roster.

A **mission** is a step sequence (agents, human gates, waits, verifications, notifications, outbound HTTP calls) executed by the sequence engine. Missions are **membership-scoped**: you see and operate only missions where you are the owner or a member — never tenant-wide. Your role per mission is `owner`, `lead`, `member` or `viewer`; owner/lead may run and edit.

**Step types and their config contract** (used by `mission_create`, `mission_steps_update`, `mission_draft_update`):

| step\_type  | config                                                                                                                                                                                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent`     | `{agent_id, no_work_token?, require_receipts?}` — `no_work_token`: if the agent's output ends with this exact token, the run completes silently (remaining steps skipped, no owner digest); `require_receipts`: an answer without a single tool call fails the step |
| `human`     | `{approver_user_id?, instruction, kind: 'approve'\|'input'}`                                                                                                                                                                                                        |
| `wait_time` | `{seconds}` or `{until_iso}`                                                                                                                                                                                                                                        |
| `wait_poll` | `{interval_seconds, max_attempts, probe?}`                                                                                                                                                                                                                          |
| `verify`    | `{probe: {kind: 'http'\|'db', ...}}`                                                                                                                                                                                                                                |
| `notify`    | `{user_id?, message}`                                                                                                                                                                                                                                               |
| `http_call` | `{url, method, headers?, body?, expect_status?, contains?, timeout?}` — outbound HTTP request; the response is checked against `expect_status` and/or `contains`; `timeout` is capped at 60s                                                                        |

Each step may also carry `handoff_prompt`, `on_fail`, and (in drafts) `output_schema` / `step_key`. Max 20 steps per mission.

The 30 mission tools fall into six groups: **reads** (see a mission), **diagnostics & analytics** (understand a run), **writes** (edit the config), **running & approving** (execute + the human gate), **runtime control** (steer an active run, all human-gated), and **drafts** (stage edits before publishing).

***

## Reads

### `mission_list`

List the missions this user can see. Each row carries your role and the latest run.

| Name    | Type   | Required | Description                    |
| ------- | ------ | -------- | ------------------------------ |
| `limit` | number | no       | Max rows (default 50, max 200) |

**Returns:** `{ projects: [...], count, note }`. Each project row carries its core fields plus your `role` and `last_run` (`{id, status, started_at, finished_at, total_credits}` or `null`).

**Permissions:** read; owner or member only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_list", "arguments": {} } }
```

### `mission_get`

One mission in one read: core fields + your role, the business passport, a step summary, variables (metadata only — never secret values), the derived genome (structural fingerprint), capability manifest and version count.

| Name | Type   | Required | Description  |
| ---- | ------ | -------- | ------------ |
| `id` | string | yes      | Mission uuid |

**Returns:** `{ mission, passport, steps, variables, genome, manifest, version_count, note }`. `mission` carries `id, role, name, goal, status, department_id, owner_user_id, created_at, updated_at, default_max_credits_per_run, max_cycles` plus a non-secret `trigger: {schedule_enabled, webhook_enabled}` (the raw `trigger_config`, including any webhook secret, is never exposed). `steps` is a summary (`{position, step_type, step_key, has_output_schema}`); `variables` is metadata only (`{key, data_type, value_source, is_secret_reference}`); `passport` is `null` when none is set.

**Permissions:** read; membership-scoped.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_get", "arguments": { "id": "<uuid>" } } }
```

### `mission_status`

One mission's full status: the step plan (positions + step\_type + config) and the latest run with its per-step chain (status, attempts, timings) and total credits — same data as the app's run timeline.

| Name | Type   | Required | Description  |
| ---- | ------ | -------- | ------------ |
| `id` | string | yes      | Mission uuid |

**Returns:** `{ project, steps, latest_run }`. `project` is your access row; `steps` is the plan (`{id, position, step_type, config, handoff_prompt, on_fail}`); `latest_run` is `{id, status, started_by, total_credits, started_at, finished_at, steps: [{id, step_position, status, attempt_count, agent_run_id, started_at, finished_at}]}` or `null` when the mission has never run.

**Permissions:** read; membership-scoped.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_status", "arguments": { "id": "<uuid>" } } }
```

### `mission_flow_get`

The mission's full step plan (config, handoff\_prompt, on\_fail, output\_schema, step\_key) plus a preview subset for every referenced agent (name, model, tools/toolkits, data grants, skills, performance — never system prompts, credentials or secrets).

| Name | Type   | Required | Description  |
| ---- | ------ | -------- | ------------ |
| `id` | string | yes      | Mission uuid |

**Returns:** `{ steps, agent_previews, note }`. `steps` is the full plan (`{id, position, step_type, step_key, config, handoff_prompt, on_fail, output_schema}`); `agent_previews` is the membership-scoped preview subset for each referenced agent (name, model, tools/toolkits, data grants, skills, performance — never system prompts or secrets).

**Permissions:** read; membership-scoped.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_flow_get", "arguments": { "id": "<uuid>" } } }
```

### `mission_members_get`

The mission roster: owner + members (user, name, role, since) and your own role. Membership is the mission's visibility boundary.

| Name | Type   | Required | Description  |
| ---- | ------ | -------- | ------------ |
| `id` | string | yes      | Mission uuid |

**Returns:** `{ owner, members, your_role, note }`. `owner` is `{user_id, name, role:"owner"}` (or `null`); `members` is `[{user_id, name, role, since}]`; `your_role` is your role on this mission.

**Permissions:** read; owner or member only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_members_get", "arguments": { "id": "<uuid>" } } }
```

### `mission_templates`

List the built-in mission templates (read-only catalog): slug, name, description, step chain and assignment slots (agent slots required, user slots optional). Instantiate one via `mission_create` with `template_slug` + `assignments`.

**Parameters:** none.

**Returns:** `{ templates, note }`. Each template: `{slug, name, description, steps: [{position, step_type, agent_slot, user_slot}], agent_slots: [{key, label}], user_slots: [{key, label}]}`.

**Permissions:** read.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_templates", "arguments": {} } }
```

## Diagnostics & analytics

### `mission_run_trace_get`

Deep trace of one run: run header (status, business verdict, credits, budget) + the per-step chain (status, verdict, attempts, timings, agent version, capped receipt/input, cost/savings, tokens). Text fields are capped — this is a diagnosis surface, not a data dump.

| Name                | Type    | Required | Description                                                        |
| ------------------- | ------- | -------- | ------------------------------------------------------------------ |
| `id`                | string  | yes      | Mission uuid                                                       |
| `run_id`            | string  | yes      | Run uuid (from `mission_status` or `mission_analytics_get.recent`) |
| `step_offset`       | number  | no       | Pagination offset into the step chain (default 0)                  |
| `step_limit`        | number  | no       | Steps per page (default 25, max 100)                               |
| `include_logs`      | boolean | no       | Include decision-log lines of the child agent runs                 |
| `include_artifacts` | boolean | no       | Include artifact metadata (title/mime/size — no content)           |

**Returns:** `{ run, steps, step_count, page, logs?, artifacts?, note }`. `run` is the run header (status, business\_verdict, credits, budget snapshot/consumed/status). Each `steps` entry: `{step_position, step_type, status, business_verdict, attempt_count, agent_version, started_at, finished_at, instruction, receipt, agent_run}` — `agent_run` is `{id, status, duration_sec, cost_usd, saved_usd, input_text, tokens_in, tokens_out}` or `null`. `page` is `{offset, limit, returned}`. `logs`/`artifacts` appear only when the matching flag is set.

**Permissions:** read; membership-scoped.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_run_trace_get", "arguments": { "id": "<uuid>", "run_id": "<uuid>", "include_artifacts": true } } }
```

### `mission_artifact_get`

Read one artifact a mission produced, **with its content** (spec, report, SOP, …). Get artifact ids from `mission_run_trace_get` with `include_artifacts:true`.

| Name          | Type   | Required | Description                                                |
| ------------- | ------ | -------- | ---------------------------------------------------------- |
| `id`          | string | yes      | Mission uuid                                               |
| `artifact_id` | string | yes      | Artifact uuid                                              |
| `max_bytes`   | number | no       | Content cap in chars (default 20000, min 1000, max 100000) |

**Returns:** `{ artifact, note }`. `artifact` is `{id, run_id, agent_id, title, mime, version, created_at, size, truncated, max_bytes, content}` — `size` is the full char length, `max_bytes` the effective (clamped) cap actually applied, `truncated` true when `size > max_bytes`, and `content` the (possibly truncated) body.

**Permissions:** read; membership-scoped.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_artifact_get", "arguments": { "id": "<uuid>", "artifact_id": "<uuid>" } } }
```

### `mission_analytics_get`

Aggregated analytics over the newest 200 runs — totals (success rate, avg duration, credits), per-step failure/duration/cost, recent runs, verdict-based analytics and reliability KPIs (retry rate, approval wait time). Same aggregation as the app's Stats tab.

| Name | Type   | Required | Description  |
| ---- | ------ | -------- | ------------ |
| `id` | string | yes      | Mission uuid |

**Returns:** `{ totals, per_step, recent, analytics, reliability, window }`. `totals` = success rate / avg duration / credits; `per_step` = per-position failure/duration/cost; `recent` = the 10 newest runs; `analytics` = verdict-based aggregation; `reliability` = retry rate / approval wait KPIs; `window` describes the run set used (e.g. `"200 newest runs (max 200)"`).

**Permissions:** read; membership-scoped.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_analytics_get", "arguments": { "id": "<uuid>" } } }
```

### `mission_economics_get`

Mission economics over the newest 200 runs — total cost, realized savings, net value, ROI, profitable runs, per-day series. Same aggregation as the app's Economics tab.

| Name | Type   | Required | Description  |
| ---- | ------ | -------- | ------------ |
| `id` | string | yes      | Mission uuid |

**Returns:** `{ economics, economics_series, window, note }`. `economics` = total cost / realized savings / net value / ROI / profitable-run count; `economics_series` = the per-day series; `window` describes the run set. Cost is the stamped `agent_runs.cost_usd`; savings are stamped run snapshots (never recomputed).

**Permissions:** read; membership-scoped.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_economics_get", "arguments": { "id": "<uuid>" } } }
```

### `mission_incidents_get`

Tenant-wide agent-run incident signal for the last 24h: total, failed, attributable failures, and the top affected mission. Aggregate counts only — no rows, no agent identity.

**Parameters:** none.

**Returns:** `{ total_24h, failed_24h, failed_24h_attributable, top_mission, note }` — `top_mission` is `{id, name, failed}` (the mission with the most attributable failures) or `null`.

**Permissions:** read.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_incidents_get", "arguments": {} } }
```

### `mission_validate`

Read-only pre-flight: checks mission active, agent steps assigned + active, human approver resolution, webhook secret, credit balance — plus a mocked happy-path walk through the sequencer and the derived capability manifest. Nothing is persisted, no agent runs.

| Name | Type   | Required | Description  |
| ---- | ------ | -------- | ------------ |
| `id` | string | yes      | Mission uuid |

**Returns:** `{ ok, checks, simulated_path, manifest, note }`. `ok` is true only when every check passes; `checks` is `[{name, ok, detail}]` (mission active, agent steps assigned+active, human approver, webhook secret, credit balance); `simulated_path` is the ordered step positions of the mocked happy path; `manifest` is the derived capability manifest.

**Permissions:** read; membership-scoped.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_validate", "arguments": { "id": "<uuid>" } } }
```

### `mission_compare_versions`

Diff two mission versions from the governance history: changed mission fields plus a per-position step diff (added/removed/type/agent/config/handoff changes).

| Name        | Type   | Required | Description          |
| ----------- | ------ | -------- | -------------------- |
| `id`        | string | yes      | Mission uuid         |
| `version_a` | number | yes      | Older version number |
| `version_b` | number | yes      | Newer version number |

**Returns:** `{ a, b, project_field_changes, step_diff, note }`. `a`/`b` are `{version, kind, actor, created_at}` for each snapshot; `project_field_changes` lists which of `name/goal/status/department_id` differ; `step_diff` is `{added_positions, removed_positions, changed: [{position, changes}]}`. Snapshots are BEFORE-states with webhook secrets stripped.

**Permissions:** read; membership-scoped.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_compare_versions", "arguments": { "id": "<uuid>", "version_a": 3, "version_b": 5 } } }
```

### `mission_compare_runs`

Two runs of the same mission side-by-side: run summaries (status, verdict, credits, total cost) and a per-position step comparison with a `differs` flag per step.

| Name    | Type   | Required | Description     |
| ------- | ------ | -------- | --------------- |
| `id`    | string | yes      | Mission uuid    |
| `run_a` | string | yes      | First run uuid  |
| `run_b` | string | yes      | Second run uuid |

**Returns:** `{ a, b, per_step }`. `a`/`b` are run summaries (`{id, status, business_verdict, started_at, finished_at, total_credits, total_cost_usd, steps}`); `per_step` aligns the two runs by position: `[{position, a, b, differs}]` where each side is `{status, verdict, attempts, duration_sec, cost_usd, agent_version}` (or `null`) and `differs` flags a status/verdict/attempts/agent\_version mismatch.

**Permissions:** read; membership-scoped.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_compare_runs", "arguments": { "id": "<uuid>", "run_a": "<uuid>", "run_b": "<uuid>" } } }
```

## Writes

### `mission_create`

Create a mission (you become owner + lead). Three modes:

1. **Explicit steps** — pass `steps[]`, validated against the engine contract; agent steps may only reference agents visible to you.
2. **AI wizard** — pass `goal` text only; the wizard proposes a plan from your existing agents.
3. **Template** — pass `template_slug` + `assignments` (see `mission_templates`); every agent slot needs an agent uuid, user slots are optional.

| Name            | Type   | Required            | Description                                                           |
| --------------- | ------ | ------------------- | --------------------------------------------------------------------- |
| `name`          | string | with explicit steps | Mission name                                                          |
| `goal`          | string | mode 2              | Goal text — triggers the AI wizard when `steps` is omitted            |
| `steps`         | array  | mode 1              | `[{step_type, config, handoff_prompt?, on_fail?}]` (max 20)           |
| `department_id` | string | no                  | Department uuid                                                       |
| `template_slug` | string | mode 3              | Built-in template slug                                                |
| `assignments`   | object | mode 3              | `{agents: {<slot>: '<agent uuid>'}, users?: {<slot>: '<user uuid>'}}` |

**Returns:** `{ ok:true, project, steps, note }`. `project` is the created mission row (id, name, goal, owner, …); `steps` echoes the resolved plan as `[{position, step_type, config}]`. Validation and mode errors return `{ error }`.

**Permissions:** write; creator becomes owner + lead.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_create", "arguments": {
  "name": "Weekly lead digest",
  "steps": [
    { "step_type": "agent", "config": { "agent_id": "<uuid>" } },
    { "step_type": "human", "config": { "instruction": "Review the digest", "kind": "approve" } },
    { "step_type": "notify", "config": { "message": "Digest published." } }
  ]
} } }
```

### `mission_update`

Merge-patch a mission — only supplied fields change (steps and members are never touched here). `trigger_config` is a section-level merge: `schedule {enabled, cron '5-field', timezone}` auto-starts runs on the cron; `webhook {enabled, secret (16-128 chars)}` makes `POST /api/webhooks/inbound/<secret>` start a run (the payload lands in run context). A paused mission never auto-starts.

| Name             | Type   | Required | Description                                             |
| ---------------- | ------ | -------- | ------------------------------------------------------- |
| `id`             | string | yes      | Mission uuid                                            |
| `name`           | string | no       | Rename                                                  |
| `goal`           | string | no       | Goal text                                               |
| `status`         | string | no       | `active` \| `paused`                                    |
| `department_id`  | string | no       | Department uuid                                         |
| `trigger_config` | object | no       | `{schedule?, webhook?}` — only supplied sections change |

**Returns:** `{ ok:true, project }` — `project` is the patched row projected to `{id, name, goal, status, department_id, owner_user_id}`.

**Permissions:** write; owner or lead only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_update", "arguments": {
  "id": "<uuid>",
  "trigger_config": { "schedule": { "enabled": true, "cron": "0 9 * * 1", "timezone": "Europe/Zurich" } }
} } }
```

### `mission_steps_update`

Edit the step plan of an existing mission. Actions: `list` (read the plan) · `add` (append one validated step) · `update` (merge-patch one step; config re-validated) · `remove` (delete one step) · `reorder` (bulk positions). Mutations are refused while a run is active.

| Name             | Type   | Required              | Description                                                           |
| ---------------- | ------ | --------------------- | --------------------------------------------------------------------- |
| `id`             | string | yes                   | Mission uuid                                                          |
| `action`         | string | no                    | `list` \| `add` \| `update` \| `remove` \| `reorder` (default `list`) |
| `step`           | object | for `add`             | `{step_type, config, handoff_prompt?, on_fail?}`                      |
| `step_id`        | string | for `update`/`remove` | Step uuid (see action `list`)                                         |
| `config`         | object | for `update`          | Replacement config (re-validated)                                     |
| `handoff_prompt` | string | for `update`          | Replacement handoff prompt                                            |
| `on_fail`        | object | for `update`          | Replacement on-fail policy                                            |
| `order`          | array  | for `reorder`         | `[{id: '<step uuid>', position: 1}, ...]`                             |

**Returns:** by action — `list` → `{ ok:true, steps: [{id, position, step_type, config, handoff_prompt, on_fail}] }`; `add` → `{ ok:true, step, note }` (the inserted row, appended at the end); `update` → `{ ok:true, step }` (the patched row); `remove`/`reorder` → `{ ok:true }`. Mutations while a run is active return `{ error }`.

**Permissions:** write; owner or lead only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_steps_update", "arguments": {
  "id": "<uuid>",
  "action": "add",
  "step": { "step_type": "notify", "config": { "message": "Run finished." } }
} } }
```

### `mission_members_update`

Add/update or remove a mission member. `add` upserts the member with a role (`lead` | `member` | `viewer`, default `member`); `remove` deletes them. The target user must belong to this tenant.

| Name      | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `id`      | string | yes      | Mission uuid                      |
| `action`  | string | yes      | `add` \| `remove`                 |
| `user_id` | string | yes      | Target user uuid                  |
| `role`    | string | no       | Role for `add` (default `member`) |

**Returns:** `add` → `{ ok:true, action:"add", member: {user_id, role} }`; `remove` → `{ ok:true, action:"remove", user_id }`. A user outside this tenant returns `{ error }`.

**Permissions:** write; owner or lead only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_members_update", "arguments": {
  "id": "<uuid>", "action": "add", "user_id": "<uuid>", "role": "member"
} } }
```

## Running & approving

### `mission_run`

Start a run of the mission's step sequence. At most **one active run per mission** — starting while a run is active returns a clean conflict error. Track progress with `mission_status`.

| Name | Type   | Required | Description  |
| ---- | ------ | -------- | ------------ |
| `id` | string | yes      | Mission uuid |

**Returns:** `{ ok:true, project_run_id, note }`. Starting while a run is active returns a conflict `{ error, status }`.

**Permissions:** write; owner or lead only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_run", "arguments": { "id": "<uuid>" } } }
```

### `mission_approve_step`

Decide the mission's currently awaiting human step (approve or reject). **This is the human gate — only call it when the human user explicitly decided.** Reject stops the run.

| Name       | Type   | Required | Description                                              |
| ---------- | ------ | -------- | -------------------------------------------------------- |
| `id`       | string | yes      | Mission uuid                                             |
| `decision` | string | yes      | `approve` \| `reject`                                    |
| `input`    | string | no       | Optional human input passed to the step (`kind:'input'`) |

**Returns:** `{ ok:true, project_run_id, decision, run_status? }` — `decision` echoes `approve`/`reject`; `run_status` is present when the decision changed the run's lifecycle.

**Permissions:** write; the step's designated approver, the mission owner, or a lead member.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_approve_step", "arguments": { "id": "<uuid>", "decision": "approve" } } }
```

## Runtime control (human-gated)

All four tools follow the same pattern: call **without** `confirm` first to get a `would` block (mission name, run id, run status, effect); show it to the human; re-call with `confirm:true` only once they decided.

### `mission_cancel`

Cancel the currently **active** run. The running step finishes, then the chain stops. **Terminal** — a canceled run can never be resumed (use `mission_pause` if you want it resumable). Returns "No active run for this mission" when nothing is running.

| Name      | Type    | Required | Description                       |
| --------- | ------- | -------- | --------------------------------- |
| `id`      | string  | yes      | Mission uuid                      |
| `confirm` | boolean | no       | Must be `true` to actually cancel |

**Returns:** without `confirm` → `{ error, requires_confirmation:true, would, note }` (nothing changed); with `confirm:true` → `{ ok:true, project_run_id, status:"canceled" }`. No active run → `{ error: "No active run for this mission" }`.

**Permissions:** write; owner or lead only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_cancel", "arguments": { "id": "<uuid>", "confirm": true } } }
```

### `mission_pause`

Pause the currently **active** run. The running step finishes, then nothing further dispatches — reversible with `mission_resume`. Only a `running` run can be paused.

| Name      | Type    | Required | Description                      |
| --------- | ------- | -------- | -------------------------------- |
| `id`      | string  | yes      | Mission uuid                     |
| `confirm` | boolean | no       | Must be `true` to actually pause |

**Returns:** without `confirm` → `{ error, requires_confirmation:true, would, note }`; with `confirm:true` → `{ ok:true, project_run_id, status:"paused" }`. Only a `running` run can be paused.

**Permissions:** write; owner or lead only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_pause", "arguments": { "id": "<uuid>", "confirm": true } } }
```

### `mission_resume`

Resume the **paused** run: it flips back to `running` and continues from the first non-success step, never from the top. Only a `paused` run can be resumed.

| Name      | Type    | Required | Description                       |
| --------- | ------- | -------- | --------------------------------- |
| `id`      | string  | yes      | Mission uuid                      |
| `confirm` | boolean | no       | Must be `true` to actually resume |

**Returns:** without `confirm` → `{ error, requires_confirmation:true, would, note }`; with `confirm:true` → `{ ok:true, project_run_id, status:"running" }`. Only a `paused` run can be resumed.

**Permissions:** write; owner or lead only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_resume", "arguments": { "id": "<uuid>", "confirm": true } } }
```

### `mission_budget_increase`

Raise the **active** run's credit budget by `add_credits` (integer 1–1000). Audited (who, role, old/new cap, reason) and optimistically locked — a concurrent top-up returns a retry conflict. If the run was parked on a budget block, the raise clears it and the sequence resumes (`resumed` in the response). Spends real credits.

| Name          | Type    | Required | Description                                 |
| ------------- | ------- | -------- | ------------------------------------------- |
| `id`          | string  | yes      | Mission uuid                                |
| `add_credits` | number  | yes      | Credits to add (integer, 1–1000)            |
| `reason`      | string  | no       | Justification, stored in the audit trail    |
| `confirm`     | boolean | no       | Must be `true` to actually raise the budget |

**Returns:** without `confirm` → `{ error, requires_confirmation:true, would, note }` (the `would` block includes `add_credits` and `reason`); with `confirm:true` → `{ ok:true, project_run_id, budget, resumed }` — `budget` is the new cap and `resumed` is true when the raise cleared a budget block and the sequence continued.

**Permissions:** write; owner or lead only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_budget_increase", "arguments": {
  "id": "<uuid>", "add_credits": 50, "reason": "Long research run", "confirm": true
} } }
```

## Drafts (staged edits)

A **draft** is a pending copy of the mission config (name/goal/department + full step list). Runs keep using the published config until the draft is published.

### `mission_draft_get`

Get the mission's pending draft, or `null` when none exists.

| Name | Type   | Required | Description  |
| ---- | ------ | -------- | ------------ |
| `id` | string | yes      | Mission uuid |

**Returns:** `{ draft }` — the pending draft object (name/goal/department + full step list, with `base_version`), or `{ draft: null }` when none exists.

**Permissions:** read; membership-scoped.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_draft_get", "arguments": { "id": "<uuid>" } } }
```

### `mission_draft_create`

Cut a draft from the current live config. Fails if a draft already exists (update or discard it first).

| Name | Type   | Required | Description  |
| ---- | ------ | -------- | ------------ |
| `id` | string | yes      | Mission uuid |

**Returns:** `{ draft }` — the newly cut draft. If one already exists → `{ error, code }` (update or discard it first).

**Permissions:** write; owner or lead only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_draft_create", "arguments": { "id": "<uuid>" } } }
```

### `mission_draft_update`

Merge-patch the draft: mission fields and/or a **full replacement** step list (max 20, same engine contract and agent-visibility gate as `mission_create`). Steps may carry `output_schema` / `step_key`. Nothing is published.

| Name      | Type   | Required | Description                                                                                         |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `id`      | string | yes      | Mission uuid                                                                                        |
| `project` | object | no       | `{name?, goal?, department_id?}` — only supplied fields change                                      |
| `steps`   | array  | no       | Full replacement plan `[{step_type, config, handoff_prompt?, on_fail?, output_schema?, step_key?}]` |

**Returns:** `{ draft }` — the merged draft after the patch. Validation failures (bad step, invisible agent) → `{ error }`; conflict → `{ error, code }`.

**Permissions:** write; owner or lead only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_draft_update", "arguments": {
  "id": "<uuid>",
  "project": { "goal": "Refined weekly digest" },
  "steps": [ { "step_type": "agent", "config": { "agent_id": "<uuid>" } } ]
} } }
```

### `mission_change_proposal_preview`

What would publishing the current draft **change**? Diffs the draft against the live mission: per-field changes and added/removed/modified steps (with the exact step fields that differ). Also flags a **stale** draft — one cut before someone else published. Read-only.

| Name | Type   | Required | Description  |
| ---- | ------ | -------- | ------------ |
| `id` | string | yes      | Mission uuid |

**Returns:** `{ has_changes, stale, base_version, current_version, diff, note }`. `diff` holds per-field changes and added/removed/modified steps; `stale:true` means the mission changed since the draft was cut (publishing would overwrite that change). No draft → `{ error }`.

**Permissions:** read; membership-scoped.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_change_proposal_preview", "arguments": { "id": "<uuid>" } } }
```

### `mission_draft_discard`

Discard the pending draft — staged changes are lost, the live mission is untouched.

| Name | Type   | Required | Description  |
| ---- | ------ | -------- | ------------ |
| `id` | string | yes      | Mission uuid |

**Returns:** `{ ok:true }` on discard; `{ error, code }` if there was nothing to discard.

**Permissions:** write; owner or lead only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_draft_discard", "arguments": { "id": "<uuid>" } } }
```

### `mission_draft_publish`

Publish the draft onto the live config: the before state is version-captured, then the mission fields + step list are replaced and the draft is cleared. Refuses while a run is active, and refuses a stale draft unless `force:true`.

| Name    | Type    | Required | Description                                                      |
| ------- | ------- | -------- | ---------------------------------------------------------------- |
| `id`    | string  | yes      | Mission uuid                                                     |
| `force` | boolean | no       | Publish even if the draft is stale (overwrites newer live edits) |

**Returns:** `{ ok:true, published_version }` — the new live version number after the draft's fields + step list replaced the live config and the draft was cleared. Refused while a run is active, or on a stale draft without `force:true` → `{ error, code }`.

**Permissions:** write; owner or lead only.

```json theme={null}
{ "method": "tools/call", "params": { "name": "mission_draft_publish", "arguments": { "id": "<uuid>" } } }
```