Changelog

SDK for programmatic usage: New createAgentSession() factory with full control over model, tools, hooks, skills, session persistence, and settings. Philosophy: "omit to discover, provide to override". Includes 12 examples and comprehensive documentation. (#272)

Project-specific settings: Settings now load from both ~/.pi/agent/settings.json (global) and <cwd>/.pi/settings.json (project). Project settings override global with deep merge for nested objects. Project settings are read-only (for version control). (#276)

SettingsManager static factories: SettingsManager.create(cwd?, agentDir?) for file-based settings, SettingsManager.inMemory(settings?) for testing. Added applyOverrides() for programmatic overrides.

SessionManager static factories: SessionManager.create(), SessionManager.open(), SessionManager.continueRecent(), SessionManager.inMemory(), SessionManager.list() for flexible session management.

Gemini 3 preview models: Added gemini-3-pro-preview and gemini-3-flash-preview to the google-gemini-cli provider. (#264 by @LukeFost)

External editor support: Press Ctrl+G to edit your message in an external editor. Uses $VISUAL or $EDITOR environment variable. On successful save, the message is replaced; on cancel, the original is kept. (#266 by @aliou)

Process suspension: Press Ctrl+Z to suspend pi and return to the shell. Resume with fg as usual. (#267 by @aliou)

Configurable skills directories: Added granular control over skill sources with enableCodexUser, enableClaudeUser, enableClaudeProject, enablePiUser, enablePiProject toggles, plus customDirectories and ignoredSkills settings. (#269 by @nicobailon)

Skills CLI filtering: Added --skills <patterns> flag for filtering skills with glob patterns. Also added includeSkills setting and glob pattern support for ignoredSkills. (#268)

Gemini image reading broken: Fixed the read tool returning images causing flaky/broken responses with Gemini models. Images in tool results are now properly formatted per the Gemini API spec.

Tab completion for absolute paths: Fixed tab completion producing //tmp instead of /tmp/. Also fixed symlinks to directories (like /tmp) not getting a trailing slash, which prevented continuing to tab through subdirectories.

Interruptible tool execution: Queuing a message while tools are executing now interrupts the current tool batch. Remaining tools are skipped with an error result, and your queued message is processed immediately. Useful for redirecting the agent mid-task. (#259 by @steipete)

Google Gemini CLI OAuth provider: Access Gemini 2.0/2.5 models for free via Google Cloud Code Assist. Login with /login and select "Google Gemini CLI". Uses your Google account with rate limits.

Google Antigravity OAuth provider: Access Gemini 3, Claude (sonnet/opus thinking models), and GPT-OSS models for free via Google's Antigravity sandbox. Login with /login and select "Antigravity". Uses your Google account with rate limits.

OAuth and model config exports: Scripts using AgentSession directly can now import getAvailableModels, getApiKeyForModel, findModel, login, logout, and getOAuthProviders from @mariozechner/pi-coding-agent to reuse OAuth token storage and model resolution. (#245)

xhigh thinking level for gpt-5.2 models: The thinking level selector and shift+tab cycling now show xhigh option for gpt-5.2 and gpt-5.2-codex models (in addition to gpt-5.1-codex-max). (#236 by @theBucky)

Subagent orchestration example: Added comprehensive custom tool example for spawning and orchestrating sub-agents with isolated context windows. Includes scout/planner/reviewer/worker agents and workflow commands for multi-agent pipelines. (#215 by @nicobailon)

getMarkdownTheme() export: Custom tools can now import getMarkdownTheme() from @mariozechner/pi-coding-agent to use the same markdown styling as the main UI.

pi.exec() signal and timeout support: Custom tools and hooks can now pass { signal, timeout } options to pi.exec() for cancellation and timeout handling. The result includes a killed flag when the process was terminated.

Kitty keyboard protocol support: Shift+Enter, Alt+Enter, Shift+Tab, Ctrl+D, and all Ctrl+key combinations now work in Ghostty, Kitty, WezTerm, and other modern terminals. (#225 by @kim0)

Dynamic API key refresh: OAuth tokens (GitHub Copilot, Anthropic OAuth) are now refreshed before each LLM call, preventing failures in long-running agent loops where tokens expire mid-session. (#223 by @kim0)

/hotkeys command: Shows all keyboard shortcuts in a formatted table.

Markdown table borders: Tables now render with proper top and bottom borders.

Subagent example improvements: Parallel mode now streams updates from all tasks. Chain mode shows all completed steps during streaming. Expanded view uses proper markdown rendering with syntax highlighting. Usage footer shows turn count.

Skills standard compliance: Skills now adhere to the Agent Skills standard. Validates name (must match parent directory, lowercase, max 64 chars), description (required, max 1024 chars), and frontmatter fields. Warns on violations but remains lenient. Prompt format changed to XML structure. Removed {baseDir} placeholder in favor of relative paths. (#231)

Custom tools now require index.ts entry point: Auto-discovered custom tools must be in a subdirectory with an index.ts file. The old pattern ~/.pi/agent/tools/mytool.ts must become ~/.pi/agent/tools/mytool/index.ts. This allows multi-file tools to import helper modules. Explicit paths via --tool or settings.json still work with any .ts file.

Hook tool_result event restructured: The ToolResultEvent now exposes full tool result data instead of just text. (#233)

• Removed: result: string field
• Added: content: (TextContent | ImageContent)[] - full content array
• Added: details: unknown - tool-specific details (typed per tool via discriminated union on toolName)
• ToolResultEventResult.result renamed to ToolResultEventResult.text (removed), use content instead
• Hook handlers returning { result: "..." } must change to { content: [{ type: "text", text: "..." }] }
• Built-in tool details types exported: BashToolDetails, ReadToolDetails, GrepToolDetails, FindToolDetails, LsToolDetails, TruncationResult
• Type guards exported for narrowing: isBashToolResult, isReadToolResult, isEditToolResult, isWriteToolResult, isGrepToolResult, isFindToolResult, isLsToolResult

Syntax highlighting: Added syntax highlighting for markdown code blocks, read tool output, and write tool content. Uses cli-highlight with theme-aware color mapping and VS Code-style syntax colors. (#214 by @svkozak)

Intra-line diff highlighting: Edit tool now shows word-level changes with inverse highlighting when a single line is modified. Multi-line changes show all removed lines first, then all added lines.

Improved system prompt documentation section with clearer pointers to specific doc files for custom models, themes, skills, hooks, custom tools, and RPC.

Cleaned up documentation:

• theme.md: Added missing color tokens (thinkingXhigh, bashMode)
• skills.md: Rewrote with better framing and examples
• hooks.md: Fixed timeout/error handling docs, added import aliases section
• custom-tools.md: Added intro with use cases and comparison table
• rpc.md: Added missing hook_error event documentation
• README.md: Complete settings table, condensed philosophy section, standardized OAuth docs

Hooks loader now supports same import aliases as custom tools (@sinclair/typebox, @mariozechner/pi-ai, @mariozechner/pi-tui, @mariozechner/pi-coding-agent).

Fixed Claude models via GitHub Copilot re-answering all previous prompts in multi-turn conversations. The issue was that assistant message content was sent as an array instead of a string, which Copilot's Claude adapter misinterpreted. Also added missing Openai-Intent: conversation-edits header and fixed X-Initiator logic to check for any assistant/tool message in history. (#209)

Detect image MIME type via file magic (read tool and @file attachments), not filename extension.

Fixed markdown tables overflowing terminal width. Tables now wrap cell contents to fit available width instead of breaking borders mid-row. (#206 by @kim0)

Fixed TUI performance regression caused by Box component lacking render caching. Built-in tools now use Text directly (like v0.22.5), and Box has proper caching for custom tool rendering.

Fixed custom tools failing to load from ~/.pi/agent/tools/ when pi is installed globally. Module imports (@sinclair/typebox, @mariozechner/pi-tui, @mariozechner/pi-ai) are now resolved via aliases.

Custom tools: Extend pi with custom tools written in TypeScript. Tools can provide custom TUI rendering, interact with users via pi.ui (select, confirm, input, notify), and maintain state across sessions via onSession callback. See docs/custom-tools.md and examples/custom-tools/. (#190)

Hook and tool examples: Added examples/hooks/ and examples/custom-tools/ with working examples. Examples are now bundled in npm and binary releases.