@markusylisiurunen/tau 0.3.50 → 0.3.52

package/dist/core/static/tau_docs/client-tools.md

@@ -117,23 +117,222 @@ Diff-tool launcher settings are separate from command client-tool definitions. T
 
 ## Implement a command tool with Tau's helper
 
-Command client tools use Tau's version 3 bidirectional NDJSON protocol over stdin and stdout. Use the exported helper instead of implementing framing manually:
+Command client tools use Tau's version 4 bidirectional NDJSON protocol over stdin and stdout. Use the exported helper instead of implementing framing manually:
 
 ```ts
-import { runTauClientToolCommand } from "@markusylisiurunen/tau/code-mode";
+import {
+  runTauClientToolCommand,
+  truncateTauClientToolText,
+} from "@markusylisiurunen/tau/code-mode";
+
+await runTauClientToolCommand({
+  name: "notify_desktop",
+  describe(args) {
+    const input = args as { title: string; message: string };
+    return {
+      subject: truncateTauClientToolText(input.title),
+    };
+  },
+  async execute(args, context) {
+    const input = args as { title: string; message: string };
+    context.signal.throwIfAborted();
+
+    await showNotification(input.title, input.message, context.signal);
+    return {
+      content: "Notification displayed.",
+      presentation: {
+        subject: truncateTauClientToolText(input.title),
+      },
+    };
+  },
+});
+```
+
+`describe` is optional. When present, it runs before acknowledgement and may return a partial running presentation containing `subject`, `subjectWrap`, `details`, or `metadata`. The execution result may independently include the same partial shape for the terminal card. Tau supplies every omitted field, owns lifecycle actions and the operation derived from the registered tool name, and renders a complete fallback when execution ends without a result.
+
+Tau preserves every explicit presentation field up to the protocol safety limits; it does not apply display truncation or normalize client text. `truncateTauClientToolText` provides optional caller-controlled `maxLines`, `maxLineChars`, and `head` or `middle` truncation. Its defaults match Tau's concise subject policy, but callers may select larger or smaller positive limits.
+
+For a subject, use the returned string directly. For a block of detail text, split the returned string on `\n` and map each line to one `details` entry:
+
+```ts
+const details = truncateTauClientToolText(output, {
+  maxLines: 7,
+  maxLineChars: 512,
+  strategy: "middle",
+})
+  .split("\n")
+  .map((text) => ({ text }));
+```
+
+Each detail or metadata entry is a single protocol line, so use `maxLines: 1` when assigning the helper's result directly to one entry. The helper shapes text for presentation; the protocol byte and collection limits still apply. Empty detail or metadata arrays explicitly suppress that phase's defaults.
+
+`runTauClientToolCommand` reads the preparation, writes readiness and any running presentation, waits until the host accepts the call, then provides the standard execution context and writes the final result. It handles execution-environment request and cancellation framing and reacts to `SIGINT`, `SIGTERM`, and protocol input closure by aborting the handler.
+
+Reserve stdout for the helper's protocol. Write diagnostics to stderr. Return a string or `{ content, presentation? }` for success. Return `{ ok: false, error, presentation? }` for a structured tool failure. Successful content and failure text become model-visible tool results.
+
+### Version 4 frame reference
+
+The shapes below use TypeScript notation. Serialize each frame as one exact JSON object followed by a newline; unknown fields are invalid.
 
-await runTauClientToolCommand(async (args, context) => {
-  const input = args as { title: string; message: string };
-  context.signal.throwIfAborted();
+Tau starts the exchange by writing:
 
-  await showNotification(input.title, input.message, context.signal);
-  return { content: "Notification displayed." };
+- `{ version: 4, type: "prepare", sessionId, agentId, callId, toolName, arguments }` exactly once. The identity fields are non-empty strings and `arguments` is the validated model input.
+- `{ version: 4, type: "execute" }` after accepting the command's ready frame. This authorizes execution.
+
+The command writes:
+
+- `{ version: 4, type: "ready", presentation?: PresentationOverride }` exactly once after preparation.
+- `{ version: 4, type: "result", ok: true, content, presentation?: PresentationOverride }` or `{ version: 4, type: "result", ok: false, error, presentation?: PresentationOverride }` exactly once after authorization. `content` and `error` are strings.
+
+During authorized execution, the command may write `{ version: 4, type: "exec", requestId, command, options }`. The non-empty `command` string runs in the session execution environment. `options` is required and may contain `args: string[]`, `env: Record<string, string>`, base64-encoded string `stdinBase64`, string `cwd`, positive integer `timeoutMs`, and positive integer `maxCaptureBytes`.
+
+Tau answers with the same `requestId` and either:
+
+- `{ version: 4, type: "exec.result", requestId, ok: true, result: ExecResult }`
+- `{ version: 4, type: "exec.result", requestId, ok: false, error: string }`
+
+`ExecResult` contains string `output`, `stdout`, and `stderr`; nullable `exitCode` and `closeSignal`; and boolean `truncated`, `timedOut`, and `aborted`. A command may cancel one unresolved request with `{ version: 4, type: "exec.cancel", requestId }`. Request IDs must be non-empty strings and cannot be reused within a call.
+
+### Implement the protocol directly in JavaScript
+
+A JavaScript command can implement the version 4 handshake using only Node.js built-ins, without importing Tau or the code-mode package:
+
+```js
+#!/usr/bin/env node
+
+import { arch, platform, release } from "node:os";
+import { createInterface } from "node:readline";
+
+const lines = createInterface({
+  input: process.stdin,
+  crlfDelay: Number.POSITIVE_INFINITY,
 });
+const input = lines[Symbol.asyncIterator]();
+
+async function readFrame() {
+  const next = await input.next();
+  if (next.done) throw new Error("Tau closed the command protocol");
+  return JSON.parse(next.value);
+}
+
+function writeFrame(frame) {
+  process.stdout.write(`${JSON.stringify(frame)}\n`);
+}
+
+const prepare = await readFrame();
+if (
+  prepare.version !== 4 ||
+  prepare.type !== "prepare" ||
+  prepare.toolName !== "system_info"
+) {
+  throw new Error("Invalid system_info preparation");
+}
+
+writeFrame({
+  version: 4,
+  type: "ready",
+  presentation: {
+    subject: "local system",
+  },
+});
+
+const execute = await readFrame();
+if (execute.version !== 4 || execute.type !== "execute") {
+  throw new Error("Invalid system_info authorization");
+}
+
+writeFrame({
+  version: 4,
+  type: "exec",
+  requestId: "git-status",
+  command: "git status --short",
+  options: {
+    maxCaptureBytes: 256 * 1024,
+  },
+});
+
+const response = await readFrame();
+if (
+  response.version !== 4 ||
+  response.type !== "exec.result" ||
+  response.requestId !== "git-status"
+) {
+  throw new Error("Invalid execution-environment response");
+}
+if (!response.ok) throw new Error(response.error);
+
+const localSystem = `${platform()} ${release()} ${arch()}`;
+const workspaceStatus =
+  response.result.output.trim() || "Working tree is clean.";
+writeFrame({
+  version: 4,
+  type: "result",
+  ok: true,
+  content: `${localSystem}\n\n${workspaceStatus}`,
+  presentation: {
+    subject: "local system",
+  },
+});
+
+lines.close();
 ```
 
-`runTauClientToolCommand` reads the invocation, provides a standard context, handles execution-environment request and cancellation framing, and writes the final result. It also reacts to `SIGINT`, `SIGTERM`, and protocol input closure by aborting the handler.
+The `exec` frame asks Tau to run `git status --short` in the session execution environment, which may be a different machine from the JavaScript process. Tau returns the matching `exec.result` on stdin. Request IDs are single-use, and the command must check both the ID and `ok` before consuming the result.
+
+Make the file executable with `chmod +x`. Diagnostics and uncaught errors go to stderr; stdout remains reserved for protocol frames.
+
+### Implement a simple command tool in Bash
+
+A small command that needs only client-machine authority can also implement the handshake in Bash. This example depends on `jq` for safe JSON parsing and encoding:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+IFS= read -r prepare
+jq -e '
+  .version == 4 and
+  .type == "prepare" and
+  .toolName == "system_info"
+' >/dev/null <<<"$prepare"
+
+jq -cn '{
+  version: 4,
+  type: "ready",
+  presentation: {
+    subject: "local system"
+  }
+}'
+
+IFS= read -r execute
+jq -e '.version == 4 and .type == "execute"' >/dev/null <<<"$execute"
+
+content=$(uname -a)
+jq -cn --arg content "$content" '{
+  version: 4,
+  type: "result",
+  ok: true,
+  content: $content
+}'
+```
+
+Configure either executable as an argument-free command tool:
+
+```json
+{
+  "name": "system_info",
+  "defaultEnabled": true,
+  "description": "Report operating-system information from the client machine.",
+  "parameters": {
+    "type": "object",
+    "properties": {},
+    "additionalProperties": false
+  },
+  "command": "./bin/tau-system-info"
+}
+```
 
-Reserve stdout for the helper's protocol. Write diagnostics to stderr. Return either a string or `{ content: string }`; that text becomes the model-visible tool result.
+Both `ready.presentation` and `result.presentation` are optional partial objects with `subject`, `subjectWrap`, `details`, and `metadata`. The ready value applies while the call runs; the result value applies only to its terminal state. Omit either object, or any field within it, to use Tau's default for that phase. Empty `details` or `metadata` arrays suppress the corresponding default field. The script must emit `ready` before reading the authorization-bearing `execute` frame. Direct implementations can emit the same `exec` frames shown in the JavaScript example, but the TypeScript helper is preferable when the tool needs multiple target-environment requests, cancellation forwarding, or more involved protocol handling.
 
 The handler receives:
 
@@ -181,7 +380,7 @@ Tau exports two higher-level helpers for client tools that expose a bounded Java
 
 For an executable configured through `clientTools`, keep the exact parameters schema to one required `code` string with no additional properties, then call `runTauCodeModeCommand` in the executable. For SDK clients, pass the returned tool from `createTauCodeModeClientTool` in the client's `clientTools` array.
 
-Both helpers supply the invocation identities, cancellation signal, execution-environment facade, progressive `docs` value, bounded API bridge, and agent-scoped scratch files. The model-facing description remains explicit caller input. Use Tau's optional shared description builder only when its progressive-disclosure wording fits the tool; Tau does not silently rewrite a configured description.
+Both helpers supply the invocation identities, cancellation signal, execution-environment facade, progressive `docs` value, bounded API bridge, and agent-scoped scratch files. They use the submitted code, concisely truncated and character-wrapped, as the running and terminal tool-card subject. The model-facing description remains explicit caller input. Use Tau's optional shared description builder only when its progressive-disclosure wording fits the tool; Tau does not silently rewrite a configured description.
 
 The generic code-mode runtime is documented through its exported types and generated tool documentation. Do not layer another unbounded process or network channel behind it without making that authority clear in the tool description.
 
@@ -195,12 +394,13 @@ The command protocol is intentionally bounded:
 - Captured stderr is limited to 1 MiB. Exceeding it terminates the command and fails the tool.
 - Execution-environment stdin is limited to 16 MiB decoded, and capture can be requested up to 24 MiB per execution.
 - At most eight execution requests may be unresolved concurrently.
+- Each client-tool presentation override is limited to 1 MiB in total. Its subject is limited to 256 KiB; metadata values to 16 KiB each; detail values to 256 KiB each; and detail and metadata collections to 1,024 entries each. These are safety limits, not recommended UI sizes. Tau preserves explicit values within those limits. Clients may use the exported helper when they want a concise preview.
 
-The configured `executionTimeoutMs` covers the whole command invocation and defaults to 60 seconds. The host also requires the owning client to acknowledge a dispatched call promptly. Standard Tau SDK clients handle acknowledgement before invoking the tool handler.
+The configured `executionTimeoutMs` covers preparation and execution and defaults to 60 seconds. The host also requires the owning client to prepare and acknowledge a dispatched call promptly. Command executables emit readiness and any bounded running presentation before acknowledgement, then wait for Tau to authorize execution.
 
 Tau starts each configured command in a detached process group. Cancellation sends termination to the group and escalates to `SIGKILL` after a short grace period, even if the original group leader exits first. The helper aborts pending execution-environment requests and stops accepting work when stdin closes.
 
-A successful command must exit with status zero after producing one final version 3 result. Missing results, malformed framing, data after the result, reused execution request IDs, nonzero exit, timeout, cancellation, excessive output, and protocol-limit violations fail the call. Stderr is included in failure diagnostics but is not a successful result channel.
+A successful protocol exchange must emit one version 4 ready frame, wait for the execute frame, emit one final version 4 result with `ok: true` or `ok: false`, and exit with status zero. An `ok: false` frame is a communicated tool failure; process and framing failures still use stderr and a nonzero exit. Missing or duplicate readiness, execution data before authorization, missing results, malformed framing, data after the result, reused execution request IDs, timeout, cancellation, excessive output, and protocol-limit violations fail the call.
 
 ## Disconnects, reconnects, and durability
 

package/dist/core/static/tau_docs/config-reference.md

@@ -222,7 +222,7 @@ A global-only remote history target:
 
 | Nested field | Type | Required | Contract |
 | --- | --- | --- | --- |
-| `endpoint` | Non-empty string | Yes | HTTP(S) URL with no query or fragment |
+| `endpoint` | Non-empty string | Yes | HTTP(S) URL with no credentials, query, or fragment |
 | `apiKey` | Non-empty string | No | Inline service API key |
 | `apiKeyEnv` | Non-empty string | No | Host environment variable containing the key |
 

package/dist/core/static/tau_docs/configuration.md

@@ -185,7 +185,7 @@ Restart the host process to apply settings used to construct host-wide services,
 - `history`
 - host environment variables and Codex account forcing
 
-For `tau serve` or `tau rpc`, make the changes on the host machine and restart that server. Restarting only an attached TUI does not rebuild the host.
+For `tau serve`, make the changes on the host machine and restart the server. Restarting only an attached TUI does not rebuild the host.
 
 ### New session or runner
 

package/dist/core/static/tau_docs/credentials.md

@@ -19,10 +19,10 @@ Common cases are:
 | Nook host tool | Session host |
 | Cloudflare Sandbox bridge and Fly Sprite API | Session host startup |
 | `/listen` and `/speak` | TUI client |
-| Telegram transcription | Telegram runner |
+| Telegram transcription and voice responses | Telegram runner |
 | `tau tool pdf-unpack` | The process running that command |
 
-With local `tau`, these roles normally share one machine. With `tau attach`, setting a key only in the attached client's shell does not authenticate the remote host. Run `tau auth` on the host machine and set host-owned environment variables where `tau serve`, `tau rpc`, or the SDK host actually runs. See [ownership and scope](ownership-and-scope.md) for the full boundary.
+With local `tau`, these roles normally share one machine. With `tau attach`, setting a key only in the attached client's shell does not authenticate the remote host. Run `tau auth` on the host machine and set host-owned environment variables where `tau serve` or the SDK host actually runs. See [ownership and scope](ownership-and-scope.md) for the full boundary.
 
 ## Provider API keys
 
@@ -61,12 +61,12 @@ Several Tau features share provider credentials but intentionally prefer a fixed
 | Feature | Resolution order |
 | --- | --- |
 | Exa web search and fetch | `EXA_API_KEY`, then `apiKeys.exa` |
-| Google speech, Gemini speech-to-text, and Telegram Gemini transcription | `GEMINI_API_KEY`, then `apiKeys.google` |
+| Google speech, Gemini speech-to-text, Telegram Gemini transcription, and Telegram voice responses | `GEMINI_API_KEY`, then `apiKeys.google` |
 | Mistral speech-to-text, Telegram Mistral transcription, and PDF OCR | `MISTRAL_API_KEY`, then `apiKeys.mistral` |
 
 The Google and Mistral rows describe feature-specific helpers. Model calls follow the general model-authentication order instead, where the configured provider key wins over ambient environment authentication.
 
-`web.discover` does not require Exa. `web.search` and `web.fetch` do. `/speak` uses Google. `/listen` and Telegram audio use the configured `speechToText.provider`, which is `mistral` unless configuration selects `gemini`. PDF OCR through `tau tool pdf-unpack` uses Mistral.
+`web.discover` does not require Exa. `web.search` and `web.fetch` do. `/speak` and Telegram `/tts_on` voice responses use Google. `/listen` and incoming Telegram audio use the configured `speechToText.provider`, which is `mistral` unless configuration selects `gemini`. PDF OCR through `tau tool pdf-unpack` uses Mistral.
 
 Set these variables on the process that owns the feature. For example, a remote TUI's `/speak` reads the attached client's `GEMINI_API_KEY`, while a Google model selected by the session reads credentials at the host.
 

package/dist/core/static/tau_docs/history.md

@@ -12,7 +12,7 @@ Every Tau host opens a machine-local SQLite database at:
 ~/.config/tau/history.sqlite
 ```
 
-The path belongs to the **host home**. An attached TUI and a remote execution environment do not get separate history stores merely because they participate in the session. Local `tau`, `tau serve`, `tau rpc`, and the default SDK host all use the host machine's database.
+The path belongs to the **host home**. An attached TUI and a remote execution environment do not get separate history stores merely because they participate in the session. Local `tau`, `tau serve`, and the default SDK host all use the host machine's database.
 
 For each session, history stores its immutable creation attributes and an ordered active transcript containing:
 
@@ -99,7 +99,7 @@ Remote history is accepted only in the host's eligible global Tau config, normal
 }
 ```
 
-`endpoint` must be an HTTP or HTTPS URL without a query or hash. Tau removes trailing slashes. The API key resolves on the host in this order:
+`endpoint` must be an HTTP or HTTPS URL without credentials, a query, or a hash. Tau removes trailing slashes. The API key resolves on the host in this order:
 
 1. `TAU_HISTORY_API_KEY`
 2. the host environment variable named by `history.apiKeyEnv`
@@ -118,7 +118,9 @@ Remote replication is local-first:
 3. The host sends pending operations to the configured endpoint asynchronously.
 4. Successful acknowledgements remove those operations from the outbox.
 
-A service outage does not block session execution or local transcript capture. Pending operations remain durable and are retried when replication is scheduled again, including after host restart or later history activity. The remote service applies operations idempotently and in order.
+A service outage does not block session execution or local transcript capture. Pending operations remain durable and are retried when replication is scheduled again, including after host restart or later history activity. The remote service applies operations idempotently. Tau preserves operation order within each session while processing separate session lanes independently.
+
+A permanent operation-domain rejection, such as conflicting immutable session metadata, quarantines only that session's replication lane. Its pending operations and diagnostic remain in local SQLite, later operations for that session stay blocked, and unrelated sessions continue replicating. Transient transport, authentication, rate-limit, and service failures do not quarantine a lane; they leave endpoint replication pending for a later retry. Both kinds of failure produce a structured `history_replication_failed` host log without exposing the API key.
 
 Local entries retain their complete captured payloads. For remote replication, an entry larger than 1 MiB keeps its identity and metadata but middle-truncates oversized content, arguments, or results with an explicit marker. Remote history is therefore useful for retrieval, but the host's local entry can contain details that the shared copy intentionally omits.
 
@@ -144,7 +146,7 @@ Cloudflare operational failures are visible through normal Worker logs, Cron Eve
 
 **The history tool returns a service error while the session still works.** Remote queries and asynchronous replication can fail independently of session execution. Check endpoint reachability and Worker logs without printing the bearer key. Local capture should continue unless the session also contains a `history unavailable` warning.
 
-**A session does not appear in remote search.** Confirm that the host was restarted with the global remote config, that the session was opened while that target was active, and that later history activity has had a chance to flush the durable outbox. Do not assume remote digests are immediate.
+**A session does not appear in remote search.** Confirm that the host was restarted with the global remote config, that the session was opened while that target was active, and that later history activity has had a chance to flush the durable outbox. Check host logs for `history_replication_failed`; a quarantined failure affects only the named session, while an unquarantined endpoint failure remains retryable. Do not assume remote digests are immediate.
 
 **Local history became unavailable.** Check host-side filesystem access, free space, and ownership for `~/.config/tau`. Restarting is required to reopen a manager disabled by an earlier local failure.
 

package/dist/core/static/tau_docs/index.md

@@ -34,7 +34,7 @@ The intrinsic `tau_docs` tool reads one exact Markdown path at a time. It does n
 
 - [Tools](tools.md) explains built-in tool availability, execution, cancellation, and code-mode tools.
 - [Sessions](sessions.md) covers creation, turns, queueing, compaction, rewind, goals, recovery, and persistence.
-- [Remote sessions](remote-sessions.md) explains `serve`, `rpc`, `attach`, remote paths, and transport authentication.
+- [Remote sessions](remote-sessions.md) explains `serve`, `attach`, remote paths, and transport authentication.
 - [History](history.md) covers local transcript history, optional remote replication, and the history tool.
 - [Nook](nook.md) explains configuration and operation of the optional static mini-app platform.
 - [Telegram](telegram.md) covers runner configuration, projects, workspaces, routing, and recovery.

package/dist/core/static/tau_docs/node-sdk.md

@@ -1,6 +1,6 @@
 # Node SDK
 
-Tau's Node SDK provides a typed client for creating, observing, and controlling sessions without implementing the wire protocol directly. Use the in-process client when your application should own the host, the WebSocket client for a long-running `tau serve` host, or the transport adapter when another process owns the connection.
+Tau's Node SDK provides a typed client for creating, observing, and controlling sessions without implementing the wire protocol directly. Use the in-process client when your application should own the host, the WebSocket client for a long-running `tau serve` host, or the transport adapter with a custom connection implementation.
 
 The SDK uses the same public [session protocol](session-protocol.md) as the TUI. Session behavior is therefore consistent across local applications, remote integrations, and terminal clients.
 
@@ -74,23 +74,7 @@ WebSocket authentication grants full session access. Deployment and TLS guidance
 
 ### Supply a protocol transport
 
-`createTauSdkClientFromTransport(transport, options?)` builds the same client facade over any `SessionProtocolTransport`. Tau exports `StdioSessionProtocolTransport` for a spawned `tau rpc` process:
-
-```ts
-import { spawn } from "node:child_process";
-import {
-  StdioSessionProtocolTransport,
-  createTauSdkClientFromTransport,
-} from "@markusylisiurunen/tau/sdk";
-
-const child = spawn("tau", ["rpc"], {
-  stdio: ["pipe", "pipe", "pipe"],
-});
-const transport = new StdioSessionProtocolTransport(child);
-const client = await createTauSdkClientFromTransport(transport);
-```
-
-The stdio transport owns the supplied process connection and terminates it on close. Stdout must contain only protocol NDJSON; stderr is retained for bounded process diagnostics.
+`createTauSdkClientFromTransport(transport, options?)` builds the same client facade over any `SessionProtocolTransport`. This keeps the SDK facade independent of WebSocket and allows applications to supply another transport without changing session semantics.
 
 A custom transport implements:
 
@@ -295,6 +279,11 @@ If rendering `timeline.item`, accept only the active epoch and merge by its allo
 Pass `TauSdkClientTool` entries in `clientTools` when model-facing work must run in the integration process:
 
 ```ts
+import {
+  createTauSdkClient,
+  truncateTauClientToolText,
+} from "@markusylisiurunen/tau/sdk";
+
 const client = await createTauSdkClient({
   clientTools: [
     {
@@ -303,12 +292,22 @@ const client = await createTauSdkClient({
         description: "Choose one item from the user's local workspace.",
         parameters: {
           type: "object",
-          properties: {},
+          properties: {
+            choice: { type: "string" },
+          },
+          required: ["choice"],
           additionalProperties: false,
         },
         executionTimeoutMs: 60_000,
       },
-      execute: async (_args, context) => {
+      describe: (args) => {
+        const input = args as { choice: string };
+        return {
+          subject: truncateTauClientToolText(input.choice),
+        };
+      },
+      execute: async (args, context) => {
+        const input = args as { choice: string };
         context.signal.throwIfAborted();
         const status = await context.executionEnvironment.exec(
           "git status --short",
@@ -316,7 +315,12 @@ const client = await createTauSdkClient({
             signal: context.signal,
           },
         );
-        return status.output || "Working tree is clean.";
+        return {
+          content: status.output || "Working tree is clean.",
+          presentation: {
+            subject: truncateTauClientToolText(input.choice),
+          },
+        };
       },
     },
   ],
@@ -325,7 +329,11 @@ const client = await createTauSdkClient({
 
 The handler receives `sessionId`, owning `agentId`, `callId`, an `AbortSignal`, and an execution-environment facade. The handler itself runs on the client machine. `context.executionEnvironment.exec()` crosses the session boundary and runs in the session execution environment.
 
-The SDK acknowledges delegated calls, converts a returned string or `{ content }` to the wire result, reports thrown errors, and aborts handlers on host cancellation, client close, or terminal transport failure. `client.close()` waits for active handlers to settle.
+`describe` is optional. When present, the SDK calls it with the arguments and a reduced context containing `sessionId`, `agentId`, `callId`, and `signal` before acknowledgement. This context deliberately has no execution-environment facade. It may return a partial running presentation containing `subject`, `subjectWrap`, `details`, or `metadata`. Tau owns action and operation, fills every omitted field, and acknowledges the resolved presentation before calling `execute`.
+
+The execution result may independently include the same partial shape for the terminal card. Return a string or `{ content, presentation? }` for success, or `{ ok: false, error, presentation? }` for a structured failure. Omitted presentation fields use Tau's terminal defaults; empty detail or metadata arrays suppress those defaults. If `describe` throws, the SDK reports a preparation error without calling `execute`. If the client never returns a result because of cancellation, timeout, detach, or another failure, the host produces a complete fallback presentation.
+
+Tau preserves every explicit presentation field up to the protocol safety limits; it does not apply display truncation or normalize client text. `truncateTauClientToolText` provides optional caller-controlled line, character, and head or middle truncation. Use its result directly for a subject. For a block of detail text, split the result on `\n` and map each line to one `details` entry; use `maxLines: 1` when assigning it directly to one detail or metadata entry. The helper shapes text but does not replace protocol validation. The SDK aborts handlers on host cancellation, client close, or terminal transport failure. `client.close()` waits for active handlers to settle.
 
 Tool definitions are frozen for each assistant turn and remain independent of persona tool allowlists. Names cannot collide with host tools or another observing client's tools. See [client tools](client-tools.md) for authority, limits, command-backed tools, and disconnect behavior.
 
@@ -353,7 +361,7 @@ const tickets = createTauCodeModeClientTool({
 });
 ```
 
-Pass `tickets` in `clientTools`. Generated code receives the declared API namespace, progressively disclosed `docs`, console output, live `Date` and `Math`, and agent-scoped scratch files when invoked as a client tool. API calls cross a bounded JSON bridge. The tool description remains explicit caller input; the builder is optional.
+Pass `tickets` in `clientTools`. Generated code receives the declared API namespace, progressively disclosed `docs`, console output, live `Date` and `Math`, and agent-scoped scratch files when invoked as a client tool. API calls cross a bounded JSON bridge. The submitted code appears, concisely truncated and character-wrapped, as the running and terminal tool-card subject. The tool description remains explicit caller input; the builder is optional.
 
 The SDK also exports `executeTauCodeMode` for standalone execution. The separate `@markusylisiurunen/tau/code-mode` entry point additionally exports file-capability types, `runTauClientToolCommand`, and `runTauCodeModeCommand` for command-backed tools. Use the helpers instead of implementing their framing manually.
 
@@ -361,7 +369,7 @@ The SDK also exports `executeTauCodeMode` for standalone execution. The separate
 
 Most turn and mutation methods do not accept an `AbortSignal`. Call `session.interrupt()` to cancel active host work. `session.exec()` is the exception: its optional signal targets only that execution.
 
-`session.unobserve()` retires one facade. `client.close()` retires the connection, rejects pending transport requests, aborts client-tool handlers, waits for them to settle, and then closes the transport. For the default in-process client it also persists sessions and shuts down the owned host. For WebSocket it leaves the remote host and sessions running. For stdio it closes the owned process connection.
+`session.unobserve()` retires one facade. `client.close()` retires the connection, rejects pending transport requests, aborts client-tool handlers, waits for them to settle, and then closes the transport. For the default in-process client it also persists sessions and shuts down the owned host. For WebSocket it leaves the remote host and sessions running.
 
 Always close clients in `finally`. Do not continue using a session facade after unobserve or any client after close.
 
@@ -371,7 +379,6 @@ All exported SDK and transport errors extend `TauSessionClientError`:
 
 - `TauSessionProtocolResponseError` means the host returned a protocol error. It exposes `code`, `message`, `requestId`, and optional `data`.
 - `TauTransportError` means connection setup, framing, version validation, timeout, closure, or another terminal transport operation failed.
-- `TauProcessError` extends `TauTransportError` for a stdio subprocess failure and includes `exitCode`, `signal`, and bounded `stderr`.
 
 Branch on a protocol error's `code`, not its message. A successful request can still return a failed, aborted, or blocked turn outcome, so inspect `result.turn.status` separately.
 
@@ -384,7 +391,7 @@ The SDK entry point exports the types needed at integration boundaries rather th
 - `TauSdkClient`, `TauSdkSession`, client option types, session summaries, and request and result aliases;
 - `TauSdkDelta`, `SessionProtocolSnapshot`, pending-message types, subagent-activity types, and ephemeral event types;
 - `TauSdkClientTool`, its execution context and environment facade, and code-mode definition and result types;
-- `SessionProtocolTransport`, listener types, WebSocket options, stdio process type, and transport errors.
+- `SessionProtocolTransport`, listener types, WebSocket options, and transport errors.
 
 It also exports `applySessionProtocolDelta`, `applySessionProtocolSubagentActivitiesMessage`, the turn-ledger helpers, and user-text projection helpers:
 

package/dist/core/static/tau_docs/ownership-and-scope.md

@@ -12,7 +12,7 @@ Client tools execute on the client machine, not wherever the agent's Bash tool r
 
 ### Host
 
-The **host** creates, observes, persists, and recovers sessions. It owns model calls, credentials, session orchestration, tool binding, history storage, and execution-environment lifecycle. Local `tau` creates an in-process host. `tau serve` and `tau rpc` are standalone host entry points.
+The **host** creates, observes, persists, and recovers sessions. It owns model calls, credentials, session orchestration, tool binding, history storage, and execution-environment lifecycle. Local `tau` creates an in-process host. `tau serve` is the standalone host entry point.
 
 The host's home owns data such as session snapshots, authentication storage, usage logs, and the local history database. Use Tau commands and session operations to manage these stores rather than editing their files directly.
 
@@ -38,10 +38,9 @@ For repository and composite projects it prepares managed workspaces. A configur
 | --- | --- | --- | --- |
 | `tau` | Local TUI process | In-process on the same machine | Local `cwd` where Tau started |
 | `tau attach … ws://…` | Machine running `tau attach` | Machine running `tau serve` | Environment selected or restored by that host |
-| `tau attach … -- <command>` | Machine running `tau attach` | Machine running the protocol command, often reached through SSH | Environment selected or restored by that host |
-| `tau rpc` or `tau serve` | A separate protocol client | The server process | Local or configured hosted environment chosen by the client |
+| `tau serve` | A separate protocol client | The server process | Local or configured hosted environment chosen by the client |
 | Default Node SDK client | SDK caller | In-process with the SDK caller | Usually a local environment supplied at session creation |
-| SDK over WebSocket or stdio | SDK caller | Remote server or command process | Environment selected or restored by that host |
+| SDK over WebSocket | SDK caller | Remote server | Environment selected or restored by that host |
 | `tau telegram` | Telegram runner | In-process on the runner machine | Prepared project workspace or persistent directory |
 
 A Cloudflare Sandbox or Fly Sprite can place the execution environment on another target while the host stays on its own machine. The host keeps provider credentials and orchestration authority; the target owns its paths and commands.

package/dist/core/static/tau_docs/prompts-and-project-context.md

@@ -139,7 +139,7 @@ tau --no-agent-context-files
 
 This disables ancestor `AGENTS.md` injection, configured `agentContextFiles`, and the descendant paths-only scan. It does not disable personas, prompt templates, or [skills](skills.md).
 
-The option applies to local TUI sessions and to hosts started with `tau rpc` or `tau serve`. For the Node SDK, `noAgentContextFiles: true` provides the same host-level behavior. An attached client cannot retroactively change how an existing remote host session was created.
+The option applies to local TUI sessions and to hosts started with `tau serve`. For the Node SDK, `noAgentContextFiles: true` provides the same host-level behavior. An attached client cannot retroactively change how an existing remote host session was created.
 
 ## Alternate subagent working directories
 
@@ -176,6 +176,6 @@ For a new local TUI session, debug mode prints discovered content, loaded contex
 tau --debug --persona release-coder
 ```
 
-Add `--no-agent-context-files` to verify the context-free variant. Debug mode is TUI startup functionality and is not available with `tau rpc` or `tau serve`.
+Add `--no-agent-context-files` to verify the context-free variant. Debug mode is TUI startup functionality and is not available with `tau serve`.
 
 If expected context is missing, verify the execution-environment `cwd` and `home`, not just the attached client's current directory. Then check exact filenames, canonical path eligibility, configuration-level path bases, scan exclusions, and reload warnings. See [troubleshooting](troubleshooting.md) for broader diagnostics.