Changelog

• Earendil startup announcement with bundled inline image rendering and a linked blog post for April 8 and 9, 2026.
• Interactive Anthropic subscription auth warning when Anthropic subscription auth is active, clarifying that Anthropic third-party usage draws from extra usage and is billed per token.

• Fixed bash output truncation by line count to always persist full output to a temp file, preventing data loss when output exceeds 2000 lines but stays under the byte threshold (#2852)
• RpcClient now forwards subprocess stderr to parent process in real-time (#2805)
• Theme file watcher now handles async fs.watch error events instead of crashing the process (#2791)
• Fixed stored session cwd handling so resuming or importing a session whose original working directory no longer exists now prompts interactive users to continue in the current cwd, while non-interactive modes fail with a clear error.
• Fixed resource collision precedence so project and user skills, prompt templates, and themes override package resources consistently, and CLI-provided paths take precedence over discovered resources (#2781)
• Fixed OpenAI-compatible completions streaming usage accounting to preserve prompt_tokens_details.cache_write_tokens and normalize OpenRouter cached_tokens, preventing incorrect cache read/write token and cost reporting in pi (#2802)
• Fixed CLI extension paths like git:gist.github.com/... being incorrectly resolved against cwd instead of being passed through to the package manager (#2845 by @aliou)
• Fixed piped stdin runs with --mode json to preserve JSONL output instead of falling back to plain text (#2848 by @aliou)
• Fixed interactive command docs to stop listing removed /exit as a supported quit command (#2850)

• Session runtime API: createAgentSessionRuntime() and AgentSessionRuntime provide a closure-based runtime that recreates cwd-bound services and session config on every session switch. Startup, /new, /resume, /fork, and import all use the same creation path. See docs/sdk.md and examples/sdk/13-session-runtime.ts.
• Label timestamps in /tree: Toggle timestamps on tree entries with Shift+T, with smart date formatting and timestamp preservation through branching (#2691 by @w-winter)
• defineTool() helper: Create standalone custom tool definitions with full TypeScript parameter type inference, no manual casts needed (#2746). See docs/extensions.md.
• Unified diagnostics: Arg parsing, service creation, session option resolution, and resource loading all return structured diagnostics (info/warning/error) instead of logging or exiting. The app layer decides presentation and exit behavior.

• Removed extension post-transition events session_switch and session_fork. Use session_start with event.reason ("startup" | "reload" | "new" | "resume" | "fork"). For "new", "resume", and "fork", session_start includes previousSessionFile.
• Removed session-replacement methods from AgentSession. Use AgentSessionRuntime for newSession(), switchSession(), fork(), and importFromJsonl(). Cross-cwd session replacement rebuilds all cwd-bound runtime state and replaces the live AgentSession instance.
• Removed session_directory from extension and settings APIs.
• Unknown single-dash CLI flags (e.g. -s) now produce an error instead of being silently ignored.

Migration: Extensions

Before:

pi.on("session_switch", async (event, ctx) => { ... });
pi.on("session_fork", async (_event, ctx) => { ... });

After:

pi.on("session_start", async (event, ctx) => {
  // event.reason: "startup" | "reload" | "new" | "resume" | "fork"
  // event.previousSessionFile: set for "new", "resume", "fork"
});

Migration: SDK session replacement

Before:

await session.newSession();
await session.switchSession("/path/to/session.jsonl");

After:

import {
  type CreateAgentSessionRuntimeFactory,
  createAgentSessionFromServices,
  createAgentSessionRuntime,
  createAgentSessionServices,
  getAgentDir,
  SessionManager,
} from "@mariozechner/pi-coding-agent";

const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
  const services = await createAgentSessionServices({ cwd });
  return {
    ...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
    services,
    diagnostics: services.diagnostics,
  };
};

const runtime = await createAgentSessionRuntime(createRuntime, {
  cwd: process.cwd(),
  agentDir: getAgentDir(),
  sessionManager: SessionManager.create(process.cwd()),
});

await runtime.newSession();
await runtime.switchSession("/path/to/session.jsonl");
await runtime.fork("entry-id");

// After replacement, runtime.session is the new live session.
// Rebind any session-local subscriptions or extension bindings.

• Added createAgentSessionRuntime() and AgentSessionRuntime for runtime-backed session replacement. The runtime takes a CreateAgentSessionRuntimeFactory closure that closes over process-global fixed inputs and recreates cwd-bound services and session config for each effective cwd. Startup and later /new, /resume, /fork, import all use the same factory.

• Added unified diagnostics model (info/warning/error) for arg parsing, service creation, session option resolution, and resource loading. Creation logic no longer logs or exits. The app layer decides presentation and exit behavior.

• Added error diagnostics for missing explicit CLI resource paths (-e, --skill, --prompt-template, --theme)

• Added defineTool() so standalone and array-based custom tool definitions keep inferred parameter types without manual casts (#2746)

• Added label timestamps to the session tree with a Shift+T toggle in /tree, smart date formatting, and timestamp preservation through branching (#2691 by @w-winter)

• Extensions and SDK callers can attach a prepareArguments hook to any tool definition, letting them normalize or migrate raw model arguments before schema validation. The built-in edit tool uses this to transparently support sessions created with the old single-edit schema. See docs/extensions.md
• Extensions can customize the collapsed thinking block label via ctx.ui.setHiddenThinkingLabel(). See examples/extensions/hidden-thinking-label.ts (#2673)

• ModelRegistry no longer has a public constructor. SDK callers and tests must use ModelRegistry.create(authStorage, modelsJsonPath?) for file-backed registries or ModelRegistry.inMemory(authStorage) for built-in-only registries. Direct new ModelRegistry(...) calls no longer compile.

• Added ToolDefinition.prepareArguments hook to prepare raw tool call arguments before schema validation, enabling compatibility shims for resumed sessions with outdated tool schemas
• Built-in edit tool now uses prepareArguments to silently fold legacy top-level oldText/newText into edits[] when resuming old sessions
• Added ctx.ui.setHiddenThinkingLabel() so extensions can customize the collapsed thinking label in interactive mode, with a no-op in RPC mode and a runnable example extension in examples/extensions/hidden-thinking-label.ts (#2673)

• Extension handlers can now use ctx.signal to forward cancellation into nested model calls, fetch(), and other abort-aware work. See docs/extensions.md#ctxsignal (#2660)
• Built-in edit tool input now uses edits[] as the only replacement shape, reducing invalid tool calls caused by mixed single-edit and multi-edit schemas (#2639)
• Large multi-edit results no longer trigger full-screen redraws in the interactive TUI when the final diff is rendered (#2664)

• Added ctx.signal to ExtensionContext and wired it to the active agent turn so extension handlers can forward cancellation into nested model calls, fetch(), and other abort-aware work (#2660)

• Added gemini-3.1-pro-preview-customtools model availability for the google-vertex provider (#2610 by @gordonhwc)

• ModelRegistry.getApiKey(model) has been replaced by getApiKeyAndHeaders(model) because models.json auth and header values can now resolve dynamically on every request. Extensions and SDK integrations that previously fetched only an API key must now fetch request auth per call and forward both apiKey and headers. Use getApiKeyForProvider(provider) only when you explicitly want provider-level API key lookup without model headers or authHeader handling (#1835)
• Removed deprecated direct minimax and minimax-cn model IDs, keeping only MiniMax-M2.7 and MiniMax-M2.7-highspeed. Update pinned model IDs to one of those supported direct MiniMax models, or use another provider route that still exposes the older IDs (#2596 by @liyuan97)

Migration Notes

Before:

const apiKey = await ctx.modelRegistry.getApiKey(model);
return streamSimple(model, messages, { apiKey });

After:

const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
if (!auth.ok) throw new Error(auth.error);
return streamSimple(model, messages, {
  apiKey: auth.apiKey,
  headers: auth.headers,
});

• Added sessionDir setting support in global and project settings.json so session storage can be configured without passing --session-dir on every invocation (#2598 by @smcllns)
• Added a startup onboarding hint in the interactive header telling users pi can explain its own features and documentation (#2620 by @ferologics)
• Added edit tool multi-edit support so one call can update multiple separate, disjoint regions in the same file while matching all replacements against the original file content
• Added support for PI_TUI_WRITE_LOG directory paths, creating a unique log file (tui-<timestamp>-<pid>.log) per instance for easier debugging of multiple pi sessions (#2508 by @mrexodia)

• Built-in tools as extensible ToolDefinitions. Extension authors can now override rendering of built-in read/write/edit/bash/grep/find/ls tools with custom renderCall/renderResult components. See docs/extensions.md.
• Unified source provenance via sourceInfo. All resources, commands, tools, skills, and prompt templates now carry structured sourceInfo with path, scope, and source metadata. Visible in autocomplete, RPC discovery, and SDK introspection. See docs/extensions.md.
• AWS Bedrock cost allocation tagging. New requestMetadata option on BedrockOptions forwards key-value pairs to the Bedrock Converse API for AWS Cost Explorer split cost allocation.

• Changed ToolDefinition.renderCall and renderResult semantics. Fallback rendering now happens only when a renderer is not defined for that slot. If renderCall or renderResult is defined, it must return a Component.
• Changed slash command provenance to use sourceInfo consistently. RPC get_commands, RpcSlashCommand, and SDK SlashCommandInfo no longer expose location or path. Use sourceInfo instead (#1734)
• Removed legacy source fields from Skill and PromptTemplate. Use sourceInfo.source for provenance instead (#1734)
• Removed ResourceLoader.getPathMetadata(). Resource provenance is now attached directly to loaded resources via sourceInfo (#1734)
• Removed extensionPath from RegisteredCommand and RegisteredTool. Use sourceInfo.path for provenance instead (#1734)

Migration Notes

Resource, command, and tool provenance now use sourceInfo consistently.

Common updates:

• RPC get_commands: replace path and location with sourceInfo.path, sourceInfo.scope, and sourceInfo.source
• SlashCommandInfo: replace command.path and command.location with command.sourceInfo
• Skill and PromptTemplate: replace .source with .sourceInfo.source
• RegisteredCommand and RegisteredTool: replace .extensionPath with .sourceInfo.path
• Custom ResourceLoader implementations: remove getPathMetadata() and read provenance from loaded resources directly

Examples:

• command.path -> command.sourceInfo.path
• command.location === "user" -> command.sourceInfo.scope === "user"
• skill.source -> skill.sourceInfo.source
• tool.extensionPath -> tool.sourceInfo.path

• Built-in tools now work like custom tools in extensions. To get built-in tool definitions, import readToolDefinition / createReadToolDefinition() and the equivalent bash, edit, write, grep, find, and ls exports from @mariozechner/pi-coding-agent.
• Cleaned up buildSystemPrompt() so built-in tool snippets and tool-local guidelines come from built-in ToolDefinition metadata, while cross-tool and global prompt rules stay in system prompt construction.
• Added structured sourceInfo to pi.getAllTools() results for built-in, SDK, and extension tools (#1734)

• Typed tool_call handler return values via ToolCallEventResult exports from the top-level package and core extension entry. See docs/extensions.md.
• Updated default models for zai, cerebras, minimax, and minimax-cn, and aligned MiniMax catalog coverage and limits with the current provider lineup. See docs/models.md and docs/providers.md.

• Added ToolCallEventResult to the @mariozechner/pi-coding-agent top-level and core extension exports so extension authors can type explicit tool_call handler return values (#2458)

• Changed the default models for zai, cerebras, minimax, and minimax-cn to match the current provider lineup, and added missing MiniMax-M2.1-highspeed model entries with normalized MiniMax context limits (#2445 by @1500256797)

• Namespaced keybinding ids and a unified keybinding manager across the app and TUI. See docs/keybindings.md and docs/extensions.md.
• JSONL session export and import via /export <path.jsonl> and /import <path.jsonl>. See README.md and docs/session.md.
• Resizable sidebar in HTML share and export views. See README.md.

• Interactive keybinding ids are now namespaced, and keybindings.json now uses those same canonical namespaced ids. Older config files are migrated automatically on startup. Custom editors and extension UI components still receive an injected keybindings: KeybindingsManager. They do not call getKeybindings() or setKeybindings() themselves. Declaration merging applies to that injected type (#2391)
• Extension author migration: update keyHint(), keyText(), and injected keybindings.matches(...) calls from old built-in names like "expandTools", "selectConfirm", and "interrupt" to namespaced ids like "app.tools.expand", "tui.select.confirm", and "app.interrupt". See docs/keybindings.md for the full list. pi.registerShortcut("ctrl+shift+p", ...) is unchanged because extension shortcuts still use raw key combos, not keybinding ids.

• Added gpt-5.4-mini to the openai-codex model catalog (#2334 by @justram)
• Added JSONL session export and import via /export <path.jsonl> and /import <path.jsonl> (#2356 by @hjanuschka)
• Added a resizable sidebar to HTML share and export views (#2435 by @dmmulroy)

• Fork existing sessions directly from the CLI with --fork <path|id>, which copies a source session into a new session in the current project. See README.md.
• Extensions and SDK callers can reuse pi's built-in local bash backend via createLocalBashOperations() for user_bash interception and custom bash integrations. See docs/extensions.md#user_bash.
• Startup no longer updates unpinned npm and git packages automatically. Use pi update explicitly, while interactive mode checks for updates in the background and notifies you when newer packages are available. See README.md.

• Changed package startup behavior so installed unpinned packages are no longer checked or updated during startup. Use pi update to apply npm/git package updates, while interactive mode now checks for available package updates in the background and notifies you when updates are available (#1963)

• Added --fork <path|id> CLI flag to fork an existing session file or partial session UUID directly into a new session (#2290)
• Added createLocalBashOperations() export so extensions and SDK callers can wrap pi's built-in local bash backend for user_bash handling and other custom bash integrations (#2299)

• Faster startup by lazy-loading @mariozechner/pi-ai provider SDKs on first use instead of import time (#2297)
• Better provider retry behavior when providers return error messages as responses (#2264)
• Better terminal integration via OSC 133 command-executed markers (#2242)
• Better Git footer branch detection for repositories using reftable storage (#2300)

• Changed custom tool system prompt behavior so extension and SDK tools are included in the default Available tools section only when they provide promptSnippet. Omitting promptSnippet now leaves the tool out of that section instead of falling back to description (#2285)

• Lazy-load built-in @mariozechner/pi-ai provider modules and root provider wrappers so coding-agent startup no longer eagerly loads provider SDKs before first use (#2297)

• Fixed steering messages to wait until the current assistant message's tool-call batch fully finishes instead of skipping pending tool calls.

• Improved settings, theme, thinking, and show-images selector layouts by using configurable select-list primary column sizing (#2154 by @markusylisiurunen)

• Added pi uninstall alias for pi install --uninstall convenience

• Claude Opus 4.6, Sonnet 4.6, and related Bedrock models now use a 1M token context window (up from 200K) (#2135 by @mitsuhiko).
• Extension tool calls now execute in parallel by default, with sequential tool_call preflight preserved for extension interception.
• GOOGLE_CLOUD_API_KEY environment variable support for the google-vertex provider as an alternative to Application Default Credentials (#1976 by @gordonhwc).
• Extensions can supply deterministic session IDs via newSession() (#2130 by @zhahaoyu).

• Added GOOGLE_CLOUD_API_KEY environment variable support for the google-vertex provider as an alternative to Application Default Credentials (#1976 by @gordonhwc)
• Added custom session ID support in newSession() for extensions that need deterministic session paths (#2130 by @zhahaoyu)

• Changed extension tool interception to use agent-core beforeToolCall and afterToolCall hooks instead of wrapper-based interception. Tool calls now execute in parallel by default, extension tool_call preflight still runs sequentially, and final tool results are emitted in assistant source order.
• Raised Claude Opus 4.6, Sonnet 4.6, and related Bedrock model context windows from 200K to 1M tokens (#2135 by @mitsuhiko)

• Tree branch folding and segment-jump navigation in /tree, with Ctrl+←/Ctrl+→ and Alt+←/Alt+→ shortcuts while ←/→ and Page Up/Page Down remain available for paging. See docs/tree.md and docs/keybindings.md.
• session_directory extension event for customizing session directory paths before session manager creation. See docs/extensions.md.
• Digit keybindings (0-9) in the TUI keybinding system, including modified combos like ctrl+1. See docs/keybindings.md.

• Added /tree branch folding and segment-jump navigation with Ctrl+←/Ctrl+→ and Alt+←/Alt+→, while keeping ←/→ and Page Up/Page Down for paging (#1724 by @Perlence)
• Added session_directory extension event that fires before session manager creation, allowing extensions to customize the session directory path based on cwd and other factors. CLI --session-dir flag takes precedence over extension-provided paths (#1730 by @hjanuschka).
• Added digit keys (0-9) to the keybinding system, including Kitty CSI-u and xterm modifyOtherKeys support for bindings like ctrl+1 (#1905)

• Extensions can intercept and modify provider request payloads via before_provider_request. See docs/extensions.md#before_provider_request.
• Extension UIs can use non-capturing overlays with explicit focus control via OverlayOptions.nonCapturing and OverlayHandle.focus() / unfocus() / isFocused(). See docs/extensions.md and ../tui/README.md.
• RPC mode now uses strict LF-only JSONL framing for robust payload handling. See docs/rpc.md.

• RPC mode now uses strict LF-delimited JSONL framing. Clients must split records on \n only instead of using generic line readers such as Node readline, which also split on Unicode separators inside JSON payloads (#1911)

• Added before_provider_request extension hook so extensions can inspect or replace provider payloads before requests are sent, with an example in examples/extensions/provider-payload.ts
• Added non-capturing overlay focus control for extension UIs via OverlayOptions.nonCapturing and OverlayHandle.focus() / unfocus() / isFocused() (#1916 by @nicobailon)

• Overlay compositing in extension UIs now uses focus order so focused overlays render on top while preserving stack semantics for show/hide behavior (#1916 by @nicobailon)

• claude-sonnet-4-6 model available via the google-antigravity provider (#1859)
• Custom editors can now define their own onEscape/onCtrlD handlers without being overwritten by app defaults, enabling vim-mode extensions (#1838)
• Shift+Enter and Ctrl+Enter now work inside tmux via xterm modifyOtherKeys fallback (docs/tmux.md, #1872)
• Auto-compaction is now resilient to persistent API errors (e.g. 529 overloaded) and no longer retriggers spuriously after compaction (#1834, #1860)

• Added claude-sonnet-4-6 model for the google-antigravity provider (#1859).
• Added tmux setup documentation for modified enter key support (#1872)

• GPT-5.4 support across openai, openai-codex, azure-openai-responses, and opencode, with gpt-5.4 now the default for openai and openai-codex (README.md, docs/providers.md).
• treeFilterMode setting to choose the default /tree filter mode (default, no-tools, user-only, labeled-only, all) (docs/settings.md, #1852 by @lajarre).
• Mistral native conversations integration with SDK-backed provider behavior, preserving Mistral-specific thinking and replay semantics (README.md, docs/providers.md, #1716).

• Added gpt-5.4 model availability for openai, openai-codex, azure-openai-responses, and opencode providers.
• Added gpt-5.3-codex fallback model availability for github-copilot until upstream model catalogs include it (#1853).
• Added treeFilterMode setting to choose the default /tree filter mode (default, no-tools, user-only, labeled-only, all) (#1852 by @lajarre).

• Updated the default models for the openai and openai-codex providers to gpt-5.4.