@astralyn/pi 1.4.11 → 1.5.0

package/docs/packages.md

@@ -9,6 +9,7 @@ Pi packages bundle extensions, skills, prompt templates, and themes so you can s
 - [Install and Manage](#install-and-manage)
 - [Package Sources](#package-sources)
 - [Creating a Pi Package](#creating-a-pi-package)
+- [Show a changelog](#show-a-changelog)
 - [Package Structure](#package-structure)
 - [Dependencies](#dependencies)
 - [Package Filtering](#package-filtering)
@@ -42,13 +43,17 @@ These commands manage pi packages and `pi update` can update the pi CLI installa
 
 By default, `install` and `remove` write to user settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead. Project settings can be shared with your team, and pi installs any missing packages automatically on startup after the project is trusted.
 
-To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:
+If a configured package fails to install at startup, for example because npm cannot reach the registry, pi warns about it, skips that package's resources, and keeps running. It tries again on the next start or `/reload`. `pi install` and `pi update --extensions` still report the failure and exit non-zero.
+
+To try a package without installing it, use `--extension` or `-e`. It is not added to settings:
 
 ```bash
 pi -e npm:@foo/bar
 pi -e git:github.com/user/repo
 ```
 
+Pi caches `-e` packages under `~/.pi/agent/tmp/extensions/` and checks them on every start and `/reload`. An npm package is reinstalled when the registry has a newer version that matches the specification; an exact version such as `@1.2.3` is not checked. A git package is fetched and reset to the remote branch or ref; a commit hash that is already checked out is not fetched. If the check fails or offline mode is on, pi loads the cached copy.
+
 ## Package Sources
 
 Pi accepts three source types in settings and `pi install`.
@@ -154,6 +159,26 @@ The [package gallery](https://pi.dev/packages) displays packages tagged with `pi
 
 If both are set, video takes precedence.
 
+## Show a changelog
+
+After a package update, pi can show what changed. On the next fresh launch, pi reads the package changelog and shows entries newer than the last seen version under "Extension Updates", the same way it shows its own changelog. The first time pi sees a package, it records the version without showing anything.
+
+This applies to packages that load at least one extension. Packages that only provide skills, prompt templates, or themes do not show a changelog.
+
+By default pi reads `CHANGELOG.md` from the package root. Point `pi.changelogPath` at another file inside the package, or set it to `""` to disable the changelog:
+
+```json
+{
+  "name": "my-package",
+  "version": "1.2.0",
+  "pi": {
+    "changelogPath": "./docs/CHANGELOG.md"
+  }
+}
+```
+
+Use version headings such as `## [1.2.0]` or `## 1.2.0 - 2026-01-01`. Entries are matched against the `version` field in `package.json`, so a git package only shows a changelog when that field increases. The `collapseChangelog` setting condenses the section to one line per package, such as `Updated my-package to v1.2.0.` `/changelog` does not show package changelogs; read the package's changelog file or repository for details.
+
 ## Package Structure
 
 ### Convention Directories

package/docs/rpc.md

@@ -959,7 +959,7 @@ Emitted when nothing more will happen without new input: no run, compaction, ret
 {"type": "session_quiescent"}
 ```
 
-`RpcClient.waitForQuiescence(timeout?)` resolves on this event, or at once when `get_state` reports `isQuiescent`; `collectEventsUntilQuiescent(timeout?)` collects events until it. `waitForIdle()` and `collectEvents()` still resolve on the first `agent_settled`. Closing stdin shuts the process down immediately, without waiting for Background work.
+`RpcClient.waitForQuiescence(timeout?)` resolves on this event, or at once when `get_state` reports `isQuiescent`. `collectEventsUntilQuiescent(timeout?)` collects events until the next one: start it before the prompt it should cover, since it does not resolve early when the session is quiescent before that prompt begins. `waitForIdle()` and `collectEvents()` still resolve on the first `agent_settled`. Closing stdin shuts the process down immediately, without waiting for Background work.
 
 ### turn_start / turn_end
 

package/docs/sdk.md

@@ -116,7 +116,9 @@ interface AgentSession {
 
   // Background host controls (see Background execution below)
   pauseTaskNotifications(): () => void;
+  withTaskNotificationsPaused<T>(operation: () => Promise<T>): Promise<T>;
   retryTaskNotifications(): void;
+  shutdownTasks(graceMs?: number): Promise<void>;
   getSessionStats(): SessionStats;
 
   // Cleanup (does not await Background draining)
@@ -258,10 +260,10 @@ Background work is admitted only while the `tasks` management tool is active in
 
 The host must choose:
 
-- **Lifetime and cancellation:** a settled main-agent turn is not the end of background work. `session.abort()` cancels foreground-owned work, not detached work. Use `session.tasks.kill(id)` for a whole execution, or `await session.tasks.shutdown(graceMs?)` to close admission, cancel all owned work and drain within a bounded grace period (default 2 seconds, maximum 60 seconds). A non-cooperating executor can outlive that grace period.
-- **Result-driven turns and cost:** automatic completions join the host's prompt queue, so a running turn receives them as steering and an idle session starts a completion turn. Use the nestable `session.pauseTaskNotifications()` to defer delivery; its returned release function is idempotent. Pausing does not stop execution or its costs. Budget worker activity and completion-triggered turns explicitly.
+- **Lifetime and cancellation:** a settled main-agent turn is not the end of background work. `session.abort()` cancels foreground-owned work, not detached work. Use `session.tasks.kill(id)` for a whole execution, or `await session.shutdownTasks(graceMs?)` to close admission, abort the main agent, cancel all owned work and drain within a bounded grace period (default 2 seconds, maximum 60 seconds). A non-cooperating executor can outlive that grace period.
+- **Result-driven turns and cost:** automatic completions join the host's prompt queue, so a running turn receives them as steering and an idle session starts a completion turn. Use the nestable `session.pauseTaskNotifications()` to defer delivery; its returned release function is idempotent. `session.withTaskNotificationsPaused(operation)` holds a pause for the duration of an async operation. Pausing does not stop execution or its costs. Budget worker activity and completion-triggered turns explicitly.
 - **Observation and delivery:** `session.tasks` exposes the [public supervision methods](extensions.md#ctxtasks). `list()`, `get()` and `read()` observe; a terminal snapshot alone does not acknowledge model delivery, and there is no blocking wait: subscribe with `session.tasks.subscribe()` or use `waitForQuiescence()` below. A direct SDK consumer that handles a result outside model history can call `session.acknowledgeTaskDelivery(task.id)` after successful consumption, which stops the session from notifying the model about it (an unknown or already delivered ID is ignored). An undelivered completion keeps its task and output retained until it is delivered or acknowledged, or its runtime closes. Failed notification delivery leaves the result available for inspection; after fixing the host failure, call `session.retryTaskNotifications()` explicitly. Pi does not retry a failed delivery forever on a timer.
-- **Shutdown:** `await runtime.dispose()` handles background shutdown and extension lifecycle when using the runtime API. For a directly owned session, drain Background, abort the main agent, then dispose; synchronous `session.dispose()` alone is not an awaited drain.
+- **Shutdown:** `await runtime.dispose()` handles background shutdown and extension lifecycle when using the runtime API. For a directly owned session, `await session.shutdownTasks()`, then dispose; synchronous `session.dispose()` alone is not an awaited drain.
 - **Waiting for all work:** `prompt()` resolves when its own run settles, before any Background completion turn. `await session.waitForQuiescence(signal?)` resolves once the session is quiescent: no run, compaction, retry or branch summary, no unsettled Background task, and no completion left to deliver (the `session_quiescent` event marks the same moment, once per transition). It uses no timers and rejects when `signal` aborts or the session is disposed. A completion whose delivery failed does not count, since it retries only on the next input; a Background task that never ends keeps the wait open, so pass a signal when that matters.
 
 A deliberately single-turn embedding can suppress completion-triggered turns and cancel leftover work on exit:
@@ -279,7 +281,7 @@ try {
   // Snapshot only: some executions may still be running.
   console.log(session.tasks.list());
 } finally {
-  await Promise.all([session.tasks.shutdown(), session.abort()]);
+  await session.shutdownTasks();
   session.dispose();
   resumeNotifications();
 }
@@ -289,7 +291,7 @@ For a longer-lived embedding, keep the host alive, subscribe to snapshots and ch
 
 Automatic completion messages carry `{ version: 3, task }` in `details`: the bounded terminal snapshot with its input, facts, diagnostics, up to 40 KiB of output and explicit truncation flags. This snapshot is self-contained for transcript replay and is not sent to the model. `content` is separately bounded prose: a log contributes an 8 KiB tail, while a report arrives from its beginning, whole when it fits the 48 KiB budget. After compaction, one request-local reminder lists still-active background tasks to prevent duplicate work; it is not persisted and does not start a turn. Each settlement appends one version-3 `task-record` holding the terminal snapshot and its usage, with no migration of earlier result records. See [Background records](session-format.md#background-records).
 
-`backgroundAllowed: false` on `createAgentSession()` is a host capability ceiling, independent of task kind. It prevents enabling background execution through `bindExtensions` or direct runtime activation, including after reload. Requests for `background: true` are rejected before startup; foreground execution remains available. Omitting this option permits host opt-in but does not enable background execution by itself. This capability restriction is not an OS sandbox.
+`backgroundAllowed: false` on `createAgentSession()` is a host capability ceiling, independent of task kind. It prevents enabling background execution through `bindExtensions`, including after reload. Requests for `background: true` are rejected before startup; foreground execution remains available. Omitting this option permits host opt-in but does not enable background execution by itself. This capability restriction is not an OS sandbox.
 
 Reload, replacement/fork, shutdown and branch navigation enforce the [Background lifetime rules](bundled/tasks.md#lifetime). Saved terminal branch history is observational only: no live processes/workers resume, and restoration does not replay accounting or completion events. Managed logs expire with their runtime records; save anything needed before eviction or shutdown.
 

package/docs/session-format.md

@@ -126,7 +126,7 @@ interface AssistantMessage {
   api: Api;
   provider: ProviderId;
   model: string;
-  responseModel?: string;
+  responseModel?: string;  // Concrete model the provider reported, when it reports one; may equal `model`
   responseId?: string;
   providerThinkingLevel?: string;
   thinkingLevel?: ModelThinkingLevel;
@@ -356,7 +356,7 @@ Terminal history is restored only from the selected branch's valid version-3 rec
 
 These `custom` entries do not enter model context. Automatic terminal delivery creates a `custom_message` with `customType: "task-completion"`, `display: true`, and `{ version: 3, task }` in `details`. The session formats `content` from the same snapshot, with a total limit of 48 KiB and 2,000 lines. A `log` task contributes only an 8 KiB output tail to the automatic model turn; a `report` task contributes its beginning, whole when it fits. Only `content` is sent to the model.
 
-Completion details are bounded to 120 KiB of serialized JSON including escaping. `task` is the terminal snapshot without `display`. Its `input` is clipped to 8 KiB, and its `result` keeps the end of a log or the beginning of a report, up to 40 KiB for replay and expanded rendering. The smaller model-facing projection does not change these stored fields. Source flags survive further clipping. The renderer sanitizes terminal control sequences and applies separate display row limits.
+Completion details are bounded to 120 KiB of serialized JSON including escaping. `task` is the terminal snapshot without `display`. Its `input` is clipped to 8 KiB, and its `result` keeps the end of a log or the beginning of a report, up to 40 KiB for replay. The smaller model-facing projection does not change these stored fields. Source flags survive further clipping. The renderer sanitizes terminal control sequences and applies separate display row limits.
 
 A shell completion's `details` can look like this:
 

package/docs/sessions.md

@@ -15,6 +15,16 @@ pi --session <path|id> # Use a specific session file or partial session ID
 pi --fork <path|id>    # Fork a session file or partial session ID into a new session
 ```
 
+Each session records the working directory it was created in and never changes it. Pi runs a session in its working directory, so tools, `@path` references, project configuration, and context files resolve from there.
+
+| Entry point | Working directory |
+|---|---|
+| `-c`, `--continue` | The current directory |
+| `-r`, `--resume`, `/resume`, `--session`, `/import` | The session's working directory, which can differ from the current directory |
+| `--fork`, or a `--session` ID from another directory that you choose to fork | The current directory, in a new session |
+
+If a session's working directory no longer exists, interactive mode offers to run the session in the current directory instead. Pi does not store that choice, so it asks again the next time you open the session. Other modes exit with an error.
+
 Use `/session` in interactive mode to see the current session file, session ID, message count, tokens, and cost.
 
 For the JSONL file format and SessionManager API, see [Session Format](session-format.md).

package/docs/settings.md

@@ -81,7 +81,7 @@ Selecting a model or thinking level with Enter changes only the current session.
 | `externalEditor` | string | `$VISUAL`, then `$EDITOR`, then Notepad on Windows or `nano` elsewhere | Command for Ctrl+G external editor; takes precedence over environment variables |
 | `quietStartup` | boolean | `"header"` | `false` | `true` hides the startup header and loaded-resource listing. `"header"` keeps the header (version and key hints) but hides the model scope line and loaded-resource listing |
 | `defaultProjectTrust` | string | `"ask"` | Fallback project trust behavior: `"ask"`, `"always"`, or `"never"`. Global setting only |
-| `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
+| `collapseChangelog` | boolean | `false` | Show condensed changelog after updates; also condenses extension package changelogs to one line per package |
 | `enableInstallTelemetry` | boolean | `true` | Legacy setting name for optional provider attribution headers. This does not control update checks |
 | `enableAnalytics` | boolean | `false` | Opt-in analytics data sharing. Currently only asked for during the experimental first-time setup (`PI_EXPERIMENTAL=1`) |
 | `trackingId` | string | - | Analytics tracking identifier, generated when `enableAnalytics` is turned on |
@@ -233,8 +233,8 @@ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explic
 | `steeringMode` | string | `"one-at-a-time"` | How steering messages are sent: `"all"` or `"one-at-a-time"` |
 | `followUpMode` | string | `"one-at-a-time"` | How follow-up messages are sent: `"all"` or `"one-at-a-time"` |
 | `transport` | string | `"auto"` | Preferred transport for providers that support multiple transports: `"sse"`, `"websocket"`, `"websocket-cached"`, or `"auto"` |
-| `httpIdleTimeoutMs` | number | `300000` | HTTP header/body idle timeout in milliseconds, also used by providers with explicit stream idle timeouts. Set to `0` to disable. |
-| `websocketConnectTimeoutMs` | number | `15000` | WebSocket connect/open handshake timeout in milliseconds for providers that support WebSocket transports. Set to `0` to disable. |
+| `httpIdleTimeoutMs` | number \| `"disabled"` | `300000` | HTTP header/body idle timeout in milliseconds, also used by providers with explicit stream idle timeouts. Set to `0` or `"disabled"` to disable. |
+| `websocketConnectTimeoutMs` | number \| `"disabled"` | `15000` | WebSocket connect/open handshake timeout in milliseconds for providers that support WebSocket transports. Set to `0` or `"disabled"` to disable. |
 
 ### Terminal & Images
 
@@ -242,7 +242,7 @@ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explic
 |---------|------|---------|-------------|
 | `terminal.showImages` | boolean | `true` | Show images in terminal (if supported) |
 | `terminal.imageWidthCells` | number | `60` | Preferred inline image width in terminal cells |
-| `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when content shrinks (can cause flicker) |
+| `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when content shrinks (can cause flicker). When unset, `PI_CLEAR_ON_SHRINK=1` enables it |
 | `terminal.hyperlinks` | boolean or `"auto"` | `"auto"` | Override OSC 8 hyperlink support (advanced, JSON-only) |
 | `terminal.images` | string or boolean | `"auto"` | Override image protocol support with `"kitty"`, `"iterm2"`, `false`, or `"auto"` (advanced, JSON-only) |
 | `terminal.trueColor` | boolean or `"auto"` | `"auto"` | Override truecolor support (advanced, JSON-only) |
@@ -256,6 +256,7 @@ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explic
 | `shellPath` | string | - | Custom shell path (e.g., for Cygwin on Windows); supports a leading `~` for the home directory |
 | `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"]`) |
+| `selfUpdateCommand` | string[] | - | Command argv `pi update` runs to update Pi itself, with `{packageName}`, `{version}`, and `{installSpec}` placeholders. `PI_SELF_UPDATE_COMMAND` takes precedence. Global setting only. See [Custom update command](usage.md#custom-update-command) |
 
 Windows paths in JSON must use forward slashes or escaped backslashes:
 

package/docs/terminal-setup.md

@@ -37,7 +37,7 @@ This is an iTerm2-wide workaround and may also change native trackpad scrolling.
 
 ## Apple Terminal
 
-Pi enables enhanced key reporting when available. If Terminal.app still sends plain Return for `Shift+Enter`, pi uses a local macOS modifier fallback to treat that Return as `Shift+Enter`.
+Pi enables enhanced key reporting when available. If Terminal.app still sends plain Return or `ESC` + Return for `Shift+Enter`, pi uses a local macOS modifier fallback to treat it as `Shift+Enter`. `ESC` + Return without Shift held remains `Alt+Enter`.
 
 This fallback only works when pi runs on the same Mac as Terminal.app. It cannot detect the local keyboard over remote SSH.
 
@@ -140,7 +140,7 @@ Pi uses Windows-style keybindings when running natively on Windows or in WSL:
 - `Ctrl+Z` undoes editing on native Windows; WSL uses `Alt+Z` so `Ctrl+Z` can suspend pi.
 - `Ctrl+Q` queues a follow-up message and `Alt+Q` restores queued messages.
 
-Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward `Shift+Enter` for inserting a new line:
+When pi runs natively on Windows, it checks the local Shift key state and treats plain Return or `ESC` + Return as `Shift+Enter` while Shift is held. This fallback does not work in WSL or over SSH. If `Shift+Enter` still submits, add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward it explicitly:
 
 ```json
 {

package/docs/tmux.md

@@ -61,3 +61,9 @@ This affects the default keybindings (`Enter` to submit, `Shift+Enter` for newli
 - A terminal emulator that supports extended keys (Ghostty, Kitty, iTerm2, WezTerm, Windows Terminal)
 
 With tmux 3.2 through 3.4, omit `extended-keys-format csi-u`; Pi still supports tmux's default xterm `modifyOtherKeys` format.
+
+## Known issues
+
+| Issue | Affects | Remedy |
+|---|---|---|
+| Text such as `c0c/0c0c/0c0c` appears in the editor at startup ([tmux#4749](https://github.com/tmux/tmux/issues/4749)) | tmux 3.6 | Upgrade tmux. Changing pi's theme does not help. |

package/docs/tui.md

@@ -176,6 +176,8 @@ export default function (pi: ExtensionAPI) {
 
 This component does not display a text cursor, so it does not need `Focusable`. A component containing `Input` or `Editor` must implement `Focusable` and propagate its `focused` value to that child.
 
+Custom components do not report pi as waiting for the user, because `ctx.ui.custom()` also hosts loaders and other non-blocking UI. When an inline component waits for an answer, pass `blocked: { kind: "question", message: "Pick a color" }` so terminals that support [program status](terminal-setup.md#program-status) show pi as blocked while the component is visible. `kind` is `"question"`, `"permission"`, or `"auth"`. Overlays ignore this option.
+
 ### Disposal
 
 A component returned from `ctx.ui.custom()`, `setWidget()`, `setFooter()`, or `setHeader()` may also implement `dispose(): void`. Use it to stop timers, abort owned work, and unsubscribe listeners. Pi calls it after a custom component finishes, or when a widget, footer, or header is replaced or cleared.
@@ -759,18 +761,21 @@ The factory's component is disposed when that widget key is replaced or cleared.
 
 **Examples:** [widget-placement.ts](../examples/extensions/widget-placement.ts)
 
-### Pattern 5b: Ephemeral Transcript Notes
+### Pattern 5b: Transcript Annotations
 
-Use `addTranscriptNote()` for a short display-only annotation tied to an existing session entry. Pi renders it in `dim` after that entry, including when compaction or branch navigation rebuilds the transcript. Notes are not persisted, are never sent to the model, and are cleared with the current extension UI runtime. Reusing a key is a no-op, which makes event retries safe.
+For a short display-only line in the transcript, such as how long a run took, append a custom entry and render it. The entry is saved where it was appended and never sent to the model, so the line reappears in place whenever Pi rebuilds the transcript, such as on resume or after branch navigation.
 
 ```typescript
-const afterEntryId = ctx.sessionManager.getLeafId();
-if (afterEntryId) {
-  ctx.ui.addTranscriptNote("run-summary", "Worked for 8s", { afterEntryId });
-}
+pi.registerEntryRenderer<{ seconds: number }>("run-time", (entry, { outputPad }, theme) =>
+  new Text(theme.fg("dim", `Worked for ${entry.data?.seconds}s`), outputPad, 0),
+);
+
+pi.on("agent_settled", () => {
+  pi.appendEntry("run-time", { seconds: 8 });
+});
 ```
 
-This is intended for settled annotations. It is not a replacement for widgets, footers, streaming components, or durable custom entries.
+Use widgets, footers or streaming components for content that changes while it is shown.
 
 ### Pattern 6: Custom Footer
 

package/docs/usage.md

@@ -44,7 +44,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/thinking` | Switch thinking level; Ctrl+S in the picker saves the startup default |
 | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
 | `/settings` | Theme, message delivery, transport, and other preferences |
-| `/resume` | Pick from previous sessions |
+| `/resume` | Resume another session |
 | `/new` | Start a new session |
 | `/name <name>` | Set session display name |
 | `/session` | Show session file, ID, messages, tokens, and cost |
@@ -55,7 +55,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/compact [prompt]` | Manually compact context, optionally with custom instructions |
 | `/copy` | Copy last assistant message to clipboard |
 | `/export [file]` | Export session to HTML or JSONL |
-| `/import <file>` | Import and resume a session from a JSONL file |
+| `/import <file>` | Import a JSONL session, preserving its ID and working directory |
 | `/share` | Upload as private GitHub gist with shareable HTML link |
 | `/bug [description]` | Report a bug to the Pi developers; see [Sessions](sessions.md#reporting-bugs) |
 | `/reload` | Reload keybindings, extensions, skills, prompts, themes, and context files |
@@ -163,6 +163,16 @@ To uninstall pi itself, see [Quickstart](quickstart.md#uninstall). `pi config` a
 
 See [Pi Packages](packages.md) for package sources and security notes.
 
+#### Custom update command
+
+If a wrapper or another package manager provides Pi, set `PI_SELF_UPDATE_COMMAND` so `pi update` runs its update command:
+
+```sh
+export PI_SELF_UPDATE_COMMAND="mise use -g npm:{packageName}@{version}"
+```
+
+`pi update` runs it only when the npm registry has a newer release, replacing `{packageName}`, `{version}`, and `{installSpec}` (`{packageName}@{version}`) with that release. The value is split on spaces. For arguments with spaces, use the `selfUpdateCommand` setting in `~/.pi/agent/settings.json` instead, an argv array such as `["nix", "profile", "upgrade", "pi"]`.
+
 ### Modes
 
 | Flag | Description |
@@ -201,10 +211,10 @@ cat README.md | pi -p "Summarize this text"
 
 | Option | Description |
 |--------|-------------|
-| `-c`, `--continue` | Continue the most recent session |
-| `-r`, `--resume` | Browse and select a session |
-| `--session <path\|id>` | Use a specific session file or partial UUID |
-| `--fork <path\|id>` | Fork a session file or partial UUID into a new session |
+| `-c`, `--continue` | Continue the most recent session for the current directory |
+| `-r`, `--resume` | Browse and select a session; it resumes in its own working directory. Press Tab to include sessions from other directories |
+| `--session <path\|id>` | Use a specific session file or partial UUID and resume it in its working directory. A match stored only for another directory is offered as a fork into the current directory |
+| `--fork <path\|id>` | Fork a session file or partial UUID into a new session in the current directory |
 | `--session-dir <dir>` | Custom session storage directory |
 | `--no-session` | Ephemeral mode; do not save |
 | `--name <name>`, `-n <name>` | Set session display name at startup |
@@ -365,11 +375,11 @@ These commands work outside a session, so agents can run them through `bash`. Se
 | Command | Description |
 |---|---|
 | `pi mcp add <server> [options] -- <command> [args...]` | Add or replace a stdio server in `mcp.json`; `--env KEY=VALUE` (repeatable) and `--cwd <dir>` set its environment and working directory. Arguments after the command are passed to it |
-| `pi mcp add <server> [options] --url <url>` | Add or replace a streamable HTTP server; `--header KEY=VALUE` (repeatable), `--bearer-token-env-var <NAME>` (sends `Authorization: Bearer ${NAME}`), `--oauth-client-id`, `--oauth-client-secret`, `--oauth-callback-port`, and `--oauth-client-name` configure authentication |
+| `pi mcp add <server> [options] --url <url>` | Add or replace a streamable HTTP server; `--header KEY=VALUE` (repeatable), `--bearer-token-env-var <NAME>` (sends `Authorization: Bearer ${NAME}`), `--oauth-client-id`, `--oauth-client-secret`, `--oauth-callback-port`, `--oauth-client-name`, and `--oauth-client-registration` (`auto`, `cimd`, or `dcr`) configure authentication |
 | `pi mcp remove <server>` | Remove a server from `mcp.json`; stored OAuth credentials are kept |
 | `pi mcp list [--json]` | Connect to every enabled server and print its state, tools, and errors; exit with `1` when a config entry is invalid or an enabled server is not connected |
-| `pi mcp login <server> [--timeout <seconds>]` | Sign in to an OAuth server: open the authorization page and wait for the browser (default 300 seconds); a terminal also accepts the pasted redirect URL |
-| `pi mcp logout <server>` | Delete the stored OAuth credentials of a server |
+| `pi mcp login <server> [-l] [--timeout <seconds>]` | Sign in to an OAuth server: open the authorization page and wait for the browser (default 300 seconds); a terminal also accepts the pasted redirect URL. `-l` requires the server to be defined in the project's `.pi/mcp.json` |
+| `pi mcp logout <server> [-l]` | Delete the stored OAuth credentials of a server |
 
 `add` and `remove` change `~/.pi/agent/mcp.json`, or `.pi/mcp.json` in the current directory with `--local` (`-l`). `add` also takes `--exposure <mode>` (see [Exposure](mcp.md#control-tool-exposure)) and `--description <text>` and does not connect; run `pi mcp list` to check the server.
 

package/docs/windows.md

@@ -23,6 +23,24 @@ Start Pi and enter this command to verify the shell:
 
 If Pi cannot find Bash, it reports the locations it checked. Install Git for Windows, set `shellPath`, or add Bash to `PATH`.
 
+## Choose a terminal
+
+Windows terminals run pi through a console host (conhost). Some bundle an up-to-date copy; others use the older one built into Windows, which has bugs that affect pi.
+
+We recommend [Windows Terminal](https://aka.ms/terminal). It always ships an up-to-date conhost, and pi is best tested with it.
+
+Last updated: October 2026.
+
+| Terminal | Conhost | Status |
+|---|---|---|
+| [Windows Terminal](https://aka.ms/terminal) | Bundled, current | Recommended |
+| [VS Code](https://code.visualstudio.com), [Tabby](https://tabby.sh), [WezTerm](https://wezterm.org) nightly | Bundled, current | Works |
+| [Alacritty](https://alacritty.org) | Built-in, unless `conpty.dll` and `OpenConsole.exe` from Windows Terminal are next to `alacritty.exe` | Works only with those files |
+| WezTerm 20240203 and older | Bundled, old | [Known issues](#known-issues) |
+| Classic console (`cmd.exe` or PowerShell without Windows Terminal), mintty (Git Bash), ConEmu, Cmder, [Hyper](https://hyper.is), Windows OpenSSH | Built-in | [Known issues](#known-issues) |
+
+See [Windows Terminal](terminal-setup.md#windows-terminal) to configure `Shift+Enter` and `Alt+Enter`.
+
 ## PowerShell Tool
 
 The optional `powershell` tool runs commands through `pwsh.exe` when available, otherwise Windows PowerShell. It starts PowerShell with `-NoProfile -NonInteractive -ExecutionPolicy Bypass`. Administrator-enforced execution policies can still take precedence.
@@ -67,3 +85,14 @@ When using the legacy WSL `bash.exe` launcher from Windows, Pi sends commands ov
 ```
 
 `"defaultTools": ["-bash", "+powershell"]` replaces Bash while preserving other configured default tools.
+
+## Known issues
+
+These issues come from conhost. Microsoft has fixed them in its source, but has not said when the built-in conhost will get the fixes.
+
+| Issue | Affects | Remedy |
+|---|---|---|
+| Switching from fullscreen to regular mode, or `Ctrl+G` from fullscreen, crashes the session ([#9186](https://github.com/earendil-works/pi/issues/9186), [microsoft/terminal#17515](https://github.com/microsoft/terminal/issues/17515)) | Built-in conhost | Use a terminal with a current conhost, or start pi with `--tui-mode regular` |
+| Text such as `;0;rgb:0000/0000/0000` appears in the prompt, and BEL opens the external editor ([#10256](https://github.com/earendil-works/pi/issues/10256)) | Built-in conhost behind another terminal: mintty, Windows OpenSSH | Use a terminal with a current conhost |
+| Fragments such as `79` or `55` appear in the prompt ([#10717](https://github.com/earendil-works/pi/issues/10717)) | WezTerm 20240203 | Use WezTerm nightly |
+| In regular mode, each keystroke redraws the input line on a new row ([#6300](https://github.com/earendil-works/pi/issues/6300)) | Built-in conhost, classic console | Use fullscreen mode (the default), or a terminal with a current conhost |

package/examples/extensions/README.md

@@ -23,9 +23,10 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 | `protected-paths.ts` | Blocks writes to protected paths (.env, .git/, node_modules/) |
 | `confirm-destructive.ts` | Confirms before destructive session actions (clear, switch, fork) |
 | `dirty-repo-guard.ts` | Prevents session changes with uncommitted git changes |
-| `sandbox/` | OS-level sandboxing using `@anthropic-ai/sandbox-runtime` with per-project config |
 | `gondolin/` | Route built-in tools and `!` commands into a Gondolin micro-VM |
 
+For isolation setup and limitations, see [Run Pi in an isolated environment](../../docs/containerization.md).
+
 ### Custom Tools
 
 | Extension | Description |

package/examples/extensions/custom-provider-anthropic/index.ts

@@ -42,7 +42,7 @@ import {
 	type TextContent,
 	type ThinkingContent,
 	type Tool,
-	type ToolCall,
+	ToolCallArgumentsStream,
 	type ToolResultMessage,
 	type TranscriptContext,
 } from "@earendil-works/pi-ai";
@@ -454,8 +454,9 @@ function streamCustomAnthropic(
 			const anthropicStream = client.messages.stream({ ...params }, { signal: options?.signal });
 			stream.push({ type: "start", partial: output });
 
-			type Block = (ThinkingContent | TextContent | (ToolCall & { partialJson: string })) & { index: number };
-			const blocks = output.content as Block[];
+			// Stream state per Anthropic block index, kept off the content blocks so it never reaches partial messages.
+			// ToolCallArgumentsStream reads each argument delta once and shows the arguments parsed so far.
+			const openBlocks = new Map<number, { contentIndex: number; arguments?: ToolCallArgumentsStream }>();
 
 			for await (const event of anthropicStream) {
 				if (event.type === "message_start") {
@@ -468,15 +469,12 @@ function streamCustomAnthropic(
 					calculateCost(model, output.usage);
 				} else if (event.type === "content_block_start") {
 					if (event.content_block.type === "text") {
-						output.content.push({ type: "text", text: "", index: event.index } as any);
+						output.content.push({ type: "text", text: "" });
+						openBlocks.set(event.index, { contentIndex: output.content.length - 1 });
 						stream.push({ type: "text_start", contentIndex: output.content.length - 1, partial: output });
 					} else if (event.content_block.type === "thinking") {
-						output.content.push({
-							type: "thinking",
-							thinking: "",
-							thinkingSignature: "",
-							index: event.index,
-						} as any);
+						output.content.push({ type: "thinking", thinking: "", thinkingSignature: "" });
+						openBlocks.set(event.index, { contentIndex: output.content.length - 1 });
 						stream.push({ type: "thinking_start", contentIndex: output.content.length - 1, partial: output });
 					} else if (event.content_block.type === "tool_use") {
 						output.content.push({
@@ -484,15 +482,18 @@ function streamCustomAnthropic(
 							id: event.content_block.id,
 							name: isOAuth ? fromClaudeCodeName(event.content_block.name, tools) : event.content_block.name,
 							arguments: {},
-							partialJson: "",
-							index: event.index,
-						} as any);
+						});
+						openBlocks.set(event.index, {
+							contentIndex: output.content.length - 1,
+							arguments: new ToolCallArgumentsStream(),
+						});
 						stream.push({ type: "toolcall_start", contentIndex: output.content.length - 1, partial: output });
 					}
 				} else if (event.type === "content_block_delta") {
-					const index = blocks.findIndex((b) => b.index === event.index);
-					const block = blocks[index];
-					if (!block) continue;
+					const open = openBlocks.get(event.index);
+					if (!open) continue;
+					const index = open.contentIndex;
+					const block = output.content[index]!;
 
 					if (event.delta.type === "text_delta" && block.type === "text") {
 						block.text += event.delta.text;
@@ -505,11 +506,8 @@ function streamCustomAnthropic(
 							delta: event.delta.thinking,
 							partial: output,
 						});
-					} else if (event.delta.type === "input_json_delta" && block.type === "toolCall") {
-						(block as any).partialJson += event.delta.partial_json;
-						try {
-							block.arguments = JSON.parse((block as any).partialJson);
-						} catch {}
+					} else if (event.delta.type === "input_json_delta" && block.type === "toolCall" && open.arguments) {
+						block.arguments = open.arguments.append(event.delta.partial_json);
 						stream.push({
 							type: "toolcall_delta",
 							contentIndex: index,
@@ -520,20 +518,19 @@ function streamCustomAnthropic(
 						block.thinkingSignature = (block.thinkingSignature || "") + (event.delta as any).signature;
 					}
 				} else if (event.type === "content_block_stop") {
-					const index = blocks.findIndex((b) => b.index === event.index);
-					const block = blocks[index];
-					if (!block) continue;
+					const open = openBlocks.get(event.index);
+					if (!open) continue;
+					openBlocks.delete(event.index);
+					const index = open.contentIndex;
+					const block = output.content[index]!;
 
-					delete (block as any).index;
 					if (block.type === "text") {
 						stream.push({ type: "text_end", contentIndex: index, content: block.text, partial: output });
 					} else if (block.type === "thinking") {
 						stream.push({ type: "thinking_end", contentIndex: index, content: block.thinking, partial: output });
-					} else if (block.type === "toolCall") {
-						try {
-							block.arguments = JSON.parse((block as any).partialJson);
-						} catch {}
-						delete (block as any).partialJson;
+					} else if (block.type === "toolCall" && open.arguments) {
+						// One full parse of the complete text; malformed arguments are reported in `argumentsError`.
+						Object.assign(block, open.arguments.finish());
 						stream.push({ type: "toolcall_end", contentIndex: index, toolCall: block, partial: output });
 					}
 				} else if (event.type === "message_delta") {
@@ -563,7 +560,6 @@ function streamCustomAnthropic(
 			stream.push({ type: "done", reason: output.stopReason, message: output });
 			stream.end();
 		} catch (error) {
-			for (const block of output.content) delete (block as any).index;
 			output.stopReason = options?.signal?.aborted ? "aborted" : "error";
 			output.errorMessage = error instanceof Error ? error.message : JSON.stringify(error);
 			stream.push({ type: "error", reason: output.stopReason, error: output });

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "1.4.0",
+      "version": "1.5.0",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/debug-provider.ts

@@ -6,7 +6,7 @@
  * as expandable custom entries.
  */
 
-import { type ExtensionAPI, keyHint } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
 
 const ENTRY_TYPE = "debug-provider-events";
@@ -24,7 +24,7 @@ export default function (pi: ExtensionAPI) {
 	let activeEvents: unknown[] | undefined;
 	let completedEntry: ProviderDebugEntry | undefined;
 
-	pi.registerEntryRenderer<ProviderDebugEntry>(ENTRY_TYPE, (entry, { expanded }, theme) => {
+	pi.registerEntryRenderer<ProviderDebugEntry>(ENTRY_TYPE, (entry, { expanded, keyHint }, theme) => {
 		const data = entry.data;
 		if (!data) return new Text(theme.fg("warning", "[provider debug] Missing event data"), 0, 0);