@counterposition/skill-pi 1.2.0 → 1.4.0

package/README.md

@@ -28,7 +28,7 @@ If you develop inside this repo, Pi already loads the skill via `.pi/settings.js
 
 ## What this covers
 
-Pi's architecture and package layout. Skill authoring, discovery, and routing. Extensions, tools, and UI hooks. MCP servers, codemode, and nested tool calls. Settings, models, providers, classifiers, and packages. Sessions, forks, and compaction. The SDK and RPC interface. Checked against Pi 1.2.0.
+Pi's architecture and package layout. Skill authoring, discovery, and routing. Extensions, tools, and UI hooks. MCP servers, codemode, and nested tool calls. Settings, models, providers, classifiers, and packages. Sessions, forks, and compaction. The SDK and RPC interface. Checked against Pi 1.4.0.
 
 The reference material lives in `references/` as task-specific documents — not a single monolith, but pieces sized for injection into a conversation when relevant.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@counterposition/skill-pi",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Pi coding agent reference skill — extensions, settings, providers, SDK/RPC, packages, and .pi/ config",
   "keywords": [
     "ai-skill",
@@ -30,8 +30,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^1.2.0",
-    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-ai": "^1.4.0",
+    "@earendil-works/pi-coding-agent": "^1.4.0",
     "@types/node": "^25.5.0",
     "typebox": "^1.3.16",
     "typescript": "^6.0.2",

package/skills/pi/README.md

@@ -28,7 +28,7 @@ If you develop inside this repo, Pi already loads the skill via `.pi/settings.js
 
 ## What this covers
 
-Pi's architecture and package layout. Skill authoring, discovery, and routing. Extensions, tools, and UI hooks. MCP servers, codemode, and nested tool calls. Settings, models, providers, classifiers, and packages. Sessions, forks, and compaction. The SDK and RPC interface. Checked against Pi 1.2.0.
+Pi's architecture and package layout. Skill authoring, discovery, and routing. Extensions, tools, and UI hooks. MCP servers, codemode, and nested tool calls. Settings, models, providers, classifiers, and packages. Sessions, forks, and compaction. The SDK and RPC interface. Checked against Pi 1.4.0.
 
 The reference material lives in `references/` as task-specific documents — not a single monolith, but pieces sized for injection into a conversation when relevant.
 

package/skills/pi/SKILL.md

@@ -7,7 +7,7 @@ compatibility: "Pi-specific guidance for agents that support Agent Skills"
 
 # Pi Coding Agent
 
-Pi is a minimal terminal coding harness. Default tools: `read`, `bash`, `edit`, `write`; `grep`, `find`, `ls`, and the Windows `powershell` tool are opt-in via the `defaultTools` setting or `--tools`. Built-in extensions (Pi 0.99.0) add MCP servers, the `codemode` tool (model-written JavaScript that calls other tools), and `tool_search`. `codemode` and `tool_search` start inactive: enable them with `defaultTools`/`--tools`, or let MCP activate them when a server needs them. Modes: interactive (`pi`), print (`pi -p`), JSON (`--mode json`), RPC (`--mode rpc`), or embedded (`createAgentSession()`). Sub-agents, plan mode, and permission flows are intentionally left to extensions and Pi packages. Skill synced with Pi 1.2.0.
+Pi is a minimal terminal coding harness. Default tools: `read`, `bash`, `edit`, `write`; `grep`, `find`, `ls`, and the Windows `powershell` tool are opt-in via the `defaultTools` setting or `--tools`. Built-in extensions (Pi 0.99.0) add MCP servers, the `codemode` tool (model-written JavaScript that calls other tools), and `tool_search`. `codemode` and `tool_search` start inactive: enable them with `defaultTools`/`--tools`, or let MCP activate them when a server needs them. Modes: interactive (`pi`), print (`pi -p`), JSON (`--mode json`), RPC (`--mode rpc`), or embedded (`createAgentSession()`). Sub-agents, plan mode, and permission flows are intentionally left to extensions and Pi packages. Skill synced with Pi 1.4.0.
 
 Pi's philosophy: **adapt Pi to your workflows, not the other way around**.
 

package/skills/pi/references/codemode.md

@@ -1,6 +1,6 @@
 # Codemode and Tool Search
 
-`codemode` is a built-in tool (Pi 0.99) that runs model-written JavaScript in a QuickJS sandbox. Scripts call Pi's other tools, filter their results, and return only what the model needs. `tool_search` declares tools the model cannot see yet. Checked against Pi v1.2.0: [codemode.md](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/codemode.md), [cli.md#tools](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/cli.md#tools), [extensions.md#tool-exposure](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/extensions.md#tool-exposure), [settings.md#tools](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/settings.md#tools), [codemode tool source](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/src/extensions/codemode/tool.ts).
+`codemode` is a built-in tool (Pi 0.99) that runs model-written JavaScript in a QuickJS sandbox. Scripts call Pi's other tools, filter their results, and return only what the model needs. `tool_search` declares tools the model cannot see yet. Checked against Pi v1.4.0: [codemode.md](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/codemode.md), [cli.md#tools](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/cli.md#tools), [extensions.md#tool-exposure](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/extensions.md#tool-exposure), [settings.md#tools](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/settings.md#tools), [codemode tool source](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/src/extensions/codemode/tool.ts).
 
 ## Enable
 
@@ -31,10 +31,11 @@ The script body is an async function: top-level `await` and `return` work.
 - Output: `text(value)`, `image(dataUrlOrImageContent)`, `console.*`, and the returned value. Since Pi 0.99.2 `image()` accepts only base64 PNG, JPEG, GIF, or WebP (a `data:` URL, `{ image_url }`, or an image block); it derives the MIME type from the image bytes, rejects remote URLs, and throws a `TypeError` for anything else, such as an SVG. Since Pi 1.0.3 it also saves each image to a temp file and names the path in the result, so a later turn can copy or move it. `exit()` ends early and keeps output.
 - `store(key, value)` / `load(key)` keep JSON values across `codemode` calls (storing `undefined` deletes). Successful scripts append a `codemode-store` custom entry, so values follow the session branch. Limits: 262144 characters of JSON per value, 1048576 in total; do not store image data.
 - `models.getModelsOfType`, `getAvailableOfType`, `getModelOfType`, `models.classify(model, { state, questions })`, and `models.generateImages(model, { input })` (Pi 1.0.0) reach the model catalog, classifiers, and image models with session credentials. Both calls use only the model's `provider` and `id`, never throw on provider errors (check `stopReason`), and run at most four at a time per script. Their usage and cost are added to the `codemode` result. Show generated images with `image(block)` rather than printing `data`; generation can take minutes, so avoid a short `timeout_ms`.
-- `models.classify()` also takes `images` (Pi 1.1.0): image blocks judged with the state, for classifiers whose `input` includes `"image"`, such as `openai/gpt-6-luna`. Other classifiers return an error result. `await tools.read({ path })` on an image file resolves to such a block (Pi 1.0.4).
+- `models.classify()` also takes `images` (Pi 1.1.0): image blocks judged with the state, for classifiers whose `input` includes `"image"`: `openai/gpt-6-luna` and, since Pi 1.4.0, Jev, Clef, and OpenRouter classifiers that list image input (see `references/providers.md`). Other classifiers return an error result. `await tools.read({ path })` on an image file resolves to such a block (Pi 1.0.4).
 - Malformed `classify()`/`generateImages()` arguments are rejected with the expected shape, and an unknown model points to `models.getAvailableOfType()`.
 - An optional first line `// @options: {"max_output_tokens": 2000, "timeout_ms": 60000}`. It must be the first line: since Pi 1.2.0 an options line anywhere else fails the call before the script runs. Output is capped at 10000 estimated tokens by default (start and end kept, full text in a temp file); there is no timeout unless set. Since Pi 1.0.1 a script fails with a `RangeError` once its output passes 16777216 characters (text plus base64 image data) or 100000 `text()`/`image()`/`console` calls; write large data to a file with a tool.
 - No timers, `fetch`, `process`, `require`, or modules. The VM has 256 MB of memory; a script awaiting a promise that can never settle fails at once; scripts cannot start other `codemode` scripts.
+- At most two codemode workers are alive at once across all sessions in one Pi process (Pi 1.3.0); a cancelled worker holds its slot until it exits. Since Pi 1.4.0 further scripts wait for a free worker in arrival order instead of failing, and fail without running after 60 seconds or their `timeout_ms`. `PI_CODEMODE_MAX_WORKERS` raises the limit, for example for in-process subagents.
 
 The result starts with `Script completed` or `Script failed`, the wall time, and the output. Since Pi 1.1.0, with more than one text item each starts with a `==> text N/M <==` line, and `console` calls follow the other output in one `<console_output>` block, one line per call. A failed script keeps its partial output followed by `Script error:`.
 
@@ -94,4 +95,4 @@ For a permission extension this means:
 - `codemode` uses only `exposure`, `prepareLoadout()`, and `ctx.executeTool()`, and `tool_search` only ranks registered tools (`pi.getAllTools()`) and adds matches with `pi.setActiveTools()`, so an extension can build either under another name.
 - A replacement should declare `reachesTools` (Pi 1.2.0, see `references/extensions.md`): only then does Pi activate it for MCP servers and wait for the servers its calls need.
 
-`@earendil-works/pi-codemode` publishes the sandbox (`CodemodeSandbox`) without Pi dependencies, for exposing any functions to model-written scripts. Since Pi 1.2.0 its `/portable` entry adds sandboxes with the same API for Cloudflare Workers and other runtimes without worker threads.
+`@earendil-works/pi-codemode` publishes the sandbox (`CodemodeSandbox`) without Pi dependencies, for exposing any functions to model-written scripts. Since Pi 1.2.0 its `/portable` entry adds sandboxes with the same API for Cloudflare Workers and other runtimes without worker threads. Breaking in Pi 1.3.0: results and `close()` settle once shutdown is requested, not when the worker exits; a host that must count workers until they exit uses the `onWorkerStarted(exited)` callback or reserves capacity with `acquireWorker()`.

package/skills/pi/references/extensions.md

@@ -25,6 +25,7 @@ import { Text } from "@earendil-works/pi-tui";
 
 - Use `typebox` (1.x) for schemas. Pi 0.83.0 bundles TypeBox 1.3.7, which removed deprecated APIs (`Type.Base`, `Type.Awaited`, `Type.Promise`, `Type.AsyncIterator`, `Type.Iterator`, `Type.Options`, `Value.Mutate`) — migrate extension sources off those before typechecking against current Pi.
 - Use `StringEnum` from `@earendil-works/pi-ai` for Google-compatible string enums.
+- Since Pi 1.4.0 extensions can import `@earendil-works/pi-ai/models` (for example `clampThinkingLevel`); earlier the extension loader could not resolve that subpath.
 - Pi 0.80.0 moved pi-ai's old global API (`getModel`, `getModels`, `stream`, `complete`, `registerApiProvider`, ...) off the pi-ai root entrypoint to `@earendil-works/pi-ai/compat`. Extensions keep working unchanged at runtime (the extension loader aliases the root to the compat superset), but extension sources that typecheck against pi-ai's published types must import those APIs from `@earendil-works/pi-ai/compat`. `StringEnum` and the type surface remain on the root. The compat entrypoint and loader alias will be removed in a future release.
 
 ## Quick Start
@@ -101,7 +102,7 @@ Useful agent events:
 - `message_end` — return a replacement message to override usage/cost or rewrite the finalized assistant message
 - `context` — transforms conversation messages; since Pi 0.87.0 handlers no longer see prompt/tool system messages, and Pi restores that state afterward (filtering or slicing messages is safe)
 - `context_with_system` (Pi 0.87.0) — runs after `context` on the full transcript including system messages and is sent verbatim; use only when a request-local transform must own the whole transcript, and keep a system message at index 0
-- `before_provider_headers` (Pi 0.80.4) — mutate `event.headers` in place after outgoing HTTP headers are assembled: set a key to a string to add/override, `null` to delete. Runs once per provider request; retries reuse the same headers
+- `before_provider_headers` (Pi 0.80.4) — mutate `event.headers` in place after outgoing HTTP headers are assembled: set a key to a string to add/override, `null` to delete. Runs once per provider request; retries reuse the same headers. Since Pi 1.4.0 handlers no longer see the OpenRouter, NVIDIA NIM, and OpenCode attribution headers, which pi-ai adds from its client identity; setting one to `null` still removes it
 - `before_provider_request`
 - `after_provider_response` — inspect the provider HTTP status and headers before stream consumption
 - `provider_stream_event` (Pi 0.99.0) — notification-only view of each parsed provider stream event before Pi normalizes it (`provider`, `api`, `model`, `data`). Treat `data` as read-only; handlers are awaited in stream order, so keep them fast. Not persisted
@@ -194,7 +195,7 @@ Important rules:
 
 ## Tool Exposure & Structured Results
 
-Pi 0.99.0 added fields for tools that other tools, codemode scripts, and permission extensions consume ([docs](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/extensions.md#tool-exposure), [types](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/src/core/extensions/types.ts)):
+Pi 0.99.0 added fields for tools that other tools, codemode scripts, and permission extensions consume ([docs](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/extensions.md#tool-exposure), [types](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/src/core/extensions/types.ts)):
 
 - `outputSchema` (TypeBox) plus `structuredContent` on every result: the model still reads `content`; codemode scripts receive `structuredContent` instead of text. Without `outputSchema`, scripts get the text. `structuredContent` must be JSON-compatible. A `tool_result` handler that replaces `content` must also return `structuredContent`, or it is dropped.
 - `isError: true` on a returned result: the model sees an error, while `details` and `structuredContent` are kept for the UI and scripts.
@@ -217,7 +218,7 @@ Pi 0.80.7 lets an extension register many tools while keeping only a small initi
 3. During loader execution, call `pi.setActiveTools([...pi.getActiveTools(), ...matches])`. Unknown names are ignored. Additive changes are the most cache-friendly everywhere.
 4. Pi records the added tools on that tool result and exposes their definitions before the next model response. Since Pi 0.86.0 prompt and tool changes are transcript-backed system messages, so they survive resume and branch navigation.
 
-Adding tools keeps the cached prompt prefix on models that support native tool changes, which Pi's generated `compat` metadata marks (recent Claude, GPT, and Kimi models). On Anthropic's own API, Opus 4.8+, Sonnet and Haiku 5.5, and Fable 5+ use the `inline-tools-2026-09-15` beta (Pi 1.0.1), so removals and same-name redefinitions keep the prefix too. Any change a model cannot take natively falls back to a checkpoint with the full tool list: activation still works, but may invalidate the cached prefix. pi-ai's `hasToolRedefinitions()` is deprecated.
+Adding tools keeps the cached prompt prefix on models that support native tool changes, which Pi's generated `compat` metadata marks (recent Claude, GPT, and Kimi models). On Anthropic's own API, Opus 4.8+, Sonnet and Haiku 5.5, and Fable 5+ use the `inline-tools-2026-09-15` beta (Pi 1.0.1), so removals and same-name redefinitions keep the prefix too. Since Pi 1.4.0 OpenAI Responses models with `additional_tools` declare every tool in those items and announce removals as text, so removals and redefinitions keep the prefix there as well. Any change a model cannot take natively falls back to a checkpoint with the full tool list: activation still works, but may invalidate the cached prefix. pi-ai's `hasToolRedefinitions()` is deprecated.
 
 Cache tips: keep the loader active for the whole session; add rather than replace. Activating a tool that has `promptSnippet`/`promptGuidelines` rebuilds the system prompt and can invalidate the prefix even with native support — lazily loaded tools should rely on their `description` alone.
 
@@ -250,6 +251,8 @@ Context carries `messageType` (`"user" | "assistant" | "assistant-thinking"`), `
 
 Check `ctx.hasUI` first. Non-interactive modes may not support UI.
 
+In interactive mode, a `select`/`confirm`/`input`/`editor` dialog or inline `custom()` component opened while another is visible shows on top, and closing it shows the previous one again (Pi 1.4.0). Before, the second replaced the first and the first promise never settled, so tools running in parallel could hang on their prompts.
+
 ```typescript
 const choice = await ctx.ui.select("Pick one:", ["A", "B"]);
 const ok = await ctx.ui.confirm("Delete?", "This cannot be undone");

package/skills/pi/references/mcp.md

@@ -1,6 +1,6 @@
 # MCP Servers
 
-Pi connects to MCP servers through a built-in extension. There is no package to install. Checked against Pi v1.2.0: [mcp.md](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/mcp.md), [cli.md#mcp-commands](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/cli.md#mcp-commands), [extensions.md#mcp-servers](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/extensions.md#mcp-servers).
+Pi connects to MCP servers through a built-in extension. There is no package to install. Checked against Pi v1.4.0: [mcp.md](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/mcp.md), [cli.md#mcp-commands](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/cli.md#mcp-commands), [extensions.md#mcp-servers](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/extensions.md#mcp-servers).
 
 ## Configure
 

package/skills/pi/references/packages.md

@@ -96,7 +96,7 @@ If there is no `pi` manifest, Pi auto-discovers:
 
 ## Dependencies
 
-Checked against Pi v1.2.0 [packages.md](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/packages.md#declare-dependencies).
+Checked against Pi v1.4.0 [packages.md](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/packages.md#declare-dependencies).
 
 - Normal runtime dependencies belong in `dependencies`
 - Pi supplies these to extensions; declare them as peer deps with `"*"` ranges and never bundle them:
@@ -110,7 +110,7 @@ Checked against Pi v1.2.0 [packages.md](https://github.com/earendil-works/pi/blo
 - Git package installs omit dev dependencies — runtime needs go in `dependencies`, not `devDependencies`
 - Installed packages load with separate module roots. Do not rely on two packages sharing one dependency instance, or on one package resolving another package's undeclared dependency.
 - Other Pi packages used as dependencies must be included in the published tarball and referenced through their `node_modules` resource paths.
-- Pin dev dependencies to the Pi line you test against (e.g. `^1.2.0`) so typecheck/tests validate against what users run; keep peers `"*"` so installs stay compatible across Pi versions. `"*"` does not prove compatibility: document the minimum supported Pi version and feature-check newer APIs (for example `ctx.executeTool`, `pi.registerMcpServer`) if you support older hosts.
+- Pin dev dependencies to the Pi line you test against (e.g. `^1.4.0`) so typecheck/tests validate against what users run; keep peers `"*"` so installs stay compatible across Pi versions. `"*"` does not prove compatibility: document the minimum supported Pi version and feature-check newer APIs (for example `ctx.executeTool`, `pi.registerMcpServer`) if you support older hosts.
 
 ## Package Filtering
 

package/skills/pi/references/providers.md

@@ -49,7 +49,7 @@ Since Pi 0.80.8, built-in catalogs are complemented by dynamic ones: `/model` re
 | Fireworks | `FIREWORKS_API_KEY` | `fireworks` |
 | Together AI | `TOGETHER_API_KEY` | `together` |
 | Baseten | `BASETEN_API_KEY` | `baseten` |
-| Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` |
+| Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` (Chat Completions since Pi 1.3.0; base URL overrides must include `/v1`) |
 | Meta (Muse) | `META_API_KEY` | `meta` |
 | MiniMax | `MINIMAX_API_KEY` | `minimax` |
 | MiniMax (China) | `MINIMAX_CN_API_KEY` | `minimax-cn` |
@@ -157,7 +157,7 @@ export GOOGLE_CLOUD_LOCATION=us-central1
 
 ## Custom Providers via `models.json`
 
-Use `models.json` for OpenAI-compatible, Anthropic-compatible, Google-compatible, or other supported APIs:
+Use `models.json` for OpenAI-compatible, Anthropic-compatible, Google-compatible, or other supported APIs. Every provider, model, override, and `compat` field is listed in [models-configuration.md](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/models-configuration.md) (Pi 1.4.0):
 
 ```json
 {
@@ -211,13 +211,13 @@ Common `api` values:
 - `modelOverrides` applies to built-in and (since Pi 0.80.4) extension-registered provider models; per-model fields: `name`, `reasoning`, `thinkingLevelMap`, `input`, `cost` (partial), `contextWindow`, `maxTokens`, `samplingParams`, `samplingParamsByThinkingLevel` (Pi 1.0.2), `headers`, `compat`, `inputLimits`, `promptCache`.
 - `inputLimits.images.resize` (Pi 0.87.0) sets per-model cache-safe image encoding — `maxWidth`, `maxHeight`, `maxBytes` (base64 payload), `jpegQuality`; defaults 2000×2000, 4.5 MiB, quality 80 — applied once to attachments, `read` images, and tool-result images (switching models does not re-encode history).
 - `promptCache: { short?, long? }` (Pi 0.86.0) declares best-effort cache lifetimes in seconds per retention tier; models without a lifetime for the active tier are not eligible for cache warming (see `cacheWarming` in `references/settings.md`).
-- `compat.allowedFallbackModels` (Pi 0.86.0) overrides or disables Anthropic server-side fallback models; `compat.supportsMidConvoEffort` (Pi 0.84.4) marks custom Anthropic Messages models that accept per-turn effort changes.
+- `compat.allowedFallbackModels` (Pi 0.86.0) overrides or disables Anthropic server-side fallback models; `compat.supportsMidConvoEffort` (Pi 0.84.4) marks custom Anthropic Messages models that accept per-turn effort changes; on `openai-responses` (Pi 1.3.0, default `false`) it sends thinking level changes as `configuration_update` input items so they keep the prompt cache, and Sign in with ChatGPT ignores it.
 - OpenAI-compatible local servers: `vllmPriority` and `supportsMaxOutputTokens` (Pi 0.85.0) plus configurable thinking-token budget fields for vLLM, Qwen/SGLang, and llama.cpp (Pi 0.84.3).
 - `openRouterRouting` is forwarded as-is in the OpenRouter `provider` field (fallbacks, ZDR, ignore lists, throughput/latency).
 - `compat.thinkingFormat` supports OpenAI-compatible reasoning variants: `openrouter` sends `reasoning: { effort }`, `together` sends `reasoning: { enabled }` plus `reasoning_effort` when supported, `qwen-chat-template` targets local Qwen-compatible servers that read `chat_template_kwargs.enable_thinking`, `chat-template` (Pi 0.79.9) sends configurable `chat_template_kwargs` via `compat.chatTemplateKwargs` — e.g. `{ "thinking": { "$var": "thinking.enabled" } }` for DeepSeek models behind vLLM/Hugging Face chat templates — and `baseten` (Pi 0.84.0) sends `chat_template_args` via `compat.chatTemplateArgs`.
 - **Breaking (Pi 0.80.7):** `compat.sendSessionIdHeader` was removed. Session affinity is now controlled by `compat.sessionAffinityFormat` (`"openai"` sends `session_id`/`x-client-request-id`, `"openai-nosession"` omits the underscore-containing `session_id` header, `"openrouter"` sends `x-session-id`; default auto-detected). Replace `sendSessionIdHeader: false` with `sessionAffinityFormat: "openai-nosession"`. `sendSessionAffinityHeaders` still gates the behavior for `openai-completions`.
 - The `compat.supportsMidConvo*`, `supportsToolSearch`, and `supportsAdditionalTools` flags enable native tool changes; set them only for verified custom endpoints (see `references/extensions.md#dynamic-tool-loading`). `compat.supportsStrictTools` / `compat.supportsOpenAIGrammarTools` / per-model `constrainedSampling` gate constrained sampling (see `references/extensions.md`). `compat.supportsFinishReason: false` (Pi 0.84.0) tells pi to infer stop/toolUse for OpenAI-compatible streams that omit `finish_reason`.
-- Advanced `compat` flags exist for proxy quirks (`cacheControlFormat` — now also covering tool-result text content, `supportsReasoningEffort`, `supportsLongCacheRetention`, `supportsEagerToolInputStreaming`, `supportsStrictMode`). See [Pi `docs/models.md`](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/models.md) when a proxy rejects pi's defaults.
+- Advanced `compat` flags exist for proxy quirks (`cacheControlFormat` — now also covering tool-result text content, `supportsReasoningEffort`, `supportsLongCacheRetention`, `supportsEagerToolInputStreaming`, `supportsStrictMode`). See [Pi `docs/models.md`](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/models.md) when a proxy rejects pi's defaults.
 
 ### Context Overflow Recovery
 
@@ -225,11 +225,11 @@ Pi can auto-compact and retry when a provider fails with a recognized context-wi
 
 ### llama.cpp
 
-Pi supports the llama.cpp router server (Pi 0.81.0): configure with `/login llama.cpp`, search/download Hugging Face models and load/unload with live progress via `/llama`, then select loaded models in `/model`. The model catalog persists across restarts (fixed in Pi 0.82.1). Every llama.cpp chat model is also listed as a classifier model (see [Classifier Models](#classifier-models)). Since Pi 1.1.0, decision models such as Julia-1, Laya, Kev, lev, and OpenJev served by llama.cpp 0.6.0+ are listed only as classifiers, answering natively through `/v1/systemone` with the `typesafe-system-one` API. `"extensions": ["-builtin:llama.cpp"]` removes the provider and `/llama`. See [Pi `docs/llama-cpp.md`](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/llama-cpp.md).
+Pi supports the llama.cpp router server (Pi 0.81.0): configure with `/login llama.cpp`, search/download Hugging Face models and load/unload with live progress via `/llama`, then select loaded models in `/model`. The model catalog persists across restarts (fixed in Pi 0.82.1). Every llama.cpp chat model is also listed as a classifier model (see [Classifier Models](#classifier-models)). Since Pi 1.1.0, decision models such as Julia-1, Laya, Kev, lev, and OpenJev served by llama.cpp 0.6.0+ are listed only as classifiers, answering natively through `/v1/systemone` with the `typesafe-system-one` API. `"extensions": ["-builtin:llama.cpp"]` removes the provider and `/llama`. See [Pi `docs/llama-cpp.md`](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/llama-cpp.md).
 
 ## Model Types
 
-Since Pi 0.99.0 catalogs hold typed models: `type` is `"chat"` (the default when omitted), `"image"`, or `"classifier"`. Chat-facing reads (`getModels()`, `getAvailable()`, `ctx.modelRegistry.getAll()`, `/model`) stay chat-only. `ModelRuntime`, `ctx.modelRegistry`, and pi-ai `Models` all have `getModelsOfType(type, provider?)`, `getModelOfType(type, provider, id)`, and async `getAvailableOfType(type, provider?)`. Only `ModelRuntime` and `Models` have `getAllModels()` and `getAllAvailable()` for every type; `ctx.modelRegistry` adds `findOfType(type, provider, id)` instead. pi-ai exports `isModelType()` and `getModelType()` for mixed lists. One upstream ID may have separate chat and image entries. Sources: [models.md](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/models.md#use-classifier-models), [pi-ai types](https://github.com/earendil-works/pi/blob/v1.2.0/packages/ai/src/types.ts).
+Since Pi 0.99.0 catalogs hold typed models: `type` is `"chat"` (the default when omitted), `"image"`, or `"classifier"`. Chat-facing reads (`getModels()`, `getAvailable()`, `ctx.modelRegistry.getAll()`, `/model`) stay chat-only. `ModelRuntime`, `ctx.modelRegistry`, and pi-ai `Models` all have `getModelsOfType(type, provider?)`, `getModelOfType(type, provider, id)`, and async `getAvailableOfType(type, provider?)`. Only `ModelRuntime` and `Models` have `getAllModels()` and `getAllAvailable()` for every type; `ctx.modelRegistry` adds `findOfType(type, provider, id)` instead. pi-ai exports `isModelType()` and `getModelType()` for mixed lists. One upstream ID may have separate chat and image entries. Sources: [models.md](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/models.md#use-classifier-models), [pi-ai types](https://github.com/earendil-works/pi/blob/v1.4.0/packages/ai/src/types.ts).
 
 ### Classifier Models
 
@@ -238,11 +238,11 @@ Classifiers do not chat. They answer typed questions about JSON state with proba
 | Provider | Model IDs | Auth |
 |----------|-----------|------|
 | `typesafe` | `jev-latest` | `TYPESAFE_API_KEY` |
-| `openrouter` | `typesafe/jev-1.13`, `~typesafe/jev-latest` | `OPENROUTER_API_KEY` or `/login` |
-| `cloudflare-workers-ai` | `typesafe/jev`, `@cf/cloudflare/clef`, `@cf/cloudflare/clef-flash` (Clef, Pi 1.0.1) | `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` (or the credential's `env` in `auth.json`) |
+| `openrouter` | `typesafe/jev-1.13`, `typesafe/jev-1.14`, `~typesafe/jev-latest`, `cloudflare/clef`, `cloudflare/clef-flash`, `cloudflare/clef-omni` (Pi 1.4.0) | `OPENROUTER_API_KEY` or `/login` |
+| `cloudflare-workers-ai` | `typesafe/jev`, `typesafe/jev-1.14.0`, `@cf/cloudflare/clef`, `@cf/cloudflare/clef-flash` (Clef, Pi 1.0.1), `@cf/cloudflare/clef-omni` (Pi 1.4.0) | `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` (or the credential's `env` in `auth.json`) |
 | `vercel-ai-gateway` | `typesafe-ai/jev` | `AI_GATEWAY_API_KEY` |
 | `opencode` | `jev-1.13`, `jev-1.13-free` | `OPENCODE_API_KEY` |
-| `openai` | `gpt-6-luna` (Pi 1.1.0; also judges `images`) | `OPENAI_API_KEY`, not Sign in with ChatGPT |
+| `openai` | `gpt-6-luna` (Pi 1.1.0) | `OPENAI_API_KEY`, not Sign in with ChatGPT |
 | llama.cpp router | decision models (Julia-1, Laya, Kev, lev, OpenJev; Pi 1.1.0) and every loaded chat model ID | `/login llama.cpp` |
 
 ```typescript
@@ -269,6 +269,8 @@ if (jev) {
 
 - Question types: `choice` (`criteria` maps labels to descriptions; answer has `choice`, `probabilities`, `confidence`), `bool` (`criteria: { true, false }`; answer has `probability`), and `score` (`criteria` is an ordered list; answer has `score`, `confidence`). Pi translates `bool` to TypeSafe's wire format.
 - `classify()` never rejects. Failures and aborts return `stopReason: "error"` or `"aborted"` with `errorMessage`. Check `stopReason` and each answer's `type` before use, and validate probabilities yourself if a decision depends on them (for example finite and within `[0, 1]`).
+- `classify(model, { state, questions, images })` judges image blocks with the state for classifiers whose `input` includes `"image"`; others return an error result. That covers GPT-6 Luna (Pi 1.1.0) and, since Pi 1.4.0, Jev on `typesafe` (experimental there) and `cloudflare-workers-ai`, Clef on `cloudflare-workers-ai`, and OpenRouter classifiers whose catalog lists image input. Jev takes PNG and JPEG; Clef takes PNG, JPEG, and WebP, at most four per request. Jev on `vercel-ai-gateway` and `opencode` takes text only.
+- Each System One service takes images in its own wire form, set by the classifier's `compat.imageInput` (`"assets"`, `"images"`, or `"state-image-urls"`) plus `compat.sendImageOptInHeader` (Pi 1.4.0). Built-in models set them, so a `baseUrl` override keeps them; a custom provider proxying another service's classifiers sets them in its provider-level `compat` in `models.json`.
 - `result.usage` carries token counts and catalog cost when the service reports them; TypeSafe's direct `jev-latest` has no catalog price.
 - `jev-latest` moves with the service. Pin a versioned ID such as `openrouter`'s `typesafe/jev-1.13` when thresholds were tuned against one model.
 - Codemode scripts reach classifiers through `models.classify()` (see `references/codemode.md`). The SDK equivalent is `modelRuntime.classify()`. A llama.cpp chat-model classifier accepts a per-request `temperature` to soften overconfident label probabilities; System One and OpenAI Decisions ignore it.
@@ -283,7 +285,7 @@ In pi-ai, image models live in the same catalog as chat models: `builtinModels()
 
 ## Virtual Models
 
-A virtual model (experimental, Pi 0.99.0) is a selectable entry that routes each request to a physical model. It is for routing by task, cost, or conversation state, not for permission decisions. Source: [virtual-models.md](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/virtual-models.md), [`jev-router.ts`](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/examples/extensions/jev-router.ts).
+A virtual model (experimental, Pi 0.99.0) is a selectable entry that routes each request to a physical model. It is for routing by task, cost, or conversation state, not for permission decisions. Source: [virtual-models.md](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/virtual-models.md), [`jev-router.ts`](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/examples/extensions/jev-router.ts).
 
 ```typescript
 pi.registerVirtualModel({
@@ -314,7 +316,7 @@ pi.registerVirtualModel({
 
 Use extensions when you need custom streaming, custom headers, OAuth/device-flow logic, or want to override an existing provider's `baseUrl`/`headers`:
 
-A config-form `models` list replaces the provider's models across chat, image, and classifier operations; image and classifier entries need an explicit `type` and implementations keyed by `api` through `images` and `classifiers`. Registering only `baseUrl` or `headers` keeps the built-in models. See [custom-provider.md](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/custom-provider.md).
+A config-form `models` list replaces the provider's models across chat, image, and classifier operations; image and classifier entries need an explicit `type` and implementations keyed by `api` through `images` and `classifiers`. Registering only `baseUrl` or `headers` keeps the built-in models. See [custom-provider.md](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/custom-provider.md).
 
 ```typescript
 // Full registration
@@ -342,7 +344,7 @@ pi.registerProvider("anthropic", { baseUrl: "https://proxy.example.com" });
 
 Since pi-ai 1.1.0 a stream function must return an `AssistantMessageEventStream`, for example from `createAssistantMessageEventStream()`; a hand-written `EventStream<AssistantMessageEvent, AssistantMessage>` subclass no longer type-checks. Dynamic catalogs receive `RefreshModelsContext.baseUrl` (pi-ai 1.2.0), the provider's base URL with configuration overrides, so `refreshModels()` can follow a `models.json` base URL.
 
-Custom `streamSimple` implementations receive a normalized `TranscriptContext` instead of `Context`. System prompts and tool declarations live in transcript system messages: read them with `getCurrentSystemPrompt(context.messages)` and `getCurrentTools(context.messages)` (not `context.systemPrompt` / `context.tools`), and call `collapseSystemMessages(context)` if the backend cannot accept mid-conversation system messages. `ToolCall.arguments` and `ToolResultMessage.details` must be JSON-compatible. Pi 0.84.3 also renamed `GoogleThinkingLevel` to `GoogleApiThinkingLevel`.
+Custom `streamSimple` implementations receive a normalized `TranscriptContext` instead of `Context`. System prompts and tool declarations live in transcript system messages: read them with `getCurrentSystemPrompt(context.messages)` and `getCurrentTools(context.messages)` (not `context.systemPrompt` / `context.tools`), and call `collapseSystemMessages(context)` if the backend cannot accept mid-conversation system messages. Breaking in pi-ai 1.4.0: `resolveTranscriptTools()` takes a `TranscriptToolSupport` (`"none"`, `"additions"`, or `"changes"`) instead of a boolean, and `TranscriptTools.anchorsAdditions` became `foldedSystemMessages`. `ToolCall.arguments` and `ToolResultMessage.details` must be JSON-compatible. Since pi-ai 1.3.0 a tool call whose complete arguments text is not a JSON object carries `arguments: {}` and `argumentsError` (the problem plus the raw text), and validation fails with it; a custom adapter should report malformed arguments that way rather than run the fields it managed to parse. Pi 0.84.3 also renamed `GoogleThinkingLevel` to `GoogleApiThinkingLevel`.
 
 ## SDK / Extension Auth Lookup
 

package/skills/pi/references/sdk.md

@@ -38,7 +38,7 @@ try {
 }
 ```
 
-Run with `npx tsx my-script.ts` (or Node's built-in type stripping). `prompt()` resolves when the run finishes, including automatic retries. `session.dispose()` aborts active work, invalidates extension contexts, and removes listeners. Checked against Pi v1.2.0: [sdk.md](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/sdk.md), [SDK examples](https://github.com/earendil-works/pi/tree/v1.2.0/packages/coding-agent/examples/sdk).
+Run with `npx tsx my-script.ts` (or Node's built-in type stripping). `prompt()` resolves when the run finishes, including automatic retries. `session.dispose()` aborts active work, invalidates extension contexts, and removes listeners. Checked against Pi v1.4.0: [sdk.md](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/sdk.md), [SDK examples](https://github.com/earendil-works/pi/tree/v1.4.0/packages/coding-agent/examples/sdk).
 
 **Breaking (Pi 0.80.8):** `ModelRuntime` replaced the old `AuthStorage`/`ModelRegistry` pair as the SDK model/auth facade. `CreateAgentSessionOptions.authStorage` and `modelRegistry` are gone — pass the async `modelRuntime` instead. `AuthStorage` is no longer exported; use `ModelRuntime` (or a custom pi-ai `CredentialStore`), or `readStoredCredential()` for one-off reads of `auth.json`. `ModelRegistry` still exists only as the synchronous extension-facing compatibility facade, and its `refresh()` is now `Promise<void>`.
 
@@ -58,6 +58,8 @@ import { getBuiltinModel } from "@earendil-works/pi-ai/providers/all";
 
 **Lightweight model construction (pi-ai 0.99.2):** `@earendil-works/pi-ai/models` builds model collections and providers without loading TypeBox, the built-in catalogs, or provider SDKs; use it in startup-sensitive code that brings its own models.
 
+**Client identity (pi-ai 1.4.0):** `createModels({ identity })` or a per-request `identity` option sets the `User-Agent` (`"detailed"`, `"short"`, or `{ custom: "..." }`) and the OpenRouter, NVIDIA NIM, and OpenCode attribution headers (`attribution: { name, url, categories? }`). `withClientIdentity()` applies one to a `Models` received from a host, and `AgentOptions.identity` does the same for agent-loop requests. Breaking: `@earendil-works/pi-ai/utils/pi-user-agent` (`getPiUserAgent()`) was removed, so use `formatUserAgent()`; the request option `telemetryContext` became `telemetry`, a parent `TelemetrySpan`; and `generateSummary()`/`generateSummaryWithUsage()` ignore `reserveTokens`, using the model's output limit.
+
 **pi-ai 0.80.0 API move:** the old global API (`getModel`, `getModels`, `getProviders`, `stream`, `complete`, `completeSimple`, `registerApiProvider`, `getEnvApiKey`, ...) moved off the `@earendil-works/pi-ai` root entrypoint to `@earendil-works/pi-ai/compat` (a deprecated shim slated for removal). For built-in model lookup use `getBuiltinModel(provider, modelId)` from `@earendil-works/pi-ai/providers/all`, or the provider-factory API (`createModels()` / `Models.getModel()`). Extensions loaded by Pi are unaffected at runtime — the extension loader aliases the pi-ai root to the compat superset — but standalone SDK scripts and typechecked extension sources must use the new paths. The selective `@earendil-works/pi-ai/base` / `@earendil-works/pi-agent-core/base` entrypoints introduced in 0.79.8 were removed again in 0.80.0.
 
 ## Core Options
@@ -96,7 +98,7 @@ Notes:
 
 ## Built-in Extensions: Codemode, Tool Search, MCP
 
-The CLI loads `codemode`, `tool_search`, MCP, and llama.cpp as built-in extensions. SDK sessions load none of them. Opt in through the resource loader (Pi 0.99.0, [example](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/examples/sdk/14-codemode-mcp.ts)):
+The CLI loads `codemode`, `tool_search`, MCP, and llama.cpp as built-in extensions. SDK sessions load none of them. Opt in through the resource loader (Pi 0.99.0, [example](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/examples/sdk/14-codemode-mcp.ts)):
 
 ```typescript
 import {
@@ -319,7 +321,7 @@ session.subscribe((event) => {
 
 ## RPC Mode
 
-`pi --mode rpc` speaks newline-delimited JSON over stdio ([rpc.md](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/rpc.md), [rpc-commands.md](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/rpc-commands.md)). Additions since Pi 0.79:
+`pi --mode rpc` speaks newline-delimited JSON over stdio ([rpc.md](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/rpc.md), [rpc-commands.md](https://github.com/earendil-works/pi/blob/v1.4.0/packages/coding-agent/docs/rpc-commands.md)). Additions since Pi 0.79:
 
 - Input dispositions (Pi 0.99.0): a successful `prompt` response carries `data.disposition` — `"started"` (a run started), `"queued"` (queued during a run), or `"handled"` (an extension command or input handler consumed it). `steer` and `follow_up` responses carry `"queued"` or `"handled"`. On `"handled"` no run started for that input: do not wait for `agent_settled`. Otherwise keep consuming events and wait for `agent_settled`, not `agent_end`. Failures after acceptance arrive as events, never as a second response. `RpcClient.prompt(message, images?, streamingBehavior?)`, `steer()`, and `followUp()` return the disposition.
 - `agent_settled` event (Pi 0.80.4) fires when a run is fully settled — no automatic retry, compaction retry, or queued continuation remains; `agent_end` now carries `willRetry`. Since Pi 1.1.0 `agent_settled` carries `aborted`, and `tool_execution_end` carries `durationMs`. `set_thinking_level` accepts `"max"` where the model supports it.

package/skills/pi/references/settings.md

@@ -115,6 +115,7 @@ Fullscreen is the default since Pi 1.0.0 (added in 0.84.0):
 
 Notes:
 
+- `compaction.reserveTokens` only decides when auto-compaction starts: once free context falls below it. Since Pi 1.4.0 compaction and branch summaries use the model's output limit instead of a fixed cap, so long reasoning no longer makes them fail.
 - `compaction.modelOverrides` (Pi 0.86.0) sets per-model `reserveTokens`/`keepRecentTokens` keyed by exact `provider/modelId`; each value falls back to the ordinary compaction setting, then the default.
 - `retry.maxRetries` (default `3`) and `retry.baseDelayMs` (default `2000`) govern Pi's own agent-level retry with exponential backoff, capped per attempt by `retry.maxAgentDelayMs` (default `60000`, Pi 0.86.0).
 - `retry.provider.*` controls the underlying provider SDK's request timeout and retry/backoff — useful for slow local LLMs and flaky proxies. `retry.provider.timeoutMs` sets the SDK request timeout; `retry.provider.maxRetries` defaults to `0` (keep it there unless you need SDK-level retries, since raising it can let provider retries swallow usage-limit errors before Pi handles them).
@@ -185,6 +186,7 @@ Notes:
 ```json
 {
   "sessionDir": ".pi/sessions",
+  "sessionShareDestination": "auto",
   "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"],
   "markdown": {
     "codeBlockIndent": "  ",
@@ -195,6 +197,7 @@ Notes:
 
 When multiple sources specify a session directory, `--session-dir` takes precedence over `sessionDir` in settings. Pi 0.65.0 removed the old `session_directory` extension/settings hook.
 
+- `sessionShareDestination` (Pi 1.3.0): `"auto"` (default) uploads `/share` to Radius when signed in and otherwise to a private GitHub gist; `"gist"` or `"radius"` forces one, and `"radius"` never falls back.
 - `markdown.mermaid` (Pi 0.84.0): `"off"`, `"final"`, or `"streaming"` — themed Unicode rendering of supported Mermaid diagrams in interactive messages. Pi 0.84.0 also renders terminal-friendly Unicode for LaTeX expressions.
 
 ## Tools & Codemode
@@ -208,6 +211,7 @@ When multiple sources specify a session directory, `--session-dir` takes precede
 
 - `defaultTools` picks the tools enabled at startup (default `read`, `bash`, `edit`, `write`; also `grep`, `find`, `ls`, `powershell`, and the built-in extension tools `codemode` and `tool_search`). Plain names replace the defaults. A list of only `+name`/`-name` entries (Pi 0.99.0) changes the inherited selection instead; in a mixed list the plain names form the selection and `+`/`-` apply in order. A project list of only `+`/`-` entries applies on top of the user setting; a project list with a plain name replaces it. An empty array disables built-in tools but keeps extension/SDK tools.
 - `--tools` with plain names replaces the whole selection for one run; entries may be `*` patterns (Pi 1.0.4), and MCP tools stay unless an entry starts with `mcp__`. A list of only `+name`/`-name` entries (Pi 1.1.0, exact names) changes the `defaultTools` selection instead, e.g. `pi --tools +codemode,-write`; the two forms cannot be mixed. `--exclude-tools` filters the result, takes patterns, and covers MCP tools; `--no-mcp` (Pi 1.0.4) turns off built-in MCP for one run.
+- Resumed sessions restore their active tools (Pi 1.3.0), and `--tools +name`/`-name` applies on top of them; `--tools` with plain names, `--no-tools`, and `--no-builtin-tools` still pick tools explicitly. Since Pi 1.4.0, resume and `/tree` also activate extension tools registered after the branch recorded its tools, unless they use `defaultActive: false`; tools the branch removed stay inactive.
 - `/reload` (Pi 0.99.2) enables tools newly added to `defaultTools`. It does not disable tools removed from it or re-enable unchanged tools turned off in the session; `--tools` with plain names, `--no-tools`, and `--no-builtin-tools` still win on reload, and a tool removed with `--tools -name` stays removed.
 - `codemode.mode`: `"on"` (default) keeps declared tools declared; `"only"` hides active built-in and extension tools from the model so it reaches them through `codemode`. `codemode.inlineBudget` (default `3000`, estimated tokens) caps tool declarations in the `codemode` description. See `references/codemode.md`.
 - MCP servers are configured in `~/.pi/agent/mcp.json` and the trust-gated `.pi/mcp.json`, not in `settings.json`. See `references/mcp.md`.
@@ -294,10 +298,10 @@ pi [options] [@files...] [messages...]
 
 # model
 --provider <name>                e.g. anthropic, openai, google; needs --model (Pi 1.0.0)
---model <pattern>                supports provider/id and optional :<thinking>
+--model <pattern>                supports provider/id and optional :<thinking>; prefers the provider with credentials when several match (Pi 1.3.0)
 --api-key <key>
 --thinking off|minimal|low|medium|high|xhigh|max
---models <patterns>              Ctrl+P cycling allowlist
+--models <patterns>              Ctrl+P cycling allowlist; a model several providers offer is added for each, with a warning (Pi 1.3.0)
 --list-models [search]
 
 # sessions
@@ -353,6 +357,7 @@ Use `/bug [description]` (Pi 0.86.0) to report a problem with redacted diagnosti
 | `PI_CACHE_RETENTION` | Set to `long` for extended prompt-cache retention where supported |
 | `PI_OAUTH_CALLBACK_HOST` | Bind the OAuth callback server to a custom interface |
 | `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
+| `PI_CODEMODE_MAX_WORKERS` | Maximum codemode workers alive at once across the process (default `2`, Pi 1.4.0); raise it when one process runs several sessions |
 | `PI_HARDWARE_CURSOR` | `1` shows the hardware cursor (see terminal-setup docs) |
 | `PI_CLIPBOARD_OSC52` | `1` (Pi 1.2.0) also sends copied text to the terminal with OSC 52, for remote clients Pi cannot detect, such as a multiplexer attached from another machine |
 | `PI_PROGRAM_STATUS` | OSC 7501 program status (Pi 1.1.0): Pi reports working/blocked/done/error/idle to terminals and agent dashboards that confirm support; `1` always reports, `0` never |