@markusylisiurunen/tau 0.3.81 → 0.3.83

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

@@ -1,25 +1,24 @@
 # Tools
 
-Tools let an agent act beyond plain model output, but not every tool comes from the same machine or policy. Tau binds host tools to a session, accepts selected tools from an attached client, and always supplies a small set of intrinsic capabilities. Understanding that ownership explains why a tool can be available in one session and absent in another.
+Tools let an agent act, not just answer. Tools come from different places: the host provides tools selected by the persona, attached clients can add their own, and a few are always present. Where a tool comes from explains why it is available in one session and missing in another.
 
-Tool availability is captured when a logical turn starts. Persona changes, configuration reloads, and client attachment changes apply to the next independently started turn rather than changing the tool set halfway through an active turn.
+A turn keeps the tool set it started with. Persona changes, reloads, and clients attaching or detaching apply from the next turn.
 
 ## Tool categories
 
-Tau uses four distinct categories:
+There are three kinds of tools:
 
 | Category | Owner and availability |
 | --- | --- |
-| Persona-controlled host tools | The host binds implementations that operate against the session execution environment or host services. The active persona's `tools` list selects them. |
-| Intrinsic tools | Tau binds these outside persona allowlists. `tau_docs` is available to main agents and subagents. |
-| Main-session goal tools | `get_goal`, `create_goal`, and `update_goal` are always available to the main session, independently of the persona. They are not subagent tools. |
-| Client-provided tools | An attached client advertises and executes these. TUI-owned `diff_review` and `prefill_input` are examples. Configured command client tools use the same boundary. |
+| Persona-selected host tools | The host provides them, and they act on the execution environment or host services. The active persona's `tools` list selects them. |
+| Built-in tools | Always present, whatever the persona selects. `tau_docs` is available to main agents and subagents. |
+| Client tools | An attached client offers and runs them. Examples are the TUI's `diff_review` and `prefill_input`, and configured command client tools. |
 
-A tool schema tells the model how to call a tool. It does not grant operating-system permissions. Host tools execute with the authority of the execution environment or the configured host service. Client tools execute with the authority of their owning client and may separately request commands in the execution environment. See [ownership and scope](ownership-and-scope.md) and [client tools](client-tools.md).
+A tool schema tells the model how to call a tool. It grants no operating-system permissions. Host tools run with the permissions of the execution environment or the host service behind them. Client tools run with the permissions of their client, and can also ask to run commands in the execution environment. See [ownership and scope](ownership-and-scope.md) and [client tools](client-tools.md).
 
 ## Persona tool selection
 
-A custom persona can set an exact list of persona-controlled tools:
+A custom persona can list exactly which tools it uses:
 
 ```yaml
 tools:
@@ -30,7 +29,7 @@ tools:
   - web
 ```
 
-The supported persona-controlled tool and capability selectors are:
+The selectable names are:
 
 ```text
 bash
@@ -49,97 +48,87 @@ list_agents
 interrupt_agent
 ```
 
-A custom persona that omits `tools` enables `bash`, `write`, `edit`, `view_image`, `web`, `nook`, `history`, `mcp`, and `models`. It also enables the five subagent-management tools. Built-in personas enable the same base and subagent tool sets.
+A custom persona that omits `tools` gets `bash`, `write`, `edit`, `view_image`, `web`, `nook`, `history`, `mcp`, and `models`, plus the five subagent tools. Built-in personas get the same set.
 
-The selectors `web`, `history`, `nook`, `mcp`, and `models` enable namespaces in the single `code` tool, not separate model-facing tools. `bash` enables both the direct Bash tools and `tau.bash` within code mode. Tau registers `code` when at least one eligible composition capability is selected; `code` is not a separate persona selector. A namespace not selected by the persona is absent from the SDK and its documentation index.
+`web`, `history`, `nook`, `mcp`, and `models` are not separate tools. Each enables a namespace inside the single `code` tool. `bash` enables both the Bash tools and `tau.bash` inside `code`. Tau adds `code` whenever at least one usable capability is selected; `code` itself cannot be listed. A namespace the persona does not select is missing from the `code` API and its documentation.
 
-An empty list disables every persona-controlled host tool:
+An empty list turns off every selectable tool:
 
 ```yaml
 tools: []
 ```
 
-It does not remove intrinsic `tau_docs` or the main-session goal tools. It also does not select client-provided tools, which are advertised independently by an observing client.
+`tau_docs` stays available. The list also has no effect on client tools, which attached clients offer on their own.
 
-The `nook` name has an additional eligibility check: the effective host configuration must contain a Nook target. Without one, Tau does not register the tool even if the persona lists it. Other credentials and service configuration can affect what an enabled tool can do, but not whether its schema is selected. Persona configuration is covered in [personas](personas.md).
+`nook` has one more condition: the host configuration must include a Nook target. Without one, Tau leaves the capability out even if the persona lists it. For other tools, missing credentials or service configuration can make calls fail, but do not remove the tool. Persona configuration is covered in [personas](personas.md).
 
-## Intrinsic Tau documentation
+## Tau documentation
 
-`tau_docs` reads the exact version-matched documentation shipped with the running Tau package. It is intrinsic, so a persona cannot disable it, and Tau also includes it in every subagent registry.
+`tau_docs` reads the documentation shipped with the running Tau version. A persona cannot disable it, and every subagent has it too.
 
-The tool accepts one exact flat Markdown path. It has no search or list operation. Start with:
+The tool takes one exact Markdown path, such as `tools.md`. It cannot search or list pages. Start with:
 
 ```text
 index.md
 ```
 
-Then follow paths linked by that page. The tool description also advertises built-in command-line tools with capability summaries and dedicated documentation paths. Agents may read those pages directly when a tool is relevant, without first loading the index. Use of these utilities is optional and depends on the execution environment's prerequisites. Unknown paths are rejected. The corpus describes supported Tau contracts, not the current effective configuration of a particular session, so use configuration inspection or debug output when the answer depends on local state.
-
-## Main-session goal tools
-
-The main agent always receives:
-
-- `get_goal`, which reads the persisted session goal or returns no goal.
-- `create_goal`, which creates an active goal only when the user or an active instruction explicitly requests one.
-- `update_goal`, which changes, completes, or blocks the current goal.
-
-These tools are outside persona allowlists because goal lifecycle is a session capability. They are not included in subagent registries or advertised by clients. Goal behavior is described in [sessions](sessions.md).
+Then follow the links on that page. The tool's description also lists the built-in command-line tools, each with a short summary and its page, so agents can open a tool's page directly without reading the index first. Whether those tools work depends on what is installed in the execution environment. Unknown paths are rejected. The documentation describes supported behavior, not a particular session's effective configuration. When the answer depends on local state, inspect the configuration or use debug output.
 
 ## Execution-environment tools
 
 ### Bash
 
-`bash` runs a command in a fresh non-interactive login Bash in the execution environment. Each call starts a new shell, so shell variables, aliases, functions, `cd`, and other shell state do not carry into the next call. Files and process side effects do persist.
+`bash` runs a command in a fresh non-interactive login Bash in the execution environment. Each call starts a new shell, so shell variables, aliases, functions, `cd`, and other shell state do not carry over to the next call. Changes to files and other side effects do persist.
 
-Tau starts Bash with `-lc` and the execution environment's `HOME`. A login shell can read `/etc/profile` and then the first available `~/.bash_profile`, `~/.bash_login`, or `~/.profile`. It reads `BASH_ENV` when set. `.bashrc` is otherwise loaded only when a login file sources it. Startup files must not print output, read stdin, require a terminal, or terminate the shell unexpectedly because Tau does not suppress their effects.
+Tau starts Bash with `-lc` and the execution environment's `HOME`. A login shell can read `/etc/profile` and then the first available `~/.bash_profile`, `~/.bash_login`, or `~/.profile`. It reads `BASH_ENV` when set. `.bashrc` is otherwise loaded only when a login file sources it. Tau does not suppress anything startup files do, so they must not print output, read stdin, require a terminal, or exit the shell.
 
-There is no TTY and assistant `bash` calls have no stdin. Commands that prompt, open an interactive editor, or require terminal control will hang until timeout or fail. Use non-interactive flags and pass a `workingDirectory` rather than relying on a previous `cd`.
+There is no TTY, and `bash` calls from the agent have no stdin. Commands that prompt, open an editor, or need a terminal hang until the timeout or fail. Use non-interactive flags, and pass `workingDirectory` instead of relying on an earlier `cd`.
 
-Tau sets `NO_COLOR=1`, `FORCE_COLOR=0`, `TERM=dumb`, and `PAGER=cat` for predictable non-interactive command output. It also forces Git into non-interactive mode: terminal prompts and askpass interaction are disabled, editors are replaced, pagers are disabled, and SSH uses batch mode. These fixed values override inherited and execution-environment values after login startup. A command can still assign its own environment explicitly. Authentication therefore needs to be available non-interactively.
+Tau sets `NO_COLOR=1`, `FORCE_COLOR=0`, `TERM=dumb`, and `PAGER=cat` so output is predictable. It also makes Git non-interactive: no terminal or askpass prompts, no editors, no pagers, and SSH in batch mode. These values override inherited ones and anything set by login startup files. A command can still set its own environment variables explicitly. Authentication must therefore work without prompts.
 
-Agents are instructed to choose the mode that avoids unnecessary waiting. Background mode is appropriate when it enables useful independent progress, for example inspecting code while a test suite runs. If the agent would only wait for completion, a foreground call with an appropriate `timeout` is preferred over launching a background job and immediately waiting for it. Runtime alone does not determine the mode.
+Agents are told to choose the mode that avoids needless waiting. Background mode fits when the agent can do other useful work meanwhile, such as reading code while tests run. If the agent would only wait for the result, a foreground call with a suitable `timeout` is better than starting a background job and waiting for it right away. How long a command takes does not decide the mode by itself.
 
-Background mode is also appropriate for a service that must remain running or execution that needs to survive turns or interruptions. Launching several independent jobs and then waiting for them is valid concurrency. This is tool guidance, not a runtime restriction on waiting.
+Background mode also fits a service that must keep running, or work that must survive turns and interruptions. Starting several independent jobs and then waiting for them is a valid way to run work in parallel. This is guidance for the agent; Tau does not enforce it.
 
-The default foreground timeout is 60 seconds. Tau captures at most 1 MiB of merged stdout and stderr, preserving the tail when raw capture overflows. The default model-facing result limit is roughly 8,192 estimated tokens. When output exceeds it, Tau returns a roughly 2,048-token middle preview and a gating notice. The command has already run and its side effects have already happened.
+The default foreground timeout is 60 seconds. Tau captures at most 1 MiB of combined stdout and stderr, and keeps the end when there is more. By default the result the model sees is limited to about 8,192 estimated tokens. Longer output is replaced by a preview of about 2,048 tokens from the middle, with a notice. The command has still run in full, with all its side effects.
 
-Prefer a narrower command over raising the result limit. When more output is genuinely needed, `maxOutputTokens` can request 8,192 through 16,384 tokens autonomously. Values above 16,384, up to 65,536, are reserved for an explicit user request. Tau may save captured output to a temporary execution-environment file when model-context truncation occurs; the result reports that path when available.
+A narrower command is better than a higher limit. When more output is really needed, the agent can set `maxOutputTokens` between 8,192 and 16,384 on its own. Values above 16,384, up to 65,536, require an explicit user request. When output is truncated, Tau may save it to a temporary file in the execution environment and report the path.
 
-On a local execution backend, Tau removes inherited environment variables whose names end in `_KEY`, `_SECRET`, `_TOKEN`, or `_PASSWORD`, plus `API_KEY`, before running execution-environment commands. Hosted backends begin from their own target environment. Explicit execution-environment overrides still apply. Do not print credentials or broad environment dumps.
+In a local execution environment, Tau removes inherited environment variables whose names end in `_KEY`, `_SECRET`, `_TOKEN`, or `_PASSWORD`, and `API_KEY`, before running commands. Hosted environments start from their own environment. Variables set explicitly for the environment still apply. Do not print credentials or whole environments.
 
-Direct TUI commands, `!<command>` and `!!<command>`, use the same fresh login-shell execution boundary. `!` adds the result to model context; `!!` does not. Their user-facing context limit is larger than an ordinary assistant tool result, but raw process capture is still bounded.
+The TUI commands `!<command>` and `!!<command>` run the same way, in a fresh login shell. `!` adds the result to the model's context and `!!` does not. They allow more output into context than an agent's tool call, but capture is still limited.
 
-With `background: true`, `bash` returns a session-owned job ID after launch rather than waiting for exit. Launch does not establish application readiness. Background jobs have no execution deadline. Combining `background: true` with `timeout` is invalid; execution timeouts are foreground-only. They keep running across turns and interruptions. Main agents, subagents, and ephemeral threads share the session's job registry.
+With `background: true`, `bash` starts the command and returns a job ID for the session right away, without waiting for it to exit. A started job is not necessarily ready to use. Background jobs have no time limit, and combining `background: true` with `timeout` is invalid. Jobs keep running across turns and interruptions. Main agents, subagents, and ephemeral threads share the session's jobs.
 
-Enabling `bash` also enables `list_bash_jobs`, `read_bash_job`, `stop_bash_job`, and `wait_for_bash_jobs`. These names are not separate persona configuration entries. List returns compact ID/status blocks; read returns the same blocks with a bounded output tail. Stop terminates the managed process group, with forced termination after a grace period. Up to 64 job records are retained, evicting the oldest completed record when needed; starting another job fails if all 64 are still running. Each job retains 64 KiB of merged output, with at most 2,048 estimated tokens returned per job and an 8,192-token shared output budget for multi-job observations. Background output does not use `maxOutputTokens` or save overflow files.
+Enabling `bash` also enables `list_bash_jobs`, `read_bash_job`, `stop_bash_job`, and `wait_for_bash_jobs`. These cannot be listed separately in a persona. List returns short ID and status blocks. Read returns the same blocks with the end of the job's output. Stop terminates the job's process group, and kills it if it has not exited after a grace period. Tau keeps up to 64 job records and drops the oldest finished one when needed. Starting a job fails if all 64 are still running. Each job keeps 64 KiB of combined output. At most 2,048 estimated tokens are returned per job, and 8,192 in total when several jobs are observed at once. Background output ignores `maxOutputTokens` and is never saved to an overflow file.
 
-`read_bash_job`, `stop_bash_job`, and `wait_for_bash_jobs` accept `includeOutput`, defaulting to `true`. Setting it to `false` omits captured stdout/stderr and output-truncation notices, but retains job ID, command, cwd, status, exit code when finished, termination reason, and operational errors. List always omits captured output.
+`read_bash_job`, `stop_bash_job`, and `wait_for_bash_jobs` accept `includeOutput`, which defaults to `true`. With `false`, the result leaves out stdout, stderr, and truncation notices, but still has the job ID, command, cwd, status, exit code once finished, termination reason, and errors. List never includes output.
 
-Management tool cards use operation-specific Bash-scoped headings such as `reading bash <id>` and `listed bash jobs`, with stable subjects and a seven-line middle-truncated preview of the model-facing result. Background launch uses `started background <command>`; this indicates launch, not readiness or eventual success.
+In the TUI, job tool cards have headings such as `reading bash <id>` and `listed bash jobs`, and show a seven-line preview from the middle of the result. A background start shows `started background <command>`, which means only that the command started.
 
-Job-management validation and operational failures include bounded diagnostics in the TUI tool card as well as the model-facing result. Ordinary cancellation leaves the card details empty.
+When a job tool call is invalid or fails, the TUI card shows a short diagnostic as well as the model's result. A normal cancellation shows no details.
 
-`wait_for_bash_jobs({ids, timeout?, includeOutput?})` returns when any requested job exits or the wait deadline expires. Already-finished jobs return immediately. Its timeout is a positive integer in milliseconds, defaults to 60,000, and cannot exceed 300,000. Expiry is a successful observation and does not stop jobs; interrupting the wait also leaves them running. This waits for exit, not readiness: servers need log or readiness checks instead. Completion does not automatically start an agent turn.
+`wait_for_bash_jobs({ids, timeout?, includeOutput?})` returns when any of the jobs exits or the wait times out. Jobs that already finished return immediately. The timeout is a positive integer in milliseconds, defaults to 60,000, and can be at most 300,000. A timeout counts as a successful result and does not stop the jobs. Interrupting the wait leaves them running too. The tool waits for a job to exit, not to become ready, so check a server's logs or readiness instead. A job finishing never starts an agent turn by itself.
 
-Jobs survive client disconnects while the host remains alive and prevent idle-session eviction until they finish. Orderly session disposal or host shutdown stops them. Job IDs and logs are not persisted or recovered; stale IDs fail clearly. An unknown job ID does not establish that the command never ran, that its side effects were undone, or that it is no longer running. Agents are instructed to check current process and output state before restarting such a command. Cleanup does not cover independently daemonized processes, arbitrary tmux sessions, or processes orphaned by a host crash or forced kill.
+Jobs survive client disconnects while the host is running, and keep an idle session from being unloaded until they finish. Closing the session normally or shutting down the host stops them. Job IDs and logs are not saved or recovered, and an old ID fails with a clear error. An unknown ID does not mean the command never ran, that its side effects were undone, or that it has stopped. Agents are told to check running processes and output before starting such a command again. Cleanup does not cover processes that daemonize themselves, tmux sessions, or processes left behind by a host crash or forced kill.
 
 ### Write and edit
 
-`write` creates or overwrites a UTF-8 file and creates missing parent directories. Relative paths resolve from the execution environment's current working directory. Because it replaces the complete file, it is best for new files or intentional full rewrites.
+`write` creates or overwrites a UTF-8 file, creating missing parent directories. Relative paths resolve from the session's working directory. It replaces the whole file, so use it for new files or deliberate full rewrites.
 
 `edit` performs one exact textual replacement in an existing UTF-8 file. `oldText` must be non-empty and match exactly once, including whitespace and newlines. Zero matches and multiple matches are rejected without changing the file. Read the current section first and make `oldText` more specific when necessary.
 
-Neither tool provides a general read operation. Use a scoped non-interactive Bash command such as `sed`, `cat`, or a language-specific utility to inspect text. Both tools can accept absolute paths, subject to the execution environment's filesystem permissions. They are not confined to the repository root by Tau.
+Neither tool reads files. To inspect text, use a focused Bash command such as `sed` or `cat`, or a language-specific tool. Both tools accept absolute paths and are limited only by the execution environment's file permissions. Tau does not restrict them to the repository.
 
 ### View image
 
-`view_image` reads an image from the execution environment and returns it to a multimodal model. Tau's built-in instruction limits use to cases where the user explicitly asks to view or analyze an image.
+`view_image` reads an image from the execution environment and shows it to a model that accepts images. Tau's built-in instructions tell the agent to use it only when the user explicitly asks to view or analyze an image.
 
-The supported formats are JPEG, PNG, and WebP. Source reads are capped at 50 MiB. Images with both dimensions at most 4,096 pixels and a model payload at most 3.5 MiB are returned unchanged. Images exceeding the dimension limit are resized to fit within 4,096 pixels while preserving aspect ratio, without upscaling. Tau tries lossless encoding before lossy compression and reduces dimensions further only if needed to meet the payload limit. Transparency is preserved. If Tau cannot reduce a valid image below the model payload limit, the call fails. Relative paths resolve from the execution-environment working directory.
+Supported formats are JPEG, PNG, and WebP, and the source file can be at most 50 MiB. An image is returned unchanged if both dimensions are at most 4,096 pixels and it is at most 3.5 MiB. A larger image is scaled down to fit within 4,096 pixels, keeping its aspect ratio; images are never scaled up. To meet the size limit, Tau tries lossless encoding first, then lossy compression, and reduces dimensions further only if needed. Transparency is kept. If a valid image still cannot fit the limit, the call fails. Relative paths resolve from the session's working directory.
 
 ## Command-line tools
 
-`tau tool` provides standalone utilities for people and agents, usable from a shell inside or outside Tau. Files, configuration, credentials, and required executables must be available on the machine running the command. Agents can invoke these commands through Bash.
+`tau tool` provides standalone utilities for people and agents, usable from any shell, inside or outside Tau. Files, configuration, credentials, and required programs must be on the machine that runs the command. Agents run these commands through Bash.
 
 | Command | Purpose | Guide |
 | --- | --- | --- |
@@ -148,33 +137,33 @@ The supported formats are JPEG, PNG, and WebP. Source reads are capped at 50 MiB
 | `tau tool speech-generate` | Generate narration or dialogue using ElevenLabs and assemble a WAV. | [Speech generation](speech-generation.md) |
 | `tau tool openrouter` | Typed decisions and standalone text/media analysis. | [OpenRouter](openrouter.md) |
 
-Each guide covers setup, input, examples, outputs, and failure behavior. Use `tau tool --help` to list commands or `tau tool <command> --help` for command-specific help. The same guides are packaged for `tau_docs` and linked from its `index.md`.
+Each guide covers setup, input, examples, outputs, and failures. Run `tau tool --help` to list commands, or `tau tool <command> --help` for one command. Agents can read the same guides with `tau_docs`.
 
 ## Code-mode composition
 
-`code` runs a one-shot JavaScript program that composes enabled capabilities through `tau.web`, `tau.history`, `tau.nook`, `tau.mcp`, `tau.bash`, and `tau.models`. Direct Bash, write, edit, and image-viewing tools remain available independently.
+`code` runs a one-off JavaScript program that combines the enabled capabilities: `tau.web`, `tau.history`, `tau.nook`, `tau.mcp`, `tau.bash`, and `tau.models`. The Bash, write, edit, and image tools stay available as separate tools.
 
 ### Documentation and output
 
-When the runtime guide is not already visible, the agent first runs a documentation-only program:
+If the agent has not yet seen the runtime guide, it first runs a program that only prints it:
 
 ```js
 printText(docs);
 ```
 
-The guide covers runtime rules, capabilities, and composition examples. The agent retrieves any unseen capability reference in a separate documentation-only call:
+The guide covers runtime rules, capabilities, and examples. The agent reads each capability's reference it has not seen yet in a separate call that only prints documentation:
 
 ```js
 printText(await tau.docs("web"));
 ```
 
-The agent reuses visible documentation. MCP descriptions and Nook's authoring guide have separate discovery steps. Programs need not print intermediate results.
+The agent does not re-read documentation it has already seen. MCP tool descriptions and Nook's authoring guide are read in their own separate steps. Programs do not need to print intermediate results.
 
-Only `printText(string)` and awaited `printImage({ data, mimeType })` emit output, in emission order; return values are ignored. Text is middle-truncated to `maxOutputTokens` (default 8,192; range 1–65,536). The agent leaves it unset unless needed, requesting up to 16,384 autonomously; higher budgets require an explicit user request. Truncated built-in text is saved to a temporary execution-environment file when possible, with its path reported. Read it rather than repeat side effects. Files exclude images and text lost to capture limits.
+Only `printText(string)` and awaited `printImage({ data, mimeType })` produce output, in the order they are called. Return values are ignored. Text is truncated in the middle to `maxOutputTokens` (default 8,192; range 1–65,536). The agent leaves it unset unless needed, and may raise it to 16,384 on its own. Higher values require an explicit user request. When text from the built-in `code` tool is truncated, Tau saves it to a temporary file in the execution environment when possible and reports the path. The agent reads that file instead of running the program again with its side effects. The file does not contain images or text lost to capture limits.
 
-JPEG, PNG, and WebP images are validated outside the sandbox and prepared within 4,096 pixels per dimension and 3.5 MiB each. Sources are limited to 40 megapixels and 16 images per program. Valid images survive built-in program failure.
+JPEG, PNG, and WebP images are validated outside the sandbox and fitted to 4,096 pixels per dimension and 3.5 MiB each. Source images can be at most 40 megapixels, and a program can emit at most 16 images. Valid images are kept even if the built-in `code` program fails.
 
-The pure globals `truncate(text, { maxChars, position? })` and `truncateLines(text, { maxLines, position? })` return bounded strings with omission markers. Position defaults to `middle`; `start` and `end` retain the corresponding edge. They do not print automatically.
+The helper functions `truncate(text, { maxChars, position? })` and `truncateLines(text, { maxLines, position? })` return shortened strings with a marker where text was removed. `position` defaults to `middle`; `start` and `end` keep that end of the text. They do not print anything.
 
 ```js
 const result = await tau.bash.run({ command: "npm test" });
@@ -183,38 +172,30 @@ printText(truncate(result.stdout, { maxChars: 4000 }));
 
 ### Execution and limits
 
-Programs have no ambient filesystem, process, environment, credential, import, timer, network, or fetch access. Capabilities supply authority; variables hold data and Bash handles files. No scratch-file API.
+Programs have no direct access to files, processes, environment variables, credentials, imports, timers, or the network. They can act only through the capabilities. Keep data in variables, and use `tau.bash` for files. There is no scratch-file API.
 
-`code` defaults to 5 minutes; `timeout` accepts 1–900,000 ms (15 minutes). `tau.bash.run` defaults to 60 seconds, capped at 5 minutes and the enclosing deadline. Programs allow 128 API requests, eight concurrent. Serialized requests and responses are capped at 64 MiB. Undefined object properties are omitted; undefined arguments and array entries are rejected. Programs are not retried; failure or cancellation does not undo actions.
+`code` times out after 5 minutes by default. `timeout` accepts 1–900,000 ms (15 minutes). `tau.bash.run` times out after 60 seconds by default, and at most after 5 minutes or the program's own deadline, whichever comes first. A program can make 128 API requests, eight at a time. Each serialized request and response can be at most 64 MiB. Object properties set to `undefined` are dropped, while `undefined` arguments and array entries are rejected. Programs are never retried, and failure or cancellation does not undo actions already taken.
 
 ### Capabilities
 
-- `tau.web`: metadata discovery, Exa search, and page content retrieval. The agent prefers local data, purpose-built CLIs, first-party APIs, and structured sources over web extraction. GitHub operations use gh or checked-out Git where suitable. Metadata discovery does not need an Exa key; search and content retrieval do.
-- `tau.history`: read-only search and paginated transcript access. The agent uses it only when explicitly instructed to consult historical sessions. Historical content is untrusted data, not instructions. See [history](history.md).
-- `tau.nook`: site deployment, templates, and site-scoped JSON KV. The agent uses it for user-requested publishing or Nook management. App authoring requires reading `tau.nook.skill()` in a separate documentation-only call first. See [Nook](nook.md).
-- `tau.mcp`: discovery and invocation of connected tools and resources. The agent reads each tool's description and schema before calling it. Connections are shared and lazy; mutations are not retried. `isError` is result data; protocol failures throw. Existing MCP server configuration and trust rules apply. See [configuration reference](config-reference.md#mcpservers) and [security](security.md#trust-mcp-servers).
-- `tau.bash`: `run`, `start`, `list`, `read`, `wait`, and `stop`. `run` returns stdout/stderr and exit/termination fields with a 24 MiB capture bound. Overflow keeps a tail; check `truncated` before parsing. Optional UTF-8 `stdin` is limited to 16 MiB and closed after writing (EOF); omitted input is unavailable, `""` is empty. `start` has no stdin. Background jobs share the direct tools' registry and bounded output tails. Jobs survive program exit and interruption; foreground work is cancelled. Shell rules above apply.
-- `tau.models`: lists fixed OpenRouter model choices and performs standalone chat or typed decisions. No session conversation or tools are inherited. Chat media accepts either paths on the agent's machine or inline padded base64 with a matching MIME type. Credentials stay with the host. Provider usage metadata is returned, but external model charges are not included in session cumulative cost or usage logs. Requests are cancellable and not automatically retried. Input, model, media, response, and request limits match [OpenRouter](openrouter.md); inspect completion/refusal status rather than assuming every response is a complete answer.
-
-SDK and command client tools use the same sandbox globals and output contract with their own explicitly declared APIs. Their default program deadline is 60 seconds unless configured otherwise.
+- `tau.web`: metadata discovery, Exa search, and fetching page content. The agent prefers local data, dedicated CLIs, first-party APIs, and structured sources over scraping web pages. For GitHub it uses `gh` or a Git checkout where suitable. Metadata discovery works without an Exa key; search and content fetching need one.
+- `tau.history`: read-only search and paginated transcripts. The agent uses it only when explicitly told to look at past sessions. It treats past content as data and never follows instructions in it. See [history](history.md).
+- `tau.nook`: deploying sites, templates, and each site's JSON KV store. The agent uses it when the user asks to publish or manage Nook. Before writing an app, the agent reads `tau.nook.skill()` in a separate call that only prints documentation. See [Nook](nook.md).
+- `tau.mcp`: finding and calling tools and resources on connected MCP servers. The agent reads each tool's description and schema before calling it. Connections are shared and opened on first use, and calls that change data are never retried. An `isError` result is returned as data, while protocol failures throw. MCP server configuration and trust rules apply. See [configuration reference](config-reference.md#mcpservers) and [security](security.md#trust-mcp-servers).
+- `tau.bash`: `run`, `start`, `list`, `read`, `wait`, and `stop`. `run` returns stdout, stderr, and exit and termination fields, capturing up to 24 MiB. Beyond that it keeps the end, so check `truncated` before parsing. Optional UTF-8 `stdin` is limited to 16 MiB and closed after writing. Without `stdin` the command has no stdin at all, while `""` gives it an empty one. `start` takes no stdin. Background jobs are the same jobs as the Bash tools', with the same output limits. Jobs survive the program ending and interruption, while foreground commands are cancelled. The shell rules above apply.
+- `tau.models`: lists a fixed set of OpenRouter models and runs standalone chats or typed decisions with them. These calls do not see the session's conversation or tools. Chat media can be paths on the agent's machine or inline padded base64 with a matching MIME type. Credentials stay on the host. Provider usage data is returned, but these charges are not included in the session's cost or usage logs. Requests can be cancelled and are never retried automatically. Limits on input, models, media, responses, and requests are the same as in [OpenRouter](openrouter.md). Check whether a response completed or was refused instead of assuming it is a full answer.
 
-## Subagent tool eligibility
-
-A subagent can receive only:
-
-```text
-bash  write  edit  view_image  web  history  nook  mcp  models
-```
+SDK and command client tools built on code mode use the same sandbox functions and output rules, with their own declared APIs. Their programs time out after 60 seconds unless configured otherwise.
 
-Tau inherits the intersection of the main persona’s tools and those nine eligible names. `tau_docs` is then added intrinsically. There is no separate child tool selection. Nook and MCP require configuration; MCP uses the parent's host connections.
+## Subagent tools
 
-Subagents do not receive goal tools, subagent-management tools, or client-provided tools. Their Bash and file tools are scoped to the subagent working directory, including an alternate directory selected at launch. See [subagents](subagents.md) for configuration and working-directory context rebuilding.
+A subagent gets each of `bash`, `write`, `edit`, `view_image`, `web`, `history`, `nook`, `mcp`, and `models` that the main persona also has, plus `tau_docs`. It never gets the subagent tools or client tools. Its Bash and file tools start in the subagent's working directory. [Subagents](subagents.md#tools) has the details.
 
 ## Client-owned tools
 
-The TUI advertises `diff_review` and `prefill_input` unless client tools are disabled. `diff_review` captures repository state through session execution and runs the review interface on the TUI machine. `prefill_input` places a draft in an empty TUI editor; it does not submit text and refuses to overwrite an existing draft.
+The TUI offers `diff_review` and `prefill_input` unless client tools are disabled. `diff_review` reads repository state from the execution environment and runs the review interface on the TUI machine. `prefill_input` puts a draft in an empty TUI editor. It never sends the text and refuses to overwrite an existing draft.
 
-Configured command client tools are also client-owned. They can run local client processes and use a bounded execution-environment facade when work belongs on the session machine. Remote attachment makes this distinction visible: the TUI process and its tools may be on a laptop while the host and execution environment are elsewhere. See [client tools](client-tools.md) for configuration, protocol helpers, and limits, and [TUI](tui.md) for diff-tool configuration.
+Configured command client tools also belong to the client. They run processes on the client machine, and can run limited commands in the execution environment when the work belongs on the session machine. This matters with remote attachment, where the TUI and its tools may be on a laptop while the host and execution environment are elsewhere. See [client tools](client-tools.md) for configuration, protocol helpers, and limits, and [TUI](tui.md) for diff-tool configuration.
 
 ### Sending files to Telegram
 
@@ -227,23 +208,23 @@ Telegram provides four client tools, each accepting `{ path, caption? }` and del
 | `send_audio_to_telegram` | Audio player | MP3/M4A | 50,000,000 bytes |
 | `send_document_to_telegram` | Original file attachment | Any type, including PDF, CSV, ZIP, WAV, and original-quality images | 50,000,000 bytes |
 
-Paths may be absolute or relative to the session working directory. Captions are plain text, limited to 1,024 UTF-16 code units. Document delivery preserves original bytes and filenames; photo delivery uses Telegram's native photo processing. File bytes do not enter model context or session history.
+Paths may be absolute or relative to the session's working directory. Captions are plain text of at most 1,024 UTF-16 code units. Documents keep their original bytes and filename, while photos go through Telegram's own photo processing. File contents never enter the model's context or the session history.
 
-Transfers read at most 8,000,000 bytes per execution-environment request and reject non-regular, empty, oversized, or changing files. Tools do not inspect codecs, convert files, or fall back to another delivery method. Telegram validates media compatibility, including photo dimensions. Unsupported media can be explicitly converted before sending or delivered as a document instead.
+Files are read in chunks of at most 8,000,000 bytes. A file that is not a regular file, is empty, is too large, or changes during the transfer is rejected. The tools do not inspect codecs, convert files, or try another delivery method. Telegram checks media compatibility, including photo dimensions. Convert unsupported media before sending, or send it as a document.
 
-Reading, cancellation, and Telegram delivery failures fail the tool call. Calls allow five minutes and are not automatically retried, since an interrupted upload may already have reached Telegram.
+Read errors, cancellation, and Telegram delivery errors fail the tool call. Each call has five minutes and is never retried automatically, because an interrupted upload may already have reached Telegram.
 
-The runner owns upload credentials and binds the recipient to the session's bot and chat; the agent cannot select a recipient. These built-in tools are independent of configured command-tool selection and do not appear in TUI sessions or subagents. Inspecting an image with `view_image` does not send it to Telegram. Automatic voice responses through `/tts_on` are separate from these tools.
+The runner holds the upload credentials, and the recipient is always the session's bot and chat; the agent cannot choose another. These tools are not affected by `enabledClientTools` and do not exist in TUI sessions or subagents. Viewing an image with `view_image` does not send it to Telegram. Automatic voice replies through `/tts_on` are separate from these tools.
 
 ## When a tool is missing or fails
 
-First identify which owner should provide it:
+First work out where the tool should come from:
 
-- For a host tool, inspect the active persona's `tools`, effective host configuration, and service credentials.
-- For a subagent tool, inspect both the subagent's explicit list and the eligible inherited set.
-- For a client tool, confirm that an observing client advertises it and that client tools were not disabled.
-- For `tau_docs` or main-session goal tools, a missing schema indicates a runtime or version problem rather than a persona setting.
+- For a host tool, check the active persona's `tools`, the host configuration, and service credentials.
+- For a subagent tool, check the main persona's `tools` against the list of tools subagents can receive.
+- For a client tool, confirm that an attached, observing client offers it and that client tools are not disabled.
+- If `tau_docs` is missing, something is wrong with the Tau installation or version; no persona setting removes it.
 
-Then check the execution boundary named in the error. A path that exists on the TUI client may not exist in the execution environment. A command available in the host's `PATH` may not be available in the execution environment's login shell. Client process errors belong to the client machine, while `executionEnvironment.exec` errors belong to the session machine.
+Then check which machine the error comes from. A path on the TUI machine may not exist in the execution environment. A command in the host's `PATH` may be missing from the execution environment's login shell. Errors from a client tool's own process come from the client machine, while `executionEnvironment.exec` errors come from the session machine.
 
-Use `tau --debug --persona <id>` for the host-tool schemas of a new local TUI session. `/reload` refreshes host configuration and persona content for an idle session, but it does not restart or re-advertise tools owned by an attached client. See [troubleshooting](troubleshooting.md) and [security](security.md) for boundary-specific checks.
+Use `tau --debug --persona <id>` to see the host tool schemas for a new local session. `/reload` reloads configuration and persona content in an idle session, but it does not restart or refresh tools that an attached client offers. See [troubleshooting](troubleshooting.md) and [security](security.md) for boundary-specific checks.