Turns API

A turn is one unit of assistant execution inside a thread. The client creates it with turn/start and observes progress through notifications. In Chat mode it is usually a provider call. In Agent mode it can include prompt compilation, tool calls, MCP calls, skills, task tools, subagents, retries, recovery, or a CLI-backed agent runtime.

Methods

Method	Params	Result	Purpose
`turn/start`	`TurnStartParams`	`TurnStartResponse`	Start a new turn in a thread.
`turn/cancel`	`TurnCancelParams`	`TurnCancelResponse`	Cancel or interrupt an in-progress turn.
`turn/resume`	`TurnResumeParams`	`TurnResumeResponse`	Resume a blocked turn through a recovery job.
`turn/get`	`TurnGetParams`	`TurnGetResponse`	Load one turn model.
`turn/items`	`TurnItemsParams`	`TurnItemsResponse`	Load persisted item events for one turn.
`turn/work/page`	`TurnWorkPageParams`	`TurnWorkPageResponse`	Load paginated work items inside one semantic turn work block.
`turn/work/items/get`	`TurnWorkItemsGetParams`	`TurnWorkItemsGetResponse`	Fetch changed or removed work items by id without reloading the whole page.
`turn/permission/request/respond`	`TurnPermissionRequestRespondParams`	`TurnPermissionRequestRespondResponse`	Resolve an open native tool permission request.

Starting a turn

{
  "jsonrpc": "2.0",
  "id": "ccccccccccccccccccccc",
  "method": "turn/start",
  "params": {
    "thread_id": "thr_000000000000000001",
    "turn_id": "trn_000000000000000001",
    "mode": "Agent",
    "permission_profile": {
      "mode": "supervised"
    },
    "sandbox_policy": {
      "mode": "FullAccess"
    },
    "input": [
      {
        "type": "text",
        "text": "Inspect the project and summarize the architecture.",
        "textElements": []
      }
    ],
    "capabilities": [
      {
        "id": "cap_docs",
        "label": "Documents",
        "kind": {
          "type": "skill",
          "slug": "workspace/documents",
          "sourceKind": "workspace"
        }
      },
      {
        "id": "cap_resend_send_email",
        "label": "resend / Send Email",
        "kind": {
          "type": "mcpTool",
          "serverName": "resend",
          "rawToolName": "send_email",
          "scopeKind": "workspace"
        }
      }
    ]
  }
}

Important fields:

Field	Notes
`thread_id`	Existing thread id.
`turn_id`	Client-provided id for this turn.
`input`	Array of `UserInput` items. Text, files, images, audio, video, artifacts, and mentions are represented here.
`capabilities`	Optional turn-scoped skills and MCP selections. Use this for composer-selected skills, MCP servers, and MCP tools.
`model`, `model_provider`	Optional per-turn override. If omitted, the thread model/provider is used.
`execution_backend`	Optional explicit execution backend. Use `apiProvider` for a remote model API provider, `cliAgentRuntime` for a configured CLI runtime, or `acpAgentRuntime` for an ACP runtime id.
`cli_runtime_options`	Optional runtime-specific options for CLI runtime turns, such as sandbox policy, effort, personality, summary, or whether to steer an active turn.
`permission_profile`	Optional Pioneer turn permission profile. Current modes are `full_access`, `auto_accept_edits`, and `supervised`. If omitted, the gateway defaults to `full_access`.
`sandbox_policy`	Legacy optional thread-era sandbox policy object. Current public shape is `{ "mode": "FullAccess" }`; use `permission_profile` for current turn permission and sandbox/resource behavior.
`mode`	Optional per-turn thread mode override, `Chat` or `Agent`.

Response:

{
  "turn": {
    "id": "trn_000000000000000001",
    "status": "InProgress",
    "prompt_manifest": null,
    "permission_profile": {
      "mode": "supervised",
      "source": "composer",
      "effective_policy": {
        "default_behavior": "ask",
        "file_read": "allow",
        "file_write": "ask",
        "shell_command": "ask",
        "network": "ask",
        "mcp_read": "allow",
        "mcp_write_or_unknown": "ask",
        "dynamic_skill_tool": "ask",
        "computer_use": "ask",
        "task_subagent": "ask"
      }
    }
  }
}

The response confirms that the gateway accepted the turn. Render progress from notifications.

Execution backends

By default, a turn uses the thread’s provider/model selection or the model_provider and model fields from turn/start. Clients can make the execution backend explicit:

{
  "execution_backend": {
    "type": "apiProvider",
    "provider": "openai"
  }
}

For CLI-backed turns, use cliAgentRuntime:

{
  "model": "gpt-5.4",
  "execution_backend": {
    "type": "cliAgentRuntime",
    "runtime_id": "codex",
    "runtime_kind": "codex"
  },
  "permission_profile": {
    "mode": "supervised"
  },
  "cli_runtime_options": {
    "effort": "high",
    "personality": "concise",
    "steer_if_active": true
  }
}

permission_profile is the Pioneer-level approval policy. The gateway maps it into the runtime-specific approval policy before starting the native runtime turn. cli_runtime_options is still runtime-specific for options such as sandbox, effort, personality, summary, or steering. A client should fetch runtime capabilities and model catalogs through the CLI Runtime API before offering a CLI runtime in a model selector. When a CLI runtime turn is active, the runtime can open pending requests for command approvals, file-change approvals, or user input. Clients resolve those through cli_runtime/request/respond, not turn/start.

Permission profiles and approval requests

Pioneer tool permissions are represented by permission_profile on turn/start and by the materialized permission_profile on every Turn.

{
  "permission_profile": {
    "mode": "auto_accept_edits"
  }
}

Supported modes:

Mode	Meaning
`full_access`	Allow tool actions without Pioneer approval prompts. This is the default when no profile is provided.
`auto_accept_edits`	Allow file reads, file writes, and MCP reads; ask for shell commands, network, MCP writes/unknown calls, skill tools, computer use, task/subagent launches, and unknown actions.
`supervised`	Allow file reads and MCP reads; ask for file writes, shell commands, network, MCP writes/unknown calls, skill tools, computer use, task/subagent launches, and unknown actions.

The gateway stores a TurnPermissionProfileSnapshot with:

Field	Meaning
`mode`	The selected or inherited permission mode.
`source`	`composer`, `defaulted`, `inherited_from_parent_turn`, `task_permission_cap`, or `system`.
`effective_policy`	A `ToolPermissionPolicySnapshot` with `allow`, `ask`, or `deny` behavior for each action kind.

ToolPermissionPolicySnapshot contains default_behavior, file_read, file_write, shell_command, network, mcp_read, mcp_write_or_unknown, dynamic_skill_tool, computer_use, task_subagent, and optional allowed_tools, denied_tools, and allowed_paths. The gateway also resolves a TurnExecutionSecuritySnapshot for runtime enforcement. That snapshot includes:

Area	Meaning
`permission_profile`	The materialized permission profile used by the tool evaluator.
`sandbox`	`unrestricted`, `workspace_write`, or `read_only`, plus cwd, filesystem entries, temp policy, network mirror, backend requirement, and backend preference.
`process`	Shell policy, environment filtering, timeout cap, and command risk rules.
`network`	`enabled`, `restricted`, or `disabled`, with allow/deny domain policy.
`approval`	Approval scopes available for this turn. Built-in restricted modes allow `allow_once` and `allow_for_turn`.
`backend`	Native, Codex CLI, or Claude CLI execution backend plus sandbox backend and backend capabilities.
`enforcement`	`active`, `partially_active`, or `unavailable`, with degraded capability details when needed.
`parent_cap`	Optional parent/task cap for child turns.

Built-in mode mapping:

Mode	Sandbox mode	Resource policy
`full_access`	`unrestricted`	Filesystem unrestricted, network enabled, process unrestricted.
`auto_accept_edits`	`workspace_write`	Resolved workspace/project roots writable, app read roots read-only, network disabled until granted, restricted process environment.
`supervised`	`read_only`	Resolved workspace/project/app roots read-only, network disabled until granted, restricted process environment.

When a native Pioneer tool action requires approval, the gateway publishes:

Event	Params	Meaning
`turn/permission/request/opened`	`TurnPermissionRequestOpenedNotification`	A tool action is waiting for user/client approval.
`turn/permission/request/resolved`	`TurnPermissionRequestResolvedNotification`	The pending request was resolved, cancelled, or expired.
`turn/permission/audit`	`TurnPermissionAuditEvent`	Durable audit event for profile selection, allowed/denied decisions, approval requests, and approval resolutions.

An approval request includes request_id, workspace_id, thread_id, turn_id, optional visible_thread_ids, tool_name, action, scope_hash, reason, optional summary, and display details. Resolve it with:

{
  "method": "turn/permission/request/respond",
  "params": {
    "request_id": "perm_000000000000000001",
    "resolution": "allow_for_turn"
  }
}

Resolutions are allow_once, allow_for_turn, deny, cancelled, and expired. allow_for_turn lets later matching requests with the same normalized scope proceed during the same turn without opening another approval request. CLI runtime-native approvals use the CLI runtime request API. Native Pioneer tool permissions use the turn permission API described here. Generated permission schemas:

/schemas/turn_permission_mode.json
/schemas/turn_permission_profile_selection.json
/schemas/turn_permission_profile_snapshot.json
/schemas/tool_permission_policy_snapshot.json
/schemas/turn_execution_security_snapshot.json
/schemas/turn_sandbox_snapshot.json
/schemas/turn_sandbox_mode.json
/schemas/turn_filesystem_sandbox_policy.json
/schemas/turn_filesystem_sandbox_entry.json
/schemas/turn_network_policy_snapshot.json
/schemas/turn_process_policy_snapshot.json
/schemas/turn_security_backend_snapshot.json
/schemas/turn_security_enforcement_status.json
/schemas/turn_security_degradation.json
/schemas/turn_security_parent_cap_snapshot.json
/schemas/permission_behavior.json
/schemas/turn_permission_approval_request.json
/schemas/turn_permission_approval_resolution.json
/schemas/turn_permission_request_opened_notification.json
/schemas/turn_permission_request_resolved_notification.json
/schemas/turn_permission_request_respond_params.json
/schemas/turn_permission_request_respond_response.json
/schemas/turn_permission_audit_event.json

User input

UserInput is a tagged union. Common variants:

[
  { "type": "text", "text": "Hello", "textElements": [] },
  { "type": "localFile", "path": "/Users/alexander/Code/pioneer/README.md" },
  { "type": "localImage", "path": "/tmp/screenshot.png" },
  { "type": "image", "url": "https://example.com/image.png" },
  { "type": "artifact", "artifactId": "art_000000000000000001" },
  { "type": "mention", "name": "repo", "path": "app://github/repo" }
]

Attachments are resolved by the gateway/provider pipeline. Local paths are evaluated on the gateway host, not on the client machine unless the gateway is local.

Files, artifacts, and remote gateways

localFile and localImage mean “a path visible to the gateway.” They are convenient for local developer flows, but they are not a portable client contract. If a desktop or mobile client is connected to a remote gateway, a path like /Users/alexander/Desktop/photo.jpg exists on the client machine, not on the gateway machine. The remote-safe path is:

Upload the file with the artifact upload API.
Bind or attach the resulting artifact to the turn.
Send a UserInput artifact reference, for example { "type": "artifact", "artifactId": "art_..." }.

The current turn can then receive the artifact as provider input when supported. Later turns do not automatically receive that file again. If a retained history message or recalled thread-context snippet refers to an older artifact, Pioneer gives the model a compact artifact ref. The model must reveal the artifact tool domain and call artifact_read if it needs the actual content. This is why clients should treat artifacts as the durable file identity and local paths as a gateway-local convenience.

Turn capabilities

Skills and MCP selections are sent separately from input:

[
  {
    "id": "cap_weather",
    "label": "weather",
    "kind": {
      "type": "skill",
      "slug": "workspace/weather",
      "sourceKind": "workspace"
    }
  },
  {
    "id": "cap_resend",
    "label": "resend",
    "kind": {
      "type": "mcpServer",
      "name": "resend",
      "scopeKind": "workspace"
    }
  },
  {
    "id": "cap_resend_add_contact",
    "label": "resend / Add Contact",
    "kind": {
      "type": "mcpTool",
      "serverName": "resend",
      "rawToolName": "add_contact",
      "scopeKind": "workspace"
    }
  }
]

Capability ids are client-generated stable ids for the turn. label is optional display text for timeline chips. The gateway normalizes duplicate and invalid capability input before resolution. Accepted capabilities are reported with reason explicit_composer_capability; rejected capabilities include reasons such as not_found, disabled_by_policy, validation_rejected, security_blocked, dependency_missing, catalog_missing, tool_missing, or provider_unsupported. Composer-selected skills become compact skill prompt entries and optional skill dynamic tools. Composer-selected MCP servers and tools become dynamic provider tools; they do not add MCP prompt text.

Cancelling a turn

{
  "method": "turn/cancel",
  "params": {
    "thread_id": "thr_000000000000000001",
    "turn_id": "trn_000000000000000001",
    "reason": "User stopped the turn"
  }
}

The response contains the updated Turn. A cancelled turn is represented as an interrupted/failed terminal state depending on where cancellation lands in the runtime.

Resuming a blocked turn

When a turn is blocked by recovery policy or an exhausted execution window, clients can resume it with turn/resume:

{
  "method": "turn/resume",
  "params": {
    "thread_id": "thr_000000000000000001",
    "turn_id": "trn_000000000000000001",
    "recovery_job_id": "rec_000000000000000001"
  }
}

recovery_job_id is optional. If omitted, the gateway chooses the active recovery job for the turn when one is available. The response includes the updated Turn and the recovery job id used for the resume operation. Clients should expect a blocked turn to publish turn/blocked before user-visible recovery actions become available.

Reading items

turn/items returns persisted TurnItemEvent rows for one turn.

{
  "method": "turn/items",
  "params": {
    "thread_id": "thr_000000000000000001",
    "turn_id": "trn_000000000000000001"
  }
}

Result:

{
  "thread_id": "thr_000000000000000001",
  "workspace_id": "ws_000000000000000001",
  "turn_id": "trn_000000000000000001",
  "events": [],
  "last_sequence": 42
}

Semantic timeline and turn work

The current semantic timeline API is split by level:

API	Use it for
`thread/timeline/page`	Top-level paginated conversation blocks for a thread.
`turn/work/page`	Paginated work items inside one `turn_work` block.
`turn/work/items/get`	Targeted refresh for changed work item ids after a live notification or reconnect.
`turn/items`	Raw persisted event replay for one turn.

Use Threads API thread/timeline/page when rendering a scrollable conversation. Use turn/work/page when the user expands or paginates the detailed work for a single turn.

Turn work page

turn/work/page loads the paginated work items inside one semantic turn work block. It is the detail API paired with Threads API thread/timeline/page.

{
  "method": "turn/work/page",
  "params": {
    "threadId": "thr_000000000000000001",
    "turnId": "trn_000000000000000001",
    "anchor": { "kind": "newest" },
    "limit": 100
  }
}

The response includes workspaceId, threadId, turnId, projectionVersion, sourceHighWatermark, projectionUpdatedAtUnixMicros, work, items, and page.

Field	Meaning
`work`	`TurnWorkBlock` summary: presentation, state, counts, cursors, and elapsed time.
`items`	`TurnWorkItem` rows containing the underlying `TurnItem`, status, item type, order key, timestamps, and optional metadata.
`page`	Cursor and `hasMoreBefore` / `hasMoreAfter` pagination state.

sourceHighWatermark and projectionUpdatedAtUnixMicros let clients reject an older response that arrives after a newer projection. Work items also carry source sequence and source-update timestamps. Use these values to prevent a late reconnect response from changing a completed, failed, or cancelled item back to an older state.

Fetching changed work items

turn/work/items/get is the narrow refresh path for semantic timeline reducers. Send the work item ids named by a change notification:

{
  "method": "turn/work/items/get",
  "params": {
    "threadId": "thr_000000000000000001",
    "turnId": "trn_000000000000000001",
    "workItemIds": ["work_000000000000000001"]
  }
}

The response returns the current items plus removedWorkItemIds, along with the projection freshness fields. A client can merge this response into the existing timeline without discarding unrelated loaded pages. Use turn/work/page when expanding or paginating the work under a turn. Use turn/items for raw persisted event replay. Generated turn-work schemas:

/schemas/turn_work_block.json
/schemas/turn_work_item.json
/schemas/turn_work_page_params.json
/schemas/turn_work_page_response.json
/schemas/turn_work_items_changed_notification.json
/schemas/turn_work_state_changed_notification.json

Turn items

TurnItem is the timeline object that clients render. Main variants:

Variant	Meaning
`userMessage`	User text and attachments, including file/artifact chips and requested skill/MCP capability chips.
`agentMessage`	Assistant visible answer text, optionally with Markdown AST.
`reasoning`	Reasoning/thinking item.
`systemEvent`	Informational/warning/error event.
`task`	Task/subagent item composed into the turn.
`commandExecution`	Shell/session tool call.
`fileChange`	File edit/patch tool call.
`webSearch`	Web search tool call.
`webFetch`	Web fetch tool call.
`download`	URL download tool call.
`dynamicToolCall`	MCP, skill, task, or other dynamic tool call.

Tool items include status, arguments, output_policy, display/storage payloads, optional recovery policy, optional recovery view, and normalized outcome fields.

Streaming notifications

Turn execution is observed through notifications:

Event	Params	Meaning
`turn/started`	`TurnStartedNotification`	Turn accepted and started.
`item/started`	`ItemStartedNotification`	A timeline item was opened.
`item/agent_message/delta`	`ItemDeltaNotification`	Assistant text delta.
`item/command_execution/output_delta`	`ItemDeltaNotification`	Shell stdout/stderr-style output delta.
`item/file_change/output_delta`	`ItemDeltaNotification`	File-change output delta.
`item/tool/progress`	`ItemDeltaNotification`	Tool progress update.
`item/completed`	`ItemCompletedNotification`	A timeline item reached terminal display state.
`item/updated`	`ItemUpdatedNotification`	A timeline item was updated after initial creation.
`turn/completed`	`TurnCompletedNotification`	Turn completed successfully.
`turn/failed`	`TurnFailedNotification`	Turn failed or was interrupted.
`turn/blocked`	`TurnBlockedNotification`	Turn stopped in a recoverable blocked state.
`thread/timeline/blocks/changed`	`ThreadTimelineBlocksChangedNotification`	Semantic thread timeline pages may be stale and should be reloaded.
`turn/work/items/changed`	`TurnWorkItemsChangedNotification`	Work items within a semantic turn work block changed.
`turn/work/state/changed`	`TurnWorkStateChangedNotification`	A semantic turn work block changed state or counts.
`turn/permission/request/opened`	`TurnPermissionRequestOpenedNotification`	A native tool action needs approval before it can run.
`turn/permission/request/resolved`	`TurnPermissionRequestResolvedNotification`	A native tool permission request was resolved.
`turn/permission/audit`	`TurnPermissionAuditEvent`	Permission profile, decision, request, or resolution audit event.

Delta notifications include stream: agent_message, stdout, stderr, tool_progress, file_change, or generic.

Execution windows

Long agent turns are divided into execution windows. A window bounds agent rounds, tool calls, wall-clock time, and provider-token accounting. When a window is exhausted, the gateway can checkpoint the turn and continue in a new window, or block the turn if the total turn budget has been reached. Execution window statuses serialize as running, exhausted, checkpointed, continued, completed, interrupted, blocked, or failed. Exhaustion reasons serialize as:

Reason	Meaning
`max_agent_rounds_per_window`	The window hit its agent-round limit.
`max_tool_calls_per_window`	The window hit its tool-call limit.
`max_wall_clock_ms_per_window`	The window hit its wall-clock limit.
`max_provider_tokens_per_window`	Provider usage exceeded the configured provider-token window.
`provider_failure_continuation`	Continuation was opened after a provider failure.
`runtime_shutdown_continuation`	Continuation was opened after runtime shutdown or recovery.

Execution-window notifications are:

Event	Params	Meaning
`turn/execution_window/started`	`TurnExecutionWindowStartedNotification`	A bounded execution window started.
`turn/execution_window/exhausted`	`TurnExecutionWindowExhaustedNotification`	The current window reached a limit and recorded observed counts.
`turn/execution_window/checkpointed`	`TurnExecutionWindowCheckpointedNotification`	The gateway wrote a continuation checkpoint.
`turn/execution_window/continued`	`TurnExecutionWindowContinuedNotification`	Execution resumed from a checkpoint into another window.
`turn/execution_window/blocked`	`TurnExecutionWindowBlockedNotification`	No further automatic window can be opened; user or recovery action is needed.

The per-window limits come from [gateway.tools.execution_windows]; total turn limits come from [gateway.tools.execution_windows.total].

Recovery and retry notifications

The gateway also publishes detailed recovery events:

Event	Meaning
`item/timeout_detected`	Tool or item attempt exceeded a deadline.
`item/recovery_opened`	A recovery job was opened for an item.
`item/recovery_attached`	A recovery attempt was attached to an existing recovery job.
`item/retry_scheduled`	Provider/item retry scheduled for a later time.
`item/retry_attempt_started`	Retry attempt started.
`item/recovery_succeeded`	Recovery succeeded.
`item/recovery_exhausted`	Recovery attempts were exhausted.
`item/tool/retry_scheduled`	Tool retry episode scheduled after recoverable tool failure.
`item/tool/retry_resolved`	Tool retry resolved.
`item/tool/retry_exhausted`	Tool retry budget exhausted.
`turn/tool_loop/budget_exceeded`	Agent tool loop hit round/tool-call budget.
`turn/permission/audit`	Permission profile selection, allowed decision, denied decision, approval request, or approval resolution was recorded.
`context/compressing`	Gateway is compressing thread history.
`context/compressed`	History compression finished.

Clients can render these as timeline diagnostics or use them to trigger a timeline refresh.

Voice-created turns

Voice input is controlled by the Voice API, but successful voice sessions become normal turns. The gateway owns transcription and starts the final turn with the transcript as the first UserInput::Text item. Clients should render the resulting user message, assistant work, permission prompts, and terminal state from the normal turn and timeline notifications. Cancelled and no-speech voice sessions do not create a turn or a timeline user message. Voice platform microphone permission is client-side capture state; it is separate from Pioneer agent permission_profile and turn sandbox/resource policy.

Prompt manifest

When the prompt compiler runs, the Turn can receive a prompt_manifest:

{
  "compiler_version": "0.1.0",
  "profile": "assistant_full",
  "section_ids": ["identity_base", "assistant_safety", "skills_runtime_prompt"],
  "fingerprint_stable": "...",
  "fingerprint_dynamic": "...",
  "fingerprint_full": "...",
  "diagnostics": []
}

The manifest is metadata for auditing prompt shape. It does not contain the full prompt text.

Introduction

Workspace & Threads

Features

Methods

Starting a turn

Execution backends

Permission profiles and approval requests

User input

Files, artifacts, and remote gateways

Turn capabilities

Cancelling a turn

Resuming a blocked turn

Reading items

Semantic timeline and turn work

Turn work page

Fetching changed work items

Turn items

Streaming notifications

Execution windows

Recovery and retry notifications

Voice-created turns

Prompt manifest

​Methods

​Starting a turn

​Execution backends

​Permission profiles and approval requests

​User input

​Files, artifacts, and remote gateways

​Turn capabilities

​Cancelling a turn

​Resuming a blocked turn

​Reading items

​Semantic timeline and turn work

​Turn work page

​Fetching changed work items

​Turn items

​Streaming notifications

​Execution windows

​Recovery and retry notifications

​Voice-created turns

​Prompt manifest

Methods

Starting a turn

Execution backends

Permission profiles and approval requests

User input

Files, artifacts, and remote gateways

Turn capabilities

Cancelling a turn

Resuming a blocked turn

Reading items

Semantic timeline and turn work

Turn work page

Fetching changed work items

Turn items

Streaming notifications

Execution windows

Recovery and retry notifications

Voice-created turns

Prompt manifest