@astralyn/pi 0.87.5 → 0.99.0

package/docs/rpc.md

@@ -70,7 +70,7 @@ If the agent is streaming and no `streamingBehavior` is specified, the command r
 
 Response:
 ```json
-{"id": "req-1", "type": "response", "command": "prompt", "success": true}
+{"id": "req-1", "type": "response", "command": "prompt", "success": true, "data": {"disposition": "started"}}
 ```
 
 `success: true` means the prompt was accepted, queued, or handled immediately. `success: false` means the prompt was rejected before acceptance. Failures after acceptance are reported through the normal event and message stream, not as a second `response` for the same request id.
@@ -94,7 +94,7 @@ The `images` field is optional. Each image uses `ImageContent` format (same as `
 
 Response:
 ```json
-{"type": "response", "command": "steer", "success": true}
+{"type": "response", "command": "steer", "success": true, "data": {"disposition": "queued"}}
 ```
 
 See [set_steering_mode](#set_steering_mode) for controlling how steering messages are processed.
@@ -116,7 +116,7 @@ The `images` field is optional. Each image uses `ImageContent` format (same as `
 
 Response:
 ```json
-{"type": "response", "command": "follow_up", "success": true}
+{"type": "response", "command": "follow_up", "success": true, "data": {"disposition": "queued"}}
 ```
 
 See [set_follow_up_mode](#set_follow_up_mode) for controlling how follow-up messages are processed.
@@ -1651,3 +1651,5 @@ process.on("SIGINT", () => {
     agent.stdin.write(JSON.stringify({ type: "abort" }) + "\n");
 });
 ```
+
+Successful `prompt` responses include `data.disposition`: `handled`, `queued`, or `started`. `steer` and `follow_up` return `handled` or `queued`. This describes the submitted input, not completion. When an extension handles input, do not wait for a run to settle on its behalf.

package/docs/sdk.md

@@ -111,8 +111,8 @@ interface AgentSession {
   abort(): Promise<void>;
 
   // Background host controls (see Background execution below)
-  pauseBackgroundNotifications(): () => void;
-  retryBackgroundNotifications(): void;
+  pauseTaskNotifications(): () => void;
+  retryTaskNotifications(): void;
   getSessionStats(): SessionStats;
 
   // Cleanup (does not await Background draining)
@@ -273,15 +273,15 @@ Both `steer()` and `followUp()` expand file-based prompt templates but error on
 
 ### Background execution
 
-Background is a session-owned capability, not a daemon or a flag on `createAgentSession()`. Interactive mode enables it. Ordinary SDK sessions and the built-in print, JSON, and RPC hosts leave it disabled and reject native shell or Subagent calls with `background: true`. Normal foreground tools still work, including standalone `createBashTool()` / `createPowerShellTool()` calls without a session context.
+Background is a session-owned capability, not a daemon or a flag on `createAgentSession()`. Interactive mode enables it. Ordinary SDK sessions and the built-in print, JSON, and RPC hosts leave it disabled and reject native shell or extension calls with `background: true`. Normal foreground tools still work, including standalone `createBashTool()` / `createPowerShellTool()` calls without a session context.
 
-An embedding can opt in with `await session.bindExtensions({ backgroundEnabled: true })`. Bind before prompting; this also binds extensions and emits their session-start lifecycle. When using `AgentSessionRuntime`, rebind the replacement session through the runtime's rebind callback. Setting `mode` or providing a UI alone does not enable Background.
+An embedding can opt in with `await session.bindExtensions({ tasksEnabled: true })`. Bind before prompting; this also binds extensions and emits their session-start lifecycle. When using `AgentSessionRuntime`, rebind the replacement session through the runtime's rebind callback. Setting `mode` or providing a UI alone does not enable Background.
 
 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.background.kill(id)` for a whole execution, or `await session.background.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.pauseBackgroundNotifications()` 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.
-- **Observation and delivery:** `session.background` exposes the [public supervision methods](extensions.md#ctxbackground). `read()` and `wait()` observe; a terminal snapshot alone does not acknowledge model delivery. The bundled `bg wait` result carries `details.backgroundTaskId`, which the host acknowledges only after persisting the tool result. A direct SDK waiter that consumes the result outside model history can explicitly call `session.background.markDelivered(task.id)` after successful consumption. A timeout or cancelled wait does not stop the execution. Failed notification delivery leaves the result available for inspection; after fixing the host failure, call `session.retryBackgroundNotifications()` explicitly. Pi does not retry a failed delivery forever on a timer.
+- **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.
+- **Observation and delivery:** `session.tasks` exposes the [public supervision methods](extensions.md#ctxtasks). `read()` and `wait()` observe; a terminal snapshot alone does not acknowledge model delivery. The built-in `tasks wait` tool binds a delivery receipt to its tool-call ID; the host confirms it only after persisting the result, even if extensions rewrite its details. A direct SDK waiter that consumes the result outside model history can explicitly call `session.tasks.markDelivered(task.id)` after successful consumption. A timeout or cancelled wait does not stop the execution. 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.
 
 A deliberately single-turn embedding can suppress completion-triggered turns and cancel leftover work on exit:
@@ -292,14 +292,14 @@ import { createAgentSession, SessionManager } from "@astralyn/pi";
 const { session } = await createAgentSession({
   sessionManager: SessionManager.inMemory(),
 });
-const resumeNotifications = session.pauseBackgroundNotifications();
+const resumeNotifications = session.pauseTaskNotifications();
 try {
-  await session.bindExtensions({ backgroundEnabled: true });
+  await session.bindExtensions({ tasksEnabled: true });
   await session.prompt("Inspect the project; delegate independent investigations if useful.");
   // Snapshot only: some executions may still be running.
-  console.log(session.background.list());
+  console.log(session.tasks.list());
 } finally {
-  await Promise.all([session.background.shutdown(), session.abort()]);
+  await Promise.all([session.tasks.shutdown(), session.abort()]);
   session.dispose();
   resumeNotifications();
 }
@@ -307,19 +307,19 @@ try {
 
 For a longer-lived embedding, keep the host alive, subscribe to snapshots and choose bounded waits or release notification delivery according to your model-turn policy. Do not use a panel or repeated reads as the billing or cleanup mechanism.
 
-Automatic completion messages carry a version-1 `BackgroundCompletionSnapshot` in `details`, with independent shell output or worker reports, diagnostics and explicit truncation flags. This snapshot is self-contained for transcript replay and is not sent to the model; `content` contains the separately bounded prose generated from it. Current terminal history uses version-2 `background-task-result` records, with no migration of earlier result records. The usage ledger remains independent. See [Background records](session-format.md#background-records).
+Automatic completion messages carry a version-1 `TaskCompletionSnapshot` in `details`, with independent shell output or worker reports, diagnostics and explicit truncation flags. This snapshot is self-contained for transcript replay and is not sent to the model; `content` contains the separately bounded prose generated from it. Current terminal history uses version-2 `task-result` records, with no migration of earlier result records. The usage ledger remains independent. See [Background records](session-format.md#background-records).
 
-`executionRole: "subagent"` on `createAgentSession()` is a trusted host-assigned identity, not a model argument. It prevents enabling Background even through `bindExtensions`; built-in workers also receive a no-background prompt rule. Their shared shell schema retains the optional flag but runtime requests for `background: true` are rejected before startup. Foreground shell access remains normal. 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` 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.
 
-Reload, replacement/fork, shutdown and branch navigation enforce the [Background lifetime rules](bundled/extensions/background.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.
+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.
 
-An executor that ignores abort and settles after its originating runtime/branch has been retired is quarantined, not charged to the active session. The old session exposes the latest 32 bounded records through `quarantinedBackgroundSettlements`; persisted sessions also attempt to append them to `<session-file>.background-late.jsonl`, reporting a diagnostic if the write fails. This is an audit trail, not automatic reconciliation or a promise that the executor stopped. See [Background records](session-format.md#background-records).
+An executor that ignores abort and settles after its originating runtime/branch has been retired is quarantined, not charged to the active session. The old session exposes the latest 32 bounded records through `quarantinedTaskSettlements`; persisted sessions also attempt to append them to `<session-file>.tasks-late.jsonl`, reporting a diagnostic if the write fails. This is an audit trail, not automatic reconciliation or a promise that the executor stopped. See [Background records](session-format.md#background-records).
 
 ### Session statistics
 
 `session.getSessionStats()` returns `sessionFile`, `sessionId`, `userMessages`, `assistantMessages`, `toolCalls`, `toolResults`, `totalMessages`, `tokens`, `cost`, and optional `contextUsage`. `tokens` contains `input`, `output`, `cacheRead`, `cacheWrite`, and `total` (the sum of those four categories); `cost` is accumulated reported cost.
 
-Usage totals cover all session entries, including other branches and compacted history: assistant requests, usage-bearing tool results, compaction/branch summaries, and the first valid `background-usage` record per execution ID. Managed foreground results omit duplicate usage. Background records do not increment message/tool counts, and reads, waits, handoff and history restoration do not add billing. Worker retry, failure, cancellation and compaction usage is included when supplied; missing provider usage is not fabricated. Quarantined late settlements are excluded.
+Usage totals cover all session entries, including other branches and compacted history: assistant requests, usage-bearing tool results, compaction/branch summaries, and the first valid `task-usage` record per execution ID. Managed foreground results omit duplicate usage. Background records do not increment message/tool counts, and reads, waits, handoff and history restoration do not add billing. Worker retry, failure, cancellation and compaction usage is included when supplied; missing provider usage is not fabricated. Quarantined late settlements are excluded.
 
 This differs from the bundled Statusline's active-branch totals. Neither accumulated worker usage nor Background billing changes the parent context-occupancy estimate or the latest parent request's cache-hit ratio.
 
@@ -1261,3 +1261,13 @@ type PromptTemplate
 ```
 
 For extension types, see [extensions.md](extensions.md) for the full API.
+
+## Codemode and MCP
+
+<a id="codemode-mcp"></a>
+
+The CLI loads `codemode`, `tool_search`, and MCP as built-in extensions. SDK sessions do not; add `createCodemodeExtension()`, `createToolSearchExtension()`, and `createMcpExtension()` to the `extensionFactories` of `DefaultResourceLoader`. `codemode` and `tool_search` are registered inactive: enable them through the `defaultTools` setting (`["+codemode", "+tool_search"]` keeps the other default tools), or let the MCP extension activate them: `codemode` for servers with `codemode` or `codemode-deferred` exposure, `tool_search` for servers with `deferred` exposure. The MCP extension connects its servers on `session_start`, so call `session.bindExtensions()`. See [Codemode and MCP](../examples/sdk/14-codemode-mcp.ts).
+
+Named inline extensions accept `builtin: true` to load as `builtin:<name>`, with user/project configuration and `noExtensions` support. `replaceable: true` lets another extension replace one when its tool, command, or flag names overlap.
+
+`steer()` and `followUp()` return `"queued"` when queued or `"handled"` when an extension consumes the input.

package/docs/security.md

@@ -57,3 +57,7 @@ If you bind-mount a host workspace read/write, writes from inside the container
 For issues that also affect upstream Pi, follow the [upstream security policy](https://github.com/earendil-works/pi/blob/main/SECURITY.md). This distribution does not operate a separate security-reporting process.
 
 Expected local-agent behavior, lack of a built-in sandbox, prompt injection from untrusted content, and behavior of user-installed extensions or skills are generally outside the security boundary unless the report demonstrates a real privilege-boundary bypass or shows how pi grants access that the local user did not already have.
+
+## MCP configuration
+
+Project `.pi/mcp.json` requires project trust before its servers are loaded. Trust permits stdio server commands to run. Global servers are configured in `~/.pi/agent/mcp.json`. See [MCP Servers](mcp.md).

package/docs/session-format.md

@@ -339,30 +339,30 @@ Managed execution uses ordinary version-3 custom entries; it does not add a new
 
 | `customType` | `data` | Purpose |
 |---|---|---|
-| `background-usage` | `{ version: 1, taskId, usage }` | Independent settlement of provider-reported nested usage |
-| `background-task-result` | `{ version: 2, task }` | Bounded terminal `BackgroundTask` snapshot with structured presentation |
+| `task-usage` | `{ version: 1, taskId, usage }` | Independent settlement of provider-reported nested usage |
+| `task-result` | `{ version: 2, task }` | Bounded terminal `TaskSnapshot` snapshot with structured presentation |
 
 `taskId` is the execution/group ID, not a worker display number. `usage` has the `Usage` shape above. Consumers count only the first valid usage record per ID within the entries they aggregate; malformed records, unsupported versions, blank IDs, and non-finite or negative usage/cost values are ignored. A later valid duplicate is not an adjustment. Do not create these host-owned entries yourself or bill again from a result/read/notification.
 
-A `BackgroundTask` has `id`, `kind` (`bash` or `subagent`; PowerShell shares the shell kind), `title`, `toolCallId`, `anchorId`, `mode`, `status`, and numeric millisecond `startedAt`; optional fields include `endedAt`, `command`, `commandTruncated`, `cwd`, `outputPath`, `projection`, `result`, `resultTruncated`, and `error`. Truncation flags record clipping at the producing/retention boundary. Mode (`foreground` or `background`) is independent of status. Persisted terminal statuses are `completed`, `partial`, `failed`, `cancelled`, or `timeout`; live snapshots can also be `queued`, `running`, or `stopping`.
+A `TaskSnapshot` has `id`, `kind` (executor-owned source label, such as `bash`, `powershell`, or an extension-defined label), `format` (`log` or `report`), `title`, `toolCallId`, `anchorId`, `mode`, `status`, and numeric millisecond `startedAt`; optional fields include `endedAt`, `command`, `commandTruncated`, `cwd`, `outputPath`, `projection`, `result`, `resultTruncated`, and `error`. Truncation flags record clipping at the producing/retention boundary. Mode (`foreground` or `background`) is independent of status. Persisted terminal statuses are `completed`, `partial`, `failed`, `cancelled`, or `timeout`; live snapshots can also be `queued`, `running`, or `stopping`.
 
-`projection` contains optional bounded status `text`, `shell: { name, output: { text, truncated } }`, and worker summaries. Each worker has `id`, `label`, `profile`, `description`, observed `status`, `report: { text, truncated }`, optional `error`, plus live `prompt`, `activity`, and optional `model`/`usage` display strings. The projection has no worker sessions or execution handles. Source truncation is explicit; the reader never recognizes truncation by matching output text.
+`projection` contains optional bounded status `text`, `shell: { name, output: { text, truncated } }`, and report items. Each item has `id`, `label`, `category`, `description`, observed `status`, `report: { text, truncated }`, optional `error`, plus live `input`, `activity`, and optional `context`/`usage` display strings. The projection has no worker sessions or execution handles. Source truncation is explicit; the reader never recognizes truncation by matching output text.
 
-The retained tool result contains bounded text (up to 48 KiB) and bounded serializable private details (up to 120 KiB, otherwise omitted); images are replaced with a text omission marker. Completion cards use the public projection independently of those private details. `outputPath`, if present, points to an ephemeral executor-owned file which may already have been removed on eviction or runtime shutdown. Save important output separately.
+The retained tool result contains bounded text (up to 48 KiB) and no executor-private details; images are replaced with a text omission marker. Completion cards use the public projection independently of those private details. `outputPath`, if present, points to an ephemeral executor-owned file which may already have been removed on eviction or runtime shutdown. Save important output separately.
 
 Terminal history is restored only from the selected branch's valid version-2 result records. Version-1 result records are ignored without migration; their independent usage entries still participate in accounting. This is read-only history: no processes or workers are restarted or reattached, and restoration does not replay usage settlement or completion events. Forks can carry historical entries on their copied path, never live execution handles.
 
-These `custom` entries do not enter model context. Automatic delivery creates a `custom_message` with `customType: "background-completion"`, `display: true`, and a self-contained `BackgroundCompletionSnapshot` in `details`. The session formats `content` from the same snapshot, with a total limit of 48 KiB and 2,000 lines. Each worker gets a share before formatting, so an early report cannot erase later workers. Only `content` is sent to the model.
+These `custom` entries do not enter model context. Automatic delivery creates a `custom_message` with `customType: "task-completion"`, `display: true`, and a self-contained `TaskCompletionSnapshot` in `details`. The session formats `content` from the same snapshot, with a total limit of 48 KiB and 2,000 lines. Each worker gets a share before formatting, so an early report cannot erase later workers. Only `content` is sent to the model.
 
 Completion details use one format, `version: 1`, bounded to 120 KiB of serialized JSON including escaping:
 
 | Part | Fields |
 |---|---|
 | Common | `version`, `taskId`, `title`, terminal `status`, numeric millisecond `startedAt` and `endedAt`, optional `error` |
-| `kind: "bash"` | `output: { text, truncated }`; optional `shell` name, `command: { text, truncated }`, `cwd`, `outputPath` |
-| `kind: "subagent"` | `workers[]` with `id`, `label`, `profile`, `description`, observed `status`, `report: { text, truncated }`, optional `error`; optional plain `output` fallback for executors without a worker projection |
+| `format: "log"` | `output: { text, truncated }`; optional `shell` name, `command: { text, truncated }`, `cwd`, `outputPath` |
+| `format: "report"` | `items[]` with `id`, `label`, `category`, `description`, observed `status`, `report: { text, truncated }`, optional `error`; optional plain `output` fallback for executors without a worker projection |
 
-Shell output is bounded to 40 KiB, each worker report to 4 KiB, and worker count to eight. Field limits include JSON escaping; source flags survive further clipping. Completion worker snapshots omit live prompt/activity/model/usage fields. Missing shell metadata is left unspecified, and worker status is never inferred from the group verdict. The renderer sanitizes terminal control sequences and applies separate display row limits.
+Shell output is bounded to 40 KiB, each worker report to 4 KiB, and worker count to eight. Field limits include JSON escaping; source flags survive further clipping. Completion item snapshots omit live input/activity/context/usage fields. Missing shell metadata is left unspecified, and worker status is never inferred from the group verdict. The renderer sanitizes terminal control sequences and applies separate display row limits.
 
 A shell completion's `details` can look like this:
 
@@ -371,6 +371,7 @@ A shell completion's `details` can look like this:
   "version": 1,
   "taskId": "bash-12345678-abcd-4321-abcd-123456789012",
   "kind": "bash",
+  "format": "log",
   "title": "Build",
   "status": "completed",
   "startedAt": 1733234400000,
@@ -385,11 +386,11 @@ A shell completion's `details` can look like this:
 
 The message carries everything needed for replay after `/reload`, branch navigation, history eviction or restart; rendering does not open the saved log or query a live task. Unsupported or malformed completion details use bounded plain message text. There is no legacy text parser, dual-format reconstruction or migration.
 
-A completion is acknowledged only after its message is persisted. A terminal `bg wait` result instead includes `details.backgroundTaskId`; only persisting that tool result acknowledges delivery, so aborting during an output read cannot consume a notification. Direct `BackgroundContext.wait()` is observational. Snapshots and repeated reads do not create more usage. Historical extension-owned `background-task` notifications and old `bg create` tool results remain transcript history, not new runnable tasks.
+A completion is acknowledged only after its message is persisted. A terminal `tasks wait` binds a host-owned receipt to the tool-call ID. Only persisting that tool result acknowledges delivery, even if its details were rewritten; aborting during an output read cannot consume a notification. Direct `TasksContext.wait()` is observational. Snapshots and repeated reads do not create more usage. Historical extension-owned `background-task` notifications and old `bg create` tool results remain transcript history, not new runnable tasks.
 
 Session-wide statistics aggregate the ledger across all entries; the bundled Statusline uses the active branch. Accrued retries, failures, cancellations and worker compaction count when usage is reported. No usage is invented for a provider that does not expose it, and worker billing does not occupy the parent's context window. See [SDK session statistics](sdk.md#session-statistics).
 
-**Late settlement quarantine:** an executor that ignores cancellation and settles after its runtime or launch branch is retired cannot append to the replacement session or move its active leaf. The originating session retains the latest 32 bounded quarantine records in memory. For persisted sessions it also appends audit JSONL to `<session-file>.background-late.jsonl`, with `{ version: 1, sessionId, generation, task, usage? }`. A sidecar write failure is reported and leaves only the bounded in-memory record. This sidecar is separate from the session tree and active totals; it is not automatically reconciled, replayed or used to resume execution. Preserve it if you need to audit late provider costs, and manage its disk retention separately from the session file.
+**Late settlement quarantine:** an executor that ignores cancellation and settles after its runtime or launch branch is retired cannot append to the replacement session or move its active leaf. The originating session retains the latest 32 bounded quarantine records in memory. For persisted sessions it also appends audit JSONL to `<session-file>.tasks-late.jsonl`, with `{ version: 1, sessionId, generation, task, usage? }`. A sidecar write failure is reported and leaves only the bounded in-memory record. This sidecar is separate from the session tree and active totals; it is not automatically reconciled, replayed or used to resume execution. Preserve it if you need to audit late provider costs, and manage its disk retention separately from the session file.
 
 ### CustomMessageEntry
 
@@ -572,3 +573,9 @@ All of these return the appended entry ID:
 - `getSessionName(): string | undefined`
 - `getCwd(): string`, `getSessionDir(): string`, `getSessionId(): string`, and `getSessionFile(): string | undefined`
 - `usesDefaultSessionDir(): boolean` and `isPersisted(): boolean`
+
+## Virtual selections and nested calls
+
+The latest `model_change` records the selected model, including a [virtual model](virtual-models.md). Assistant messages record the physical model that answered and its `thinkingLevel`. Router state is stored in custom entries named `pi.virtual-model-state` with `{ provider, modelId, state }`.
+
+Tool results can include bounded `nestedCalls` metadata for calls made through `ctx.executeTool()`. It records arguments and execution status, never nested results; compaction and HTML exports use it.

package/docs/settings.md

@@ -77,7 +77,7 @@ Selecting a model or thinking level with Enter changes only the current session.
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
-| `theme` | string | `"dark"` | Theme name (`"dark"`, `"light"`, or custom) |
+| `theme` | string | `"system"` | Theme name (`"system"`, `"dark"`, `"light"`, bundled ice-cream themes, or custom) |
 | `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 | `false` | Hide startup header |
 | `defaultProjectTrust` | string | `"ask"` | Fallback project trust behavior: `"ask"`, `"always"`, or `"never"`. Global setting only |
@@ -285,7 +285,7 @@ Windows paths in JSON must use forward slashes or escaped backslashes:
 |---------|------|---------|-------------|
 | `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. Available built-ins are `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, and `ls`:
+`defaultTools` selects tools enabled at startup; plain names replace the selection, while `+name` and `-name` modify it. It can also activate `codemode`, `tool_search`, and other inactive extension tools. Extension and SDK custom tools remain enabled. Available built-ins are `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, and `ls`:
 
 ```json
 {
@@ -427,3 +427,27 @@ Project settings (`.pi/settings.json`) override global settings. Nested objects
   "compaction": { "enabled": true, "triggerPercent": 70 }
 }
 ```
+
+## Codemode and tool selection
+
+A list of only `+name` and `-name` entries changes the inherited selection instead of replacing it. For example, this enables `codemode` next to the default tools:
+
+```json
+{
+  "defaultTools": ["+codemode"]
+}
+```
+
+This replaces `bash` with `powershell` and enables `grep`: `["-bash", "+powershell", "+grep"]`. Project settings apply on top of user settings: a project list with only `+name` and `-name` entries changes the user's selection, and a project list with a plain name replaces it. In one list, plain names form the selection, and `+name` and `-name` then apply in order.
+
+CLI tool options override this setting for one invocation; `--tools` does not accept `+name` or `-name`. See [Command Line](usage.md#tools).
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `codemode.mode` | `"on"` | `on` keeps direct tool declarations; `only` hides callable tools from direct model access and lists them in codemode |
+| `codemode.inlineBudget` | `3000` | Estimated tokens for inline tool declarations; scripts discover the rest with `searchTools()` |
+| `fullscreenWheelScrollLines` | `"auto"` | 1–100 lines per wheel event, or automatic acceleration; Alt+wheel moves five times as far |
+
+Built-in extensions can be disabled in `pi config` or with `"extensions": ["-builtin:mcp"]`. Project `+builtin:<name>` and `-builtin:<name>` entries override user settings. `--no-extensions` disables built-ins too; `-e builtin:mcp` loads one explicitly.
+
+MCP servers live in `~/.pi/agent/mcp.json` or trusted project `.pi/mcp.json`; see [MCP Servers](mcp.md).

package/docs/themes.md

@@ -18,7 +18,7 @@ Themes are JSON files that define colors for the TUI.
 
 Pi loads themes from:
 
-- Built-in: `dark`, `light`, `ice-cream-dark`, `ice-cream-light`
+- Built-in: `system`, `dark`, `light`, `ice-cream-dark`, `ice-cream-light`
 - Global: `~/.pi/agent/themes/*.json`
 - Project: `.pi/themes/*.json` (only after the project is trusted)
 - Packages: `themes/` directories or `pi.themes` entries in `package.json`
@@ -37,7 +37,7 @@ Select a theme via `/settings` or in `settings.json`:
 }
 ```
 
-On first run, pi detects your terminal background and defaults to `dark` or `light`.
+Without a saved theme setting, Pi uses `system`, which follows the terminal palette and appearance.
 
 ### Initial Theme
 
@@ -158,7 +158,8 @@ vim ~/.pi/agent/themes/my-theme.json
 }
 ```
 
-- `name` is required, must be unique, and must not contain `/`.
+- `name` is required, must be unique, must not contain `/`, and cannot be `system`.
+- `appearance` is optional: `"dark"` or `"light"`. Pi detects it from the colors when omitted.
 - `vars` is optional. Define reusable colors here, then reference them in `colors`.
 - `colors` must define all 51 required tokens. `thinkingMax`, `scrollbarThumb`, and the two search highlight tokens are optional and use the fallbacks listed below.
 
@@ -276,11 +277,13 @@ The `export` section controls colors for `/export` HTML output. If omitted, colo
 
 ## Color Values
 
-Four formats are supported:
+Six formats are supported:
 
 | Format | Example | Description |
 |--------|---------|-------------|
-| Hex | `"#ff0000"` | 6-digit hex RGB |
+| Hex | `"#f00"` or `"#ff0000"` | 3- or 6-digit hex RGB |
+| OKLCH | `"oklch(62% 0.1 200)"` | Perceptual lightness, chroma, and hue |
+| OKHSL | `"okhsl(250 60% 55%)"` | Hue, saturation, and lightness within the sRGB gamut |
 | 256-color | `39` | xterm 256-color palette index (0-255) |
 | Variable | `"primary"` | Reference to a `vars` entry |
 | Default | `""` | Terminal's default color |
@@ -318,3 +321,22 @@ echo $COLORTERM  # Should output "truecolor" or "24bit"
 The built-in themes are selected by name: `dark`, `light`, `ice-cream-dark`, and `ice-cream-light`. When inspecting an installed package, their JSON assets are under `node_modules/@astralyn/pi/dist/modes/interactive/theme/` (the global-install equivalent is under Pi's npm package directory).
 
 The ice-cream palette and bundled design notes are documented in [Bundled themes](bundled/themes.md).
+
+## Use your terminal's colors
+
+The `system` theme is the default. It builds Pi's colors from your terminal's theme, so Pi matches the terminal instead of bringing its own palette:
+
+- Pi queries the terminal's default foreground and background colors and its 16 ANSI colors.
+- Each Pi color takes its hue from one ANSI color, for example errors from red and links from blue.
+- Pi sets each color's lightness so that it stands out from the background by a minimum contrast. Body text keeps at least a 4.5:1 WCAG contrast ratio on the background and every panel.
+- When the terminal switches between light and dark, Pi queries the colors again and rebuilds the theme.
+
+The theme adapts to what the terminal reports:
+
+| Terminal reports | Result |
+|---|---|
+| Background and ANSI colors | Colors from the terminal palette, placed for the actual background. |
+| Background only | Pi's own hues, placed for the actual background. |
+| Nothing | ANSI color indices and the terminal's default colors, which the terminal renders itself. Secondary text is faint, and panels have no background color. |
+
+Pi asks the terminal for its colors when it starts. Terminals usually answer within a few milliseconds, and Pi waits at most 100 ms before showing the startup header. If the terminal does not answer in time, Pi uses the ANSI color fallback, and it still applies the colors if they arrive later, for example over a slow SSH connection. `system` is a reserved name: a custom theme with that name is ignored.

package/docs/tui.md

@@ -829,3 +829,23 @@ PI_TUI_WRITE_LOG=/tmp/tui-ansi.log pi
 
 - **Game loop and disposal:** [examples/extensions/snake.ts](../examples/extensions/snake.ts)
 - **Custom tool rendering:** [examples/extensions/todo.ts](../examples/extensions/todo.ts)
+
+## Combined theme styles
+
+Use `theme.style()` to combine foreground and background colors with text attributes:
+
+```typescript
+return new Text(
+  theme.style("Done!", {
+    fg: "success",
+    bg: "toolSuccessBg",
+    bold: true,
+  }),
+  0,
+  0,
+);
+```
+
+A style color can be a semantic theme token or a concrete `Color`. Foreground tokens are accepted as `fg` and background tokens as `bg`; to use a token's color in the other position, pass its concrete color, for example `{ fg: theme.colors.userMessageBg }`. Access concrete colors through `theme.colors` and use utilities such as `mixColors()` from `@earendil-works/pi-tui` when color math is needed. Tokens that a theme sets to the terminal default render with the terminal's own color; `theme.colors` reports the color the terminal announced for them, or a guess when it did not. Use `theme.appearance` (`"dark"` or `"light"`) to decide, for example, whether to lighten or darken a color. Pi converts the result to truecolor or 256-color output based on terminal capabilities. Theme tokens are converted once per theme; compute concrete colors outside the render path when possible.
+
+The existing `theme.fg()` and `theme.bg()` helpers remain available for applying one semantic color.

package/docs/usage.md

@@ -38,6 +38,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 |---------|-------------|
 | `/login`, `/logout` | Manage OAuth or API-key credentials |
 | [`/llama`](llama-cpp.md) | Download, load, and unload llama.cpp router models |
+| [`/mcp`](mcp.md) | Manage MCP servers, authentication, tools, and resources |
 | [`/btw [question]`](bundled/extensions/btw.md) | Open a temporary side conversation using the current context |
 | `/model` | Switch models; Ctrl+S in the picker saves the startup default |
 | `/thinking` | Switch thinking level; Ctrl+S in the picker saves the startup default |
@@ -219,8 +220,8 @@ Built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`,
 
 | Option | Description |
 |--------|-------------|
-| `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
-| `--no-extensions` | Disable extension discovery |
+| `-e`, `--extension <source>` | Load an extension from path, npm, git, or `builtin:<name>`; repeatable |
+| `--no-extensions` | Disable discovered, configured, and built-in extensions; explicit `-e` entries still load |
 | `--skill <path>` | Load a skill; repeatable |
 | `--no-skills` | Disable skill discovery |
 | `--prompt-template <path>` | Load a prompt template; repeatable |
@@ -305,6 +306,63 @@ pi --exclude-tools ask_question
 
 Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages.
 
-This distribution ships selected workflows as hidden built-in extensions, including sub-agents, to-dos, and background bash tasks. It does not include built-in MCP or permission popups. You can build or install additional workflows as extensions or packages, or use external tools such as containers and tmux.
+Upstream Pi provides the llama.cpp integration, codemode, MCP, and tool search. This distribution adds Tasks, BTW, Todo, other workflow extensions, and its native tool presentation. See the [feature catalog](bundled/README.md) for their origins and usage. You can build or install additional workflows as extensions or packages.
 
 For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).
+
+## Codemode and tool search
+
+Codemode and tool search are built-in extensions from [upstream Pi](https://github.com/earendil-works/pi), included in `@astralyn/pi`. Both tools are inactive by default; enable them explicitly or let the MCP extension activate them when needed.
+
+### Enable codemode
+
+To turn on `codemode` for every session, add it to the default tools in `~/.pi/agent/settings.json` or a project's `.pi/settings.json`:
+
+```json
+{
+  "defaultTools": ["+codemode"]
+}
+```
+
+This keeps `read`, `bash`, `edit`, and `write` and adds `codemode`. For one invocation, list every tool, since `--tools` replaces the selection:
+
+```sh
+pi --tools read,bash,edit,write,codemode
+```
+
+Codemode is useful without MCP: scripts can run several tool calls in parallel, filter large output before it reaches the model, and call classifier models such as TypeSafe's Jev through `models.classify()` (see [Classifier models](models.md#use-classifier-models)).
+
+### How codemode works
+
+Codemode scripts run in a QuickJS sandbox that can only reach the other tools, through `tools.<name>(args)`; `ALL_TOOLS` lists them. Output comes from `text(value)`, `image(dataUrlOrImageContent)`, `console.*`, and a top-level `return value`; `exit()` ends the script early. The result starts with `Script completed` or `Script failed`, the wall time, and the output; a failed script keeps its partial output, followed by `Script error:` and the error.
+
+A script may start with an options line such as `// @options: {"max_output_tokens": 2000, "timeout_ms": 60000}`. `max_output_tokens` (default 10000) limits the output: longer output keeps its start and end, and the full text is written to a temp file whose path is included in the result. `timeout_ms` is a hard deadline, unset by default.
+
+While `codemode` is active, `codemode.mode` in [settings](settings.md#tools) decides how the other tools are presented. With `on` (default) declared tools keep being declared and their descriptions show how to call them from scripts. With `only` they are hidden from the model and listed in the `codemode` description instead, so the model calls them through scripts.
+
+The `codemode` description lists the callable tools with their TypeScript declarations, grouped by namespace (for example one MCP server). Declarations share a budget of 3000 estimated tokens (`codemode.inlineBudget` in [settings](settings.md#tools)); every namespace is still listed with its tool count, and the description says whether the list is complete. Scripts find the rest with `await searchTools(query, { limit, namespace })`, which ranks tools with BM25, and `await describeTool(name)`, or by filtering `ALL_TOOLS`.
+
+Tools with an output schema resolve to structured values: `bash` to `{ output, truncated, full_output_path?, exit_code, wall_time_seconds }`, also for non-zero exit codes, and MCP tools to their `CallToolResult`. Other tools resolve to their text output. The `output` of `bash` is not limited to the 2000 lines or 50KB the model sees: it holds up to 1 MiB, and longer output keeps its first and last 512 KiB around an omission marker, with `truncated` set and the full output in `full_output_path`.
+
+`store(key, value)` and `load(key)` keep JSON values across `codemode` calls: each successful script that stores values appends a `codemode-store` custom entry to the session, so resumed sessions keep the values and each branch sees only the values written on its path. Scripts can also use `models`: `getModelsOfType`, `getAvailableOfType`, and `getModelOfType` list the model catalog, and `classify(model, context)` runs a classifier model with the session's credentials, at most four at a time per script.
+
+### Tool search
+
+`tool_search` is off by default; enable it with `"defaultTools": ["+tool_search"]` or `--tools`. It uses the same ranking as `searchTools()` over tools that are not declared yet and declares the matches for the next model call. Loaded tools are recorded in the session like other tool changes, so they stay declared on that branch.
+
+## MCP commands
+
+These commands work outside a session, so agents can run them through `bash`. See [MCP Servers](mcp.md).
+
+| 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`, and `--oauth-callback-port` 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 |
+
+`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#exposure)) and does not connect; run `pi mcp list` to check the server.
+
+Project `.pi/mcp.json` files are only read for projects that are already trusted.

package/docs/virtual-models.md

@@ -0,0 +1,114 @@
+# Virtual Models
+
+A virtual model is a selectable model that picks a physical model for each request. Use one to route by task, cost, or conversation state. For example, a router can send quick questions to a small model and hard problems to a large one, while the user selects a single model.
+
+Register virtual models from an [extension](extensions.md). They appear in `/model`, `--model`, scoped models, and settings like any other model. A virtual model can be listed under any provider, including one with physical models, such as `openai-codex/auto`.
+
+## Selection and dispatch
+
+A virtual model selects a model and a thinking level. A router maps that pair to a physical pair for each request:
+
+```
+selected (virtual model, virtual level)  ->  dispatched (physical model, physical level)
+jev/auto:low                             ->  anthropic/claude-sonnet-4-5:high
+```
+
+The virtual thinking level is an input to the router. Its meaning is up to the router; it need not correspond to a reasoning budget.
+
+Pi keeps the two pairs apart:
+
+| | Selection | Dispatch |
+|---|---|---|
+| Recorded in | `model_change` and `thinking_level_change` entries | Each assistant message: `provider`, `api`, `model`, `thinkingLevel` |
+| Visible as | `ctx.model`, `ctx.thinkingLevel`, `PI_MODEL`, `PI_REASONING_LEVEL`, `/model` | The assistant message of each response |
+
+Providers only receive physical models. Assistant messages name the physical model, so replaying a conversation across different physical models works the same as after a manual model switch. Resuming a session restores the virtual selection from its latest `model_change` entry. If the virtual model is no longer registered, Pi falls back to the physical model that answered last.
+
+In interactive mode, the footer shows the routed model next to the selection, for example `auto • high → gpt-5.6-luna • medium`. `/session` lists the cost for each physical model.
+
+Context usage uses the limits of the physical model that produced the latest response, even if that response came before switching to the virtual model. Without such a response, it uses the limits declared on the virtual model, if any. Compaction checks the same limits, and again the limits of the model each request is routed to. If that model's context window is too small for the conversation, Pi compacts before sending the request; the route stays as the router chose it.
+
+## Register a virtual model
+
+```typescript
+import type { ExtensionAPI } from "@astralyn/pi";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerVirtualModel({
+    provider: "router",
+    id: "auto",
+    name: "Auto",
+    thinkingLevels: ["low", "high"],
+    route(request, ctx) {
+      // Tool follow-ups and retries stay on the model that handled the turn.
+      const sticky = request.failed ?? request.previous;
+      if (request.reason !== "user" && sticky) {
+        return { model: sticky.model, thinkingLevel: sticky.thinkingLevel ?? "medium" };
+      }
+      const id = request.thinkingLevel === "high" ? "claude-sonnet-4-5" : "claude-haiku-4-5";
+      return { model: ctx.modelRegistry.find("anthropic", id)!, thinkingLevel: "medium" };
+    },
+  });
+}
+```
+
+- `provider` is the provider the model is listed under. It can be any provider ID. A provider can list several virtual models next to its physical ones. On a physical provider, the virtual model is available when that provider has credentials. Under an ID that no provider uses, it is always available.
+- `id` must not be the ID of a physical model of that provider. If a catalog refresh later adds a physical model with the same ID, the virtual model hides it.
+- `thinkingLevels` lists the levels offered for selection. It defaults to `["off"]`.
+- `contextWindow` and `maxTokens` are shown before the first response. Unset limits are unknown.
+- `input` lists the input types offered for selection. It defaults to text and images; physical models without image support receive placeholders.
+
+Registration follows the same queuing and reload rules as `pi.registerProvider()`. Registering the same provider and ID again replaces the virtual model. `pi.unregisterVirtualModel(provider, id)` removes it; `pi.unregisterProvider()` does not. SDK code can register one without an extension: `modelRuntime.registerVirtualModel(definition)`.
+
+## Route requests
+
+`route(request, ctx)` runs before every request made with the virtual model and returns `{ model, thinkingLevel }`. The model can be any physical model in the catalog whose provider has credentials; look it up with `ctx.modelRegistry`. A virtual model cannot route to another virtual model. Pi clamps the thinking level to the returned model.
+
+| Field | Meaning |
+|---|---|
+| `model`, `thinkingLevel` | The selected virtual model and level |
+| `reason` | Why the request is made, see below |
+| `previous` | Physical model and thinking level of the latest successful response in `messages` |
+| `failed` | For `retry`: physical model, thinking level, and assistant `message` of the failed request, which `messages` no longer contains. The message carries `stopReason` and `errorMessage`. Absent when routing itself failed |
+| `state` | Router state last returned on this session branch, see below |
+| `messages` | The conversation for this request, including system messages |
+| `signal` | Abort signal of the request |
+
+| `reason` | Request |
+|---|---|
+| `user` | First request after a message the user wrote, including steering and follow-up messages |
+| `continuation` | Any other request in the agent loop, such as after tool results or extension messages |
+| `retry` | Automatic retry after a failed request, including after compaction for a context overflow |
+| `direct` | Request made outside the agent loop, such as a compaction summary or an extension calling `ctx.modelRegistry.streamSimple()` |
+
+Returning `previous` for `continuation` and `failed` for `retry` keeps prompt caches and thinking signatures valid. Switching models between turns is allowed but loses the prompt cache. A retry can also switch to another model, for example when `failed.message.errorMessage` reports that a provider is overloaded or the context overflowed.
+
+If `route()` throws, or returns a virtual model or a model without credentials, the request ends with an error response.
+
+## Keep routing state
+
+`route()` can return `state` next to the model. Pi stores it on the session branch and passes it back as `request.state` on later requests. Use it for decisions the transcript does not record, such as classifier results or a routing phase:
+
+```typescript
+pi.registerVirtualModel<{ phase: "plan" | "build" }>({
+  provider: "router",
+  id: "phased",
+  name: "Phased",
+  route(request, ctx) {
+    const state = request.state ?? { phase: "plan" };
+    const id = state.phase === "plan" ? "claude-opus-4-5" : "claude-haiku-4-5";
+    return { model: ctx.modelRegistry.find("anthropic", id)!, thinkingLevel: "medium", state };
+  },
+});
+```
+
+- State must be JSON-serializable. Returning `undefined` or `request.state` itself keeps the current state.
+- Pi stores any other returned object as new state, before the request is sent, even when it equals the current state. Return a new object only when the state changes. The state stays stored if the request later fails.
+- State follows the session tree, so forks and `/tree` navigation see the state of their branch. It survives compaction.
+- `direct` requests have no state, and Pi ignores state they return.
+
+The transcript already records the selection and every dispatched model, and `ctx.sessionManager.getBranch()` exposes both.
+
+Routers can call other models through `ctx.modelRegistry`, for example `ctx.modelRegistry.classify()` with a classifier model from `ctx.modelRegistry.findOfType("classifier", provider, id)`. The call adds latency before the first token of the turn.
+
+See [`jev-router.ts`](../examples/extensions/jev-router.ts) for a complete router. It plans on a strong OpenAI Codex model chosen by the Jev classifier, lets that model make the first edit, and then switches once to a cheaper model, accepting a single prompt-cache miss. It keeps the phase as router state.

package/docs/windows.md

@@ -37,3 +37,5 @@ The `!` and `!!` editor commands still use Bash.
   "shellPath": "C:\\cygwin64\\bin\\bash.exe"
 }
 ```
+
+`"defaultTools": ["-bash", "+powershell"]` replaces Bash while preserving other configured default tools.

package/examples/README.md

@@ -10,7 +10,7 @@ Runs one prompt through a Pi RPC child process with the typed `RpcClient`: it st
 Build the package before running it from a repository checkout:
 
 ```bash
-npx tsx examples/rpc-client.ts "Explain this repository"
+node examples/rpc-client.ts "Explain this repository"
 ```
 
 ### [rpc-extension-ui.ts](rpc-extension-ui.ts)

package/examples/extensions/README.md

@@ -113,6 +113,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 |-----------|-------------|
 | `message-renderer.ts` | Custom message rendering with colors and expandable details via `registerMessageRenderer` |
 | `entry-renderer.ts` | TUI-only session entry rendering via `appendEntry` and `registerEntryRenderer` |
+| `debug-provider.ts` | Toggle raw provider stream capture with `/debug-provider` and inspect each assistant message in a TUI-only session entry |
 | `event-bus.ts` | Inter-extension communication via `pi.events` |
 
 ### Session Metadata
@@ -128,6 +129,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 |-----------|-------------|
 | `custom-provider-anthropic/` | Custom Anthropic provider with OAuth support and custom streaming implementation |
 | `custom-provider-gitlab-duo/` | GitLab Duo provider using pi-ai's built-in Anthropic/OpenAI streaming via proxy |
+| `jev-router.ts` | Virtual model via `registerVirtualModel` that plans on Codex Sol or Terra (picked by the Jev classifier) and switches to Luna after the first edit |
 
 ### External Dependencies