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

{tau_coding_agent-0.4.0/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.4.0
+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
@@ -32,10 +32,10 @@ Dynamic: license-file
 
 # Tau (τ)
 
-A Python reimplementation of [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.
+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.

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

@@ -1,9 +1,9 @@
 # Tau (τ)
 
-A Python reimplementation of [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.
+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.

{tau_coding_agent-0.4.0 → 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.4.0 → 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.4.0 → 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.4.0 → 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.4.0 → 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",

{tau_coding_agent-0.4.0 → tau_coding_agent-0.4.5}/docs/project-structure.md

@@ -234,35 +234,33 @@ Trust and permission system for tool execution.
 - `types.py` - Trust data structures
 - `utils.py` - Trust utilities
 
-### `tui/` - Terminal User Interface
-
-Complete terminal UI (22 modules, 736 LOC).
-
-Core components:
-- `tui.py` - Main TUI event loop
-- `app.py` - TUI application state
-- `terminal.py` - Terminal control and cursor management
-- `renderer.py` - Differential update renderer
-
-Input handling:
-- `input.py` - Text input editor
-- `input_handler.py` - Input event handling
-- `autocomplete.py` - Command/file autocomplete
-- `component.py` - UI component system
-
-Rendering:
-- `message_renderers.py` - Message and tool result rendering
-- `markdown.py` - Markdown to ANSI rendering
-- `overlay.py` - Overlay UI (dialogs, popups)
-
-Display:
-- `theme.py` - Theme application
-- `ansi.py` - ANSI code utilities
-- `keybindings.py` - Keybinding definitions
-- `fuzzy.py` - Fuzzy matching for search
-
-Integration:
-- `agent_hooks.py` - TUI event hooks
+### `tui/` - Terminal UI Primitives
+
+Reusable terminal parsing, differential rendering, components, themes, and
+keybindings.
+
+- `tui.py` - Main event loop, focus, overlays, and differential rendering
+- `terminal.py` - Terminal control and capability detection
+- `input.py` - Generic input events, terminal parser, and keybinding registry
+- `component.py` - Component and container primitives
+- `components/` - Editor, text input, selectors, spinner, images, and boxes
+- `autocomplete.py` - Generic autocomplete management
+- `markdown.py` - Markdown-to-ANSI rendering
+- `theme.py` - TUI theme types
+- `ui_context.py` - Extension-facing UI context
+
+### `modes/interactive/` - Interactive Application
+
+Interactive runtime orchestration and Tau-specific UI composition.
+
+- `app.py` - Application lifecycle and global shortcuts
+- `agent_hooks.py` - Agent-event to UI-state projection
+- `input_handler.py` - Runtime-aware submit, queue, media, and history orchestration
+- `commands/` - Interactive slash-command implementations
+- `components/layout.py` - Editor-zone composition
+- `components/message_list.py` - Message and tool-result rendering
+- `components/selector_controller.py` - Inline selector lifecycle and input routing
+- `components/overlays.py` - Interactive dialogs and editors
 - `ui_context.py` - UI state context
 
 ## Key Types and Classes

{tau_coding_agent-0.4.0 → tau_coding_agent-0.4.5}/docs/python-api.md

@@ -123,8 +123,8 @@ unsub()  # remove the handler
 |-------|------|
 | `message_end` | Model response fully received |
 | `tool_execution_end` | A tool call finished |
-| `agent_end` | Agent turn is complete |
-| `settled` | Agent is fully idle (follow-up queue drained) |
+| `agent_end` | The current low-level engine loop ended; post-run processing may remain |
+| `settled` | The invocation completed post-run processing with no messages currently queued |
 
 ## Custom Tools at Runtime
 
@@ -185,9 +185,17 @@ agent = runtime.agent
 
 # Check state
 agent.is_idle()
+agent.phase             # AgentPhase.IDLE, TURN, COMPACTION, or BRANCH_SUMMARY
+agent.streaming_message
+agent.pending_tool_call_ids
+agent.error_message
+agent.queued_messages
 agent.get_context_usage()   # ContextUsage(tokens, context_window, percent)
 agent.get_system_prompt()
 
+# Wait through save-point handlers and post-run compaction
+await agent.wait_for_idle()
+
 # Abort
 agent.abort()
 

{tau_coding_agent-0.4.0 → tau_coding_agent-0.4.5}/docs/sessions.md

@@ -14,6 +14,10 @@ A session is a conversation between you and the agent. Each session includes:
 
 Sessions are saved to `~/.tau/sessions/` in a per-project subdirectory so sessions from different projects never mix.
 
+Set `session_dir` in settings, or pass `--session-dir PATH`, to override this
+location. `tau --resume ID` resumes a matching session, `tau --fork ID` creates
+a new session from it, and `--name NAME` assigns a display name at startup.
+
 ## Session Files
 
 Sessions are stored per-project. The working directory is encoded into a safe subdirectory name:
@@ -32,6 +36,15 @@ The subdirectory name is derived from the absolute path of the working directory
 
 Files are in JSONL format (one JSON object per line), allowing efficient appending and compression.
 
+Opening an existing empty, invalid, or unsupported future-version session
+fails without modifying the file. Persistence errors are reported to the
+caller instead of allowing in-memory state to appear saved when the disk write
+failed.
+
+When a branch is extracted into a new session, label entries are recreated at
+the end of the extracted path. Retained entries are re-chained so removing a
+label from between conversation entries cannot leave orphaned parent IDs.
+
 ## Resume Sessions
 
 ### Continue Last Session
@@ -112,6 +125,10 @@ Useful for one-off queries where you don't need the conversation history.
 
 Every session is a **tree**, not a flat list. When you branch with `/fork` or navigate to a different point in history, tau records a `leaf` entry that points to the new active node. The full conversation history — including all branches — lives in a single JSONL file.
 
+Parent traversal rejects cycles in malformed session data. Tree rendering
+treats missing-parent entries as separate roots so recoverable orphaned history
+remains visible.
+
 ```text
 root
  └── msg A (user)
@@ -148,14 +165,21 @@ Both sessions start in an identical state. Changes in one do not affect the othe
 
 Use `/tree` to open the interactive branch navigator. It shows every message node in the session tree, indented by depth, with the current leaf marked `(current)`. Press Enter on any node to navigate to that branch point.
 
-When you navigate to a different branch, tau generates a **branch summary** of the path you're leaving, so context from the abandoned branch isn't lost. The summary is injected into the new branch's context as a `[Branch Summary]` block.
+When you navigate to a different branch, Tau can generate a **branch summary**
+of the path you're leaving, so context from the abandoned branch isn't lost.
+The TUI asks whether to summarize unless prompting is disabled. When generated,
+the summary is attached to the destination branch and injected into its context
+as a `[Branch Summary]` block.
 
 #### Branch summary behaviour
 
-- Generated automatically on navigation — no manual action needed.
+- Offered during TUI navigation; API callers opt in with `summarize=True`.
 - Captures: goal, progress, key decisions, next steps, and files read/modified.
-- Stored as a `branch_summary` entry in the session file and included in context whenever you return to that branch.
-- Extensions can intercept and customise summaries via the `session_before_tree` event (see [Extensions](extensions.md#event-reference)).
+- Stored as a `branch_summary` entry under the destination node and included in that branch's context.
+- Uses the active model's input limit and a bounded prompt. If summarization fails, navigation still completes without a summary and Tau reports the failure.
+- Extensions can return a complete summary and metadata from
+  `session_before_tree`, bypassing Tau's default summary model call. See
+  [Extensions](extensions.md#event-reference).
 
 ### Resuming a Past Session
 
@@ -252,16 +276,19 @@ Long sessions eventually fill the model's context window. Tau handles this autom
 
 ### When Compaction Runs
 
-Token usage is estimated from the **last successful response's reported usage** plus a chars/4 estimate of anything after it, so the trigger reflects real provider accounting rather than a pure guess. The threshold is `context_tokens > context_window - reserve_tokens`. Tau checks this at three points so context is trimmed before it can overflow:
+Token usage is estimated from the **last successful response's reported usage** plus a chars/4 estimate of anything after it, so the trigger reflects real provider accounting rather than a pure guess. Provider cache counters are normalized so cached input is not counted twice. Before the first response, and after switching models, the estimate also includes the system prompt and tool schemas.
+
+The threshold is `context_tokens >= context_window - reserve_tokens`. Tau checks this at three points so context is trimmed before it can overflow:
 
 1. **Pre-flight** — before sending a new turn. Catches resumed or already-oversized sessions that would otherwise fail on the very first request.
-2. **Post-turn** — after each agent turn completes, the normal proactive path.
+2. **Post-task** — after the agent finishes the current prompt and becomes idle.
 3. **Overflow recovery (reactive backstop)** — if a request still fails with a provider *context-overflow* error, Tau catches it, drops the failed response, compacts, and **retries the turn once** automatically. This is bounded to a single attempt per turn — if it overflows again, Tau surfaces a message asking you to reduce context or switch to a larger-context model rather than looping.
 
 Two guards keep this stable:
 
 - **Stale-anchor guard** — immediately after a compaction, the kept messages still carry their pre-compaction (large) usage numbers. Tau skips re-triggering when the usage anchor predates the latest compaction, so it won't compact on every subsequent turn.
 - **Circuit breaker** — if automatic compaction fails repeatedly (3×), Tau stops auto-compacting for the session and surfaces a notice instead of failing silently. You can still run `/compact` manually.
+- **Model-switch guard** — usage reported by the previous model is discarded after a model change. Tau falls back to a full heuristic estimate against the new model's context window instead of skipping the check.
 
 ### Manual Compaction
 
@@ -283,6 +310,13 @@ Compaction is controlled by three settings under the `compaction` key in `settin
 | `reserve_tokens` | `16384` | Tokens to keep free at the top of the context window; compaction triggers when headroom falls below this |
 | `keep_recent_tokens` | `20000` | Approximate token budget for the recent messages that are kept verbatim after compaction |
 
+At runtime, Tau clamps `reserve_tokens` and `keep_recent_tokens` to the active
+model's input limit. It always leaves room for the generated summary, preventing
+small-context models from retaining more history than they can accept.
+
+Disabling automatic compaction also disables overflow-triggered compaction and
+retry. Provider context-overflow errors are returned directly in that mode.
+
 Example — tighten the trigger and keep more recent history:
 
 ```json

{tau_coding_agent-0.4.0 → tau_coding_agent-0.4.5}/docs/settings.md

@@ -84,6 +84,7 @@ All field names use `snake_case`.
 | `thinking_level` | string | Extended thinking budget level (see below) |
 | `transport` | string | Transport layer override (`"streaming"` or `"polling"`) |
 | `enabled_models` | list[string] | Restrict the model picker to these model IDs |
+| `session_dir` | string | Override the directory used to store and discover sessions |
 
 ```json
 {
@@ -120,6 +121,7 @@ Toggle during a session with `/effort` or the effort picker.
 | `show_tool_calls` | boolean | `true` | Show tool call / result blocks in the message list |
 | `picker_max_visible` | integer | `8` | Max visible rows in the model / theme picker |
 | `autocomplete_max_visible` | integer | `5` | Max visible rows in the editor autocomplete dropdown |
+| `tool_result_preview_lines` | integer | `5` | Lines shown before thinking or default-shell tool results collapse; values below 1 are clamped |
 | `show_hardware_cursor` | boolean | `false` | Keep the terminal cursor visible while it is repositioned (aids IME input) |
 | `editor_padding_x` | integer | `0` | Horizontal padding (spaces) added inside the input editor |
 | `double_escape_action` | string | `"fork"` | What happens when Escape is pressed twice on an empty editor: `"fork"` clones the current branch, `"tree"` opens the branch navigator, `"none"` does nothing |
@@ -187,9 +189,14 @@ When your conversation grows long, tau automatically summarizes older messages t
 - **`reserve_tokens`**: How many tokens to keep available for the LLM's response (default 16,384 ≈ 4K-5K words)
 - **`keep_recent_tokens`**: How many recent message tokens to preserve word-for-word before summarization kicks in (default 20,000 ≈ 5K-6K words)
 
+The active values are resolved live, so changes made through `/settings` apply
+without restarting Tau. For models with smaller input limits, Tau clamps both
+budgets and reserves additional space for the generated summary. Automatic and
+overflow-triggered compaction are both disabled when `enabled` is `false`.
+
 #### Mid-turn (threshold) compaction
 
-In addition to compaction triggered at the start of a turn, tau can compact **mid-turn** when the context hits the configured limit while the agent is already running. When this happens the engine stops cleanly so you can review the compacted context and continue — no partial output is lost. Tool output lines are truncated before sending to the LLM to help prevent hitting the threshold in the first place.
+In addition to compaction triggered at the start of a turn, tau can compact **mid-turn** when context usage reaches `input_limit - reserve_tokens` while the agent is already running. When this happens the engine stops cleanly so you can review the compacted context and continue — no partial output is lost. Tool output lines are truncated before sending to the LLM to help prevent hitting the threshold in the first place.
 
 Example configurations:
 
@@ -232,8 +239,8 @@ summary of the branch you're leaving.  These settings control that behaviour.
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `branch_summary.enabled` | boolean | `true` | Enable branch summarisation entirely. When `false`, the summarisation selector is never shown when switching branches in `/tree` |
-| `branch_summary.skip_prompt` | boolean | `false` | Skip the "Summarize branch?" picker and always navigate without a summary |
-| `branch_summary.reserve_tokens` | integer | `16384` | Token budget reserved when generating the branch summary |
+| `branch_summary.skip_prompt` | boolean | `false` | Skip the "Summarize branch?" picker and navigate without a summary |
+| `branch_summary.reserve_tokens` | integer | `16384` | Output/headroom budget reserved when generating the branch summary; clamped to the active model's input limit |
 
 Disable branch summarization entirely:
 ```json