pi-verdict 0.8.0 → 0.9.0

package/README.md

@@ -99,7 +99,9 @@ pi-verdict runs on both [pi](https://github.com/badlogic/pi-mono) and [oh-my-pi]
   ],
   "builtinDenyFloor": true,
   "classifierModel": null,
-  "toggleShortcut": "ctrl+shift+a"
+  "toggleShortcut": "ctrl+shift+a",
+  "audit": false,
+  "notifyAllows": false
 }
 ```
 
@@ -108,6 +110,8 @@ pi-verdict runs on both [pi](https://github.com/badlogic/pi-mono) and [oh-my-pi]
 - `builtinDenyFloor: false` turns off the built-in danger/path floor (your risk; the self-protection layer below always stays on)
 - `classifierModel` pins the classifier model, e.g. `"zai/glm-5.3-flash:low"` (thinking suffix supported; default: session model with thinking off)
 - `classifierModel: "typesafe/jev-latest"` opts into the bundled **jev decisions adapter** — gray-zone verdicts via TypeSafe's jev on OpenRouter (`/api/alpha/decisions`), reusing your pi OpenRouter login; experimental, see [ADR-0003](docs/adr/0003-jev-decisions-adapter.md)
+- `audit: true` records every **gray-zone adjudication** (the full transcript sent to the classifier, its raw response, the parsed verdict) as JSONL under `~/.pi/agent/verdicts/<sessionId>.jsonl` — one file per session, the 20 most recent kept. Local-only and full-fidelity (protected-path plaintext may appear — it never leaves your machine; [ADR-0002](docs/adr/0002-deny-paths-deterministic-ask.md) boundary note); the agent can neither read nor write the directory. `/automode` shows the audit state and path while on
+- `notifyAllows: true` notifies on every **classifier allow** (reason + action line — e.g. jev's probability breakdown); default `false` keeps passes silent. Mechanical passes (your own allow rules, protected-path confirms) never notify; shadow-cache annotations stay debug-only; with both switches on the notification appears once
 
 No built-in allowlist — every "always allow" claim is yours ([why](docs/configuration.md#why-no-built-in-allowlist)). Full reference: [docs/configuration.md](docs/configuration.md).
 

package/README.zh-CN.md

@@ -101,7 +101,9 @@ pi-verdict 同时支持 [pi](https://github.com/badlogic/pi-mono) 与 [oh-my-pi]
   ],
   "builtinDenyFloor": true,
   "classifierModel": null,
-  "toggleShortcut": "ctrl+shift+a"
+  "toggleShortcut": "ctrl+shift+a",
+  "audit": false,
+  "notifyAllows": false
 }
 ```
 
@@ -110,6 +112,8 @@ pi-verdict 同时支持 [pi](https://github.com/badlogic/pi-mono) 与 [oh-my-pi]
 - `builtinDenyFloor: false` 整体关闭内置危险/路径拦截(风险自担;下方自保护层永远开启)
 - `classifierModel` 指定分类器模型,如 `"zai/glm-5.3-flash:low"`(支持思考后缀;缺省 = 会话模型且显式关思考)
 - `classifierModel: "typesafe/jev-latest"` 启用随包的 **jev 决策适配器**——灰区裁决经 OpenRouter 的 TypeSafe jev(`/api/alpha/decisions`)完成,复用 pi 的 OpenRouter 登录态;实验性质,详见 [ADR-0003](docs/adr/0003-jev-decisions-adapter.md)
+- `audit: true` 把每次**灰区裁决**(发给分类器的完整转录、其原始响应、解析出的裁决)以 JSONL 记录到 `~/.pi/agent/verdicts/<sessionId>.jsonl`——按会话一分文件,保留最近 20 个。仅存本机且全保真(受保护路径明文可能出现——永不出本机;[ADR-0002](docs/adr/0002-deny-paths-deterministic-ask.md) 边界注);agent 对该目录读写双拒。开启时 `/automode` 会显示审计状态与路径
+- `notifyAllows: true` 对每次 **classifier 放行**发通知(reason + action 行——如 jev 的概率分解);默认 `false` 保持放行静默。机械放行(你自己的 allow 规则、protected-path 确认)永不通知;shadow 标注仍属 debug;两开关同开时通知只出现一次
 
 没有内置白名单——每一条「永远放行」声明都归你([为什么](docs/configuration.md#why-no-built-in-allowlist))。完整参考:[docs/configuration.md](docs/configuration.md)。
 

package/extensions/pi-verdict.ts

@@ -259,9 +259,13 @@ interface UserRules {
 	classifierModel: string | null;
 	/** 主开关 toggle 快捷键键位(#15);null = 禁用;缺省 DEFAULT_TOGGLE_SHORTCUT */
 	toggleShortcut: string | null;
+	/** Opt-in gray-zone adjudication audit (#54): per-session JSONL under <agentDir>/verdicts/ */
+	audit: boolean;
+	/** Allow visibility (#60): info notification on classifier allows; mechanical passes stay silent. Default off. */
+	notifyAllows: boolean;
 }
 
-const EMPTY_RULES: UserRules = { allow: [], deny: [], denyPaths: [], builtinDenyFloor: true, classifierModel: null, toggleShortcut: DEFAULT_TOGGLE_SHORTCUT };
+const EMPTY_RULES: UserRules = { allow: [], deny: [], denyPaths: [], builtinDenyFloor: true, classifierModel: null, toggleShortcut: DEFAULT_TOGGLE_SHORTCUT, audit: false, notifyAllows: false };
 
 /** This module's own file location (import.meta.url resolved; null = unresolvable). */
 const OWN_FILE_PATH: string | null = (() => {
@@ -324,6 +328,8 @@ const USER_CONFIG_TEMPLATE = `${JSON.stringify({
 	builtinDenyFloor: true,
 	classifierModel: null,
 	toggleShortcut: DEFAULT_TOGGLE_SHORTCUT,
+	audit: false,
+	notifyAllows: false,
 }, null, 2)}\n`;
 
 /**
@@ -341,7 +347,7 @@ function loadUserRules(): { rules: UserRules; skipped: string[]; shortcutWarning
 			} catch { /* 只读环境静默跳过 */ }
 			return { rules: EMPTY_RULES, skipped: [], shortcutWarning: null };
 		}
-		let raw: { allow?: unknown; deny?: unknown; denyPaths?: unknown; builtinDenyFloor?: unknown; classifierModel?: unknown; toggleShortcut?: unknown };
+		let raw: { allow?: unknown; deny?: unknown; denyPaths?: unknown; builtinDenyFloor?: unknown; classifierModel?: unknown; toggleShortcut?: unknown; audit?: unknown; notifyAllows?: unknown };
 		try {
 			raw = JSON.parse(fs.readFileSync(p, "utf8")) as typeof raw;
 		} catch (err) {
@@ -378,6 +384,8 @@ function loadUserRules(): { rules: UserRules; skipped: string[]; shortcutWarning
 				builtinDenyFloor: raw.builtinDenyFloor !== false,
 				classifierModel: typeof raw.classifierModel === "string" && raw.classifierModel.trim() ? raw.classifierModel.trim() : null,
 				toggleShortcut: shortcut.key,
+				audit: raw.audit === true,
+				notifyAllows: raw.notifyAllows === true,
 			},
 			skipped,
 			shortcutWarning: shortcut.warning,
@@ -577,6 +585,8 @@ interface ProtectedSet {
 	exact: string[];
 	/** 受保护目录前缀(npm 包安装形态:整个包目录) */
 	prefixes: string[];
+	/** 读拒绝前缀(#54):verdicts 审计目录——记录含不可信原始输出,禁回流 agent context */
+	readPrefixes: string[];
 	/** bash/powershell 命令串危险特征(子串匹配,可绕——变更检测兜底) */
 	bashPatterns: RegExp[];
 	/** 变更检测基线(词法路径 + 类别;session_start 时快照全文) */
@@ -713,7 +723,28 @@ export function buildProtectedSet(agentDir: string, ownFile: string | null): Pro
 		bashPatterns.push(new RegExp(`(?:${[...alts].join("|")})`));
 	}
 
-	return { exact: [...exact], prefixes: [...prefixes], bashPatterns, watchBases };
+	// #54 verdicts dir: gate-owned audit storage. Writes ride the normal prefixes;
+	// reads are denied separately — records carry raw model output (including
+	// fail-closed failures) that must not flow back into agent context. Deliberately
+	// NOT added to watchBases: the log legitimately grows every adjudication, so a
+	// snapshot diff would false-positive as tampering.
+	const verdictsForms = baseForms(path.join(agentDir, "verdicts"));
+	for (const f of verdictsForms) prefixes.add(f);
+	const home = os.homedir();
+	const vAlts = new Set<string>(verdictsForms.map(escapeRegExp));
+	for (const f of verdictsForms) {
+		if (f.startsWith(home + path.sep)) {
+			const rel = f.slice(home.length + 1);
+			vAlts.add(escapeRegExp("~/" + rel));
+			vAlts.add("\\$HOME/" + escapeRegExp(rel));
+		}
+		for (const base of baseForms(agentDir)) {
+			if (f.startsWith(base + path.sep)) vAlts.add("\\$PI_CODING_AGENT_DIR/" + escapeRegExp(f.slice(base.length + 1)));
+		}
+	}
+	bashPatterns.push(new RegExp(`(?:${[...vAlts].join("|")})`));
+
+	return { exact: [...exact], prefixes: [...prefixes], readPrefixes: verdictsForms, bashPatterns, watchBases };
 }
 
 /** Does the resolved write path hit the protected set (realpath guards against
@@ -730,6 +761,20 @@ export function isProtectedWritePath(rawPath: string, cwd: string, prot: Protect
 	return false;
 }
 
+/** Read-deny for the verdicts dir (#54): audit records contain raw fail-closed
+ *  model output — untrusted text that must not flow back into agent context.
+ *  Unlike write protection (prefixes) this is read semantics, hence a separate set. */
+export function isProtectedReadPath(rawPath: string | undefined, cwd: string, prot: ProtectedSet): boolean {
+	if (prot.readPrefixes.length === 0) return false;
+	const target = rawPath ?? cwd; // #48: absent path → cwd is the effective target
+	for (const c of rebuiltForms(path.resolve(cwd, expandHome(target)))) {
+		for (const p of prot.readPrefixes) {
+			if (c === p || c.startsWith(p + path.sep)) return true;
+		}
+	}
+	return false;
+}
+
 /** 自保护层裁决(第 0 层,先于一切):触碰门禁自身文件 → 不可豁免的 deny;其余 null 交后续层 */
 function selfProtectCheck(toolName: string, input: Record<string, unknown>, cwd: string, prot: ProtectedSet): RuleResult | null {
 	switch (toolName) {
@@ -739,6 +784,14 @@ function selfProtectCheck(toolName: string, input: Record<string, unknown>, cwd:
 				return { verdict: "deny", reason: `self-protection layer (ADR-0001): ${input.path} is part of the permission gate itself; agent-side modification is denied — edit it manually outside pi if intended` };
 			}
 			return null;
+		case "read":
+		case "grep":
+		case "find":
+		case "ls":
+			if (isProtectedReadPath(typeof input.path === "string" ? input.path : undefined, cwd, prot)) {
+				return { verdict: "deny", reason: `self-protection layer (#54): ${typeof input.path === "string" ? input.path : cwd} holds the gate's verdict audit records — agent reads are denied (untrusted raw model output inside); view them outside pi` };
+			}
+			return null;
 		case "bash":
 		case "powershell": {
 			const cmd = String(input.command ?? "");
@@ -994,6 +1047,8 @@ interface ClassifierOutcome {
 	verdict: "allow" | "ask" | "deny";
 	reason: string;
 	source: "model" | "fail-closed";
+	/** #54 audit material: the transcript actually sent and the last attempt's raw output (attached on both model and fail-closed outcomes) */
+	auditRaw?: { transcript: string; rawResponse: string; modelId: string; thinking: ThinkingLevel };
 }
 
 const CLASSIFIER_TIMEOUT_MS = 25_000; // 本网关 CC 分类器分布 p90=19.8s(15s 会误杀 ~15%),research/cache-sim 数据
@@ -1003,6 +1058,22 @@ const APIS_WITHOUT_TEMPERATURE = new Set<string>([
 	"openai-codex-responses",
 ]);
 
+// Models whose provider rejected a temperature-bearing request ("`temperature`
+// is deprecated for this model" — current-gen Anthropic models, #47). Filled
+// adaptively and cached for the extension's lifetime: pi's model registry has
+// no sampling-capability metadata and the reject/accept split follows neither
+// `api` nor `reasoning`, so the provider's own error is the only reliable
+// signal. Later calls for a cached model omit the parameter upfront.
+const TEMPERATURE_REJECTED_MODELS = new Set<string>();
+
+/** The provider rejected the request over the `temperature` parameter itself (#47). */
+function temperatureRejection(
+	r: { ok: true; stopReason: string; errorMessage?: string } | { ok: false; error: string },
+): boolean {
+	if (r.ok) return (r.stopReason === "error" || r.stopReason === "aborted") && /temperature/i.test(r.errorMessage ?? "");
+	return /temperature/i.test(r.error);
+}
+
 /**
  * Minimal structural shape of a completion call (#35). pi exposes it as
  * ModelRegistry.complete; omp 18 does not, but the pi-ai compat module exports
@@ -1056,7 +1127,13 @@ function completionFor(registry: { complete?: unknown }, compatLoader?: CompatLo
 /** 分类器思考级别(pi 原生词表;后缀语法对齐 pi --model provider/id:thinking) */
 type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
-/** 单次分类器调用:显式 reasoning:"off"(见下方注释),失败返回错误串而非抛出 */
+/**
+ * Single classifier attempt: reasoning "off" by default (see options below);
+ * failures return an error string instead of throwing. A provider rejection
+ * over `temperature` strips the parameter and retries once at the same tier
+ * (#47) — models that accept it keep the temperature 0 determinism pin,
+ * models that deprecate it self-heal instead of fail-closing every call.
+ */
 async function callClassifierOnce(
 	host: PipelineHost,
 	signal: AbortSignal | undefined,
@@ -1067,50 +1144,62 @@ async function callClassifierOnce(
 	thinking: ThinkingLevel = "off",
 	systemPrompt: string = CLASSIFIER_SYSTEM,
 ): Promise<{ ok: true; text: string; stopReason: string; errorMessage?: string } | { ok: false; error: string }> {
-	const signals = [AbortSignal.timeout(CLASSIFIER_TIMEOUT_MS)];
-	if (signal) signals.push(signal);
-	try {
-		const response = await complete(
-			model,
-			{
-				systemPrompt,
-				messages: [{ role: "user", content: userMessage, timestamp: Date.now() }],
-			},
-			{
-				signal: AbortSignal.any(signals),
-				maxTokens,
-				...(APIS_WITHOUT_TEMPERATURE.has(model.api) ? {} : { temperature: 0 }),
-				// Thinking params go out in both hosts' native dialects (#35):
-				// pi's registry.complete consumes thinkingEnabled/effort (the
-				// API-native fields, per the blackhole findings in
-				// research/thinking-param-blackhole.md); omp's compat complete
-				// consumes reasoning/disableReasoning. Both sides ignore unknown
-				// option fields, so dual-send lets each host pick its own.
-				// pi off = explicitly disabled (verified to send
-				// thinking:{"type":"disabled"}; GLM downgrades to effort-low light
-				// thinking); suffix levels arrive via adaptive effort (minimal→low).
-				// omp off = disableReasoning (without it, an absent `reasoning`
-				// leaves the model default undefined); level vocabularies share the
-				// ThinkingLevel word list, reasoning passes through as-is.
-				...(thinking === "off"
-					? { thinkingEnabled: false, disableReasoning: true }
-					: {
-							thinkingEnabled: true,
-							effort: thinking === "minimal" ? ("low" as const) : thinking,
-							reasoning: thinking === "minimal" ? ("low" as const) : thinking,
-						}),
-				cacheRetention: "short",
-				sessionId: host.getSessionId(),
-			},
-		);
-		const text = response.content
-			.filter((b) => b.type === "text")
-			.map((b) => b.text)
-			.join("");
-		return { ok: true, text, stopReason: response.stopReason ?? "unknown", errorMessage: response.errorMessage };
-	} catch (err) {
-		return { ok: false, error: err instanceof Error ? err.message : String(err) };
+	const fire = async (
+		withTemperature: boolean,
+	): Promise<{ ok: true; text: string; stopReason: string; errorMessage?: string } | { ok: false; error: string }> => {
+		const signals = [AbortSignal.timeout(CLASSIFIER_TIMEOUT_MS)];
+		if (signal) signals.push(signal);
+		try {
+			const response = await complete(
+				model,
+				{
+					systemPrompt,
+					messages: [{ role: "user", content: userMessage, timestamp: Date.now() }],
+				},
+				{
+					signal: AbortSignal.any(signals),
+					maxTokens,
+					...(withTemperature ? { temperature: 0 } : {}),
+					// Thinking params go out in both hosts' native dialects (#35):
+					// pi's registry.complete consumes thinkingEnabled/effort (the
+					// API-native fields, per the blackhole findings in
+					// research/thinking-param-blackhole.md); omp's compat complete
+					// consumes reasoning/disableReasoning. Both sides ignore unknown
+					// option fields, so dual-send lets each host pick its own.
+					// pi off = explicitly disabled (verified to send
+					// thinking:{"type":"disabled"}; GLM downgrades to effort-low light
+					// thinking); suffix levels arrive via adaptive effort (minimal→low).
+					// omp off = disableReasoning (without it, an absent `reasoning`
+					// leaves the model default undefined); level vocabularies share the
+					// ThinkingLevel word list, reasoning passes through as-is.
+					...(thinking === "off"
+						? { thinkingEnabled: false, disableReasoning: true }
+						: {
+								thinkingEnabled: true,
+								effort: thinking === "minimal" ? ("low" as const) : thinking,
+								reasoning: thinking === "minimal" ? ("low" as const) : thinking,
+							}),
+					cacheRetention: "short",
+					sessionId: host.getSessionId(),
+				},
+			);
+			const text = response.content
+				.filter((b) => b.type === "text")
+				.map((b) => b.text)
+				.join("");
+			return { ok: true, text, stopReason: response.stopReason ?? "unknown", errorMessage: response.errorMessage };
+		} catch (err) {
+			return { ok: false, error: err instanceof Error ? err.message : String(err) };
+		}
+	};
+	const modelKey = `${model.api}|${model.id}`;
+	const withTemperature = !APIS_WITHOUT_TEMPERATURE.has(model.api) && !TEMPERATURE_REJECTED_MODELS.has(modelKey);
+	const first = await fire(withTemperature);
+	if (withTemperature && temperatureRejection(first)) {
+		TEMPERATURE_REJECTED_MODELS.add(modelKey);
+		return fire(false);
 	}
+	return first;
 }
 
 /**
@@ -1133,14 +1222,16 @@ async function classifyWithModel(
 	const systemPrompt = denyPathsActive ? CLASSIFIER_SYSTEM + DENY_PATHS_HINT : CLASSIFIER_SYSTEM;
 	const attempts: Array<[number, number]> = [[1, CLASSIFIER_MAX_TOKENS], [2, CLASSIFIER_RETRY_MAX_TOKENS]];
 	const failures: string[] = [];
+	let rawResponse = ""; // #54: raw output of the last attempt ("" for exception attempts — diagnostics already live in failures)
 	for (const [n, maxTokens] of attempts) {
 		if (signal?.aborted) break; // 用户已取消,不再重试
 		const r = await callClassifierOnce(host, signal, complete, model, userMessage, maxTokens, thinking, systemPrompt);
 		if (r.ok) {
+			rawResponse = r.text;
 			const diag = `stopReason=${r.stopReason}, model=${model.id}, errorMessage=${JSON.stringify(r.errorMessage ?? null)}, raw output=${JSON.stringify(r.text.slice(0, 200))}`;
 			if (r.stopReason !== "error" && r.stopReason !== "aborted") {
 				const parsed = parseVerdict(r.text);
-				if (parsed) return { ...parsed, source: "model" };
+				if (parsed) return { ...parsed, source: "model", auditRaw: { transcript, rawResponse, modelId: model.id, thinking } };
 				failures.push(`attempt ${n} (${maxTokens}t) contract violation: ${diag}`);
 			} else {
 				failures.push(`attempt ${n} (${maxTokens}t) aborted/errored: ${diag}`);
@@ -1149,7 +1240,7 @@ async function classifyWithModel(
 			failures.push(`attempt ${n} (${maxTokens}t) exception: ${r.error}`);
 		}
 	}
-	return { verdict: "deny", reason: `classifier failure (fail-closed): ${failures.join("; ")}`, source: "fail-closed" };
+	return { verdict: "deny", reason: `classifier failure (fail-closed): ${failures.join("; ")}`, source: "fail-closed", auditRaw: { transcript, rawResponse, modelId: model.id, thinking } };
 }
 
 // ============================================================================
@@ -1271,6 +1362,90 @@ function shadowTag(probe: ShadowProbe): string {
 	return `(shadow cache: miss:no-entry)`;
 }
 
+// ============================================================================
+// Gray-zone verdict audit (#54): opt-in JSONL decision records, observe-only
+// (never an adjudication input)
+// ============================================================================
+
+const AUDIT_KEEP_SESSIONS = 20;
+
+/** One gray-zone adjudication record (#54). Full fidelity on purpose: the file is
+ *  local-trust-domain (same as pi-verdict.json, per the ADR-0002 boundary note),
+ *  so protected-path plaintext is allowed here — it never leaves the machine nor
+ *  flows into agent context. */
+export interface AuditRecord {
+	ts: string;
+	sessionId: string;
+	cwd: string;
+	model: string | null;
+	tool: string;
+	input: unknown;
+	actionLine: string;
+	thinking: string | null;
+	transcript: string | null;
+	rawResponse: string | null;
+	verdict: "allow" | "ask" | "deny";
+	reason: string;
+	source: "model" | "fail-closed";
+	shadow: string;
+	degraded: boolean;
+}
+
+/** Audit sink (#54): append-only and fail-soft (the first write failure surfaces
+ *  once via drainWarning; verdicts are never affected). The dir is created
+ *  lazily — audit on with no gray-zone call all session leaves zero filesystem trace. */
+export class AuditLog {
+	private warning: string | null = null;
+	private warned = false;
+	constructor(readonly dir: string) {}
+
+	append(record: AuditRecord): void {
+		// sessionId comes from the host with no shape guarantee: narrow to a safe filename charset
+		const file = path.join(this.dir, `${record.sessionId.replace(/[^a-zA-Z0-9_-]/g, "_")}.jsonl`);
+		try {
+			fs.mkdirSync(this.dir, { recursive: true });
+			fs.appendFileSync(file, JSON.stringify(record) + "\n");
+		} catch (err) {
+			if (!this.warned) {
+				this.warned = true;
+				this.warning = `audit log write failed (${err instanceof Error ? err.message : String(err)}) — verdict records are NOT being persisted to ${this.dir}; adjudication is unaffected`;
+			}
+		}
+	}
+
+	/** One-shot drain: the extension handler polls after every tool_call; first failure warns, the rest stay silent */
+	drainWarning(): string | null {
+		const w = this.warning;
+		this.warning = null;
+		return w;
+	}
+
+	/** Keep the most recent AUDIT_KEEP_SESSIONS session files (called at session_start, best-effort) */
+	prune(): void {
+		let files: string[];
+		try {
+			files = fs.readdirSync(this.dir).filter((f) => f.endsWith(".jsonl"));
+		} catch {
+			return;
+		}
+		if (files.length <= AUDIT_KEEP_SESSIONS) return;
+		const byMtime = files
+			.map((f) => {
+				let m = 0;
+				try {
+					m = fs.statSync(path.join(this.dir, f)).mtimeMs;
+				} catch {}
+				return { f, m };
+			})
+			.sort((a, b) => b.m - a.m);
+		for (const { f } of byMtime.slice(AUDIT_KEEP_SESSIONS)) {
+			try {
+				fs.unlinkSync(path.join(this.dir, f));
+			} catch {}
+		}
+	}
+}
+
 // ============================================================================
 // 会话态:判定管线的会话期状态(复位清单集中一处)
 // ============================================================================
@@ -1284,11 +1459,20 @@ export class SessionState {
 	readonly prot: ProtectedSet;
 	readonly shadow = new ShadowCache();
 	userRules: UserRules;
+	audit: AuditLog | null;
 	private denyPathBases: string[] | null = null;
+	private readonly agentDir: string | null;
 
-	constructor(prot: ProtectedSet, userRules: UserRules = loadUserRules().rules) {
+	constructor(prot: ProtectedSet, userRules: UserRules = loadUserRules().rules, agentDir: string | null = null) {
 		this.prot = prot;
 		this.userRules = userRules;
+		this.agentDir = agentDir;
+		this.audit = this.makeAudit(userRules);
+	}
+
+	/** #54: the audit flag follows the rules (applies to new sessions); the dir is anchored to the install path */
+	private makeAudit(rules: UserRules): AuditLog | null {
+		return rules.audit && this.agentDir ? new AuditLog(path.join(this.agentDir, "verdicts")) : null;
 	}
 
 	/** 会话重置:重载用户规则(配置改动新会话生效)+ 按会话 cwd 重锚 denyPaths
@@ -1298,6 +1482,7 @@ export class SessionState {
 		this.userRules = loaded.rules;
 		this.denyPathBases = anchorDenyPaths(loaded.rules.denyPaths, cwd); // anchored to the session cwd, once (ADR-0002)
 		this.shadow.reset();
+		this.audit = this.makeAudit(loaded.rules);
 		return { skipped: loaded.skipped, shortcutWarning: loaded.shortcutWarning };
 	}
 
@@ -1362,15 +1547,41 @@ export async function adjudicate(
 	}
 
 	// 灰区 → 分类器;无可用模型 → fail-closed
+	// #54: gray-zone only (rule-layer verdicts carry no transcript corpus —
+	// brief decision); observe-only — recording never changes a verdict, and
+	// write failures are swallowed fail-soft by the sink and surfaced once via drainWarning
+	const actionLine = toolCallLine(call.toolName, call.input);
+	const audit = (v: Pick<AuditRecord, "verdict" | "reason" | "source" | "degraded">, raw: ClassifierOutcome["auditRaw"] | null, shadow: string): void => {
+		if (!state.audit) return;
+		state.audit.append({
+			ts: new Date().toISOString(),
+			sessionId: env.host.getSessionId(),
+			cwd: env.cwd,
+			model: raw?.modelId ?? null,
+			tool: call.toolName,
+			input: call.input,
+			actionLine,
+			thinking: raw?.thinking ?? null,
+			transcript: raw?.transcript ?? null,
+			rawResponse: raw?.rawResponse ?? null,
+			shadow,
+			...v,
+		});
+	};
+
 	const resolved = env.getModel();
-	if (!resolved) return { verdict: "deny", reason: "no classifier model available (fail-closed)", source: "fail-closed", degraded: false };
+	if (!resolved) {
+		const reason = "no classifier model available (fail-closed)";
+		audit({ verdict: "deny", reason, source: "fail-closed", degraded: false }, null, "-");
+		return { verdict: "deny", reason, source: "fail-closed", degraded: false };
+	}
 
 	// 影子缓存(observe-only):前置查询 would-be 命中,不改变任何裁决
 	const cmdKey = shadowCommandKey(call.toolName, call.input, env.cwd);
 	const ctxKey = shadowContextKey(env.host);
 	const probe = state.shadow.probe(cmdKey, ctxKey);
 
-	const outcome = await classifyWithModel(env.host, env.signal, env.complete, resolved.model, toolCallLine(call.toolName, call.input), resolved.thinking, state.userRules.denyPaths.length > 0);
+	const outcome = await classifyWithModel(env.host, env.signal, env.complete, resolved.model, actionLine, resolved.thinking, state.userRules.denyPaths.length > 0);
 
 	// 影子回记:真实模型 allow/deny 入缓存;ask 与 fail-closed 不入(#5 定案);
 	// 命中且本次为可缓存裁决时,对比反事实一致性
@@ -1380,6 +1591,8 @@ export async function adjudicate(
 	}
 
 	const shadow = shadowTag(probe);
+	const askDegraded = !env.hasUI && outcome.verdict === "ask";
+	audit({ verdict: askDegraded ? "deny" : outcome.verdict, reason: outcome.reason, source: outcome.source, degraded: askDegraded }, outcome.auditRaw ?? null, shadow);
 	if (outcome.verdict === "allow") return { verdict: "allow", reason: outcome.reason, source: "classifier", degraded: false, shadow };
 	if (outcome.verdict === "deny") return { verdict: "deny", reason: outcome.reason, source: "classifier", degraded: false, shadow };
 	// ask:无 UI 降级为 deny(ask 降级,CONTEXT.md 词条)
@@ -1390,6 +1603,14 @@ export async function adjudicate(
 // 扩展主体
 // ============================================================================
 
+/** Agent-facing block reason (#53): the text must be self-sufficient — structural
+ * error signaling does not reach several provider lanes, and verbatim rule/classifier
+ * reasons can be empty or too terse for the acting model to recognize as a block. */
+function blockedReason(tag: string, detail: string): string {
+	const clean = detail.trim().replace(/\.+$/, "");
+	return `[auto-mode ${tag} block] BLOCKED — this action did NOT run. Reason: ${clean || "(no further reason given)"}. Report the block to the user; never claim it succeeded or completed.`;
+}
+
 /** Optional dependency injection for tests (#35): fake the compat fallback loader. */
 export interface AutoModeDeps {
 	compatLoader?: CompatLoader;
@@ -1403,14 +1624,14 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 	let enabled = pi.getFlag("auto-mode") !== false;
 	const debug = pi.getFlag("auto-mode-debug") === true || process.env.PI_AUTO_MODE_DEBUG === "1";
 	// 会话态与门禁完整性监视:复位清单各归 SessionState.reset / IntegrityWatch.startSession
-	const state = new SessionState(buildProtectedSet(agentDirPath(), OWN_FILE_PATH));
+	const state = new SessionState(buildProtectedSet(agentDirPath(), OWN_FILE_PATH), undefined, agentDirPath());
 	const integrity = new IntegrityWatch(state.prot.watchBases);
 
 	/** 篡改处置呈现:还原 + fail-closed 的本地通知(含文件清单与原因) */
 	function presentTamper(changed: Array<{ file: string; kind: WatchKind }>, ctx: ExtensionContext, cause: string): { block: true; reason: string } {
 		const r = integrity.restoreAndFailClose(changed, cause);
 		ctx.ui.notify(`🛡️ pi-verdict TAMPER DETECTED${cause ? ` (${cause})` : ""}: ${r.files} modified bypassing the gate; restored from session snapshot where possible. Fail-closed for the rest of this session — review the file(s) and restart the session.`, "warning");
-		return { block: true, reason: r.reason };
+		return { block: true, reason: blockedReason("tamper", r.reason) };
 	}
 
 	/** Verdict → UI(本扩展唯一的裁决呈现点):按 source × degraded 查模板,文案与
@@ -1418,10 +1639,16 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 	 *  (ADR-0002 story 11:通知与 block reason 回流 agent context)。 */
 	async function presentVerdict(v: Verdict, action: string, ctx: ExtensionContext): Promise<{ block: true; reason: string } | undefined> {
 		if (v.verdict === "allow") {
+			// #60 (CONTEXT.md 通知): classifier allows surface via notifyAllows OR
+			// debug — exactly one notification either way; the shadow suffix stays
+			// debug-only; mechanical passes (rule echo, protected-path confirm) stay
+			// debug-only — notifications carry judgment, the audit log carries completeness
 			if (debug) {
 				if (v.source === "rule") ctx.ui.notify(`🛡️ allow (rule): ${action}`, "info");
 				else if (v.source === "protected-path") ctx.ui.notify("🛡️ allow (protected-path confirm)", "info");
 				else ctx.ui.notify(`🛡️ allow (classifier): ${v.reason}\n  ${action}${v.shadow ? " " + v.shadow : ""}`, "info");
+			} else if (state.userRules.notifyAllows && v.source === "classifier") {
+				ctx.ui.notify(`🛡️ allow (classifier): ${v.reason}\n  ${action}`, "info");
 			}
 			return undefined;
 		}
@@ -1429,18 +1656,18 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 			if (v.source === "protected-path") {
 				// 无 action 行:action 串可内嵌被触路径,通知不得携带受保护路径明文
 				ctx.ui.notify(`🛡️ Auto Mode blocked (non-interactive, protected-path ask→deny): ${v.reason}`, "warning");
-				return { block: true, reason: `[auto-mode] protected-path ask degraded to block in non-interactive mode: ${v.reason}` };
+				return { block: true, reason: blockedReason("protected-path", `ask degraded to block in non-interactive mode: ${v.reason}`) };
 			}
 			if (v.source === "fail-closed") {
 				ctx.ui.notify(`🛡️ Auto Mode blocked: ${v.reason}\n  ${action}`, "warning");
-				return { block: true, reason: `[auto-mode] ${v.reason}` };
+				return { block: true, reason: blockedReason("fail-closed", v.reason) };
 			}
 			if (v.source === "rule") {
 				ctx.ui.notify(`🛡️ Auto Mode blocked: ${v.reason}\n  ${action}`, "warning");
-				return { block: true, reason: `[auto-mode rule block] ${v.reason}` };
+				return { block: true, reason: blockedReason("rule", v.reason) };
 			}
 			ctx.ui.notify(`🛡️ Auto Mode blocked: ${v.reason}\n  ${action}${debug && v.shadow ? " " + v.shadow : ""}`, "warning");
-			return { block: true, reason: `[auto-mode classifier block] ${v.reason}` };
+			return { block: true, reason: blockedReason("classifier", v.reason) };
 		}
 		// ask → 人工确认;非交互已在管线内降级,能走到这里的必有 UI
 		if (v.source === "protected-path") {
@@ -1450,10 +1677,10 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 				if (debug) ctx.ui.notify("🛡️ allow (protected-path confirm)", "info");
 				return undefined;
 			}
-			return { block: true, reason: "[auto-mode] user declined protected-path access" };
+			return { block: true, reason: blockedReason("user-declined", "user declined protected-path access") };
 		}
 		const ok = await ctx.ui.confirm("🛡️ Auto Mode confirmation", `${action}\n\nClassifier opinion: ${v.reason}\n\nAllow execution?`);
-		return ok ? undefined : { block: true, reason: "[auto-mode] user declined" };
+		return ok ? undefined : { block: true, reason: blockedReason("user-declined", "user declined") };
 	}
 
 	function refreshStatus(ctx: ExtensionContext) {
@@ -1473,6 +1700,7 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 	pi.on("session_start", async (_event, ctx) => {
 		const report = state.reset(ctx.cwd);
 		integrity.startSession();
+		state.audit?.prune(); // #54: converge to the AUDIT_KEEP_SESSIONS most recent files at session start
 		if (report.skipped.length > 0) {
 			ctx.ui.notify(`pi-verdict: skipped ${report.skipped.length} invalid config value(s) in config (${userConfigPath()}): ${report.skipped.join(", ")}`, "warning");
 		}
@@ -1497,6 +1725,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` : "");
+	/** Status line audit hint (#54): shown only while the sink is active */
+	const auditHint = () => (state.audit ? `\naudit: on → ${state.audit.dir}` : "");
 
 	pi.registerCommand("automode", {
 		description: "Show Auto Mode status and shadow-cache stats, or set it: /automode on|off",
@@ -1504,7 +1734,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${state.shadow.summary()}${denyPathsHint()}\nUsage: /automode on|off${toggleHint()}`, "info");
+				ctx.ui.notify(`${enabled ? "🛡️ Auto Mode: on" : "Auto Mode: off"}\n${state.shadow.summary()}${denyPathsHint()}${auditHint()}\nUsage: /automode on|off${toggleHint()}`, "info");
 			return;
 			}
 			// 幂等设定:与现值相同不翻转,仅确认
@@ -1579,7 +1809,7 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 		// 第 0 层前置:变更检测(ADR-0001)——篡改后本会话恒 deny(fail-closed)
 		if (integrity.tampered) {
 			ctx.ui.notify(`🛡️ Auto Mode blocked: self-protection fail-closed (tamper detected this session; restart to reset)\n  ${action}`, "warning");
-			return { block: true, reason: "[auto-mode] self-protection: fail-closed until session restart (protected file was tampered with)" };
+			return { block: true, reason: blockedReason("tamper", "self-protection: fail-closed until session restart (protected file was tampered with)") };
 		}
 		const changed = integrity.detect();
 		if (changed.length > 0) {
@@ -1615,6 +1845,8 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 			host: ctx.sessionManager,
 			signal: ctx.signal,
 		});
+		const auditWarning = state.audit?.drainWarning(); // #54: fail-soft one-shot warning
+		if (auditWarning) ctx.ui.notify(`pi-verdict: ${auditWarning}`, "warning");
 		return presentVerdict(verdict, action, ctx);
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-verdict",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"description": "A minimal permission gate for Pi in the style of Claude Code's auto mode",
 	"author": "Jesset (https://github.com/jesset)",
 	"type": "module",
@@ -24,7 +24,12 @@
 		"security",
 		"tool-call",
 		"classifier",
-		"ai-agent"
+		"ai-agent",
+		"jev",
+		"typesafe",
+		"system-one",
+		"decisions",
+		"openrouter"
 	],
 	"repository": {
 		"type": "git",