@zhushanwen/pi-permission 0.0.1

package/src/rules/matcher.ts

@@ -0,0 +1,160 @@
+/**
+ * 规则匹配引擎（W3 层 2 核心入口）。
+ *
+ * 三个 critical gap 修正（design-review）：
+ *
+ *  ── G1: no-match 兜底语义 ──
+ *  无匹配返回 `{ action: 'ask', matchedRule: undefined }`（非 'deny'）。
+ *  deny 会让 auto 模式所有未匹配命令被拦截，无法到 AI 层。ask 让未匹配命令
+ *  进入下游（auto 模式 → AI classifier；approve/strict 模式 → 人工审批）。
+ *
+ *  ── G2: pattern 双语义 ──
+ *  source='builtin-danger' 的 pattern 是 RegExp 源字符串（含 `\b`/`\s`），
+ *  用 `new RegExp(pattern, 'i')` 编译；其余（builtin-safe/user）是 OpenCode
+ *  wildcard，用 `wildcardToRegExp(pattern)` 编译。resolvePattern 按 source 分发。
+ *
+ *  ── G3: 24+5 白名单用函数（C3 修正：不再短路）──
+ *  matchRulesForArgv 先遍历 rules（last-match-wins）；若无 deny/allow 命中（ask），
+ *  再查 isKnownSafeCommand(argv) 兜底返回 allow。白名单不再短路：用户 deny 规则
+ *  可覆盖白名单。白名单不进 Rule[] 数组（Codex flag 子检查无法用单条 wildcard 表达）。
+ *
+ * 匹配语义：last-match-wins（rules 数组顺序遍历，最后匹配的 rule 胜出）。
+ * 拼接顺序由调用方（W5）负责：[...builtin-danger, ...userRules]。
+ */
+
+import type { Rule, RuleMatchResult } from "../types.js";
+import { isKnownSafeCommand } from "./builtins.js";
+import { wildcardToRegExp } from "./wildcard.js";
+
+// ──────────────────────── pattern 缓存（module-level 状态）────────────────────────
+
+/**
+ * pattern → RegExp 缓存，key = `source + ':' + pattern`。
+ *
+ * 唯一的 module-level 可变状态（matcher 是纯函数，缓存为性能优化，不改变语义）。
+ * 进程级生命周期，无需手动清理（pattern 集合有限且有界）。
+ */
+const patternCache = new Map<string, RegExp>();
+
+/**
+ * 把 rule.pattern 编译为 RegExp，按 source 分发（G2）。
+ *
+ *  - source='builtin-danger'：pattern 是 RegExp 源字符串 → `new RegExp(pattern, 'i')`
+ *  - 其余（builtin-safe/user）：pattern 是 OpenCode wildcard → `wildcardToRegExp(pattern)`
+ *
+ * 结果缓存到 patternCache。
+ */
+export function resolvePattern(rule: Rule): RegExp {
+	const cacheKey = rule.source + ":" + rule.pattern;
+	const cached = patternCache.get(cacheKey);
+	if (cached !== undefined) return cached;
+
+	const re =
+		rule.source === "builtin-danger"
+			? new RegExp(rule.pattern, "i")
+			: wildcardToRegExp(rule.pattern);
+
+	patternCache.set(cacheKey, re);
+	return re;
+}
+
+// ──────────────────────── matchRulesForArgv（happy path，W2 clean=true 有 argv[]）────────────────────────
+
+/** 命中 isKnownSafeCommand 时构造的虚拟 builtin-safe rule（保持 matchedRule 字段一致性）。 */
+function virtualSafeRule(argv0: string): Rule {
+	return {
+		id: "builtin-safe",
+		tool: "bash",
+		pattern: argv0,
+		action: "allow",
+		source: "builtin-safe",
+		description: "known safe command (Codex safelist)",
+	};
+}
+
+/**
+ * 对已 tokenize 的 argv 做规则匹配（happy path）。
+ *
+ * 顺序（C3 修正：白名单不再短路，用户 deny 可覆盖白名单，符合 last-match-wins 契约）：
+ *  1. 遍历 rules（last-match-wins），对每条用 resolvePattern(rule).test(argv.join(' '))
+ *     记录 winner。
+ *  2. winner.action === 'deny' → 返回 deny（用户/builtin deny 优先于白名单）
+ *  3. winner.action === 'allow' → 返回 allow
+ *  4. winner.action === 'ask'（无匹配）：
+ *       - isKnownSafeCommand(argv) → allow（白名单兜底，虚拟 builtin-safe rule）
+ *       - 否则 → ask
+ *  5. 空 argv → ask（G1）
+ *
+ * 匹配目标字符串统一为 `argv.join(' ')`（builtin-danger 正则与 user wildcard 都对它匹配）。
+ */
+export function matchRulesForArgv(argv: string[], rules: readonly Rule[]): RuleMatchResult {
+	if (argv.length === 0) {
+		// 空命令无法匹配任何规则 → ask（G1）
+		return { action: "ask", matchedRule: undefined };
+	}
+
+	const commandStr = argv.join(" ");
+
+	let winner: RuleMatchResult = { action: "ask", matchedRule: undefined };
+	for (const rule of rules) {
+		const re = resolvePattern(rule);
+		if (re.test(commandStr)) {
+			winner = { action: rule.action, matchedRule: rule };
+		}
+	}
+
+	// deny / allow 直接由 winner 决定（用户规则可覆盖白名单）
+	if (winner.action === "deny" || winner.action === "allow") {
+		return winner;
+	}
+
+	// winner.action === 'ask'（无规则匹配）→ 白名单兜底
+	if (isKnownSafeCommand(argv)) {
+		return { action: "allow", matchedRule: virtualSafeRule(argv[0] ?? "") };
+	}
+	return winner;
+}
+
+// ──────────────────────── matchRules（退化路径，command 字符串）────────────────────────
+
+/**
+ * 对原始 command 字符串做规则匹配（退化路径 + C1 完整字符串补充检查）。
+ *
+ * 两种使用场景：
+ *  1. 退化路径：W2 AST 解析失败（parseError）或调用方只拿到 command 字符串
+ *     （无法可靠 tokenize argv）。
+ *  2. C1 补充检查：pipeline.ts 对 bash 工具的完整 command 字符串做一次额外
+ *     builtin-danger deny 匹配，覆盖「curl | sh」这类跨 argv 管道命令（AST 按
+ *     管道拆分后单个 argv 不含 `|`，deny 规则的正则无法命中）。
+ *
+ * 行为：
+ *  - toolName !== 'bash' → ask（W3 只管 bash，其他工具交下游）
+ *  - command === undefined / 空字符串 → ask
+ *  - 遍历 rules（last-match-wins），对每条用 resolvePattern(rule).test(command)
+ *  - 无匹配 → ask（G1）
+ *
+ * 不调 isKnownSafeCommand（不查白名单）：command 字符串无法可靠提取 argv
+ * （含引号/转义/管道），argv 级白名单判断由 matchRulesForArgv 在 happy path 负责。
+ * 因此本函数仅用于 deny 补充检查或退化路径，不用作 allow 放行依据。
+ */
+export function matchRules(
+	toolName: string,
+	command: string | undefined,
+	rules: readonly Rule[],
+): RuleMatchResult {
+	if (toolName !== "bash") {
+		return { action: "ask", matchedRule: undefined };
+	}
+	if (command === undefined || command === "") {
+		return { action: "ask", matchedRule: undefined };
+	}
+
+	let winner: RuleMatchResult = { action: "ask", matchedRule: undefined };
+	for (const rule of rules) {
+		const re = resolvePattern(rule);
+		if (re.test(command)) {
+			winner = { action: rule.action, matchedRule: rule };
+		}
+	}
+	return winner;
+}

package/src/rules/wildcard.ts

@@ -0,0 +1,43 @@
+/**
+ * OpenCode 风格 wildcard → RegExp 转换。
+ *
+ * 移植自 opencode-anomaly/packages/core/src/util/wildcard.ts。
+ * 语义：
+ *  - 路径分隔符统一为 '/'（replaceAll('\\','/')）
+ *  - 元字符转义：`[.+^${}()|[\]\\]` → 加 `\` 前缀
+ *  - `*` → `.*`（跨任意字符，含空格）
+ *  - `?` → `.`（单字符）
+ *  - 末尾 ` *` 改写为 `( .*)?`（使 `ls *` 也能匹配无参 `ls`）
+ *  - 全锚定 `^...$`；非 win32 用 `s` flag（dotAll），win32 加 `i`（大小写不敏感）
+ *
+ * 注意：本模块只对 pattern 做 wildcard 编译，不对 input 做路径归一化
+ * （matcher 层调用方负责把 argv.join(' ') 作为 input 传入）。
+ */
+
+/** 非 win32 平台始终返回同一个 flag 字符串，便于上层缓存 key 稳定。 */
+function flags(): string {
+	return process.platform === "win32" ? "si" : "s";
+}
+
+/**
+ * 把 OpenCode 风格 wildcard pattern 编译为全锚定 RegExp。
+ *
+ * 纯函数：相同输入始终产生等价 RegExp（process.platform 在进程生命周期内稳定）。
+ */
+export function wildcardToRegExp(pattern: string): RegExp {
+	let escaped = pattern
+		.replaceAll("\\", "/")
+		.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+		.replace(/\*/g, ".*")
+		.replace(/\?/g, ".");
+
+	// 末尾 ` *`（已转写为 ` .*`）改写为可选的 `( .*)?`，
+	// 使 `ls *` 这类 pattern 也能匹配无参 `ls`。
+	const TRAILING_WILDCARD = " .*";
+	const OPTIONAL_WILDCARD = "( .*)?";
+	if (escaped.endsWith(TRAILING_WILDCARD)) {
+		escaped = escaped.slice(0, -TRAILING_WILDCARD.length) + OPTIONAL_WILDCARD;
+	}
+
+	return new RegExp("^" + escaped + "$", flags());
+}

package/src/statusline.ts

@@ -0,0 +1,226 @@
+/**
+ * Pi Permission statusline — footer 集成（W6 T1）。
+ *
+ * 通过 ctx.ui.setFooter(factory) 注册一个 footer factory，在 TUI 底部显示当前
+ * 权限模式标签（YOLO/AUTO/APPROVE/STRICT）+ enabled 状态。
+ *
+ * 设计参考 extensions/statusline/src/index.ts:84-136 的 UiWithFooter 桥接模式：
+ *  - SDK 未声明 setFooter 的精确类型（stub 为 `setFooter(factory: unknown): void`），
+ *    故本地定义 UiWithFooter 接口，用 `ctx.ui as unknown as UiWithFooter` 桥接。
+ *  - factory 返回 FooterHandle（dispose/invalidate/render），render(width) 返回行数组。
+ *
+ * 单例限制：Pi 只有一个 footer 槽位，本扩展的 footer 会覆盖（或被覆盖）其他扩展
+ * （如 @zhushanwen/pi-statusline）的 footer。已知限制，README 注明。
+ *
+ * 可测试性：createPermissionFooter 是纯函数（输入 mode+enabled，返回 factory）；
+ * renderPermissionLine 是纯函数（输入 mode+enabled+palette，返回行数组），便于单测。
+ */
+
+import type { PermissionMode } from "./types.js";
+import { MODE_LABELS } from "./types.js";
+
+// ──────────────────────── Footer API 适配类型 ────────────────────────
+
+/** Tui 句柄（Pi TUI 提供的渲染接口，最小子集）。 */
+interface TuiHandle {
+	requestRender(): void;
+}
+
+/** Footer 渲染句柄（setFooter 回调的返回值）。 */
+export interface FooterHandle {
+	dispose(): void;
+	invalidate(): void;
+	render(width: number): string[];
+}
+
+/** Footer factory 的签名（setFooter 的回调参数类型）。 */
+export type FooterFactory = (
+	tui: TuiHandle,
+	theme: unknown,
+	footerData: unknown,
+) => FooterHandle;
+
+/**
+ * SDK 缺失的 setFooter 类型 —— 仅本扩展需要。
+ *
+ * 绕过 `as any`：用 `as unknown as` 明确意图，配合本地接口提供类型检查。
+ * SDK 补齐 setFooter 类型后可移除本接口。
+ */
+export interface UiWithFooter {
+	setFooter(fn: FooterFactory): void;
+}
+
+// ──────────────────────── 渲染（纯函数） ────────────────────────
+
+/** 语义色 token 到字符串着色器的映射（与 statusline 扩展的 Pallet 对齐）。 */
+export interface PermissionPalette {
+	/** dim 文本（次要信息） */
+	dim(s: string): string;
+	/** 主文本 */
+	text(s: string): string;
+	/** accent（模式标签高亮） */
+	accent(s: string): string;
+	/** success（enabled 状态） */
+	success(s: string): string;
+	/** warning（disabled 状态） */
+	warning(s: string): string;
+}
+
+/** 模式对应的 accent 色建议（调用方可参考，非强制）。 */
+export const MODE_ACCENT_TOKEN: Record<PermissionMode, "accent" | "warning" | "success"> = {
+	yolo: "warning",
+	auto: "accent",
+	approve: "accent",
+	strict: "success",
+};
+
+/**
+ * 渲染权限状态行（纯函数，便于单测）。
+ *
+ * 输出格式：`[pi-permission] MODE · <enabled|disabled>`
+ *  - mode 标签用 MODE_LABELS（YOLO/Auto/Approve/Strict）
+ *  - enabled=true → success 色 "enabled"
+ *  - enabled=false → warning 色 "disabled"（等同 yolo 但保留配置）
+ *
+ * yolo 模式额外提示 "all tools allowed"，strict 提示 "all require approval"。
+ *
+ * @param mode 当前权限模式
+ * @param enabled 扩展是否启用
+ * @param palette 色彩映射（测试可传纯字符串透传的 palette）
+ * @returns 渲染行（单行，数组包装便于 footer render 统一接口）
+ */
+export function renderPermissionLine(
+	mode: PermissionMode,
+	enabled: boolean,
+	palette: PermissionPalette,
+): string[] {
+	const label = MODE_LABELS[mode];
+	const statePart = enabled
+		? palette.success("enabled")
+		: palette.warning("disabled");
+	const detail = enabled ? modeDetail(mode) : "passthrough (config preserved)";
+	return [`${palette.dim("[pi-permission]")} ${palette.accent(label)} ${palette.dim("·")} ${statePart} ${palette.dim(detail)}`];
+}
+
+/** 各模式的简短补充说明（renderPermissionLine 用）。 */
+function modeDetail(mode: PermissionMode): string {
+	switch (mode) {
+		case "yolo":
+			return "all tools allowed";
+		case "auto":
+			return "AST + rules + AI classifier";
+		case "approve":
+			return "rules + manual approval";
+		case "strict":
+			return "all require approval";
+	}
+}
+
+// ──────────────────────── FooterHandle 实现 ────────────────────────
+
+/**
+ * 创建 footer factory（注册给 ctx.ui.setFooter）。
+ *
+ * factory 返回的 FooterHandle：
+ *  - dispose()：noop（无定时器/订阅需清理；mode 变化由 session_start 重建 factory）
+ *  - invalidate()：清渲染缓存
+ *  - render(width)：返回 renderPermissionLine 结果（缓存 + 截断到 width）
+ *
+ * @param getMode 返回当前 PermissionMode 的闭包（session 内 mode 可变，闭包读最新值）
+ * @param getEnabled 返回当前 enabled 状态的闭包
+ * @param palette 色彩映射（生产用 theme.fg 构造，测试用透传 palette）
+ */
+export function createPermissionFooter(
+	getMode: () => PermissionMode,
+	getEnabled: () => boolean,
+	palette: PermissionPalette,
+): FooterFactory {
+	return (_tui: TuiHandle, _theme: unknown, _footerData: unknown): FooterHandle => {
+		let cachedWidth: number | undefined;
+		let cachedLines: string[] | undefined;
+
+		return {
+			dispose() {
+				/* noop — 无定时器/订阅 */
+			},
+			invalidate() {
+				cachedWidth = undefined;
+				cachedLines = undefined;
+			},
+			render(width: number): string[] {
+				if (cachedWidth === width && cachedLines) {
+					return cachedLines;
+				}
+				const lines = renderPermissionLine(getMode(), getEnabled(), palette);
+				cachedWidth = width;
+				cachedLines = lines;
+				return lines;
+			},
+		};
+	};
+}
+
+// ──────────────────────── 生产 palette 构造 ────────────────────────
+
+/**
+ * 从 Pi Theme 构造 PermissionPalette（生产用）。
+ *
+ * theme.fg(token, text) 是 Pi 的语义着色 API（token 如 "dim"/"text"/"success"）。
+ * 本地包装为 PermissionPalette 接口，便于 footer 与测试共用纯函数。
+ *
+ * @param theme Pi Theme 对象（ctx.ui.theme）
+ */
+export function paletteFromTheme(theme: { fg(token: string, text: string): string }): PermissionPalette {
+	return {
+		dim: (s) => theme.fg("dim", s),
+		text: (s) => theme.fg("text", s),
+		accent: (s) => theme.fg("accent", s),
+		success: (s) => theme.fg("success", s),
+		warning: (s) => theme.fg("warning", s),
+	};
+}
+
+/**
+ * 注册权限 footer 到 ctx.ui（生产入口）。
+ *
+ * 在 session_start handler 里调用。用 `ctx.ui as unknown as UiWithFooter` 桥接
+ * SDK 未声明的 setFooter 类型。
+ *
+ * 防御：headless（json/print）模式或 mock ctx 可能无 setFooter/theme —— 此时跳过
+ * footer 注册（footer 仅 TUI 有意义），返回 noop invalidator。用 duck typing 检查，不抛异常。
+ *
+ * 返回 invalidator：调用它清 footer 渲染缓存 + 触发重绘（mode/enabled 切换后 footer
+ * 才会显示新标签）。FooterHandle 由 Pi 在 factory 内部创建，扩展拿不到，故 invalidator
+ * 通过闭包捕获 factory 内创建的 handle + tui 句柄。
+ *
+ * @param ctxUi ctx.ui 对象（需含 setFooter + theme，缺失则跳过，返回 noop）
+ * @param getMode 返回当前 PermissionMode 的闭包
+ * @param getEnabled 返回当前 enabled 状态的闭包
+ * @returns invalidator 函数（mode 切换成功后调用，使 footer 立即反映新 mode）
+ */
+export function registerPermissionFooter(
+	ctxUi: { setFooter?: unknown; theme?: unknown },
+	getMode: () => PermissionMode,
+	getEnabled: () => boolean,
+): () => void {
+	// duck typing：setFooter 必须是函数，theme 必须有 fg 函数（headless/mock 缺失则跳过）
+	if (typeof ctxUi.setFooter !== "function") return () => {};
+	const theme = ctxUi.theme as { fg?: unknown } | undefined;
+	if (!theme || typeof theme.fg !== "function") return () => {};
+
+	const palette = paletteFromTheme(theme as { fg(token: string, text: string): string });
+	// 闭包捕获：factory 被 Pi 调用时创建的 handle + tui，供 invalidator 刷缓存 + 重绘。
+	let handle: FooterHandle | undefined;
+	let tui: TuiHandle | undefined;
+	const factory = (t: TuiHandle, th: unknown, data: unknown): FooterHandle => {
+		tui = t;
+		const h = createPermissionFooter(getMode, getEnabled, palette)(t, th, data);
+		handle = h;
+		return h;
+	};
+	(ctxUi as unknown as UiWithFooter).setFooter(factory);
+	return () => {
+		handle?.invalidate();
+		tui?.requestRender();
+	};
+}

package/src/types.ts

@@ -0,0 +1,249 @@
+/**
+ * @zhushanwen/pi-permission — 类型定义
+ *
+ * 全部类型统一在此声明，W2-W5 import 使用，避免跨模块类型碎片化。
+ * 对应 slice plan 的 DM1-DM5 数据模型。
+ */
+
+// ──────────────────────── DM1: PermissionMode ────────────────────────
+
+/** 四档权限模式，按严格等级排序（yolo 最低，strict 最高） */
+export type PermissionMode = "yolo" | "auto" | "approve" | "strict";
+
+/** 模式枚举顺序（严格等级从低到高） */
+export const PERMISSION_MODES: PermissionMode[] = ["yolo", "auto", "approve", "strict"];
+
+/** 模式人类可读描述 */
+export const MODE_DESCRIPTIONS: Record<PermissionMode, string> = {
+	yolo: "完全无防护，所有工具调用放行",
+	auto: "安全命令规则直接放行 + 非安全命令过 AI 审查 + AI 认为安全放行/AI 认为非安全人工审批",
+	approve: "自动模式去除 AI，规则匹配后安全放行、非安全直接人工审批",
+	strict: "全部审批",
+};
+
+/** 模式简短标签（statusline / 命令输出用） */
+export const MODE_LABELS: Record<PermissionMode, string> = {
+	yolo: "YOLO",
+	auto: "Auto",
+	approve: "Approve",
+	strict: "Strict",
+};
+
+/** PermissionMode 类型守卫 */
+export function isValidPermissionMode(value: unknown): value is PermissionMode {
+	return typeof value === "string" && PERMISSION_MODES.includes(value as PermissionMode);
+}
+
+// ──────────────────────── DM2: Rule ────────────────────────
+
+/** 权限规则（层 2 规则匹配用） */
+export interface Rule {
+	/** 唯一 id（用户规则 'user-<n>'，内置安全 'builtin-safe-<n>'，内置危险 'builtin-danger-<n>'） */
+	id: string;
+	/** 工具名匹配模式，wildcard（'*' 匹配全部，'bash' 精确匹配） */
+	tool: string;
+	/** 命令匹配模式，wildcard（仅 bash 工具用，其他工具 undefined 或 '*'） */
+	pattern: string;
+	/** 决策动作 */
+	action: PermissionAction;
+	/** 规则来源 */
+	source: RuleSource;
+	/** 可选描述（UI 展示用） */
+	description?: string;
+}
+
+/** 权限决策动作（三态） */
+export type PermissionAction = "allow" | "deny" | "ask";
+
+/** 规则来源 */
+export type RuleSource = "builtin-safe" | "builtin-danger" | "user";
+
+// ──────────────────────── DM3: PermissionDecision ────────────────────────
+
+/** 权限决策结果（checkPermission 返回） */
+export interface PermissionDecision {
+	/** 最终动作 */
+	action: PermissionAction;
+	/** 人类可读原因（UI 展示 + 拒绝理由回传 agent） */
+	reason: string;
+	/** 决策来源（审计/调试用） */
+	source: DecisionSource;
+	/** AI 风险等级（仅 source='ai'） */
+	riskLevel?: RiskLevel;
+	/** 匹配的规则（仅 source='rule'） */
+	matchedRule?: Rule;
+	/** AI 置信度 0-1（仅 source='ai'） */
+	confidence?: number;
+}
+
+/** 决策来源 */
+export type DecisionSource = "mode" | "ast" | "rule" | "ai" | "user";
+
+/** AI 风险等级 */
+export type RiskLevel = "low" | "medium" | "high";
+
+// ──────────────────────── DM4: ClassifierConfig ────────────────────────
+
+/** AI Classifier 配置（层 3 用，W4 实现） */
+export interface ClassifierConfig {
+	/** 是否启用 AI 层（auto 模式自动 true，其他模式忽略） */
+	enabled: boolean;
+	/** 模型：'auto'（选最便宜）或 'provider/model-id'（如 'zhipu/glm-4-flash'） */
+	model: string;
+	/** 超时秒数 */
+	timeout: number;
+	/** 低风险是否自动放行 */
+	autoApproveLowRisk: boolean;
+	/** 高风险是否自动拦截（转人工审批） */
+	autoDenyHighRisk: boolean;
+}
+
+// ──────────────────────── DM5: PermissionConfig ────────────────────────
+
+/** 扩展配置（~/.pi/agent/permission-config.json 持久化格式） */
+export interface PermissionConfig {
+	/** 当前权限模式 */
+	mode: PermissionMode;
+	/** 扩展是否启用（false=完全放行，等同于 yolo 但保留配置） */
+	enabled: boolean;
+	/** AI Classifier 配置 */
+	classifier: ClassifierConfig;
+	/** 用户自定义规则（内置规则在代码里硬编码，不进配置） */
+	userRules: Rule[];
+}
+
+// ──────────────────────── 默认配置 ────────────────────────
+
+export const DEFAULT_CLASSIFIER_CONFIG: ClassifierConfig = {
+	enabled: true,
+	model: "auto",
+	timeout: 90,
+	autoApproveLowRisk: true,
+	autoDenyHighRisk: true,
+};
+
+export const DEFAULT_CONFIG: PermissionConfig = {
+	mode: "yolo",
+	enabled: true,
+	classifier: { ...DEFAULT_CLASSIFIER_CONFIG },
+	userRules: [],
+};
+
+// ──────────────────────── 后续 wave 用的类型（W1 声明，W2-W5 import） ────────────────────────
+
+/** 权限检查输入（I1 checkPermission 参数） */
+export interface PermissionCheckInput {
+	toolName: string;
+	command?: string;
+	path?: string;
+	toolInput?: unknown;
+	cwd: string;
+	agentName?: string;
+}
+
+/** 权限上下文（I1 checkPermission 参数，含当前模式 + 规则 + classifier 配置） */
+export interface PermissionContext {
+	mode: PermissionMode;
+	rules: Rule[];
+	classifier: ClassifierConfig;
+	enabled: boolean;
+	signal?: AbortSignal;
+}
+
+/** bash 结构分析结果（I2 analyzeBashStructure 返回，W2 实现） */
+export interface BashAnalysis {
+	/** 是否只有白名单结构（干净 SimpleCommand） */
+	clean: boolean;
+	/** 提取的命令 token 数组（每个元素是一条 SimpleCommand 的 argv） */
+	commands: string[][];
+	/** 检测到的危险结构节点类型（command_substitution/file_redirect/subshell 等） */
+	dangerousStructures: string[];
+	/** AST 解析是否失败（malformed 语法） */
+	parseError: boolean;
+}
+
+/** 规则匹配结果（I3 matchRules 返回，W3 实现） */
+export interface RuleMatchResult {
+	action: PermissionAction;
+	matchedRule?: Rule;
+}
+
+/** AI 分类结果（I4 classifyRisk 返回，W4 实现） */
+export interface ClassifierResult {
+	risk_level: RiskLevel;
+	outcome: PermissionAction;
+	reasoning: string;
+	confidence: number;
+}
+
+/** AI 分类器的工具调用上下文（I4 输入） */
+export interface ToolInvocationContext {
+	toolName: string;
+	command?: string;
+	path?: string;
+	cwd: string;
+	agentName?: string;
+}
+
+/** 用户审批决策（I5 Racing 的 showUserDialog 返回，W5 实现） */
+export interface UserDecision {
+	approved: boolean;
+	reason?: string;
+	scope?: "once" | "session" | "always";
+}
+
+// ──────────────────────── W6 T8: 从 pipeline.ts 迁移的类型 ────────────────────────
+
+/**
+ * 用户审批 UI 需要的数据（runLayer3WithRacing / approve / strict 传给 requestUserApproval）。
+ *
+ * reason 是人类可读的「为什么要审批」（含工具名 + 命令 + 触发原因），由 buildApprovalRequest 构造。
+ * preClassification 仅 auto 模式 AI 先返回时携带（让用户看到 AI 的判断，辅助决策）。
+ *
+ * W6 T8：从 pipeline.ts 迁移到 types.ts（统一类型声明），pipeline.ts re-export 保持 public API。
+ */
+export interface ApprovalRequest {
+	toolName: string;
+	command?: string;
+	reason: string;
+	preClassification?: ClassifierResult;
+}
+
+/**
+ * checkPermission 的外部依赖（DI 便于测试 mock）。
+ *
+ * - analyzeBashStructure：W2 AST 分析（层 1）。
+ * - matchRulesForArgv：W3 规则匹配（层 2，bash happy path）。
+ * - getDefaultRules：W3 内置危险规则（12 条 builtin-danger）。
+ * - classifier.classifyRisk：W4 AI 风险分类（层 3）。
+ * - requestUserApproval：W5 用户审批 UI（TUI/RPC/headless 三分支）。
+ *
+ * 生产装配见 production.ts；测试 mock 见 pipeline.test.ts。
+ *
+ * W6 T8：从 pipeline.ts 迁移到 types.ts（统一类型声明），pipeline.ts re-export 保持 public API。
+ */
+export interface CheckPermissionDeps {
+	analyzeBashStructure: (command: string) => Promise<BashAnalysis>;
+	matchRulesForArgv: (argv: string[], rules: readonly Rule[]) => RuleMatchResult;
+	getDefaultRules: () => Rule[];
+	/**
+	 * 是否处于 headless 模式（json/print，无交互 UI）。
+	 *
+	 * auto 模式 Racing 用此判断：headless 时不启动 user promise（立即 deny 会抢占 AI 的 race），
+	 * 纯等 AI classifier 判定；AI 失败/超时则 fail-closed deny。
+	 * strict/approve 不受影响——它们的 askUser 走 requestHeadless 立即 deny（无 AI 可兜底）。
+	 */
+	isHeadless: () => boolean;
+	classifier: {
+		classifyRisk: (
+			ctx: ToolInvocationContext,
+			config: ClassifierConfig,
+			signal?: AbortSignal,
+		) => Promise<ClassifierResult>;
+	};
+	requestUserApproval: (
+		req: ApprovalRequest,
+		ctx: ToolInvocationContext,
+		signal: AbortSignal | undefined,
+	) => Promise<UserDecision>;
+}