tau-coding-agent 0.3.9__tar.gz → 0.4.5__tar.gz

{tau_coding_agent-0.3.9/tau_coding_agent.egg-info → tau_coding_agent-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tau-coding-agent
-Version: 0.3.9
+Version: 0.4.5
 Summary: A self-extensible agent CLI with terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools and commands
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -35,7 +35,7 @@ Dynamic: license-file
 Inspired by [Pi](https://pi.dev), **Tau** brings the same agent framework capabilities to Python developers. A self-extensible agent CLI with a terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools, commands, and customization.
 
 <p align="center">
-  <img src="assets/tui.png" alt="Tau TUI" width="700">
+  <img src="assets/tui.jpeg" alt="Tau TUI" width="700">
 </p>
 
 Start a conversation with the agent in the terminal.
@@ -47,7 +47,7 @@ Start a conversation with the agent in the terminal.
 ### Installation
 
 ```bash
-pip install tau-coding-agent
+uv pip install tau-coding-agent
 ```
 
 Or install from source:

{tau_coding_agent-0.3.9 → tau_coding_agent-0.4.5}/README.md

@@ -3,7 +3,7 @@
 Inspired by [Pi](https://pi.dev), **Tau** brings the same agent framework capabilities to Python developers. A self-extensible agent CLI with a terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools, commands, and customization.
 
 <p align="center">
-  <img src="assets/tui.png" alt="Tau TUI" width="700">
+  <img src="assets/tui.jpeg" alt="Tau TUI" width="700">
 </p>
 
 Start a conversation with the agent in the terminal.
@@ -15,7 +15,7 @@ Start a conversation with the agent in the terminal.
 ### Installation
 
 ```bash
-pip install tau-coding-agent
+uv pip install tau-coding-agent
 ```
 
 Or install from source:

{tau_coding_agent-0.3.9 → tau_coding_agent-0.4.5}/docs/architecture.md

@@ -102,18 +102,20 @@ User input flows through these stages:
 
 ## Agent Execution State Machine
 
-The agent has three main states:
+The agent has four observable phases:
 
 ```
 IDLE ──user input──> TURN ──no more tool calls──> IDLE
-       ↑                ↓
-       └─ tool results ─┘
+  ├── manual/auto compact ──> COMPACTION ──> previous phase
+  └── tree navigation ──────> BRANCH_SUMMARY ──> IDLE
 ```
 
 | State | Meaning |
 |-------|---------|
 | `IDLE` | No active inference; waiting for user input |
 | `TURN` | Processing a turn: calling inference, executing tools |
+| `COMPACTION` | Generating or applying a context compaction summary |
+| `BRANCH_SUMMARY` | Generating or applying a branch-navigation summary |
 
 The state is exposed via `AgentPhase` enum in `agent/types.py` and accessible to extensions via hooks.
 
@@ -126,14 +128,19 @@ Each agent turn follows this sequence:
 2. Add message to session
 3. Call inference (LLM API)
 4. Collect tool calls from response
-5. Execute tools (in parallel if possible)
+5. Execute tools concurrently only when every call in the batch is marked parallel
 6. Add tool results to context
 7. Call inference again (only if tools were called)
 8. Render all messages and results (TUI)
 9. Save session to disk
-10. Fire completion hooks
+10. Run post-turn compaction and drain messages queued by lifecycle handlers
+11. Fire the settled hook
 ```
 
+TUI overlays participate in focus lifecycle. Hiding or closing a capturing
+overlay restores the next visible overlay or its previous focus target.
+Components exposing `dispose()` are disposed when their overlay closes.
+
 ## Message Types and Context
 
 Messages in sessions are typed:

{tau_coding_agent-0.3.9 → tau_coding_agent-0.4.5}/docs/cli-reference.md

@@ -6,17 +6,21 @@
 tau [OPTIONS] [MESSAGE]
 ```
 
-`MESSAGE` is an optional positional argument. When provided with `--print` or `--mode print`, it is the prompt to run.
+Use `--prompt TEXT` for a non-interactive prompt. Piped stdin can supply or
+augment it.
 
 ## Options
 
 | Option | Short | Description |
 |--------|-------|-------------|
-| `--provider` | `-p` | Provider to use, e.g. `anthropic`, `openai`, `groq` |
-| `--model` | `-m` | Model ID, or `provider/model` shorthand (e.g. `groq/llama-3.3-70b-versatile`) |
+| `--prompt` | `-p` | Run a non-interactive prompt |
+| `--provider` | | Provider to use, e.g. `anthropic`, `openai`, `groq` |
+| `--model` | | Model ID, or `provider/model` shorthand (e.g. `groq/llama-3.3-70b-versatile`) |
 | `--theme` | `-t` | UI theme: `default`, `dracula`, `nord`, `gruvbox`, `catppuccin`, `ayu-dark`, `everforest`, `horizon`, `kanagawa`, `material-ocean`, `monokai`, `night-owl`, `one-dark`, `rose-pine`, `solarized-dark`, `tokyo-night`, or a custom name |
-| `--resume` | `-r` | Resume the most recent session |
-| `--session` | `-s` | Resume a specific session by ID or file path |
+| `--resume [ID]` | `-r` | Resume the most recent or a specified session |
+| `--fork ID` | | Fork a specified session at startup |
+| `--session-dir PATH` | | Override session storage |
+| `--name NAME` | | Set the session display name at startup |
 | `--ephemeral` | `-e` | Don't save this session to disk |
 | `--approve` | `-a` | Trust project-local files (extensions, settings, context files) for this run |
 | `--no-approve` | `-na` | Don't trust project-local files for this run |
@@ -42,10 +46,14 @@ tau --model claude-sonnet-4-6
 Run a single prompt, print the response, and exit:
 
 ```bash
-tau --print "Summarize this repo"
-tau -p anthropic --print "What is this file?" 
+tau --prompt "Summarize this repo"
+cat README.md | tau --print --prompt "Summarize this text"
+tau --prompt "Compare these files" @src/old.py @src/new.py
 ```
 
+Piped text, attached file contents, and the explicit prompt are combined in
+that order.
+
 ### JSON mode
 
 Emit a JSON event stream on stdout:

{tau_coding_agent-0.3.9 → tau_coding_agent-0.4.5}/docs/extension-settings.md

@@ -21,7 +21,7 @@ def register(tau):
     timeout = config.get("timeout_ms", 5000)
 ```
 
-In `~/.tau/settings.json` or `.tau/settings.json`:
+The values are stored in `~/.tau/settings.json` (global) or `.tau/settings.json` (project-local):
 
 ```json
 {
@@ -39,6 +39,71 @@ In `~/.tau/settings.json` or `.tau/settings.json`:
 }
 ```
 
+### Where settings live
+
+Settings for an extension are stored in the `settings` object of its entry inside `extensions.list`. Tau matches entries by path — the path in the list must match the path or directory the extension was loaded from.
+
+**Project-local** — `.tau/settings.json` (only applies in this directory):
+
+```json
+{
+  "extensions": {
+    "list": [
+      {
+        "path": ".tau/extensions/lsp",
+        "settings": {
+          "lsp": true,
+          "eager": [],
+          "servers": {
+            "pyright": { "enabled": true },
+            "ruff": { "enabled": true },
+            "typescript-language-server": { "enabled": false }
+          }
+        }
+      },
+      {
+        "path": ".tau/extensions/voice",
+        "settings": {
+          "enabled": true,
+          "stt_model": "whisper-1",
+          "stt_provider": "openai",
+          "hold_seconds": 2,
+          "sample_rate": 16000
+        }
+      }
+    ]
+  }
+}
+```
+
+**Global** — `~/.tau/settings.json` (applies to every project):
+
+```json
+{
+  "extensions": {
+    "list": [
+      {
+        "path": "~/.tau/extensions/web-search",
+        "settings": {
+          "enabled": true,
+          "engine": "ddgs",
+          "results": 10
+        }
+      },
+      {
+        "path": "~/.tau/extensions/my_ext.py",
+        "settings": {
+          "api_key": "sk-...",
+          "timeout_ms": 5000
+        }
+      }
+    ]
+  }
+}
+```
+
+Both files can coexist — project settings are merged on top of global settings at startup. Extensions loaded from `.tau/extensions/` read from the project file; extensions loaded from `~/.tau/extensions/` read from the global file.
+
 ## Nested Structures
 
 `ExtensionSettings` handles nested configuration just as naturally:
@@ -237,7 +302,147 @@ def register(tau):
 
 Extensions can register settings items that appear as a named sub-panel at the bottom of the interactive `/settings` panel. Users can then edit extension settings from the TUI without touching JSON.
 
-### Basic example
+There are two ways to do this: declare the schema in `manifest.json` (recommended for directory extensions) or register it imperatively with `tau.register_settings()` (useful for single-file extensions).
+
+---
+
+### Option A — manifest.json schema (recommended)
+
+Add a `"settings"` block under the `"tau"` key in `manifest.json`. Tau reads it at load time, builds the `/settings` sub-panel automatically, reads current values from the extension's config, and persists changes back to `settings.json` (reloading just that extension so the change applies live — no restart needed).
+
+```json
+{
+  "tau": {
+    "extensions": ["__init__.py"],
+    "dependencies": ["requests"],
+    "settings": {
+      "title": "Web search",
+      "fields": [
+        {
+          "key": "enabled",
+          "label": "Enabled",
+          "type": "bool",
+          "default": true,
+          "description": "Enable or disable the web search extension."
+        },
+        {
+          "key": "engine",
+          "label": "Search engine",
+          "type": "enum",
+          "values": ["ddgs", "exa", "tavily"],
+          "default": "ddgs",
+          "description": "Which search backend to use."
+        },
+        {
+          "key": "results",
+          "label": "Max results",
+          "type": "int",
+          "default": 10,
+          "min": 1,
+          "max": 50,
+          "description": "Number of results returned per query."
+        },
+        {
+          "key": "api_key",
+          "label": "API key",
+          "type": "secret",
+          "default": "",
+          "description": "Provider API key (stored in settings.json)."
+        },
+        {
+          "key": "exa",
+          "label": "Exa settings",
+          "type": "group",
+          "fields": [
+            {
+              "key": "base_url",
+              "label": "Base URL",
+              "type": "string",
+              "default": "https://api.exa.ai"
+            },
+            {
+              "key": "highlights",
+              "label": "Highlights",
+              "type": "bool",
+              "default": true
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+The corresponding `.tau/settings.json` entry that stores the current values:
+
+```json
+{
+  "extensions": {
+    "list": [
+      {
+        "path": ".tau/extensions/web-search",
+        "settings": {
+          "enabled": true,
+          "engine": "exa",
+          "results": 20,
+          "api_key": "sk-exa-...",
+          "exa": {
+            "base_url": "https://api.exa.ai",
+            "highlights": false
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+#### Field types
+
+| Type | UI control | Notes |
+|------|-----------|-------|
+| `bool` | Toggle `off` / `on` | Stored as a JSON boolean in settings |
+| `int` | Text input (numeric) | Optional `min` and `max` clamps |
+| `string` | Text input | Optional `pattern` (regex the value must match) |
+| `secret` | Text input | Same as `string`; signals sensitive content |
+| `text` | Text input | Same as `string`; intended for longer values |
+| `enum` or `select` | Cycle through values on Enter | Requires a non-empty `"values"` list |
+| `group` | Opens a nested sub-panel | Contains a `"fields"` list; keys are prefixed |
+
+#### Field properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `key` | Yes | Setting key. Supports dot-notation: `"exa.api_key"` is equivalent to nesting under a `"exa"` group |
+| `label` | Yes | Display text shown in the `/settings` panel |
+| `type` | No (defaults to `string`) | One of the types listed above |
+| `default` | No | Fallback value when the key is absent from settings |
+| `description` | No | Dimmed help text shown below the label |
+| `values` | `enum`/`select` only | List of allowed values to cycle through |
+| `min` / `max` | `int` only | Clamp the entered value to this range |
+| `pattern` | `string`/`secret`/`text` | Regex the value must fully match; invalid input is silently ignored |
+| `fields` | `group` only | Nested list of field definitions |
+
+#### Summary badge
+
+The first top-level `bool` field is automatically used as an on/off summary badge on the extension's parent row in the main `/settings` list. This lets users see at a glance whether an extension is enabled without opening its sub-panel.
+
+#### Dot-notation keys
+
+`"key": "exa.api_key"` at the top level is exactly equivalent to a field with `"key": "api_key"` nested inside a group with `"key": "exa"`. Both read and write the same path in settings:
+
+```json
+{ "exa": { "api_key": "sk-..." } }
+```
+
+Use the explicit `group` type when you want the sub-panel to have a header label. Use dot-notation directly when you just want nested storage without the extra level of UI.
+
+---
+
+### Option B — `tau.register_settings()` (imperative)
+
+#### Basic example
 
 ```python
 from tau.tui.components.settings_modal import SettingItem
@@ -254,7 +459,7 @@ def register(tau):
     ], title="My Extension", on_change=on_change)
 ```
 
-### `tau.register_settings(items, title, on_change)`
+#### `tau.register_settings(items, title, on_change)`
 
 Registers a sub-panel in `/settings` containing the provided items.
 
@@ -264,7 +469,7 @@ Registers a sub-panel in `/settings` containing the provided items.
 | `title` | `str` | The sub-panel title shown in the list |
 | `on_change` | `callable(key, value)` | Called when the user changes a value |
 
-### `SettingItem` fields
+#### `SettingItem` fields
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -278,7 +483,7 @@ Registers a sub-panel in `/settings` containing the provided items.
 | `submenu_settings` | `list[SettingItem] \| None` | Open a full nested sub-panel with these items (arbitrary depth) |
 | `submenu_on_change` | `callable \| None` | Overrides the parent `on_change` for a nested sub-panel |
 
-### Nested sub-panels
+#### Nested sub-panels
 
 A `SettingItem` with `submenu_settings` opens another level of the settings panel. Nesting can be arbitrarily deep. Use `submenu_on_change` to override the change callback for that level:
 
@@ -298,7 +503,7 @@ tau.register_settings([
 ], title="My Extension", on_change=on_change)
 ```
 
-### `tau.settings.set_extension_config_key(ext_path, key, value)`
+#### `tau.settings.set_extension_config_key(ext_path, key, value)`
 
 Persists a value back to `extensions.list[].settings` in `settings.json`.
 

{tau_coding_agent-0.3.9 → tau_coding_agent-0.4.5}/docs/extensions.md

@@ -3,6 +3,12 @@
 Extensions are plain Python files that hook into tau's lifecycle. Each one exports
 a single `register(tau)` function — everything is wired up there.
 
+Extension tools and commands may shadow built-ins while loaded. Tau retains the
+shadowed source layer, so disabling or reloading the extension restores the
+previous implementation. Reload also replaces extension message renderers,
+autocomplete providers, shortcuts, and published services; do not retain
+service objects across reload.
+
 ## File locations
 
 tau loads extensions from three sources, in this order:
@@ -36,6 +42,41 @@ dependencies with incompatible versions. The install only runs once — a hash o
 the dependency list is cached, so unchanged manifests are a no-op on subsequent
 launches.
 
+## Installable resource packages
+
+`tau install` accepts PyPI names, pip-compatible Git URLs, local distributions,
+and direct wheel or source-archive URLs:
+
+```bash
+tau install pypi:tau-tools==1.2.3
+tau install git+ssh://git@github.com/example/tau-tools.git@v1
+tau install ./dist/tau_tools-1.2.3-py3-none-any.whl
+tau install https://packages.example.com/tau_tools-1.2.3-py3-none-any.whl
+tau install tau-tools==1.2.3 --index-url https://packages.example.com/simple
+```
+
+Repeat `--extra-index-url URL` to resolve dependencies from additional indexes.
+Index configuration is retained for future updates.
+
+Packages can bundle extensions, skills, prompts, and themes:
+
+```json
+{
+  "tau": {
+    "extensions": ["extensions/main.py"],
+    "skills": ["skills"],
+    "prompts": ["prompts"],
+    "themes": ["themes"]
+  }
+}
+```
+
+Conventional resource directories are discovered when a manifest field is
+omitted. Package entries in `settings.json` support an `enabled` switch and
+optional `extensions`, `skills`, `prompts`, and `themes` path filters. An empty
+filter disables that resource type. Use `tau update --all` to update Tau and
+all installed packages.
+
 ## Entry point
 
 Every extension must export a `register(tau)` function:
@@ -212,9 +253,17 @@ def register(tau):
 
 #### Agent state
 
+| Property | Type | Description |
+|----------|------|-------------|
+| `ctx.phase` | `AgentPhase` | Current lifecycle phase: `idle`, `turn`, `compaction`, or `branch_summary` |
+| `ctx.streaming_message` | `AssistantMessage \| None` | Current partial assistant response |
+| `ctx.pending_tool_call_ids` | `frozenset[str]` | Snapshot of tool calls that have started but not finished |
+| `ctx.error_message` | `str \| None` | Most recent engine error |
+| `ctx.queued_messages` | `dict[str, list[LLMMessage]]` | Snapshots of the steering and follow-up queues |
+
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `ctx.is_idle()` | `bool` | `True` when the agent is not currently streaming a response |
+| `ctx.is_idle()` | `bool` | `True` when `ctx.phase` is `AgentPhase.IDLE` |
 | `ctx.abort()` | — | Cancel the current agent turn; no-op if already idle |
 | `ctx.shutdown()` | — | Exit tau gracefully |
 | `ctx.get_context_usage()` | `dict \| None` | Token usage info (see below) |
@@ -224,6 +273,13 @@ def register(tau):
 | `ctx.signal` | `asyncio.Event \| None` | The current abort signal while the agent is streaming; the event is set when the turn is aborted. `None` when idle |
 | `ctx.get_system_prompt_options()` | `dict` | Metadata about how the active system prompt was assembled — keys: `skills`, `prompts`, `tools`, `system_prompt_length` |
 
+Extensions can inject a user message with
+`await ctx.send_user_message(content, deliver_as="steer", trigger_turn=False)`.
+Set `trigger_turn=True` to start a new turn immediately when the agent is idle;
+while it is busy, the message is queued using the selected delivery mode. In
+interactive mode, an immediately triggered message is rendered as a normal user
+message before the assistant response.
+
 `get_context_usage()` returns a dict with three keys, or `None` if token data is not yet available (e.g. immediately after compaction, before the next LLM response):
 
 ```python
@@ -251,7 +307,7 @@ These methods are `async` and are available in both event handlers and command h
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `await ctx.wait_for_idle()` | — | Suspend until the agent finishes its current turn |
+| `await ctx.wait_for_idle()` | — | Suspend until the active invocation and its post-run save/compaction processing finish |
 | `await ctx.new_session()` | `{"cancelled": bool}` | Start a fresh session |
 | `await ctx.fork(entry_id)` | `{"cancelled": bool}` | Fork from a specific session entry |
 | `await ctx.navigate_tree(target_id, summarize=False, custom_instructions=None)` | `{"cancelled": bool}` | Jump to another branch in the session tree |
@@ -297,12 +353,30 @@ async def cmd(ctx, args):
     ctx.compact(custom_instructions="Keep only the final conclusions.")
 ```
 
-`navigate_tree` optionally generates a branch summary before switching:
+`navigate_tree` optionally generates a branch summary and attaches it to the
+destination branch. If summary generation fails, navigation still completes
+without a summary:
 
 ```python
 result = await ctx.navigate_tree(target_id, summarize=True)
 ```
 
+Extensions can replace the default branch-summary model call:
+
+```python
+from tau.hooks import SessionBeforeTreeResult
+
+def register(tau):
+    @tau.on("session_before_tree")
+    async def summarize(event, ctx):
+        entries = event.preparation.entries_to_summarize
+        summary = await my_summarizer(entries)
+        return SessionBeforeTreeResult(
+            summary=summary,
+            summary_details={"source": "my-extension"},
+        )
+```
+
 #### `branch_entries` vs `session_entries`
 
 The session file stores entries from every branch ever taken — forks, navigations, abandoned paths. `session_entries` returns all of them. `branch_entries` returns only the linear path from the root to the current leaf — the entries actually in scope for the current conversation.
@@ -359,7 +433,11 @@ def register(tau):
 | `session_shutdown` | `reason`, `target_session_file` | — | Session about to close — last chance for cleanup |
 | `session_before_switch` | `reason`, `target_session_file` | `SessionBeforeSwitchResult` | About to replace the active session — return `cancel=True` to block |
 | `session_before_fork` | `entry_id`, `position` | `SessionBeforeForkResult` | About to create a branch — return `cancel=True` to block |
-| `session_before_tree` | `preparation` | `SessionBeforeTreeResult` | About to rewrite the session tree (branch navigation). Mutate `preparation` or return `cancel=True` |
+| `session_before_tree` | `preparation` | `SessionBeforeTreeResult` | About to rewrite the tree. Return `summary=` and optional `summary_details=` to replace default summarization, or `cancel=True` to block |
+| `branch_summary_start` | `old_leaf_id`, `target_id`, `from_extension` | — | Branch summarization begins |
+| `branch_summary_end` | `old_leaf_id`, `target_id`, `summary_entry_id`, `summary_length`, `from_extension` | — | Summary attached to the destination |
+| `branch_summary_failure` | `old_leaf_id`, `target_id`, `error` | — | Summary failed; navigation continues without it |
+| `branch_summary_cancelled` | `old_leaf_id`, `target_id`, `reason` | — | Summary or navigation was cancelled |
 | `session_tree` | `new_leaf_id`, `old_leaf_id`, `from_extension` | — | Session tree has been rewritten with the new active leaf |
 
 **Agent & turn lifecycle**
@@ -372,7 +450,7 @@ def register(tau):
 | `agent_error` | `error` | — | Engine terminated with an unrecoverable error |
 | `turn_start` | `turn_index`, `timestamp` | — | New LLM inference turn begins |
 | `turn_end` | `turn_index`, `message`, `tool_results` | — | Turn completes with assistant message and tool results |
-| `settled` | — | — | Agent finishes a `prompt()` call with no more queued turns — the agent is fully idle |
+| `settled` | — | — | The invocation completed queued turns and post-run compaction with no messages currently queued; this is an observation, not a lock against concurrent submissions |
 
 **Input**
 
@@ -425,9 +503,11 @@ def register(tau):
 
 | Event | Payload fields | Result type | Description |
 |-------|---------------|-------------|-------------|
-| `before_compaction` | `preparation`, `entries`, `manual` | `BeforeCompactionResult` | Before the LLM summarisation call — see [Custom Compaction](#custom-compaction) |
-| `compaction_start` | `manual` | — | Compaction begins (after `before_compaction` passes) |
-| `compaction_end` | `manual`, `tokens_before`, `summary_length`, `from_extension` | — | Compaction finished |
+| `before_compaction` | `preparation`, `entries`, `manual`, `reason`, `will_retry` | `BeforeCompactionResult` | Before summarization; may cancel or provide a complete compaction |
+| `compaction_start` | `manual`, `reason`, `will_retry` | — | Compaction begins after interception |
+| `compaction_end` | `manual`, `reason`, `will_retry`, `tokens_before`, `summary_length`, `from_extension` | — | Compaction succeeds |
+| `compaction_failure` | `manual`, `reason`, `will_retry`, `error` | — | Compaction fails |
+| `compaction_cancelled` | `manual`, `reason`, `will_retry` | — | An extension cancels compaction |
 
 **Model & settings**
 

{tau_coding_agent-0.3.9 → tau_coding_agent-0.4.5}/docs/keybindings.md

@@ -13,7 +13,7 @@
 | Ctrl+K | Kill to end of line |
 | Ctrl+W | Delete previous word |
 | Ctrl+A / Home | Move to line start |
-| Ctrl+E / End | Move to line end |
+| Ctrl+E / End | Move to line end (Ctrl+E falls through to the app when input is empty) |
 | Delete / Ctrl+D | Delete character at cursor |
 
 ### Message Queue
@@ -30,7 +30,8 @@
 | Escape | Abort current turn; restore queued messages |
 | Ctrl+C | Abort turn; double-press to quit |
 | Ctrl+D | Quit (on empty input) |
-| Ctrl+O | Toggle expand/collapse for template blocks |
+| Ctrl+O | Toggle expand/collapse for thinking and tool-result blocks |
+| Ctrl+E | Toggle template and skill blocks when the editor is empty |
 
 ### Pickers (model, theme, command palette)
 
@@ -52,12 +53,14 @@
 Pass a `KeyMap` to `App.create()` at startup:
 
 ```python
-from tau.tui.keybindings import KeyMap
+from tau.tui import KeyMap
 
 overrides: KeyMap = {
     "tui.app.quit": ["ctrl+q"],
     "tui.input.submit": ["enter"],
     "app.message.followup": ["alt+enter"],
+    "app.details.toggle": ["ctrl+o"],
+    "app.invocations.toggle": ["ctrl+e"],
 }
 
 app = await App.create(runtime, keybindings=overrides)
@@ -75,6 +78,8 @@ A `KeyMap` is `dict[str, list[str]]` — action name → list of key combos that
 | `tui.input.word_back` | `ctrl+w` | Delete previous word |
 | `app.message.followup` | `alt+enter` | Queue as follow-up message |
 | `app.message.dequeue` | `alt+up` | Restore queued messages into editor |
+| `app.details.toggle` | `ctrl+o` | Toggle thinking and tool-result previews |
+| `app.invocations.toggle` | `ctrl+e` | Toggle template and skill blocks |
 | `tui.app.quit` | `ctrl+c`, `ctrl+d` | Quit tau |
 | `tui.app.abort` | `ctrl+c` | Abort the current turn |
 | `tui.select.up` | `up`, `ctrl+p` | Move selection up |

{tau_coding_agent-0.3.9 → tau_coding_agent-0.4.5}/docs/messages.md

@@ -28,6 +28,12 @@ Referenced files are automatically processed based on type:
 
 A response from the LLM. Can include text and tool calls.
 
+Assistant messages also store provider usage metadata: input, output,
+cache-read, and cache-write token counts. The
+`input_tokens_include_cache_read` flag records whether cached tokens are
+already included in the provider's input count, preventing context usage from
+counting the same tokens twice.
+
 ```python
 {
   "type": "assistant",