# Run control API

> Resolve waits, steer sessions, and apply idempotent safe-point or abort controls to exact Runs.

Every route below begins `/v1/namespaces/:namespace/agents/:agent/sessions/:session`. Controls are durable authenticated events. Supply the exact Run id and caller-stable `eventId`; do not infer current state from analytics before mutating it.

| Method | Suffix | Required body or purpose |
| --- | --- | --- |
| `POST` | `/waits/:promiseId/resolve` | `{ eventId, value }`; value must satisfy the pinned wait schema |
| `POST` | `/steers` | `{ eventId, text, data? }`; append fresh authenticated guidance |
| `POST` | `/runs/:run/pause` | `{ eventId }` or idempotency header; stop at a safe point |
| `POST` | `/runs/:run/resume` | `{ eventId }`; resume and drive dispatchable work |
| `POST` | `/runs/:run/cancel` | `{ eventId? }`; terminally stop future work |
| `POST` | `/runs/:run/interrupt` | `{ eventId, mode, payload? }`; `mode` is `safe-point` or `abort` |
| `POST` | `/runs/:run/policy` | `{ eventId, policyHash }`, `{ eventId, maxTurns }`, or `{ eventId, maxMicroUsd }` |
| `POST` | `/runs/:run/rebind` | `{ eventId, bindings }` for fixed bindings; scoped targets derive from accepted authority |
| `POST` | `/runs/:run/truncate` | `{ eventId, to, text, data? }`; move the same history head and steer |
| `POST` | `/runs/:run/branch` | `{ eventId, at, text, data? }`; create and drive a forked Run |

Abort interruption additionally requires `run:abort`. A fixed rebind supplies the complete map and cannot change the Agent’s logical model identity or leave a Tool need unsatisfied. A scoped rebind rejects caller-selected targets and resolves current assignments for the Run’s already accepted principal/customer authority.

After every operation, persist the receipt and refresh [Run detail](/docs/api/agents-and-runs.md#read). An uncertain external effect is reconciled according to the pinned Resource operation recovery contract; a control does not make blind repetition safe.