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

package/src/task/executor.ts

@@ -532,6 +532,11 @@ function createSubagentSettings(baseSettings: Settings): Settings {
 		...snapshot,
 		"async.enabled": false,
 		"bash.autoBackground.enabled": false,
+		// Subagents run headless — there is no UI to confirm prompts against, so
+		// the parent task approval is the authorization boundary. Use yolo mode
+		// to preserve unattended subagent execution while still honoring any
+		// tool-level safety override that can be handled before execution.
+		"tools.approvalMode": "yolo",
 	});
 }
 
@@ -1148,6 +1153,11 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			if (model?.contextWindow && model.contextWindow > 0) {
 				progress.contextWindow = model.contextWindow;
 			}
+			if (model) {
+				progress.resolvedModel = explicitThinkingLevel
+					? `${model.provider}/${model.id}:${resolvedThinkingLevel}`
+					: `${model.provider}/${model.id}`;
+			}
 			const effectiveThinkingLevel = explicitThinkingLevel
 				? resolvedThinkingLevel
 				: (thinkingLevel ?? resolvedThinkingLevel);
@@ -1606,6 +1616,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		contextTokens: progress.contextTokens,
 		contextWindow: progress.contextWindow,
 		modelOverride,
+		resolvedModel: progress.resolvedModel,
 		error: exitCode !== 0 && stderr ? stderr : undefined,
 		aborted: wasAborted,
 		abortReason: finalAbortReason,

package/src/task/index.ts

@@ -27,6 +27,7 @@ import planModeSubagentPrompt from "../prompts/system/plan-mode-subagent.md" wit
 import subagentUserPromptTemplate from "../prompts/system/subagent-user-prompt.md" with { type: "text" };
 import taskDescriptionTemplate from "../prompts/tools/task.md" with { type: "text" };
 import taskSummaryTemplate from "../prompts/tools/task-summary.md" with { type: "text" };
+import { truncateForPrompt } from "../tools/approval";
 import { formatBytes, formatDuration } from "../tools/render-utils";
 import {
 	type AgentDefinition,
@@ -214,6 +215,24 @@ function validateTaskModeParams(simpleMode: TaskSimpleMode, params: TaskParams):
  */
 export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetails, Theme> {
 	readonly name = "task";
+	readonly approval = "exec" as const;
+	readonly formatApprovalDetails = (args: unknown): string[] => {
+		const params = args as Partial<TaskParams>;
+		const lines: string[] = [];
+		if (typeof params.agent === "string") {
+			lines.push(`Agent: ${truncateForPrompt(params.agent)}`);
+		}
+		const tasks = Array.isArray(params.tasks) ? params.tasks : [];
+		const firstTask = tasks[0];
+		if (firstTask) {
+			lines.push(`Task: ${truncateForPrompt(firstTask.id)}`);
+			lines.push(`Assignment:\n${truncateForPrompt(firstTask.assignment)}`);
+			if (tasks.length > 1) {
+				lines.push(`+${tasks.length - 1} more task${tasks.length === 2 ? "" : "s"}`);
+			}
+		}
+		return lines;
+	};
 	readonly label = "Task";
 	readonly summary = "Spawn a subagent to complete a parallel task";
 	readonly strict = true;

package/src/task/render.ts

@@ -8,6 +8,7 @@ import path from "node:path";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Container, Text } from "@oh-my-pi/pi-tui";
 import { formatNumber } from "@oh-my-pi/pi-utils";
+import { settings } from "../config/settings";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import {
@@ -59,6 +60,8 @@ function appendAgentStats(
 		contextTokens?: number;
 		contextWindow?: number;
 		cost: number;
+		resolvedModel?: string;
+		showResolvedModelBadge?: boolean;
 	},
 	theme: Theme,
 ): string {
@@ -83,6 +86,9 @@ function appendAgentStats(
 	if (opts.cost > 0) {
 		line += `${theme.sep.dot}${theme.fg("statusLineCost", `$${opts.cost.toFixed(2)}`)}`;
 	}
+	if (opts.resolvedModel && opts.showResolvedModelBadge) {
+		line += `${theme.sep.dot}${theme.fg("dim", truncateToWidth(replaceTabs(opts.resolvedModel), 30))}`;
+	}
 	return line;
 }
 
@@ -564,14 +570,15 @@ function renderAgentProgress(
 		statusLine += ` ${formatBadge(statusLabel, iconColor, theme)}`;
 	}
 
+	const showBadge = settings.get("task.showResolvedModelBadge");
 	if (progress.status === "running") {
 		if (!description) {
 			const taskPreview = truncateToWidth(progress.assignment ?? progress.task, 40);
 			statusLine += ` ${theme.fg("muted", taskPreview)}`;
 		}
-		statusLine = appendAgentStats(statusLine, progress, theme);
+		statusLine = appendAgentStats(statusLine, { ...progress, showResolvedModelBadge: showBadge }, theme);
 	} else if (progress.status === "completed") {
-		statusLine = appendAgentStats(statusLine, progress, theme);
+		statusLine = appendAgentStats(statusLine, { ...progress, showResolvedModelBadge: showBadge }, theme);
 	}
 
 	lines.push(statusLine);
@@ -838,6 +845,7 @@ function renderAgentResult(result: SingleResult, isLast: boolean, expanded: bool
 		iconColor,
 		theme,
 	)}`;
+	const showBadge = settings.get("task.showResolvedModelBadge");
 	statusLine = appendAgentStats(
 		statusLine,
 		{
@@ -845,6 +853,8 @@ function renderAgentResult(result: SingleResult, isLast: boolean, expanded: bool
 			contextTokens: result.contextTokens,
 			contextWindow: result.contextWindow,
 			cost: result.usage?.cost.total ?? 0,
+			resolvedModel: result.resolvedModel,
+			showResolvedModelBadge: showBadge,
 		},
 		theme,
 	);

package/src/task/types.ts

@@ -210,6 +210,8 @@ export interface AgentProgress {
 	cost: number;
 	durationMs: number;
 	modelOverride?: string | string[];
+	/** Resolved model display string in the form `<provider>/<id>`, optionally suffixed with `:<thinkingLevel>` when the level was set explicitly. Undefined when the model could not be resolved. */
+	resolvedModel?: string;
 	/** Data extracted by registered subprocess tool handlers (keyed by tool name) */
 	extractedToolData?: Record<string, unknown[]>;
 	/**
@@ -268,6 +270,8 @@ export interface SingleResult {
 	/** Model's context window in tokens, when known. */
 	contextWindow?: number;
 	modelOverride?: string | string[];
+	/** Resolved model display string in the form `<provider>/<id>`, optionally suffixed with `:<thinkingLevel>` when the level was set explicitly. Omitted from tool-result JSON when undefined to keep wire payloads small. */
+	resolvedModel?: string;
 	error?: string;
 	aborted?: boolean;
 	abortReason?: string;

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";