Tasks API

Tasks are the durable automation layer in the gateway. 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. When the executor is agent, the task can create a subagent thread with its own prompt, model, context policy, tool policy, and result contract. 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.

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/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.

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", "file_read"],
        "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 currently serialize as PascalCase: Draft, Scheduled, Queued, Running, Waiting, Completed, Failed, Cancelled. Many supporting enums 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

Subagents are represented by agentSpec. They are not just a UI affordance; the gateway uses the spec to create a child thread and run that child thread with bounded context and tools.

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.
`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. When a task creates a child thread, task events include child thread lineage. Clients can then show the subagent’s work in the parent task tree and can load the child conversation through Threads API and Turns API.

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, 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": [],
  "pending": [],
  "timedOut": false,
  "totalCount": 1,
  "terminalCount": 1,
  "pendingCount": 0,
  "mode": "all_terminal"
}

Wait modes are all_terminal and any_terminal. A timed-out wait does not cancel the task; it only returns control to the caller.

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/cancelled`	Run terminal updates.
`task/run/retry_scheduled`, `task/run/retry_exhausted`	Retry lifecycle updates.
`task/completed`, `task/failed`, `task/cancelled`	Task terminal updates.
`task/detached`, `task/rescheduled`, `task/paused`, `task/resumed`	Manual lifecycle 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/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 Turns API turn/timeline with 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

Policies

Reading Tasks

Events

Waiting

Cancelling And Lifecycle Changes

Agenda

Deliveries

Notifications

How Tasks Relate To Turns

Introduction

Workspace & Threads

Features

Documentation Index

​Methods

​Creating An Agent Task

​Trigger Specs

​Subagents

​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

Policies

Reading Tasks

Events

Waiting

Cancelling And Lifecycle Changes

Agenda

Deliveries

Notifications

How Tasks Relate To Turns