task operations

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

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 its namespace and agent; see identities and namespaces. The operations index explains role, kind and the MCP all listing. Unknown input fields are served and named in ignored_args.

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 and extend 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.