@oh-my-pi/pi-coding-agent 13.3.13 → 13.4.0

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 ## [Unreleased]
 
+## [13.4.0] - 2026-03-01
+
+### Breaking Changes
+
+- `ast_grep` parameter `pattern` (string) replaced by `patterns` (string[])
+- `ast_edit` parameters `pattern` + `rewrite` replaced by `ops: Array<{ pat: string; out: string }>`
+
+### Added
+
+- Added `resolve` tool to apply or discard pending preview actions with required reasoning
+- AST edit now registers pending actions after preview, allowing explicit apply/discard workflow via `resolve` tool
+- Custom tools can register pending actions via `pushPendingAction(action)` in `CustomToolAPI`, enabling the `resolve` workflow for custom preview-apply flows
+- `deferrable?: boolean` field added to `AgentTool`, `CustomTool`, and `ToolDefinition` interfaces; tools that set it signal they may stage pending actions
+- `HIDDEN_TOOLS` and `ResolveTool` exported from `@oh-my-pi/pi-coding-agent` SDK for manual tool composition
+- `PendingActionStore` now uses a LIFO stack (`push`/`peek`/`pop`); multiple deferrable tools can stage actions that resolve in reverse order of registration
+- Added `gemini`, `codex`, and `synthetic` as supported values for the `providers.webSearch` setting
+- `ast_grep` tool now accepts a `patterns` array (replaces single `pattern`); multiple patterns run in one native pass and results are merged before offset/limit
+- `ast_edit` tool now accepts an `ops` array of `{ pat, out }` entries (replaces `pattern` + `rewrite`); duplicate patterns are rejected upfront
+- AST find output now uses `>>` prefix on match-start lines and pads line numbers; directory-tree grouping with `# dir` / `## └─ file` headers for directory-scoped searches
+- AST replace output now renders diff-style (`-before` / `+after`) change previews grouped by directory
+- Both AST tools now report `scopePath`, `files`, and per-file match/replacement counts in tool details
+- Task item `id` max length raised from 32 to 48 characters
+- Anthropic web search provider now uses `buildAnthropicSearchHeaders` (dedicated search header builder separate from inference headers)
+- Gemini web search provider: endpoint fallback (daily → sandbox) with retry on 429/5xx
+- Gemini web search now injects Antigravity system instruction and aligned request metadata (`requestType`, `userAgent`, `requestId`) for Antigravity credentials
+- `buildGeminiRequestTools()` helper for composable Gemini tool configuration (googleSearch, codeExecution, urlContext)
+- Web search schema exposes `max_tokens`, `temperature`, and `num_search_results` as tool parameters
+- Web search provider fallback: when an explicit provider is unavailable, resolves the auto chain instead of returning empty results
+
+### Changed
+
+- Simplified `resolve` tool output rendering to use inline highlighted format instead of boxed layout
+- Updated `resolve` tool to parse source tool name from label using colon separator for cleaner display
+- `resolve` tool is now conditionally injected: included only when at least one active tool has `deferrable: true` (previously always included)
+- `discoverAndLoadCustomTools` / `loadCustomTools` accept an optional `pendingActionStore` parameter to wire `pushPendingAction` for custom tools
+- AST edit tool no longer accepts `preview` parameter; all AST edit calls now return previews by default
+- AST edit workflow changed: preview is always shown, then use `resolve` tool to apply or discard changes
+- Agent now suggests calling `resolve` tool after AST edit preview with system reminder
+- `ast_grep`: `include_meta` parameter removed; metavariable captures are now always included in output
+- `ast_edit`: `dry_run` renamed to `preview`; `max_files` removed from schema and capped globally via `$PI_MAX_AST_FILES` (default 1000); `max_replacements` renamed to `limit`
+- `ast_grep` and `ast_edit`: parse errors in tool output are now capped at `PARSE_ERRORS_LIMIT` (20); excess errors are summarised as `N / total parse issues` rather than flooding the context
+- Updated `ast_grep` and `ast_edit` tool prompt examples to use concise, idiomatic patterns
+
+### Removed
+
+- Removed `normativeRewrite` setting that rewrote tool call arguments to normalized format in session history
+- Removed `buildNormativeUpdateInput()` helper and normative patch transformation logic
+
+### Fixed
+
+- `ast_edit` no longer rejects empty `out` values; an empty string now deletes matched nodes
+- `ast_edit` no longer trims `pat` and `out` values, preserving intentional whitespace
+- `gemini_image` tool: corrected `responseModalities` values from `'Image'`/`'Text'` to uppercase `'IMAGE'`/`'TEXT'` matching the API enum
+
+## [13.3.14] - 2026-02-28
+
+### Added
+
+- Expanded AST tool language support from 7 to all 25 ast-grep tree-sitter languages (Bash, C, C++, C#, CSS, Elixir, Go, Haskell, HCL, HTML, Java, JavaScript, JSON, Kotlin, Lua, Nix, PHP, Python, Ruby, Rust, Scala, Solidity, Swift, TSX, TypeScript, YAML)
+- AST find now emits all lines of multiline matches with hashline tags (LINE#HASH:content) consistent with read/grep output
+- Added AST pattern syntax reference (metavariables, wildcards, variadics) to system prompt
+- Added examples and scoping guidance to ast-grep and ast-edit tool prompts
+- Added `provider-schema-compatibility.test.ts`: integration test that instantiates every builtin and hidden tool, runs their parameter schemas through `adaptSchemaForStrict`, `sanitizeSchemaForGoogle`, and `prepareSchemaForCCA`, and asserts zero violations against each provider's compatibility rules
+
+### Fixed
+
+- Non-code files (.md, .zip, .bin, .gitignore, etc.) are now silently skipped by AST tools instead of producing misleading parse errors
+- Fixed `grep` path wildcard handling so file patterns passed via `path` (for example `schema-review-*.test.ts`) are resolved as glob filters instead of failing path existence checks
+
 ## [13.3.11] - 2026-02-28
 
 ### Fixed
@@ -13,9 +82,9 @@
 
 ### Added
 
-- Added `ast_find` tool for structural code search using AST matching via ast-grep, enabling syntax-aware pattern discovery across codebases
-- Added `ast_replace` tool for structural AST-aware rewrites via ast-grep, enabling safe syntax-level codemods without text-based fragility
-- Added `astFind.enabled` and `astReplace.enabled` settings to control availability of AST tools
+- Added `ast_grep` tool for structural code search using AST matching via ast-grep, enabling syntax-aware pattern discovery across codebases
+- Added `ast_edit` tool for structural AST-aware rewrites via ast-grep, enabling safe syntax-level codemods without text-based fragility
+- Added `astGrep.enabled` and `astEdit.enabled` settings to control availability of AST tools
 - Added system prompt guidance to prefer AST tools over bash text manipulation (grep/sed/awk/perl) for syntax-aware operations
 - Extracted prompt formatting logic into reusable `formatPromptContent()` utility with configurable render phases and formatting options
 - Added `type_definition` action to navigate to symbol type definitions with source context
@@ -42,10 +111,10 @@
 - Updated HTML parsing API calls from `node-html-parser` to `linkedom` across all web scrapers (arXiv, IACR, Go pkg, Read the Docs, Twitter, Wikipedia)
 - Changed element text extraction from `.text` property to `.textContent` property for compatibility with linkedom DOM API
 - Optimized document link extraction to use regex-based parsing with deduplication and a 20-link limit instead of full DOM traversal
-- Unified `path` parameter in ast_find and ast_replace tools to accept files, directories, or glob patterns directly, eliminating the separate `glob` parameter
-- Removed `strictness` parameter from ast_find and ast_replace tools
-- Removed `fail_on_parse_error` parameter from ast_replace tool (now always false)
-- Updated ast_find and ast_replace prompt guidance to clarify that `path` accepts glob patterns and no longer requires separate glob specification
+- Unified `path` parameter in ast_grep and ast_edit tools to accept files, directories, or glob patterns directly, eliminating the separate `glob` parameter
+- Removed `strictness` parameter from ast_grep and ast_edit tools
+- Removed `fail_on_parse_error` parameter from ast_edit tool (now always false)
+- Updated ast_grep and ast_edit prompt guidance to clarify that `path` accepts glob patterns and no longer requires separate glob specification
 - Refactored prompt template rendering to use unified `formatPromptContent()` function with phase-aware formatting (pre-render vs post-render)
 - Updated `format-prompts.ts` script to use centralized prompt formatting utility instead of inline implementation
 - Replaced `column` parameter with `symbol` parameter for more intuitive position specification
@@ -92,6 +161,7 @@
 - Fixed `todo_write` task normalization to auto-activate the first remaining task and include explicit remaining-items output in tool results, removing the need for an immediate follow-up start update
 
 ## [13.3.7] - 2026-02-27
+
 ### Breaking Changes
 
 - Removed `preloadedSkills` option from `CreateAgentSessionOptions`; skills are no longer inlined into system prompts
@@ -125,11 +195,13 @@
 - Fixed handling of union type schemas (e.g., object|null) to normalize them into strict-mode compatible variants
 
 ## [13.3.6] - 2026-02-26
+
 ### Breaking Changes
 
 - Changed `submit_result` tool parameter structure from top-level `data` or `error` fields to nested `result` object containing either `result.data` or `result.error`
 
 ## [13.3.5] - 2026-02-26
+
 ### Added
 
 - Added support for setting array and record configuration values using JSON syntax
@@ -144,6 +216,7 @@
 - Enhanced type display in config list output to show correct type indicators for number, array, and record settings
 
 ## [13.3.3] - 2026-02-26
+
 ### Added
 
 - Support for `move` parameter in `computeHashlineDiff` to enable file move operations alongside content edits
@@ -195,13 +268,16 @@
 ## [13.2.1] - 2026-02-24
 
 ### Fixed
+
 - Fixed changelog tools to enforce category-specific arrays and reuse the shared category list for generation
 - Non-interactive environment variables (pager, editor, prompt suppression) were not applied to non-PTY bash execution, causing commands to potentially block on pagers or prompts
 
 ### Changed
 
 - Extracted non-interactive environment config from `bash-interactive.ts` into shared `non-interactive-env.ts` module, applied consistently to all bash execution paths
+
 ## [13.2.0] - 2026-02-23
+
 ### Breaking Changes
 
 - Made `description` field required in CustomTool interface
@@ -225,19 +301,24 @@
 ## [13.1.2] - 2026-02-23
 
 ### Breaking Changes
+
 - Removed `timeout` parameter from await tool—tool now waits indefinitely until jobs complete or the call is aborted
 - Renamed `job_ids` parameter to `jobs` in await tool schema
 - Removed `timedOut` field from await tool result details
 
 ### Changed
+
 - Resolved docs index generation paths using path.resolve relative to the script directory
+
 ## [13.1.1] - 2026-02-23
 
 ### Fixed
 
 - Fixed bash internal URL expansion to resolve `local://` targets to concrete filesystem paths, including newly created destination files for commands like `mv src.json local://dest.json`
 - Fixed bash local URL resolution to create missing parent directories under the session local root before command execution, preventing `mv` destination failures for new paths
+
 ## [13.1.0] - 2026-02-23
+
 ### Breaking Changes
 
 - Renamed `file` parameter to `path` in replace, patch, and hashline edit operations
@@ -254,6 +335,7 @@
 - Moved intent field documentation from per-tool JSON schema descriptions into a single system prompt block, reducing token overhead proportional to tool count
 
 ## [13.0.1] - 2026-02-22
+
 ### Changed
 
 - Simplified hashline edit schema to use unified `first`/`last` anchor fields instead of operation-specific field names (`tag`, `before`, `after`)
@@ -261,6 +343,7 @@
 - Updated hashline tool documentation to reflect new unified anchor syntax across all operations (replace, append, prepend, insert)
 
 ## [13.0.0] - 2026-02-22
+
 ### Added
 
 - Added `getTodoPhases()` and `setTodoPhases()` methods to ToolSession API for managing todo state programmatically
@@ -301,6 +384,7 @@
 - Fixed todo reminder XML tags from underscore to kebab-case format (`system-reminder`)
 
 ## [12.19.3] - 2026-02-22
+
 ### Added
 
 - Added `pty` parameter to bash tool to enable PTY mode for commands requiring a real terminal (e.g., sudo, ssh, top, less)
@@ -314,12 +398,14 @@
 - Removed `bash.virtualTerminal` setting; use the `pty` parameter on individual bash commands instead
 
 ## [12.19.1] - 2026-02-22
+
 ### Removed
 
 - Removed `replaceText` edit operation from hashline mode (substring-based text replacement)
 - Removed autocorrect heuristics that attempted to detect and fix line merges and formatting rewrites in hashline edits
 
 ## [12.19.0] - 2026-02-22
+
 ### Added
 
 - Added `poll_jobs` tool to block until background jobs complete, providing an alternative to polling `read jobs://` in loops
@@ -367,6 +453,7 @@
 - Fixed `submit_result` schema generation to use valid JSON Schema when no explicit output schema is provided
 
 ## [12.18.1] - 2026-02-21
+
 ### Added
 
 - Added Buffer.toBase64() polyfill for Bun compatibility to enable base64 encoding of buffers
@@ -395,6 +482,7 @@
 - Fixed potential race condition in bash interactive component where output could be appended after the component was closed
 
 ## [12.17.2] - 2026-02-21
+
 ### Changed
 
 - Modified bash command normalization to only apply explicit head/tail parameters from tool input, removing automatic extraction from command pipes
@@ -406,6 +494,7 @@
 - Fixed hard timeout handling to properly interrupt long-running commands that exceed the grace period beyond the configured timeout
 
 ## [12.17.1] - 2026-02-21
+
 ### Added
 
 - Added `filterBrowser` option to filter out browser automation MCP servers when builtin browser tool is enabled
@@ -414,6 +503,7 @@
 - Added `BrowserFilterResult` type for browser MCP server filtering results
 
 ## [12.17.0] - 2026-02-21
+
 ### Added
 
 - Added timeout protection (5 seconds) for system prompt preparation with graceful fallback to minimal context on timeout

package/examples/sdk/README.md

@@ -45,7 +45,9 @@ import {
 	ModelRegistry,
 	SessionManager,
 	BUILTIN_TOOLS,
+	HIDDEN_TOOLS,
 	createTools,
+	ResolveTool,
 } from "@oh-my-pi/pi-coding-agent";
 
 // Auth and models setup
@@ -104,6 +106,26 @@ session.subscribe((event) => {
 await session.prompt("Hello");
 ```
 
+## Resolve preview workflow (AST edit apply/discard)
+
+`ast_edit` now always returns a preview. To finalize, call hidden `resolve` with a required reason.
+
+- `action: "apply"` → commit pending preview changes
+- `action: "discard"` → drop pending preview changes
+- `reason: string` is required for both paths
+
+`createAgentSession()` / `createTools()` include `resolve` automatically, even when filtering `toolNames`.
+If you are composing tools manually, use `HIDDEN_TOOLS.resolve` (or `ResolveTool`) and wire the same `pendingActionStore`.
+
+```typescript
+const tools = await createTools(toolSession, ["ast_edit"]); // resolve is auto-included
+const resolveTool = tools.find(t => t.name === "resolve") as ResolveTool;
+
+await resolveTool.execute("call-1", {
+  action: "apply",
+  reason: "Preview matches expected replacements",
+});
+```
 ## Options
 
 | Option                      | Default                       | Description                       |

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "13.3.13",
+	"version": "13.4.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -41,12 +41,12 @@
 	},
 	"dependencies": {
 		"@mozilla/readability": "^0.6",
-		"@oh-my-pi/omp-stats": "13.3.13",
-		"@oh-my-pi/pi-agent-core": "13.3.13",
-		"@oh-my-pi/pi-ai": "13.3.13",
-		"@oh-my-pi/pi-natives": "13.3.13",
-		"@oh-my-pi/pi-tui": "13.3.13",
-		"@oh-my-pi/pi-utils": "13.3.13",
+		"@oh-my-pi/omp-stats": "13.4.0",
+		"@oh-my-pi/pi-agent-core": "13.4.0",
+		"@oh-my-pi/pi-ai": "13.4.0",
+		"@oh-my-pi/pi-natives": "13.4.0",
+		"@oh-my-pi/pi-tui": "13.4.0",
+		"@oh-my-pi/pi-utils": "13.4.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/capability/index.ts

@@ -419,14 +419,4 @@ export function cacheStats(): { content: number; dir: number } {
 // Re-exports
 // =============================================================================
 
-export type {
-	Capability,
-	CapabilityInfo,
-	CapabilityResult,
-	LoadContext,
-	LoadOptions,
-	LoadResult,
-	Provider,
-	ProviderInfo,
-	SourceMeta,
-} from "./types";
+export type * from "./types";

package/src/commit/analysis/index.ts

@@ -1,4 +1,4 @@
-export { generateConventionalAnalysis } from "./conventional";
-export { extractScopeCandidates } from "./scope";
-export { generateSummary, stripTypePrefix } from "./summary";
-export { validateAnalysis, validateScope, validateSummary } from "./validation";
+export * from "./conventional";
+export * from "./scope";
+export * from "./summary";
+export * from "./validation";

package/src/config/settings-schema.ts

@@ -254,15 +254,6 @@ export const SETTINGS_SCHEMA = {
 			submenu: true,
 		},
 	},
-	normativeRewrite: {
-		type: "boolean",
-		default: false,
-		ui: {
-			tab: "agent",
-			label: "Normative rewrite",
-			description: "Rewrite tool call arguments to normalized format in session history",
-		},
-	},
 	repeatToolDescriptions: {
 		type: "boolean",
 		default: false,
@@ -455,18 +446,18 @@ export const SETTINGS_SCHEMA = {
 			submenu: true,
 		},
 	},
-	"astFind.enabled": {
+	"astGrep.enabled": {
 		type: "boolean",
 		default: true,
-		ui: { tab: "tools", label: "Enable AST Find", description: "Enable the ast_find tool for structural AST search" },
+		ui: { tab: "tools", label: "Enable AST Grep", description: "Enable the ast_grep tool for structural AST search" },
 	},
-	"astReplace.enabled": {
+	"astEdit.enabled": {
 		type: "boolean",
 		default: true,
 		ui: {
 			tab: "tools",
-			label: "Enable AST Replace",
-			description: "Enable the ast_replace tool for structural AST rewrites",
+			label: "Enable AST Edit",
+			description: "Enable the ast_edit tool for structural AST rewrites",
 		},
 	},
 	"notebook.enabled": {
@@ -737,7 +728,19 @@ export const SETTINGS_SCHEMA = {
 	// ─────────────────────────────────────────────────────────────────────────
 	"providers.webSearch": {
 		type: "enum",
-		values: ["auto", "exa", "brave", "jina", "kimi", "zai", "perplexity", "anthropic"] as const,
+		values: [
+			"auto",
+			"exa",
+			"brave",
+			"jina",
+			"kimi",
+			"zai",
+			"perplexity",
+			"anthropic",
+			"gemini",
+			"codex",
+			"synthetic",
+		] as const,
 		default: "auto",
 		ui: { tab: "services", label: "Web search provider", description: "Provider for web search tool", submenu: true },
 	},

package/src/config/settings.ts

@@ -41,26 +41,8 @@ import {
 } from "./settings-schema";
 
 // Re-export types that callers need
-export type {
-	BashInterceptorRule,
-	BranchSummarySettings,
-	CommitSettings,
-	CompactionSettings,
-	ContextPromotionSettings,
-	ExaSettings,
-	GroupPrefix,
-	GroupTypeMap,
-	MemoriesSettings,
-	RetrySettings,
-	SettingPath,
-	SettingValue,
-	SkillsSettings,
-	StatusLineSettings,
-	ThinkingBudgetsSettings,
-	TodoCompletionSettings,
-	TtsrSettings,
-} from "./settings-schema";
-export { getDefault, getEnumValues, getPathsForTab, getType, getUi, hasUi } from "./settings-schema";
+export type * from "./settings-schema";
+export * from "./settings-schema";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // Types

package/src/discovery/index.ts

@@ -76,14 +76,4 @@ export type { SSHHost } from "../capability/ssh";
 export type { SystemPrompt } from "../capability/system-prompt";
 export type { CustomTool } from "../capability/tool";
 // Re-export types
-export type {
-	Capability,
-	CapabilityInfo,
-	CapabilityResult,
-	LoadContext,
-	LoadOptions,
-	LoadResult,
-	Provider,
-	ProviderInfo,
-	SourceMeta,
-} from "../capability/types";
+export type * from "../capability/types";

package/src/exa/index.ts

@@ -27,16 +27,7 @@ export const exaTools: CustomTool<any, ExaRenderDetails>[] = [
 
 export { companyTool } from "./company";
 export { linkedinTool } from "./linkedin";
-export {
-	callExaTool,
-	callWebsetsTool,
-	createMCPToolFromServer,
-	fetchMCPToolSchema,
-	findApiKey,
-	formatSearchResults,
-	isSearchResponse,
-	MCPWrappedTool,
-} from "./mcp-client";
+export * from "./mcp-client";
 export { renderExaCall, renderExaResult } from "./render";
 export { researcherTools } from "./researcher";
 // Re-export individual modules for selective importing

package/src/extensibility/custom-commands/index.ts

@@ -1,15 +1,2 @@
-export {
-	type DiscoverCustomCommandsOptions,
-	type DiscoverCustomCommandsResult,
-	discoverCustomCommands,
-	type LoadCustomCommandsOptions,
-	loadCustomCommands,
-} from "./loader";
-export type {
-	CustomCommand,
-	CustomCommandAPI,
-	CustomCommandFactory,
-	CustomCommandSource,
-	CustomCommandsLoadResult,
-	LoadedCustomCommand,
-} from "./types";
+export * from "./loader";
+export type * from "./types";

package/src/extensibility/custom-tools/index.ts

@@ -2,21 +2,6 @@
  * Custom tools module.
  */
 
-export { CustomToolLoader, discoverAndLoadCustomTools, loadCustomTools } from "./loader";
-export type {
-	AgentToolResult,
-	AgentToolUpdateCallback,
-	CustomTool,
-	CustomToolAPI,
-	CustomToolContext,
-	CustomToolFactory,
-	CustomToolResult,
-	CustomToolSessionEvent,
-	CustomToolsLoadResult,
-	CustomToolUIContext,
-	ExecResult,
-	LoadedCustomTool,
-	RenderResultOptions,
-	ToolLoadError,
-} from "./types";
-export { CustomToolAdapter } from "./wrapper";
+export * from "./loader";
+export type * from "./types";
+export * from "./wrapper";

package/src/extensibility/custom-tools/loader.ts

@@ -14,6 +14,7 @@ import type { ExecOptions } from "../../exec/exec";
 import { execCommand } from "../../exec/exec";
 import type { HookUIContext } from "../../extensibility/hooks/types";
 import { getAllPluginToolPaths } from "../../extensibility/plugins/loader";
+import type { PendingActionStore } from "../../tools/pending-action";
 import { createNoOpUIContext, resolvePath } from "../utils";
 import type { CustomToolAPI, CustomToolFactory, LoadedCustomTool, ToolLoadError } from "./types";
 
@@ -84,7 +85,7 @@ export class CustomToolLoader {
 	#sharedApi: CustomToolAPI;
 	#seenNames: Set<string>;
 
-	constructor(cwd: string, builtInToolNames: string[]) {
+	constructor(cwd: string, builtInToolNames: string[], pendingActionStore?: PendingActionStore) {
 		this.#sharedApi = {
 			cwd,
 			exec: (command: string, args: string[], options?: ExecOptions) =>
@@ -94,6 +95,18 @@ export class CustomToolLoader {
 			logger,
 			typebox,
 			pi: piCodingAgent,
+			pushPendingAction: action => {
+				if (!pendingActionStore) {
+					throw new Error("Pending action store unavailable for custom tools in this runtime.");
+				}
+				pendingActionStore.push({
+					label: action.label,
+					sourceToolName: action.sourceToolName ?? "custom_tool",
+					apply: action.apply,
+					reject: action.reject,
+					details: action.details,
+				});
+			},
 		};
 		this.#seenNames = new Set<string>(builtInToolNames);
 	}
@@ -138,8 +151,13 @@ export class CustomToolLoader {
  * @param cwd - Current working directory for resolving relative paths
  * @param builtInToolNames - Names of built-in tools to check for conflicts
  */
-export async function loadCustomTools(pathsWithSources: ToolPathWithSource[], cwd: string, builtInToolNames: string[]) {
-	const loader = new CustomToolLoader(cwd, builtInToolNames);
+export async function loadCustomTools(
+	pathsWithSources: ToolPathWithSource[],
+	cwd: string,
+	builtInToolNames: string[],
+	pendingActionStore?: PendingActionStore,
+) {
+	const loader = new CustomToolLoader(cwd, builtInToolNames, pendingActionStore);
 	await loader.load(pathsWithSources);
 	return {
 		tools: loader.tools,
@@ -160,7 +178,12 @@ export async function loadCustomTools(pathsWithSources: ToolPathWithSource[], cw
  * @param cwd - Current working directory
  * @param builtInToolNames - Names of built-in tools to check for conflicts
  */
-export async function discoverAndLoadCustomTools(configuredPaths: string[], cwd: string, builtInToolNames: string[]) {
+export async function discoverAndLoadCustomTools(
+	configuredPaths: string[],
+	cwd: string,
+	builtInToolNames: string[],
+	pendingActionStore?: PendingActionStore,
+) {
 	const allPathsWithSources: ToolPathWithSource[] = [];
 	const seen = new Set<string>();
 
@@ -193,5 +216,5 @@ export async function discoverAndLoadCustomTools(configuredPaths: string[], cwd:
 		addPath(resolvePath(configPath, cwd), { provider: "config", providerName: "Config", level: "project" });
 	}
 
-	return loadCustomTools(allPathsWithSources, cwd, builtInToolNames);
+	return loadCustomTools(allPathsWithSources, cwd, builtInToolNames, pendingActionStore);
 }

package/src/extensibility/custom-tools/types.ts

@@ -26,6 +26,20 @@ export type { AgentToolResult, AgentToolUpdateCallback };
 // Re-export for backward compatibility
 export type { ExecOptions, ExecResult } from "../../exec/exec";
 
+/** Pending action entry consumed by the hidden resolve tool */
+export interface CustomToolPendingAction {
+	/** Human-readable preview label shown in resolve flow */
+	label: string;
+	/** Apply callback invoked when resolve(action="apply") is called */
+	apply(reason: string): Promise<AgentToolResult<unknown>>;
+	/** Optional reject callback invoked when resolve(action="discard") is called */
+	reject?(reason: string): Promise<AgentToolResult<unknown> | undefined>;
+	/** Optional details metadata stored with the pending action */
+	details?: unknown;
+	/** Optional source tool name shown by resolve renderer (defaults to "custom_tool") */
+	sourceToolName?: string;
+}
+
 /** API passed to custom tool factory (stable across session changes) */
 export interface CustomToolAPI {
 	/** Current working directory */
@@ -42,6 +56,8 @@ export interface CustomToolAPI {
 	typebox: typeof import("@sinclair/typebox");
 	/** Injected pi-coding-agent exports */
 	pi: typeof import("../..");
+	/** Push a preview action that can later be resolved with the hidden resolve tool */
+	pushPendingAction(action: CustomToolPendingAction): void;
 }
 
 /**
@@ -162,7 +178,8 @@ export interface CustomTool<TParams extends TSchema = TSchema, TDetails = any> {
 	parameters: TParams;
 	/** If true, tool is excluded unless explicitly listed in --tools or agent's tools field */
 	hidden?: boolean;
-
+	/** If true, tool may stage deferred changes that require explicit resolve/discard. */
+	deferrable?: boolean;
 	/**
 	 * Execute the tool.
 	 * @param toolCallId - Unique ID for this tool call