# Durable work and settlement

Bind a run to a unit of durable work that outlives the session, continue it later, and understand what settlement mode adds.

Most agents answer a request and are done. Some serve a piece of work that has its own identity:
an invoice to reconcile, a case to close. Durable work gives that unit a record the platform
manages, so a later session can continue it and its outcome is settled once.

> **Availability:** Durable work and settlement are enabled per tenant. A `settlement`-mode version fails session activation where the boundary is unavailable rather than running without it. See [What is available where](/reference/availability).

- `settlement_mode` in the manifest is `standard`, `work`, or `settlement`, in that order of
  strength. Missing means `standard`.
- In `work` and `settlement` modes, the first run in a new session declares the work it serves:
  `work.subject` to open new work, or `work.work_id` to continue existing work.
- The admitted run returns `settlement_work_id`. Store it if another session may continue the
  work.
- Work ends in one of two ways decided by the platform, never by a person editing its state.

## Declare the mode

```yaml title="agent.yaml"
settlement_mode: work
```

| Mode | Behaviour |
|---|---|
| `standard` | The existing behaviour: runs are units of execution and nothing more. |
| `work` | The agent produces durable work records. Runs bind to work. |
| `settlement` | As `work`, and the session must establish the managed worker and proxy boundary or fail activation, so every effect the work dispatches is enforced through policy. |

## Open or continue work

```json title="POST /v1/sessions/{session_id}/runs"
{
  "input": { "prompt": "Reconcile invoice INV-1842." },
  "work": {
    "subject": "invoice:INV-1842",
    "contract_ref": "billing/reconciliation",
    "contract_version": "2026-09"
  },
  "idempotency_key": "invoice-1842-attempt-1"
}
```

Send either `subject` or `work_id`, never both. When opening work, `contract_ref` and
`contract_version` may name a contract and must be sent together; later requests may omit the
pair or restate it exactly, but cannot add or change it. The response's `settlement_work_id` is
the handle another session uses with `work.work_id`.

A work item has at most one live run at a time; a second run against the same work while one is
live returns `409` with `work_has_live_run`.

## What settlement adds

In `settlement` mode the effects a run dispatches to other systems, not the messages it exchanges,
are the things being settled. Each is authorized through the policy facade before it happens and
recorded as it happens, and the work's outcome is decided from those records. Work ends two ways:
it settles, or it is abandoned by the platform's rules. A person does not end it by hand, which is
what makes the record trustworthy.

## Where to go next

- [Sessions and runs](/concepts/sessions-and-runs): where work sits beside sessions and runs.
- [Start a run](/api/runs/start-run): the request fields.
- [Agent manifest](/reference/agent-manifest#state-warm-starts-and-sessions): the mode field.