@markusylisiurunen/tau 0.3.89 → 0.3.91

package/dist/core/history/threaded_history_store.js

@@ -0,0 +1,107 @@
+import { Worker } from "node:worker_threads";
+export class ThreadedHistoryStore {
+    path;
+    worker;
+    pending = new Map();
+    nextId = 0;
+    closed = false;
+    constructor(path) {
+        this.path = path;
+    }
+    createSession(...args) {
+        return this.request("createSession", args);
+    }
+    append(...args) {
+        return this.request("append", args);
+    }
+    truncateFromSources(...args) {
+        return this.request("truncateFromSources", args);
+    }
+    search(...args) {
+        return this.request("search", args);
+    }
+    read(...args) {
+        return this.request("read", args);
+    }
+    listPendingOperations(...args) {
+        return this.request("listPendingOperations", args);
+    }
+    listPendingOperationLanes(...args) {
+        return this.request("listPendingOperationLanes", args);
+    }
+    acknowledgeOperations(...args) {
+        return this.request("acknowledgeOperations", args);
+    }
+    quarantineReplicationSession(...args) {
+        return this.request("quarantineReplicationSession", args);
+    }
+    clearReplicationFailure(...args) {
+        return this.request("clearReplicationFailure", args);
+    }
+    listReplicationFailures(...args) {
+        return this.request("listReplicationFailures", args);
+    }
+    close() {
+        this.closed = true;
+        const worker = this.worker;
+        this.fail(new Error("history store is closed"));
+        if (worker)
+            void worker.terminate();
+    }
+    request(method, args) {
+        if (this.closed)
+            return Promise.reject(new Error("history store is closed"));
+        if (!this.worker) {
+            const worker = new Worker(new URL("./history_store_worker.js", import.meta.url), {
+                workerData: { path: this.path },
+                execArgv: [],
+            });
+            this.worker = worker;
+            worker.on("message", ({ id, result, error }) => {
+                const pending = this.pending.get(id);
+                if (!pending)
+                    return;
+                this.pending.delete(id);
+                if (error)
+                    pending.reject(Object.assign(new Error(error.message), { errcode: error.errcode }));
+                else
+                    pending.resolve(result);
+                if (this.pending.size === 0)
+                    worker.unref();
+            });
+            worker.on("error", (error) => {
+                if (this.worker === worker)
+                    this.fail(error);
+            });
+            worker.on("exit", (code) => {
+                if (this.worker === worker)
+                    this.fail(new Error(`history worker exited (${code})`));
+            });
+        }
+        const worker = this.worker;
+        worker.ref();
+        return new Promise((resolve, reject) => {
+            const id = ++this.nextId;
+            this.pending.set(id, {
+                resolve: (value) => resolve(value),
+                reject,
+            });
+            try {
+                worker.postMessage({ id, method, args });
+            }
+            catch (error) {
+                this.pending.delete(id);
+                if (this.pending.size === 0)
+                    worker.unref();
+                reject(error);
+            }
+        });
+    }
+    fail(error) {
+        this.worker = undefined;
+        for (const pending of this.pending.values())
+            pending.reject(error);
+        this.pending.clear();
+    }
+}
+//# sourceMappingURL=threaded_history_store.js.map

package/dist/core/history/threaded_history_store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"threaded_history_store.js","sourceRoot":"","sources":["../../../src/core/history/threaded_history_store.ts"],"names":[],"mappings":"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"}

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

@@ -15,7 +15,7 @@ The TUI also offers the configured command client tools selected for its own wor
 
 A Telegram runner offers the built-in `send_photo_to_telegram`, `send_video_to_telegram`, `send_audio_to_telegram`, and `send_document_to_telegram` tools, plus the command client tools selected by each prepared workspace's Tau configuration. The built-in [file delivery tools](tools.md#sending-files-to-telegram) send files to the session's chat and are not affected by `enabledClientTools`. The runner does not offer the TUI's tools. The session's workspace, whether repository, persistent directory, or composite, decides which configuration selects its tools. See [Telegram projects and workspaces](telegram-projects.md) for workspace types.
 
-Node SDK clients can pass `TauSdkClientTool` handlers when they initialize. The same rules for routing, cancellation, and execution-environment access apply.
+Node SDK clients can pass `TauSdkClientTool` handlers when they initialize. Their schemas may set `executionTimeoutMs` to `null` for no execution deadline, or omit it for the 60-second default. Configured command tools require a positive timeout and do not accept `null`. The same rules for routing, cancellation, and execution-environment access apply.
 
 Only a client that is observing a session can add tools to it. The tools disappear when that client detaches or disconnects. When several clients observe one session, only one may offer a given tool name, and Tau rejects the later client if names collide. Client tool names also must not match host tools or built-in tools.
 

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

@@ -10,7 +10,8 @@ The host makes model calls and runs services such as web search and remote histo
 
 | Operation | Where the credential belongs |
 | --- | --- |
-| Main-agent, subagent, sampling, and maintenance model calls | Session host |
+| Main-agent, native Tau subagent, sampling, and maintenance model calls | Session host |
+| Claude Code subagent subscription login | Claude Code on the execution environment |
 | OpenAI Codex OAuth accounts | Session host home |
 | Exa-backed `web.search` and `web.fetch` | Session host |
 | Remote history replication and queries | Session host |
@@ -22,6 +23,8 @@ The host makes model calls and runs services such as web search and remote histo
 
 With local `tau`, all of these are usually one machine. With `tau attach`, a key set only in the attached client's shell does not reach the remote host. Run `tau auth` on the host machine, and set host environment variables where `tau serve` or the SDK host runs. See [ownership and scope](ownership-and-scope.md) for the full boundary.
 
+Claude Code subagents use a Claude subscription login on the execution environment. Sign in with Claude Code there; `tau auth` does not manage this account. Tau checks the account before sending a task and does not fall back to API billing. See [Claude Code subagents](subagents.md#claude-code-subagents) for setup and extra-usage charges.
+
 ## Provider API keys
 
 Tau accepts provider API keys in global configuration:

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

@@ -23,7 +23,13 @@ For each session, history stores the creation attributes and the active transcri
 
 `<system>...</system>` blocks at the start of user messages stay in history. Tool arguments and results can contain file contents, command output, and other sensitive data, so treat the database as private. Tau creates its directory and file with private permissions, but the host user and the machine's administrators can still read them. Never copy the database into a repository or share it.
 
-Recording history is best effort. If the database cannot open, or a later write fails, the session keeps running. Tau adds one `history unavailable` warning to the session, which stays in the session, and turns history off until the host restarts. A restart tries to open the database again.
+Recording history is best effort and never waits for database locks on the agent's event loop. The host buffers changes in memory and writes them in order from a background worker. Temporary SQLite contention delays recording; the worker retries automatically, including when opening the database. Normal appends and rewinds retain their order while waiting.
+
+The buffer holds up to 64 MiB of serialized changes per host. When it fills, new changes are dropped until space is available. Other local write errors drop the affected change rather than disabling history. Later changes in the same session are still recorded. Session files and agent work are unaffected by history failures.
+
+Pending changes have not reached durable storage. A crash can lose them; normal shutdown gives recording and replication up to two seconds to flush. Events already committed to SQLite remain on disk, including any pending remote replication. Tau does not automatically reconstruct missing history from session files.
+
+Hosts emit `history_recording` diagnostics with a `delayed`, `dropped`, or `recovered` status, a session ID, and pending operation and byte counts. The TUI displays them, headless hosts write them to stderr, and in-process SDK hosts deliver them through `onDiagnostic`. Repeated drop diagnostics are rate-limited. A recording gap does not stop later recording or require a host restart.
 
 ## How session operations affect history
 
@@ -202,13 +208,13 @@ Cloudflare problems show up in the normal Worker logs, Cron Events, and D1 diagn
 
 **The agent has no history capability.** The active persona must select `history`. Fix the persona and run `/reload` while idle.
 
-**The history capability returns a service error while the session works.** Remote searches and replication can fail without affecting the session. Check that the endpoint is reachable and read the Worker logs, without printing the key. Local recording continues unless the session also shows a `history unavailable` warning.
+**The history capability returns a service error while the session works.** Remote searches and replication can fail without affecting the session or local recording. Check that the endpoint is reachable and read the Worker logs, without printing the key. Check `history_recording` diagnostics separately for local write failures.
 
 **The browser keeps asking for credentials.** Use username `tau` and the viewer password from the latest setup. The API key is for hosts and does not work in the browser.
 
 **A session does not appear in remote search.** Confirm the host was restarted with the remote config, the session was used while the config was active, and enough history activity has happened to send the outbox. Check host logs for `history_replication_failed`. A permanent rejection affects only the named session, while other failures are retried. Summaries are not immediate.
 
-**Local history became unavailable.** On the host, check that you are running as the expected user and home, and check file access, free space, and ownership of `~/.config/tau`, the Node version, and whether another process is using the database. A restart is needed to reopen history after a local failure. Do not open, edit, replace, or delete the SQLite files as a first repair, and do not inspect outbox rows or keys.
+**Local history is delayed or dropping changes.** Brief SQLite contention is retried automatically. For sustained failures, check the host's `history_recording` diagnostics, file access, free space, ownership of `~/.config/tau`, and whether another process holds a long database transaction. Fixing the underlying problem lets later writes proceed without restarting the host; dropped changes remain gaps. `tau history status` reports remote replication quarantines, not the live recording buffer. Do not edit, replace, or delete the SQLite files as a first repair, and do not inspect outbox rows or keys.
 
 **Search finds material removed from the model's context.** This is expected after compaction. After a rewind, the removed entries should disappear; if the remote copy still has them, wait for the deletion to replicate.
 

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

@@ -52,7 +52,7 @@ type TauSdkClientOptions = {
 
 `persona`, `reasoning`, and `noAgentContextFiles` apply to sessions created by this host. `connectTimeoutMs` defaults to 5,000 ms. Default initialization metadata is `{ client: { name: "tau-sdk", version: "1" } }`.
 
-The in-process host never writes background diagnostics to stdout or stderr. Set `onDiagnostic` to receive them as structured objects, such as history replication failures that will be retried, and route them to your application's logging.
+The in-process host never writes background diagnostics to stdout or stderr. Set `onDiagnostic` to receive them as structured objects and route them to your application's logging. `history_recording` reports delayed, dropped, or recovered local recording, with a session ID and pending operation and byte counts. `history_replication_failed` reports remote delivery failures. Neither stops agent work; see [history](history.md) for retry behavior and durability limits.
 
 By default, creating an in-process client starts one background check of the model catalog against `pi.dev`. The host loads `~/.config/tau/models-store.json` first, never refreshes on a timer, and keeps each session on the catalog it started with until `session.reload()`. Set `refreshModelCatalog: false` to skip this client's check, or set `TAU_OFFLINE` to skip automatic checks for the whole process. Neither removes an existing cache or blocks an explicit `tau models refresh`. See [models](models.md) for details and [security](security.md) for why the catalog is trusted.
 

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

@@ -24,6 +24,8 @@ The built-in `tau_docs` tool also belongs to the host. It reads the documentatio
 
 The **execution environment** is the machine the agent can act on. It owns the agent-visible working directory (`cwd`), home, platform, environment, filesystem, processes, project repository, project configuration and content, `AGENTS.md` files, skills, and command resolution.
 
+[Claude Code subagents](subagents.md#claude-code-subagents) run their model calls here and keep their subscription login and conversation files here. The host starts, observes, and stops these workers through the execution environment. Their credentials remain with Claude Code.
+
 Tau reads files and runs commands through the execution environment, even when it is on the same machine as the host. Each session has exactly one execution environment. Paths shown to the agent and paths passed to its tools are always paths on that environment.
 
 ### Telegram runner

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

@@ -20,6 +20,8 @@ Give each part only the access it needs:
 
 Interruption, timeouts, output limits, and process-group termination limit how long and how much a command runs. They do not ask for approval and cannot undo anything already done. Review destructive commands, and use Tau's normal session operations instead of asking an agent to change Tau's internal files.
 
+[Claude Code subagents](subagents.md#claude-code-subagents) run on the execution environment with permission checks bypassed and the Claude Code sandbox disabled. They load local Claude settings, project instructions, skills, and normally configured MCP servers. Review those files and server permissions before enabling workers. The parent persona controls the selected built-in tools; Claude Code's own configuration controls its MCP connections. Tau disables hooks and nested agents. Managed Claude policies still apply. Claude credentials and transcripts stay on that environment; Tau does not forward host service credentials or MCP connections. Subscription extra usage can incur charges if enabled in the Claude account.
+
 ## Treat project content as executable policy
 
 Tau loads more than source files from the execution environment. It reads project `.tau/config.json`, personas, prompts, skills, `.agents/skills`, and `AGENTS.md` from the working directory and its parents. This content can choose models and tools, add instructions, define workflows, and change which of your global client tools are offered.

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

@@ -41,7 +41,7 @@ params: {
       name: string;
       description: string;
       parameters: unknown;
-      executionTimeoutMs?: number;
+      executionTimeoutMs?: number | null; // omitted: 60 seconds; null: no execution deadline
     }>;
   };
 }

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

@@ -228,6 +228,8 @@ An initialized client that advertised a tool can receive:
 }
 ```
 
+`executionDeadlineMs` is a positive duration in milliseconds, or `null` when the advertised tool has no execution deadline. Omitting `executionTimeoutMs` from the tool definition uses 60 seconds; setting it to `null` disables only the execution deadline. Acknowledgement deadlines and cancellation on interruption or client detach still apply.
+
 Acknowledge promptly with `session.clientTool.ack`, optionally with a partial presentation for the running tool card. Start work only after the acknowledgement returns `{ accepted: true }`. Then send exactly one `session.clientTool.result` with `{ ok: true, content }` or `{ ok: false, error }`, optionally with a separate presentation for the finished card. `content` is an ordered array of text and image blocks. Both presentations may contain `subject`, `subjectWrap`, `details`, and `metadata`. The host sets the action and operation and fills in omitted fields. Fields you set are kept unchanged once they pass validation, while defaults are truncated the way Tau truncates its own cards. An empty `details` or `metadata` array hides that default.
 
 A successful result is rejected until the acknowledgement has completed. If preparation fails, send an error result before acknowledging; the host records a preparation failure and the tool never runs. If no result arrives, because of a timeout, cancellation, detach, or other failure, the host shows a complete default card. The result method returns `{ accepted: boolean }`; `false` means the result does not fit the call's current state or the call no longer expects it.

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

@@ -6,7 +6,7 @@ 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 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 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.
 
 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).
 
@@ -18,7 +18,7 @@ The agent follows this rule itself. Tau checks that a launch is valid, but it do
 
 ## Tools
 
-A subagent can receive these tools:
+A native Tau subagent can receive these tools. [Claude Code subagents](#claude-code-subagents) use the corresponding Claude Code tools instead:
 
 - `bash`
 - `write`
@@ -32,7 +32,7 @@ A subagent can receive these tools:
 
 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.
 
-Every 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 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.
 
 ## Models and settings
 
@@ -46,7 +46,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. 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` 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.
 
 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.
 
@@ -67,17 +67,63 @@ 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`.
 
+## 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.
+
+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.
+
+Add the desired model/effort combinations to the launch allowlist:
+
+```json
+{
+  "subagents": {
+    "launchModels": [
+      "claude-code/claude-opus-5-5:medium",
+      "claude-code/claude-sonnet-5-5:medium",
+      "claude-code/claude-haiku-5-5:low"
+    ]
+  }
+}
+```
+
+These are the three supported model IDs. Effort may be `low`, `medium`, `high`, `xhigh`, or `max`. Each permitted combination needs its own allowlist entry. Model availability also depends on the Claude account and installed Claude Code version. If Claude Code rejects a model, Tau reports the failure.
+
+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.
+
+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:
+
+| Inherited Tau tool | Claude Code tools      |
+| ------------------ | ---------------------- |
+| `bash`             | Bash, Read, Glob, Grep |
+| `view_image`       | Read, Glob, Grep       |
+| `write`            | Write                  |
+| `edit`             | Edit                   |
+| `web`              | WebSearch, WebFetch    |
+
+Workers receive no Tau `code` capabilities, host MCP connections, `tau_docs`, or client tools. Nested agents and interactive questions are disabled. Hooks and automatic memory are disabled too. Claude Code discovers its own MCP servers from its normal configuration sources, including project and user configuration on the execution environment. These connections are independent of the parent persona's `mcp` tool selection; Tau does not map or forward its host MCP connections. Managed Claude Code policies still apply.
+
+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.
+
+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.
+
+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.
 
-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.
+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.
 
-The new directory does **not** change the subagent's persona, model catalog, runtime configuration, credentials, or tool policy. Those always come from the parent session. Configuration in the new directory is read only where context needs it, such as for skill discovery.
+For native Tau subagents, the new directory does not change the persona, model catalog, runtime configuration, credentials, or tool policy. Those come from the parent session. Configuration in the new directory is read only where context needs it, such as for skill discovery.
 
 `workingDirectory` is always a path on the execution environment, which matters in monorepos and hosted environments. The host and attached clients never resolve it against their own filesystems.
 
-A 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.
+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
 
@@ -113,7 +159,7 @@ In the TUI, `Ctrl+G` interrupts the selected running subagent. Interrupting the
 
 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 the subagents' conversations no longer exist. A recovered session cannot send input to an old subagent ID.
+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.
 

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

@@ -208,6 +208,8 @@ The session host provides temporary review agents, and the local tool runs the b
 
 The TUI also offers diff review to the agent as a client tool, unless `--no-client-tools` is set. `/diff` works either way. See [client tools](client-tools.md) for what this means with several clients.
 
+Agent-launched diff reviews have no execution deadline. They remain open until submitted or closed, or until the turn is interrupted or the owning client disconnects. Acknowledgement and review initialization still have startup timeouts.
+
 The agent can use `diff_review` with `workingDirectory` to review another directory without changing the session directory. Paths refer to the session's execution environment; relative paths resolve from the session directory. The selected directory must be inside a Git repository and is used by review assistants and for relative patch-file paths. Omitting it uses the session directory.
 
 ## Use speech

package/dist/core/subagents/agent_supervisor.js

@@ -6,6 +6,7 @@ import { createAutoCompactionArchiver } from "../session/auto_compaction_archive
 import { ToolCatalog } from "../tools/catalog.js";
 import { appendUsageLogEntry, getUsageCostTotal, getUsageTotals, } from "../usage/logs.js";
 import { extractAssistantText } from "../utils/messages.js";
+import { ClaudeCodeRuntime } from "./claude_code_runtime.js";
 import { formatActiveSubagentsForCompaction } from "./format.js";
 const MAX_ACTIVE_SUBAGENTS = 8;
 async function raceWithAbort(promise, signal) {
@@ -69,31 +70,43 @@ export class AgentSupervisor {
         }
         const id = randomUUID();
         const runtimeConfig = { ...options.runtimeConfig, workingDirectory };
-        const persona = {
-            id: `${options.personaId ?? "agent"}-subagent`,
-            label: "subagent",
-            description: "Background agent",
-            source: "project",
-            systemPrompt: runtimeConfig.systemPrompt,
-            model: runtimeConfig.model,
-            settings: runtimeConfig.settings,
-            tools: runtimeConfig.tools,
-            subagentLaunchModels: [],
-        };
-        const runtime = new AgentRuntime({
-            spec: createAgentSpec({
-                autoCompactThresholdTokens: null,
-                ...resolveAgentModel(persona, options.config, {
-                    includeModelNotice: true,
-                    deps: this.deps,
+        let runtime;
+        let reasoning;
+        if (runtimeConfig.kind === "claude-code") {
+            runtime = new ClaudeCodeRuntime({
+                config: runtimeConfig,
+                backend: options.backend,
+                onEvent: async (event) => await this.recordClaudeCodeEvent(id, event),
+            });
+            reasoning = runtimeConfig.effort;
+        }
+        else {
+            runtime = new AgentRuntime({
+                spec: createAgentSpec({
+                    autoCompactThresholdTokens: null,
+                    ...resolveAgentModel({
+                        id: `${options.personaId ?? "agent"}-subagent`,
+                        label: "subagent",
+                        description: "Background agent",
+                        source: "project",
+                        systemPrompt: runtimeConfig.systemPrompt,
+                        model: runtimeConfig.model,
+                        settings: runtimeConfig.settings,
+                        tools: runtimeConfig.tools,
+                        subagentLaunchModels: [],
+                    }, options.config, {
+                        includeModelNotice: true,
+                        deps: this.deps,
+                    }),
+                    systemPrompt: runtimeConfig.systemPrompt,
+                    tools: ToolCatalog.createSubagentRegistry(runtimeConfig.tools, options.backend, workingDirectory, options.config, options.bashJobs, options.history, options.mcp),
                 }),
-                systemPrompt: runtimeConfig.systemPrompt,
-                tools: ToolCatalog.createSubagentRegistry(runtimeConfig.tools, options.backend, workingDirectory, options.config, options.bashJobs, options.history, options.mcp),
-            }),
-            eventSink: async (event) => await this.recordAgentEvent(id, event),
-            clock: this.deps.clock,
-            archiveAutoCompaction: createAutoCompactionArchiver(options.backend),
-        });
+                eventSink: async (event) => await this.recordAgentEvent(id, event),
+                clock: this.deps.clock,
+                archiveAutoCompaction: createAutoCompactionArchiver(options.backend),
+            });
+            reasoning = runtime.spec.attribution.reasoningEffort;
+        }
         const createdAt = this.deps.clock.now();
         const record = {
             id,
@@ -101,12 +114,11 @@ export class AgentSupervisor {
             model: {
                 provider: runtimeConfig.model.provider,
                 id: runtimeConfig.model.id,
-                reasoning: runtime.spec.attribution.reasoningEffort,
+                reasoning,
             },
             workingDirectory,
             createdAt,
             originHistoryEntryId: options.originHistoryEntryId,
-            runtimeConfig,
             personaId: options.personaId,
             runtime,
             run: {
@@ -122,8 +134,9 @@ export class AgentSupervisor {
                 cacheRead: 0,
                 cacheWrite: 0,
                 contextWindowUsageTokens: 0,
-                contextWindow: runtimeConfig.model.contextWindow,
+                contextWindow: runtimeConfig.kind === "native" ? runtimeConfig.model.contextWindow : 0,
             },
+            claudeMessageUsage: new Map(),
             toolPresentations: new Map(),
             blockedToolCalls: new Map(),
             completion: Promise.resolve(undefined),
@@ -193,15 +206,27 @@ export class AgentSupervisor {
         record.completion = this.emit({ type: eventType, state: this.toSnapshot(record) })
             .then(async () => {
             if (record.run.interruptRequested) {
-                return {
-                    aborted: true,
-                    terminalResult: { aborted: true },
-                };
+                this.finishInterrupted(record);
+            }
+            else if (record.runtime instanceof ClaudeCodeRuntime) {
+                const completion = await record.runtime.submit(prompt);
+                if (record.run.interruptRequested || completion.status === "interrupted") {
+                    this.finishInterrupted(record);
+                }
+                else if (completion.result.failed) {
+                    this.finishFailed(record, {
+                        kind: "provider-error",
+                        message: completion.result.response,
+                        stopReason: "error",
+                    });
+                }
+                else {
+                    this.finishSucceeded(record, completion.result.response);
+                }
+            }
+            else {
+                this.applyTurnResult(record, await record.runtime.submit(prompt));
             }
-            return await record.runtime.submit(prompt);
-        })
-            .then((result) => {
-            this.applyTurnResult(record, result);
             return record;
         })
             .catch((error) => {
@@ -259,13 +284,16 @@ export class AgentSupervisor {
             });
             return;
         }
+        this.finishSucceeded(record, extractAssistantText(result.finalMessage).trim());
+    }
+    finishSucceeded(record, response) {
         record.run = {
             revision: record.run.revision,
             status: "succeeded",
             startedAt: record.run.startedAt,
             finishedAt: this.deps.clock.now(),
             interruptRequested: false,
-            response: extractAssistantText(result.finalMessage).trim(),
+            response,
         };
     }
     finishInterrupted(record) {
@@ -288,6 +316,99 @@ export class AgentSupervisor {
             failure,
         };
     }
+    async recordClaudeCodeEvent(id, event) {
+        const record = this.records.get(id);
+        if (!record)
+            return;
+        if (event.type === "usage" || event.type === "result") {
+            let reported = event.usage;
+            if (event.type === "usage") {
+                const previous = record.claudeMessageUsage.get(event.messageId);
+                // Final result totals already cover these messages, including resumed replays.
+                if (previous === null)
+                    return;
+                const current = {
+                    input: Math.max(previous?.input ?? 0, event.usage.input),
+                    output: Math.max(previous?.output ?? 0, event.usage.output),
+                    cacheRead: Math.max(previous?.cacheRead ?? 0, event.usage.cacheRead),
+                    cacheWrite: Math.max(previous?.cacheWrite ?? 0, event.usage.cacheWrite),
+                };
+                record.claudeMessageUsage.set(event.messageId, current);
+                reported = {
+                    input: record.usage.input + current.input - (previous?.input ?? 0),
+                    output: record.usage.output + current.output - (previous?.output ?? 0),
+                    cacheRead: record.usage.cacheRead + current.cacheRead - (previous?.cacheRead ?? 0),
+                    cacheWrite: record.usage.cacheWrite + current.cacheWrite - (previous?.cacheWrite ?? 0),
+                };
+                if (getUsageTotals(current).total === getUsageTotals(previous).total)
+                    return;
+                record.usage.contextWindowUsageTokens = getUsageTotals(current).total;
+            }
+            else {
+                for (const messageId of record.claudeMessageUsage.keys()) {
+                    record.claudeMessageUsage.set(messageId, null);
+                }
+                record.usage.contextWindowUsageTokens = event.usage.contextWindowUsageTokens;
+                record.usage.contextWindow = event.usage.contextWindow;
+            }
+            // SDK totals include the history restored on resume. Record only the delta,
+            // and replace (rather than sum) the current context-window measurement.
+            const usage = getUsageTotals({
+                input: Math.max(0, reported.input - record.usage.input),
+                output: Math.max(0, reported.output - record.usage.output),
+                cacheRead: Math.max(0, reported.cacheRead - record.usage.cacheRead),
+                cacheWrite: Math.max(0, reported.cacheWrite - record.usage.cacheWrite),
+            });
+            const cost = event.type === "result" ? Math.max(0, event.cost - record.costTotal) : 0;
+            // Startup failures can report zero totals even for a resumed session.
+            record.costTotal += cost;
+            record.usage = {
+                ...record.usage,
+                input: record.usage.input + usage.input,
+                output: record.usage.output + usage.output,
+                cacheRead: record.usage.cacheRead + usage.cacheRead,
+                cacheWrite: record.usage.cacheWrite + usage.cacheWrite,
+            };
+            (this.options.recordUsage ?? appendUsageLogEntry)({
+                timestamp: this.deps.clock.now(),
+                sessionId: record.id,
+                personaId: record.personaId,
+                provider: record.model.provider,
+                model: record.model.id,
+                api: "claude-agent-sdk",
+                reasoningEffort: record.model.reasoning,
+                usage,
+                cost: { total: cost },
+                agent: { type: "subagent" },
+            });
+            await this.emit({ type: "subagent_updated", state: this.toSnapshot(record) });
+        }
+        else if (event.type === "assistant") {
+            await this.emit({
+                type: "subagent_activity",
+                state: this.toSnapshot(record),
+                activity: { type: "assistant", text: event.text },
+            });
+        }
+        else if (event.type === "tool") {
+            await this.emit({
+                type: "subagent_activity",
+                state: this.toSnapshot(record),
+                activity: {
+                    type: "tool",
+                    toolName: event.name,
+                    outcome: event.failed ? "failed" : "succeeded",
+                    presentation: {
+                        action: event.failed ? "failed" : "completed",
+                        subject: event.subject,
+                        subjectWrap: "word",
+                        details: [],
+                        metadata: [],
+                    },
+                },
+            });
+        }
+    }
     async recordAgentEvent(id, event) {
         const record = this.records.get(id);
         if (!record)
@@ -302,7 +423,7 @@ export class AgentSupervisor {
                 cacheRead: record.usage.cacheRead + usage.cacheRead,
                 cacheWrite: record.usage.cacheWrite + usage.cacheWrite,
                 contextWindowUsageTokens: usage.input + usage.output + usage.cacheRead + usage.cacheWrite,
-                contextWindow: record.runtimeConfig.model.contextWindow,
+                contextWindow: record.usage.contextWindow,
             };
             (this.options.recordUsage ?? appendUsageLogEntry)({
                 timestamp: event.message.timestamp,