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

package/src/tools/approval.ts

@@ -0,0 +1,185 @@
+/**
+ * Tool approval resolution.
+ *
+ * Approval policy is declared by each tool. This module only knows how to:
+ * - normalize user `tools.approval.<tool>: allow | deny | prompt` overrides,
+ * - compare a tool capability tier against the active approval mode,
+ * - format the generic approval prompt body.
+ */
+import type { AgentTool, ToolApprovalDecision, ToolTier } from "@oh-my-pi/pi-agent-core";
+
+export type { ToolApproval, ToolApprovalDecision, ToolTier } from "@oh-my-pi/pi-agent-core";
+
+export type ApprovalPolicy = "allow" | "deny" | "prompt";
+export type ApprovalMode = "always-ask" | "write" | "yolo";
+
+type ApprovalSubject = Pick<AgentTool, "name" | "approval" | "formatApprovalDetails">;
+
+export interface ResolvedApproval {
+	policy: ApprovalPolicy;
+	tier: ToolTier;
+	reason?: string;
+	override: boolean;
+}
+
+const POLICY_VALUES: ReadonlySet<ApprovalPolicy> = new Set(["allow", "deny", "prompt"]);
+const TIER_VALUES: ReadonlySet<ToolTier> = new Set(["read", "write", "exec"]);
+
+const TIER_RANK: Record<ToolTier, number> = {
+	read: 0,
+	write: 1,
+	exec: 2,
+};
+
+const APPROVAL_MODE_MAX_TIER: Record<ApprovalMode, ToolTier> = {
+	"always-ask": "read",
+	write: "write",
+	yolo: "exec",
+};
+
+const DEFAULT_PROMPT_TRUNCATE_CHARS = 2000;
+
+/** Best-effort conversion of an arbitrary user-supplied value to a policy. */
+function normalizePolicy(value: unknown): ApprovalPolicy | undefined {
+	if (typeof value !== "string") return undefined;
+	const lowered = value.trim().toLowerCase();
+	return POLICY_VALUES.has(lowered as ApprovalPolicy) ? (lowered as ApprovalPolicy) : undefined;
+}
+
+function isToolTier(value: unknown): value is ToolTier {
+	return typeof value === "string" && TIER_VALUES.has(value as ToolTier);
+}
+
+function normalizeDecision(value: unknown): Omit<ResolvedApproval, "policy"> {
+	if (isToolTier(value)) {
+		return { tier: value, override: false };
+	}
+
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const record = value as Record<string, unknown>;
+		const tier = isToolTier(record.tier) ? record.tier : "exec";
+		const reason = typeof record.reason === "string" && record.reason.length > 0 ? record.reason : undefined;
+		return {
+			tier,
+			override: record.override === true,
+			...(reason ? { reason } : {}),
+		};
+	}
+
+	return { tier: "exec", override: false };
+}
+
+function getToolDecision(tool: ApprovalSubject, args: unknown): Omit<ResolvedApproval, "policy"> {
+	const approval = tool.approval;
+	const decision: ToolApprovalDecision | undefined = typeof approval === "function" ? approval(args) : approval;
+	return normalizeDecision(decision);
+}
+
+function modeApprovesTier(mode: ApprovalMode, tier: ToolTier): boolean {
+	return TIER_RANK[tier] <= TIER_RANK[APPROVAL_MODE_MAX_TIER[mode]];
+}
+
+/**
+ * Resolve approval policy for a tool call.
+ *
+ * Resolution order:
+ *  1. Tool `approval(args)` decision, defaulting to tier "exec" when omitted.
+ *  2. User per-tool override, if set and valid.
+ *  3. Active mode tier comparison.
+ *
+ * Tool decisions with `override: true` force a prompt in every mode unless the
+ * user explicitly denies the tool; deny remains the strongest policy.
+ */
+export function resolveApproval(
+	tool: ApprovalSubject,
+	args: unknown,
+	mode: ApprovalMode,
+	userConfig: Record<string, unknown> = {},
+): ResolvedApproval {
+	const decision = getToolDecision(tool, args);
+	const userPolicy = Object.hasOwn(userConfig, tool.name) ? normalizePolicy(userConfig[tool.name]) : undefined;
+
+	if (decision.override) {
+		if (userPolicy === "deny") {
+			return { policy: "deny", tier: decision.tier, override: true };
+		}
+		return {
+			policy: "prompt",
+			tier: decision.tier,
+			override: true,
+			...(decision.reason ? { reason: decision.reason } : {}),
+		};
+	}
+
+	if (userPolicy) {
+		return { policy: userPolicy, tier: decision.tier, override: false };
+	}
+
+	if (modeApprovesTier(mode, decision.tier)) {
+		return { policy: "allow", tier: decision.tier, override: false };
+	}
+
+	return {
+		policy: "prompt",
+		tier: decision.tier,
+		override: false,
+		...(decision.reason ? { reason: decision.reason } : {}),
+	};
+}
+
+/**
+ * Check if a tool call requires user approval.
+ *
+ * @throws Error if policy is 'deny'
+ * @returns Object with required flag and optional reason for the prompt
+ */
+export function requiresApproval(
+	tool: ApprovalSubject,
+	args: unknown,
+	mode: ApprovalMode,
+	userConfig: Record<string, unknown> = {},
+): { required: boolean; reason?: string } {
+	const { policy, reason } = resolveApproval(tool, args, mode, userConfig);
+
+	if (policy === "deny") {
+		throw new Error(
+			`Tool "${tool.name}" is blocked by user policy.\n` +
+				`To allow: remove "tools.approval.${tool.name}: deny" from config.`,
+		);
+	}
+
+	if (policy === "prompt") return { required: true, reason };
+	return { required: false };
+}
+
+export function truncateForPrompt(value: string, maxChars = DEFAULT_PROMPT_TRUNCATE_CHARS): string {
+	if (value.length <= maxChars) return value;
+	const omitted = value.length - maxChars;
+	return `${value.slice(0, maxChars)}… (${omitted} chars truncated)`;
+}
+
+/**
+ * Format the approval prompt body shown to the user.
+ */
+export function formatApprovalPrompt(tool: ApprovalSubject, args: unknown, reason?: string): string {
+	const lines = [`Allow tool: ${tool.name}`];
+
+	if (tool.name.startsWith("mcp__") && tool.approval === undefined) {
+		lines.push("Origin: MCP server tool");
+	}
+
+	if (reason) {
+		lines.push(`Reason: ${reason}`);
+	}
+
+	const details = tool.formatApprovalDetails?.(args);
+	if (typeof details === "string") {
+		if (details.length > 0) lines.push(details);
+	} else if (Array.isArray(details)) {
+		for (const detail of details) {
+			if (detail.length > 0) lines.push(detail);
+		}
+	}
+
+	return lines.join("\n");
+}

package/src/tools/ask.ts

@@ -378,6 +378,7 @@ type AskParams = AskToolInput;
  */
 export class AskTool implements AgentTool<typeof askSchema, AskToolDetails> {
 	readonly name = "ask";
+	readonly approval = "read" as const;
 	readonly label = "Ask";
 	readonly summary = "Ask the user a clarifying question";
 	readonly description: string;

package/src/tools/ast-edit.ts

@@ -12,10 +12,11 @@ import astEditDescription from "../prompts/tools/ast-edit.md" with { type: "text
 import { Ellipsis, fileHyperlink, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
+import { truncateForPrompt } from "./approval";
 import { createFileRecorder, formatResultPath } from "./file-recorder";
 import { formatGroupedFiles } from "./grouped-file-output";
 import type { OutputMeta } from "./output-meta";
-import { resolveToolSearchScope } from "./path-utils";
+import { isInternalUrlPath, resolveToolSearchScope } from "./path-utils";
 import {
 	appendParseErrorsBulletList,
 	capParseErrors,
@@ -162,6 +163,29 @@ export interface AstEditToolDetails {
 
 export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolDetails> {
 	readonly name = "ast_edit";
+	readonly approval = (args: unknown) => {
+		const paths = Array.isArray((args as Partial<z.infer<typeof astEditSchema>>).paths)
+			? ((args as Partial<z.infer<typeof astEditSchema>>).paths as string[])
+			: [];
+		return paths.length > 0 && paths.every(path => isInternalUrlPath(path)) ? "read" : "write";
+	};
+	readonly formatApprovalDetails = (args: unknown): string[] => {
+		const params = args as Partial<z.infer<typeof astEditSchema>>;
+		const lines: string[] = [];
+		const ops = Array.isArray(params.ops) ? params.ops : [];
+		const firstOp = ops[0];
+		if (firstOp) {
+			lines.push(`Pattern: ${truncateForPrompt(firstOp.pat)}`);
+			lines.push(`Replacement: ${truncateForPrompt(firstOp.out)}`);
+			if (ops.length > 1) {
+				lines.push(`+${ops.length - 1} more op${ops.length === 2 ? "" : "s"}`);
+			}
+		}
+		if (Array.isArray(params.paths) && params.paths.length > 0) {
+			lines.push(`Paths: ${truncateForPrompt(params.paths.join(", "))}`);
+		}
+		return lines;
+	};
 	readonly label = "AST Edit";
 	readonly summary = "Perform AST-aware code edits (structural refactoring)";
 	readonly description: string;

package/src/tools/ast-grep.ts

@@ -122,6 +122,7 @@ export interface AstGrepToolDetails {
 
 export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolDetails> {
 	readonly name = "ast_grep";
+	readonly approval = "read" as const;
 	readonly label = "AST Grep";
 	readonly summary = "Search code with AST patterns (structural grep)";
 	readonly description: string;

package/src/tools/bash.ts

@@ -1,5 +1,11 @@
 import * as fs from "node:fs";
-import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type {
+	AgentTool,
+	AgentToolContext,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	ToolApprovalDecision,
+} from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { ImageProtocol, TERMINAL, Text } from "@oh-my-pi/pi-tui";
 import { getProjectDir, isEnoent, logger, prompt } from "@oh-my-pi/pi-utils";
@@ -17,6 +23,7 @@ import { renderStatusLine } from "../tui";
 import { CachedOutputBlock } from "../tui/output-block";
 import { getSixelLineMask } from "../utils/sixel";
 import type { ToolSession } from ".";
+import { truncateForPrompt } from "./approval";
 import { applyBashFixups } from "./bash-command-fixup";
 import { type BashInteractiveResult, runInteractiveBashPty } from "./bash-interactive";
 import { checkBashInterception } from "./bash-interceptor";
@@ -34,6 +41,54 @@ export const BASH_DEFAULT_PREVIEW_LINES = 10;
 const BASH_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const DEFAULT_AUTO_BACKGROUND_THRESHOLD_MS = 60_000;
 
+/**
+ * Bash patterns that force an approval prompt even in yolo mode.
+ *
+ * Kept intentionally tight — the cost of a false positive is one extra prompt;
+ * the cost of a false negative is data loss or a compromised host. New patterns
+ * should target shapes that are virtually never legitimate in automation.
+ */
+export const CRITICAL_BASH_PATTERNS = [
+	// Recursive destruction.
+	/\brm\s+-[a-z]*[rRfF][a-z]*\s+\//i, // rm -rf /, rm -fr /, rm -r /, rm -f /…
+	/\bsudo\s+rm\b/i, // any `sudo rm`.
+	/\bchmod\s+-R\s+[0-7]+\s+\//i, // `chmod -R 777 /`.
+	/\bchmod\s+-R\s+[ugoa+\-=rwxXst,]+\s+\//, // `chmod -R u+x /`, `chmod -R u+rwx,o+w /etc` (symbolic mode, root target).
+	/\bchown\s+-R\s+\S+\s+\//i, // `chown -R user /`.
+
+	// Fork bomb (a few common spacings).
+	/:\(\)\s*\{\s*:\s*\|\s*:/i,
+
+	// Disk / filesystem destruction.
+	/>\s*\/dev\/sd[a-z]/i, // write to disk device.
+	/\bmkfs(\.|\b)/i, // format filesystem.
+	/\bdd\s+if=.+of=\/dev\//i, // dd to a device.
+	/\bshred\s+\/dev\//i,
+	/\bcryptsetup\b/i,
+
+	// System-config destruction.
+	/>\s*\/etc\/(?:passwd|shadow|sudoers)\b/i,
+	/\btee\s+(?:-a\s+)?\/etc\/(?:passwd|shadow|sudoers)\b/i, // `tee /etc/passwd`, `tee -a /etc/sudoers`.
+
+	// Remote-fetch-then-execute (curl/wget piped to a shell or process-subbed).
+	/\b(?:curl|wget|fetch)\b[^|]*\|\s*(?:bash|sh|zsh|fish)\b/i,
+	// Process-sub variants — `bash <(curl …)`, `source <(curl …)`, `. <(curl …)`. `.` and `source` are
+	// anchored to a command boundary so `find . -name` and similar don't false-positive.
+	/(?:^|[\s;&|(])(?:bash|sh|zsh|source|\.)\s+<\(\s*(?:curl|wget|fetch)\b/i,
+	// `eval "$(curl …)"` / `eval $(curl …)` / `eval \`curl …\``.
+	/\beval\s+["'`]?\$\(\s*(?:curl|wget|fetch)\b|\beval\s+`\s*(?:curl|wget|fetch)\b/i,
+
+	// Process/host control.
+	/\bkill\s+-9\s+1\b/, // kill PID 1.
+	// Process/host control — must sit at command position so `npm run reboot-tests`
+	// or `echo 'shutdown the queue'` don't false-positive.
+	/(?:^|[\s;&|(])(?:shutdown|poweroff|reboot|halt)(?:\s|$|[;|&])/i,
+	/(?:^|[\s;&|(])init\s+0\b/i,
+
+	// Network-shell exfil.
+	/\bnc\b[^|;]*\s-[a-zA-Z]*[ec][a-zA-Z]*\s/i, // `nc -e` / `nc -c`.
+] as const;
+
 async function saveBashOriginalArtifact(session: ToolSession, originalText: string): Promise<string | undefined> {
 	try {
 		const alloc = await session.allocateOutputArtifact?.("bash-original");
@@ -224,6 +279,19 @@ function formatTimeoutClampNotice(requestedTimeoutSec: number, effectiveTimeoutS
  */
 export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 	readonly name = "bash";
+	readonly approval = (args: unknown): ToolApprovalDecision => {
+		const rawCommand = (args as Partial<BashToolInput>).command;
+		const command = typeof rawCommand === "string" ? rawCommand : "";
+		if (command !== "" && CRITICAL_BASH_PATTERNS.some(pattern => pattern.test(command))) {
+			return { tier: "exec", override: true, reason: "Critical pattern detected" };
+		}
+		return "exec";
+	};
+	readonly formatApprovalDetails = (args: unknown): string[] => {
+		const rawCommand = (args as Partial<BashToolInput>).command;
+		const command = typeof rawCommand === "string" ? rawCommand : "(missing)";
+		return [`Command: ${truncateForPrompt(command)}`];
+	};
 	readonly label = "Bash";
 	readonly loadMode = "essential";
 	readonly description: string;

package/src/tools/browser/tab-supervisor.ts

@@ -105,7 +105,7 @@ export async function acquireTab(
 					await runInTabWithSnapshot(
 						name,
 						{
-							code: `await tab.goto(${JSON.stringify(opts.url)}, { waitUntil: ${JSON.stringify(opts.waitUntil ?? "networkidle2")} });`,
+							code: `await tab.goto(${JSON.stringify(opts.url)}, { waitUntil: ${JSON.stringify(opts.waitUntil ?? "load")} });`,
 							timeoutMs: opts.timeoutMs,
 							signal: opts.signal,
 						},

package/src/tools/browser.ts

@@ -3,6 +3,7 @@ import { prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
 import browserDescription from "../prompts/tools/browser.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
+import { truncateForPrompt } from "./approval";
 import { acquireBrowser, type BrowserHandle, type BrowserKind, type BrowserKindTag } from "./browser/registry";
 import type { Observation, ScreenshotResult } from "./browser/tab-protocol";
 import { acquireTab, dropHeadlessTabs, getTab, releaseAllTabs, releaseTab, runInTab } from "./browser/tab-supervisor";
@@ -87,6 +88,20 @@ function resolveBrowserKind(params: BrowserParams, session: ToolSession): Browse
  */
 export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolDetails> {
 	readonly name = "browser";
+	readonly approval = "exec" as const;
+	readonly formatApprovalDetails = (args: unknown): string[] => {
+		const params = args as Partial<BrowserParams>;
+		const lines = [`Action: ${typeof params.action === "string" ? params.action : "(missing)"}`];
+		const tabName = typeof params.name === "string" ? params.name : DEFAULT_TAB_NAME;
+		lines.push(`Tab: ${truncateForPrompt(tabName)}`);
+		if (typeof params.url === "string" && params.url.length > 0) {
+			lines.push(`URL: ${truncateForPrompt(params.url)}`);
+		}
+		if (typeof params.code === "string" && params.code.length > 0) {
+			lines.push(`Code:\n${truncateForPrompt(params.code)}`);
+		}
+		return lines;
+	};
 	readonly label = "Browser";
 	readonly loadMode = "discoverable";
 	readonly summary = "Control a headless browser to navigate and interact with web pages";

package/src/tools/calculator.ts

@@ -396,6 +396,7 @@ type CalculatorParams = z.infer<typeof calculatorSchema>;
  */
 export class CalculatorTool implements AgentTool<typeof calculatorSchema, CalculatorToolDetails> {
 	readonly name = "calc";
+	readonly approval = "read" as const;
 	readonly label = "Calc";
 	readonly summary = "Evaluate a mathematical expression";
 	readonly loadMode = "discoverable";

package/src/tools/checkpoint.ts

@@ -48,6 +48,7 @@ function isTopLevelSession(session: ToolSession): boolean {
 
 export class CheckpointTool implements AgentTool<typeof checkpointSchema, CheckpointToolDetails> {
 	readonly name = "checkpoint";
+	readonly approval = "read" as const;
 	readonly label = "Checkpoint";
 	readonly summary = "Create a git-based checkpoint to save and restore session state";
 	readonly description: string;
@@ -93,6 +94,7 @@ export class CheckpointTool implements AgentTool<typeof checkpointSchema, Checkp
 
 export class RewindTool implements AgentTool<typeof rewindSchema, RewindToolDetails> {
 	readonly name = "rewind";
+	readonly approval = "read" as const;
 	readonly label = "Rewind";
 	readonly summary = "Rewind to a previously created checkpoint";
 	readonly description: string;

package/src/tools/debug.ts

@@ -5,6 +5,7 @@ import type {
 	AgentToolResult,
 	AgentToolUpdateCallback,
 	RenderResultOptions,
+	ToolApprovalDecision,
 } from "@oh-my-pi/pi-agent-core";
 import { type Component, Text } from "@oh-my-pi/pi-tui";
 import { isEnoent, prompt } from "@oh-my-pi/pi-utils";
@@ -37,6 +38,7 @@ import debugDescription from "../prompts/tools/debug.md" with { type: "text" };
 import { renderStatusLine } from "../tui";
 import { CachedOutputBlock } from "../tui/output-block";
 import type { ToolSession } from ".";
+import { truncateForPrompt } from "./approval";
 import type { OutputMeta } from "./output-meta";
 import { formatPathRelativeToCwd, resolveToCwd } from "./path-utils";
 import {
@@ -51,6 +53,23 @@ import { ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
 import { clampTimeout } from "./tool-timeouts";
 
+/**
+ * DAP debug actions that only read program state (no mutation, no execution).
+ * Execution-side actions (`launch`, `attach`, `continue`, `step_*`, `pause`,
+ * `evaluate`, breakpoint mutations, memory writes) are exec-tier.
+ */
+export const DEBUG_READONLY_ACTIONS: ReadonlySet<string> = new Set([
+	"output",
+	"threads",
+	"stack_trace",
+	"scopes",
+	"variables",
+	"disassemble",
+	"read_memory",
+	"loaded_sources",
+	"modules",
+	"sessions",
+]);
 const debugSchema = z.object({
 	action: z.enum([
 		"launch",
@@ -609,6 +628,19 @@ export const debugToolRenderer = {
 
 export class DebugTool implements AgentTool<typeof debugSchema, DebugToolDetails> {
 	readonly name = "debug";
+	readonly approval = (args: unknown): ToolApprovalDecision => {
+		const rawAction = (args as Partial<DebugParams>).action;
+		const action = typeof rawAction === "string" ? rawAction.toLowerCase() : "";
+		return DEBUG_READONLY_ACTIONS.has(action) ? "read" : "exec";
+	};
+	readonly formatApprovalDetails = (args: unknown): string[] => {
+		const params = args as Partial<DebugParams>;
+		const lines = [`Action: ${typeof params.action === "string" ? params.action : "(missing)"}`];
+		if (typeof params.program === "string" && params.program.length > 0) {
+			lines.push(`Program: ${truncateForPrompt(params.program)}`);
+		}
+		return lines;
+	};
 	readonly label = "Debug";
 	readonly summary = "Debug a running process with DAP (debugger adapter protocol)";
 	readonly description: string;
@@ -647,6 +679,9 @@ export class DebugTool implements AgentTool<typeof debugSchema, DebugToolDetails
 				await validateLaunchProgram(program, commandCwd);
 				const adapter = selectLaunchAdapter(program, commandCwd, params.adapter);
 				if (!adapter) {
+					if (params.adapter === "debugpy") {
+						throw new ToolError("adapter 'debugpy' is not available: python not found in PATH");
+					}
 					throw new ToolError(
 						`No debugger adapter available. Installed adapters: ${getConfiguredAdapters(commandCwd)}`,
 					);
@@ -667,6 +702,9 @@ export class DebugTool implements AgentTool<typeof debugSchema, DebugToolDetails
 				const commandCwd = params.cwd ? resolveToCwd(params.cwd, this.session.cwd) : this.session.cwd;
 				const adapter = selectAttachAdapter(commandCwd, params.adapter, params.port);
 				if (!adapter) {
+					if (params.adapter === "debugpy") {
+						throw new ToolError("adapter 'debugpy' is not available: python not found in PATH");
+					}
 					throw new ToolError(
 						`No debugger adapter available. Installed adapters: ${getConfiguredAdapters(commandCwd)}`,
 					);

package/src/tools/eval.ts

@@ -15,6 +15,7 @@ import evalDescription from "../prompts/tools/eval.md" with { type: "text" };
 import { DEFAULT_MAX_BYTES, OutputSink, type OutputSummary, TailBuffer } from "../session/streaming-output";
 import { getTreeBranch, getTreeContinuePrefix, renderCodeCell } from "../tui";
 import { resolveEvalBackends, type ToolSession } from ".";
+import { truncateForPrompt } from "./approval";
 import {
 	formatStyledTruncationWarning,
 	resolveOutputMaxColumns,
@@ -202,6 +203,20 @@ async function resolveBackend(session: ToolSession, language: EvalLanguage): Pro
 
 export class EvalTool implements AgentTool<typeof evalSchema> {
 	readonly name = "eval";
+	readonly approval = "exec" as const;
+	readonly formatApprovalDetails = (args: unknown): string[] => {
+		const params = args as Partial<EvalToolParams>;
+		const cells = Array.isArray(params.cells) ? params.cells : [];
+		const firstCell = cells[0] as Partial<EvalCellInput> | undefined;
+		if (!firstCell) return [];
+		const language = typeof firstCell.language === "string" ? firstCell.language : "(missing)";
+		const code = typeof firstCell.code === "string" ? firstCell.code : "";
+		const lines = [`Language: ${language}`, `Code:\n${truncateForPrompt(code)}`];
+		if (cells.length > 1) {
+			lines.push(`+${cells.length - 1} more cell${cells.length === 2 ? "" : "s"}`);
+		}
+		return lines;
+	};
 	readonly summary = "Execute Python or JavaScript code in an in-process eval backend";
 	readonly loadMode = "discoverable";
 	readonly label = "Eval";

package/src/tools/find.ts

@@ -59,11 +59,15 @@ const MAX_GLOB_TIMEOUT_MS = 60_000;
  * Commas inside brace expansion (`{a,b}`) are legitimate glob syntax and
  * must pass through.
  */
-function validateFindPathInputs(paths: readonly string[]): void {
+export function validateFindPathInputs(paths: readonly string[]): void {
 	for (const entry of paths) {
 		let braceDepth = 0;
 		for (let i = 0; i < entry.length; i++) {
 			const ch = entry.charCodeAt(i);
+			if (ch === 0x5c /* \ */ && i + 1 < entry.length) {
+				i++;
+				continue;
+			}
 			if (ch === 0x7b /* { */) braceDepth++;
 			else if (ch === 0x7d /* } */) {
 				if (braceDepth > 0) braceDepth--;
@@ -115,6 +119,7 @@ export interface FindToolOptions {
 
 export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 	readonly name = "find";
+	readonly approval = "read" as const;
 	readonly summary = "Find files and directories matching a glob pattern";
 	readonly loadMode = "discoverable";
 	readonly label = "Find";
@@ -304,6 +309,7 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 
 			let matches: natives.GlobMatch[];
 			const onUpdateMatches: string[] = [];
+			const onUpdateMtimes: number[] = [];
 			const updateIntervalMs = 200;
 			let lastUpdate = 0;
 			const emitUpdate = () => {
@@ -323,9 +329,10 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 				});
 			};
 			const onMatch = (err: Error | null, match: natives.GlobMatch | null) => {
-				if (err || signal?.aborted || !match?.path) return;
+				if (err || combinedSignal.aborted || !match?.path) return;
 				const relativePath = formatMatchPath(match.path, match.fileType);
 				onUpdateMatches.push(relativePath);
+				onUpdateMtimes.push(match.mtime ?? 0);
 				emitUpdate();
 			};
 
@@ -335,7 +342,6 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 						{
 							pattern: globPattern,
 							path: searchPath,
-							fileType: natives.FileType.File,
 							hidden: includeHidden,
 							maxResults: effectiveLimit,
 							sortByMtime: true,
@@ -371,15 +377,18 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 				// instead of throwing — empty results after a multi-second wait force the
 				// caller to retry blind, which is the worst possible outcome.
 				const seen = new Set<string>();
-				const partial: string[] = [];
-				for (const entry of onUpdateMatches) {
+				const partial: Array<{ p: string; m: number }> = [];
+				for (let i = 0; i < onUpdateMatches.length; i++) {
+					const entry = onUpdateMatches[i];
 					if (seen.has(entry)) continue;
 					seen.add(entry);
-					partial.push(entry);
+					partial.push({ p: entry, m: onUpdateMtimes[i] ?? 0 });
 				}
+				partial.sort((a, b) => b.m - a.m);
+				const sortedPaths = partial.map(e => e.p);
 				const seconds = timeoutMs % 1000 === 0 ? `${timeoutMs / 1000}` : (timeoutMs / 1000).toFixed(1);
-				const notice = `find timed out after ${seconds}s; returning ${partial.length} partial matches — increase timeout or narrow pattern`;
-				return buildResult(partial, { notice, forceTruncated: true });
+				const notice = `find timed out after ${seconds}s; returning ${sortedPaths.length} partial matches — increase timeout or narrow pattern`;
+				return buildResult(sortedPaths, { notice, forceTruncated: true });
 			}
 
 			const relativized: string[] = [];

package/src/tools/gh.ts

@@ -2,7 +2,13 @@ import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import { scheduler } from "node:timers/promises";
-import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type {
+	AgentTool,
+	AgentToolContext,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	ToolApprovalDecision,
+} from "@oh-my-pi/pi-agent-core";
 
 import { getWorktreeDir, hashPath, isEnoent, prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
@@ -196,6 +202,15 @@ const RUN_URL_PATTERN = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/actions\/runs\/
 const RUN_SUCCESS_CONCLUSIONS = new Set(["success", "neutral", "skipped"]);
 const RUN_FAILURE_CONCLUSIONS = new Set(["failure", "timed_out", "cancelled", "action_required", "startup_failure"]);
 const JOB_FAILURE_CONCLUSIONS = new Set(["failure", "timed_out", "cancelled", "action_required"]);
+const GITHUB_READONLY_OPS: ReadonlySet<string> = new Set([
+	"repo_view",
+	"search_issues",
+	"search_prs",
+	"search_code",
+	"search_commits",
+	"search_repos",
+	"run_watch",
+]);
 
 const githubSchema = z
 	.object({
@@ -2344,6 +2359,11 @@ function buildTextResult(
 
 export class GithubTool implements AgentTool<typeof githubSchema, GhToolDetails> {
 	readonly name = "github";
+	readonly approval = (args: unknown): ToolApprovalDecision => {
+		const rawOp = (args as Partial<GithubInput>).op;
+		const op = typeof rawOp === "string" ? rawOp : "";
+		return GITHUB_READONLY_OPS.has(op) ? "read" : "exec";
+	};
 	readonly summary = "Interact with GitHub issues, pull requests, and repositories";
 	readonly loadMode = "discoverable";
 	readonly label = "GitHub";

package/src/tools/hindsight-recall.ts

@@ -13,6 +13,7 @@ export type HindsightRecallParams = z.infer<typeof hindsightRecallSchema>;
 
 export class HindsightRecallTool implements AgentTool<typeof hindsightRecallSchema> {
 	readonly name = "recall";
+	readonly approval = "read" as const;
 	readonly label = "Recall";
 	readonly description = recallDescription;
 	readonly parameters = hindsightRecallSchema;

package/src/tools/hindsight-reflect.ts

@@ -14,6 +14,7 @@ export type HindsightReflectParams = z.infer<typeof hindsightReflectSchema>;
 
 export class HindsightReflectTool implements AgentTool<typeof hindsightReflectSchema> {
 	readonly name = "reflect";
+	readonly approval = "read" as const;
 	readonly label = "Reflect";
 	readonly description = reflectDescription;
 	readonly parameters = hindsightReflectSchema;

package/src/tools/hindsight-retain.ts

@@ -18,6 +18,7 @@ const hindsightRetainSchema = z.object({
 export type HindsightRetainParams = z.infer<typeof hindsightRetainSchema>;
 export class HindsightRetainTool implements AgentTool<typeof hindsightRetainSchema> {
 	readonly name = "retain";
+	readonly approval = "read" as const;
 	readonly label = "Retain";
 	readonly description = retainDescription;
 	readonly parameters = hindsightRetainSchema;

package/src/tools/image-gen.ts

@@ -901,6 +901,7 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 	name: "generate_image",
 	label: "GenerateImage",
 	strict: false,
+	approval: "write",
 	description: prompt.render(imageGenDescription),
 	parameters: imageGenSchema,
 	async execute(_toolCallId, params, _onUpdate, ctx, signal) {