pi-verdict 0.2.0 → 0.2.1

package/README.md

@@ -21,7 +21,11 @@
 | [@zhushanwen/pi-permission](https://www.npmjs.com/package/@zhushanwen/pi-permission) | ✅ (outcome) | ❌ single-turn, no context | closed (→ ask) | 4 |
 | [@gotgenes/pi-permission-system](https://github.com/gotgenes/pi-packages) | ✅ deterministic only | — (no built-in classifier) | closed | 3 |
 
-Full landscape: [`research/pi-permission-landscape.md`](research/pi-permission-landscape.md). The single-file, zero-dependency shape is deliberate — the whole extension is one readable [~590-line file](extensions/auto-mode.ts).
+Full landscape: [`research/pi-permission-landscape.md`](research/pi-permission-landscape.md) · convergence analysis with the closest architectural relative: [`research/pi-automode-convergence.md`](research/pi-automode-convergence.md).
+
+Honest framing: pi-automode and pi-verdict have **converged on the same architecture** (deny floor → user rules → classifier, fail-closed — see the convergence analysis). What remains distinct here: a classifier that can say `ask` (runtime human-in-the-loop, not just rule-declared), a built-in floor you can turn off (`builtinDenyFloor` — user sovereignty), a zero-dependency single file (~700 lines, deliberate), and the measurement habit — every design decision in this repo is backed by shipped research.
+
+The single-file, zero-dependency shape is deliberate — the whole extension is one readable [~700-line file](extensions/auto-mode.ts).
 
 ## Pipeline
 
@@ -84,13 +88,16 @@ cp extensions/auto-mode.ts ~/.pi/agent/extensions/
 {
   "allow": ["^ls\\b", "^git (status|log|diff)\\b"],
   "deny":  ["rm ", "docker ", "^/etc/"],
-  "builtinDenyFloor": true
+  "builtinDenyFloor": true,
+  "classifierModel": null
 }
 ```
 
 - `allow`/`deny` are JS regex arrays; **`deny` wins over `allow`**, both beat the classifier
 - matched against the **full command string** for bash, the **absolute path** for file tools (read/write/edit/grep/find/ls); other tools (MCP etc.) always go to the classifier
 - `builtinDenyFloor: false` turns the built-in danger/path floor off entirely (risk accepted by you; the classifier and your rules remain)
+- `classifierModel: "provider/model-id"` persistently sets the classifier model (e.g. a fast flash-class model); precedence is flag > env > config > session model (self-reflection); an invalid value falls back to the session model with a one-time warning
+- the spec accepts pi's native `--model` thinking suffix: `"zai/glm-4-flash:low"` sets classifier thinking to effort low (default without suffix: thinking explicitly off — the [measured](research/thinking-param-blackhole.md) default)
 - first run generates a template at `~/.pi/agent/config/pi-verdict.json` (honors `PI_CODING_AGENT_DIR`); changes apply to new sessions
 
 Why no built-in allowlist? A third-party security audit ([`research/rule-layer-security-audit.md`](research/rule-layer-security-audit.md)) showed that allowlist soundness requires shell AST analysis — every built-in "always allow" would be a security claim maintained by the author. The built-in layer only makes **deny** claims (the sound direction); allow claims are yours.
@@ -105,6 +112,8 @@ Design decisions here are settled by measurement, and the lab notes ship with th
 - [`research/thinking-param-blackhole.md`](research/thinking-param-blackhole.md) — three-layer forensic root-cause of thinking models burning the classifier budget; why the fix is `thinkingEnabled: false`
 - [`research/rule-engine-sim`](research/rule-engine-sim/README.md) — measured a tree-sitter rule-engine port against 746 real bash calls (**absorbs 0 gray calls**) and rejected it
 - [`research/pi-permission-landscape.md`](research/pi-permission-landscape.md) — the competitive landscape this README's positioning is checked against
+- [`research/rule-layer-security-audit.md`](research/rule-layer-security-audit.md) — third-party audit of the rule layer (8/8 reproduced → fixed architecturally in 0.2.0)
+- [`research/pi-automode-convergence.md`](research/pi-automode-convergence.md) — where this project genuinely converges with pi-automode, and what remains distinct
 - [`research/claude-code-classifier-prompts.md`](research/claude-code-classifier-prompts.md) — structural reconstruction of Claude Code's classifier design (via self-hosted Langfuse observations) that this extension's transcript contract descends from
 
 ## Status & limitations

package/README.zh-CN.md

@@ -21,7 +21,11 @@
 | [@zhushanwen/pi-permission](https://www.npmjs.com/package/@zhushanwen/pi-permission) | ✅(outcome) | ❌ 单轮无上下文 | closed(→ ask) | 4 |
 | [@gotgenes/pi-permission-system](https://github.com/gotgenes/pi-packages) | ✅ 纯确定性 | —(无内置分类器) | closed | 3 |
 
-完整全景:[`research/pi-permission-landscape.md`](research/pi-permission-landscape.md)。零依赖单文件形态是有意为之——整个扩展就是一个可通读的 [~590 行文件](extensions/auto-mode.ts)。
+完整全景:[`research/pi-permission-landscape.md`](research/pi-permission-landscape.md) · 与最近架构亲缘的收敛分析:[`research/pi-automode-convergence.md`](research/pi-automode-convergence.md)。
+
+诚实地说:pi-automode 与 pi-verdict 在**架构上已收敛**(deny floor → 用户规则 → 分类器,fail-closed——见收敛分析)。这里仍然不同的是:分类器能说 `ask`(运行时人工介入,而非仅由规则预声明)、内置 floor 可以关(`builtinDenyFloor`——用户主权)、零依赖单文件(~700 行,刻意为之)、以及测量的习惯——本仓库每个设计决策都有随库研究背书。
+
+零依赖单文件形态是有意为之——整个扩展就是一个可通读的 [~700 行文件](extensions/auto-mode.ts)。
 
 ## 管线
 
@@ -83,13 +87,16 @@ cp extensions/auto-mode.ts ~/.pi/agent/extensions/
 {
   "allow": ["^ls\\b", "^git (status|log|diff)\\b"],
   "deny":  ["rm ", "docker ", "^/etc/"],
-  "builtinDenyFloor": true
+  "builtinDenyFloor": true,
+  "classifierModel": null
 }
 ```
 
 - `allow`/`deny` 为 JS 正则数组;**`deny` 优先于 `allow`**,两者都优先于分类器
 - 匹配目标:bash = **完整命令串**;文件类工具(read/write/edit/grep/find/ls)= **绝对路径**;其余工具(MCP 等)恒走分类器
 - `builtinDenyFloor: false` 可整体关闭内置危险/路径拦截(风险自担;分类器与你的规则仍在)
+- `classifierModel: "provider/model-id"` 持久指定分类器模型(如轻量 flash 类);优先级 flag > env > config > 自省;无效值回退会话模型并一次性警告
+- spec 支持 pi 原生 `--model` 思考级别后缀:`"zai/glm-4-flash:low"` 将分类器思考设为 effort low(无后缀缺省 = 显式关思考,[实测](research/thinking-param-blackhole.md)背书的默认)
 - 首次运行自动生成模板 `~/.pi/agent/config/pi-verdict.json`(尊重 `PI_CODING_AGENT_DIR`);修改后新会话生效
 
 为什么没有内置白名单?第三方安全审计(见 [`research/rule-layer-security-audit.md`](research/rule-layer-security-audit.md))证明白名单的健全性需要 shell AST 分析——每条内置「永远放行」都是作者维护的安全声明。因此内置层只做 **deny** 声明(方向健全),allow 声明归你。
@@ -104,6 +111,8 @@ cp extensions/auto-mode.ts ~/.pi/agent/extensions/
 - [`research/thinking-param-blackhole.md`](research/thinking-param-blackhole.md) —— 思考模型烧尽分类器预算的三层取证,以及为什么修复是 `thinkingEnabled: false`
 - [`research/rule-engine-sim`](research/rule-engine-sim/README.md) —— 用 746 条真实 bash 调用实测 tree-sitter 规则引擎移植(**灰区吸收 0 条**)并否决
 - [`research/pi-permission-landscape.md`](research/pi-permission-landscape.md) —— 本 README 定位所对照的竞品全景
+- [`research/rule-layer-security-audit.md`](research/rule-layer-security-audit.md) —— 规则层第三方安全审计(8/8 复现 → 0.2.0 架构性修复)
+- [`research/pi-automode-convergence.md`](research/pi-automode-convergence.md) —— 与 pi-automode 何处真正收敛、何处仍然不同
 - [`research/claude-code-classifier-prompts.md`](research/claude-code-classifier-prompts.md) —— Claude Code 分类器设计的结构化还原(基于自托管 Langfuse 观测),本扩展 transcript 契约的血统来源
 
 ## 状态与限制

package/extensions/auto-mode.ts

@@ -23,11 +23,13 @@
  *
  * 配置:
  *   --auto-mode / --no-auto-mode   CLI flag,总开关(默认开)
- *   --auto-mode-model provider/id  分类器模型(默认继承会话当前模型)
+ *   --auto-mode-model provider/id[:thinking]  分类器模型 + 可选思考级别后缀
+ *                                  (pi 原生 --model 语法;缺省 off = 显式关思考)
  *   PI_AUTO_MODE_MODEL             同上的环境变量形式
  *   --auto-mode-debug             所有裁决(含放行)都弹通知;影子缓存标注同步开启
  *   PI_AUTO_MODE_DEBUG=1           同上的环境变量形式(兼容保留)
- *   <agentDir>/config/pi-verdict.json   用户规则:{ allow: [regex], deny: [regex] }
+ *   <agentDir>/config/pi-verdict.json   用户规则:{ allow: [regex], deny: [regex],
+ *                                     builtinDenyFloor, classifierModel }
  *                                     匹配:bash=完整命令串 / 文件工具=绝对路径;新会话生效
  *
  * 已知原型简化(见 README「已知限制」):
@@ -101,9 +103,11 @@ interface UserRules {
 	deny: RegExp[];
 	/** 内置 deny floor 开关(危险正则 + 路径敏感度 deny),默认 true;关闭后依赖用户规则与分类器 */
 	builtinDenyFloor: boolean;
+	/** 分类器模型 spec(provider/id);null = 未配置(自省继承会话模型) */
+	classifierModel: string | null;
 }
 
-const EMPTY_RULES: UserRules = { allow: [], deny: [], builtinDenyFloor: true };
+const EMPTY_RULES: UserRules = { allow: [], deny: [], builtinDenyFloor: true, classifierModel: null };
 
 function userConfigPath(): string {
 	const agentDir = process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent");
@@ -111,10 +115,11 @@ function userConfigPath(): string {
 }
 
 const USER_CONFIG_TEMPLATE = `${JSON.stringify({
-	_hint: "pi-verdict 用户规则。allow/deny 为 JS 正则数组;deny 优先于 allow;匹配目标:bash=完整命令串,文件工具=绝对路径。builtinDenyFloor=false 可关闭内置危险规则/路径敏感度拦截(风险自担)。修改后新会话生效。",
+	_hint: "pi-verdict 用户规则。allow/deny 为 JS 正则数组;deny 优先于 allow;匹配目标:bash=完整命令串,文件工具=绝对路径。builtinDenyFloor=false 可关闭内置危险规则/路径敏感度拦截(风险自担)。classifierModel 可持久指定分类器模型(provider/id,如 zai/glm-4-flash;可带 pi 原生思考后缀如 zai/glm-4-flash:low;留空=自省继承会话模型)。修改后新会话生效。",
 	allow: ["^ls\\b"],
 	deny: [],
 	builtinDenyFloor: true,
+	classifierModel: null,
 }, null, 2)}\n`;
 
 /**
@@ -131,7 +136,7 @@ function loadUserRules(): { rules: UserRules; skipped: string[] } {
 			} catch { /* 只读环境静默跳过 */ }
 			return { rules: EMPTY_RULES, skipped: [] };
 		}
-		const raw = JSON.parse(fs.readFileSync(p, "utf8")) as { allow?: unknown; deny?: unknown; builtinDenyFloor?: unknown };
+		const raw = JSON.parse(fs.readFileSync(p, "utf8")) as { allow?: unknown; deny?: unknown; builtinDenyFloor?: unknown; classifierModel?: unknown };
 		const skipped: string[] = [];
 		const compile = (list: unknown): RegExp[] =>
 			(Array.isArray(list) ? list : []).filter((x): x is string => typeof x === "string").flatMap((src) => {
@@ -142,7 +147,15 @@ function loadUserRules(): { rules: UserRules; skipped: string[] } {
 					return [];
 				}
 			});
-		return { rules: { allow: compile(raw.allow), deny: compile(raw.deny), builtinDenyFloor: raw.builtinDenyFloor !== false }, skipped };
+		return {
+			rules: {
+				allow: compile(raw.allow),
+				deny: compile(raw.deny),
+				builtinDenyFloor: raw.builtinDenyFloor !== false,
+				classifierModel: typeof raw.classifierModel === "string" && raw.classifierModel.trim() ? raw.classifierModel.trim() : null,
+			},
+			skipped,
+		};
 	} catch {
 		return { rules: EMPTY_RULES, skipped: [] };
 	}
@@ -345,6 +358,7 @@ async function callClassifierOnce(
 	model: NonNullable<ExtensionContext["model"]>,
 	userMessage: string,
 	maxTokens: number,
+	thinking: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" = "off",
 ): Promise<{ ok: true; text: string; stopReason: string } | { ok: false; error: string }> {
 	const signals = [AbortSignal.timeout(CLASSIFIER_TIMEOUT_MS)];
 	if (ctx.signal) signals.push(ctx.signal);
@@ -359,14 +373,14 @@ async function callClassifierOnce(
 				signal: AbortSignal.any(signals),
 				maxTokens,
 				temperature: 0,
-				// 关思考必须用 API 原生字段 thinkingEnabled:false,而非 reasoning:"off"。
-				// 扩展侧 ModelRegistry 只暴露 API 层 complete(),其选项类型没有 reasoning 字段
-				// (它是 SimpleStreamOptions 的字段;宽类型 Model<Api> 的索引签名让 TS 静默放行,
-				// 运行时被丢弃)——minimal/off 从未生效,GLM 按默认 max 档思考烧尽预算/超时。
-				// anthropic-messages 栈上 thinkingEnabled:false → thinking:{"type":"disabled"}
-				// → GLM 降为 effort low 轻思考;其他 API 为无害多余
-				// 属性,交由防御重试兜底。根因与研究:research/thinking-param-blackhole.md
-				thinkingEnabled: false,
+				// 思考参数必须用 API 原生字段(thinkingEnabled/effort),而非 reasoning
+				// (API 层 complete() 无此字段,宽类型索引签名静默放行后运行时丢弃——见
+				// research/thinking-param-blackhole.md)。
+				// 缺省 off = 显式关思考(实证送达 thinking:{"type":"disabled"},GLM 降为
+				// effort low 轻思考);后缀级别经 adaptive effort 送达(minimal→low 映射)。
+				...(thinking === "off"
+					? { thinkingEnabled: false }
+					: { thinkingEnabled: true, effort: thinking === "minimal" ? ("low" as const) : thinking }),
 				cacheRetention: "short",
 				sessionId: ctx.sessionManager.getSessionId(),
 			},
@@ -391,6 +405,7 @@ async function classifyWithModel(
 	ctx: ExtensionContext,
 	model: NonNullable<ExtensionContext["model"]>,
 	actionLine: string,
+	thinking: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" = "off",
 ): Promise<ClassifierOutcome> {
 	const transcript = buildTranscript(ctx, actionLine);
 	const userMessage = `<transcript>\n${transcript}\n</transcript>\nJudge the LAST action in the transcript above. Your entire response MUST begin with <verdict>.`;
@@ -398,7 +413,7 @@ async function classifyWithModel(
 	const failures: string[] = [];
 	for (const [n, maxTokens] of attempts) {
 		if (ctx.signal?.aborted) break; // 用户已取消,不再重试
-		const r = await callClassifierOnce(ctx, model, userMessage, maxTokens);
+		const r = await callClassifierOnce(ctx, model, userMessage, maxTokens, thinking);
 		if (r.ok) {
 			const diag = `stopReason=${r.stopReason}, model=${model.id}, 原始输出=${JSON.stringify(r.text.slice(0, 200))}`;
 			if (r.stopReason !== "error" && r.stopReason !== "aborted") {
@@ -540,7 +555,7 @@ function shadowTag(probe: ShadowProbe): string {
 
 export default function autoMode(pi: ExtensionAPI) {
 	pi.registerFlag("auto-mode", { description: "Enable Auto Mode (rules + model classifier gating for tool calls)", type: "boolean", default: true });
-	pi.registerFlag("auto-mode-model", { description: "Classifier model as provider/id (default: inherit session model)", type: "string" });
+	pi.registerFlag("auto-mode-model", { description: "Classifier model as provider/id[:thinking] (pi --model syntax; default: inherit session model)", type: "string" });
 	pi.registerFlag("auto-mode-debug", { description: "Notify every verdict incl. allows, with shadow-cache annotation", type: "boolean", default: false });
 
 	let enabled = pi.getFlag("auto-mode") !== false;
@@ -590,14 +605,44 @@ export default function autoMode(pi: ExtensionAPI) {
 		},
 	});
 
+	let warnedClassifierModel = false;
+	/** 思考级别集(pi 原生 EXTENDED_THINKING_LEVELS;后缀语法对齐 pi --model provider/id:thinking) */
+	const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+
+	/** 解析 "provider/id:thinking" → { specPart, level }。无效后缀 → 忽略并警告一次 */
+	function parseModelSpec(raw: string, ctx: ExtensionContext): { specPart: string; level: string | null } {
+		const slash = raw.lastIndexOf("/");
+		const colon = raw.lastIndexOf(":");
+		if (colon > slash + 1 && THINKING_LEVELS.has(raw.slice(colon + 1))) {
+			return { specPart: raw.slice(0, colon), level: raw.slice(colon + 1) };
+		}
+		if (colon > slash + 1 && !warnedClassifierModel) {
+			warnedClassifierModel = true;
+			ctx.ui.notify(`pi-verdict:思考级别后缀 "${raw.slice(colon + 1)}" 无效(合法:${[...THINKING_LEVELS].join("/")}),已忽略`, "warning");
+		}
+		return { specPart: raw, level: null };
+	}
+
+	/** 分类器思考级别:spec 后缀指定;缺省 off(显式关思考,blackhole 研究背书) */
+	let classifierThinking: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" = "off";
+
 	function resolveClassifierModel(ctx: ExtensionContext): NonNullable<ExtensionContext["model"]> | null {
-		const spec = (pi.getFlag("auto-mode-model") as string | undefined) ?? process.env.PI_AUTO_MODE_MODEL;
-		if (spec) {
-			const slash = spec.indexOf("/");
+		// 优先级:CLI flag > 环境变量 > 配置文件(classifierModel) > 自省(会话模型)
+		const raw =
+			(pi.getFlag("auto-mode-model") as string | undefined) ?? process.env.PI_AUTO_MODE_MODEL ?? userRules.classifierModel;
+		classifierThinking = "off";
+		if (raw) {
+			const { specPart, level } = parseModelSpec(raw, ctx);
+			if (level) classifierThinking = level as typeof classifierThinking;
+			const slash = specPart.indexOf("/");
 			if (slash > 0) {
-				const model = ctx.modelRegistry.find(spec.slice(0, slash), spec.slice(slash + 1));
+				const model = ctx.modelRegistry.find(specPart.slice(0, slash), specPart.slice(slash + 1));
 				if (model && ctx.modelRegistry.hasConfiguredAuth(model)) return model;
 			}
+			if (!warnedClassifierModel) {
+				warnedClassifierModel = true; // 每会话仅警告一次,避免逐调用刷屏
+				ctx.ui.notify(`pi-verdict:分类器模型 "${raw}" 不可用(未找到或未配置凭证),回退会话模型(自省)`, "warning");
+			}
 		}
 		return ctx.model ?? null; // 自省:继承当前会话模型
 	}
@@ -635,7 +680,7 @@ export default function autoMode(pi: ExtensionAPI) {
 		const ctxKey = shadowContextKey(ctx);
 		const probe = shadow.probe(cmdKey, ctxKey);
 
-		const outcome = await classifyWithModel(ctx, model, action);
+		const outcome = await classifyWithModel(ctx, model, action, classifierThinking);
 
 		// 影子回记:真实模型 allow/deny 入缓存;ask 与 fail-closed 不入(#5 定案);
 		// 命中且本次为可缓存裁决时,对比反事实一致性

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-verdict",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Pi coding agent extension: automatic tool-call permission verdicts — rule layer + model classifier with three-state adjudication (allow/ask/deny), fail-closed, evidence-driven",
   "author": "Jesset (https://github.com/jesset)",
   "type": "module",