@markusylisiurunen/tau 0.3.94 → 0.3.95

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

@@ -6,13 +6,13 @@ Subagents are background agents that the main agent starts and the host supervis
 
 Subagents are general-purpose workers. There are no named types. Several can run at once, each with its own task and conversation.
 
-A native Tau subagent behaves like the active main persona, wrapped in instructions that Tau maintains. Those instructions and the subagent's description cannot be configured. Put task-specific instructions, including any relevant skill guidance, in the launch prompt.
+A native Tau subagent works like a main agent of the active persona in the subagent's working directory. Its system prompt is the one a main agent would get there, with the same persona prompt, skills, project instructions, and environment context. Tau adds a short section in front that explains the subagent's role: work headless on the part of the main agent's task given in the assignment, treat later messages as coming from the main agent, wait for background work its answer depends on, never start other agents, leave contact with the user to the main agent, and return a self-contained result. The section also gives the parent session's ID. This section cannot be configured. Put task-specific instructions in the launch prompt.
 
-Whether the agent can start subagents depends on the main persona's tool list. Built-in personas, and custom personas that omit `tools`, enable all five subagent tools. A custom persona with a `tools` list that lacks `spawn_agent` cannot start subagents. Leave out all five subagent tools when no subagent interaction is wanted. There is no other setting to turn subagents on or off. See [personas](personas.md).
+Whether the agent can start subagents depends on the main persona's tool list. The `agents` tool name enables `tau.agents` in the `code` tool and the `wait_for_agents` tool. Built-in personas, and custom personas that omit `tools`, include it. A custom persona with a `tools` list that lacks `agents` cannot start or manage subagents. There is no other setting to turn subagents on or off. See [personas](personas.md).
 
 ## Trigger sensitivity
 
-The main agent starts subagents only when the user or active instructions explicitly ask for delegation. Ask in ordinary language; no special tag is needed. The request itself does not create a subagent: the main agent still has to call `spawn_agent`.
+The main agent starts subagents only when the user or active instructions explicitly ask for delegation. Ask in ordinary language; no special tag is needed. The request itself does not create a subagent: the main agent still has to call `tau.agents.spawn`.
 
 The agent follows this rule itself. Tau checks that a launch is valid, but it does not judge whether the request really asked for delegation.
 
@@ -29,9 +29,11 @@ A native Tau subagent can receive these tools. [Claude Code subagents](#claude-c
 - `mcp`, when the host has enabled MCP servers
 - `models`
 
-A subagent gets each of these that the main persona also has. For example, a main persona with `bash`, `edit`, `history`, and `spawn_agent` gives its subagents `bash`, `edit`, and `history`. Names such as `web` and `history` enable the matching capability in the subagent's `code` tool. MCP uses the host's existing connections, whatever the subagent's working directory. There is no separate tool list for subagents.
+A subagent gets each of these that the main persona also has. For example, a main persona with `bash`, `edit`, `history`, and `agents` gives its subagents `bash`, `edit`, and `history`. Names such as `web` and `history` enable the matching capability in the subagent's `code` tool. MCP uses the host's existing connections, whatever the subagent's working directory. There is no separate tool list for subagents.
 
-Every native Tau subagent also gets the built-in `tau_docs` tool, and a persona's `tools` list cannot remove it. Subagents never get the subagent tools, client tools, or TUI tools, so a subagent cannot start subagents of its own. See [tools](tools.md) for how tool availability works in general.
+Every native Tau subagent also gets the built-in `tau_docs` tool, and a persona's `tools` list cannot remove it. Subagents never get `agents`: their `code` tool has no `tau.agents`, and they have no `wait_for_agents`. A subagent cannot start or manage other agents.
+
+Subagents also never get [client tools](client-tools.md), such as the TUI's tools or a Telegram runner's file delivery tools. Only the main agent uses tools that attached clients offer. See [tools](tools.md) for how tool availability works in general.
 
 ## Models and settings
 
@@ -45,7 +47,7 @@ A model override uses this exact form:
 
 The provider is lowercased. The model ID is kept exactly as written and is case-sensitive. Effort is one of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`.
 
-The configured list of launch models is an allowlist. It does not choose a default. The main agent should normally omit the `model` argument to `spawn_agent`, and the subagent then uses the active persona's model and reasoning. When `model` is given, it must exactly match an allowlist entry after normalization. For native Tau subagents, the override changes the provider, model, and reasoning, and keeps the other settings.
+The configured list of launch models is an allowlist. It does not choose a default. The main agent should normally omit the `model` option of `tau.agents.spawn`, and the subagent then uses the active persona's model and reasoning. When `model` is given, it must exactly match an allowlist entry after normalization. For native Tau subagents, the override changes the provider, model, and reasoning, and keeps the other settings.
 
 A model ID may be missing from the catalog if its provider is known (see [models](models.md)). An entry with an invalid provider, model, effort, or format makes the configuration field invalid. Duplicate entries are removed.
 
@@ -64,13 +66,13 @@ Configure the allowlist with `subagents.launchModels` in `config.json`:
 }
 ```
 
-The nearest `launchModels` list replaces broader ones; lists are not combined. The resulting list applies to every persona that has `spawn_agent`.
+The nearest `launchModels` list replaces broader ones; lists are not combined. The resulting list applies to every persona that has `agents`.
 
 ## Claude Code subagents
 
-The `claude-code` launch provider runs Claude Code through Anthropic's Agent SDK. The main agent uses the usual spawn, list, wait, follow-up, and interrupt tools to manage these workers. Claude Code models are available only as explicit subagent launch overrides.
+The `claude-code` launch provider runs Claude Code through Anthropic's Agent SDK. The main agent manages these workers with the same `tau.agents` methods and `wait_for_agents` tool as native Tau subagents. Claude Code models are available only as explicit subagent launch overrides.
 
-Install Claude Code on the session's execution environment, put `claude` on its login-shell `PATH`, and sign in there with a Claude subscription. A login on the host or attached laptop does not reach a separate execution environment. Tau includes Agent SDK 0.3.308, so no separate SDK installation is needed.
+Install Claude Code on the session's execution environment, put `claude` on its login-shell `PATH`, and sign in there with a Claude subscription. A login on the host or attached laptop does not reach a separate execution environment. Tau includes Agent SDK 0.3.312, so no separate SDK installation is needed.
 
 Add the desired model/effort combinations to the launch allowlist:
 
@@ -90,7 +92,7 @@ These are the three supported model IDs. Effort may be `low`, `medium`, `high`,
 
 Claude Code manages its conversation, retries, and compaction. Each run allows up to 1,024 agentic turns. Tau passes the selected model, effort, working directory, and task. Other Tau model settings, such as service tier, do not apply. Follow-ups resume the same Claude session.
 
-The worker uses Claude Code's native system prompt with a short addition: complete the task autonomously, preserve other agents' work, and return a self-contained result. It cannot ask the parent or user for clarification. Tau does not copy the parent conversation, persona prompt, project instructions, or skill descriptions. The worker is instructed to follow applicable project instructions itself.
+The worker uses Claude Code's native system prompt with a short addition: complete the task autonomously, treat later messages as coming from the parent agent, preserve other agents' work, and return a self-contained result. It cannot ask the parent or user for clarification. Tau does not copy the parent conversation, persona prompt, project instructions, or skill descriptions. The worker is instructed to follow applicable project instructions itself.
 
 Claude Code loads its user, project, and local settings and discovers its own instructions and skills. The `Skill` tool is always available. Other native tools follow the parent persona's selection:
 
@@ -106,15 +108,17 @@ Workers receive no Tau `code` capabilities, host MCP connections, `tau_docs`, or
 
 Selected tools use `bypassPermissions`, with Claude Code's sandbox disabled. They run with the execution environment's operating-system authority, like Tau's tools. Review the local Claude settings, skills, and MCP configuration before enabling these workers.
 
-Tau displays short assistant updates and tool completion summaries. Full tool output stays in Claude Code's conversation files. Tau records SDK-reported assistant token usage as it arrives, so interruption preserves counts already received. Repeated message blocks and resumed messages are counted once. Final SDK totals reconcile these counts and supply cost estimates, including earlier usage when a session resumes. Cost from an interrupted run remains unavailable until the SDK reports it. The latest assistant usage supplies a context-token estimate; after a successful run, the SDK's context summary supplies the window size and a fuller measurement.
+Tau displays short assistant updates and tool completion summaries. It also records the worker's assistant text, tool calls, and tool results in the worker's [trace](#conversation-traces), using Claude Code's own tool names, such as `Bash` and `Read`. Tau records SDK-reported assistant token usage as it arrives, so interruption preserves counts already received. Repeated message blocks and resumed messages are counted once. Final SDK totals reconcile these counts and supply cost estimates, including earlier usage when a session resumes. Cost from an interrupted run remains unavailable until the SDK reports it. The latest assistant usage supplies a context-token estimate; after a successful run, the SDK's context summary supplies the window size and a fuller measurement.
 
 Before sending the task, Tau checks that the SDK reports a subscription login without API-key authentication. Claude Code keeps its own credentials. Tau removes API and cloud-provider routing overrides from the child environment and provides no API fallback. Fast mode is disabled. Account-level extra usage can still incur charges; disable it in Claude to use only the included subscription allowance. The SDK's dollar estimates do not report subscription charges.
 
+Steering messages go to Claude Code through the Agent SDK's streaming input while the worker is busy. Claude Code decides when to read them, typically between tool rounds, and a tool that is already running may continue. A steering message that Claude Code has not read when its turn ends is handled in another turn. Queued messages wait until Claude Code reports that its turn is finished.
+
 Claude workers share the eight-worker limit and the usual subagent lifetime. Interrupting a worker terminates its process group. A follow-up can resume its Claude session while the parent session remains alive. Host restart, session disposal, and rewind remove workers under the same rules as native Tau subagents. Claude's transcript files remain on disk, but Tau does not use them to restore workers after a restart.
 
 ## Working directory
 
-`spawn_agent` normally runs the subagent in the main session's `cwd`. The optional `workingDirectory` may be absolute or relative to that `cwd`. Tau resolves it to an absolute path on the execution environment.
+`tau.agents.spawn` normally runs the subagent in the main session's `cwd`. The optional `workingDirectory` may be absolute or relative to that `cwd`. Tau resolves it to an absolute path on the execution environment.
 
 For native Tau subagents, when that path differs from the parent's `cwd`, Tau rebuilds the subagent's context for the new directory. It detects the platform and repository there, reads the applicable `AGENTS.md` files, and discovers that directory's skills.
 
@@ -124,43 +128,118 @@ For native Tau subagents, the new directory does not change the persona, model c
 
 A native Tau launch fails if Tau cannot build context for the directory, if the directory is invalid for the environment, or if the environment cannot resolve working directories. A path that resolves to the parent's `cwd`, such as `.`, reuses the parent's context. Claude Code workers load context themselves in the selected directory; an invalid directory fails when the worker starts.
 
-## Lifecycle and subagent tools
+## Managing subagents
+
+The main agent manages subagents with `tau.agents` inside the [`code` tool](code-mode.md), and waits for them with the `wait_for_agents` tool. Each subagent has an ID that the host generates, and one conversation that grows with each input.
 
-Each subagent has an ID that the host generates.
+| Method | Purpose |
+| --- | --- |
+| `spawn({ title, prompt, model?, workingDirectory? })` | Start a subagent. |
+| `list()` | State of every subagent, plus the number running and the limit. |
+| `read({ id })` | State of one subagent. |
+| `sendInput({ id, message, mode })` | Queue or steer more input. |
+| `interrupt({ id, wait? })` | Stop the current turn and discard pending input. |
+| `waitUntilIdle({ id })` | Wait inside a program until the subagent is idle. |
+| `trace({ id, kinds?, toolName?, limit?, cursor? })` | Read a page of the subagent's conversation. |
+| `readText({ id, seq, maxChars? })` | Read the text of one assistant message or tool result. |
+| `readContent({ id, ref, cursor? })` | Page through large or non-text content. |
+
+The agent reads the complete reference, with types and examples, by printing `await tau.docs("agents")` in `code`. A program reads conversation data into JavaScript variables. Only what the program prints reaches the main agent's conversation, so the agent can select the part of a long trace it needs.
 
 ### Spawn
 
-`spawn_agent` takes a title, a prompt, an optional model, and an optional working directory. The prompt is the subagent's only initial input, so it should be self-contained. The call returns right away with the new ID, and the subagent keeps working in the background.
+`spawn` takes a single-line title of at most 512 characters, a prompt of at most 262,144 characters, an optional model, and an optional working directory. The prompt is the subagent's first message, and the subagent does not see the parent conversation, so the prompt should be self-contained. The call returns right away with the subagent's state, and the subagent keeps working in the background.
+
+When the main persona has `history`, a native Tau subagent may read the parent session's transcript as a last resort, when missing context would stop the work or force an important assumption. It reads with `tau.history.read` and `source: "local"`, so the read uses the host's local history even when a remote collection is configured. Local recording is best-effort, so the newest parent entries can occasionally be missing.
+
+At most eight subagents can be working at once in one main session. Idle subagents do not count toward this limit.
+
+### State and waiting
+
+A subagent's state has its ID, title, model and reasoning, working directory, status, counts of pending queued and steering input, token usage, context size, and cost. The status is one of:
+
+- `working`: the subagent is handling input.
+- `stopping`: an interrupt was requested and the turn has not ended yet.
+- `idle`: no turn is running and no input is pending. `reason` tells how the latest turn ended: `completed`, `interrupted`, or `failed`, with an error code and message for a failure.
+
+`completed` means the turn ended normally. It does not mean the task succeeded, so the main agent reads the subagent's answer before relying on it. Background Bash and code jobs that a subagent started do not keep it working. A subagent that needs a job's result must wait for the job before it answers.
+
+`wait_for_agents` takes one or more IDs. It returns as soon as at least one of them is idle, with a text block for every requested subagent:
+
+```
+id: 0b6c2f1e-7d4a-4c1b-9a53-2e8f0d9c4b71
+title: "review authentication"
+status: idle
+reason: completed
+pending: queue=0 steer=0
+response_seq: 42
+response_complete: true
+response_partial: false
+
+--- response ---
+No problems found in the session expiry checks.
+```
+
+A subagent that is still working or stopping gets only its ID, title, status, and pending counts. An idle subagent also gets `reason`, an `error` line with the code and message after a failed turn, and the last assistant message from its latest turn:
 
-At most eight subagents can be running at once in one main session. Subagents that have finished or been interrupted do not count toward this limit.
+- `response_seq` is the message's `seq` in the trace. `readText({ id, seq, maxChars })` in `code` reads more retained text. For messages beyond its limit, use `trace` to get the content reference and page through it with `readContent`.
+- `response_complete` is `false` when the text was shortened to fit the budget, or when some of it is unavailable or was removed from the trace. Shortened text keeps its beginning and end, with a marker in the middle.
+- `response_partial` is `true` when the turn failed or was interrupted, so the message may be an unfinished answer.
+- `response: none` replaces these lines when the latest turn produced no assistant message. A message from an earlier turn is never returned.
 
-### Observe and wait
+The response text of all requested subagents shares a budget of 8,192 estimated tokens, split evenly between them, working ones included. The optional `maxOutputTokens` sets a different budget, from 1 to 65,536.
 
-`list_agents` returns every subagent with its ID, name, title, model and reasoning, working directory, run state, context usage, cost, and whether a response is ready. Use it to find an ID again or to check progress.
+Inside a program, `waitUntilIdle` waits for one subagent with the same meaning of idle and returns its state without the response. Neither wait returns until queued input has been handled too. Cancelling a wait, or stopping the program that waits, does not interrupt the subagent.
 
-`wait_for_agents` takes one or more IDs. It returns as soon as at least one of them finishes, with the current state of all of them. A finished response stays readable through later waits until a follow-up run replaces it.
+The host also sends live subagent activity to attached clients for display. It is a summary for display. The subagent's messages and tool results are in its trace.
 
-The host also sends live subagent activity to attached clients for display. It is a summary for display, and the final response from these tools remains the real result.
+### Send more input
 
-### Follow up
+`sendInput` requires a `mode`:
 
-`send_input_to_agent` starts another run on an idle subagent. The subagent keeps its conversation, model, settings, tools, and working directory. It must finish or be interrupted before it accepts more input.
+- `queue`: the subagent finishes its current work, then handles the message as a separate turn. Queued messages run in the order they were sent.
+- `steer`: the subagent takes the message into account as soon as possible during its current turn. A native Tau subagent applies it at the next safe point, never in the middle of a model response or tool call, as in the [main session](sessions.md#submit-queue-and-steer). [Claude Code subagents](#claude-code-subagents) follow Claude Code's own streaming-input behavior.
 
-A follow-up replaces the subagent's previous response, so read anything you need first. Follow-ups do not pick up a changed persona definition or a reloaded allowlist.
+Either mode starts a new turn right away on an idle subagent. The call returns once the input is accepted, before the subagent reads it. The subagent keeps its conversation, model, settings, tools, and working directory. Earlier messages stay readable in its trace.
+
+Sending input fails while the subagent is stopping, when 64 inputs are already pending, or when the subagent is idle and eight subagents are already working. Follow-up input does not pick up a changed persona definition or a reloaded allowlist.
 
 ### Interrupt
 
-`interrupt_agent` asks the current run to stop and waits for the subagent's latest state. The subagent stays available for follow-up input. On an idle subagent, the call just returns its state.
+`interrupt` stops the current turn and discards all pending input, so the subagent does not continue with queued work. By default the call waits until the turn has ended. With `wait: false` it returns right away, and the status may still be `stopping`. Interrupting an idle subagent only returns its state. Background jobs that the subagent started keep running, and the subagent stays available for more input.
 
 In the TUI, `Ctrl+G` interrupts the selected running subagent. Interrupting the main session does not interrupt subagents, and interrupting a subagent does not interrupt the main session.
 
+### Conversation traces
+
+Each subagent has a trace: an ordered record of what it was told, what it said, and what its tools returned. Native Tau and Claude Code subagents produce the same kinds of entries:
+
+| Kind | Contents |
+| --- | --- |
+| `input` | Each message the subagent was sent, with its mode: `initial`, `queue`, or `steer`. Recorded when the message is accepted. |
+| `assistant` | The subagent's message text. |
+| `tool_call` | The tool name, call ID, and arguments as JSON. |
+| `tool_result` | The tool name, call ID, outcome, and the result exactly as the subagent received it. |
+| `notice` | An event with a machine-readable code, such as `input.discarded` after an interrupt or `compaction.compacted`. A failed turn adds a notice with the failure code. |
+| `status` | The subagent started working, began stopping, or became idle. |
+
+Traces do not contain reasoning or system prompts. A tool result that the tool itself shortened stays shortened, and the trace cannot recover the missing output.
+
+Each entry has a sequence number `seq` and a timestamp. A `trace` call returns the newest matching entries in chronological order, 20 by default and at most 50. It can filter by entry kinds and by tool name. Its `nextCursor` leads to older entries. A cursor keeps its starting point, so new activity does not shift the pages.
+
+Content of at most 4,096 bytes as JSON, without images, is inline in the entry. Larger content and all images are references. `readText` returns the text of one assistant message or tool result, up to 30,000 UTF-16 code units by default and at most 100,000. Its `complete` field is `false` when the text was cut or some content is unavailable. It does not detect output that the tool itself shortened. Content with JSON or images needs `readContent`, which returns one block per page. Text arrives in chunks of at most 16,384 UTF-16 code units that join to the exact text.
+
+A trace keeps the newest 4,096 entries, up to 64 MiB, for each subagent. When older entries are removed, trace pages report `historyEvicted: true`, and reading a removed entry or reference fails. A single content value larger than 6 MiB is replaced by a block that marks it unavailable. Traces last as long as the subagent and do not survive a host restart.
+
+A failed call throws an error with a `code` and a `message`. The codes are `invalid_arguments`, `unknown_agent`, `invalid_cursor`, `expired_content`, `content_type`, `operation_failed`, and `cancelled`. A subagent's own failure is part of its state and trace, not a failed call.
+
 ## Detach, rewind, and recovery
 
 Subagents belong to the running session on the host, not to an attached TUI. Detaching a client, or losing the connection, does not stop them while the session stays alive. Another client can attach to the session and see their current state.
 
 Subagents do not survive the end of a session on the host or a host restart. Their status may be saved while the session is live, but recovery removes those records, because their runtimes no longer exist. A recovered session cannot send input to an old subagent ID.
 
-Rewind also removes subagents that were started by an assistant message the rewind removed. Host shutdown or session disposal interrupts and removes all subagents.
+Rewind also removes subagents that were started by an assistant message the rewind removed. A subagent started from a `code` program belongs to the assistant message that ran the program, including a program running as a background job. Host shutdown or session disposal interrupts and removes all subagents.
 
 Plan long work with this in mind. Important results should reach the main agent and end up in the session history or in project files before the session on the host goes away. [Sessions](sessions.md) covers saving and recovery in general.
 
@@ -170,6 +249,6 @@ Changes to persona tools or to the launch allowlist apply after `/reload` in an
 
 `subagents.launchModels` must be an array of valid `<provider>/<model>:<effort>` strings. Unknown providers, invalid efforts, and malformed entries produce configuration warnings.
 
-A launch can fail because of invalid arguments, a model outside the allowlist, the concurrency limit, a prompt that cannot be built, or a working directory whose context cannot be built. Follow-up, wait, and interrupt calls reject unknown IDs. A follow-up also fails while the subagent is still running.
+A launch can fail because of invalid arguments, a model outside the allowlist, the concurrency limit, a prompt that cannot be built, or a working directory whose context cannot be built. Calls with an unknown subagent ID fail. Sending input also fails under the conditions in [send more input](#send-more-input).
 
-Before starting a local TUI, `tau --debug --persona <id>` shows which tools are available, the model and settings subagents inherit, and the subagents' tool list. In a running session, `/reload` reports file warnings and `list_agents` shows live subagent state.
+Before starting a local TUI, `tau --debug --persona <id>` shows which tools are available, the model and settings subagents inherit, and the subagents' tool list. In a running session, `/reload` reports file warnings and `tau.agents.list()` shows live subagent state.

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

@@ -40,16 +40,12 @@ web
 history
 mcp
 models
-spawn_agent
-send_input_to_agent
-wait_for_agents
-list_agents
-interrupt_agent
+agents
 ```
 
-A custom persona that omits `tools` gets `bash`, `write`, `edit`, `view_image`, `web`, `history`, `mcp`, and `models`, plus the five subagent tools. Built-in personas get the same set.
+A custom persona that omits `tools` gets all of these names. Built-in personas get the same set.
 
-`web`, `history`, `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.
+`web`, `history`, `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`. `agents` enables `tau.agents` inside `code` and the `wait_for_agents` tool, which together start and manage [subagents](subagents.md). Tau adds `code` and its [job tools](code-mode.md#background-code-jobs) 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 turns off every selectable tool:
 
@@ -89,7 +85,7 @@ Agents are told to choose the mode that avoids needless waiting. Background mode
 
 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 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.
+The default foreground timeout is 60 seconds. Tau captures at most 24 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 that keeps the beginning and end, with a notice. The command has still run in full, with all its side effects.
 
 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.
 
@@ -97,21 +93,40 @@ In a local execution environment, Tau removes inherited environment variables wh
 
 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` 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.
+With `background: true`, `bash` starts the command and returns a job ID right away, without waiting for it to exit. Background jobs have no time limit, and combining `background: true` with `timeout` or `maxOutputTokens` is invalid. Jobs keep running across turns and interruptions.
 
-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.
+Each job belongs to the agent that started it, and only that agent can list, read, wait for, or stop it. The main agent, each subagent, and each ephemeral thread have separate jobs. A subagent keeps its jobs across follow-up messages. An ephemeral thread, including a fork, starts with no jobs.
 
-`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.
+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. Each job appears as a block of labeled lines: `id`, `status`, `command`, `cwd`, and, once the command has exited, `exit_code` and any terminating `signal`. Read, stop, and wait add the job's output after an `--- output ---` line. List never includes output. For example:
 
-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.
+```text
+id: <job id>
+status: running
+command: "npm test"
+cwd: "/work/app"
+output: truncated; showing beginning and end
+
+--- output ---
+<beginning and end of output>
+```
+
+Stop terminates the job's process group, kills it if it has not exited after a grace period, and waits until it has stopped. Tau keeps up to 64 job records for each agent and drops the oldest finished one when needed. Starting a job fails if all 64 are still running.
+
+Each job keeps the last 24 MiB of combined output. Read, stop, and wait return that output within a budget of 8,192 estimated tokens for the whole response by default, divided evenly among the requested jobs. `maxOutputTokens` sets this budget, from 1 to 65,536. When a job's output exceeds its share, the result shows the beginning and the end. The `output: truncated` line means only that this response shows part of the output. A separate `capture: truncated` line means the job produced more than 24 MiB, so its earliest output is lost.
+
+When a job with output finishes, Tau writes all of its retained text to a temporary file in the execution environment. Later results that include output give the file's path as `text_log`, so the agent can read or search it instead of raising the budget or running the command again. A running job has no text log. If the file cannot be written, the result shows `text_log: unavailable`.
+
+`read_bash_job`, `stop_bash_job`, and `wait_for_bash_jobs` accept `includeOutput`, which defaults to `true`. With `false`, the result has only the labeled job lines. It leaves out output, truncation lines, the text log, and execution error messages.
+
+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>`.
 
 Background launch and job-tool footers show the tool call's duration, estimated tokens, and line count. Counts cover the exact text returned to the model after output limits, before the card preview is shortened. With `includeOutput: false`, only returned job information counts. The launch footer also includes the working directory. A `◆` marker means included command output was truncated; shortening the card preview alone does not add it. A wait that reaches its timeout appends `timed out` without making the card an error. Durations measure the tool call, not the job's lifetime, and cards remain snapshots of that call.
 
 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 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.
+`wait_for_bash_jobs({ids, timeout?, includeOutput?, maxOutputTokens?})` 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. It starts with a note that the jobs are still running, followed by their current blocks, and does not stop the jobs. Interrupting the wait leaves them running too. A job finishing never starts an agent turn by itself.
 
-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.
+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 the jobs of every agent in the session. Job records 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
 
@@ -142,56 +157,11 @@ Each guide covers setup, input, examples, outputs, and failures. Run `tau tool -
 
 ## Code-mode composition
 
-`code` runs a one-off JavaScript program that combines the enabled capabilities: `tau.web`, `tau.history`, `tau.mcp`, `tau.bash`, and `tau.models`. The Bash, write, edit, and image tools stay available as separate tools.
-
-### Documentation and output
-
-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 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 does not re-read documentation it has already seen. MCP tool descriptions are read separately. Programs do not need to print intermediate results.
-
-`printText` accepts only strings; objects and arrays throw a `TypeError`. The agent selects relevant fields and explicitly formats concise plain text to save tokens. `JSON.stringify` is reserved for cases where the structure matters or machine-readable JSON is requested, with fields selected first instead of dumping whole responses.
-
-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 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 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" });
-printText(truncate(result.stdout, { maxChars: 4000 }));
-```
-
-### Execution and limits
-
-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` 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 fetching page content. Search uses Auto with Dynamic Highlights to select evidence across results. An optional `objective` (1–4,096 nonblank characters) describes the broader task and facts to extract. Results include a `notices` array with retrieval qualifications such as relaxed query restrictions; each notice retains its `code`, `path`, `message`, and optional `details`. The agent prints notices alongside selected search results. 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.mcp`: finding and calling tools and resources on configured MCP servers. When the persona allows MCP, enabled server names and optional configured descriptions are visible in the initial tool definition, before any tool call. Disabled servers and connection settings are omitted. These summaries guide discovery and do not grant permission to act. 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.
-
-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.
+`code` runs a JavaScript program, inline or from a saved file, that combines the enabled capabilities. It can also run the program as a background job. See [code mode](code-mode.md) for input, output, limits, background code jobs, and each capability.
 
 ## Subagent tools
 
-A subagent gets each of `bash`, `write`, `edit`, `view_image`, `web`, `history`, `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.
+A subagent gets each of `bash`, `write`, `edit`, `view_image`, `web`, `history`, `mcp`, and `models` that the main persona also has, plus `tau_docs`. It never gets `agents` 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
 
@@ -223,7 +193,7 @@ The runner holds the upload credentials, and the recipient is always the session
 First work out where the tool should come from:
 
 - 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 tool inside a subagent, 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.
 

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

@@ -117,11 +117,11 @@ For a host tool, check the active persona's `tools` list. A list replaces the de
 
 For subagents, check three things:
 
-1. The main persona has `spawn_agent` and any other subagent tools needed.
+1. The main persona has `agents`.
 2. A requested model exactly matches an entry in the launch allowlist.
 3. Fewer than eight subagents are running.
 
-A running subagent keeps its model, tools, and working directory after a reload. Recovery does not restore subagents, so old IDs cannot receive follow-ups after a host restart. Use `list_agents` to see live subagents. See [subagents](subagents.md).
+A running subagent keeps its model, tools, and working directory after a reload. Recovery does not restore subagents, so old IDs cannot receive follow-ups after a host restart. Use `tau.agents.list()` in `code` to see live subagents. See [subagents](subagents.md).
 
 If `tau_docs` is missing, the problem is the host's installation or version, not a persona. Check the host package and restart it.