pi-verdict 0.13.1 → 0.14.0

package/README.md

@@ -157,6 +157,7 @@ pi 0.99 can run model-written JavaScript in a QuickJS sandbox (`codemode`) that
 - **`ignoreTools` and MCP names**: tool names are normalized — every character outside `[A-Za-z0-9_]` becomes `_` (`mcp__dev-radius__x` → `mcp__dev_radius__x`); exemption entries must use the normalized form
 - **Cost amplification**: one script may issue up to 256 nested calls; gray-zone calls classify one by one, so a slow LLM classifier multiplies per-call latency
 - **Exposure boundary**: adding an MCP server auto-enables codemode, and `pi --no-extensions -e builtin:mcp` runs MCP tools with no extensions loaded — i.e. without this gate. The gate is itself an extension, so it cannot be active in a session that loads none; the boundary is inherent to pi's extension model, stated here rather than papered over
+- **Batch latency is configurable** ([ADR-0006](docs/adr/0006-codemode-nested-calls-policy.md)): every nested call adjudicates individually and gray-zone adjudication is serial (~350ms/call measured), so large script batches pay real latency. `"codemodeNestedCalls": "rules-only"` opts nested calls into the deterministic layers only (rules, floor, self-protection, denyPaths + ask) — the gray zone passes; the trade-off is that rule-passing actions the classifier would have caught (e.g. a nested `bash head ~/.ssh/config` without a denyPaths declaration) pass too. Audit records carry `toolCallId`/`parentToolCallId` either way
 
 ### Self-protection (the gate guards itself — [ADR-0001](docs/adr/0001-self-protection-layer.md))
 
@@ -184,7 +185,7 @@ Honest framing: pi-automode and pi-verdict have **converged on the same architec
 
 ![pi-verdict security gate — tool-call adjudication pipeline](https://cdn.jsdelivr.net/gh/jesset/pi-verdict@main/docs/diagrams/security-pipeline.en.svg)
 
-*Diagram source & regeneration: [docs/diagrams/](docs/diagrams/README.md). Pipeline as of v0.12 — the ASCII version below is the text-faithful equivalent.*
+*Diagram source & regeneration: [docs/diagrams/](docs/diagrams/README.md). Pipeline as of v0.14 — the ASCII version below is the text-faithful equivalent.*
 
 ```
 tool_call
@@ -202,12 +203,13 @@ tool_call
   │     ├─ ignoreTools: your declared uncovered tools → allow, zero model calls
   │     └─ no built-in allowlist — every "always allow" claim is yours to make
   │
-  ├─ 2. Gray zone → model classifier (defaults to session model — "self-reflection")
-  │     ├─ input: CC-style <transcript> — recent user intent + tool calls,
-  │     │        action under review always last
-  │     └─ output: native classify() answers (choice + probabilities + confidence;
-  │              tag-free reason, full contract line in the audit rawResponse) or,
-  │              on the chat path, <verdict>…</verdict> prefix-anchored free text
+  ├─ 2. Gray zone → nested-call policy, then model classifier
+  │     ├─ nested call (codemode) + codemodeNestedCalls=rules-only → pass;
+  │     │   deterministic layers above already ran (ADR-0006)
+  │     ├─ gate (default, or a direct call) → classifier: native classify()
+  │     │   (choice + probabilities + confidence; tag-free reason, full contract
+  │     │   line in the audit rawResponse) or, on the chat path (session-model
+  │     │   self-reflection), <verdict>…</verdict> prefix-anchored free text
   │
   └─ 3. Three-state adjudication
         ├─ allow → pass

package/README.zh-CN.md

@@ -157,6 +157,7 @@ pi 0.99 可以在 QuickJS 沙箱(`codemode`)里运行模型写的 JavaScript 去
 - **`ignoreTools` 与 MCP 工具名**:工具名会归一化——`[A-Za-z0-9_]` 之外的字符统一变 `_`(`mcp__dev-radius__x` → `mcp__dev_radius__x`);豁免条目必须写归一化后的形态
 - **成本放大**:单个脚本最多可发 256 次嵌套调用,灰区调用逐个分类,慢的 LLM 分类器会把单次延迟成倍放大
 - **暴露边界**:添加 MCP 服务器会自动开启 codemode,而 `pi --no-extensions -e builtin:mcp` 可在不加载任何扩展(即无本门禁)的情况下启用 MCP 工具。门禁自身即扩展,在完全不加载扩展的会话中无法生效;此边界为 pi 扩展模型的固有属性,此处显式陈述而非掩饰
+- **批量延迟可配置**([ADR-0006](docs/adr/0006-codemode-nested-calls-policy.md)):每个嵌套调用独立裁决且灰区裁决为串行(实测 ~350ms/次),大脚本批次的判定开销可观。`"codemodeNestedCalls": "rules-only"` 让嵌套调用只走确定性层(规则、floor、自保护、denyPaths + ask)——灰区直接放行;代价是规则层放行、但分类器会拦的动作(如未声明 denyPaths 时的嵌套 `bash head ~/.ssh/config`)同样放行。两种模式下审计记录均携带 `toolCallId`/`parentToolCallId` 归因
 
 ### 自保护(门禁守护自身——[ADR-0001](docs/adr/0001-self-protection-layer.md))
 
@@ -184,7 +185,7 @@ pi 0.99 可以在 QuickJS 沙箱(`codemode`)里运行模型写的 JavaScript 去
 
 ![pi-verdict 安全门禁——工具调用判定管线](https://cdn.jsdelivr.net/gh/jesset/pi-verdict@main/docs/diagrams/security-pipeline.zh.svg)
 
-*图源与再生成：[docs/diagrams/](docs/diagrams/README.md)。管线基准：v0.12——下方 ASCII 为文本等价版。*
+*图源与再生成：[docs/diagrams/](docs/diagrams/README.md)。管线基准：v0.14——下方 ASCII 为文本等价版。*
 
 ```
 tool_call
@@ -202,10 +203,13 @@ tool_call
   │     ├─ ignoreTools:用户声明的未覆盖工具 → 直接放行,零模型调用
   │     └─ 无内置白名单 —— 「永远放行」的声明由你自己做
   │
-  ├─ 2. 灰区 → 模型分类器(默认继承会话模型 —— "自省")
-  │     ├─ 输入:CC 风格 <transcript> —— 近期用户意图 + 工具调用,
-  │     │        待审动作固定在末尾
-  │     └─ 输出契约:<verdict>allow|ask|deny</verdict> 前缀锚定
+  ├─ 2. 灰区 → 嵌套策略,再进模型分类器
+  │     ├─ 嵌套调用(codemode)+ codemodeNestedCalls=rules-only → 放行;
+  │     │   上方确定性层已全部跑完(ADR-0006)
+  │     ├─ gate(默认,或直发调用)→ 分类器:原生 classify()
+  │     │   (choice + probabilities + confidence;reason 无标签,完整契约行
+  │     │   存审计 rawResponse)或 chat 路径(会话模型自省)的
+  │     │   <verdict>…</verdict> 前缀锚定自由文本
   │
   └─ 3. 三态裁决
         ├─ allow → 放行

package/extensions/pi-verdict.ts

@@ -276,9 +276,17 @@ interface UserRules {
 	/** #67: does the second layer adjudicate cascaded calls ("enforce", default since
 	 *  0.12.0) or only record its opinion while the human decides ("shadow")? */
 	classifierFallbackMode: "shadow" | "enforce";
+	/** #90/ADR-0006: nested-call policy. "gate" (default) = nested calls adjudicate
+	 *  identically to direct calls; "rules-only" = nested calls keep every
+	 *  deterministic layer (self-protection, floor, user rules, denyPaths + its ask)
+	 *  and skip only the classifier + cascade — the gray zone passes, because serial
+	 *  adjudication of codemode batches amplifies per-call latency (live-fire:
+	 *  ~350ms/call). Opt-in: rule-passing actions the classifier would have caught
+	 *  pass under rules-only (coverage is denyPaths-declaration-dependent). */
+	codemodeNestedCalls: "gate" | "rules-only";
 }
 
-const EMPTY_RULES: UserRules = { allow: [], deny: [], denyPaths: [], ignoreTools: [], builtinDenyFloor: true, classifierModel: null, toggleShortcut: DEFAULT_TOGGLE_SHORTCUT, audit: false, notifyAllows: false, classifierMinConfidence: null, classifierFallbackModel: null, classifierFallbackMode: "enforce" };
+const EMPTY_RULES: UserRules = { allow: [], deny: [], denyPaths: [], ignoreTools: [], builtinDenyFloor: true, classifierModel: null, toggleShortcut: DEFAULT_TOGGLE_SHORTCUT, audit: false, notifyAllows: false, classifierMinConfidence: null, classifierFallbackModel: null, classifierFallbackMode: "enforce", codemodeNestedCalls: "gate" };
 
 /** This module's own file location (import.meta.url resolved; null = unresolvable). */
 const OWN_FILE_PATH: string | null = (() => {
@@ -371,7 +379,7 @@ function loadUserRules(): { rules: UserRules; skipped: string[]; shortcutWarning
 			} catch { /* 只读环境静默跳过 */ }
 			return { rules: EMPTY_RULES, skipped: [], shortcutWarning: null };
 		}
-		let raw: { allow?: unknown; deny?: unknown; denyPaths?: unknown; ignoreTools?: unknown; builtinDenyFloor?: unknown; classifierModel?: unknown; toggleShortcut?: unknown; audit?: unknown; notifyAllows?: unknown; classifierFallbackModel?: unknown; classifierFallbackConfidence?: unknown; classifierMinConfidence?: unknown; classifierFallbackMode?: unknown };
+		let raw: { allow?: unknown; deny?: unknown; denyPaths?: unknown; ignoreTools?: unknown; builtinDenyFloor?: unknown; classifierModel?: unknown; toggleShortcut?: unknown; audit?: unknown; notifyAllows?: unknown; classifierFallbackModel?: unknown; classifierFallbackConfidence?: unknown; classifierMinConfidence?: unknown; classifierFallbackMode?: unknown; codemodeNestedCalls?: unknown };
 		try {
 			raw = JSON.parse(fs.readFileSync(p, "utf8")) as typeof raw;
 		} catch (err) {
@@ -416,6 +424,9 @@ function loadUserRules(): { rules: UserRules; skipped: string[]; shortcutWarning
 		if (minConfRaw !== undefined && minConfRaw !== null && !minConfOk) skipped.push(`classifierMinConfidence: ${JSON.stringify(minConfRaw)}`);
 		const fbModeRaw = raw.classifierFallbackMode;
 		if (fbModeRaw !== undefined && fbModeRaw !== "shadow" && fbModeRaw !== "enforce") skipped.push(`classifierFallbackMode: ${JSON.stringify(fbModeRaw)}`);
+		// #90: nested-call policy — invalid values skip into the one-shot warning channel
+		const nestedRaw = raw.codemodeNestedCalls;
+		if (nestedRaw !== undefined && nestedRaw !== "gate" && nestedRaw !== "rules-only") skipped.push(`codemodeNestedCalls: ${JSON.stringify(nestedRaw)}`);
 		return {
 			rules: {
 				allow: compile(raw.allow),
@@ -430,6 +441,7 @@ function loadUserRules(): { rules: UserRules; skipped: string[]; shortcutWarning
 				classifierFallbackModel: typeof raw.classifierFallbackModel === "string" && raw.classifierFallbackModel.trim() ? raw.classifierFallbackModel.trim() : null,
 				classifierMinConfidence: minConfOk ? minConfRaw : null,
 				classifierFallbackMode: fbModeRaw === undefined ? "enforce" : fbModeRaw === "enforce" ? "enforce" : "shadow", // invalid values land on the conservative shadow (standing invalid-config precedent); the key-less default is enforce
+				codemodeNestedCalls: nestedRaw === "rules-only" ? "rules-only" : "gate", // invalid values keep the safe default (gate)
 			},
 			skipped,
 			shortcutWarning: shortcut.warning,
@@ -1741,14 +1753,23 @@ export interface AuditRecord {
 	verdict: "allow" | "ask" | "deny";
 	reason: string;
 	/** #62: protected-path asks are recorded too — their user answers grade the
-	 *  denyPaths rules; rule allow/deny verdicts remain unaudited. */
-	source: "model" | "fail-closed" | "protected-path";
+	 *  denyPaths rules; rule allow/deny verdicts remain unaudited. "rule" exists for
+	 *  one audited rule-layer outcome: the rules-only nested passthrough (#90). */
+	source: "model" | "fail-closed" | "protected-path" | "rule";
 	degraded: boolean;
 	/** #62 ground truth: the user's answer to an interactive ask confirm. Present only
 	 *  on records whose confirm actually ran; headless/degraded asks omit it. */
 	userAnswer?: "allowed" | "declined";
 	/** #62: ISO timestamp of the confirm resolution; `ts` stays adjudication time. */
 	answeredAt?: string;
+	/** #90: the call's id — `<parent id>/<n>` for nested calls (codemode scripts).
+ *  Direct-call records carry it too; pre-0.14 corpora simply lack the field. */
+	toolCallId?: string;
+	/** #90: set iff another tool (a codemode script) issued this call — the audit
+	 *  attribution that makes nested calls distinguishable from direct ones. */
+	parentToolCallId?: string;
+	/** #90: the nested-call policy in effect for a rules-only passthrough record. */
+	policy?: "rules-only";
 	/** #62: protected-path records only — the matched path. */
 	detail?: string;
 	/** #67: the confidence floor fired — the first-layer verdict was demoted. */
@@ -1991,7 +2012,7 @@ async function runConfidenceCascade(
  */
 export async function adjudicate(
 	state: SessionState,
-	call: { toolName: string; input: Record<string, unknown> },
+	call: { toolName: string; input: Record<string, unknown>; toolCallId?: string; parentToolCallId?: string },
 	env: AdjudicateEnv,
 ): Promise<Verdict> {
 	const rule = classifyByRules(call.toolName, call.input, env.cwd, state.userRules, state.prot, state.anchoredDenyPathBases(env.cwd));
@@ -2016,6 +2037,10 @@ export async function adjudicate(
 		thinking: raw?.thinking ?? null,
 		transcript: raw?.transcript ?? null,
 		rawResponse: raw?.rawResponse ?? null,
+		// #90 audit attribution: ids ride on every record; nested records additionally
+		// carry the parent linkage, making them distinguishable from direct calls
+		...(call.toolCallId !== undefined ? { toolCallId: call.toolCallId } : {}),
+		...(call.parentToolCallId !== undefined ? { parentToolCallId: call.parentToolCallId } : {}),
 		...v,
 	});
 
@@ -2030,6 +2055,17 @@ export async function adjudicate(
 		return { verdict: "deny", reason: rule.reason ?? "", detail: rule.detail, source: "protected-path", degraded: true };
 	}
 
+	// ADR-0006 (#90): the layered-exemption policy. Nested calls under rules-only have
+	// already passed every deterministic layer above (self-protection, floor, user
+	// rules, denyPaths + its ask) — only the intelligence layer is skipped: the gray
+	// zone passes. Audited when audit is on (source rule + policy marker): the user
+	// needs corpus data on what the opt-in actually let through.
+	if (call.parentToolCallId !== undefined && state.userRules.codemodeNestedCalls === "rules-only") {
+		const reason = "codemodeNestedCalls rules-only: gray-zone passthrough (nested call — deterministic layers only)";
+		state.audit?.append({ ...buildRecord({ verdict: "allow", reason, source: "rule", degraded: false }, null), policy: "rules-only" });
+		return { verdict: "allow", reason, source: "rule", degraded: false };
+	}
+
 	// 灰区 → 分类器;无可用模型 → fail-closed
 
 	const resolved = env.getModel();
@@ -2219,6 +2255,8 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 	const toggleHint = () => (registeredToggleKey ? ` · toggle: ${registeredToggleKey}` : "");
 	/** Status line denyPaths count (ADR-0002): shown only when configured */
 	const denyPathsHint = () => (state.userRules.denyPaths.length > 0 ? `\ndenyPaths: ${state.userRules.denyPaths.length} active` : "");
+	/** #90: nested-call policy hint — shown only when the exemption is active */
+	const nestedPolicyHint = () => (state.userRules.codemodeNestedCalls === "rules-only" ? "\nnested calls: rules-only (deterministic layers only — the gray zone passes)" : "");
 	/** Status line audit hint (#54): shown only while the sink is active */
 	const auditHint = () => (state.audit ? `\naudit: on → ${state.audit.dir}` : "");
 	/** Status line cascade hint (#63/#67): shown while the floor or the fallback is configured */
@@ -2236,7 +2274,7 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 			const arg = args.trim().toLowerCase();
 			// 裸调用:只读状态展示,无副作用
 			if (arg === "") {
-				ctx.ui.notify(`${enabled ? "🛡️ Auto Mode: on" : "Auto Mode: off"}\n${denyPathsHint()}${auditHint()}${fallbackHint()}\nUsage: /automode on|off${toggleHint()}`, "info");
+				ctx.ui.notify(`${enabled ? "🛡️ Auto Mode: on" : "Auto Mode: off"}\n${denyPathsHint()}${nestedPolicyHint()}${auditHint()}${fallbackHint()}\nUsage: /automode on|off${toggleHint()}`, "info");
 			return;
 			}
 			// 幂等设定:与现值相同不翻转,仅确认
@@ -2451,7 +2489,7 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 		}
 
 		// 判定管线(零 UI)→ 呈现(source 模板)
-		const verdict = await adjudicate(state, { toolName: event.toolName, input }, {
+		const verdict = await adjudicate(state, { toolName: event.toolName, input, toolCallId: event.toolCallId, parentToolCallId: event.parentToolCallId }, {
 			cwd: ctx.cwd,
 			hasUI: !!ctx.hasUI,
 			getModel: () => resolveClassifier(ctx),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-verdict",
-	"version": "0.13.1",
+	"version": "0.14.0",
 	"description": "A minimal permission gate for Pi, inspired by Claude Code's auto mode",
 	"author": "Jesset (https://github.com/jesset)",
 	"type": "module",
@@ -55,7 +55,7 @@
 		}
 	},
 	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "0.99.2",
+		"@earendil-works/pi-coding-agent": "1.0.0",
 		"@types/node": "^26.3.0",
 		"typescript": "^7.0.2"
 	}