@oh-my-pi/pi-coding-agent 15.4.3 → 15.5.1

package/src/config/model-registry.ts

@@ -900,9 +900,20 @@ export class ModelRegistry {
 
 		this.#addImplicitDiscoverableProviders(configuredProviders);
 		let builtInModels = this.#applyHardcodedModelPolicies(this.#loadBuiltInModels(overrides));
-		const cachedStandardModels = this.#applyHardcodedModelPolicies(this.#loadCachedStandardProviderModels());
+		const cachedStandardResult = this.#loadCachedStandardProviderModels();
+		const cachedStandardModels = this.#applyHardcodedModelPolicies(cachedStandardResult.models);
 		const cachedDiscoveries = this.#applyHardcodedModelPolicies(this.#loadCachedDiscoverableModels());
-		const cachedAuthoritativeProviders = providersWithAuthoritativeProjectCatalog(cachedStandardModels);
+		// Only drop bundled fallback models when the cached project-catalog row is
+		// itself fresh AND authoritative. A stale or non-authoritative snapshot
+		// (e.g. after ADC discovery failure rewrote the row with authoritative=0)
+		// must not strip bundled Vertex Gemini entries — that would leave only the
+		// stale project-scoped rows in API-key-only environments.
+		const cachedAuthoritativeProviders = new Set<string>();
+		for (const provider of providersWithAuthoritativeProjectCatalog(cachedStandardModels)) {
+			if (cachedStandardResult.authoritativeFreshProviders.has(provider)) {
+				cachedAuthoritativeProviders.add(provider);
+			}
+		}
 		if (cachedAuthoritativeProviders.size > 0) {
 			builtInModels = dropProviderModels(builtInModels, cachedAuthoritativeProviders);
 		}
@@ -1008,9 +1019,10 @@ export class ModelRegistry {
 		return merged;
 	}
 
-	#loadCachedStandardProviderModels(): Model<Api>[] {
+	#loadCachedStandardProviderModels(): { models: Model<Api>[]; authoritativeFreshProviders: Set<string> } {
 		const configuredDiscoveryProviders = new Set(this.#discoverableProviders.map(provider => provider.provider));
 		const cachedModels: Model<Api>[] = [];
+		const authoritativeFreshProviders = new Set<string>();
 		for (const descriptor of PROVIDER_DESCRIPTORS) {
 			if (configuredDiscoveryProviders.has(descriptor.providerId)) {
 				continue;
@@ -1019,6 +1031,9 @@ export class ModelRegistry {
 			if (!cache) {
 				continue;
 			}
+			if (cache.fresh && cache.authoritative) {
+				authoritativeFreshProviders.add(descriptor.providerId);
+			}
 			const models = cache.models.map(model =>
 				model.provider === descriptor.providerId ? model : { ...model, provider: descriptor.providerId },
 			);
@@ -1031,7 +1046,7 @@ export class ModelRegistry {
 				: withTransport;
 			cachedModels.push(...this.#applyProviderModelOverrides(descriptor.providerId, withCompat));
 		}
-		return cachedModels;
+		return { models: cachedModels, authoritativeFreshProviders };
 	}
 
 	#loadCachedDiscoverableModels(): Model<Api>[] {

package/src/config/prompt-templates.ts

@@ -8,7 +8,6 @@ import {
 	parseFrontmatter,
 	prompt,
 } from "@oh-my-pi/pi-utils";
-import { HL_LINE_BODY_SEP } from "../hashline/hash";
 import { jtdToTypeScript } from "../tools/jtd-to-typescript";
 import { parseCommandArgs, substituteArgs } from "../utils/command-args";
 
@@ -30,130 +29,6 @@ prompt.registerHelper("jtdToTypeScript", (schema: unknown): string => {
 	}
 });
 
-function formatHashlineRef(lineNum: unknown, content: unknown): { num: number; text: string; ref: string } {
-	const num = typeof lineNum === "number" ? lineNum : Number.parseInt(String(lineNum), 10);
-	const raw = typeof content === "string" ? content : String(content ?? "");
-	const text = raw.replace(/\\t/g, "\t").replace(/\\n/g, "\n").replace(/\\r/g, "\r");
-	const ref = `${num}`;
-	return { num, text, ref };
-}
-
-interface HashlineHelperRef {
-	line: number;
-	ref: string;
-}
-
-interface HashlineHelperState {
-	last?: HashlineHelperRef;
-	byLine: Map<number, HashlineHelperRef>;
-}
-
-const HL_HELPER_STATE = Symbol("hashlineHelperState");
-
-interface HashlineHelperStateHolder {
-	[HL_HELPER_STATE]?: HashlineHelperState;
-}
-
-function isHelperOptions(value: unknown): value is prompt.HelperOptions {
-	return typeof value === "object" && value !== null && "hash" in value;
-}
-
-function splitHelperArgs(args: unknown[]): { positional: unknown[]; options?: prompt.HelperOptions } {
-	const maybeOptions = args.at(-1);
-	if (!isHelperOptions(maybeOptions)) return { positional: args };
-	return { positional: args.slice(0, -1), options: maybeOptions };
-}
-
-function getHashlineHelperState(context: unknown, options: prompt.HelperOptions | undefined): HashlineHelperState {
-	const data = options?.data;
-	const root = data?.root;
-	const holderTarget = data && typeof data === "object" ? data : root && typeof root === "object" ? root : context;
-	if (!holderTarget || typeof holderTarget !== "object") {
-		throw new Error("hashline prompt helpers require an object render context");
-	}
-
-	const holder = holderTarget as HashlineHelperStateHolder;
-	if (!holder[HL_HELPER_STATE]) {
-		holder[HL_HELPER_STATE] = { byLine: new Map() };
-	}
-	return holder[HL_HELPER_STATE];
-}
-
-function isLineNumberArg(value: unknown): boolean {
-	const num = typeof value === "number" ? value : Number.parseInt(String(value), 10);
-	return Number.isFinite(num);
-}
-
-function rememberHashlineRef(state: HashlineHelperState, line: number, ref: string): void {
-	const entry = { line, ref };
-	state.last = entry;
-	state.byLine.set(line, entry);
-}
-
-function requireStoredHashlineRef(state: HashlineHelperState, lineArg?: unknown): string {
-	if (lineArg === undefined) {
-		if (!state.last) {
-			throw new Error("{{href}} requires a previous {{hline}} call in the same prompt render");
-		}
-		return state.last.ref;
-	}
-
-	const line = typeof lineArg === "number" ? lineArg : Number.parseInt(String(lineArg), 10);
-	const entry = state.byLine.get(line);
-	if (!entry) {
-		throw new Error(`{{href ${line}}} requires a previous {{hline ${line} ...}} call in the same prompt render`);
-	}
-	return entry.ref;
-}
-
-function wrapHashlineRef(ref: string, args: unknown[]): string {
-	const preStr = typeof args[0] === "string" ? args[0] : "";
-	const postStr = typeof args[1] === "string" ? args[1] : "";
-	return `${preStr}${ref}${postStr}`;
-}
-
-function resolveHashlineRef(state: HashlineHelperState, args: unknown[]): string {
-	if (args.length === 0) return requireStoredHashlineRef(state);
-	const [first, second, ...rest] = args;
-	if (isLineNumberArg(first)) {
-		if (second === undefined) return requireStoredHashlineRef(state, first);
-		const { ref } = formatHashlineRef(first, second);
-		return wrapHashlineRef(ref, rest);
-	}
-	return wrapHashlineRef(requireStoredHashlineRef(state), args);
-}
-
-/**
- * {{href lineNum "content"}} — compute a hashline line ref for prompt examples.
- * {{href lineNum}} — quote the ref remembered by the earlier {{hline lineNum "..."}}
- * {{href}} — quote the ref from the previous {{hline}} call.
- * {{href "[" "]"}} — wrap the previous {{hline}} ref with pre/post chars.
- * Returns `"lineNum"` (e.g., `"42"`), or `"[42]"` when pre/post are supplied.
- */
-prompt.registerHelper("href", function (this: unknown, ...args: unknown[]): string {
-	const { positional, options } = splitHelperArgs(args);
-	const state = getHashlineHelperState(this, options);
-	return JSON.stringify(resolveHashlineRef(state, positional));
-});
-prompt.registerHelper("hrefr", function (this: unknown, ...args: unknown[]): string {
-	const { positional, options } = splitHelperArgs(args);
-	const state = getHashlineHelperState(this, options);
-	return resolveHashlineRef(state, positional);
-});
-
-/**
- * {{hline lineNum "content"}} — format a full read-style line with prefix.
- * Returns `"lineNum:content"` (colon between line number and content).
- */
-prompt.registerHelper("hline", function (this: unknown, ...args: unknown[]): string {
-	const { positional, options } = splitHelperArgs(args);
-	const [lineNum, content] = positional;
-	const { num, ref, text } = formatHashlineRef(lineNum, content);
-	const state = getHashlineHelperState(this, options);
-	rememberHashlineRef(state, num, ref);
-	return `${ref}${HL_LINE_BODY_SEP}${text}`;
-});
-
 const INLINE_ARG_SHELL_PATTERN = /\$(?:ARGUMENTS|@(?:\[\d+(?::\d*)?\])?|\d+)/;
 const INLINE_ARG_TEMPLATE_PATTERN = /\{\{[\s\S]*?(?:\b(?:arguments|ARGUMENTS|args)\b|\barg\s+[^}]+)[\s\S]*?\}\}/;
 

package/src/config/settings-schema.ts

@@ -1574,7 +1574,8 @@ export const SETTINGS_SCHEMA = {
 		ui: {
 			tab: "editing",
 			label: "Hashline Duplicate Insert Drop",
-			description: "Drop 2+ pure-insert payload lines that duplicate adjacent file context",
+			description:
+				"Drop payload lines that duplicate adjacent file context — 2+-line context echoes on `↑`/`↓` inserts, and a single boundary line at either edge of an `A-B:` replacement",
 		},
 	},
 	"edit.blockAutoGenerated": {
@@ -1789,6 +1790,53 @@ export const SETTINGS_SCHEMA = {
 	// Tools
 	// ────────────────────────────────────────────────────────────────────────
 
+	// Tool approval policies
+	"tools.approval": {
+		type: "record",
+		default: {},
+		ui: {
+			tab: "tools",
+			label: "Tool Approval Policies",
+			description:
+				"Per-tool approval policies. Set to 'allow' to auto-approve, 'prompt' to require confirmation, or 'deny' to block. Overrides are honored in every approval mode.",
+		},
+	},
+
+	// Default tool approval mode (interaction tab, but governs the tool wrapper).
+	//   "always-ask" — auto-approves read-tier tools only; prompts for write/exec.
+	//   "write"      — auto-approves read and write-tier tools; prompts for exec.
+	//   "yolo"       — auto-approves every tier unless a tool declares `override: true`.
+	"tools.approvalMode": {
+		type: "enum",
+		values: ["always-ask", "write", "yolo"] as const,
+		default: "yolo",
+		ui: {
+			tab: "interaction",
+			label: "Tool Approval",
+			description:
+				"Default approval behaviour for tool calls. 'Always ask' auto-approves read-only tools only. 'Write' auto-approves read and workspace-write tools. 'Yolo' auto-approves every tier unless a tool declares a safety override. `tools.approval.<tool>` overrides are honored in every mode.",
+			options: [
+				{
+					value: "always-ask",
+					label: "Always ask",
+					description: "Auto-approve read-only tools; require confirmation for write and exec tools.",
+				},
+				{
+					value: "write",
+					label: "Write",
+					description:
+						"Auto-approve read-only and write tools; require confirmation for exec tools such as bash, eval, browser, task, recipe, and ssh.",
+				},
+				{
+					value: "yolo",
+					label: "Yolo",
+					description:
+						"Auto-approve read, write, and exec tools. Safety overrides declared by tools (for example critical bash patterns) still require confirmation.",
+				},
+			],
+		},
+	},
+
 	// Todo tool
 	"todo.enabled": {
 		type: "boolean",
@@ -2477,6 +2525,16 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"task.showResolvedModelBadge": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "appearance",
+			label: "Show Resolved Model Badge",
+			description: "Display the actual model ID used by each subagent in the task widget status line",
+		},
+	},
+
 	// Skills
 	"skills.enabled": { type: "boolean", default: true },
 

package/src/config/settings.ts

@@ -100,7 +100,6 @@ function setByPath(obj: RawSettings, segments: string[], value: unknown): void {
 }
 
 const PATH_SCOPED_ARRAY_SETTINGS = new Set<SettingPath>(["enabledModels", "disabledProviders"]);
-
 type PathScopedStringArrayEntry = {
 	path?: unknown;
 	paths?: unknown;
@@ -218,6 +217,8 @@ export class Settings {
 			for (const [key, value] of Object.entries(options.overrides)) {
 				setByPath(this.#overrides, key.split("."), value);
 			}
+
+			this.#overrides = this.#migrateRawSettings(this.#overrides);
 		}
 	}
 

package/src/dap/session.ts

@@ -108,14 +108,28 @@ function toErrorMessage(value: unknown): string {
 interface DapStartRequestFailure {
 	rejected: boolean;
 	error?: unknown;
+	/**
+	 * Resolves (never rejects) when the underlying launch/attach request
+	 * settles either way. Set by {@link trackDapStartRequest} on each call,
+	 * so a single failure object must not be reused across launch attempts.
+	 * Consumed by {@link throwPreferredDapStartError} to bound how long to
+	 * wait for a delayed adapter-side rejection before falling back to the
+	 * cascade error from configurationDone.
+	 */
+	settled?: Promise<void>;
 }
 
 function trackDapStartRequest<T>(promise: Promise<T>, failure: DapStartRequestFailure): Promise<T> {
-	return promise.catch(error => {
+	const tracked = promise.catch(error => {
 		failure.rejected = true;
 		failure.error = error;
 		throw error;
 	});
+	failure.settled = tracked.then(
+		() => {},
+		() => {},
+	);
+	return tracked;
 }
 
 function combineDapStartErrors(command: "launch" | "attach", startError: unknown, configurationError: unknown): Error {
@@ -134,12 +148,27 @@ async function throwPreferredDapStartError(
 	startFailure: DapStartRequestFailure,
 	configurationError: unknown,
 ): Promise<never> {
-	await Promise.resolve();
+	await Promise.race([startFailure.settled ?? Promise.resolve(), timers.setTimeout(50)]);
 	if (startFailure.rejected) {
 		throw combineDapStartErrors(command, startFailure.error, configurationError);
 	}
 	throw configurationError;
 }
+
+const DEBUGPY_MISSING_MODULE_RE = /No module named ['"]?debugpy['"]?/;
+
+/**
+ * Map a generic adapter-side failure into the targeted `pip install debugpy`
+ * hint when the adapter is debugpy and stderr/the wrapping error mentions
+ * the missing module. Returns null when the heuristic does not apply, so the
+ * caller can rethrow the original error untouched.
+ */
+function mapDebugpyMissingModule(adapterName: string, error: unknown): Error | null {
+	if (adapterName !== "debugpy") return null;
+	if (!DEBUGPY_MISSING_MODULE_RE.test(toErrorMessage(error))) return null;
+	return new Error("adapter 'debugpy' is not available: install with 'pip install debugpy'");
+}
+
 function normalizePath(filePath: string): string {
 	return path.resolve(filePath);
 }
@@ -274,6 +303,8 @@ export class DapSessionManager {
 			return buildSummary(session);
 		} catch (error) {
 			await this.#disposeSession(session);
+			const mapped = mapDebugpyMissingModule(options.adapter.name, error);
+			if (mapped) throw mapped;
 			throw error;
 		}
 	}
@@ -330,6 +361,8 @@ export class DapSessionManager {
 			return buildSummary(session);
 		} catch (error) {
 			await this.#disposeSession(session);
+			const mapped = mapDebugpyMissingModule(options.adapter.name, error);
+			if (mapped) throw mapped;
 			throw error;
 		}
 	}

package/src/discovery/builtin.ts

@@ -132,7 +132,7 @@ async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>>
 			if (serverConfig.timeout === undefined || serverConfig.timeout === null) {
 				timeout = undefined;
 			} else if (typeof serverConfig.timeout === "number") {
-				if (Number.isFinite(serverConfig.timeout) && serverConfig.timeout > 0) {
+				if (Number.isFinite(serverConfig.timeout) && serverConfig.timeout >= 0) {
 					timeout = serverConfig.timeout;
 				} else {
 					logger.warn(`MCP server "${serverName}": invalid timeout ${serverConfig.timeout}, ignoring`);
@@ -140,7 +140,7 @@ async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>>
 				}
 			} else if (typeof serverConfig.timeout === "string") {
 				const parsed = Number(serverConfig.timeout);
-				if (Number.isFinite(parsed) && parsed > 0) {
+				if (Number.isFinite(parsed) && parsed >= 0) {
 					timeout = parsed;
 				} else {
 					logger.warn(`MCP server "${serverName}": invalid timeout "${serverConfig.timeout}", ignoring`);

package/src/discovery/mcp-json.ts

@@ -74,7 +74,7 @@ function transformMCPConfig(config: MCPConfigFile, source: SourceMeta): MCPServe
 				if (
 					typeof serverConfig.timeout === "number" &&
 					Number.isFinite(serverConfig.timeout) &&
-					serverConfig.timeout > 0
+					serverConfig.timeout >= 0
 				) {
 					timeout = serverConfig.timeout;
 				} else {

package/src/edit/index.ts

@@ -20,6 +20,8 @@ import hashlineDescription from "../prompts/tools/hashline.md" with { type: "tex
 import patchDescription from "../prompts/tools/patch.md" with { type: "text" };
 import replaceDescription from "../prompts/tools/replace.md" with { type: "text" };
 import type { ToolSession } from "../tools";
+import { truncateForPrompt } from "../tools/approval";
+import { isInternalUrlPath } from "../tools/path-utils";
 import { type EditMode, normalizeEditMode, resolveEditMode } from "../utils/edit-mode";
 import { type ApplyPatchParams, applyPatchSchema, expandApplyPatchToEntries } from "./modes/apply-patch";
 import applyPatchGrammar from "./modes/apply-patch.lark" with { type: "text" };
@@ -266,7 +268,31 @@ async function executeSinglePathEntries(
 	};
 }
 
+function extractApprovalPath(args: unknown): string {
+	const record = args && typeof args === "object" ? (args as Record<string, unknown>) : {};
+	const targetPath = record.path;
+	if (typeof targetPath === "string" && targetPath.length > 0) {
+		return targetPath;
+	}
+
+	const input = typeof record.input === "string" ? record.input : undefined;
+	if (!input) return "(unknown)";
+
+	const hashlineMatch = /^(?:¶|§|@)([^\s#]+)/m.exec(input);
+	if (hashlineMatch?.[1]) return hashlineMatch[1];
+
+	const applyPatchMatch = /^\*\*\* (?:Add|Update|Delete) File:\s*(.+)$/m.exec(input);
+	return applyPatchMatch?.[1]?.trim() || "(unknown)";
+}
+
 export class EditTool implements AgentTool<TInput> {
+	readonly approval = (args: unknown) => {
+		const targetPath = extractApprovalPath(args);
+		return targetPath !== "(unknown)" && isInternalUrlPath(targetPath) ? "read" : "write";
+	};
+	readonly formatApprovalDetails = (args: unknown): string[] => [
+		`File: ${truncateForPrompt(extractApprovalPath(args))}`,
+	];
 	readonly name = "edit";
 	readonly label = "Edit";
 	readonly loadMode = "essential";

package/src/edit/modes/patch.ts

@@ -1763,7 +1763,7 @@ export async function executePatchSingle(
 			postEditContent.length === preEditContent.length &&
 			postEditContent.every((b, i) => b === preEditContent[i]);
 		if (unchanged) {
-			throw new ToolError(`edit appeared successful but file content did not change on disk: ${resolvedPath}`, {
+			throw new ToolError(`edit appeared successful but file content did not change on disk: ${path}`, {
 				path: resolvedPath,
 			});
 		}

package/src/edit/streaming.ts

@@ -386,14 +386,24 @@ function buildHashlineNaturalOrderPreviews(
 			case "envelope-begin":
 			case "envelope-end":
 			case "abort":
-			case "op-insert":
-			case "op-replace":
 			case "op-delete":
 				continue;
 			case "header":
 				currentPath = token.path;
 				if (currentPath) ensure(currentPath);
 				continue;
+			case "op-insert":
+			case "op-replace":
+				// Inline body on the op line itself (`N↓payload`, `A-B:payload`) is
+				// payload content that just happens to share a line with the op
+				// header — render it the same as a standalone payload token so
+				// the very first character the model types after the sigil shows
+				// up in the streaming preview. Without this, the preview is
+				// empty until a newline arrives, and the renderer falls back to
+				// raw input ("A-B: bla bla bla") instead of "+ bla bla bla".
+				if (!currentPath || token.inlineBody === undefined) continue;
+				ensure(currentPath).push(`+${token.inlineBody}`);
+				continue;
 			case "blank":
 				if (!currentPath) continue;
 				ensure(currentPath).push("+");

package/src/exec/bash-executor.ts

@@ -4,7 +4,8 @@
  * Uses brush-core via native bindings for shell execution.
  */
 import * as fs from "node:fs/promises";
-import { executeShell, type MinimizerOptions, Shell } from "@oh-my-pi/pi-natives";
+import { ExponentialYield } from "@oh-my-pi/pi-agent-core/utils/yield";
+import { executeShell, type MinimizerOptions, Shell, type ShellRunResult } from "@oh-my-pi/pi-natives";
 import { Settings, type ShellMinimizerSettings } from "../config/settings";
 import { OutputSink } from "../session/streaming-output";
 import { resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../tools/output-meta";
@@ -196,7 +197,10 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 					},
 				);
 
-		const winner = await Promise.race([
+		const ey = new ExponentialYield();
+		const winner = await ey.race<
+			{ kind: "result"; result: ShellRunResult } | { kind: "timeout" } | { kind: "abort" }
+		>([
 			runPromise.then(result => ({ kind: "result" as const, result })),
 			timeoutDeferred.promise.then(kind => ({ kind })),
 			abortDeferred.promise.then(kind => ({ kind })),

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

@@ -14,6 +14,8 @@
 import { prompt } from "@oh-my-pi/pi-utils";
 import type { CustomCommand, CustomCommandAPI } from "../../../../extensibility/custom-commands/types";
 import type { HookCommandContext } from "../../../../extensibility/hooks/types";
+import reviewCustomRequestTemplate from "../../../../prompts/review-custom-request.md" with { type: "text" };
+import reviewHeadlessRequestTemplate from "../../../../prompts/review-headless-request.md" with { type: "text" };
 import reviewRequestTemplate from "../../../../prompts/review-request.md" with { type: "text" };
 import * as git from "../../../../utils/git";
 
@@ -225,6 +227,14 @@ function buildReviewPrompt(mode: string, stats: DiffStats, rawDiff: string, addi
 	});
 }
 
+function buildCustomReviewPrompt(instructions: string): string {
+	return prompt.render(reviewCustomRequestTemplate, { instructions });
+}
+
+function buildHeadlessReviewPrompt(focus?: string): string {
+	return prompt.render(reviewHeadlessRequestTemplate, { focus });
+}
+
 export class ReviewCommand implements CustomCommand {
 	name = "review";
 	description = "Launch interactive code review";
@@ -233,8 +243,7 @@ export class ReviewCommand implements CustomCommand {
 
 	async execute(args: string[], ctx: HookCommandContext): Promise<string | undefined> {
 		if (!ctx.hasUI) {
-			const base = "Use the Task tool to run the 'reviewer' agent to review recent code changes.";
-			return args.length > 0 ? `${base} Focus: ${args.join(" ")}` : base;
+			return buildHeadlessReviewPrompt(args.length > 0 ? args.join(" ") : undefined);
 		}
 
 		// Inline args act as additional instructions appended to the generated prompt.
@@ -379,7 +388,12 @@ export class ReviewCommand implements CustomCommand {
 
 			case 4: {
 				// Custom instructions - still uses the old approach since user provides context
-				const instructions = await ctx.ui.editor("Enter custom review instructions", "Review the following:\n\n");
+				const instructions = await ctx.ui.editor(
+					"Enter custom review instructions",
+					"Review the following:\n\n",
+					undefined,
+					{ promptStyle: true },
+				);
 				if (!instructions?.trim()) return undefined;
 
 				// For custom, we still try to get current diff for context
@@ -402,17 +416,7 @@ export class ReviewCommand implements CustomCommand {
 					);
 				}
 
-				// No diff available, just pass instructions
-				return `## Code Review Request
-
-### Mode
-Custom review instructions
-
-### Instructions
-
-${instructions}
-
-Use the Task tool with \`agent: "reviewer"\` to execute this review.`;
+				return buildCustomReviewPrompt(instructions);
 			}
 
 			default:

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

@@ -4,7 +4,13 @@
  * Custom tools are TypeScript modules that define additional tools for the agent.
  * They can provide custom rendering for tool calls and results in the TUI.
  */
-import type { AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type {
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	ToolApproval,
+	ToolApprovalDecision,
+	ToolTier,
+} from "@oh-my-pi/pi-agent-core";
 import type { CompactionResult } from "@oh-my-pi/pi-agent-core/compaction";
 import type { Model, Static, TSchema } from "@oh-my-pi/pi-ai";
 import type { Component } from "@oh-my-pi/pi-tui";
@@ -23,7 +29,7 @@ export type CustomToolUIContext = HookUIContext;
 // Re-export for backward compatibility
 export type { ExecOptions, ExecResult } from "../../exec/exec";
 /** Re-export for custom tools to use in execute signature */
-export type { AgentToolResult, AgentToolUpdateCallback };
+export type { AgentToolResult, AgentToolUpdateCallback, ToolApproval, ToolApprovalDecision, ToolTier };
 
 /** Pending action entry consumed by the hidden resolve tool */
 export interface CustomToolPendingAction {
@@ -80,6 +86,8 @@ export interface CustomToolContext {
 	abort(): void;
 	/** Settings instance for the current session. Prefer over the global singleton. */
 	settings?: Settings;
+	/** Whether to auto-approve all destructive tool operations (--auto-approve CLI flag) */
+	autoApprove?: boolean;
 }
 
 /** Session event passed to onSession callback */
@@ -191,6 +199,12 @@ export interface CustomTool<TParams extends TSchema = TSchema, TDetails = any> {
 	mcpServerName?: string;
 	/** Original MCP tool name for discovery/search metadata. */
 	mcpToolName?: string;
+
+	/** Capability tier declaration used by approval gates. Omitted means "exec". */
+	approval?: ToolApproval;
+
+	/** Lines appended after the standard approval prompt header. */
+	formatApprovalDetails?: (args: unknown) => string | string[] | undefined;
 	/**
 	 * Execute the tool.
 	 * @param toolCallId - Unique ID for this tool call

package/src/extensibility/extensions/wrapper.ts

@@ -3,7 +3,9 @@
  */
 import type { AgentTool, AgentToolContext, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
 import type { ImageContent, Static, TextContent, TSchema } from "@oh-my-pi/pi-ai";
+import type { Settings } from "../../config/settings";
 import type { Theme } from "../../modes/theme/theme";
+import { type ApprovalMode, formatApprovalPrompt, requiresApproval } from "../../tools/approval";
 import { applyToolProxy } from "../tool-proxy";
 import type { ExtensionRunner } from "./runner";
 import type { RegisteredTool, ToolCallEventResult } from "./types";
@@ -108,7 +110,40 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 		onUpdate?: AgentToolUpdateCallback<TDetails, TParameters>,
 		context?: AgentToolContext,
 	) {
-		// Emit tool_call event - extensions can block execution
+		// 1. Check approval policy (before extension handlers).
+		// CLI `--auto-approve` / `--yolo` forces yolo mode for the session, but
+		// tool-level safety overrides still prompt. User `tools.approval.<tool>`
+		// policies are honored in every mode.
+		const cliAutoApprove = context?.autoApprove === true;
+		const settings: Settings | undefined = context?.settings;
+		const configuredMode = (settings?.get("tools.approvalMode") ?? "yolo") as ApprovalMode;
+		const approvalMode: ApprovalMode = cliAutoApprove ? "yolo" : configuredMode;
+		const userPolicies = (settings?.get("tools.approval") ?? {}) as Record<string, unknown>;
+		const approvalCheck = requiresApproval(this.tool, params, approvalMode, userPolicies);
+
+		if (approvalCheck.required) {
+			// Check if UI is available
+			if (!this.runner.hasUI()) {
+				throw new Error(
+					`Tool "${this.tool.name}" requires approval but no interactive UI available.\n` +
+						`Options:\n` +
+						`  1. Set tools.approvalMode: yolo in /settings\n` +
+						`  2. Add tools.approval.${this.tool.name}: allow to config\n` +
+						`  3. Use an interactive UI to approve the tool call`,
+				);
+			}
+
+			const uiContext = this.runner.getUIContext();
+			const choice = await uiContext.select(formatApprovalPrompt(this.tool, params, approvalCheck.reason), [
+				"Approve",
+				"Deny",
+			]);
+			if (choice !== "Approve") {
+				throw new Error(`Tool call denied by user: ${this.tool.name}`);
+			}
+		}
+
+		// 2. Emit tool_call event - extensions can block execution
 		if (this.runner.hasHandlers("tool_call")) {
 			try {
 				const callResult = (await this.runner.emitToolCall({