Task Tools

Tools for creating, claiming, and managing the task lifecycle.

Task States

backlog ──► todo ──► in_progress ──► in_review ──► completed
              ▲           │               │
              │           ▼               ▼
              ├─── failed ◄┘          todo (bounce)
              ├─── blocked
              ├─── cancelled
              └─── skipped

Priorities: urgent | high | medium | low | none

---

core_create_task

Create a new task. Returns the created task including its assigned task_id.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
run_id	UUID	✓	Run that created this task
agent_id	UUID	✓	Creating agent
title	string	✓	Task title (max 512 chars)
task_id	UUID		Explicit task ID (generated if omitted)
parent_id	UUID		Parent task for hierarchical grouping
depends_on	UUID[]		Task IDs this task depends on (max 256)
detail	string		Full markdown description (max 8000 chars)
status	string		Initial status (default: backlog)
priority	string		urgent, high, medium, low, or none (default)
order_index	number		Sort order within a list
assigned_to	UUID		Agent to assign immediately
meta_json	object		Arbitrary metadata

---

core_get_task

Retrieve a task by ID including current status, lock state, and metadata.

Parameter	Type	Required	Description
task_id	UUID	✓	Task UUID

---

core_claim_task

Acquire an advisory lock on a task. Safe to call concurrently — only one agent wins. Does not change task status.

Parameter	Type	Required	Description
task_id	UUID	✓	Task to claim
agent_id	UUID	✓	Claiming agent
note	string		Optional claim note (max 4000)

Returns { claimed: true } on success, { claimed: false } if already locked by another agent.

---

core_claim_and_start_task

Atomic claim + advisory lock + transition to in_progress. Preferred over separate core_claim_task + core_transition_task calls.

Parameter	Type	Required	Description
task_id	UUID	✓	Task to claim and start
agent_id	UUID	✓	Claiming agent
claim_note	string		Note for the claim event (max 4000)
start_note	string		Note for the status transition (max 4000)

---

core_transition_task

Move a task to a new lifecycle state. Enforces the state machine — invalid transitions are rejected.

Parameter	Type	Required	Description
task_id	UUID	✓	Task to transition
agent_id	UUID	✓	Agent performing the transition
to_status	string	✓	Target status (see state machine above)
expected_from_status	string		Guard: fail if current status differs
note	string		Transition note appended to history (max 4000)
release_lock	boolean		Release advisory lock alongside transition (default: false)

Valid transitions by source state:

From	Allowed transitions
backlog	todo, cancelled, skipped
todo	in_progress, blocked, cancelled, skipped
in_progress	in_review, todo, failed, blocked, cancelled
in_review	completed, todo, in_review, failed, cancelled
completed	todo
failed	todo, backlog, cancelled
blocked	todo, backlog, cancelled
cancelled	backlog, todo
skipped	backlog, todo

---

core_update_task

Update task metadata, priority, assignment, or order. Does not change status (use core_transition_task for that).

Parameter	Type	Required	Description
task_id	UUID	✓	Task to update
agent_id	UUID	✓	Agent making the update
assigned_to	UUID/null		Reassign or unassign (null to unassign)
priority	string		New priority
order_index	number/null		New sort position
meta_json	object		Metadata to merge or replace
merge_meta	boolean		Merge meta_json into existing (default: true). False replaces.
note	string		Update note (max 4000)

---

core_list_tasks

Query tasks with filtering and full-text title search.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
status	string[]		Filter to one or more statuses
priority	string[]		Filter to one or more priorities
assigned_to	UUID		Filter by assignee
title_search	string		Substring search on task title (max 256)
limit	number		Maximum results (default: 20, max: 1000)

---

core_release_task_lock

Release an advisory lock on a task. Use when an agent finishes or yields without transitioning state.

Parameter	Type	Required	Description
task_id	UUID	✓	Task to unlock
agent_id	UUID	✓	Agent releasing the lock
note	string		Release note (max 4000)

---

core_recover_task

Force a stuck task into a recoverable state. Used for tasks that failed, timed out, or have orphaned locks. Bypasses normal transition guards.

Parameter	Type	Required	Description
task_id	UUID	✓	Task to recover
agent_id	UUID	✓	Agent performing recovery
to_status	string	✓	Recovery target: todo, failed, or in_review
note	string	✓	Recovery reason (required, max 4000)

---

post_task_message

Append a message to a task's thread. Used for inter-agent communication, inline notes, and structured log entries.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
task_id	UUID	✓	Target task
agent_id	UUID	✓	Posting agent
body	string	✓	Message content (max 8000 chars)
kind	string		message (default), note, or log
tags	string[]		Searchable tags (max 32)
meta	object		Arbitrary metadata

---

list_task_messages

List messages on a task thread in chronological order.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
task_id	UUID	✓	Target task
limit	number		Maximum results (default: 50, max: 200)