---
title: task operations
---

The exact fields each `task.*` operation takes and returns.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Every op is `POST /v1/<op>` over HTTP and the MCP tool `loom_<op>`. The identity fields (`org`, `namespace`, `agent`, `user_id`, `session_id`) are filled from the token and the MCP session when a transport can; for an HTTP call with no token on a single-user server, the install's org on every op but `code.*` and `tracker.*` (which keep their plane's), and on [some ops](/reference/http-api#request) its namespace and agent; see [identities and namespaces](/concepts/identities-and-namespaces). The [operations index](/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

<!-- prettier-ignore-start -->

## `task.accept`

Accept a triaged task into the inbox's backlog (owner side), optionally setting priority and constraints.

`POST /v1/task.accept` · MCP `loom_task_accept` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The `triage` task to accept; its poster may not accept it (403). |
| `priority` | `int \| None` | `None` | Optional edits the approver makes while accepting. |
| `constraints` | `str \| None` | `None` | Text stored in the brief as `constraints`, replacing any there; None leaves the brief alone. |
| `note` | `str` | `''` | Free text stored on the `accepted` event. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the transition. |
| `seq` | `int` | The seq of the event this call wrote. |

## `task.block`

Mark a task blocked, releasing its lease, with the reason and what it is blocked on.

`POST /v1/task.block` · MCP `loom_task_block` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The `in_progress` task this owner write addresses. |
| `fence` | `int` | required | The fence token the claim returned; a stale one (the lease moved on) answers 409. |
| `reason` | `str` | required | Why the task cannot proceed; stored on the row and the event. |
| `blocked_on` | `Literal['sender', 'human', 'external']` | `'human'` | Who must act: `sender` (the poster may then unblock it), `human` or `external`. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the transition. |
| `seq` | `int` | The seq of the event this call wrote. |

## `task.cancel`

A transition anyone entitled may make, with a reason; ``fence`` is required only when the caller is the current owner of an in_progress task.

`POST /v1/task.cancel` · MCP `loom_task_cancel` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The task to move: an unfinished one, or a failed, wont_do or cancelled one for `task.reopen`. |
| `reason` | `str` | required | Why; stored on the row and the event. |
| `fence` | `int \| None` | `None` | The claim's fence, checked against an `in_progress` task when given; None skips the check. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the transition. |
| `seq` | `int` | The seq of the event this call wrote. |

## `task.claim`

Claim a todo task under a lease; the returned fence guards every later progress, block or finish.

`POST /v1/task.claim` · MCP `loom_task_claim` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The `todo` task to claim; one whose `not_before` is still ahead answers 409. |
| `lease_seconds` | `int \| None` | `None` | Lease length; None uses the inbox's `default_lease_seconds`. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the transition. |
| `seq` | `int` | The seq of the event this call wrote. |

## `task.complete`

WHAT: Finish a task you claimed: pass the fence from task.pull and an outcome (links, ids, a short result).

`POST /v1/task.complete` · MCP `loom_task_complete` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The `in_progress` task this owner write addresses. |
| `fence` | `int` | required | The fence token the claim returned; a stale one (the lease moved on) answers 409. |
| `outcome` | `dict[str, Any]` | *(computed)* | The result as a JSON object, stored on the task. |
| `note` | `str` | `''` | Free text stored on the `done` event. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the transition. |
| `seq` | `int` | The seq of the event this call wrote. |

## `task.counts`

Count tasks by status for one inbox or every inbox of a namespace.

`POST /v1/task.counts` · MCP `loom_task_counts` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `inbox` | `str \| None` | `None` | Count one inbox; None counts every inbox owned by `namespace`. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `counts` | `list[InboxCount]` | One row per (inbox, status, blocked_on) with its count and oldest `created_at`. |

## `task.create`

``namespace`` is the poster's own namespace; ``inbox`` the target.

`POST /v1/task.create` · MCP `loom_task_create` · role `writer` · idempotent · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `inbox` | `str` | required | The target inbox; one the caller may neither post to nor read answers 404. |
| `kind` | `str` | required | The task type, chosen by the poster; policies and pull filters match on it. |
| `title` | `str` | required | One-line summary shown in lists. |
| `brief` | `dict[str, Any]` | *(computed)* | The task body as a JSON object; every `require_evidence` path of the matching policy must be non-empty here (else 422). |
| `priority` | `int` | `3` | 1 (most urgent) to 4; pulls take lower numbers first, then the oldest. |
| `disclosure` | `Literal['confidential', 'internal', 'public_ok']` | `'internal'` | How sensitive the brief is: `confidential`, `internal` or `public_ok`; the inbox must list it in `accept_disclosure`. |
| `not_before` | `datetime \| None` | `None` | Pulls and claims skip the task until this time (naive = UTC); None makes it available at once. |
| `deadline` | `datetime \| None` | `None` | When the poster needs it done (naive = UTC); stored and shown, nothing enforces it. |
| `origin` | `str` | `''` | Free text naming where the task came from; stored and returned, never interpreted. |
| `parent_task_id` | `str \| None` | `None` | The task this one follows from (a task id); None for a top-level task. |
| `idempotency_key` | `str` | `''` | A retry by the same poster with the same key into the same inbox returns the first task with `created=false`; another poster's same key stores its own task; "" never deduplicates. |
| `from_subject` | `str` | `''` | Dev mode only (no token): who is posting. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task as stored, or the earlier one on an idempotent replay. |
| `created` | `bool` | False when `idempotency_key` matched an earlier task. |
| `seq` | `int` | The returned row's version; on a new task, the seq of its `created` event. |
| `next` | `str` | What happens next when the task lands in `triage` — the inbox's owner accepts it; the poster cannot, and heartbeat / complete / defer refuse a triage task. "" when it landed `todo`, so an agent reads what to do instead of learning it from… |

## `task.defer`

WHAT: Put a claimed task back with a resume_at; the sweeper returns it to the queue at that time.

`POST /v1/task.defer` · MCP `loom_task_defer` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The `in_progress` task this owner write addresses. |
| `fence` | `int` | required | The fence token the claim returned; a stale one (the lease moved on) answers 409. |
| `reason` | `str` | required | Why the task is parked; stored on the row and the event. |
| `resume_at` | `datetime \| None` | `None` | When the sweeper returns it to `todo`; None parks it until `task.resume`. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the transition. |
| `seq` | `int` | The seq of the event this call wrote. |

## `task.fail`

WHAT: Mark a claimed task failed with a reason; the owner side may reopen it, and the inbox's max_attempts decides when it is blocked on a human instead.

`POST /v1/task.fail` · MCP `loom_task_fail` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The `in_progress` task this owner write addresses. |
| `fence` | `int` | required | The fence token the claim returned; a stale one (the lease moved on) answers 409. |
| `reason` | `str` | required | Why it failed; stored on the row and the event. |
| `outcome` | `dict[str, Any]` | *(computed)* | Any partial result as a JSON object, stored on the task. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the transition. |
| `seq` | `int` | The seq of the event this call wrote. |

## `task.get`

One task by `task_id`: its state, lease, poster, result and history.

`POST /v1/task.get` · MCP `loom_task_get` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The task to read. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `found` | `bool` | False when the task does not exist or the caller may not read it. |
| `task` | `TaskPayload \| None` | The task; null when not found. |

## `task.heartbeat`

WHAT: Renew the lease on a task you claimed (fence from task.pull) and optionally leave a progress note.

`POST /v1/task.heartbeat` · MCP `loom_task_heartbeat` · role `writer` · idempotent · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The `in_progress` task this owner write addresses. |
| `fence` | `int` | required | The fence token the claim returned; a stale one (the lease moved on) answers 409. |
| `lease_seconds` | `int \| None` | `None` | Extend the lease this many seconds from now; None uses the inbox default. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the transition. |
| `seq` | `int` | The seq of the event this call wrote. |

## `task.history`

Return a task's event history (posted, accepted, claimed, progress, finished, ...).

`POST /v1/task.history` · MCP `loom_task_history` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The task whose events to read. |
| `limit` | `int` | `200` | At most this many events, 1-1000, oldest first. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `found` | `bool` | False when the task does not exist or the caller may not read it. |
| `events` | `list[TaskEventPayload]` | The task's events in seq order. |

## `task.list`

Tasks in ``inbox`` (owner side) or, with ``posted_by_me``, the tasks the caller posted anywhere in the org.

`POST /v1/task.list` · MCP `loom_task_list` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `inbox` | `str \| None` | `None` | The inbox to list (owner side); required unless `posted_by_me`. |
| `posted_by_me` | `bool` | `False` | True lists the caller's own posts across the org; `inbox`, `posted_by` and `owner` are then ignored. |
| `posted_by` | `str \| None` | `None` | Owner side: the tasks one poster (subject or agent) sent to ``inbox`` — the track record shown beside a triage decision. |
| `statuses` | `list[Literal['triage', 'todo', 'in_progress', 'blocked', 'deferred', 'done', 'wont_do', 'failed', 'cancelled']]` | *(computed)* | Only these statuses; empty lists every status. |
| `kinds` | `list[str]` | *(computed)* | Only these kinds; empty lists every kind. |
| `owner` | `str \| None` | `None` | Only tasks currently claimed by this agent. |
| `limit` | `int` | `100` | At most this many rows, 1-500; `truncated` says more matched. |
| `fields` | `list[str]` | *(computed)* | Columns to return per row (identity columns always ride along, unknown names are dropped); empty returns full task payloads. |
| `newest_first` | `bool` | `False` | Newest first instead of the work-queue order. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `tasks` | `list[dict[str, Any]]` | One object per task, by priority then age unless `newest_first`. |
| `truncated` | `bool` | True when more tasks matched than `limit`. |

## `task.progress`

Record a progress note on a claimed task without extending its lease.

`POST /v1/task.progress` · MCP `loom_task_progress` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The `in_progress` task this owner write addresses. |
| `fence` | `int` | required | The fence token the claim returned; a stale one (the lease moved on) answers 409. |
| `note` | `str` | required | Progress text recorded on a `progress` event; the lease is not extended. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the transition. |
| `seq` | `int` | The seq of the event this call wrote. |

## `task.pull`

``namespace`` is the inbox's owner namespace; the caller must be a writer there.

`POST /v1/task.pull` · MCP `loom_task_pull` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `inbox` | `str` | required | The inbox to pull from. |
| `kinds` | `list[str]` | *(computed)* | Only tasks of these kinds; empty takes every kind. |
| `limit` | `int` | `1` | At most this many tasks per call, 1-20. |
| `wait_seconds` | `int` | `0` | Seconds to long-poll while nothing is available, up to 30; 0 returns at once. |
| `lease_seconds` | `int \| None` | `None` | Lease length of each claim; None uses the inbox's `default_lease_seconds`. |
| `status` | `Literal['todo', 'triage']` | `'todo'` | `todo` claims tasks under a lease; `triage` lists review items without claiming. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `tasks` | `list[TaskPayload]` | The tasks claimed (or listed, for `triage`), by priority then age; empty when nothing arrived in time. |
| `waited_ms` | `int` | Milliseconds the call spent, long-poll wait included. |
| `backend` | `str` | The lease arbiter that took the claims: `keeper` or `log`. |
| `note` | `str` | An empty todo pull says how many wait in triage. |

## `task.reassign`

Owner side: cancel here, re-post into another inbox as a child task (the destination's trust policy applies to the original poster).

`POST /v1/task.reassign` · MCP `loom_task_reassign` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The unfinished task to move; it is cancelled in its current inbox. |
| `to_inbox` | `str` | required | The destination; the caller must be able to post to it (as for task.create), it must accept the task's disclosure, and its policy for the original poster decides `todo` or `triage`. |
| `reason` | `str` | required | Why; stored on both the cancelled task and the replacement. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The original task, now `cancelled`. |
| `replacement` | `TaskPayload` | The new task in `to_inbox`; its `parent_task_id` is the original. |

## `task.reopen`

A transition anyone entitled may make, with a reason; ``fence`` is required only when the caller is the current owner of an in_progress task.

`POST /v1/task.reopen` · MCP `loom_task_reopen` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The task to move: an unfinished one, or a failed, wont_do or cancelled one for `task.reopen`. |
| `reason` | `str` | required | Why; stored on the row and the event. |
| `fence` | `int \| None` | `None` | The claim's fence, checked against an `in_progress` task when given; None skips the check. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the transition. |
| `seq` | `int` | The seq of the event this call wrote. |

## `task.resume`

A deferred task back to ``todo`` now, ahead of its ``resume_at``.

`POST /v1/task.resume` · MCP `loom_task_resume` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The `deferred` task to return to `todo`. |
| `note` | `str` | `''` | Free text stored on the `resumed` event. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the transition. |
| `seq` | `int` | The seq of the event this call wrote. |

## `task.unblock`

Owner side, or the poster when the task is blocked on the sender.

`POST /v1/task.unblock` · MCP `loom_task_unblock` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The `blocked` task to return to `todo`. |
| `note` | `str` | `''` | Free text stored on the `unblocked` event. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the transition. |
| `seq` | `int` | The seq of the event this call wrote. |

## `task.update`

Edit the brief.

`POST /v1/task.update` · MCP `loom_task_update` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The task to edit; allowed while it is `triage`, `todo`, `blocked` or `deferred`. |
| `if_match_version` | `int` | required | The task `version` the edit is based on; a mismatch answers 409 with the current row. |
| `title` | `str \| None` | `None` | New title; None keeps it. |
| `brief` | `dict[str, Any] \| None` | `None` | Replaces the whole brief; None keeps it. |
| `priority` | `int \| None` | `None` | New priority, 1-4; None keeps it. |
| `deadline` | `datetime \| None` | `None` | New deadline; None keeps it (see `clear_deadline`). |
| `not_before` | `datetime \| None` | `None` | New earliest start; None keeps it (see `clear_not_before`). |
| `clear_deadline` | `bool` | `False` | True removes the deadline; wins over `deadline`. |
| `clear_not_before` | `bool` | `False` | True removes `not_before`; wins over `not_before`. |
| `note` | `str` | `''` | Free text stored on the `updated` event; a note alone is a valid update. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the edit. |
| `seq` | `int` | The seq of the `updated` event. |
| `conflict` | `bool` | Always false: a version mismatch answers 409 with the current row instead. |

## `task.updates`

The sender's cursor: events on tasks this caller posted (or, with ``inbox``, every event in an inbox the caller owns) after ``since_seq``.

`POST /v1/task.updates` · MCP `loom_task_updates` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `since_seq` | `int` | `0` | Return events after this seq: pass the previous `next_seq`; 0 starts at the beginning. |
| `inbox` | `str \| None` | `None` | Read every event of this inbox (one the caller can read) instead of the events on the caller's own posts. |
| `limit` | `int` | `200` | At most this many events per call, 1-1000. |
| `wait_seconds` | `int` | `0` | Seconds to long-poll while no event is available, up to 30; 0 returns at once. |
| `from_subject` | `str` | `''` | Dev mode only (no token): whose posts to follow; a token's subject wins. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `events` | `list[TaskEventPayload]` | Events in seq order; the last few seconds are held back so a row still landing on another replica is not skipped. |
| `next_seq` | `int` | The cursor for the next call: the last event's seq, or `since_seq` when none. |
| `waited_ms` | `int` | Milliseconds the call spent, long-poll wait included. |

## `task.wont_do`

A transition anyone entitled may make, with a reason; ``fence`` is required only when the caller is the current owner of an in_progress task.

`POST /v1/task.wont_do` · MCP `loom_task_wont_do` · role `writer` · write · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `task_id` | `str` | required | The task to move: an unfinished one, or a failed, wont_do or cancelled one for `task.reopen`. |
| `reason` | `str` | required | Why; stored on the row and the event. |
| `fence` | `int \| None` | `None` | The claim's fence, checked against an `in_progress` task when given; None skips the check. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `task` | `TaskPayload` | The task after the transition. |
| `seq` | `int` | The seq of the event this call wrote. |

<!-- prettier-ignore-end -->
