@astralyn/pi 0.84.4 → 0.84.5

package/docs/bundled/extensions/background.md

@@ -0,0 +1,64 @@
+# background — background bash tasks
+
+Adds `bg_bash`, `bg_logs`, and `bg_kill` tools plus the `/bg` command. Long-running commands (dev servers, watch builds, slow tests) run in the background while the agent keeps working; when a task ends, its status, exit code, and a tail of its output arrive automatically as a notification.
+
+## Tools
+
+`bg_bash` starts a command and returns immediately with a task id and output file path:
+
+```json
+{ "command": "npm run build", "timeout": 300 }
+```
+
+The optional `timeout` is in seconds; on expiry the task is killed and reported as `timeout`. The tool result only reports the start — the completion notification is the single source of truth for the outcome, so there is never a need to poll with sleep loops or repeated `bg_logs` calls.
+
+`bg_logs` reads a bounded slice of a task's output file while it runs or after it ends:
+
+```json
+{ "taskId": "bg-3f2a91", "mode": "tail", "bytes": 8192 }
+```
+
+`mode` defaults to `tail`; `bytes` defaults to 8KB and clamps between 256 bytes and 50KB. Truncated reads state the omission up front and always include the full output path.
+
+`bg_kill` stops a single running task by killing its whole process tree:
+
+```json
+{ "taskId": "bg-3f2a91" }
+```
+
+Killing does not bypass the normal pipeline: the task still finalizes as `killed` and its completion notification still arrives.
+
+Task ids accept a unique prefix (with or without the `bg-` part); an ambiguous prefix is an error listing the candidates.
+
+## Completion delivery
+
+When a task ends, the extension sends a `background-task` notification: a small XML message carrying the task id, terminal status, exit code, runtime, output file path, and the sanitized last ~4KB of output. While the agent is streaming, the notification queues behind the current run and is delivered when the run settles; when the agent is idle, it wakes a new turn so the result is acted on immediately.
+
+The transcript renders this notification as a one-line summary (`✓ bg-3f2a91 npm run build — completed, exit 0 in 34s`) with the output path below; expanding it shows the embedded output tail.
+
+## /bg
+
+`/bg` opens an inline task menu in the editor slot (like `/model`); the chat transcript stays visible above it. The list shows each task's status glyph, id, duration, and command; `Enter` opens the selected task's live output view, which replaces the menu.
+
+| Key | In the task list | In the output view |
+|---|---|---|
+| `↑` / `↓` | Select task | — |
+| `Enter` | Open the selected task's output | — |
+| `k` | Kill the selected running task | Kill the viewed task |
+| `PgUp` / `PgDn` | — | Scroll the output; `PgUp` freezes it, scrolling back to the bottom resumes following |
+| `Esc` | Close the menu | Back to the task list |
+
+The output view polls the output file once per second and only ever reads the last 128KB. Outside an interactive TUI, `/bg` prints a bounded task summary instead.
+
+## Statusline
+
+Running and finished counts appear in the footer as `bg 2 running · 1 done`; the segment disappears when no tasks exist.
+
+## Limits and lifecycle
+
+- Background tasks inherit the session's `PI_*` environment variables (`PI_SESSION_ID`, `PI_MODEL`, …) just like the built-in bash tool, snapshotted when the task starts.
+- Output streams directly to a system-temp file (`pi-bg-<id>.log`), never into the project or into memory. Memory holds only a byte counter.
+- Output is capped at 20MB. Hitting the cap kills the task and marks it `failed` rather than silently truncating.
+- At most 8 tasks may run concurrently; `bg_bash` reports the running tasks when the limit is reached.
+- Aborting the current turn (Esc) does not kill background tasks — that is what `bg_kill` and `/bg` are for.
+- Session shutdown, `/reload`, new sessions, and session switches kill all running tasks; those kills are silent (no notification flood). There is no restart reattachment: finished-task records live only for the current session.

package/docs/bundled/extensions/subagent.md

@@ -1,111 +1,123 @@
 # subagent — isolated foreground delegation
 
-Adds the `subagent` tool and `/agents` profile settings command. It delegates a bounded task to an isolated in-process `AgentSession`; it is not a background worker or a fleet manager.
+Adds the `subagent` tool and `/agents` settings command. It delegates bounded work to isolated in-process `AgentSession` workers; it is not a background-worker or fleet-management system.
+
+## Tool contract
+
+Every call supplies one ordered `tasks` array with 1–8 items:
+
+```json
+{
+  "tasks": [
+    {
+      "prompt": "Locate the provider retry implementation and report exact symbols.",
+      "agent": "explorer",
+      "cwd": "src/core"
+    }
+  ]
+}
+```
 
-## Tool modes
+Each item has:
 
-Exactly one mode is required per call:
+```text
+prompt   Required self-contained worker briefing
+agent?   explorer or general; defaults to explorer
+cwd?     Directory inside the parent working directory
+```
 
-- **Single**: `agent`, `description`, and `prompt`.
-- **Parallel**: `tasks`, an array of independent task objects.
+There is no separate single-task or parallel mode. One item launches one worker; multiple items launch concurrent workers. A session-scoped gate permits at most five active workers across all sibling `subagent` calls, so additional items wait for a slot. Results always follow input order, regardless of completion order.
 
-There is deliberately no chain mode: sequential work is driven by the parent, which reads each report before writing the next briefing.
+All tasks are preflighted before any worker starts. Profile, working-directory, model, thinking-level, or authentication failure in one item rejects the entire call without launching the other workers. Once execution begins, one worker failing does not cancel independent siblings.
 
-Every task object has:
+Sequential work uses another `subagent` call after the parent has read the previous report and written the next briefing.
 
-```text
-agent?       Agent profile name; defaults to general
-description  Short UI label
-prompt       Self-contained worker briefing
-cwd?         Relative or absolute directory inside the parent working directory
-```
+## Built-in profiles
 
-Parallel batches allow at most eight tasks. A session-scoped gate runs at most five workers concurrently, including sibling `subagent` calls from the same parent session.
+There are exactly two profiles:
 
-## Agent profiles
+- **Explorer** (`explorer`, default): read-only investigation with `read`, `grep`, `find`, `ls`, and `bash`. Bash remains available for Git history and inspection commands such as `git log`, `git diff`, `git blame`, `git show`, `git status`, `wc`, `head`, and `tail`. Its system prompt forbids redirects, heredoc writes, temporary files, state-changing Git commands, installs, and network access.
+- **General** (`general`): implementation, file changes, and stateful verification with `read`, `bash`, `edit`, and `write`.
 
-Profiles are Markdown files with YAML frontmatter:
+There are no user or project profile files. Child sessions load no extensions, skills, prompt templates, or themes, so workers cannot recursively call `subagent` or inherit unrelated extension capabilities. Explorer continues to skip project context files such as `AGENTS.md`; General loads trusted project context normally.
 
-```yaml
----
-name: reviewer
-description: Read-only implementation reviewer
-tools: read, grep, find, ls
-model: anthropic/claude-sonnet-4-5
-thinking: medium
-backend: sdk
----
+Worker contexts are isolated, but workers share the parent's checkout. Concurrent tasks therefore must be independent and must not perform overlapping writes.
 
-Review the delegated task independently and report exact evidence.
-```
+## Model and thinking selection
 
-Sources and precedence are:
+Model and thinking resolution has two layers:
 
 ```text
-built-in < ~/.pi/agent/agents/*.md < trusted-project/.pi/agents/*.md
+saved /agents override > current parent session
 ```
 
-Project definitions are loaded only after Pi trusts the project. Invalid Markdown definitions appear as `/agents` diagnostics without hiding valid profiles.
+Callers cannot select model or thinking per task. Run `/agents` to configure Explorer or General:
 
-Built-in profiles:
+1. Select **Explorer** or **General**.
+2. Select **Model** or **Thinking**.
+3. Choose a concrete value or **inherit**.
 
-- `general`: read, bash, edit, and write.
-- `explorer`: `read`, `grep`, `find`, and `ls`, plus `bash` constrained by its system prompt to read-only inspection (git history, counting, and similar).
+Each confirmed choice is saved immediately; there is no draft, Apply, or Save step. Choosing **inherit** immediately removes that override. Escape only navigates back and never rolls back choices already confirmed.
 
-A profile may only allow Pi built-in tools. Child sessions load no extensions, skills, or prompt templates, so a worker cannot recursively call `subagent` or inherit unrelated extension capabilities. Project context files such as `AGENTS.md` remain available, except for the built-in `explorer`, which skips them: read-only exploration needs no commit/PR rules, and the parent interprets its results.
-
-## Model and thinking selection
+The TUI model picker supports search, scoped/all models, unavailable saved models, and catalog refresh. Thinking choices are limited to levels supported by the effective model.
 
-The model/thinking resolution has exactly two layers:
+Overrides are saved atomically in:
 
 ```text
-saved /agents profile override > current parent session
+~/.pi/agent/subagent.json
 ```
 
-Callers cannot pick models per call, and profile Markdown `model`/`thinking`
-frontmatter is intentionally ignored: agent files travel across machines, so a
-pinned model rarely exists in the reader's environment.
+Only `explorer` and `general` keys are valid. A stale or invalid `subagent.json` (older formats, unknown profiles, or malformed JSON) is reset to an empty, fully inheriting config the first time it is loaded, so an old file never blocks the tool or `/agents`. Overrides affect future workers and never change the parent session's model or thinking level.
 
-Run `/agents` to choose a profile. The TUI presents display-only title labels
-(`explorer` becomes `Explorer`, `code-reviewer` becomes `Code Reviewer`) in
-identifier order, while tool calls, profile files, and saved configuration keep
-the lowercase identifier. The selected profile's human-facing description
-appears below the list in full and wraps to the terminal width; built-in
-profiles keep longer delegation guidance out of this UI copy.
+## Lifecycle and retry
 
-The profile editor keeps model search and thinking selection on one screen:
+- The parent call waits until every worker reaches a terminal state.
+- Parent abort, `/reload`, `/new`, `/resume`, `/fork`, and session shutdown abort active and queued workers.
+- Provider auto-retry remains visible as `Retrying (n/m) in Xs`.
+- A retryable failure that produced no turns or tool use may be retried at task level up to two more times. Runs with partial work are never restarted.
+- Retry backoff does not hold a concurrency slot; another queued worker can run while the failed task waits.
+- A parent abort or session shutdown interrupts queued and retrying workers immediately.
 
-- type to search configured models;
-- use `Tab` to switch between scoped and all models when a scope exists;
-- use the configured thinking-cycle key (`Shift+Tab` by default) to choose
-  **inherit** or a level supported by the highlighted model;
-- use `Enter` to save the model and thinking choice together, or `Esc` to return
-  without saving.
+Child sessions share the parent's canonical model/authentication runtime, so extension-registered providers and current credentials do not need to be mirrored into a second runtime.
 
-**inherit** follows the parent session's current model or thinking value. An
-explicit model is stored as `provider/model`; an explicit thinking override is
-stored as its supported level.
+## Transcript UI
 
-Overrides are user-owned and saved atomically in:
+While running, the collapsed view shows a progress header followed by one
+row per task in original input order:
 
 ```text
-~/.pi/agent/subagent.json
+› 2/4 done · 12s
+  › Explorer · Locate retry scheduling — Run git log
+  ✓ Explorer · Map provider registration
+  ○ Explorer · Find related tests
+  ○ General  · Apply focused fix
+```
+
+Every task is always listed: there is no row cap, no active-first
+reordering, and no `+N more` truncation. Live rows append the current
+activity, failure reason, or retry countdown.
+
+Expanded running calls show profile/model/thinking/cwd metrics, retry state, and the bounded Activity history for each task. Streaming assistant text is not copied into the parent transcript.
+
+Once settled, the collapsed view keeps the same one-row-per-task layout under an aggregate line with the batch outcome, counts, cost, and duration:
+
+```text
+✓ 3 completed · 1 failed · 24s · $0.031
+  ✓ Explorer · Locate retry scheduling · 12s
+  ✓ Explorer · Map provider registration · 8.4s
+  × General  · Apply focused fix · 1m 3s
+  ✓ Explorer · Find related tests · 21s
 ```
 
-They apply only to future subagent runs and never change the parent session's `/model` or thinking level.
+The expanded settled view shows, for each task:
 
-## Lifecycle and output
+- the complete original Prompt from the tool call;
+- model, thinking, cwd, usage, cost, and duration;
+- Error when present;
+- the final Report, or `Report · partial` when a failed/aborted worker produced useful output.
 
-- The parent tool call waits until every worker reaches a terminal state.
-- Parent abort, `/reload`, `/new`, `/resume`, `/fork`, and session shutdown abort active child sessions. Queued workers do not survive the call.
-- Parallel worker failures do not cancel other independent workers.
-- Transient provider errors auto-retry: the worker session retries retryable stream errors with backoff (visible as a live `Retrying (n/m) in Xs…` countdown), and a failure that produced no work (for example a preflight auth throw) is rerun at the task level up to two more times. Provider and task retries share one absolute-deadline state; at zero it reads `Retrying now…`, and parent abort/session shutdown interrupts backoff immediately. Runs with partial work behind them are never rerun.
-- Progress is rendered in Pi's native tool transcript. While a call is running, the Subagent renderer re-schedules its own repaint once per second, independently of worker output and the main Working spinner. Silent single and parallel runs therefore keep advancing their own elapsed clocks in collapsed and expanded views, and queued retries keep counting down. Once settled, the final duration is fixed and refresh stops.
-- The collapsed view stays lean in both phases: while running, one bounded intent line (for example `Verifying changes`) carries tool uses, the `ctx:` context watermark, cost, and elapsed time above the current tool marked with `›` and the live output tail; once settled, the sentence-aware result excerpt is followed by a single metrics line (`tok · $ · duration`, plus tool uses and `ctx:` for single runs) and the configured expand hint. Live lines never quote token totals — mid-run totals are cache-inflated. The call-level status dot belongs to the tool shell; run and activity rows only use `›`, `○`, `✓`, `×`, and `■`, and parallel run rows carry stable dim ordinals that match the expanded section numbers. `Ctrl+O` expands each run into a report cover sheet: a status line, a metrics line, a fixed two-line `Prompt` preview (`… continues, N more lines`, honest about the 1KB bound), an `Activity · last n of N` digest whose successful rows are quiet aligned one-liners, a `Working` tail while streaming, and the full `Report` (or `Error`, with `Report · partial` for salvaged output) rendered as Markdown. Expanded batches start with a numbered contents list whose numbers match the `── N · ✓ Agent` section headers.
-- Failed and aborted batch runs place their bounded reason on a separate error-colored line below the run headline instead of cutting it into the status row. Reasons are capped at 200 characters and keep their hanging indent when wrapped; successful settled excerpts prefer complete leading sentences within their 96-character budget. Rounded durations switch to minute form at 60 seconds without producing `1m 60s`.
-- Full child transcripts are not stored separately. Bounded run details remain in the parent tool result, so completed calls restore naturally in the parent session tree.
-- Nested usage is returned with the tool result and included in parent session accounting.
+Activity is intentionally a running-state view; settled transparency comes from the original Prompt and final Report. Full child transcripts are not stored separately. Activity, errors, reports, usage, and model-facing output remain bounded, and completed calls restore through the parent session tree.
 
 ## Deliberate non-features
 
-There are no background agents, persistent worker IDs, unread state, fleet panel, statusline widget, send/stop/resume control plane, completion notifications, swarm/coordinator, worktree isolation, nested agents, MCP, hooks, or agent memory.
+There are no custom profiles, background agents, persistent worker IDs, unread state, fleet panel, statusline widget, send/stop/resume control plane, completion notifications, chain mode, swarm/coordinator, worktree isolation, nested agents, MCP, hooks, or agent memory.

package/docs/compaction.md

@@ -1,6 +1,6 @@
 # Compaction & Branch Summarization
 
-LLMs have limited context windows. When conversations grow too long, pi uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
+LLMs have limited context windows. When conversations grow too long, Pi uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
 
 ## Public API
 
@@ -51,7 +51,7 @@ You can also trigger manually with `/compact [instructions]`, where optional ins
 Before compaction:
 
   entry:  0     1     2     3      4     5     6      7      8     9
-        ┌─────┬─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┐
+        ┌─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┐
         │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│
         └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┘
                 └────────┬───────┘ └──────────────┬──────────────┘
@@ -62,7 +62,7 @@ Before compaction:
 After compaction (new entry appended):
 
   entry:  0     1     2     3      4     5     6      7      8     9     10
-        ┌─────┬─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┐
+        ┌─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┬─────┐
         │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│ cmp │
         └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┴─────┘
                └──────────┬──────┘ └──────────────────────┬───────────────────┘
@@ -105,7 +105,7 @@ Split turn (one huge turn exceeds budget):
   turnPrefixMessages = [usr, ass, tool, ass, tool, tool]
 ```
 
-For split turns, pi generates two summaries and merges them:
+For split turns, Pi generates two summaries and merges them:
 1. **History summary**: Previous context (if any)
 2. **Turn prefix summary**: The early part of the split turn
 
@@ -152,7 +152,7 @@ Pi uses an internal preparation step before `compact()`. For direct programmatic
 
 ### When It Triggers
 
-When you use `/tree` to navigate to a different branch, pi offers to summarize the work you're leaving. This injects context from the left branch into the new branch.
+When you use `/tree` to navigate to a different branch, Pi offers to summarize the work you're leaving. This injects context from the left branch into the new branch.
 
 ### How It Works
 
@@ -181,7 +181,7 @@ After navigation with summary:
 
 ### Cumulative File Tracking
 
-Both compaction and branch summarization track files cumulatively. When generating a summary, pi extracts file operations from:
+Both compaction and branch summarization track files cumulatively. When generating a summary, Pi extracts file operations from:
 - Tool calls in the messages being summarized
 - Previous compaction or branch summary `details` (if any)
 

package/docs/custom-provider.md

@@ -169,7 +169,7 @@ Set `api` on the provider as the default, or on a model when one provider has mo
 | `openai-responses` | OpenAI Responses APIs |
 | `azure-openai-responses` | Azure OpenAI Responses APIs |
 | `openai-codex-responses` | OpenAI Codex Responses APIs |
-| `mistral-conversations` | Mistral Conversations APIs |
+| `mistral-conversations` | Native Mistral Chat Completions streaming |
 | `google-generative-ai` | Google Generative AI APIs |
 | `google-vertex` | Google Vertex AI APIs |
 | `bedrock-converse-stream` | Amazon Bedrock Converse Stream APIs |

package/docs/docs.json

@@ -56,6 +56,10 @@
           "title": "Overview",
           "path": "bundled/README.md"
         },
+        {
+          "title": "Background",
+          "path": "bundled/extensions/background.md"
+        },
         {
           "title": "DeepWiki",
           "path": "bundled/extensions/deepwiki.md"

package/docs/environment-variables.md

@@ -3,14 +3,19 @@
 Pi uses environment variables in three ways:
 
 - Variables such as `PI_OFFLINE` configure the Pi process.
-- Pi sets `PI_CODING_AGENT` so child processes can detect that they run inside Pi.
+- Pi sets process markers so child processes can identify Pi as the launching agent.
 - Commands run by the LLM-callable bash tool receive `PI_*` variables describing the current session.
 
 Provider API-key variables are documented separately in [Providers](providers.md#environment-variables-or-auth-file).
 
 ## Process Marker
 
-The CLI and RPC entry points set `PI_CODING_AGENT=true`. Child processes inherit it and can use it to detect that they run inside Pi. It is not session-specific and is not set automatically when Pi is embedded through the SDK.
+The CLI and RPC entry points set two process markers:
+
+- `AI_AGENT=pi` is a generic marker that lets tooling identify Pi as the agent that launched the process.
+- `PI_CODING_AGENT=true` is Pi-specific and lets child processes detect that they run inside Pi.
+
+Child processes inherit both markers. They are not session-specific and are not set automatically when Pi is embedded through the SDK.
 
 ## Bash Tool Session Environment
 
@@ -82,6 +87,7 @@ These variables are read by Pi itself:
 | `PI_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
 | `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
 | `PI_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
+| `PI_TUI_ESC_TIMEOUT` | How long to wait after a lone ESC before treating it as Escape, in milliseconds; defaults to `100` over SSH and `10` otherwise. Increase it if Alt-key input is misread as Escape |
 | `VISUAL`, `EDITOR` | Fallback external editor for Ctrl+G when `externalEditor` is unset; defaults to Notepad on Windows and `nano` elsewhere |
 | `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
 

package/docs/extensions.md

@@ -999,9 +999,9 @@ ctx.sessionManager.buildContextEntries()    // Active branch entries with compac
 ctx.sessionManager.getLeafId()              // Current leaf entry ID
 ```
 
-### ctx.modelRegistry / ctx.model / ctx.thinkingLevel / ctx.scopedModels
+### ctx.modelRegistry / ctx.modelRuntime / ctx.model / ctx.thinkingLevel / ctx.scopedModels
 
-Access to models, providers, and resolved authentication. `ctx.modelRegistry.getProvider(id)` returns the effective pi-ai provider, while `getProviderAuth(id)` resolves its current API key, headers, base URL, and provider-scoped environment without requiring a loaded model. `ctx.model` is the active model (or `undefined` when none is active), and `ctx.thinkingLevel` is its current effective thinking level when the session runtime provides one.
+Access to models, providers, and resolved authentication. `ctx.modelRegistry.getProvider(id)` returns the effective pi-ai provider, while `getProviderAuth(id)` resolves its current API key, headers, base URL, and provider-scoped environment without requiring a loaded model. `ctx.modelRuntime` is the canonical `ModelRuntime` owned by the current session; use it when creating nested SDK sessions so they share the same provider registrations, model catalog, and credentials instead of constructing and synchronizing a mirror runtime. `ctx.model` is the active model (or `undefined` when none is active), and `ctx.thinkingLevel` is its current effective thinking level when the session runtime provides one.
 
 `ctx.scopedModels` is the read-only list of models scoped to the current session—the same set shown by `/scoped-models`. Pi resolves it at session start from `--models` and the `enabledModels` setting, matching `provider/modelId` or bare `modelId` patterns with minimatch. An empty list means no scope is configured and every available model is usable. Each entry is `{ model, thinkingLevel? }`; use this list when a custom model picker should mirror the built-in scope rather than enumerate the full registry.
 
@@ -1448,12 +1448,16 @@ pi.sendUserMessage([
 // During streaming - must specify delivery mode
 pi.sendUserMessage("Focus on error handling", { deliverAs: "steer" });
 pi.sendUserMessage("And then summarize", { deliverAs: "followUp" });
+
+// Opt in to extension command dispatch and skill/prompt template expansion
+pi.sendUserMessage("/review src/index.ts", { expandPromptTemplates: true });
 ```
 
 **Options:**
 - `deliverAs` - Required when agent is streaming:
   - `"steer"` - Queues the message for delivery after the current assistant turn finishes executing its tool calls
   - `"followUp"` - Waits for agent to finish all tools
+- `expandPromptTemplates` - Dispatch extension commands and expand skill commands and prompt templates. Defaults to `false`.
 
 When not streaming, the message is sent immediately and triggers a new turn. When streaming without `deliverAs`, throws an error.
 

package/docs/json.md

@@ -17,6 +17,7 @@ type JsonAgentSessionEvent =
   | Exclude<AgentSessionEvent, { type: "message_update" }>
   | {
       type: "message_update";
+      usage: Usage;
       assistantMessageEvent: WithoutPartial<AssistantMessageEvent>;
     };
 ```
@@ -93,16 +94,17 @@ Followed by events as they occur:
 {"type":"agent_start"}
 {"type":"turn_start"}
 {"type":"message_start","message":{"role":"assistant","content":[],...}}
-{"type":"message_update","assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
 {"type":"message_end","message":{...}}
 {"type":"turn_end","message":{...},"toolResults":[]}
 {"type":"agent_end","messages":[...],"willRetry":false}
 ```
 
 `message_update` records are delta-only. They omit both the cumulative `message` field and
-`assistantMessageEvent.partial` to keep stream size linear. Use `contentIndex` and `delta`
-to assemble live text, thinking, or tool-call arguments if needed. `message_end` contains
-the final authoritative message.
+`assistantMessageEvent.partial` to keep stream size linear. The top-level `usage` field contains
+the latest cumulative provider-reported usage and may remain zero when a provider only reports
+usage at completion. Use `contentIndex` and `delta` to assemble live text, thinking, or tool-call
+arguments if needed. `message_end` contains the final authoritative message.
 
 ## Example
 

package/docs/keybindings.md

@@ -86,7 +86,7 @@ The dedicated history actions always change history entries, regardless of the c
 
 ### TUI Fullscreen Viewport
 
-These actions apply when interactive mode uses `--tui-mode fullscreen` and target the primary transcript scroll region. Two-finger trackpad and mouse-wheel input scroll the region under the pointer, falling back to the transcript over the fixed editor/status/footer dock. Clicking an OSC 8 hyperlink opens it in the default handler. Dragging with the primary mouse button selects text and copies it to the clipboard; holding at the transcript's top or bottom edge auto-scrolls into off-screen content.
+These actions apply when interactive mode uses `--tui-mode fullscreen` and target the primary transcript scroll region. Two-finger trackpad and mouse-wheel input scroll the region under the pointer, falling back to the transcript over the fixed editor/status/footer dock. Clicking an OSC 8 hyperlink opens it in the default handler. Dragging with the primary mouse button selects text and copies it to the clipboard; holding at the transcript's top or bottom edge auto-scrolls into off-screen content. See [Terminal setup](terminal-setup.md) for terminal-specific mouse and trackpad behavior.
 
 Fullscreen transcript bindings take precedence over editor bindings. The default unmodified navigation keys therefore control the transcript in fullscreen mode, while their `ctrl` variants continue to control the editor. Outside fullscreen mode, both variants control the editor.
 
@@ -97,7 +97,7 @@ Fullscreen transcript bindings take precedence over editor bindings. The default
 | `pageUp`, `pageDown` | Editor | Transcript |
 | `ctrl+pageUp`, `ctrl+pageDown` | Editor | Editor |
 
-This routing remains configurable through the ordinary action bindings. For example, `"tui.altScreen.pageUp": "ctrl+pageUp"` makes `pageUp` control the editor and `ctrl+pageUp` control the transcript in fullscreen mode. Bind `tui.altScreen.halfPageUp` and `tui.altScreen.halfPageDown` for smaller transcript steps while keeping the full-page bindings. Setting `"tui.altScreen.pageUp": []` disables that transcript shortcut entirely. User bindings replace the defaults for that action.
+This routing remains configurable through the ordinary action bindings. For example, `"tui.altScreen.pageUp": "ctrl+pageUp"` makes `pageUp` control the editor and `ctrl+pageUp` control the transcript in fullscreen mode. Bind `tui.altScreen.halfPageUp` and `tui.altScreen.halfPageDown` for half-page steps, or bind `tui.altScreen.lineUp` and `tui.altScreen.lineDown` for single-line steps. Setting `"tui.altScreen.pageUp": []` disables that transcript shortcut entirely. User bindings replace the defaults for that action.
 
 | Keybinding id | Default | Description |
 |--------|---------|-------------|
@@ -105,8 +105,14 @@ This routing remains configurable through the ordinary action bindings. For exam
 | `tui.altScreen.pageDown` | `pageDown` | Scroll the transcript down by one page |
 | `tui.altScreen.halfPageUp` | *(none)* | Scroll the transcript up by half a page |
 | `tui.altScreen.halfPageDown` | *(none)* | Scroll the transcript down by half a page |
+| `tui.altScreen.lineUp` | *(none)* | Scroll the transcript up by one line |
+| `tui.altScreen.lineDown` | *(none)* | Scroll the transcript down by one line |
 | `tui.altScreen.previousPrompt` | `ctrl+shift+up` | Jump to the previous marked message |
 | `tui.altScreen.nextPrompt` | `ctrl+shift+down` | Jump to the next marked message |
+| `tui.altScreen.search` | `ctrl+shift+f` | Search the rendered transcript |
+| `tui.altScreen.searchNext` | `enter`, `ctrl+g` | Select the next search match while searching |
+| `tui.altScreen.searchPrevious` | `shift+enter`, `ctrl+shift+g` | Select the previous search match while searching |
+| `tui.altScreen.searchClose` | `escape` | Close transcript search |
 | `tui.altScreen.top` | `home` | Scroll to the beginning of the transcript |
 | `tui.altScreen.bottom` | `end` | Scroll to the transcript end and follow new output |
 
@@ -120,6 +126,7 @@ This routing remains configurable through the ordinary action bindings. For exam
 | `app.suspend` | `ctrl+z` (none on Windows) | Suspend to background |
 | `app.editor.external` | `ctrl+g` | Open in external editor (`externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere) |
 | `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows) | Paste image or text from clipboard |
+| `app.backgroundTasks.kill` | `k` | Stop the selected task in the Background task menu |
 
 ### Sessions
 

package/docs/rpc.md

@@ -954,6 +954,14 @@ Emitted during streaming of assistant messages. Contains a delta event without a
 ```json
 {
   "type": "message_update",
+  "usage": {
+    "input": 100,
+    "output": 1,
+    "cacheRead": 0,
+    "cacheWrite": 0,
+    "totalTokens": 101,
+    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0, "total": 0}
+  },
   "assistantMessageEvent": {
     "type": "text_delta",
     "contentIndex": 0,
@@ -978,12 +986,15 @@ The `assistantMessageEvent` field contains one of these delta types:
 
 Example streaming a text response:
 ```json
-{"type":"message_update","assistantMessageEvent":{"type":"text_start","contentIndex":0}}
-{"type":"message_update","assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
-{"type":"message_update","assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":" world"}}
-{"type":"message_update","assistantMessageEvent":{"type":"text_end","contentIndex":0,"content":"Hello world"}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_start","contentIndex":0}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":" world"}}
+{"type":"message_update","usage":{...},"assistantMessageEvent":{"type":"text_end","contentIndex":0,"content":"Hello world"}}
 ```
 
+The top-level `usage` field contains the latest cumulative provider-reported usage. It may remain
+zero until completion when a provider does not report usage during streaming.
+
 `message_update` intentionally omits the former cumulative `message` field and
 `assistantMessageEvent.partial`. Clients that need a live partial message must assemble it
 from `message_start` and subsequent events using `contentIndex`. Treat `message_end.message`

package/docs/sdk.md

@@ -408,6 +408,13 @@ import { createAgentSession, ModelRuntime } from "@astralyn/pi";
 
 const modelRuntime = await ModelRuntime.create();
 
+// create() restores cached catalogs but does not refresh them from pi.dev by default.
+// Opt in to a create-time network refresh and bound how long it may take:
+const refreshedRuntime = await ModelRuntime.create({
+  allowModelNetwork: true,
+  modelRefreshTimeoutMs: 15_000,
+});
+
 // Find specific built-in models (doesn't check whether API keys exist)
 const opus = getModel("anthropic", "claude-opus-4-5");
 const sonnet = getModel("anthropic", "claude-sonnet-4-5");
@@ -439,6 +446,8 @@ If no model is provided:
 2. Uses default from settings
 3. Prefers a known provider default among available models, then falls back to the first available model
 
+Remote catalogs are persisted locally so later runtimes can restore them without a network request. The default file is `~/.pi/agent/models-store.json`; set `modelsStorePath` to choose another location, or inject `modelsStore` to control persistence. Network refreshes are throttled to once per provider every four hours unless forced. To force an immediate refresh, call `await modelRuntime.refresh({ allowNetwork: true, force: true, signal })`. Setting `PI_OFFLINE` disables model network access.
+
 To match CLI model parsing, use the exported resolver helpers:
 
 ```typescript

package/docs/settings.md

@@ -66,6 +66,7 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
 | `autocompleteMaxVisible` | number | `5` | Max visible items in autocomplete dropdown (3-20) |
 | `showHardwareCursor` | boolean | `false` | Show the terminal cursor while TUI positions it for IME support |
 | `tuiMode` | string | `"fullscreen"` | Interactive TUI mode: `"fullscreen"` or `"regular"`. Changes from `/settings` apply immediately; `--tui-mode` overrides this setting at startup |
+| `fullscreenExitOutput` | string | `"transcript"` | Fullscreen exit output: `"transcript"` prints the final transcript and resume hint, while `"resume-hint"` restores the previous screen and prints only the resume hint. Has no effect in regular TUI mode |
 | `fullscreenScrollbar` | string | `"auto"` | Fullscreen transcript scrollbar: `"auto"` shows it temporarily while scrolling, `"always"` reserves the rightmost column and keeps it visible, and `"hidden"` hides it. Has no effect in regular TUI mode |
 
 For VS Code, include `--wait` so pi resumes after the editor exits:
@@ -191,6 +192,20 @@ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explic
 | `shellCommandPrefix` | string | - | Prefix for every bash command (e.g., `"shopt -s expand_aliases"`) |
 | `npmCommand` | string[] | - | Command argv used for npm package lookup/install operations (e.g., `["mise", "exec", "node@20", "--", "npm"]`) |
 
+Windows paths in JSON must use forward slashes or escaped backslashes:
+
+```json
+{
+  "shellPath": "C:/Program Files/Git/bin/bash.exe"
+}
+```
+
+```json
+{
+  "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"
+}
+```
+
 ```json
 {
   "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
@@ -199,6 +214,22 @@ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explic
 
 `npmCommand` is used for all npm package-manager operations, including installs, uninstalls, and dependency installs inside git packages. User-scoped npm packages install under `~/.pi/agent/npm/`; project-scoped npm packages install under `.pi/npm/`. Use argv-style entries exactly as the process should be launched. When `npmCommand` is configured, git package dependency installs use plain `install` to avoid npm-specific flags in wrappers or alternate package managers.
 
+### Tools
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `defaultTools` | string[] | - | Built-in tools enabled initially. When omitted, Pi uses its standard defaults |
+
+`defaultTools` selects the built-in tools enabled at startup. Extension and SDK custom tools remain enabled:
+
+```json
+{
+  "defaultTools": ["bash", "edit", "write"]
+}
+```
+
+An empty array starts with no built-in tools while preserving extension and SDK custom tools. `--tools` replaces this behavior with a strict allowlist for all tools, `--no-tools` disables all tools, and `--no-builtin-tools` disables the built-in defaults. `--exclude-tools` filters the resulting list. A project `defaultTools` array replaces the global array.
+
 ### Sessions
 
 | Setting | Type | Default | Description |

package/docs/terminal-setup.md

@@ -2,9 +2,26 @@
 
 Pi uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Most modern terminals support this protocol, but some require configuration.
 
-## Kitty, iTerm2
+## Kitty
 
-Work out of the box.
+Works out of the box.
+
+## iTerm2
+
+### Regular TUI mode
+
+Works out of the box.
+
+### Fullscreen TUI mode
+
+Pi owns the viewport, so iTerm2 sends mouse-wheel reports instead of scrolling its native scrollback. With iTerm2's default fast-trackpad behavior, those reports can lose most of an accelerated wheel delta, making fullscreen scrolling much slower than regular scrolling.
+
+If fast mouse-wheel gestures move only about one line at a time in fullscreen mode:
+
+1. Open **iTerm2 → Settings → Advanced**.
+2. Search for **Trackpad scrolls fast?** and set it to **No**.
+
+This is an iTerm2-wide workaround and may also change native trackpad scrolling. The underlying behavior is tracked in [iTerm2 issue 9619](https://gitlab.com/gnachman/iterm2/-/work_items/9619).
 
 ## Apple Terminal
 
@@ -32,6 +49,10 @@ If Claude Code 2.x or newer is the only reason you added that mapping, you can r
 
 Pi binds `Ctrl+J` as a default newline alias, so `Shift+Enter` keeps working in tmux via that remap without extra pi configuration.
 
+### Fullscreen TUI mode
+
+In fullscreen mode, links remain clickable, but Ghostty does not show its hover underline or lower-left URL preview while pi captures mouse input. Hold `Shift+Command` on macOS or `Shift+Ctrl` on Linux to use Ghostty's native link handling.
+
 ## WezTerm
 
 WezTerm usually works out of the box for `Shift+Enter` via xterm modifyOtherKeys. To use the Kitty keyboard protocol explicitly, create `~/.wezterm.lua`: