@markusylisiurunen/tau 0.3.82 → 0.3.83

package/dist/core/static/tau_docs/session-protocol-methods.md

@@ -1,8 +1,8 @@
 # Session protocol method reference
 
-This page defines every request method in protocol version 15. It is the compact wire reference for clients that already understand connection, observation, and delta application from the [session protocol](session-protocol.md).
+This page lists every request method of the protocol version that ships with this Tau release. It is a compact reference for clients that already know how to connect, observe, and apply deltas, as described in the [session protocol](session-protocol.md).
 
-Every request uses `{ version, type: "request", id, method, params }`. Every successful response uses `{ version, type: "response", id, ok: true, result }`. `params` is required even when empty, and unknown object fields are stripped.
+Every request is `{ version, type: "request", id, method, params }`, and every successful response is `{ version, type: "response", id, ok: true, result }`. `version` is the number the server sends in `ready`. `params` is required even when empty, and unknown fields are removed.
 
 ## Common values
 
@@ -10,7 +10,7 @@ A `sessionId` is a non-empty opaque string returned by `session.create` or `sess
 
 Reasoning values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
 
-Turn methods return one of these terminal outcomes:
+Turn methods return one of these final outcomes:
 
 ```ts
 type TurnOutcome =
@@ -24,7 +24,7 @@ type TurnOutcome =
     };
 ```
 
-A completed protocol request can therefore contain a failed, aborted, or blocked turn outcome. The protocol request itself fails only when the host cannot accept or settle it.
+A successful request can therefore report a failed, aborted, or blocked turn. The request itself fails only when the host cannot accept or finish it.
 
 ## Connect and find sessions
 
@@ -47,7 +47,7 @@ params: {
 }
 
 result: {
-  protocolVersion: 15;
+  protocolVersion: number; // same as `version` in `ready`
   methods: string[];
   alreadyInitialized: boolean;
 }
@@ -76,11 +76,11 @@ params: {
 result: { sessionId: string }
 ```
 
-`cwd` must be absolute inside the selected execution environment. Fly Sprites must already exist and be reachable through a host-configured resolver. Tau does not provision a target or repository.
+`cwd` must be an absolute path inside the chosen execution environment. A Fly Sprite must already exist, and the host must have a `flySprites` connection configured. Tau does not create the target or the repository.
 
-`attributes` is required, including when empty. It accepts at most 32 immutable pairs; keys are 1 to 64 characters and values at most 1,024 characters. Tau stores the supplied strings without inferring missing provenance. Conventional attributes and their use are covered in [sessions](sessions.md) and [history](history.md).
+`attributes` is required, even when empty. It accepts at most 32 pairs, which never change after creation. Keys are 1 to 64 characters and values at most 1,024 characters. Tau stores them as given and does not fill in missing ones. Conventional attributes and their use are covered in [sessions](sessions.md) and [history](history.md).
 
-A local `env` supplies execution-environment overrides. Names must be valid environment-variable names, values cannot contain NUL, and `HOME` is forbidden because the execution environment owns it. Overrides become durable session state, so do not put secrets there unless the session store is protected accordingly.
+A local `env` sets environment variables for the execution environment. Names must be valid variable names, values cannot contain NUL, and `HOME` is not allowed because the execution environment sets it. These variables are saved with the session, so do not put secrets there unless the session store is protected accordingly.
 
 Creation returns only an id. Call `session.observe` for state and streamed updates.
 
@@ -111,7 +111,7 @@ result: {
 }
 ```
 
-Install all three baselines before applying later messages. Calling `observe` again refreshes the baselines without creating a second session.
+Install all three before applying later messages. Calling `observe` again returns fresh starting states; it does not create a second session.
 
 ### `session.unobserve`
 
@@ -139,7 +139,7 @@ params: { sessionId: string; text: string; historyEntryId?: string }
 result: { snapshot: SessionProtocolSnapshot; userHistoryEntryId: string }
 ```
 
-This is a serialized context mutation. It can interrupt an active turn and rejects pending queue or steering requests before appending the message. Use it for user-authored material that should become model-visible, not for arbitrary client diagnostics.
+This changes the context and waits its turn behind other changes. It can interrupt a running turn, and rejects pending queued and steering requests before adding the message. Use it for text written by the user that the model should see, not for client diagnostics.
 
 ### `session.submit`
 
@@ -150,22 +150,22 @@ params: { sessionId: string; text: string; historyEntryId?: string }
 result: { userHistoryEntryId: string; turn: TurnOutcome }
 ```
 
-Once accepted, the turn is durably represented in `snapshot.turns[userHistoryEntryId]`. Changes stream through the observed state channels while the request remains open.
+Once accepted, the turn is recorded in `snapshot.turns[userHistoryEntryId]`. Updates arrive through the observed channels while the request is open.
 
 ### `session.queue`
 
-Uses the same parameters and result as `session.submit`. When the session is idle it starts immediately. While a turn is active, it appears in pending state and starts after the session becomes idle.
+Same parameters and result as `session.submit`. When the session is idle, the turn starts right away. While a turn is running, the message is listed as pending and starts once the session is idle.
 
 ```ts
 params: { sessionId: string; text: string; historyEntryId?: string }
 result: { userHistoryEntryId: string; turn: TurnOutcome }
 ```
 
-The request response remains pending until its eventual turn settles.
+The response arrives when that turn finishes.
 
 ### `session.steer`
 
-Requests a change of direction for active model work.
+Changes the direction of the running turn.
 
 ```ts
 params: {
@@ -178,11 +178,11 @@ result: {
 }
 ```
 
-When idle, steering starts an ordinary turn. During an active turn, Tau waits for a safe continuation boundary, batches steering in arrival order, and starts one continuation turn before queued work. Batched requests share the generated `userHistoryEntryId`. Steering does not accept a caller-provided history id.
+When idle, steering starts an ordinary turn. During a turn, Tau waits for the next safe point, batches steering messages in arrival order, and continues the turn with them before any queued work. Batched requests share the same generated `userHistoryEntryId`. Steering does not accept a history ID from the caller.
 
 ### `session.cancelPendingMessages`
 
-Cancels all pending queue and steering requests without interrupting active work.
+Cancels all pending queued and steering requests without interrupting running work.
 
 ```ts
 params: {
@@ -212,7 +212,7 @@ The session must be idle.
 
 ### `session.interrupt`
 
-Requests cancellation of active session work, including turns, direct executions, model samples, and maintenance.
+Asks the session's running work to stop: turns, direct commands, model samples, and maintenance.
 
 ```ts
 params: {
@@ -224,7 +224,7 @@ result: {
 }
 ```
 
-`isTurnRunning` may remain `true` while cancellation settles. The method also cancels unapplied boundary steering. It does not dispose reusable subagent threads; use `session.interruptSubagent` for one subagent.
+`isTurnRunning` may stay `true` until the cancellation finishes. The method also cancels steering that has not been applied. It does not interrupt or remove subagents; use `session.interruptSubagent` for a subagent.
 
 ## Run independent execution and sampling
 
@@ -259,9 +259,9 @@ result: {
 
 `execId` must be unique among active executions in the session. `stdinBase64` is limited to 16 MiB decoded. `maxCaptureBytes` is positive and at most 24 MiB; the default is 1 MiB. `HOME` cannot be overridden.
 
-When `args` is present, Bash receives the first value as `$0` and the rest as `$@`. A safe exact-executable pattern is `command: 'exec "$0" "$@"'` with the executable and arguments in `args`. `cwd` chooses the command directory but is not a confinement boundary.
+When `args` is present, Bash receives the first value as `$0` and the rest as `$@`. To run one executable safely, use `command: 'exec "$0" "$@"'` with the executable and its arguments in `args`. `cwd` sets the starting directory; it does not restrict the command to it.
 
-Executions can overlap turns, samples, mutations, and other executions. Clients must coordinate workspace access when consistency matters.
+Commands can run at the same time as turns, samples, session changes, and other commands. Clients must coordinate workspace access when consistency matters.
 
 ### `session.cancelExec`
 
@@ -279,7 +279,7 @@ result: {
 
 ### `session.sample`
 
-Runs isolated inference against the session's active resolved model target. It uses only the supplied context and does not mutate the session, execute tool calls, emit deltas, or add to session cost.
+Runs a standalone model call with the session's current model. It uses only the context you supply, and does not change the session, run tools, send deltas, or add to the session's cost.
 
 ```ts
 params: {
@@ -299,13 +299,13 @@ params: {
 result: { message: AssistantMessage }
 ```
 
-`context.messages` and the returned message use Tau's provider-neutral model message shape. Intermediate system messages use the plain-text, versioned metadata shape described in the [session protocol](session-protocol.md); metadata is not sent to the provider. Unsupported sections and tool mutations are rejected. Returned tool calls are data only. Samples can run concurrently and are cancelled by `session.interrupt`, transport shutdown, or host shutdown.
+`context.messages` and the returned message use Tau's provider-independent message format. System messages after the first use the plain-text format with versioned metadata described in the [session protocol](session-protocol.md); the metadata is not sent to the provider. Sections and tool changes are rejected. Tool calls in the response are returned as data and never run. Samples can run at the same time, and `session.interrupt`, transport shutdown, or host shutdown cancels them.
 
 ## Read and change session state
 
 ### `session.snapshot`
 
-Returns the complete authoritative snapshot.
+Returns the complete current snapshot.
 
 ```ts
 params: {
@@ -318,7 +318,7 @@ Use this after observation, on demand, or to recover from a delta revision gap.
 
 ### `session.setReasoning`
 
-Changes the reasoning effort for the next independently started turn.
+Changes the reasoning effort, starting with the next turn.
 
 ```ts
 params: {
@@ -331,7 +331,7 @@ result: {
 }
 ```
 
-The update is serialized but does not interrupt a running turn. Active turns and steering continuations retain their captured settings.
+The change waits its turn behind other changes but does not interrupt a running turn. Running turns, including their steering, keep their settings.
 
 ### `session.setPersona`
 
@@ -345,7 +345,7 @@ params: {
 result: SessionProtocolSnapshot;
 ```
 
-This is a serialized context mutation. It interrupts an active turn and rejects pending input before returning the authoritative snapshot.
+This changes the context and waits its turn behind other changes. It interrupts a running turn and rejects pending input, then returns the new snapshot.
 
 ### `session.resolvePrompt`
 
@@ -362,11 +362,11 @@ result: {
 }
 ```
 
-Snapshot catalog entries contain prompt metadata only. Call this lazily when the user invokes a prompt.
+The snapshot catalog holds only prompt IDs and labels. Call this when the user chooses a prompt.
 
 ### `session.autocompletePaths`
 
-Returns bounded path suggestions from the execution environment.
+Returns a limited list of path suggestions from the execution environment.
 
 ```ts
 params: { sessionId: string; query: string; limit: number }
@@ -379,7 +379,7 @@ result: { paths: string[] }
 
 ### `session.reload`
 
-Reloads session-owned configuration and content from the execution environment.
+Reloads the session's configuration and content from the execution environment.
 
 ```ts
 params: { sessionId: string }
@@ -390,11 +390,11 @@ result: {
 }
 ```
 
-Reload is a serialized context mutation. It interrupts an active turn and rejects pending input. It does not reload client-owned themes or tools, process environment variables, or host-wide services. See [configuration](configuration.md) for apply boundaries.
+Reload changes the context and waits its turn behind other changes. It interrupts a running turn and rejects pending input. It does not reload client themes or tools, process environment variables, or host services. See [configuration](configuration.md) for when changes apply.
 
 ### `session.compact`
 
-Manually replaces active model context with a generated summary.
+Replaces the model's context with a generated summary.
 
 ```ts
 params: {
@@ -409,11 +409,11 @@ result: {
 }
 ```
 
-Compaction interrupts an active turn, rejects pending input, and returns an authoritative replacement snapshot. A successful compaction advances the timeline epoch.
+Compaction interrupts a running turn, rejects pending input, and returns the new snapshot. A successful compaction advances the timeline epoch.
 
 ### `session.rewind`
 
-Removes one selected user history entry and all later active state.
+Removes one user message and everything after it.
 
 ```ts
 params: { sessionId: string; historyEntryId: string }
@@ -425,13 +425,13 @@ result: {
 }
 ```
 
-Rewind requires no active turn and no pending user input. It returns `busy` rather than interrupting work. The returned `text` is the selected user text for restoring to an editor.
+Rewind requires an idle session with no pending input, and returns `busy` instead of interrupting work. The returned `text` is the removed user message, for putting back in an editor.
 
 ## Control subagents and ephemeral contexts
 
 ### `session.interruptSubagent`
 
-Interrupts the current run of one supervised subagent without disposing its reusable thread.
+Interrupts one subagent's current run. The subagent stays available for follow-ups.
 
 ```ts
 params: {
@@ -445,7 +445,7 @@ result: {
 
 ### `session.ephemeral.create`
 
-Creates a non-persisted host-owned agent context independent of the main timeline.
+Creates an agent context on the host that is not saved and is separate from the main conversation.
 
 ```ts
 params: {
@@ -459,7 +459,7 @@ result: {
 }
 ```
 
-The context uses the hosted session's persona and execution environment plus the supplied instructions and exact tool set. `reasoning` sets the initial effort for new threads. When omitted, the context captures the parent session agent's current effective effort. Later parent setting changes do not affect the context. It is not recoverable after host restart.
+The context uses the session's persona and execution environment, with the given instructions and exactly the given tools. `reasoning` sets the starting effort for new threads. Without it, the context uses the session's effort at creation time. Later changes to the session's settings do not affect the context. It does not survive a host restart.
 
 ### `session.ephemeral.submit`
 
@@ -477,7 +477,7 @@ params: {
 result: { threadId: string; response: string }
 ```
 
-`reasoning` updates the target thread before running the submitted message and remains active for later submissions. When omitted, the thread retains its current effort. `forkFromThreadId` creates a new thread from an idle thread in the same context, including its current reasoning effort; a submit-time `reasoning` value overrides only the new fork. Overlapping submissions to the same thread return `busy`; independent threads can run concurrently.
+`reasoning` changes the thread's effort before running the message, and stays in effect for later messages. Without it, the thread keeps its current effort. `forkFromThreadId` creates a new thread from an idle thread in the same context, copying its effort; a `reasoning` value given here applies only to the new fork. A second submission to a busy thread returns `busy`, while different threads can run at once.
 
 ### `session.ephemeral.close`
 
@@ -497,7 +497,7 @@ result: {
 
 ## Complete delegated client-tool calls
 
-These methods are for a client that advertised tools during `initialize`. Ordinary clients do not call them.
+These methods are for clients that offered tools in `initialize`. Other clients never call them.
 
 ### `session.clientTool.ack`
 
@@ -523,9 +523,9 @@ result: {
 }
 ```
 
-The optional presentation is a partial running-state override. When present, `subject` must be non-empty and may contain line feeds but not carriage returns. Each detail text and metadata value is one line. Presentation objects are limited to 1 MiB; subjects and detail values to 256 KiB each; metadata values to 16 KiB each; and detail and metadata collections to 1,024 entries each.
+The optional presentation partly overrides the running tool card. If given, `subject` must be non-empty and may contain line feeds but not carriage returns. Each detail text and metadata value is one line. Presentation objects are limited to 1 MiB; subjects and detail values to 256 KiB each; metadata values to 16 KiB each; and detail and metadata collections to 1,024 entries each.
 
-The host preserves explicit fields within those safety limits and supplies canonical display-truncated defaults for omitted fields. It owns the action and operation and records the resolved presentation. Empty detail or metadata arrays suppress those default fields. An accepted acknowledgement authorizes the client to begin execution.
+The host keeps fields you set, within those limits, and fills in omitted fields with defaults truncated as Tau truncates its own cards. It sets the action and operation, and records the final presentation. An empty `details` or `metadata` array hides that default. Once the acknowledgement is accepted, the client may start work.
 
 ### `session.clientTool.result`
 
@@ -564,10 +564,10 @@ params:
 result: { accepted: boolean };
 ```
 
-`content` preserves text/image block order in the model-facing result, snapshots, and deltas. It may be empty and allows at most 1,024 blocks, including at most 16 images with valid padded base64 representing at most 3.5 MiB each. Image bytes are not presentation content.
+`content` keeps the order of text and image blocks in the model's result, snapshots, and deltas. It may be empty and can have at most 1,024 blocks, including at most 16 images in valid padded base64 of at most 3.5 MiB each. Images are never shown in the tool card.
 
-The optional result presentation applies only to the reported terminal state and is resolved independently from the running presentation. The host preserves explicit fields unchanged after safety validation and supplies canonical display-truncated defaults for omitted fields. If no client result arrives, the host uses a complete fallback for timeout, cancellation, detach, or another terminal outcome.
+The optional presentation applies only to the finished card, separately from the running one. The host keeps fields you set once they pass validation, and fills in omitted fields with truncated defaults. If no result arrives, the host shows a complete default card for the timeout, cancellation, detach, or other outcome.
 
-A successful result is accepted only after the host has accepted the acknowledgement. An error sent before acknowledgement records a preparation failure, such as an error from `describe`, without authorizing execution. An error sent afterward records an execution failure.
+A successful result is accepted only after the host has accepted the acknowledgement. An error sent before acknowledging records a preparation failure, such as an error from `describe`, and the tool never runs. An error sent afterward records an execution failure.
 
-`accepted: false` means the successful call was not yet authorized, or the call was cancelled, timed out, detached, unknown, or already completed. Do not retry or send additional results for that call.
+`accepted: false` means a successful result arrived before the call was acknowledged, or the call was cancelled, timed out, detached, unknown, or already finished. Do not retry or send more results for that call.

package/dist/core/static/tau_docs/session-protocol.md

@@ -1,8 +1,8 @@
 # Session protocol
 
-Tau's session protocol is the public wire contract for clients that create, observe, and control hosted sessions through `tau serve`. Node applications can usually use the typed [Node SDK](node-sdk.md) instead.
+Tau's session protocol is the wire format for clients that create, observe, and control sessions hosted by `tau serve`. Node applications can usually use the typed [Node SDK](node-sdk.md) instead.
 
-The protocol is transport-neutral and request and response based, with separate server messages for observed state, pending input, subagent activity, ephemeral feedback, and delegated client tools. Tau currently exposes it over WebSocket. The complete method surface is in the [session protocol method reference](session-protocol-methods.md).
+The protocol is based on requests and responses, plus server messages for session state, pending input, subagent activity, short-lived feedback, and client tool calls. It does not depend on a particular transport; Tau serves it over WebSocket. The complete method surface is in the [session protocol method reference](session-protocol-methods.md).
 
 ## Connect over WebSocket
 
@@ -10,7 +10,7 @@ The protocol is transport-neutral and request and response based, with separate
 
 The server exposes one host. Starting it does not create or select a session. A client lists, creates, or observes sessions explicitly.
 
-The client, host, and execution environment remain separate logical machines even when they share a process or filesystem. Session paths and commands belong to the execution environment. Persistence, credentials, model work, and protocol coordination belong to the host. Client tools and local UI belong to the connected client. See [ownership and scope](ownership-and-scope.md) before passing paths or credentials across this boundary.
+The client, host, and execution environment are separate, even when they share a process or filesystem. Session paths and commands are on the execution environment. Saving, credentials, model calls, and protocol handling are on the host. Client tools and local UI are on the connected client. See [ownership and scope](ownership-and-scope.md) before passing paths or credentials across this boundary.
 
 ## Connect and initialize
 
@@ -24,7 +24,7 @@ The server sends `ready` as its first message:
 }
 ```
 
-The actual `methods` array contains the complete supported method set, not only the shortened example above. Protocol versioning is exact rather than negotiated. A client and host that disagree on `version` must use compatible Tau releases.
+The real `methods` array lists every supported method; the example above is shortened. Versions must match exactly and are not negotiated. If client and host disagree on `version`, use matching Tau releases.
 
 After `ready`, send `initialize` with non-empty client metadata:
 
@@ -40,9 +40,9 @@ After `ready`, send `initialize` with non-empty client metadata:
 }
 ```
 
-A successful result returns `protocolVersion`, the complete `methods` array, and `alreadyInitialized`. Repeating `initialize` is allowed and reports `alreadyInitialized: true`. Initialization is a handshake signal, not a session operation, but clients should complete it before other requests.
+A successful result returns `protocolVersion`, the full `methods` array, and `alreadyInitialized`. Calling `initialize` again is allowed and returns `alreadyInitialized: true`. It does not act on any session, but clients should complete it before other requests.
 
-An initializing client may advertise in-process client tools through `client.tools`. Tool calls are then delegated over this connection. The [client tools](client-tools.md) page owns tool behavior, authority, and command-backed helpers; this page describes the wire messages required by a raw protocol client.
+A client can offer its own tools in `client.tools` when initializing. Calls to those tools are then sent to it over this connection. [Client tools](client-tools.md) covers tool behavior, permissions, and command helpers; this page covers only the wire messages a raw protocol client needs.
 
 ## Send requests and match responses
 
@@ -58,7 +58,7 @@ Every request has the same envelope:
 }
 ```
 
-`id` is a non-empty client-chosen string and must identify the outstanding request on that connection. `params` is always required, including `{}` for `session.list`. The host validates required fields, field types, discriminators, method names, and the exact protocol version. Unknown object fields are accepted and stripped, except system messages and their metadata, which reject unsupported fields.
+`id` is a non-empty string chosen by the client, unique among its open requests on the connection. `params` is always required, even if empty, as in `{}` for `session.list`. The host validates required fields, types, discriminators, method names, and the exact protocol version. Unknown fields are accepted and removed, except in system messages and their metadata, where they are rejected.
 
 Successful responses echo the request id:
 
@@ -76,7 +76,7 @@ A request can remain open while the host emits state messages or handles later r
 
 ## Observe before consuming session state
 
-`session.create` creates a hosted session but does not observe it. `session.observe` establishes observation on this connection and returns three authoritative baselines together:
+`session.create` creates a session but does not observe it. `session.observe` starts observing on this connection and returns three complete starting states together:
 
 ```json
 {
@@ -86,13 +86,13 @@ A request can remain open while the host emits state messages or handles later r
 }
 ```
 
-Install all three baselines before processing later messages for that session. The host buffers updates while preparing the observe response and sends only updates newer than the returned revisions afterward.
+Install all three before processing later messages for that session. The host holds back updates while preparing the response, and afterward sends only updates newer than the returned revisions.
 
-Observation controls delivery, not session ownership. `session.unobserve` stops this connection's updates without deleting the session or interrupting work. Several connections may observe the same session, and every observer can mutate it. Client-tool names must remain unique across observing clients.
+Observing controls which updates you receive; it does not make you the owner. `session.unobserve` stops this connection's updates without deleting the session or interrupting work. Several connections can observe one session, and each can change it. Client tool names must be unique among observing clients.
 
-## Treat the snapshot as authoritative
+## Treat the snapshot as the source of truth
 
-`SessionProtocolSnapshot` is the recoverable public state for one session. Its major fields are:
+`SessionProtocolSnapshot` is the saved, recoverable state of one session. Its main fields are:
 
 | Field | Meaning |
 | --- | --- |
@@ -103,26 +103,26 @@ Observation controls delivery, not session ownership. `session.unobserve` stops
 | `settings`, `costTotal` | Persona and reasoning settings, and accumulated session cost. |
 | `bootstrap`, `catalog` | Selected model and prompt metadata plus available personas, prompt metadata, skills, and enabled host-configured MCP server names. |
 | `executionEnvironment` | The environment kind, identity, `cwd`, and home used for agent-visible work. |
-| `messages`, `turns` | Synchronized model-facing records and durable logical-turn receipts. |
+| `messages`, `turns` | Messages sent to the model, and a saved record for each accepted turn. |
 | `timeline` | Ordered active transcript placement. |
-| `tools`, `operations`, `agents` | Mutable semantic state referenced by timeline items or client views. |
+| `tools`, `operations`, `agents` | Changing state that timeline items or client views refer to. |
 | `facets` | Versioned client-facing metadata. Unknown facet kinds and versions should be ignored. |
 
-`catalog.mcpServers` lists enabled MCP server names from the host configuration. It does not indicate live connections; servers connect lazily when used. Only names are exposed, not connection settings or credentials.
+`catalog.mcpServers` lists the enabled MCP servers in the host configuration, by name only. It does not mean they are connected; servers connect on first use. Connection settings and credentials are never included.
 
-`bootstrap.prompt.subagentSystemPrompt` is present when subagent launches are enabled. Each catalog persona has a `subagentLaunchModels` allowlist. Subagent records have task titles and IDs, not worker-type names.
+`bootstrap.prompt.subagentSystemPrompt` is present when subagents can be started. Each catalog persona has a `subagentLaunchModels` allowlist. Subagent records have task titles and IDs; there are no worker types.
 
 Render active transcript order from `timeline.items`, not by sorting or filtering `messages`. A timeline item either contains a notice or references a message, tool, or operation in the corresponding snapshot collection. Some model-visible messages intentionally have no timeline item.
 
 The timeline has an `epoch`, a per-epoch sequence high-water mark, and ordered items. Successful compaction replaces the active recoverable timeline and advances the epoch. Rewind stays in the same epoch, removes later items, and preserves the sequence high-water mark so sequence numbers are not reused.
 
-User message text is raw recoverable session text. User-facing renderers should remove Tau metadata and leading exact `<system>...</system>\n` blocks. The Node SDK exports projection helpers for this purpose. Do not apply user-text projection to assistant, tool-result, or protocol system messages.
+User message text is stored raw. Before showing it, remove Tau metadata and any leading `<system>...</system>\n` blocks; the Node SDK exports helpers for this. Apply this only to user messages, never to assistant, tool-result, or system messages.
 
-The initial system message is the separate persona/base prompt. Intermediate system messages are ordered history records with plain-text `content`, a `timestamp`, and required structured `metadata`: `{ type: "instruction" | "auto-compaction-continuation", version: 1 }`. They remain model-visible and recoverable. The normal TUI hides them, while searchable conversation history includes them as system entries. Tau metadata is removed before provider dispatch. Text-block arrays, named sections, and tool additions or removals are not supported in system messages.
+The first system message is the persona's base prompt. Later system messages are history records, in order, with plain-text `content`, a `timestamp`, and required `metadata`: `{ type: "instruction" | "auto-compaction-continuation", version: 1 }`. The model sees them and they are recoverable. The TUI hides them, and searchable history includes them as system entries. Tau metadata is removed before sending to the provider. System messages cannot contain text-block arrays, named sections, or tool changes.
 
-Intermediate instructions are committed without a user turn receipt. Their durable append uses the `system-message` delta cause and does not require a timeline item. The initial prompt has no intermediate-message metadata; recovery restores subsequent instructions without duplicating that base prompt. There is no public insertion method or automatic conversion of user-authored `<system>` text.
+These later system messages are added without a turn record. Adding one uses the `system-message` delta cause and needs no timeline item. The base prompt has no such metadata, and recovery restores later instructions without duplicating it. Clients cannot insert system messages, and a user's `<system>` text is never turned into one.
 
-Turn requests return a terminal outcome, and accepted user turns are also keyed by `userHistoryEntryId` in `snapshot.turns`. Use that ledger to distinguish an unknown request from accepted running work and settled work. Do not infer request outcomes from notice titles, message counts, or timing.
+Turn requests return a final outcome, and each accepted user turn is also recorded in `snapshot.turns`, keyed by `userHistoryEntryId`. Use this record to tell an unknown request apart from accepted work that is running or finished. Never infer outcomes from notice titles, message counts, or timing.
 
 User-facing behavior such as retry, compaction, rewind, and recovery is described in [sessions](sessions.md).
 
@@ -152,17 +152,17 @@ Observed snapshot changes arrive as `session.delta`:
 }
 ```
 
-For a patch, `fromRevision` must equal the installed snapshot revision and `toRevision` becomes the new revision. Apply every `changes` entry atomically and in order. Changes can set scalar state, append or replace messages, append streamed content, update the timeline, or set and remove keyed tools, operations, agents, turns, and facets.
+For a patch, `fromRevision` must equal your current snapshot revision, and `toRevision` becomes the new one. Apply all `changes` in order, as one unit. Changes can set scalar state, append or replace messages, append streamed content, update the timeline, or set and remove keyed tools, operations, agents, turns, and facets.
 
-`snapshot.reset` carries a complete replacement snapshot. Reset causes identify `compaction`, `rewind`, or `resync`; compaction and rewind include the timeline data needed to validate the transition. Use the structured cause rather than inferring destructive transitions from content.
+`snapshot.reset` carries a complete new snapshot. Its cause is `compaction`, `rewind`, or `resync`, and compaction and rewind include the timeline data needed to validate the change. Use the cause; never guess at a destructive change from the content.
 
-If a patch has an unexpected `fromRevision`, or applying any change would produce invalid references or ordering, stop applying deltas and call `session.snapshot`. Deltas whose `toRevision` is already installed are stale and must not replay client presentation transitions.
+If a patch has an unexpected `fromRevision`, or a change would leave invalid references or ordering, stop applying deltas and call `session.snapshot`. A delta whose `toRevision` you already have is stale; do not replay its effects in the UI.
 
 Node clients can use `applySessionProtocolDelta`, which validates session identity, revision continuity, timeline rules, references, and the resulting snapshot.
 
 ## Maintain the independent live-state channels
 
-Not all observed state belongs in the recoverable snapshot. Each live channel has its own revision or delivery semantics.
+Some live state is not part of the snapshot. Each of these channels has its own revision or delivery rules.
 
 ### Pending user messages
 
@@ -183,23 +183,23 @@ Not all observed state belongs in the recoverable snapshot. Each live channel ha
 }
 ```
 
-Replace the complete pending list only when its revision is newer. Pending revisions are independent of snapshot revisions. This state is shared by observers while the hosted session remains in memory, but it starts empty after recovery.
+Replace the whole list, but only when the revision is newer. These revisions are separate from snapshot revisions. All observers share this state while the session is loaded on the host. It is empty after recovery.
 
 ### Subagent activities
 
 `session.subagentActivities` carries an independent `revision` and a list of changes. `agent.set` replaces that agent's complete current-run activity list; `agent.remove` deletes it. Apply changes only when the message revision is newer than the installed activity revision. The observe result provides the complete baseline.
 
-Activity lists contain bounded assistant text, settled tool presentations, and notices. They are transient supervision state, not a substitute for `snapshot.agents`, and they start empty after recovery.
+Activity lists contain limited assistant text, finished tool cards, and notices. They are live progress information, do not replace `snapshot.agents`, and are empty after recovery.
 
 ### Ephemeral events
 
-`session.ephemeral` carries best-effort live events with no channel revision:
+`session.ephemeral` carries live events that are not guaranteed and have no revision:
 
-- `feedback.notice` is temporary footer feedback.
-- `ephemeral-agent.thread-update` reports live progress for an ephemeral context and thread.
-- `timeline.item` is a non-recoverable notice with an active timeline epoch and allocated sequence.
+- `feedback.notice` is short-lived footer feedback.
+- `ephemeral-agent.thread-update` reports progress of an ephemeral context and thread.
+- `timeline.item` is a notice that is not saved, with a timeline epoch and sequence number.
 
-A `timeline.item` can be merged into current presentation only when its epoch matches the installed snapshot. Discard old-epoch items after compaction and post-cutoff items after rewind. Missing ephemeral events do not require resynchronization.
+Show a `timeline.item` only if its epoch matches your snapshot. After compaction, drop items from the old epoch; after rewind, drop items past the rewind point. Missing ephemeral events never require a resync.
 
 ## Delegate client tools
 
@@ -219,11 +219,11 @@ An initialized client that advertised a tool can receive:
 }
 ```
 
-Acknowledge promptly with `session.clientTool.ack`, optionally including a bounded partial running presentation. Begin execution only after the acknowledgement returns `{ accepted: true }`, then send exactly one `session.clientTool.result` with either `{ ok: true, content }` or `{ ok: false, error }` and an optional independent terminal presentation. Successful `content` is an ordered array of text/image blocks. Both presentation objects may contain `subject`, `subjectWrap`, `details`, and `metadata`; the host owns action and operation and supplies every omitted field. Explicit fields are preserved unchanged after protocol safety validation, while generated defaults use Tau's canonical display truncation. Empty detail or metadata arrays suppress those defaults.
+Acknowledge promptly with `session.clientTool.ack`, optionally with a partial presentation for the running tool card. Start work only after the acknowledgement returns `{ accepted: true }`. Then send exactly one `session.clientTool.result` with `{ ok: true, content }` or `{ ok: false, error }`, optionally with a separate presentation for the finished card. `content` is an ordered array of text and image blocks. Both presentations may contain `subject`, `subjectWrap`, `details`, and `metadata`. The host sets the action and operation and fills in omitted fields. Fields you set are kept unchanged once they pass validation, while defaults are truncated the way Tau truncates its own cards. An empty `details` or `metadata` array hides that default.
 
-A successful result is rejected until acknowledgement has completed. If preparation itself fails, send an error result before acknowledgement; the host records it as a preparation failure without authorizing execution. If no result arrives because of timeout, cancellation, detach, or another failure, the host renders a complete fallback terminal presentation. The result method returns `{ accepted: boolean }`; `false` means the message is invalid for the call's current state or the call is no longer waiting for it.
+A successful result is rejected until the acknowledgement has completed. If preparation fails, send an error result before acknowledging; the host records a preparation failure and the tool never runs. If no result arrives, because of a timeout, cancellation, detach, or other failure, the host shows a complete default card. The result method returns `{ accepted: boolean }`; `false` means the result does not fit the call's current state or the call no longer expects it.
 
-`session.clientTool.cancel` names the session and call with reason `aborted`, `timeout`, `client-detached`, or `host-failed`. Abort local work and do not send a late result. The SDK implements this lifecycle automatically. Tool execution authority and the execution-environment facade are covered in [client tools](client-tools.md).
+`session.clientTool.cancel` names the session and call, with reason `aborted`, `timeout`, `client-detached`, or `host-failed`. Stop local work and do not send a result. The SDK handles all of this for you. Permissions and execution-environment access for client tools are covered in [client tools](client-tools.md).
 
 ## Handle errors and terminal transport failure
 
@@ -255,19 +255,19 @@ The supported codes are:
 | `cancelled` | Pending input, execution, or sampling was cancelled. |
 | `internal_error` | The host could not complete the operation. |
 
-When no valid request id can be recovered, an error response uses `id: null`. Error `message` and optional `data` are diagnostic. Branch on `code`, not message text.
+When the request ID cannot be read, the error response uses `id: null`. The error `message` and optional `data` are for diagnostics. Branch on `code`, never on message text.
 
-A WebSocket close, malformed server payload, unsupported version, or other terminal transport failure rejects all outstanding requests. Stop sending, cancel client-local delegated tools, and reconnect or create a new transport deliberately. A WebSocket disconnect detaches from the long-running host.
+A WebSocket close, a malformed server message, an unsupported version, or another fatal transport failure rejects all open requests. Stop sending, cancel running client tools, and reconnect or create a new transport on purpose. A WebSocket disconnect only detaches from the long-running host.
 
 ## Coordinate concurrent work
 
-The server can accept several requests before earlier requests settle, so responses and streamed messages may interleave.
+The server accepts new requests before earlier ones finish, so responses and streamed messages can interleave.
 
 - Only one main-session turn runs at a time. `session.submit` and `session.retry` return `busy` on conflict.
-- `session.queue` waits for idle work. `session.steer` requests the next safe turn boundary. Each request receives its own eventual response.
-- Session mutations are serialized in arrival order across clients. Mutations that replace context can interrupt active work and reject pending input. `session.rewind` instead requires the session to be idle with no pending input.
-- `session.setReasoning` is serialized but does not interrupt the active turn. The new setting applies to the next independently started turn.
-- `session.exec` and `session.sample` are side channels. They can overlap turns, mutations, each other, and ephemeral agents. Clients own workspace coordination.
-- Ephemeral contexts run outside the main mutation queue. Two submissions to the same ephemeral thread conflict, while different threads can run independently.
+- `session.queue` waits until the session is idle. `session.steer` joins the running turn at its next safe point. Each request gets its own response when done.
+- Session changes run one at a time, in arrival order across all clients. Changes that replace the context can interrupt running work and reject pending input. `session.rewind` instead requires an idle session with no pending input.
+- `session.setReasoning` waits its turn but does not interrupt the running turn. The new setting applies from the next turn.
+- `session.exec` and `session.sample` run alongside everything else: turns, other changes, each other, and ephemeral agents. Clients must coordinate their own use of the workspace.
+- Ephemeral contexts are not part of that one-at-a-time ordering. Two submissions to the same ephemeral thread conflict, while different threads can run at once.
 
-Do not assume a success response arrives before the deltas caused by that request. Maintain state from the observed streams, correlate completion by request id, and use `session.snapshot` when continuity is uncertain.
+A success response may arrive before or after the deltas the request caused. Keep state from the observed streams, match completion by request ID, and call `session.snapshot` when unsure whether you missed something.