@markusylisiurunen/tau 0.3.81 → 0.3.83

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

@@ -1,27 +1,27 @@
 # Client tools
 
-Client tools let an attached client contribute capabilities that the host does not own. A TUI can open a local review interface, a Telegram runner can invoke a workspace-specific command, and an SDK client can provide an in-process handler. The model sees an ordinary tool schema, but execution stays with the client that advertised it.
+Client tools are tools that an attached client adds to a session. A TUI can open a local review interface, a Telegram runner can run a workspace-specific command, and an SDK client can provide an in-process handler. The model sees an ordinary tool, but the tool runs in the client that offered it.
 
-This boundary matters in remote sessions. The client process, host, and execution environment may be three different machines. A command client tool starts on the client machine. If it needs to inspect or change the agent's workspace, it must use the provided execution-environment facade rather than assuming the same filesystem is locally mounted.
+In a remote session, the client, the host, and the execution environment may be three different machines. A command client tool starts on the client machine. To read or change the agent's workspace, it must use the execution-environment API that Tau provides. It cannot assume the workspace is on its own filesystem.
 
 ## Which client advertises which tools
 
 Tau's TUI advertises two built-in client tools:
 
-- `diff_review` runs the TUI-local diff review flow while capturing repository data through the session execution environment.
+- `diff_review` runs diff review on the TUI machine, reading repository data from the session's execution environment.
 - `prefill_input` puts a draft in an empty TUI editor for the user to edit and submit. It never submits the draft and does not replace existing editor text.
 
-The TUI also advertises the configured command client tools selected for its current client-side working directory. This is true for local `tau` and for `tau attach`. During remote attach, the command executable and its environment belong to the attaching machine, not the remote host.
+The TUI also offers the configured command client tools selected for its own working directory, both with local `tau` and with `tau attach`. When attached to a remote host, the command and its environment are on the attaching machine, not on the host.
 
-A Telegram runner advertises the built-in `send_photo_to_telegram`, `send_video_to_telegram`, `send_audio_to_telegram`, and `send_document_to_telegram` tools, plus the configured command client tools selected from each prepared workspace's Tau configuration. The built-in [file delivery tools](tools.md#sending-files-to-telegram) send files to the session's chat and are independent of `enabledClientTools`. It does not advertise TUI-only tools. Repository, persistent-directory, and composite workspace preparation determines the client-side configuration scope used for that Telegram session. See [Telegram](telegram.md) for workspace ownership.
+A Telegram runner offers the built-in `send_photo_to_telegram`, `send_video_to_telegram`, `send_audio_to_telegram`, and `send_document_to_telegram` tools, plus the command client tools selected by each prepared workspace's Tau configuration. The built-in [file delivery tools](tools.md#sending-files-to-telegram) send files to the session's chat and are not affected by `enabledClientTools`. The runner does not offer the TUI's tools. The session's workspace, whether repository, persistent directory, or composite, decides which configuration selects its tools. See [Telegram projects and workspaces](telegram-projects.md) for workspace types.
 
-Node SDK clients can supply `TauSdkClientTool` handlers directly when they initialize. The same session routing, cancellation, and execution-environment contracts apply.
+Node SDK clients can pass `TauSdkClientTool` handlers when they initialize. The same rules for routing, cancellation, and execution-environment access apply.
 
-Only an observing client can contribute tools to a session. The tools disappear when that client detaches or disconnects. If several clients observe one session, at most one may advertise a given client-tool name. Tau rejects the later attachment on a name collision. Client-tool names must also not collide with host or intrinsic tools.
+Only a client that is observing a session can add tools to it. The tools disappear when that client detaches or disconnects. When several clients observe one session, only one may offer a given tool name, and Tau rejects the later client if names collide. Client tool names also must not match host tools or built-in tools.
 
 ## Configure command client tools globally
 
-Executable client-tool definitions are accepted only from the global `~/.config/tau/config.json`, and that global level is in scope only when the client-side working directory is inside home. Project configuration cannot define executable commands. This prevents a checked-out repository from silently introducing a process that runs on the client machine.
+Client tool commands can be defined only in the global `~/.config/tau/config.json`, and only when the client's working directory is inside home. Project configuration cannot define commands, so a cloned repository can never add a process that runs on your machine.
 
 A definition requires `name`, `defaultEnabled`, `description`, `parameters`, and `command`:
 
@@ -56,20 +56,20 @@ The exact fields are:
 | `name` | Required non-empty string. Names must be unique within `clientTools` and must not collide with tools already bound to the session. |
 | `defaultEnabled` | Required boolean. Controls selection when no project level supplies `enabledClientTools`. |
 | `description` | Required non-empty model-facing description. State when the tool should be used and any important side effects. |
-| `parameters` | Required object JSON Schema whose root has `"type": "object"`. Tau passes the remaining schema through and validates each invocation against it. |
+| `parameters` | Required JSON Schema whose root has `"type": "object"`. Tau passes the rest of the schema through unchanged and validates every call against it. |
 | `command` | Required non-empty executable name or path. |
 | `args` | Optional array of literal string arguments. |
 | `executionTimeoutMs` | Optional positive integer. The default is 60,000 ms. |
 
-Unknown fields on a definition are discarded. Invalid entries are skipped with configuration diagnostics; valid siblings remain available. Duplicate names are exact and case-sensitive.
+Unknown fields on a definition are ignored. An invalid entry is skipped with a configuration warning, and the other entries stay available. Names are compared exactly, including case, when checking for duplicates.
 
 ### Command path resolution
 
-A `command` containing `/` is resolved as a path from home, the root of the global configuration level. For example, `./bin/tau-notify` resolves to `~/bin/tau-notify`. A bare command such as `tau-notify` is left unchanged and resolved through the client process's `PATH` when invoked.
+A `command` that contains `/` resolves from home, because the definition is global. For example, `./bin/tau-notify` resolves to `~/bin/tau-notify`. A bare command such as `tau-notify` resolves through the client process's `PATH` when the tool runs.
 
-Tau starts the executable directly with `args`. It does not use a shell, expand globs, interpolate variables, or process quoting syntax. If shell behavior is truly needed, configure an explicit shell executable and arguments, but a dedicated executable is easier to validate and cancel safely.
+Tau starts the executable directly with `args`. It does not use a shell, expand globs, substitute variables, or process quotes. If you really need a shell, configure the shell as the command with explicit arguments, but a dedicated executable is easier to validate and to cancel safely.
 
-The process inherits the owning client process's environment unchanged. Unlike execution-environment Bash, Tau does not remove credential-shaped variables from command client tools. Treat every configured executable as trusted local code and give it only the credentials it needs.
+The process inherits the client process's environment unchanged. The agent's Bash tool removes variables that look like credentials, but command client tools keep them. Treat every configured executable as trusted local code and give it only the credentials it needs.
 
 ## Select tools per project
 
@@ -81,17 +81,17 @@ Project `.tau/config.json` files may set `enabledClientTools` to an exact allowl
 }
 ```
 
-Tau uses the nearest project level that defines this field. It does not merge allowlists across project levels.
+Tau uses the nearest project level that sets this field. Lists from different levels are not combined.
 
-Selection has three distinct states:
+There are three cases:
 
 - If no project level defines `enabledClientTools`, Tau selects global definitions with `defaultEnabled: true`.
 - If the nearest definition is a non-empty array, Tau selects exactly the known names in that array, regardless of `defaultEnabled`.
 - If the nearest definition is `[]`, Tau disables every configured command client tool for that workspace.
 
-Unknown selected names are ignored without an error. Repeated names are deduplicated. Names are matched exactly and case-sensitively.
+Unknown names are ignored without an error. Repeated names are removed. Names match exactly, including case.
 
-`enabledClientTools` selects trusted global definitions; it cannot change their command, arguments, schema, description, or timeout. The field is valid only at project scope. Conversely, `clientTools` is valid only at global scope.
+`enabledClientTools` only selects global definitions. It cannot change their command, arguments, schema, description, or timeout. The field is allowed only in project configuration, and `clientTools` only in global configuration.
 
 For Telegram, `enabledClientTools: []` is the normal way to disable configured tools for a prepared workspace. For the TUI, the startup flag described below can disable all client tools at once.
 
@@ -109,9 +109,9 @@ For attach mode, place the flag with the attach options:
 tau attach --no-client-tools ws://host.example:8787
 ```
 
-This disables both configured command tools and the TUI's built-in `diff_review` and `prefill_input`. It does not disable host tools, intrinsic `tau_docs`, or session goal tools.
+This disables the configured command tools and the TUI's built-in `diff_review` and `prefill_input`. Host tools and the built-in `tau_docs` tool are not affected.
 
-Client tools are selected and advertised when the owning client starts and connects. `/reload` refreshes host-side session configuration and content but does not recreate the TUI or Telegram client's advertised tool set. Restart or reconnect the owning client after changing `clientTools`, `enabledClientTools`, or `--no-client-tools` behavior.
+A client selects and offers its tools when it starts and connects. `/reload` does not change the tools a TUI or Telegram client offers. Restart or reconnect the client after changing `clientTools`, `enabledClientTools`, or `--no-client-tools`.
 
 Diff review uses Tau’s built-in browser tool on the TUI machine, separately from command client-tool definitions. See [TUI](tui.md).
 
@@ -148,9 +148,9 @@ await runTauClientToolCommand({
 });
 ```
 
-`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.
+`describe` is optional. If present, it runs before the call is accepted and may return a partial presentation for the running tool card, with any of `subject`, `subjectWrap`, `details`, or `metadata`. The execution result may include the same partial shape for the finished card. Tau fills in every omitted field, controls the card's lifecycle and the operation label (derived from the tool name), and shows a complete default card if 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.
+Tau keeps every presentation field you set, up to the protocol limits. It does not truncate or normalize client text for display. `truncateTauClientToolText` truncates text for you, with optional `maxLines`, `maxLineChars`, and a `head` or `middle` strategy. Its defaults match the length Tau uses for its own subjects, and you can choose larger or smaller 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:
 
@@ -164,27 +164,27 @@ const details = truncateTauClientToolText(output, {
   .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.
+Each detail or metadata entry is one line, so use `maxLines: 1` when putting the helper's result directly into one entry. The helper only shapes text; the protocol's byte and count limits still apply. An empty `details` or `metadata` array hides that phase's default content.
 
-`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.
+`runTauClientToolCommand` reads the `prepare` frame, writes `ready` with any running presentation, waits until the host accepts the call, then runs your handler and writes the final result. It also handles execution-environment requests and their cancellation. On `SIGINT`, `SIGTERM`, or closed stdin, it aborts 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. `content` may be a string or ordered text/image blocks; the helper wraps strings in text blocks.
 
 ### Version 5 frame reference
 
-Write each frame as one JSON object and a newline; unknown fields are invalid.
+Write each frame as one JSON object followed by a newline. Unknown fields are invalid.
 
 Tau starts the exchange by writing:
 
-- `{ version: 5, type: "prepare", sessionId, agentId, callId, toolName, arguments }` exactly once. The identity fields are non-empty strings and `arguments` is the validated model input.
-- `{ version: 5, type: "execute" }` after accepting the command's ready frame. This authorizes execution.
+- `{ version: 5, type: "prepare", sessionId, agentId, callId, toolName, arguments }` exactly once. The ID fields are non-empty strings, and `arguments` is the model's input after validation.
+- `{ version: 5, type: "execute" }` after Tau accepts the command's `ready` frame. The command may not start work before this frame.
 
 The command writes:
 
 - `{ version: 5, type: "ready", presentation?: PresentationOverride }` exactly once after preparation.
-- `{ version: 5, type: "result", ok: true, content, presentation?: PresentationOverride }` or `{ version: 5, type: "result", ok: false, error, presentation?: PresentationOverride }` exactly once after authorization. `error` is a string. `content` is an ordered array of at most 1,024 text (`{ type: "text", text }`) or image (`{ type: "image", data, mimeType }`) blocks. At most 16 images are allowed: padded base64, at most 3.5 MiB decoded each, JPEG/PNG/WebP MIME types.
+- `{ version: 5, type: "result", ok: true, content, presentation?: PresentationOverride }` or `{ version: 5, type: "result", ok: false, error, presentation?: PresentationOverride }` exactly once, after `execute`. `error` is a string. `content` is an ordered array of at most 1,024 text (`{ type: "text", text }`) or image (`{ type: "image", data, mimeType }`) blocks. At most 16 images are allowed: padded base64, at most 3.5 MiB decoded each, JPEG/PNG/WebP MIME types.
 
-During authorized execution, the command may write `{ version: 5, 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`.
+After `execute`, the command may write `{ version: 5, 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:
 
@@ -283,7 +283,7 @@ Make the file executable with `chmod +x`. Diagnostics and uncaught errors go to
 
 ### 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:
+A small command that only needs the client machine can also implement the handshake in Bash. This example depends on `jq` for safe JSON parsing and encoding:
 
 ```bash
 #!/usr/bin/env bash
@@ -332,7 +332,7 @@ Configure either executable as an argument-free command tool:
 }
 ```
 
-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.
+`ready.presentation` and `result.presentation` are optional partial objects with `subject`, `subjectWrap`, `details`, and `metadata`. The `ready` value applies while the call runs, and the `result` value applies to the finished card. Omit either object, or any field in it, to use Tau's default. An empty `details` or `metadata` array hides that default. The script must write `ready` before it reads the `execute` frame. Direct implementations can send the same `exec` frames as the JavaScript example, but the TypeScript helper is the better choice when the tool makes several execution-environment requests, needs to forward cancellation, or handles the protocol in more complex ways.
 
 The handler receives:
 
@@ -348,13 +348,13 @@ The handler receives:
 }
 ```
 
-`sessionId` routes the owning session. `agentId` identifies the owning agent for scratch-space and attribution purposes. `callId` identifies this invocation. Do not substitute one identity for another or cache context across calls.
+`sessionId` identifies the session, `agentId` the agent that made the call (for scratch space and attribution), and `callId` this call. Never use one ID in place of another, and never reuse a context across calls.
 
-`signal` aborts when the assistant turn is interrupted, the host cancels or times out the tool, the owning client closes, the transport fails, or the protocol input closes. Pass it to all cancellable local work and to execution-environment calls.
+`signal` aborts when the turn is interrupted, the host cancels or times out the tool, the client closes, the connection fails, or stdin closes. Pass it to all local work that can be cancelled and to execution-environment calls.
 
-### Use the execution-environment facade
+### Run commands in the execution environment
 
-`context.executionEnvironment.exec()` runs a command in the session execution environment through the existing session execution boundary. It does not run on the client machine. Use it for agent-visible files, repository commands, and workspace state:
+`context.executionEnvironment.exec()` runs a command in the session's execution environment, not on the client machine. Use it for the agent's files, repository commands, and workspace state:
 
 ```ts
 const result = await context.executionEnvironment.exec("git status --short", {
@@ -367,28 +367,28 @@ const result = await context.executionEnvironment.exec("git status --short", {
 return { content: result.output || "Working tree is clean." };
 ```
 
-The optional execution settings are `args`, `env`, binary `stdin`, `cwd`, `timeoutMs`, `maxCaptureBytes`, and `signal`. The result reports combined and split output, exit status, truncation, timeout, cancellation, and closing signal. Commands use the execution environment's login Bash behavior, path resolution, environment, and authority. `HOME` belongs to that environment and cannot be overridden through the session execution request.
+The optional settings are `args`, `env`, binary `stdin`, `cwd`, `timeoutMs`, `maxCaptureBytes`, and `signal`. The result has combined and separate output, exit status, and whether output was truncated, timed out, or aborted, plus the closing signal. Commands run in the execution environment's login Bash, with its paths, environment, and permissions. `HOME` comes from that environment and cannot be overridden in the request.
 
-Up to eight execution requests may be active while their responses are being delivered. Each request ID is single-use. Cancelling one request does not cancel unrelated requests, although cancellation of the whole client-tool context aborts all of them.
+Up to eight requests may be unresolved at once. Each request ID can be used only once. Cancelling one request does not affect the others, but cancelling the whole tool call aborts all of them.
 
 ## Implement code-mode client tools
 
-Tau exports two higher-level helpers for client tools that expose a bounded JavaScript API:
+Tau exports two helpers for client tools that let the model run JavaScript against an API you define:
 
 - `createTauCodeModeClientTool` creates an in-process `TauSdkClientTool` for an SDK client.
 - `runTauCodeModeCommand` runs a code-mode definition as a command client-tool executable.
 
-Command tools need a parameters schema with required `code` string, optional `maxOutputTokens` integer (1–65,536), and no additional properties. SDK clients pass the helper's returned tool in `clientTools`.
+Command tools need a parameters schema with a required `code` string, an optional `maxOutputTokens` integer (1–65,536), and no other properties. SDK clients pass the tool returned by the helper in `clientTools`.
 
-Both helpers supply invocation identities, cancellation, the execution-environment facade, `docs`, the API bridge, and output/truncation functions. Code is the truncated, character-wrapped card subject. Descriptions are caller input; the shared builder is optional.
+Both helpers provide the call IDs, cancellation, the execution-environment API, `docs`, the bridge to your API, and output and truncation functions. The card subject is the submitted code, truncated and wrapped by character. You write the tool description; the shared description builder is optional.
 
 `await printImage(block)` emits ordered text/image blocks in `content`; see [tools](tools.md) for limits. `maxOutputTokens` defaults to 8,192 estimated tokens. Saving output requires a `persistOutput` callback.
 
-Disclose any additional process or network authority in the tool description.
+If the tool can start processes or reach the network, say so in its description.
 
 ## Limits and failure behavior
 
-The command protocol is intentionally bounded:
+The command protocol has fixed limits:
 
 - The command-to-client stdout NDJSON stream is limited to 512 frames and 192 MiB in total.
 - Each frame on that stdout stream is limited to 80 MiB.
@@ -396,35 +396,35 @@ 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.
+- Each presentation override is limited to 1 MiB in total: the subject to 256 KiB, each metadata value to 16 KiB, each detail value to 256 KiB, and `details` and `metadata` to 1,024 entries each. These are safety limits, not recommended display sizes. Tau keeps values within them unchanged. Use the exported helper for a short preview.
 
-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.
+`executionTimeoutMs` covers both preparation and execution, and defaults to 60 seconds. The host also expects the client to prepare and accept each call promptly. A command writes `ready` and any running presentation first, then waits for Tau's `execute`.
 
-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.
+Tau starts each command in its own process group. Cancellation sends a termination signal to the group and follows with `SIGKILL` after a short grace period, even if the main process has already exited. When stdin closes, the helper aborts pending execution-environment requests and accepts no more work.
 
-A successful protocol exchange must emit one version 5 ready frame, wait for the execute frame, emit one final version 5 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.
+A successful exchange writes one `ready` frame, waits for `execute`, writes one `result` frame with `ok: true` or `ok: false`, and exits with status zero. `ok: false` reports a tool failure the command handled. Process and framing failures still use stderr and a nonzero exit. The call fails on: a missing or repeated `ready`, output before `execute`, a missing result, malformed frames, output after the result, a reused request ID, timeout, cancellation, too much output, or any other limit violation.
 
 ## Disconnects, reconnects, and durability
 
-Client-tool execution is transient. Calls are not persisted for replay, and Tau does not move them to another client when the owner disappears.
+Client tool calls are not saved. Tau never replays them and never moves them to another client when the owning client goes away.
 
-When an observing owner detaches, Tau removes its schemas from subsequent turns and cancels its active calls. Client close and terminal transport failure abort local handlers and targeted execution-environment commands. The client waits for active handlers to settle before close completes, but it does not send late results after the transport is terminal.
+When the owning client detaches, Tau removes its tools from later turns and cancels its running calls. When the client closes or its connection fails for good, local handlers and the execution-environment commands they started are aborted. Closing waits for running handlers to finish, but no results are sent once the connection is gone.
 
-After reconnecting, the new client advertises its current tool definitions and must observe the session before they become available there. If another observer already owns one of those names, attachment fails on the collision. A reconnect does not resume a command process from the previous connection.
+After reconnecting, the client offers its current tools again, and they become available once it observes the session. If another client already offers one of those names, the attachment fails. A reconnect never resumes a command process from the earlier connection.
 
 ## Security and troubleshooting
 
-Command client tools are trusted executables with the full environment and operating-system authority of the client process. Keep definitions in the user-owned global configuration, use narrow JSON Schemas, avoid shell interpolation, bound local work, honor cancellation, and return only data the model needs. A project allowlist is permission to select a global definition, not permission to provide executable code.
+Command client tools are trusted executables with the client process's full environment and operating-system permissions. Keep definitions in your global configuration, use narrow JSON Schemas, avoid shell interpolation, limit local work, honor cancellation, and return only data the model needs. A project's `enabledClientTools` can only select global definitions; it can never supply code to run.
 
-The execution-environment facade is powerful in a different place. Validate every model-supplied argument before building commands, prefer fixed command names and argument arrays, avoid concatenating untrusted text into shell source, and use the context signal and bounded capture options.
+The execution-environment API is just as powerful, on the session machine. Validate every argument from the model before building a command, prefer fixed command names and argument arrays, never concatenate untrusted text into shell code, and use the context signal and capture limits.
 
-When a tool is unexpectedly absent, check:
+When a tool is missing, check:
 
 1. The owning client is currently observing the session.
-2. The global definition is valid and in scope for the client-side `cwd`.
+2. The global definition is valid, and the client's `cwd` is inside home.
 3. The nearest `enabledClientTools` selection includes the exact name, or `defaultEnabled` applies.
 4. `--no-client-tools` is not active for the TUI.
 5. No other observer or host tool owns the same name.
 6. The client was restarted or reconnected after configuration changes.
 
-For execution failures, distinguish client-local process errors from `executionEnvironment.exec()` errors on the session machine. Check executable permissions, the client `PATH`, stderr diagnostics, timeout and framing limits, then the execution environment's own `cwd`, login startup files, and command availability. See [tools](tools.md), [security](security.md), and [troubleshooting](troubleshooting.md).
+For failures, first tell apart errors from the local process and errors from `executionEnvironment.exec()` on the session machine. Check executable permissions, the client's `PATH`, stderr output, and timeout and framing limits. Then check the execution environment's `cwd`, login startup files, and whether the command exists there. See [tools](tools.md), [security](security.md), and [troubleshooting](troubleshooting.md).

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

@@ -1,27 +1,24 @@
 # Configuration reference
 
-`config.json` controls Tau defaults and integrations. The same schema is available at global and project levels, but a few fields are restricted to one scope and different components consume different results. This reference lists the current fields only.
+`config.json` sets Tau defaults and integrations. Global and project levels use the same schema, but a few fields are allowed at only one level, and different parts of Tau read different fields.
 
-Read [configuration](configuration.md) first for discovery and precedence. In the tables below, **global** means `~/.config/tau/config.json` when that level is eligible, and **project** means an ancestor `.tau/config.json` discovered from the relevant `cwd`.
+Read [configuration](configuration.md) first for discovery and precedence. In the tables below, **global** means `~/.config/tau/config.json` when that level applies, and **project** means a `.tau/config.json` found from the relevant `cwd` upward.
 
 ## Shipped defaults
 
-These are defaults built into this Tau version, not a dump of the effective configuration:
+These are the defaults for fields you leave unset in this Tau version:
 
-| Behavior                               | Shipped default      |
-| -------------------------------------- | -------------------- |
-| Default persona                        | `sonnet-5.5-coder`   |
-| Default TUI theme                      | `gold`               |
-| Built-in personas                      | Enabled              |
-| Speech-to-text provider                | Gemini               |
-| Built-in diff tool code theme          | `github-dark-dimmed` |
-| Command client tool timeout when unset | `60000` ms           |
+| Field                              | Default            |
+| ---------------------------------- | ------------------ |
+| `defaultPersona`                   | `sonnet-5.5-coder` |
+| `defaultTheme`                     | `gold`             |
+| `clientTools[].executionTimeoutMs` | `60000` ms         |
 
-Project and global content can change which persona ids are available. A configured default must match an available persona or built-in theme; otherwise Tau reports a warning.
+Project and global content can change which persona ids exist. A configured default must match an available persona or built-in theme. Otherwise Tau reports a warning.
 
 ## Field summary
 
-| Field | Type | Scope | Combination | Primary owner and apply boundary |
+| Field | Type | Scope | Combination | Read by; when changes apply |
 | --- | --- | --- | --- | --- |
 | `apiKeys` | Object of string values | Global only | Provider-keyed map | Owning host or feature process; restart after changes |
 | `defaultPersona` | Non-empty string | Global, project | Most-specific wins | Session host; new session |
@@ -29,14 +26,14 @@ Project and global content can change which persona ids are available. A configu
 | `defaultTheme` | Non-empty string | Global, project | Most-specific wins | TUI client; client restart |
 | `clientTools` | Array of objects | Global only | One global definition list | Owning client; TUI restart or new Telegram session client |
 | `enabledClientTools` | String array | Project only | Most-specific project list | Owning client; TUI restart or new Telegram session client |
-| `subagents` | Object | Global, project | Field-wise, currently one selectable list | Session runtime; `/reload` or new session |
+| `subagents` | Object | Global, project | Most-specific `launchModels` list | Session runtime; `/reload` or new session |
 | `modelSystemNotices` | String map | Global, project | Merge by model target | Session runtime; `/reload`, affects later inputs |
 | `flySprites` | Object | Global, project | Merge connection fields | Host startup; host restart |
 | `nook` | Object | Global, project | Most-specific complete object | Host tool runtime; `/reload` or new session |
 | `history` | Object | Global only | One global object | Host startup; host restart |
 | `mcpServers` | Object keyed by server name | Global and project | Merge names; nearer entry replaces | Host startup; host restart |
 
-Unknown fields are stripped without warnings. Wrong types and invalid known values produce warnings, and Tau continues with valid fields. A field at a forbidden scope is rejected.
+Unknown fields are removed without a warning. Wrong types and invalid values produce warnings, and Tau continues with the valid fields. A field at a level where it is not allowed is rejected.
 
 ## Persona, model behavior, and context
 
@@ -50,17 +47,17 @@ A persona id, optionally followed by `:` and a reasoning level:
 }
 ```
 
-Allowed reasoning suffixes are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. The persona id is matched exactly and case-sensitively during startup selection. The id must exist after built-in, global, and project personas are loaded.
+Allowed reasoning suffixes are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. The persona id must match exactly, including case, a persona that exists after built-in, global, and project personas are loaded.
 
-`defaultPersona` selects a new session when no CLI or session-creation override is supplied. Reloading an existing session retains its current persona id when possible. See [personas](personas.md).
+`defaultPersona` sets the persona of a new session unless a CLI flag or creation request chooses another. Reloading an existing session keeps its current persona when it still exists. See [personas](personas.md).
 
 ### `subagents`
 
-The top-level subagent configuration currently accepts one optional field:
+`subagents` accepts one optional field:
 
-| Nested field   | Type         | Contract                                     |
-| -------------- | ------------ | -------------------------------------------- |
-| `launchModels` | String array | Allowlist for launch overrides for subagents |
+| Nested field | Type | Contract |
+| --- | --- | --- |
+| `launchModels` | String array | Models an agent may choose when it starts a subagent |
 
 Each entry must use `<provider>/<model>:<effort>` and resolve against the merged model catalog:
 
@@ -75,7 +72,7 @@ Each entry must use `<provider>/<model>:<effort>` and resolve against the merged
 }
 ```
 
-A more-specific list replaces the broader list. The worker’s instructions and tools are inherited from the main persona; custom worker definitions are not supported. See [subagents](subagents.md).
+A more specific list replaces the broader one. Subagents inherit instructions and tools from the main persona. Custom subagent definitions are not supported. See [subagents](subagents.md).
 
 ### `modelSystemNotices`
 
@@ -89,9 +86,9 @@ A map from exact `<provider>/<model>` targets to non-empty notice text:
 }
 ```
 
-Provider ids must be known, and model ids must resolve against the bundled and refreshed model catalog. Entries merge by normalized target, with the more-specific value winning. Tau prepends the matching notice to later committed main-session and subagent user input. Ephemeral agents and maintenance model calls do not receive a newly resolved notice.
+Provider ids must be known, and model ids must exist in the model catalog. Entries merge by normalized target, and the more specific value wins. Tau adds the matching notice to the start of later user input in the main session and in subagents. Ephemeral agents and maintenance model calls do not receive a newly resolved notice.
 
-Use this for model-specific operational guidance, not for persona behavior that belongs in a persona file. See [models](models.md) and [personas](personas.md).
+Use notices for guidance that applies to one model. Behavior that belongs to a persona goes in the persona file. See [models](models.md) and [personas](personas.md).
 
 ## Credentials and service selection
 
@@ -111,9 +108,9 @@ A map from provider or feature id to a string credential:
 }
 ```
 
-The global map accepts arbitrary non-empty provider names and string values. Values are trimmed when consumed; an empty string is not a usable credential.
+The map accepts any non-empty provider name with a string value. Values are trimmed when used, and an empty string does not count as a credential.
 
-For model requests and feature helpers, provider-supported environment credentials take precedence over global `apiKeys`. Provider-supported ambient authentication remains available. Project `apiKeys` values are rejected. Codex managed OAuth uses the explicitly active account separately. See [credentials](credentials.md).
+For model requests and features, a provider's environment variable wins over the same provider's entry in `apiKeys`. Other authentication a provider supports without a key still works. `apiKeys` in a project file is rejected. Codex OAuth does not use this map; it uses the active stored account. See [credentials](credentials.md).
 
 ### `speech`
 
@@ -137,15 +134,15 @@ For terminal recording, `recordingShortcut` replaces Ctrl+Y. Its required `key`
 }
 ```
 
-A double tap must arrive within 300 ms. For printable double-tap bindings, an unmatched first tap inserts the character after that delay; another key inserts it immediately before processing the new input. Single-press bindings reserve the character. Bracketed paste never triggers recording. Keyboard auto-repeat can count as repeated taps. Recording shortcuts apply only to the TUI, not Telegram.
+A double tap must arrive within 300 ms. For printable double-tap bindings, an unmatched first tap inserts the character after that delay; another key inserts it immediately before processing the new input. A single-press binding reserves its character, so it can no longer be typed. Bracketed paste never triggers recording. Keyboard auto-repeat can count as repeated taps. Recording shortcuts apply only to the TUI, not Telegram.
 
-Without an override, Tau looks up Maisie (`QtY3JBOUKEB5xzrRfOKc`) before synthesis and tries Caleb (`AaOhDHYJ1XLZk74lXhdE`) only if ElevenLabs reports that Maisie was not found. If neither is available, speech fails. A configured voice is used exclusively: an unavailable custom voice is an error, not a request to use a default.
+Without an override, Tau looks up Maisie (`QtY3JBOUKEB5xzrRfOKc`) before synthesis and tries Caleb (`AaOhDHYJ1XLZk74lXhdE`) only if ElevenLabs reports that Maisie was not found. If neither is available, speech fails. A configured voice is the only voice Tau tries. If it is unavailable, speech fails without falling back to a default.
 
-Voice lookup authentication, permission, rate-limit, and network errors do not trigger fallback. Successful metadata lookup fixes the voice for the entire reply; it does not guarantee synthesis permission. Synthesis failures never switch voices or automatically retry a potentially billable request.
+Authentication, permission, rate-limit, and network errors during voice lookup do not trigger the fallback. Once lookup succeeds, that voice is used for the whole reply, although synthesis can still be refused. Synthesis failures never switch voices, and Tau never retries synthesis automatically because each request may be billed.
 
 Speech uses Eleven v4 Turbo, the delivery note `[Brisk but relaxed, speaking naturally to a colleague]`, and a 1.15× tempo adjustment. GPT-6 Luna rewrites the text with reasoning disabled before ElevenLabs synthesis, so both OpenAI and ElevenLabs credentials are required. Voice Library API access may require a paid ElevenLabs plan, and shared voices can become unavailable.
 
-The TUI reads this setting from its client-side configuration, including during remote attachment. Telegram reads it from the runner's startup configuration, not individual session workspaces. Restart the respective process after changes. This setting does not affect the explicit voices supplied to `tau tool speech-generate`.
+The TUI reads this setting from its own client configuration, also when attached to a remote host. Telegram reads it from the runner's startup configuration, not from session workspaces. Restart the respective process after changes. This setting does not affect the explicit voices supplied to `tau tool speech-generate`.
 
 ### `nook`
 
@@ -168,7 +165,7 @@ Connection details for one existing Nook deployment:
 }
 ```
 
-Tau normalizes the domain to a lowercase hostname. A non-empty value from `accessClientSecretEnv` takes precedence over `accessClientSecret`. The `nook` tool is available only when both the active persona allows it and effective configuration contains this object. See [Nook](nook.md).
+Tau normalizes the domain to a lowercase hostname. A non-empty value from `accessClientSecretEnv` wins over `accessClientSecret`. The `nook` tool is available only when the active persona allows it and the effective configuration contains this object. See [Nook](nook.md).
 
 ### `history`
 
@@ -189,11 +186,17 @@ A global-only remote history target:
 }
 ```
 
-Credential precedence is `TAU_HISTORY_API_KEY`, then the variable named by `apiKeyEnv`, then `apiKey`. Configuring an endpoint without an available key prevents the host service from starting. Without `history`, transcript storage and queries remain machine-local. See [history](history.md).
+Tau uses the first key it finds: `TAU_HISTORY_API_KEY`, then the variable named by `apiKeyEnv`, then `apiKey`. If `history` is configured but no key is available, the host fails to start. Without `history`, history is stored and searched only on the host machine. See [history](history.md).
 
 ### `mcpServers`
 
-MCP servers are resolved at host startup from the global `~/.config/tau/config.json` and ancestor/project `.tau/config.json` layers for the host's launch directory. Server names accumulate across layers; a nearer definition replaces the entire same-named entry, including credentials. Use `enabled: false` to disable an inherited server. All sessions on that host share the resolved definitions, and subagents inherit their parent's access even in another working directory. Session execution-environment configuration does not contribute servers. Restart the host after changing definitions or credentials; `/reload` does not reload servers.
+The host reads MCP servers once at startup, from the global config and the project levels of the directory where the host was launched.
+
+- Server names add up across levels. A nearer definition replaces the whole entry with the same name, including credentials.
+- Set `enabled: false` to turn off an inherited server.
+- All sessions on the host share the same servers. Subagents have their parent's access, even in another working directory.
+- Configuration in a session's execution environment never adds servers.
+- Restart the host after changing definitions or credentials. `/reload` does not reload servers.
 
 ```json
 {
@@ -219,11 +222,11 @@ Server names use letters, digits, `_`, and `-`. Every entry requires an explicit
 - `http`: requires an HTTP(S) `url` without embedded username/password; accepts optional string-valued `headers`. This is streamable HTTP, not the legacy SSE transport.
 - Both accept `enabled` (default `true`), `timeoutMs` for tool calls and resource reads (integer from 1 to 900,000, default 300,000), and `discoveryTimeoutMs` for connection startup and discovery requests (integer from 1 to 60,000, default 30,000). The outer MCP code-mode program has a 15-minute deadline. All calls remain interruptible.
 
-Stdio executables run directly without a shell. Bare commands resolve through the host's `PATH`. Commands containing `/` and relative `cwd` values resolve from the directory owning the defining config layer; `~/` resolves from host home. An omitted `cwd` defaults to the defining layer's directory. Arguments are literal: Tau does not interpolate them or expand shell syntax.
+Stdio executables run directly, without a shell. Bare commands resolve through the host's `PATH`. Commands that contain `/`, and relative `cwd` values, resolve from the directory of the config level that defines the server. `~/` resolves from the host user's home. Without `cwd`, the server starts in the defining level's directory. Arguments are passed literally, with no interpolation or shell expansion.
 
-Values in `env` and `headers` can reference host environment variables with `${NAME}`. Missing variables fail connection setup. Command substitution is not supported. Stdio servers inherit the host environment, with `env` overriding matching names. Keep secrets in the host environment rather than committing them to JSON.
+Values in `env` and `headers` can reference host environment variables as `${NAME}`. A missing variable makes the connection fail. Command substitution is not supported. Stdio servers inherit the host environment, and `env` overrides matching names. Keep secrets in the host environment instead of committing them to JSON.
 
-Invalid entries are skipped with diagnostics while valid siblings remain configured. OAuth sign-in, MCP prompts, subscriptions, elicitation, sampling, execution-environment servers, and user approval dialogs are not supported. See [tools](tools.md#mcp) for discovery, calls, and result handling.
+An invalid entry is skipped with a diagnostic, and the other servers stay configured. OAuth sign-in, MCP prompts, subscriptions, elicitation, sampling, execution-environment servers, and user approval dialogs are not supported. See [tools](tools.md#capabilities) for discovery, calls, and result handling.
 
 ## TUI presentation and diff review
 
@@ -237,7 +240,7 @@ The exact, case-sensitive id of a built-in theme. The shipped default is `gold`:
 }
 ```
 
-The attached TUI uses its client-local configuration. `/theme:<id>` changes the current client only and is not persisted into the session. See [TUI](tui.md).
+An attached TUI uses its own client configuration. `/theme:<id>` changes only the current client and is not saved in the session. See [TUI](tui.md).
 
 ## Command client tools
 
@@ -276,9 +279,9 @@ A global-only array of commands exposed as client-provided tools:
 }
 ```
 
-Unknown properties inside `parameters` are preserved as part of the configured schema; unknown fields elsewhere in each tool object are stripped. A command containing `/` resolves from home because definitions are global. The command executes directly on the owning client without a shell and participates in Tau's bounded client-tool protocol.
+Unknown properties inside `parameters` are kept as part of the schema. Unknown fields elsewhere in a tool object are removed. Because definitions are global, a command that contains `/` resolves from home. The command runs directly on the client, without a shell.
 
-TUI startup flag `--no-client-tools` disables both configured command tools and built-in TUI client tools. See [client tools](client-tools.md).
+The TUI flag `--no-client-tools` disables both configured command tools and the TUI's built-in client tools. See [client tools](client-tools.md).
 
 ### `enabledClientTools`
 
@@ -290,13 +293,13 @@ A project-only exact allowlist of names from global `clientTools`:
 }
 ```
 
-Names are trimmed and duplicates removed. Unknown names are silently ignored. An empty list selects none. If the field is absent at every project level, Tau selects tools with `defaultEnabled: true`.
+Names are trimmed and duplicates removed. Unknown names are ignored without a warning. An empty list selects no tools. If no project level sets the field, Tau selects the tools with `defaultEnabled: true`.
 
-The most-specific project list replaces broader project lists. Project configuration cannot define executable client tool commands.
+The most specific project list replaces broader ones. Project configuration cannot define client tool commands.
 
 ## Hosted execution environments
 
-These fields configure resolvers owned by a host process. They do not provision Sprites. A client creating a session supplies an existing environment identity and `cwd` that references one of these host-known entries. See [remote sessions](remote-sessions.md).
+These fields tell a host how to reach hosted execution environments. They do not create Sprites. A client that creates a session names an existing environment and a `cwd` on it, and the host connects using these settings. See [remote sessions](remote-sessions.md).
 
 ### `flySprites`
 
@@ -318,4 +321,4 @@ One configured connection:
 | `tokenEnv` | Non-empty string | No | Host environment variable used when `token` is absent |
 | `home` | Non-empty string | No | Sprite home, default `/home/sprite` |
 
-A usable token is required when the host resolves a Sprite. Select an existing Sprite by name. More-specific connection fields replace broader values.
+The host needs a usable token when it connects to a Sprite. Sessions select an existing Sprite by name. More specific connection fields replace broader ones.