@zhushanwen/pi-permission 0.0.1

package/src/__tests__/statusline.test.ts

@@ -0,0 +1,221 @@
+/**
+ * statusline.test.ts — W6 T10: createPermissionFooter + renderPermissionLine 测试。
+ *
+ * 覆盖（4 case）：
+ *  1. renderPermissionLine：四档模式 + enabled/disabled 渲染正确
+ *  2. createPermissionFooter：factory 返回 FooterHandle（dispose/invalidate/render）
+ *  3. render 缓存：同 width 第二次返回缓存；invalidate 后重算
+ *  4. registerPermissionFooter：duck typing（无 setFooter/theme 时跳过）
+ */
+import { describe, expect, it, vi } from "vitest";
+
+import {
+	createPermissionFooter,
+	type FooterFactory,
+	type FooterHandle,
+	MODE_ACCENT_TOKEN,
+	paletteFromTheme,
+	registerPermissionFooter,
+	renderPermissionLine,
+	type PermissionPalette,
+} from "../statusline.js";
+import type { PermissionMode } from "../types.js";
+import { MODE_LABELS } from "../types.js";
+
+// ──────────────────────── mock helpers ────────────────────────
+
+/** 透传 palette（不加 ANSI，便于断言原始字符串）。 */
+function passthroughPalette(): PermissionPalette {
+	return {
+		dim: (s) => s,
+		text: (s) => s,
+		accent: (s) => s,
+		success: (s) => s,
+		warning: (s) => s,
+	};
+}
+
+/** mock theme（fg 透传，记录 token）。 */
+function mockTheme(): { fg: (token: string, text: string) => string; calls: Array<{ token: string; text: string }> } {
+	const calls: Array<{ token: string; text: string }> = [];
+	return {
+		fg(token: string, text: string): string {
+			calls.push({ token, text });
+			return text;
+		},
+		calls,
+	};
+}
+
+const ALL_MODES: PermissionMode[] = ["yolo", "auto", "approve", "strict"];
+
+// ──────────────────────── case 1: renderPermissionLine ────────────────────────
+
+describe("W6 T10 case 1: renderPermissionLine（四档模式 + enabled）", () => {
+	it("每个模式渲染对应的 MODE_LABELS", () => {
+		const palette = passthroughPalette();
+		for (const mode of ALL_MODES) {
+			const lines = renderPermissionLine(mode, true, palette);
+			expect(lines).toHaveLength(1);
+			expect(lines[0]).toContain(MODE_LABELS[mode]);
+		}
+	});
+
+	it("enabled=true 渲染 'enabled' + 模式 detail", () => {
+		const palette = passthroughPalette();
+		const lines = renderPermissionLine("strict", true, palette);
+		expect(lines[0]).toContain("enabled");
+		expect(lines[0]).toContain("all require approval");
+	});
+
+	it("enabled=false 渲染 'disabled' + passthrough 提示", () => {
+		const palette = passthroughPalette();
+		const lines = renderPermissionLine("yolo", false, palette);
+		expect(lines[0]).toContain("disabled");
+		expect(lines[0]).toContain("passthrough");
+	});
+
+	it("yolo 模式 detail 是 'all tools allowed'", () => {
+		const lines = renderPermissionLine("yolo", true, passthroughPalette());
+		expect(lines[0]).toContain("all tools allowed");
+	});
+
+	it("auto 模式 detail 是 'AST + rules + AI classifier'", () => {
+		const lines = renderPermissionLine("auto", true, passthroughPalette());
+		expect(lines[0]).toContain("AST + rules + AI classifier");
+	});
+
+	it("行含 [pi-permission] 前缀（grep 友好）", () => {
+		const lines = renderPermissionLine("auto", true, passthroughPalette());
+		expect(lines[0]).toContain("[pi-permission]");
+	});
+
+	it("MODE_ACCENT_TOKEN 映射完整（四档模式都有对应 token）", () => {
+		for (const mode of ALL_MODES) {
+			expect(MODE_ACCENT_TOKEN[mode]).toBeDefined();
+		}
+	});
+});
+
+// ──────────────────────── case 2: createPermissionFooter factory ────────────────────────
+
+describe("W6 T10 case 2: createPermissionFooter（factory 返回 FooterHandle）", () => {
+	it("factory 返回含 dispose/invalidate/render 的 handle", () => {
+		const palette = passthroughPalette();
+		const factory = createPermissionFooter(() => "auto", () => true, palette);
+		const handle = factory({ requestRender() {} }, {}, {});
+		expect(typeof handle.dispose).toBe("function");
+		expect(typeof handle.invalidate).toBe("function");
+		expect(typeof handle.render).toBe("function");
+	});
+
+	it("dispose 不抛异常（noop）", () => {
+		const palette = passthroughPalette();
+		const factory = createPermissionFooter(() => "yolo", () => true, palette);
+		const handle = factory({ requestRender() {} }, {}, {});
+		expect(() => handle.dispose()).not.toThrow();
+	});
+
+	it("render 返回行数组（含当前模式）", () => {
+		const palette = passthroughPalette();
+		const factory = createPermissionFooter(() => "strict", () => true, palette);
+		const handle = factory({ requestRender() {} }, {}, {});
+		const lines = handle.render(80);
+		expect(Array.isArray(lines)).toBe(true);
+		expect(lines.length).toBeGreaterThan(0);
+		expect(lines.join(" ")).toContain("Strict");
+	});
+
+	it("getMode/getEnabled 闭包读最新值（mode 变化反映到 render）", () => {
+		let currentMode: PermissionMode = "yolo";
+		const palette = passthroughPalette();
+		const factory = createPermissionFooter(() => currentMode, () => true, palette);
+		const handle = factory({ requestRender() {} }, {}, {});
+		const lines1 = handle.render(80);
+		expect(lines1.join(" ")).toContain("YOLO");
+
+		// 切换 mode 后 invalidate + 重 render
+		currentMode = "strict";
+		handle.invalidate();
+		const lines2 = handle.render(80);
+		expect(lines2.join(" ")).toContain("Strict");
+		expect(lines2.join(" ")).not.toContain("YOLO");
+	});
+});
+
+// ──────────────────────── case 3: render 缓存 ────────────────────────
+
+describe("W6 T10 case 3: render 缓存（同 width 复用，invalidate 重算）", () => {
+	it("同 width 第二次 render 返回缓存（同一引用）", () => {
+		const palette = passthroughPalette();
+		const factory = createPermissionFooter(() => "auto", () => true, palette);
+		const handle = factory({ requestRender() {} }, {}, {});
+		const first = handle.render(100);
+		const second = handle.render(100);
+		expect(second).toBe(first); // 同一引用（缓存命中）
+	});
+
+	it("不同 width → 重新渲染（缓存 key 含 width）", () => {
+		const palette = passthroughPalette();
+		const factory = createPermissionFooter(() => "auto", () => true, palette);
+		const handle = factory({ requestRender() {} }, {}, {});
+		const first = handle.render(80);
+		const second = handle.render(120);
+		expect(second).not.toBe(first); // 不同引用（width 变了）
+	});
+
+	it("invalidate 后同 width → 重新渲染", () => {
+		const palette = passthroughPalette();
+		const factory = createPermissionFooter(() => "auto", () => true, palette);
+		const handle = factory({ requestRender() {} }, {}, {});
+		const first = handle.render(80);
+		handle.invalidate();
+		const second = handle.render(80);
+		expect(second).not.toBe(first); // invalidate 后重新渲染
+	});
+});
+
+// ──────────────────────── case 4: registerPermissionFooter duck typing ────────────────────────
+
+describe("W6 T10 case 4: registerPermissionFooter（duck typing 跳过）", () => {
+	it("ctx.ui 含 setFooter + theme → 调用 setFooter 注册 factory", () => {
+		const setFooter = vi.fn();
+		const theme = mockTheme();
+		registerPermissionFooter({ setFooter, theme }, () => "auto", () => true);
+		expect(setFooter).toHaveBeenCalledOnce();
+		const factory = setFooter.mock.calls[0]![0] as FooterFactory;
+		expect(typeof factory).toBe("function");
+		// 验证 factory 产出可用
+		const handle: FooterHandle = factory({ requestRender() {} }, {}, {});
+		expect(handle.render(80).length).toBeGreaterThan(0);
+	});
+
+	it("ctx.ui 无 setFooter → 跳过（不抛异常）", () => {
+		const theme = mockTheme();
+		// 只有 theme，没有 setFooter
+		expect(() => registerPermissionFooter({ theme }, () => "auto", () => true)).not.toThrow();
+	});
+
+	it("ctx.ui 无 theme → 跳过", () => {
+		const setFooter = vi.fn();
+		// 只有 setFooter，没有 theme
+		registerPermissionFooter({ setFooter }, () => "auto", () => true);
+		expect(setFooter).not.toHaveBeenCalled();
+	});
+
+	it("ctx.ui.theme 无 fg 函数 → 跳过", () => {
+		const setFooter = vi.fn();
+		const theme = { fg: "not-a-function" };
+		registerPermissionFooter({ setFooter, theme }, () => "auto", () => true);
+		expect(setFooter).not.toHaveBeenCalled();
+	});
+
+	it("paletteFromTheme 从 theme 构造 palette（透传 fg 调用）", () => {
+		const theme = mockTheme();
+		const palette = paletteFromTheme(theme);
+		palette.dim("test-dim");
+		palette.accent("test-accent");
+		expect(theme.calls.some((c) => c.token === "dim" && c.text === "test-dim")).toBe(true);
+		expect(theme.calls.some((c) => c.token === "accent" && c.text === "test-accent")).toBe(true);
+	});
+});

package/src/__tests__/types.test.ts

@@ -0,0 +1,59 @@
+/**
+ * WT6: PermissionMode 枚举完整性测试
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+	DEFAULT_CONFIG,
+	isValidPermissionMode,
+	MODE_DESCRIPTIONS,
+	MODE_LABELS,
+	PERMISSION_MODES,
+} from "../types.js";
+
+describe("WT6: PermissionMode 枚举完整性", () => {
+	it("PERMISSION_MODES 包含四档且顺序正确（严格等级低→高）", () => {
+		expect(PERMISSION_MODES).toEqual(["yolo", "auto", "approve", "strict"]);
+	});
+
+	it("MODE_DESCRIPTIONS 四个 key 都有值", () => {
+		for (const mode of PERMISSION_MODES) {
+			expect(MODE_DESCRIPTIONS[mode]).toBeTruthy();
+			expect(typeof MODE_DESCRIPTIONS[mode]).toBe("string");
+		}
+	});
+
+	it("MODE_LABELS 四个 key 都有值", () => {
+		for (const mode of PERMISSION_MODES) {
+			expect(MODE_LABELS[mode]).toBeTruthy();
+			expect(typeof MODE_LABELS[mode]).toBe("string");
+		}
+	});
+
+	it("isValidPermissionMode 对四档返回 true", () => {
+		for (const mode of PERMISSION_MODES) {
+			expect(isValidPermissionMode(mode)).toBe(true);
+		}
+	});
+
+	it("isValidPermissionMode 对非法值返回 false", () => {
+		expect(isValidPermissionMode("Yolo")).toBe(false); // 大小写敏感
+		expect(isValidPermissionMode("read-only")).toBe(false);
+		expect(isValidPermissionMode("")).toBe(false);
+		expect(isValidPermissionMode(undefined)).toBe(false);
+		expect(isValidPermissionMode(null)).toBe(false);
+		expect(isValidPermissionMode(123)).toBe(false);
+		expect(isValidPermissionMode({ mode: "yolo" })).toBe(false);
+	});
+
+	it("DEFAULT_CONFIG 有合理默认值", () => {
+		expect(DEFAULT_CONFIG.mode).toBe("yolo");
+		expect(DEFAULT_CONFIG.enabled).toBe(true);
+		expect(DEFAULT_CONFIG.classifier.enabled).toBe(true);
+		expect(DEFAULT_CONFIG.classifier.model).toBe("auto");
+		expect(DEFAULT_CONFIG.classifier.timeout).toBe(90);
+		expect(DEFAULT_CONFIG.classifier.autoApproveLowRisk).toBe(true);
+		expect(DEFAULT_CONFIG.classifier.autoDenyHighRisk).toBe(true);
+		expect(DEFAULT_CONFIG.userRules).toEqual([]);
+	});
+});

package/src/approval.ts

@@ -0,0 +1,352 @@
+/**
+ * 用户审批 UI（W5 集成层 + W6 T9 Reject-with-Reason）。
+ *
+ * 三分支（按 ctx.mode 分发，ctx 由 caller 从 Pi ExtensionContext 提取）：
+ *  - tui：ctx.ui.custom 自定义 Component（ApprovalComponent，G4 补 invalidate）。
+ *    G3：调 ctx.ui.custom 前先检查 signal.aborted 短路（AI 先于 UI factory 执行时
+ *    controller.abort() 触发但 comp 尚未创建，cancel 落空）。
+ *  - rpc：ctx.ui.select（GUI 对话框）。M2：接收 signal，abort 短路 + 透传给 ui.select。
+ *  - headless（json/print）：无交互 UI。M1：返回永不主动 resolve 的 Promise（让 Racing 中的
+ *    AI 有机会赢），仅在 signal abort 时 fail-closed deny（避免 headless 下 auto 退化为 strict）。
+ *
+ * ApprovalComponent 是简化版 TUI 组件（参考 ask-user AskUserComponent）：
+ *  - 显示工具名 + 命令 + 触发原因 + 可选 AI 预分类。
+ *  - y/approve、n/deny、Esc/cancel。
+ *  - signal abort → comp.cancel()（复用 _resolved 守卫，避免二次 done）。
+ *
+ * W6 T9 G3 Reject-with-Reason：用户拒绝时，若 ctx.ui.input 存在则弹出文本输入框
+ * 采集真实拒绝理由（回传给 agent，辅助理解为何被拒）；ctx.ui.input 不存在则 fallback
+ * 用固定 "denied via rpc/tui" 文案。当前 RPC 分支已完整接入 ctx.ui.input；
+ * TUI 分支因 pi-tui Input 组件集成成本较高，暂保留简化 deny（TODO 后续迭代）。
+ */
+
+import { type Component, matchesKey, type SelectItem, truncateToWidth } from "@earendil-works/pi-tui";
+
+import type { ApprovalRequest } from "./pipeline.js";
+import type { ToolInvocationContext, UserDecision } from "./types.js";
+
+// ──────────────────────── ApprovalContext（从 ExtensionContext 提取的最小子集） ────────────────────────
+
+/**
+ * 审批 UI 上下文（从 Pi ExtensionContext 提取的最小子集）。
+ *
+ * 提取为独立接口便于：
+ *  - 测试 mock（不依赖完整 ExtensionContext）。
+ *  - 明确 requestUserApproval 只用 mode + ui.{custom,select,notify,input}。
+ *
+ * mode 来自 ExtensionContext.mode（"tui"|"rpc"|"json"|"print"）。
+ * headless = mode !== "tui" && mode !== "rpc"（json/print 无交互 UI）。
+ *
+ * W6 T9 G3：ui.input 可选（SDK 提供，但测试 mock 可能缺失）。
+ * Reject-with-Reason 的「受阻」定义为可观测条件：
+ *  - ui.input 存在（typeof === 'function'）→ 采集真实 reason
+ *  - ui.input 缺失 → fallback 固定文案
+ */
+export interface ApprovalContext {
+	mode: "tui" | "rpc" | "json" | "print";
+	ui: {
+		notify(msg: string, type?: "info" | "warning" | "error"): void;
+		select(title: string, options: string[], opts?: { signal?: AbortSignal; timeout?: number }): Promise<string | undefined>;
+		custom<T = void>(
+			factory: (tui: unknown, theme: unknown, kb: unknown, done: (result: T) => void) => Component,
+			options?: { overlay?: boolean },
+		): Promise<T>;
+		/** W6 T9 G3：可选文本输入（Reject-with-Reason 用）。SDK 提供，mock 可能缺失。 */
+		input?(title: string, placeholder?: string, opts?: { signal?: AbortSignal; timeout?: number }): Promise<string | undefined>;
+	};
+}
+
+// ──────────────────────── requestUserApproval ────────────────────────
+
+/**
+ * 请求用户审批（按 mode 分发）。
+ *
+ * @param req 审批请求数据（工具名 + 命令 + 原因 + 可选 AI 预分类）
+ * @param _ctxUnused 未使用（保留签名对称性；实际 UI ctx 在 approvalCtx）
+ * @param signal abort signal（racing 用：AI 赢时 abort，UI 短路）
+ * @param approvalCtx UI 上下文（mode + ui.*）
+ * @returns UserDecision（approved + reason）
+ */
+export async function requestUserApproval(
+	req: ApprovalRequest,
+	_ctxUnused: ToolInvocationContext,
+	signal: AbortSignal | undefined,
+	approvalCtx: ApprovalContext,
+): Promise<UserDecision> {
+	switch (approvalCtx.mode) {
+		case "tui":
+			return await requestTui(req, signal, approvalCtx);
+		case "rpc":
+			// M2：传 signal 给 requestRpc（abort 时短路 + 透传给 ui.select 关闭对话框）
+			return await requestRpc(req, signal, approvalCtx);
+		case "json":
+		case "print":
+		default:
+			// headless 立即 fail-closed deny（无 UI 无 AI 可判）。
+			// auto 模式的 Racing 在 headless 下不调用此路径（见 runLayer3WithRacing 的 isHeadless 分支）。
+			return requestHeadless(req, approvalCtx);
+	}
+}
+
+// ──────────────────────── TUI 分支（G3 + G4） ────────────────────────
+
+/** TUI 模式：ctx.ui.custom + ApprovalComponent。G3：先检查 signal.aborted。 */
+async function requestTui(
+	req: ApprovalRequest,
+	signal: AbortSignal | undefined,
+	approvalCtx: ApprovalContext,
+): Promise<UserDecision> {
+	// G3 修正：AI 先于 UI factory 执行时，controller.abort() 已触发但 comp 未创建。
+	// 在调 ctx.ui.custom 前检查 signal.aborted，短路返回 deny（fail-closed）。
+	if (signal?.aborted) {
+		approvalCtx.ui.notify(`[pi-permission] approval aborted before prompt: ${req.toolName}`, "warning");
+		return { approved: false, reason: "aborted before prompt (AI won the race)" };
+	}
+
+	return approvalCtx.ui.custom<UserDecision>((tui, _theme, _kb, done) => {
+		const comp = new ApprovalComponent(req, tui as TuiLike, done);
+		// signal abort → comp.cancel()（复用 _resolved 守卫，避免二次 done）
+		if (signal) {
+			signal.addEventListener("abort", () => comp.cancel(), { once: true });
+		}
+		return comp;
+	});
+}
+
+// ──────────────────────── RPC 分支 ────────────────────────
+
+/** RPC 模式：ctx.ui.select（GUI 单选对话框）+ W6 T9 G3 Reject-with-Reason。 */
+async function requestRpc(
+	req: ApprovalRequest,
+	signal: AbortSignal | undefined,
+	approvalCtx: ApprovalContext,
+): Promise<UserDecision> {
+	const title = formatTitle(req);
+	// TODO: spec 未要求 session/always scope，当前仅支持 once。
+	// 未来如需扩展，options 加 "Approve (session)" / "Approve (always)"，UserDecision.scope 透传。
+	const options = ["Approve (once)", "Deny"];
+	// M2：与 requestTui 一致——调 select 前检查 signal.aborted 短路（AI 先于对话框弹出赢 race 时，
+	// controller.abort() 已触发但 select 尚未发起，这里 fail-closed deny 避免弹出无意义对话框）。
+	if (signal?.aborted) {
+		approvalCtx.ui.notify(`[pi-permission] approval aborted before prompt: ${req.toolName}`, "warning");
+		return { approved: false, reason: "aborted before prompt (AI won the race)" };
+	}
+	// M2：把 signal 透传给 ui.select（SDK 支持 { signal } options），AI 赢 race abort 时关闭对话框。
+	const choice = await approvalCtx.ui.select(title, options, signal ? { signal } : undefined);
+	if (choice === undefined) {
+		return { approved: false, reason: "user dismissed the prompt" };
+	}
+	if (choice.startsWith("Approve")) {
+		return { approved: true, reason: "approved via rpc", scope: "once" };
+	}
+	// W6 T9 G3：Reject-with-Reason。用户选 Deny 后，若 ctx.ui.input 存在则采集真实理由。
+	// 「受阻」可观测条件：typeof ctx.ui.input === 'function'。
+	return { approved: false, reason: await collectRejectReason(req, approvalCtx) };
+}
+
+/**
+ * W6 T9 G3：采集拒绝理由（Reject-with-Reason）。
+ *
+ * 可观测条件：ctx.ui.input 存在（typeof === 'function'）→ 弹文本输入框采集真实 reason。
+ * 否则 fallback 固定文案（"denied via <mode>"）。
+ *
+ * 空输入（用户直接回车）也 fallback 固定文案（不强制要求理由）。
+ *
+ * @param req 审批请求（用于构造提示标题）
+ * @param approvalCtx UI 上下文
+ * @returns 拒绝理由字符串（真实采集或 fallback）
+ */
+export async function collectRejectReason(
+	req: ApprovalRequest,
+	approvalCtx: ApprovalContext,
+): Promise<string> {
+	// 「受阻」可观测条件：ctx.ui.input 必须是函数
+	if (typeof approvalCtx.ui.input !== "function") {
+		return `denied via ${approvalCtx.mode}`;
+	}
+	try {
+		const reason = await approvalCtx.ui.input(
+			`[pi-permission] Reason for denying ${req.toolName}${req.command ? `: ${req.command}` : ""} (optional, press Enter to skip)`,
+			"Why are you denying this?",
+		);
+		// 空输入或 undefined（用户跳过）→ fallback
+		if (reason === undefined || reason.trim().length === 0) {
+			return `denied via ${approvalCtx.mode}`;
+		}
+		return `denied via ${approvalCtx.mode}: ${reason.trim()}`;
+	} catch {
+		// input 调用异常 → fail-soft fallback（不阻塞 deny）
+		return `denied via ${approvalCtx.mode}`;
+	}
+}
+
+// ──────────────────────── headless 分支 ────────────────────────
+
+/**
+ * headless（json/print）：无交互 UI → fail-closed deny。
+ *
+ * 此函数服务于 strict/approve 的 `askUser` 路径——这些路径无 AI 层可兜底，
+ * headless 下既无法问用户也无法判风险，立即 deny 是唯一正确行为。
+ *
+ * auto 模式的 Racing（`runLayer3WithRacing`）在 headless 下不调用此函数——
+ * `CheckPermissionDeps.isHeadless()` 让 Racing 跳过 user promise，纯等 AI 判定
+ * （M1 修正：headless 下 auto 应让 AI classifier 有机会赢，而非立即 deny 退化成 strict）。
+ */
+function requestHeadless(req: ApprovalRequest, approvalCtx: ApprovalContext): UserDecision {
+	approvalCtx.ui.notify(`[pi-permission] headless mode auto-deny: ${req.reason}`, "warning");
+	return { approved: false, reason: `headless mode (${approvalCtx.mode}): cannot prompt, auto-deny` };
+}
+
+// ──────────────────────── 辅助：标题格式化 ────────────────────────
+
+/** 格式化审批标题（RPC select / TUI 顶部）。 */
+function formatTitle(req: ApprovalRequest): string {
+	const lines: string[] = [];
+	lines.push(`[pi-permission] Approval required`);
+	lines.push(`Tool: ${req.toolName}`);
+	if (req.command !== undefined && req.command.length > 0) {
+		lines.push(`Command: ${req.command}`);
+	}
+	lines.push(`Reason: ${req.reason}`);
+	if (req.preClassification) {
+		const pc = req.preClassification;
+		lines.push(`AI: risk=${pc.risk_level} outcome=${pc.outcome} (conf=${pc.confidence})`);
+	}
+	return lines.join("\n");
+}
+
+// ──────────────────────── ApprovalComponent（TUI 组件，G4 invalidate） ────────────────────────
+
+/** 最小 TUI 接口（满足真实 TUI 和测试 stub）。 */
+interface TuiLike {
+	requestRender(): void;
+}
+
+/**
+ * TUI 审批组件（简化版，参考 ask-user AskUserComponent）。
+ *
+ * 显示：标题 + 工具名 + 命令 + 原因 + 可选 AI 预分类 + 操作提示。
+ * 键位：y/Enter → approve；n/Esc → deny/cancel。
+ *
+ * G4：implements Component，补 invalidate()（调 tui.requestRender()）。
+ * signal abort → cancel()（复用 _resolved 守卫）。
+ *
+ * TODO W6：若需更丰富的 TUI（方向键选择 once/session/always scope、高亮风险等级、
+ * Reject-with-Reason 的内联文本输入），参考 ask-user AskUserComponent 的 SelectList
+ * + pi-tui Input 组件集成。当前简化版的 deny 走固定文案（RPC 分支已接入 ctx.ui.input
+ * 采集真实理由，TUI 分支因 Input 组件集成成本较高暂保留简化 deny，后续迭代补齐）。
+ */
+export class ApprovalComponent implements Component {
+	private readonly req: ApprovalRequest;
+	private readonly tui: TuiLike;
+	private readonly done: (result: UserDecision) => void;
+	private _resolved = false;
+
+	// 渲染缓存（width → lines），invalidate 清空。
+	private cachedWidth: number | undefined;
+	private cachedLines: string[] | undefined;
+
+	constructor(req: ApprovalRequest, tui: TuiLike, done: (result: UserDecision) => void) {
+		this.req = req;
+		this.tui = tui;
+		this.done = done;
+		this.invalidate();
+	}
+
+	/** G4：Component 接口要求。失效渲染缓存 + 请求重绘。 */
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+
+	private rerender(): void {
+		this.invalidate();
+		this.tui.requestRender();
+	}
+
+	render(width: number): string[] {
+		if (this.cachedWidth === width && this.cachedLines) {
+			return this.cachedLines;
+		}
+		const lines = renderApprovalView(this.req, width);
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+
+	handleInput(data: string): void {
+		if (this._resolved) return;
+		// Enter → approve
+		if (matchesKey(data, "enter")) {
+			this.approve();
+			return;
+		}
+		// Esc → deny
+		if (matchesKey(data, "escape")) {
+			this.deny();
+			return;
+		}
+		// 其他键 no-op（不泄漏）
+	}
+
+	private approve(): void {
+		if (this._resolved) return;
+		this._resolved = true;
+		// TODO: spec 未要求 session/always scope，当前硬编码 "once"。未来如需扩展，
+		// 增加 handleInput 对应键位（如 's' → session、'a' → always）并透传 UserDecision.scope。
+		this.done({ approved: true, reason: "approved via tui", scope: "once" });
+	}
+
+	private deny(): void {
+		if (this._resolved) return;
+		this._resolved = true;
+		this.done({ approved: false, reason: "denied via tui" });
+	}
+
+	/** 取消（signal abort 调用）。复用 _resolved 守卫，避免二次 done。 */
+	cancel(): void {
+		if (this._resolved) return;
+		this._resolved = true;
+		this.done({ approved: false, reason: "cancelled (signal abort)" });
+	}
+}
+
+/** box 边框左右各占用 1 列（│ × 2） */
+const BORDER_OVERHEAD = 2;
+
+/** 渲染审批视图（纯函数，便于单测）。 */
+export function renderApprovalView(req: ApprovalRequest, width: number): string[] {
+	const innerWidth = Math.max(0, width - BORDER_OVERHEAD); // 减去左右边框
+	const inner: string[] = [];
+	inner.push("[pi-permission] Approval required");
+	inner.push("");
+	inner.push(`Tool: ${req.toolName}`);
+	if (req.command !== undefined && req.command.length > 0) {
+		inner.push(`Command: ${req.command}`);
+	}
+	inner.push(`Reason: ${req.reason}`);
+	if (req.preClassification) {
+		const pc = req.preClassification;
+		inner.push("");
+		inner.push(`AI classification:`);
+		inner.push(`  risk: ${pc.risk_level}`);
+		inner.push(`  outcome: ${pc.outcome}`);
+		inner.push(`  confidence: ${pc.confidence}`);
+		inner.push(`  reasoning: ${pc.reasoning}`);
+	}
+	inner.push("");
+	inner.push("[Enter] Approve  [Esc] Deny");
+
+	// 用 box 边框包裹
+	const lines: string[] = [];
+	lines.push(`┌${"─".repeat(innerWidth)}┐`);
+	for (const line of inner) {
+		const padded = truncateToWidth(line, innerWidth, "", true);
+		lines.push(`│${padded}│`);
+	}
+	lines.push(`└${"─".repeat(innerWidth)}┘`);
+	return lines;
+}
+
+// re-export SelectItem 仅为测试便利（mock ctx.ui.select 时构造选项）
+export type { SelectItem };