Changelog

Compaction hook improvements: The before_compact session event now includes:

• previousSummary: Summary from the last compaction (if any), so hooks can preserve accumulated context
• messagesToKeep: Messages that will be kept after the summary (recent turns), in addition to messagesToSummarize
• resolveApiKey: Function to resolve API keys for any model (checks settings, OAuth, env vars)
• Removed apiKey string in favor of resolveApiKey for more flexibility

SessionManager API cleanup:

• Renamed loadSessionFromEntries() to buildSessionContext() (builds LLM context from entries, handling compaction)
• Renamed loadEntries() to getEntries() (returns defensive copy of all session entries)
• Added buildSessionContext() method to SessionManager

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