> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Turns API

> Submitting turns, cancelling turns, reading turn items, composing timelines, and handling streaming turn notifications.

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "execution_backend": {
    "type": "apiProvider",
    "provider": "openai"
  }
}
```

For CLI-backed turns, use `cliAgentRuntime`:

```json theme={null}
{
  "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](/protocol/cli-runtime) 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`.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
[
  { "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:

1. Upload the file with the artifact upload API.
2. Bind or attach the resulting artifact to the turn.
3. 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`:

```json theme={null}
[
  {
    "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

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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.

```json theme={null}
{
  "method": "turn/items",
  "params": {
    "thread_id": "thr_000000000000000001",
    "turn_id": "trn_000000000000000001"
  }
}
```

Result:

```json theme={null}
{
  "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](/protocol/threads) `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](/protocol/threads) `thread/timeline/page`.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/protocol/voice), 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`:

```json theme={null}
{
  "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.