Tasks API

Tasks are the gateway’s durable automation layer. A task can run immediately, wait for a schedule, repeat on an interval or cron expression, depend on another task, or be triggered manually or externally. With the agent executor, it can create a subagent thread with its own prompt, model, context policy, tool policy, result contract, and review policy. Clients use the Tasks API for two different experiences: user-facing automation UI and internal agent orchestration. In both cases the gateway owns task state, run state, retries, write locks, delivery state, and the lineage between parent work and subagent threads. Collaborative Composer submissions are also represented by the task runtime. They are not a third client method: the normal turn submission creates detached task work with a frozen TaskComposerWork launch record, a child conversation, and a delivery back to the originating thread. Use the explicit Tasks API when you need to create or inspect a durable task contract; use the Threads and Turns APIs to render the conversation and the task card created by a Composer request.

Methods

Method	Params	Result	Purpose
`task/create`	`TaskCreateParams`	`TaskCreateResponse`	Create a task and its first trigger.
`task/get`	`TaskGetParams`	`TaskGetResponse`	Load one task plus triggers, runs, specs, dependencies, and locks.
`task/list`	`TaskListParams`	`TaskListResponse`	List tasks in a workspace with optional filters.
`task/tree`	`TaskTreeParams`	`TaskTreeResponse`	Load a root task with nested child tasks.
`task/events`	`TaskEventsParams`	`TaskEventsResponse`	Read durable task event history.
`task/wait`	`TaskWaitParams`	`TaskWaitResponse`	Wait for tasks or runs to reach terminal state.
`task/accept`	`TaskAcceptParams`	`TaskAcceptResponse`	Accept a pending result candidate and finalize the run.
`task/revise`	`TaskReviseParams`	`TaskReviseResponse`	Reject a pending result candidate and start a revision turn in the same child thread.
`task/cancel`	`TaskCancelParams`	`TaskCancelResponse`	Cancel a task and optionally its subtree.
`task/reschedule`	`TaskRescheduleParams`	`TaskRescheduleResponse`	Replace a task trigger.
`task/detach`	`TaskDetachParams`	`TaskDetachResponse`	Detach a child task from parent lifecycle.
`task/pause`	`TaskPauseParams`	`TaskPauseResponse`	Pause active triggers.
`task/resume`	`TaskResumeParams`	`TaskResumeResponse`	Resume paused triggers.
`task/agenda`	`TaskAgendaParams`	`TaskAgendaResponse`	Query upcoming/recent task schedule view.
`task/deliveries`	`TaskDeliveriesParams`	`TaskDeliveriesResponse`	Query task result delivery records and attempts.

crates/protocol also defines TaskUpdateParams, TaskUpdateResponse, and a task/update method constant for task-service update contracts. The current gateway JSON-RPC dispatcher does not expose task/update as a client-callable method. Task updates can still happen through the model-facing task_update tool and task service, and clients observe them through task/updated plus task/tree/changed.

Creating an agent task

task/create uses mostly camelCase payload fields. The gateway creates the task, stores the trigger, and may also create a run immediately depending on the trigger.

{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "method": "task/create",
  "params": {
    "workspaceId": "ws_000000000000000001",
    "ownerKind": "thread",
    "ownerId": "thr_000000000000000001",
    "createdByThreadId": "thr_000000000000000001",
    "createdByTurnId": "trn_000000000000000001",
    "executorKind": "agent",
    "title": "Review the protocol docs",
    "goal": "Check the protocol reference for missing methods and incorrect examples.",
    "priority": 0,
    "trigger": {
      "spec": {
        "kind": "immediate"
      }
    },
    "agentSpec": {
      "agentRole": "Reviewer",
      "agentNickname": "Protocol reviewer",
      "model": "gpt-5.1",
      "modelProvider": "openai",
      "prompt": {
        "goal": "Review the Protocol Reference section.",
        "instructions": [
          "Compare the docs with pioneer-protocol types.",
          "Report incorrect method names, payload casing, or missing lifecycle notes."
        ],
        "outputInstructions": "Return a concise Markdown review."
      },
      "contextPolicy": {
        "mode": "inherit_parent",
        "includeParentSummary": true,
        "includeArtifacts": true
      },
      "toolPolicy": {
        "allowedTools": ["grep_files", "read_file"],
        "deniedTools": [],
        "writeMode": "read_only",
        "allowedPaths": ["/Users/alexander/Code/pioneer"],
        "networkAccess": false
      },
      "resultContract": {
        "format": "markdown",
        "required": true
      },
      "depth": 1,
      "maxDepth": 2
    }
  }
}

Important create fields:

Field	Meaning
`workspaceId`	Gateway workspace that owns the task.
`ownerKind`, `ownerId`	Logical owner: `user`, `thread`, `workspace`, or `system`.
`createdByThreadId`, `createdByTurnId`	Optional lineage back to the turn that created the task.
`parentTaskId`	Optional parent for task trees and subagent orchestration.
`executorKind`	`agent`, `tool`, `workflow`, `webhook`, or `system`.
`title`, `goal`	Human-facing title and durable goal.
`priority`	Higher-level scheduling hint. Defaults to `0`.
`trigger`	When and how the task should run.
`agentSpec`	Required for agent-style subagent work.
`lifecyclePolicy`	Parent/child attachment and completion behavior.
`deliveryPolicy`	Where the result should be delivered.
`retryPolicy`, `timeoutPolicy`, `concurrencyPolicy`	Execution controls.
`metadata`	Labels and structured custom data.

Response:

{
  "task": {
    "id": "tsk_000000000000000001",
    "workspaceId": "ws_000000000000000001",
    "ownerKind": "thread",
    "ownerId": "thr_000000000000000001",
    "executorKind": "agent",
    "status": "queued",
    "title": "Review the protocol docs",
    "goal": "Check the protocol reference for missing methods and incorrect examples.",
    "priority": 0,
    "revision": 1,
    "createdAt": 1777900000,
    "updatedAt": 1777900000
  },
  "trigger": {
    "id": "trg_000000000000000001",
    "taskId": "tsk_000000000000000001",
    "status": "active",
    "spec": {
      "kind": "immediate"
    },
    "createdAt": 1777900000,
    "updatedAt": 1777900000
  },
  "run": {
    "id": "run_000000000000000001",
    "taskId": "tsk_000000000000000001",
    "runGroupId": "grp_000000000000000001",
    "attemptNumber": 1,
    "runNumber": 1,
    "status": "queued",
    "executorKind": "agent",
    "createdAt": 1777900000,
    "updatedAt": 1777900000
  },
  "agentSpec": {
    "id": "ags_000000000000000001",
    "taskId": "tsk_000000000000000001",
    "agentRole": "Reviewer",
    "agentNickname": "Protocol reviewer",
    "prompt": {
      "goal": "Review the Protocol Reference section.",
      "instructions": [],
      "outputInstructions": "Return a concise Markdown review."
    },
    "depth": 1,
    "maxDepth": 2,
    "createdAt": 1777900000,
    "updatedAt": 1777900000
  }
}

TaskStatus values serialize as snake_case: draft, scheduled, queued, running, waiting, completed, failed, cancelled. Many task payloads use camelCase field names while enum values use snake_case, so clients should follow the generated schema rather than guessing casing.

Trigger specs

The trigger.spec object is tagged by kind.

Kind	Extra fields	Meaning
`immediate`	none	Queue as soon as the task is created.
`scheduled_at`	`scheduled_at`, optional `timezone`	Run once at a Unix timestamp.
`interval`	`interval_seconds`, optional `interval_anchor_at`	Run repeatedly on an interval.
`cron`	`cron_expr`, `timezone`	Run repeatedly from a cron expression.
`manual`	optional `allowed_actor`	Create task but wait for manual/external start.
`external`	`source`, optional `event_type`, optional `filter`	Run from an external event source.
`dependency`	`policy`	Run after other tasks satisfy a dependency policy.

Example cron trigger:

{
  "spec": {
    "kind": "cron",
    "cron_expr": "0 9 * * 1-5",
    "timezone": "Europe/Moscow"
  }
}

Dependency trigger policy uses mode values all_succeeded, any_succeeded, or all_terminal and a dependsOnTaskIds list.

Subagents

agentSpec tells the gateway to create a child thread and run it with bounded context and tools. The UI is only one way to request this work.

Field	Meaning
`agentRole`, `agentNickname`	Human-readable identity for history and task trees.
`model`, `modelProvider`	Optional model override for this subagent.
`prompt.goal`	Main objective.
`prompt.instructions`	Additional instructions.
`prompt.input`	Optional structured variables, attachments, and references.
`prompt.outputInstructions`	How the result should be returned.
`contextPolicy`	What parent context the subagent receives.
`toolPolicy`	What tools, paths, writes, and network access are allowed.
`resultContract`	Expected result format and optional schema.
`reviewPolicy`	How the subagent result candidate should be reviewed before it becomes final.
`depth`, `maxDepth`	Nesting controls for subagent trees.

Context policy modes are inherit_parent, last_n_turns, summary_only, empty, and custom. Write modes are read_only, workspace_write, scoped_write, and full_access. Result formats are text, markdown, json, and artifact. Callers usually omit reviewPolicy. The gateway applies the default parent-agent review policy to immediate attached agent tasks. Direct reviewPolicy overrides in task/create require gateway.tasks.review.allow_task_create_review_policy = true. When a task creates a child thread, task events include child thread lineage. The child thread is hidden from the normal sidebar, but clients can show the subagent’s work in the parent task tree and can load the child conversation through Threads API and Turns API.

Result review

Agent tasks can require review before a child result becomes the final run result. For attached subagent work, the default review mode is parent-agent review with explicit acceptance and five revision rounds. Review policy fields:

Field	Meaning
`mode`	`none`, `parent_agent`, `parent_agent_with_reviewers`, or `user_approval`.
`maxRevisionRounds`	Maximum number of revision turns after the initial child turn.
`requireExplicitAcceptance`	Whether a candidate must be accepted before the run succeeds.
`reviewers`	Optional reviewer specs for future review-agent or user-review flows.
`resolutionStrategy`	How multiple review decisions resolve, for example `parent_final` or `require_all_required_reviewers_then_parent`.

When a child turn finishes, the gateway creates a TaskResultCandidate. If review is required, the candidate status is pending_review, the run/execution waits for review, and task/wait can return it under reviewRequired. The parent accepts a candidate with task/accept:

{
  "jsonrpc": "2.0",
  "id": "review_accept_00000001",
  "method": "task/accept",
  "params": {
    "taskId": "tsk_000000000000000001",
    "runId": "run_000000000000000001",
    "candidateId": "trc_000000000000000001",
    "reason": "The subagent included the required file:line references and answered the task."
  }
}

Accepting creates a TaskResultReviewEvent with decision = accept, marks the candidate accepted, stores the accepted result on the run, and completes the task when its lifecycle policy allows it. The parent requests changes with task/revise:

{
  "jsonrpc": "2.0",
  "id": "review_revise_00000001",
  "method": "task/revise",
  "params": {
    "taskId": "tsk_000000000000000001",
    "runId": "run_000000000000000001",
    "candidateId": "trc_000000000000000001",
    "feedback": "Add a Revision verification section with three exact file:line references.",
    "additionalInstructions": [
      "Keep the original structure.",
      "Do not redo unrelated research."
    ]
  }
}

Revising creates a review event with decision = request_changes, marks the current candidate rejected, creates a new TaskRunTurn with kind = revision, and dispatches the same child thread again with the feedback. The next child turn produces a new candidate. TaskResultReviewEvent is an audit log rather than a snapshot of the latest state. It records reviewer kind (parent_agent, review_agent, user, runtime_auto, or system), event kind (advisory, decision, override, or system_auto), decision, feedback, optional reviewer thread/turn/user/agent ids, and the next revision turn when one is created.

Policies

Lifecycle policy controls what happens to child tasks when parent work ends:

{
  "attachment": "attached",
  "onParentCancel": "cancel",
  "onParentFailure": "detach",
  "completion": "complete_on_terminal_run"
}

Delivery policy controls where task results go:

{
  "mode": "owner_thread",
  "includeResult": true,
  "format": "summary"
}

Retry, timeout, and concurrency policies are optional, but they are what turn tasks from “run this once” into reliable automation:

{
  "retryPolicy": {
    "maxAttempts": 3,
    "backoff": "exponential",
    "initialDelaySeconds": 30,
    "maxDelaySeconds": 600,
    "retryOn": ["provider", "tool", "timeout"]
  },
  "timeoutPolicy": {
    "queueTimeoutSeconds": 300,
    "runTimeoutSeconds": 1800,
    "heartbeatTimeoutSeconds": 120
  },
  "concurrencyPolicy": {
    "key": "docs-protocol-reference",
    "maxParallelRuns": 1,
    "onConflict": "queue"
  }
}

Write locks are produced by the task runtime when a task needs exclusive write access to a workspace or path. Clients normally display them in diagnostics rather than creating them directly.

Reading tasks

Use task/get for a detail view:

{
  "jsonrpc": "2.0",
  "id": "bbbbbbbbbbbbbbbbbbbbb",
  "method": "task/get",
  "params": {
    "taskId": "tsk_000000000000000001"
  }
}

Use task/list for a workspace list:

{
  "jsonrpc": "2.0",
  "id": "ccccccccccccccccccccc",
  "method": "task/list",
  "params": {
    "workspaceId": "ws_000000000000000001",
    "ownerKind": "thread",
    "ownerId": "thr_000000000000000001",
    "status": "running",
    "limit": 50
  }
}

task/tree returns a root TaskTree with nested children. Use it when showing a delegated workflow, because a parent task can fan out into child tasks and each child can have its own run, agent spec, dependencies, write locks, and child thread lineage.

{
  "jsonrpc": "2.0",
  "id": "ddddddddddddddddddddd",
  "method": "task/tree",
  "params": {
    "taskId": "tsk_000000000000000001"
  }
}

Events

task/events returns durable task events with monotonically increasing sequence.

{
  "jsonrpc": "2.0",
  "id": "eeeeeeeeeeeeeeeeeeeee",
  "method": "task/events",
  "params": {
    "taskId": "tsk_000000000000000001",
    "afterSequence": 42
  }
}

Each event has eventType, payload, createdAt, optional runId, optional threadId, and optional turnId. The payload is tagged by kind, with variants for task creation, trigger creation, task updates, run start/completion/failure, retries, cancellation, delivery, child thread linking, depth limits, and write-lock state. Use afterSequence for incremental polling after reconnect. Live clients should also listen to task notifications.

Waiting

task/wait is useful for automation clients and for a parent agent waiting on delegated work.

{
  "jsonrpc": "2.0",
  "id": "fffffffffffffffffffff",
  "method": "task/wait",
  "params": {
    "taskIds": ["tsk_000000000000000001"],
    "runIds": [],
    "timeoutMs": 30000,
    "mode": "all_terminal",
    "returnCompleted": true,
    "returnPending": true
  }
}

Response groups terminal and pending work:

{
  "completed": [],
  "failed": [],
  "cancelled": [],
  "reviewRequired": [],
  "pending": [],
  "timedOut": false,
  "totalCount": 1,
  "terminalCount": 1,
  "pendingCount": 0,
  "reviewRequiredCount": 0,
  "mode": "all_terminal"
}

Wait modes are all_terminal, any_terminal, all_terminal_or_review_required, and any_terminal_or_review_required. A timed-out wait does not cancel the task; it only returns control to the caller. Parent-agent orchestration normally uses a review-aware wait mode. When a candidate needs a decision, reviewRequired contains the task/run item, the candidate, the review policy, revision limits, and allowed actions:

{
  "reviewRequired": [
    {
      "item": {
        "task": { "id": "tsk_000000000000000001", "status": "waiting" },
        "run": { "id": "run_000000000000000001", "status": "waiting_review" },
        "childThreadId": "thr_child_0000000001",
        "childTurnId": "trn_child_0000000001"
      },
      "candidate": {
        "id": "trc_000000000000000001",
        "status": "pending_review",
        "round": 0,
        "summary": "Found the relevant TaskService implementation."
      },
      "maxRevisionRounds": 5,
      "remainingRevisionRounds": 5,
      "allowedActions": ["task_accept", "task_revise", "task_cancel"]
    }
  ],
  "reviewRequiredCount": 1,
  "mode": "all_terminal_or_review_required"
}

If remainingRevisionRounds is 0, allowedActions omits task_revise and revisionBlockedReason explains why. The parent should then accept, cancel, or create a separate follow-up task.

Cancelling and lifecycle changes

Cancel scope controls how far cancellation propagates:

Scope	Meaning
`task_only`	Cancel only this task.
`attached_subtree`	Cancel this task and attached children. This is the default.
`full_subtree`	Cancel this task and all descendants.

{
  "jsonrpc": "2.0",
  "id": "ggggggggggggggggggggg",
  "method": "task/cancel",
  "params": {
    "taskId": "tsk_000000000000000001",
    "reason": "User cancelled from UI",
    "scope": "attached_subtree"
  }
}

Use task/pause and task/resume for scheduled or recurring tasks. Use task/reschedule to replace the trigger. Use task/detach when a child task should keep running independently of its parent.

Agenda

task/agenda is optimized for “what is coming up” and “what recently ran” screens.

{
  "jsonrpc": "2.0",
  "id": "hhhhhhhhhhhhhhhhhhhhh",
  "method": "task/agenda",
  "params": {
    "workspaceId": "ws_000000000000000001",
    "from": 1777900000,
    "to": 1778504800,
    "triggerKinds": ["cron", "interval", "scheduled_at"],
    "includePaused": true,
    "includeCompleted": false,
    "limit": 100
  }
}

Agenda items include the task, trigger, latest run, latest delivery, goal preview, next/last fire timestamps, recurring flag, delivery mode, and result/error previews.

Deliveries

Delivery records track result handoff after a run: owner thread posts, target thread posts, user notifications, and webhook attempts.

{
  "jsonrpc": "2.0",
  "id": "iiiiiiiiiiiiiiiiiiiii",
  "method": "task/deliveries",
  "params": {
    "workspaceId": "ws_000000000000000001",
    "taskId": "tsk_000000000000000001",
    "statuses": ["pending", "failed"],
    "limit": 50
  }
}

The response contains deliveries and attempts. Use it for a delivery/debug panel and for retry/error visibility in scheduled automation.

Notifications

Task notifications use the same event names as durable task events:

Event	Meaning
`task/created`, `task/scheduled`, `task/queued`	Task lifecycle entered created/scheduled/queued state.
`task/run/created`, `task/run/started`, `task/progress`	Run lifecycle and progress updates.
`task/run/completed`, `task/run/failed`, `task/run/blocked`, `task/run/cancelled`	Run terminal or recoverable blocked updates.
`task/run/retry_scheduled`, `task/run/retry_exhausted`	Retry lifecycle updates.
`task/run/thread_binding/created`	A task run was linked to its executor, reviewer, or recovery thread.
`task/run/turn/started`, `task/run/turn/completed`, `task/run/turn/failed`, `task/run/turn/blocked`	Initial, revision, recovery, and review turn lifecycle.
`task/run/entered_review`	A run has a pending result candidate and is waiting for review.
`task/result_candidate/created`, `task/result_candidate/accepted`, `task/result_candidate/rejected`, `task/result_candidate/cancelled`	Candidate lifecycle for child outputs.
`task/result_review_event/recorded`	Parent-agent, user, review-agent, runtime-auto, or system review event was recorded.
`task/revision/requested`	A review decision requested another child-thread revision turn.
`task/completed`, `task/failed`, `task/blocked`, `task/cancelled`	Task terminal or recoverable blocked updates.
`task/detached`, `task/updated`, `task/rescheduled`, `task/paused`, `task/resumed`	Manual lifecycle and editable task contract changes.
`task/tree/changed`	Parent/child structure, dependencies, or child thread linkage changed.
`task/recovered`	Runtime recovered task state.
`task/delivery/queued`, `task/delivery/started`, `task/delivery/delivered`, `task/delivery/failed`, `task/delivery/cancelled`	Result delivery lifecycle.
`task/write_lock/acquired`, `task/write_lock/extended`, `task/write_lock/released`, `task/write_lock/blocked`, `task/write_lock/expired`	Write-lock lifecycle.

Notification params include a context object with workspaceId, taskId, optional runId, optional parent/root ids, optional thread/turn ids, eventId, and sequence. Treat notifications as streaming state changes and use read methods to rebuild exact state when needed.

How tasks relate to turns

Agent turns can create tasks, tasks can create child threads, and child turns can report results back to parent tasks. For rendering a conversation that includes delegated work, combine Threads API thread/timeline/page, Turns API turn/work/page, task/tree, and task/events. For a task automation screen, use task/agenda, task/list, task/get, and task/deliveries. For an agent orchestration screen, use task/tree, task/events, and child thread links.

Introduction

Workspace & Threads

Features

Methods

Creating an agent task

Trigger specs

Subagents

Result review

Policies

Reading tasks

Events

Waiting

Cancelling and lifecycle changes

Agenda

Deliveries

Notifications

How tasks relate to turns

​Methods

​Creating an agent task

​Trigger specs

​Subagents

​Result review

​Policies

​Reading tasks

​Events

​Waiting

​Cancelling and lifecycle changes

​Agenda

​Deliveries

​Notifications

​How tasks relate to turns

Methods

Creating an agent task

Trigger specs

Subagents

Result review

Policies

Reading tasks

Events

Waiting

Cancelling and lifecycle changes

Agenda

Deliveries

Notifications

How tasks relate to turns