pi-verdict 0.6.0 → 0.7.0

package/README.md

@@ -8,7 +8,7 @@
 
 **pi-verdict is a minimal permission gate for [pi](https://pi.dev) in the style of Claude Code's auto mode: every tool call gets checked before it runs — allow, deny, or ask you first.**
 
-- Minimal — just a few hundred lines of code
+- Minimal — just 1k+ lines of code
 - Built-in danger rules and your own allow/deny rules settle the clear cases first, at zero latency
 - Everything else goes to a model classifier that sees the conversation context
 - Any uncertainty or failure fails closed; nothing ever runs silently
@@ -26,19 +26,21 @@ pi-verdict adds the missing gate: a model decides whether each call should run,
 
 ## Design principles
 
-A small set of security principles shapes the whole gate — the full statement, with the honest edges, lives in [docs/security-principles.md](docs/security-principles.md):
-
 - **Fail closed** — uncertainty produces friction, never permission.
 - **Deterministic floor before AI** — hard denies are never overridden by the classifier or user allow rules.
-- **Semantics over syntax** — a long read-only pipeline may auto-allow while a short destructive one still denies; the classifier judges what an action *does*, not how long it is.
+- **Semantics over syntax** — the classifier judges what an action *does*, not how long it is.
 - **Judgments, not proofs** — a classifier `allow` is an informed opinion; the floor exists because that is all it is.
 - **Minimal trusted input** — no tool results in the transcript (#22), zero path plaintext to the classifier (ADR-0002).
 - **Canonical identity** — lexical + realpath dual-form matching; a workspace-*looking* path is not trusted as one (#20/#21).
 - **The gate guards itself** — self-protection that no configuration can disable (ADR-0001).
 - **A permission gate, not a sandbox** — stack OS isolation on top; this gate never replaces it.
 
+Full statement in [docs/security-principles.md](docs/security-principles.md).
+
 ## Screenshots
 
+![Demo: protected-path ask declined](docs/demo.gif)
+
 ![Automode Status](docs/images/status.png)
 ![Ask Permission](docs/images/asked.png)
 
@@ -52,7 +54,7 @@ pi install npm:pi-verdict
 omp plugin install npm:pi-verdict
 
 # or directly from git — try it once
-pi --extension ./extensions/auto-mode.ts
+pi --extension ./extensions/pi-verdict.ts
 
 ```
 
@@ -63,7 +65,7 @@ pi-verdict runs on both [pi](https://github.com/badlogic/pi-mono) and [oh-my-pi]
 | | pi | omp |
 |---|---|---|
 | install | `pi install npm:pi-verdict` | `omp plugin install npm:pi-verdict` |
-| extension copy | `~/.pi/agent/extensions/` | `~/.omp/agent/plugins/node_modules/pi-verdict/` |
+| extension copy | `~/.pi/agent/extensions/` | `~/.omp/plugins/node_modules/pi-verdict/` (omp 18.1+; ≤18.0: under `agent/`) |
 | user rules | `~/.pi/agent/config/pi-verdict.json` | `~/.omp/agent/config/pi-verdict.json` |
 | credential file (S0 hard deny) | `~/.pi/agent/auth.json` | `~/.omp/agent/auth.json` |
 
@@ -121,7 +123,7 @@ Requires pi ≥ 0.84. Works in interactive and non-interactive (`-p`/json/rpc) s
 
 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 self-protection layer that no config can turn off ([ADR-0001](docs/adr/0001-self-protection-layer.md) — gate integrity), a zero-dependency single file ([one readable file](extensions/auto-mode.ts), still one file on purpose), and the measurement habit — every design decision in this repo is backed by shipped research.
+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 self-protection layer that no config can turn off ([ADR-0001](docs/adr/0001-self-protection-layer.md) — gate integrity), a zero-dependency single file ([one readable file](extensions/pi-verdict.ts), still one file on purpose), and the measurement habit — every design decision in this repo is backed by shipped research.
 
 ## Pipeline
 
@@ -176,7 +178,7 @@ Design decisions here are settled by measurement, and the lab notes ship with th
 - parallel gray-zone calls are adjudicated serially
 - self-reflection means the session model adjudicates — point `--auto-mode-model` at a lighter model if verdict latency/cost matters (open question tracked in the issue tracker)
 - shadow cache is observe-only by decision; the serving switch is a one-line change once measured hit rates justify it
-- `denyPaths` bash extraction is token-level ([ADR-0002](docs/adr/0002-deny-paths-deterministic-ask.md)): command substitution, base64-embedded paths and external script contents produce no hit signal — those calls fall back to the classifier's existence-hint vigilance. MCP and custom tools bypass the extractor entirely (their gray-zone adjudication still carries the hint). Honest framing, same as the self-protection substring precedent: the deterministic layer is obfuscatable, which is exactly why a hit routes to *you* rather than silently deciding
+- `denyPaths` bash extraction is token-level ([ADR-0002](docs/adr/0002-deny-paths-deterministic-ask.md)): command substitution, base64-embedded paths and external script contents produce no hit signal — those calls fall back to the classifier's existence-hint vigilance. MCP and custom tools bypass the extractor entirely (their gray-zone adjudication still carries the hint). Path normalization is base-tier only (ADR-0002): a nonexistent target written through a symlinked directory rebuilds no real form and produces no hit — that indirection falls to the hint vigilance too (the ancestor-rebuilding tier applies to the self-protection layer and the sensitivity floor, not denyPaths). Honest framing, same as the self-protection substring precedent: the deterministic layer is obfuscatable, which is exactly why a hit routes to *you* rather than silently deciding
 - `denyPaths` bash tokens contain no spaces: a *declared* path containing spaces cannot be spelled in a bash command in a way the extractor sees — `cat "/path with space/x"` splits into two tokens and never hits (file tools still hit, their path is not tokenized). A glob covering the final segment of a base (`cat /proj/pers*` against `denyPaths: ["/proj/personal"]`) also misses — the base's own name never appears literally. Both holes fall back to the classifier's existence hint, alongside substitution/base64 above
 - self-protection bash matching is substring regex — obfuscatable; the tamper-detection backstop catches within-session bypasses, but a cross-session baseline (hash + change confirmation at startup, incl. upgrade UX) is phase 2 per [ADR-0001](docs/adr/0001-self-protection-layer.md)
 - dev checkouts (running the extension from a repo, not `<agentDir>/extensions/`) are not self-protected — the installed copy the *next* normal session loads is only covered by its own sessions' gate

package/README.zh-CN.md

@@ -8,7 +8,7 @@
 
 **pi-verdict 是 [pi](https://pi.dev) 的 Claude Code 风格的 Auto mode 式的极简权限门禁:每次工具调用执行前先过检查——放行、拦截,或先问你。**
 
-- 只有几百行的极简代码
+- 只有1k行左右的极简代码
 - 内置危险规则与你的 allow/deny 规则以零延迟先行裁决明确情形
 - 其余交给携带会话上下文的模型分类器
 - 任何不确定或失败一律 fail-closed, 绝不静默放行
@@ -22,23 +22,26 @@ pi-verdict 补上这道缺失的门禁, 由模型基于上下文和你的意图
 
 ## 为什么是三态
 
-**verdict 是裁决,不是开关。** 本品类的分类器大多只输出二值 allow/block。三态有意义的地方在:`ask` 把真正含糊的动作转交人类确认(非交互会话中降级为 `deny`),「不确定」永远不会静默变成「放行」——目标是安全的自动化而非最大的自动化:审批疲劳与静默危险执行都是输家。
+**verdict 是裁决,不是开关。** 本品类的分类器大多只输出二值 allow/block。三态有意义的地方在:`ask` 把真正含糊的动作转交人类确认(非交互会话中降级为 `deny`),「不确定」永远不会静默变成「放行」——目标是安全的自动化而非最大的自动化:审批疲劳与静默危险执行都是危险。
 
 ## 设计原则
 
-一小组安全设计原则塑形了整个门禁——完整表述(含诚实的边界说明)见 [docs/security-principles.md](docs/security-principles.md):
-
 - **Fail closed**——不确定产生摩擦,绝不产生许可。
 - **确定性 floor 先于 AI**——硬 deny 永不被分类器或用户 allow 规则覆盖。
-- **语义优先于语法**——长而只读的管道可以自动放行,短而具破坏性的照样拦下;分类器判定的是动作**做什么**,而不是命令有多长。
+- **语义优先于语法**——分类器判定的是动作**做什么可能会产生什么安全影响**,而不是命令有多长。
 - **是判断,不是证明**——分类器的 `allow` 是有依据的判断;floor 的存在正因为它仅此而已。
 - **最小化可信输入**——transcript 不含工具结果(#22),分类器零路径明文(ADR-0002)。
 - **规范化身份**——词法 + realpath 双形匹配;「看起来在项目内」的路径不因此被信任(#20/#21)。
 - **门禁守护自身**——任何配置都关不掉的自保护层(ADR-0001)。
 - **是权限门禁,不是沙箱**——请在上面叠加 OS 级隔离;本门禁不替代它。
 
+完整表述见 [docs/security-principles.md](docs/security-principles.md):
+
+
 ## 截图
 
+![演示:受保护路径 ask 被拒绝](docs/demo.gif)
+
 ![Automode Status](docs/images/status.png)
 ![Ask Permission](docs/images/asked.png)
 
@@ -52,7 +55,7 @@ pi install npm:pi-verdict
 omp plugin install npm:pi-verdict
 
 # 或直接从源码 —— 试用一次
-pi --extension ./extensions/auto-mode.ts
+pi --extension ./extensions/pi-verdict.ts
 
 ```
 
@@ -63,7 +66,7 @@ pi-verdict 同时支持 [pi](https://github.com/badlogic/pi-mono) 与 [oh-my-pi]
 | | pi | omp |
 |---|---|---|
 | 安装 | `pi install npm:pi-verdict` | `omp plugin install npm:pi-verdict` |
-| 扩展副本 | `~/.pi/agent/extensions/` | `~/.omp/agent/plugins/node_modules/pi-verdict/` |
+| 扩展副本 | `~/.pi/agent/extensions/` | `~/.omp/plugins/node_modules/pi-verdict/`(omp 18.1+;≤18.0 在 `agent/` 下) |
 | 用户规则 | `~/.pi/agent/config/pi-verdict.json` | `~/.omp/agent/config/pi-verdict.json` |
 | 凭据文件(S0 硬 deny) | `~/.pi/agent/auth.json` | `~/.omp/agent/auth.json` |
 
@@ -121,7 +124,7 @@ pi-verdict 同时支持 [pi](https://github.com/badlogic/pi-mono) 与 [oh-my-pi]
 
 完整全景:[`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`——用户主权)、任何配置都关不掉的自保护层([ADR-0001](docs/adr/0001-self-protection-layer.md)——门禁完整性)、零依赖的[可通读单文件](extensions/auto-mode.ts)(仍刻意单文件)、以及测量的习惯——本仓库每个设计决策都有随库研究背书。
+诚实地说:pi-automode 与 pi-verdict 在**架构上已收敛**(deny floor → 用户规则 → 分类器,fail-closed——见收敛分析)。这里仍然不同的是:分类器能说 `ask`(运行时人工介入,而非仅由规则预声明)、内置 floor 可以关(`builtinDenyFloor`——用户主权)、任何配置都关不掉的自保护层([ADR-0001](docs/adr/0001-self-protection-layer.md)——门禁完整性)、零依赖的[可通读单文件](extensions/pi-verdict.ts)(仍刻意单文件)、以及测量的习惯——本仓库每个设计决策都有随库研究背书。
 
 ## 管线
 
@@ -176,7 +179,7 @@ tool_call
 - 并行灰区调用串行裁决
 - 自省意味着会话模型亲自裁决 —— 若延迟/成本敏感,用 `--auto-mode-model` 指向轻量模型(开放问题见 issue tracker)
 - 影子缓存按决议仅观察不生效;实测命中率达标后,生效开关是一行改动
-- `denyPaths` 的 bash 提取是 token 级([ADR-0002](docs/adr/0002-deny-paths-deterministic-ask.md)):命令替换、base64 内嵌路径、外部脚本内容不产生命中信号——这些调用回落到分类器的存在性话术警戒。MCP 与自定义工具完全绕过提取器(其灰区裁决仍带话术)。诚实表述,与自保护子串正则同例:确定性层可被混淆——这正是命中交由**你**裁决而非静默决定的原因
+- `denyPaths` 的 bash 提取是 token 级([ADR-0002](docs/adr/0002-deny-paths-deterministic-ask.md)):命令替换、base64 内嵌路径、外部脚本内容不产生命中信号——这些调用回落到分类器的存在性话术警戒。MCP 与自定义工具完全绕过提取器(其灰区裁决仍带话术)。路径归一化亦为基础档(ADR-0002):经符号链接目录写入尚不存在的目标不重建真实形、不产生命中——该间接路径同样由话术警戒覆盖(祖先重建档只适用于自保护层与路径敏感度 floor,不适用 denyPaths)。诚实表述,与自保护子串正则同例:确定性层可被混淆——这正是命中交由**你**裁决而非静默决定的原因
 - `denyPaths` 的 bash token 不含空格:**声明路径本身含空格时**,bash 拼写无法被提取器识别——`cat "/path with space/x"` 被拆成两个 token 永不命中(文件类工具仍命中,其路径不经 token 化)。glob 覆盖基名末段(`denyPaths: ["/proj/personal"]` 时 `cat /proj/pers*`)同样漏过——基名自身从未字面出现。两个洞与上述替换/base64 一样回落到分类器的存在性话术
 - 自保护 bash 匹配是子串正则——可被混淆绕过;变更检测兜底覆盖会话内绕过,跨会话基线(启动时哈希比对与变更确认,含升级 UX)按 ADR-0001 为二期
 - dev checkout(从仓库而非 `<agentDir>/extensions/` 运行扩展)不受自保护——下一个正常会话加载的安装副本只在其自身会话的门禁内受保护

package/extensions/{auto-mode.ts → pi-verdict.ts}

@@ -36,6 +36,12 @@
  *   3. Three-state verdict: allow passes / deny blocks / ask goes to a human
  *      (ctx.ui.confirm)
  *
+ * Structure: the pipeline is adjudicate() — a zero-UI module returning a Verdict
+ * value object (source: rule|protected-path|classifier|fail-closed, plus a
+ * `degraded` flag for ask→deny in non-interactive sessions); the tool_call
+ * handler maps verdicts to UI (notify/confirm/select) by source × degraded and
+ * runs IntegrityWatch (ADR-0001) as a pre-pipeline gate-integrity check.
+ *
  * Shadow cache (observe-only, #7): gray-zone verdicts are replayed against a
  * double-key LRU(128) to measure would-be hit rate; recorded, never applied
  * (verdicts always come from the model), accumulating pi field data for the
@@ -136,6 +142,59 @@ function classifyBash(command: string, floorOn: boolean): RuleResult {
 	return { verdict: "gray", reason: "no built-in allowlist" };
 }
 
+// ============================================================================
+// 规范形:双形匹配两档的唯一实现(纪律见 CONTEXT.md「双形匹配」词条)
+// ============================================================================
+
+/**
+ * 基础档(ADR-0002):词法绝对形 + 整路径 realpath 形(realpath 解析 symlink
+ * 间接;失败——目标不存在、glob token——降级为仅词法形)。denyPaths 与一切
+ * 「基址侧」双形集合(cwd 基址、agentDir、安装根、受保护集合、基线快照)走这一档。
+ */
+function baseForms(p: string): string[] {
+	const out = [p];
+	try {
+		const r = fs.realpathSync(p);
+		if (r !== p) out.push(r);
+	} catch {
+		/* 不存在:仅词法形 */
+	}
+	return out;
+}
+
+/**
+ * 祖先重建档(#20):基础形之外,目标尚不存在时自最近存在祖先的 realpath 逐级
+ * 重建真实形——symlink 别名即使最终段不存在也暴露其真实位置。误放行代价高的
+ * 判定(自保护层、路径敏感度 floor)走这一档;denyPaths 不升档(ADR-0002)。
+ */
+function rebuiltForms(abs: string): string[] {
+	const out = new Set<string>([abs]);
+	let dir = abs;
+	const tail: string[] = [];
+	for (;;) {
+		try {
+			const real = fs.realpathSync(dir);
+			out.add(path.join(real, ...tail));
+			return [...out];
+		} catch {
+			const parent = path.dirname(dir);
+			if (parent === dir) return [...out];
+			tail.unshift(path.basename(dir));
+			dir = parent;
+		}
+	}
+}
+
+/** Case-insensitive filesystems (default macOS APFS, Windows) compare path strings
+ *  case-folded; realpath already normalizes case whenever it resolves, this covers
+ *  the lexical-only forms of nonexistent targets (#21). Linux stays case-sensitive.
+ *  折叠比较仅 denyPaths 消费(S-rules 的比较纪律在正则 /i、自保护层在精确匹配
+ *  ——各自持有,不因本模块统一,见双形匹配词条)。 */
+const CASE_INSENSITIVE_FS = process.platform === "darwin" || process.platform === "win32";
+const fold = (s: string): string => (CASE_INSENSITIVE_FS ? s.toLowerCase() : s);
+const pathEquals = (a: string, b: string): boolean => fold(a) === fold(b);
+const pathStartsWith = (child: string, base: string): boolean => fold(child).startsWith(fold(base) + path.sep);
+
 // ============================================================================
 // 用户规则:白名单/黑名单(可配置;#12 审计响应)
 //
@@ -217,11 +276,12 @@ const OWN_FILE_PATH: string | null = (() => {
  * Resolve the agent directory the gate is anchored to (#35, dual-host):
  *   1. PI_CODING_AGENT_DIR — explicit user override, always wins.
  *   2. Self-anchoring from the extension's own installed path: a copy at
- *      <home>/<dot-dir>/agent/(plugins/node_modules/<pkg>/)?extensions/…
+ *      <home>/<dot-dir>/(agent/)?(plugins/node_modules/<pkg>/)?extensions/…
  *      anchors to <home>/<dot-dir>/agent. Covers the pi forms
- *      (~/.pi/agent/extensions[/pkg]/…) and the omp npm form
- *      (~/.omp/agent/plugins/node_modules/<pkg>/extensions/…); XDG-style
- *      ~/.config/pi trees match too because the anchor accepts any dot-dir.
+ *      (~/.pi/agent/extensions[/pkg]/…) and the two omp npm layouts:
+ *      under the agent dir (~/.omp/agent/plugins/node_modules/<pkg>/…) and,
+ *      since omp 18.1, next to it (~/.omp/plugins/node_modules/<pkg>/…) —
+ *      omp keeps its config tree under <dot-dir>/agent in both layouts.
  *      Deliberately NO host-tree existence probing: on a dual-install machine
  *      running under pi, a present ~/.omp must not misroute the gate.
  *   3. Fallback: today's default (~/.pi/agent) — dev checkouts and any
@@ -232,8 +292,8 @@ const OWN_FILE_PATH: string | null = (() => {
 export function resolveAgentDir(ownFile: string | null, home: string, envAgentDir: string | undefined): string {
 	if (envAgentDir) return envAgentDir;
 	if (ownFile) {
-		const anchor = new RegExp(`^${escapeRegExp(home)}(/(\\.[^/]+)/agent/(?:plugins/node_modules/(?:@[^/]+/)?[^/]+/)?extensions/)`);
-		for (const f of [ownFile, tryRealpath(ownFile)]) {
+		const anchor = new RegExp(`^${escapeRegExp(home)}(/(\\.[^/]+)/(?:agent/)?(?:plugins/node_modules/(?:@[^/]+/)?[^/]+/)?extensions/)`);
+		for (const f of baseForms(ownFile)) {
 			const m = f.match(anchor);
 			if (m) return path.join(home, m[2], "agent");
 		}
@@ -346,38 +406,13 @@ const S1_SYSTEM = [/^\/etc(\/|$)/i, /^\/private\/(etc|var)(\/|$)/i, /^\/usr(\/|$
 const S2_USER_RC = [/\.(bashrc|zshrc|profile|bash_profile|gitconfig)$/i, /crontab/i, /Library\/LaunchAgents(\/|$)/i, /\.config\/systemd(\/|$)/i];
 const S3_GIT_META = [/(^|\/)\.git\/(hooks|config|modules)(\/|$)/i, /(^|\/)\.gitmodules$/i];
 
-/**
- * All canonical forms of a path for rule matching: the lexical absolute plus,
- * whenever an existing ancestor can be resolved, the form rebuilt from that
- * ancestor's realpath. Read and write targets may both not exist yet — walking
- * up to the nearest existing ancestor means a symlink alias exposes its real
- * form even when the final segments do not exist (#20).
- */
-function targetForms(abs: string): string[] {
-	const out = new Set<string>([abs]);
-	let dir = abs;
-	const tail: string[] = [];
-	for (;;) {
-		try {
-			const real = fs.realpathSync(dir);
-			out.add(path.join(real, ...tail));
-			return [...out];
-		} catch {
-			const parent = path.dirname(dir);
-			if (parent === dir) return [...out];
-			tail.unshift(path.basename(dir));
-			dir = parent;
-		}
-	}
-}
-
 /** read 类工具:S0 读取即高危(deny),其余读取放行。isWrite: write/edit 走完整分级 */
 function classifyPath(toolName: string, rawPath: string, cwd: string, isWrite: boolean, floorOn: boolean): RuleResult {
 	const abs = path.resolve(cwd, expandHome(rawPath));
 	// Dual-form matching (#20): rules test every canonical form of the target —
 	// a project-local symlink aliasing ~/.ssh or a .git/hooks dir must not pass
 	// the floor on its lexical spelling alone.
-	const forms = targetForms(abs);
+	const forms = rebuiltForms(abs);
 	const hit = (rules: RegExp[]) => forms.some((f) => rules.some((r) => r.test(f)));
 	// floor 关闭时:内置 deny 一律降级 gray(永不升格 allow);非 deny 分支(allow/gray)保持
 	const D = floorOn
@@ -395,7 +430,7 @@ function classifyPath(toolName: string, rawPath: string, cwd: string, isWrite: b
 	// In-cwd write allowance (#20): every canonical form must sit inside the cwd
 	// (in either its lexical or real form) — a lexical prefix hit whose real
 	// form escapes the project (symlink alias) grades as an outside-cwd write.
-	const cwdBases = new Set([cwd, tryRealpath(cwd)]);
+	const cwdBases = new Set(baseForms(cwd));
 	const inCwd = (f: string) => [...cwdBases].some((b) => f === b || f.startsWith(b + path.sep));
 	if (forms.every(inCwd)) return { verdict: "allow" };
 	return { verdict: "gray", reason: `write outside project directory (CWD): ${rawPath}` };
@@ -454,20 +489,14 @@ function userRuleTarget(toolName: string, input: Record<string, unknown>, cwd: s
 const BASH_PATH_TOKENS =
 	/(?:~|\$HOME)(?:\/[\w.@*-]+)*|\/(?:[\w.@*-]+\/)*[\w.@*-]*|\.{1,2}(?:\/[\w.@*-]+)+|[\w.-]+(?:\/[\w.-]+)+/g;
 
-/** Case-insensitive filesystems (default macOS APFS, Windows) compare path strings
- *  case-folded; realpath already normalizes case whenever it resolves, this covers
- *  the lexical-only forms of nonexistent targets (#21). Linux stays case-sensitive. */
-const CASE_INSENSITIVE_FS = process.platform === "darwin" || process.platform === "win32";
-const fold = (s: string): string => (CASE_INSENSITIVE_FS ? s.toLowerCase() : s);
-const pathEquals = (a: string, b: string): boolean => fold(a) === fold(b);
-const pathStartsWith = (child: string, base: string): boolean => fold(child).startsWith(fold(base) + path.sep);
-
-/** Normalized forms of one path (lexical + realpath when it exists) for denyPaths comparison */
+/** Normalized forms of one path for denyPaths comparison: base tier only (ADR-0002) —
+ *  no ancestor rebuild; a nonexistent target under a symlinked dir falls to the
+ *  classifier + existence hint instead (pinned by a regression test). */
 function denyPathForms(raw: string, cwd: string): string[] {
 	if (!raw) return [];
 	// denyPaths spellings accept $HOME/ as an alias for ~/ (user-rule targets stay raw strings — no $ expansion there)
 	const expanded = expandHome(raw.replace(/^\$HOME(?=\/|$)/, os.homedir()));
-	return pathForms(path.resolve(cwd, expanded));
+	return baseForms(path.resolve(cwd, expanded));
 }
 
 /** Normalize the configured denyPaths against one cwd (ADR-0002: anchored once per session, never re-derived) */
@@ -506,10 +535,9 @@ function hitDenyPaths(toolName: string, input: Record<string, unknown>, cwd: str
 // 门禁自身的完整性不受任何配置豁免:builtinDenyFloor:false 只关危险正则与路径
 // 敏感度,关不掉本层;用户 allow 规则亦不可越过。保护对象:
 //   - <agentDir>/config/pi-verdict.json(用户规则 = 门禁的判定输入)
-//   - 本扩展的安装副本(pi installs under <agentDir>/extensions/, omp under
-//     <agentDir>/plugins/node_modules/<pkg>/; self-anchored via import.meta.url,
-//     covering the single-file and npm package-dir install forms; dev
-//     checkouts are not in scope)
+//   - 本扩展的安装副本(pi under <agentDir>/extensions/, omp under
+//     plugins/node_modules/<pkg>/ in its config root — install forms listed
+//     with resolveAgentDir; dev checkouts are not in scope)
 // 语义:门禁内一切写入按定义均由 agent 发起 → 恒 deny(reason 指引手工编辑);
 // 读放行(读门禁文件无害);用户经编辑器的修改不经门禁,不受影响。
 // bash 侧:命令串正则覆盖字面量/~/\$HOME/\$PI_CODING_AGENT_DIR 变体,可被混淆
@@ -529,26 +557,6 @@ interface ProtectedSet {
 
 type WatchKind = "config" | "extension";
 
-function tryRealpath(p: string): string {
-	try {
-		return fs.realpathSync(p);
-	} catch {
-		return p;
-	}
-}
-
-/** 路径的全部规范形:词法绝对 + realpath(存在且不同时追加) */
-function pathForms(p: string): string[] {
-	const out = [p];
-	try {
-		const r = fs.realpathSync(p);
-		if (r !== p) out.push(r);
-	} catch {
-		/* 不存在:仅词法形 */
-	}
-	return out;
-}
-
 function escapeRegExp(s: string): string {
 	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -556,17 +564,17 @@ function escapeRegExp(s: string): string {
 /**
  * 构建受保护集合。
  * ownFile:本模块文件路径(import.meta.url 解析;null = 不可解析,仅保护配置)。
- * The installed copy is protected only when ownFile sits under
- * <agentDir>/extensions/ (pi) or <agentDir>/plugins/node_modules/<pkg>/
- * (omp npm form, #35). Dev checkouts (source inside the cwd) are NOT
- * protected — in-project development writes are legitimate daily work (ADR-0001).
+ * The installed copy is protected only when ownFile sits under one of the
+ * install roots (forms listed with resolveAgentDir; #35). Dev checkouts
+ * (source inside the cwd) are NOT protected — in-project development writes
+ * are legitimate daily work (ADR-0001).
  */
 export function buildProtectedSet(agentDir: string, ownFile: string | null): ProtectedSet {
 	const exact = new Set<string>();
 	const prefixes = new Set<string>();
 	const configPath = path.join(agentDir, "config", "pi-verdict.json");
 	const watchBases: Array<{ file: string; kind: WatchKind }> = [{ file: configPath, kind: "config" }];
-	for (const f of pathForms(configPath)) exact.add(f);
+	for (const f of baseForms(configPath)) exact.add(f);
 
 	// 安装副本目标:单文件形态 → 文件本体(exact);npm 目录形态 → 包根目录(prefix)。
 	// extRoot 与 ownFile 各取词法/realpath 双形交叉判定,集合同样双形收录——
@@ -613,35 +621,38 @@ export function buildProtectedSet(agentDir: string, ownFile: string | null): Pro
 		watchBases.push({ file: ownFile, kind: "extension" });
 		const seenWatch = new Set<string>([ownFile]);
 		let pkgRoot: string | null = null;
-		// Install roots, lexical + realpath forms (#35): pi installs under
-		// <agentDir>/extensions/, omp installs npm plugins under
-		// <agentDir>/plugins/node_modules/. First path segment under the matched
-		// root is the install target (single file → exact, package dir → prefix),
-		// so the omp form gets whole-package-dir protection exactly like the pi
-		// npm-dir form (#26).
+		// Install roots, lexical + realpath forms (#35): <agentDir>/extensions
+		// (pi) and plugins/node_modules under agentDir or its parent dir (the
+		// two omp layouts — see resolveAgentDir for the layout history). The
+		// path segments under the matched root name the install target: a file
+		// → exact, a package dir (`@scope/pkg` or `pkg`) → prefix, so every
+		// npm form gets whole-package-dir protection (#26).
 		const extRoots = new Set<string>();
+		const agentBases = new Set(baseForms(agentDir));
+		const configRootBases = new Set([...agentBases].map((b) => path.dirname(b)));
 		for (const seg of [["extensions"], ["plugins", "node_modules"]]) {
-			for (const base of new Set([agentDir, tryRealpath(agentDir)])) {
-				const root = path.join(base, ...seg);
-				extRoots.add(root);
-				extRoots.add(tryRealpath(root));
+			const bases = seg.length === 2 ? new Set([...agentBases, ...configRootBases]) : agentBases;
+			for (const base of bases) {
+				for (const root of baseForms(path.join(base, ...seg))) extRoots.add(root);
 			}
 		}
-		const ownForms = new Set([ownFile, tryRealpath(ownFile)]);
+		const ownForms = new Set(baseForms(ownFile));
 		for (const extRoot of extRoots) {
 			for (const own of ownForms) {
 				if (!own.startsWith(extRoot + path.sep)) continue;
-				const rel = path.relative(extRoot, own);
-				const singleFile = !rel.includes(path.sep);
-				const target = singleFile ? own : path.join(extRoot, rel.split(path.sep)[0]);
-				for (const f of pathForms(target)) {
+				const segs = path.relative(extRoot, own).split(path.sep);
+				const singleFile = segs.length === 1;
+				// npm scopes are two-segment dirs (@scope/pkg): the install
+				// target is the package, not the whole scope dir
+				const target = singleFile ? own : path.join(extRoot, ...segs.slice(0, segs[0].startsWith("@") ? 2 : 1));
+				for (const f of baseForms(target)) {
 					(singleFile ? exact : prefixes).add(f);
 					extTargets.add(f);
 				}
 				if (!singleFile && pkgRoot === null) pkgRoot = target;
 			}
 		}
-		// one walk of the package root (lexical form; takeSnapshots' pathForms
+		// one walk of the package root (lexical form; takeSnapshots' baseForms
 		// expansion picks up real forms per file) — no duplicate entries
 		if (pkgRoot !== null) {
 			for (const f of listPackageFiles(pkgRoot)) {
@@ -665,7 +676,7 @@ export function buildProtectedSet(agentDir: string, ownFile: string | null): Pro
 				alts.add("\\$HOME/" + escapeRegExp(rel));
 			}
 			// $PI_CODING_AGENT_DIR 变体:词法与 realpath 两种基名列举(符号链接目录容忍)
-			for (const base of new Set([agentDir, tryRealpath(agentDir)])) {
+			for (const base of new Set(baseForms(agentDir))) {
 				if (f.startsWith(base + path.sep)) {
 					alts.add("\\$PI_CODING_AGENT_DIR/" + escapeRegExp(f.slice(base.length + 1)));
 				}
@@ -682,7 +693,7 @@ export function buildProtectedSet(agentDir: string, ownFile: string | null): Pro
  *  nearest existing ancestor, #20) */
 export function isProtectedWritePath(rawPath: string, cwd: string, prot: ProtectedSet): boolean {
 	if (!rawPath) return false;
-	for (const c of targetForms(path.resolve(cwd, expandHome(rawPath)))) {
+	for (const c of rebuiltForms(path.resolve(cwd, expandHome(rawPath)))) {
 		if (prot.exact.includes(c)) return true;
 		for (const p of prot.prefixes) {
 			if (c === p || c.startsWith(p + path.sep)) return true;
@@ -692,7 +703,7 @@ export function isProtectedWritePath(rawPath: string, cwd: string, prot: Protect
 }
 
 /** 自保护层裁决(第 0 层,先于一切):触碰门禁自身文件 → 不可豁免的 deny;其余 null 交后续层 */
-export function selfProtectCheck(toolName: string, input: Record<string, unknown>, cwd: string, prot: ProtectedSet): RuleResult | null {
+function selfProtectCheck(toolName: string, input: Record<string, unknown>, cwd: string, prot: ProtectedSet): RuleResult | null {
 	switch (toolName) {
 		case "write":
 		case "edit":
@@ -722,7 +733,7 @@ function takeSnapshots(bases: Array<{ file: string; kind: WatchKind }>): Array<{
 	const out: Array<{ file: string; kind: WatchKind; content: Buffer | null }> = [];
 	const seen = new Set<string>();
 	for (const b of bases) {
-		for (const f of pathForms(b.file)) {
+		for (const f of baseForms(b.file)) {
 			if (seen.has(f)) continue;
 			seen.add(f);
 			let content: Buffer | null = null;
@@ -737,6 +748,68 @@ function takeSnapshots(bases: Array<{ file: string; kind: WatchKind }>): Array<{
 	return out;
 }
 
+/**
+ * 变更检测(ADR-0001 一期)的会话实例:基线快照 + 篡改旗标。处置差分(config-only
+ * 且有 UI → select 双选)由扩展 handler 编排——本类零 UI;restoreAndFailClose 只做
+ * 还原与置位,通知由调用方按返回的文件清单/原因拼装。
+ */
+class IntegrityWatch {
+	private snapshots: Array<{ file: string; kind: WatchKind; content: Buffer | null }>;
+	private _tampered = false;
+
+	constructor(private watchBases: Array<{ file: string; kind: WatchKind }>) {
+		this.snapshots = takeSnapshots(watchBases);
+	}
+
+	get tampered(): boolean {
+		return this._tampered;
+	}
+
+	/** 复核受保护文件,返回变化清单(不处置——处置按 kind 差分,ADR-0001 定稿 D) */
+	detect(): Array<{ file: string; kind: WatchKind }> {
+		const hit: Array<{ file: string; kind: WatchKind }> = [];
+		for (const s of this.snapshots) {
+			let current: Buffer | null = null;
+			try {
+				current = fs.readFileSync(s.file);
+			} catch {
+				/* 不存在 */
+			}
+			const same = (a: Buffer | null, b: Buffer | null): boolean => (a === null || b === null ? a === b : a.equals(b));
+			if (!same(current, s.content)) hit.push({ file: s.file, kind: s.kind });
+		}
+		return hit;
+	}
+
+	/** 重建基线(Accept 路径与 session_start 共用;不动篡改旗标) */
+	rebaseline(): void {
+		this.snapshots = takeSnapshots(this.watchBases);
+	}
+
+	/** 会话重置:重建基线 + 清篡改旗标 */
+	startSession(): void {
+		this.rebaseline();
+		this._tampered = false;
+	}
+
+	/** 从快照回写变化文件(扩展进程自身执行,不经门禁)+ fail-closed 置位 */
+	restoreAndFailClose(changed: Array<{ file: string }>, cause: string): { reason: string; files: string } {
+		for (const c of changed) {
+			const s = this.snapshots.find((x) => x.file === c.file);
+			if (s && s.content !== null) {
+				try {
+					fs.writeFileSync(s.file, s.content);
+				} catch {
+					/* 还原失败:仍 fail-closed */
+				}
+			}
+		}
+		this._tampered = true;
+		const files = [...new Set(changed.map((c) => c.file))].join(", ");
+		return { reason: `[auto-mode] self-protection: tamper detected${cause ? ` (${cause})` : ""} and restored (${files}); fail-closed until restart`, files };
+	}
+}
+
 /**
  * Tool call → rule-layer verdict. Order (#12; ADR-0001 adds layer 0; ADR-0002 inserts denyPaths):
  *   0. self-protection — deny is terminal (no config exempts it, not even builtinDenyFloor:false)
@@ -846,15 +919,19 @@ function toolCallLine(name: string, args: Record<string, unknown>): string {
 	return `${name}: ${transcriptSafe(JSON.stringify(args))}`;
 }
 
+/** 判定管线对宿主会话的最小结构需求(转录源 + 会话 id)——adjudicate 不接完整
+ *  ExtensionContext,测试只喂这两个成员即可 */
+export type PipelineHost = Pick<ExtensionContext["sessionManager"], "getBranch" | "getSessionId">;
+
 /**
  * 从会话分支收集精简转录原料:user 消息行与 assistant 工具调用行。
  * 丢弃 assistant 叙述/thinking 与 toolResult(注入面与 token 大头)。
  * 影子缓存的 contextKey 与 buildTranscript 同源(同一批 user 行),保证键与模型输入一致。
  */
-function collectTranscriptParts(ctx: ExtensionContext): { userLines: string[]; toolLines: string[] } {
+function collectTranscriptParts(host: PipelineHost): { userLines: string[]; toolLines: string[] } {
 	const userLines: string[] = [];
 	const toolLines: string[] = [];
-	for (const entry of ctx.sessionManager.getBranch()) {
+	for (const entry of host.getBranch()) {
 		if (entry.type !== "message") continue;
 		const msg = entry.message;
 		if (msg.role === "user") {
@@ -870,8 +947,8 @@ function collectTranscriptParts(ctx: ExtensionContext): { userLines: string[]; t
 }
 
 /** 精简转录:最近 user 消息 + 最近工具调用,待审查动作固定为最后一行(位置约定,借鉴 CC) */
-function buildTranscript(ctx: ExtensionContext, actionLine: string): string {
-	const { userLines, toolLines } = collectTranscriptParts(ctx);
+function buildTranscript(host: PipelineHost, actionLine: string): string {
+	const { userLines, toolLines } = collectTranscriptParts(host);
 	const lines = [...userLines.slice(-MAX_USER_MESSAGES), ...toolLines.slice(-MAX_TOOL_CALLS)];
 	lines.push(actionLine);
 	return lines.join("\n");
@@ -944,18 +1021,22 @@ function completionFor(registry: { complete?: unknown }, compatLoader?: CompatLo
 	return fn;
 }
 
+/** 分类器思考级别(pi 原生词表;后缀语法对齐 pi --model provider/id:thinking) */
+type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
 /** 单次分类器调用:显式 reasoning:"off"(见下方注释),失败返回错误串而非抛出 */
 async function callClassifierOnce(
-	ctx: ExtensionContext,
+	host: PipelineHost,
+	signal: AbortSignal | undefined,
 	complete: CompletionFn,
 	model: NonNullable<ExtensionContext["model"]>,
 	userMessage: string,
 	maxTokens: number,
-	thinking: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" = "off",
+	thinking: ThinkingLevel = "off",
 	systemPrompt: string = CLASSIFIER_SYSTEM,
 ): 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);
+	if (signal) signals.push(signal);
 	try {
 		const response = await complete(
 			model,
@@ -987,7 +1068,7 @@ async function callClassifierOnce(
 							reasoning: thinking === "minimal" ? ("low" as const) : thinking,
 						}),
 				cacheRetention: "short",
-				sessionId: ctx.sessionManager.getSessionId(),
+				sessionId: host.getSessionId(),
 			},
 		);
 		const text = response.content
@@ -1007,21 +1088,22 @@ async function callClassifierOnce(
  * 两档皆失败 → fail-closed deny(理由含两次诊断)。
  */
 async function classifyWithModel(
-	ctx: ExtensionContext,
+	host: PipelineHost,
+	signal: AbortSignal | undefined,
 	complete: CompletionFn,
 	model: NonNullable<ExtensionContext["model"]>,
 	actionLine: string,
-	thinking: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" = "off",
+	thinking: ThinkingLevel = "off",
 	denyPathsActive = false,
 ): Promise<ClassifierOutcome> {
-	const transcript = buildTranscript(ctx, actionLine);
+	const transcript = buildTranscript(host, actionLine);
 	const userMessage = `<transcript>\n${transcript}\n</transcript>\nJudge the LAST action in the transcript above. Your entire response MUST begin with <verdict>.`;
 	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[] = [];
 	for (const [n, maxTokens] of attempts) {
-		if (ctx.signal?.aborted) break; // 用户已取消,不再重试
-		const r = await callClassifierOnce(ctx, complete, model, userMessage, maxTokens, thinking, systemPrompt);
+		if (signal?.aborted) break; // 用户已取消,不再重试
+		const r = await callClassifierOnce(host, signal, complete, model, userMessage, maxTokens, thinking, systemPrompt);
 		if (r.ok) {
 			const diag = `stopReason=${r.stopReason}, model=${model.id}, raw output=${JSON.stringify(r.text.slice(0, 200))}`;
 			if (r.stopReason !== "error" && r.stopReason !== "aborted") {
@@ -1146,8 +1228,8 @@ function shadowCommandKey(toolName: string, input: Record<string, unknown>, cwd:
 	return fnv1a(`${toolName}\u0000${JSON.stringify(input)}\u0000${cwd}`);
 }
 
-function shadowContextKey(ctx: ExtensionContext): string {
-	const { userLines } = collectTranscriptParts(ctx);
+function shadowContextKey(host: PipelineHost): string {
+	const { userLines } = collectTranscriptParts(host);
 	return fnv1a(userLines.slice(-MAX_USER_MESSAGES).join("\u0000"));
 }
 
@@ -1157,6 +1239,121 @@ function shadowTag(probe: ShadowProbe): string {
 	return `(shadow cache: miss:no-entry)`;
 }
 
+// ============================================================================
+// 会话态:判定管线的会话期状态(复位清单集中一处)
+// ============================================================================
+
+/**
+ * 判定管线的会话期状态。session_start 的复位清单归 reset() 拥有——新增会话态只改
+ * 这里,install 与 session_start 不再各持一份初始化点。prot 源自安装路径而非配置,
+ * 构造期定,不参与 reset。导出仅为测试(内部 seam 的测试面,与 adjudicate 同组)。
+ */
+export class SessionState {
+	readonly prot: ProtectedSet;
+	readonly shadow = new ShadowCache();
+	userRules: UserRules;
+	private denyPathBases: string[] | null = null;
+
+	constructor(prot: ProtectedSet, userRules: UserRules = loadUserRules().rules) {
+		this.prot = prot;
+		this.userRules = userRules;
+	}
+
+	/** 会话重置:重载用户规则(配置改动新会话生效)+ 按会话 cwd 重锚 denyPaths
+	 *  (ADR-0002: 每会话锚定一次)+ 清影子缓存;返回加载报告供表现层通知 */
+	reset(cwd: string): { skipped: string[]; shortcutWarning: string | null } {
+		const loaded = loadUserRules();
+		this.userRules = loaded.rules;
+		this.denyPathBases = anchorDenyPaths(loaded.rules.denyPaths, cwd); // anchored to the session cwd, once (ADR-0002)
+		this.shadow.reset();
+		return { skipped: loaded.skipped, shortcutWarning: loaded.shortcutWarning };
+	}
+
+	/** denyPaths 基址:session_start 已锚定;此惰性回退仅守护乱序的首次 tool_call
+	 *  (pi 正常次序 session_start 先行),一旦锚定不再重derive。 */
+	anchoredDenyPathBases(cwd: string): string[] {
+		if (this.denyPathBases === null) this.denyPathBases = anchorDenyPaths(this.userRules.denyPaths, cwd);
+		return this.denyPathBases;
+	}
+}
+
+// ============================================================================
+// 判定管线(adjudicate):tool_call → Verdict 的唯一裁决入口,零 UI 依赖
+// ============================================================================
+
+/** 裁决来源:呈现模板的键之一(与 degraded 正交分解)。rule = 规则层(含自保护层
+ *  ——同走规则呈现模板);protected-path = denyPaths 命中;classifier = 灰区分类器
+ *  结果(含其 fail-closed——呈现模板相同);fail-closed = 无可用分类器模型 */
+export type VerdictSource = "rule" | "protected-path" | "classifier" | "fail-closed";
+
+/** 判定管线的输出值对象:一次 tool_call 的完整裁决。detail 为 UI-only 明文(受保护
+ *  路径仅入本地确认框,ADR-0002 零泄漏承诺——reason 与通知永不携带);degraded 标记
+ *  ask 在无 UI 会话的降级产物;shadow 为影子缓存标注(仅 debug 呈现拼接用)。 */
+export interface Verdict {
+	verdict: "allow" | "ask" | "deny";
+	reason: string;
+	detail?: string;
+	source: VerdictSource;
+	degraded: boolean;
+	shadow?: string;
+}
+
+/** 逐调用环境:呈现无关的宿主能力。model 经 getModel 惰性求值——保持「仅灰区才
+ *  解析」的原行为(回退警告不会出现在规则已裁决的调用上);null → fail-closed。 */
+export interface AdjudicateEnv {
+	cwd: string;
+	hasUI: boolean;
+	getModel: () => { model: NonNullable<ExtensionContext["model"]>; thinking: ThinkingLevel } | null;
+	complete: CompletionFn;
+	host: PipelineHost;
+	signal?: AbortSignal;
+}
+
+/**
+ * 判定管线(CONTEXT.md「判定管线」词条的实现):自保护 → 内置 floor → 用户 deny →
+ * denyPaths ask → 用户 allow → 灰区分类器;ask 降级(无 UI → deny)与 fail-closed
+ * 内建于此,两处重复的降级实现自此唯一。零 UI:表现(notify/confirm/select)由扩展
+ * handler 按 source × degraded 模板呈现;变更检测(IntegrityWatch)是管线前置的
+ * 独立关注点,不在 adjudicate 内。导出仅为测试(内部 seam 的测试面,#35 既有模式)。
+ */
+export async function adjudicate(
+	state: SessionState,
+	call: { toolName: string; input: Record<string, unknown> },
+	env: AdjudicateEnv,
+): Promise<Verdict> {
+	const rule = classifyByRules(call.toolName, call.input, env.cwd, state.userRules, state.prot, state.anchoredDenyPathBases(env.cwd));
+	if (rule.verdict === "allow") return { verdict: "allow", reason: rule.reason ?? "", source: "rule", degraded: false };
+	if (rule.verdict === "deny") return { verdict: "deny", reason: rule.reason ?? "", source: "rule", degraded: false };
+	if (rule.verdict === "ask") {
+		// denyPaths 命中 → ask 终局(ADR-0002):声明者本人裁决例外;无 UI 降级为 deny
+		return { verdict: env.hasUI ? "ask" : "deny", reason: rule.reason ?? "", detail: rule.detail, source: "protected-path", degraded: !env.hasUI };
+	}
+
+	// 灰区 → 分类器;无可用模型 → fail-closed
+	const resolved = env.getModel();
+	if (!resolved) return { verdict: "deny", reason: "no classifier model available (fail-closed)", 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);
+
+	// 影子回记:真实模型 allow/deny 入缓存;ask 与 fail-closed 不入(#5 定案);
+	// 命中且本次为可缓存裁决时,对比反事实一致性
+	if (outcome.source === "model" && outcome.verdict !== "ask") {
+		if (probe.result === "hit") state.shadow.countDivergence(probe.entry.verdict, outcome.verdict);
+		state.shadow.record(cmdKey, ctxKey, outcome.verdict);
+	}
+
+	const shadow = shadowTag(probe);
+	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 词条)
+	return { verdict: env.hasUI ? "ask" : "deny", reason: outcome.reason, source: "classifier", degraded: !env.hasUI, shadow };
+}
+
 // ============================================================================
 // 扩展主体
 // ============================================================================
@@ -1173,56 +1370,58 @@ 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";
-	const shadow = new ShadowCache();
-	let userRules: UserRules = loadUserRules().rules;
-	// denyPath bases, normalized ONCE per session anchored to the session cwd (ADR-0002):
-	// mid-session symlink creation or cwd drift must not change what the declaration covers.
-	// session_start anchors it; the lazy null-fallback only guards an out-of-order first
-	// tool_call (pi's normal order is session_start first) and, once set, it is never re-derived.
-	let denyPathBases: string[] | null = null;
-	const anchoredDenyPathBases = (cwd: string): string[] => {
-		if (denyPathBases === null) denyPathBases = anchorDenyPaths(userRules.denyPaths, cwd);
-		return denyPathBases;
-	};
-
-	// Self-protection layer (ADR-0001): self-anchored protected set + tamper
-	// baseline (in-memory, per session)
-	const prot = buildProtectedSet(agentDirPath(), OWN_FILE_PATH);
-	let snapshots = takeSnapshots(prot.watchBases);
-	let tampered = false;
+	// 会话态与门禁完整性监视:复位清单各归 SessionState.reset / IntegrityWatch.startSession
+	const state = new SessionState(buildProtectedSet(agentDirPath(), OWN_FILE_PATH));
+	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 };
+	}
 
-	/** 复核受保护文件,返回变化清单(不还原——处置按 kind 差分,ADR-0001 定稿 D) */
-	function detectTamper(): Array<{ file: string; kind: WatchKind }> {
-		const hit: Array<{ file: string; kind: WatchKind }> = [];
-		for (const s of snapshots) {
-			let current: Buffer | null = null;
-			try {
-				current = fs.readFileSync(s.file);
-			} catch {
-				/* 不存在 */
+	/** Verdict → UI(本扩展唯一的裁决呈现点):按 source × degraded 查模板,文案与
+	 *  重构前逐字节一致。受保护路径分支的通知永不携带路径明文与 action 行
+	 *  (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") {
+			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");
 			}
-			const same = (a: Buffer | null, b: Buffer | null): boolean => (a === null || b === null ? a === b : a.equals(b));
-			if (!same(current, s.content)) hit.push({ file: s.file, kind: s.kind });
+			return undefined;
 		}
-		return hit;
-	}
-
-	/** 从快照回写变化文件(扩展进程自身执行,不经门禁)+ fail-closed,返回 block 载荷 */
-	function restoreAndFailClose(changed: Array<{ file: string }>, ctx: ExtensionContext, cause: string): { block: true; reason: string } {
-		for (const c of changed) {
-			const s = snapshots.find((x) => x.file === c.file);
-			if (s && s.content !== null) {
-				try {
-					fs.writeFileSync(s.file, s.content);
-				} catch {
-					/* 还原失败:仍 fail-closed */
-				}
+		if (v.verdict === "deny") {
+			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}` };
+			}
+			if (v.source === "fail-closed") {
+				ctx.ui.notify(`🛡️ Auto Mode blocked: ${v.reason}\n  ${action}`, "warning");
+				return { block: true, reason: `[auto-mode] ${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}` };
 			}
+			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}` };
 		}
-		tampered = true;
-		const files = [...new Set(changed.map((c) => c.file))].join(", ");
-		ctx.ui.notify(`🛡️ pi-verdict TAMPER DETECTED${cause ? ` (${cause})` : ""}: ${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: `[auto-mode] self-protection: tamper detected${cause ? ` (${cause})` : ""} and restored (${files}); fail-closed until restart` };
+		// ask → 人工确认;非交互已在管线内降级,能走到这里的必有 UI
+		if (v.source === "protected-path") {
+			const ok = await ctx.ui.confirm("🛡️ Auto Mode: protected path", `${action}\n\n${v.reason}\n\nProtected path: ${v.detail ?? "(see pi-verdict.json)"}\n\nAllow this access?`);
+			if (ok) {
+				// debug notify 不带 action 行:同上,通知不得携带受保护路径明文
+				if (debug) ctx.ui.notify("🛡️ allow (protected-path confirm)", "info");
+				return undefined;
+			}
+			return { block: true, reason: "[auto-mode] 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" };
 	}
 
 	function refreshStatus(ctx: ExtensionContext) {
@@ -1240,23 +1439,19 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 	// session_start:重置影子缓存(会话内存态,#5 定案)+ 重载用户规则(配置改动新会话生效)
 	// + 重建自保护基线(ADR-0001:受保护文件的会话启动快照)
 	pi.on("session_start", async (_event, ctx) => {
-		shadow.reset();
-		tampered = false;
-		const loaded = loadUserRules();
-		userRules = loaded.rules;
-		denyPathBases = anchorDenyPaths(userRules.denyPaths, ctx.cwd); // anchored to the session cwd, once (ADR-0002)
-		snapshots = takeSnapshots(prot.watchBases);
-		if (loaded.skipped.length > 0) {
-			ctx.ui.notify(`pi-verdict: skipped ${loaded.skipped.length} invalid config value(s) in config (${userConfigPath()}): ${loaded.skipped.join(", ")}`, "warning");
+		const report = state.reset(ctx.cwd);
+		integrity.startSession();
+		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");
 		}
-		if (loaded.shortcutWarning) ctx.ui.notify(`pi-verdict: ${loaded.shortcutWarning}`, "warning");
+		if (report.shortcutWarning) ctx.ui.notify(`pi-verdict: ${report.shortcutWarning}`, "warning");
 		refreshStatus(ctx);
 	});
 
 	// 主开关 toggle 快捷键(#15):键位取首次加载的用户规则(会话内固定——改配置后
 	// /reload 重载扩展或新会话生效);handler 与 /automode 语义等价,静默切换,
 	// footer 始终显示是唯一反馈
-	const registeredToggleKey = userRules.toggleShortcut;
+	const registeredToggleKey = state.userRules.toggleShortcut;
 	if (registeredToggleKey) {
 		// KeyId 是 pi 的编译期联合类型(运行时即 string);用户配置键位经 KEY_COMBO_RE
 		// 运行时校验后断言转入,零依赖约束下不引入 pi 内部类型路径
@@ -1269,7 +1464,7 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 	/** Usage 行的 toggle 提示(#15):无注册键位时不显示;显示注册时固定的键 */
 	const toggleHint = () => (registeredToggleKey ? ` · toggle: ${registeredToggleKey}` : "");
 	/** Status line denyPaths count (ADR-0002): shown only when configured */
-	const denyPathsHint = () => (userRules.denyPaths.length > 0 ? `\ndenyPaths: ${userRules.denyPaths.length} active` : "");
+	const denyPathsHint = () => (state.userRules.denyPaths.length > 0 ? `\ndenyPaths: ${state.userRules.denyPaths.length} active` : "");
 
 	pi.registerCommand("automode", {
 		description: "Show Auto Mode status and shadow-cache stats, or set it: /automode on|off",
@@ -1277,7 +1472,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${shadow.summary()}${denyPathsHint()}\nUsage: /automode on|off${toggleHint()}`, "info");
+				ctx.ui.notify(`${enabled ? "🛡️ Auto Mode: on" : "Auto Mode: off"}\n${state.shadow.summary()}${denyPathsHint()}\nUsage: /automode on|off${toggleHint()}`, "info");
 			return;
 			}
 			// 幂等设定:与现值相同不翻转,仅确认
@@ -1288,7 +1483,7 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 				const head = next
 					? `🛡️ Auto Mode enabled${changed ? "" : " (unchanged)"}: tool calls adjudicated by rules + classifier`
 					: `Auto Mode disabled${changed ? "" : " (unchanged)"}: tool calls execute directly`;
-				ctx.ui.notify(`${head}\n${shadow.summary()}`, "info");
+				ctx.ui.notify(`${head}\n${state.shadow.summary()}`, "info");
 				return;
 			}
 			// 未知参数:严格拒绝并列出用法(大小写已归一化)
@@ -1314,28 +1509,29 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 		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 {
-		// 优先级:CLI flag > 环境变量 > 配置文件(classifierModel) > 自省(会话模型)
+	/** 解析分类器模型与思考级别:CLI flag > 环境变量 > 配置文件(classifierModel) >
+	 *  自省(会话模型)。不可用回退会话模型并警告一次;null = 连会话模型都没有 →
+	 *  fail-closed。经 AdjudicateEnv.getModel 惰性调用(仅灰区),回退警告不会出现在
+	 *  规则已裁决的调用上。 */
+	function resolveClassifier(ctx: ExtensionContext): { model: NonNullable<ExtensionContext["model"]>; thinking: ThinkingLevel } | null {
 		const raw =
-			(pi.getFlag("auto-mode-model") as string | undefined) ?? process.env.PI_AUTO_MODE_MODEL ?? userRules.classifierModel;
-		classifierThinking = "off";
+			(pi.getFlag("auto-mode-model") as string | undefined) ?? process.env.PI_AUTO_MODE_MODEL ?? state.userRules.classifierModel;
+		let thinking: ThinkingLevel = "off";
 		if (raw) {
 			const { specPart, level } = parseModelSpec(raw, ctx);
-			if (level) classifierThinking = level as typeof classifierThinking;
+			thinking = (level ?? "off") as ThinkingLevel;
 			const slash = specPart.indexOf("/");
 			if (slash > 0) {
 				const model = ctx.modelRegistry.find(specPart.slice(0, slash), specPart.slice(slash + 1));
-				if (model && ctx.modelRegistry.hasConfiguredAuth(model)) return model;
+				if (model && ctx.modelRegistry.hasConfiguredAuth(model)) return { model, thinking };
 			}
 			if (!warnedClassifierModel) {
 				warnedClassifierModel = true; // 每会话仅警告一次,避免逐调用刷屏
 				ctx.ui.notify(`pi-verdict: classifier model "${raw}" unavailable (not found or no configured auth), falling back to session model (self-reflection)`, "warning");
 			}
 		}
-		return ctx.model ?? null; // 自省:继承当前会话模型
+		// 自省:继承当前会话模型;显式指定的思考级别在回退时仍生效(原语义)
+		return ctx.model ? { model: ctx.model, thinking } : null;
 	}
 
 	function describeAction(toolName: string, input: Record<string, unknown>): string {
@@ -1349,11 +1545,11 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 		const action = describeAction(event.toolName, input);
 
 		// 第 0 层前置:变更检测(ADR-0001)——篡改后本会话恒 deny(fail-closed)
-		if (tampered) {
+		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)" };
 		}
-		const changed = detectTamper();
+		const changed = integrity.detect();
 		if (changed.length > 0) {
 			// 差分处置(ADR-0001 定稿 D):仅 config 变化且有 UI → select 双选(选项即动作);
 			// 扩展副本被改 / 无 UI → 一律还原 + fail-closed。
@@ -1368,82 +1564,25 @@ export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 					[CONFIG_ACCEPT_CHOICE, CONFIG_DECLINE_CHOICE],
 				);
 				if (choice === CONFIG_ACCEPT_CHOICE) {
-					snapshots = takeSnapshots(prot.watchBases); // 重建基线
+					integrity.rebaseline(); // 重建基线
 					ctx.ui.notify("pi-verdict: config change accepted — new baseline taken; applies to new sessions as usual", "info");
 				} else {
-					return restoreAndFailClose(changed, ctx, choice === undefined ? "config dialog dismissed" : "config change declined by user");
+					return presentTamper(changed, ctx, choice === undefined ? "config dialog dismissed" : "config change declined by user");
 				}
 			} else {
-				return restoreAndFailClose(changed, ctx, "");
-			}
-		}
-
-		// 第 1 层:规则
-		const rule = classifyByRules(event.toolName, input, ctx.cwd, userRules, prot, anchoredDenyPathBases(ctx.cwd));
-		if (rule.verdict === "allow") {
-			if (debug) ctx.ui.notify(`🛡️ allow (rule): ${action}`, "info");
-			return undefined;
-		}
-		if (rule.verdict === "deny") {
-			ctx.ui.notify(`🛡️ Auto Mode blocked: ${rule.reason}\n  ${action}`, "warning");
-			return { block: true, reason: `[auto-mode rule block] ${rule.reason}` };
-		}
-		// denyPaths hit → deterministic ask (ADR-0002): the declaring user adjudicates
-		// the exception; non-interactive sessions degrade to deny (existing ask rule)
-		if (rule.verdict === "ask") {
-			if (!ctx.hasUI) {
-				// no action line here: the action string can embed the touched path, and
-				// notifications must not carry protected-path plaintext (ADR-0002 story 11)
-				ctx.ui.notify(`🛡️ Auto Mode blocked (non-interactive, protected-path ask→deny): ${rule.reason}`, "warning");
-				return { block: true, reason: `[auto-mode] protected-path ask degraded to block in non-interactive mode: ${rule.reason}` };
-			}
-			const ok = await ctx.ui.confirm("🛡️ Auto Mode: protected path", `${action}\n\n${rule.reason}\n\nProtected path: ${rule.detail ?? "(see pi-verdict.json)"}\n\nAllow this access?`);
-			if (ok) {
-				// debug notify stays plaintext-free too: the action line can embed the
-				// touched path, and notifications must not carry protected-path plaintext
-				if (debug) ctx.ui.notify("🛡️ allow (protected-path confirm)", "info");
-				return undefined;
+				return presentTamper(changed, ctx, "");
 			}
-			return { block: true, reason: "[auto-mode] user declined protected-path access" };
-		}
-
-		// 第 2 层:灰区 → 模型分类器
-		const model = resolveClassifierModel(ctx);
-		if (!model) {
-			ctx.ui.notify(`🛡️ Auto Mode blocked: no classifier model available (fail-closed)\n  ${action}`, "warning");
-			return { block: true, reason: "[auto-mode] no classifier model available (fail-closed)" };
-		}
-
-		// 影子缓存(observe-only):前置查询 would-be 命中,不改变任何裁决
-		const cmdKey = shadowCommandKey(event.toolName, input, ctx.cwd);
-		const ctxKey = shadowContextKey(ctx);
-		const probe = shadow.probe(cmdKey, ctxKey);
-
-		const outcome = await classifyWithModel(ctx, completionFor(ctx.modelRegistry, deps.compatLoader), model, action, classifierThinking, userRules.denyPaths.length > 0);
-
-		// 影子回记:真实模型 allow/deny 入缓存;ask 与 fail-closed 不入(#5 定案);
-		// 命中且本次为可缓存裁决时,对比反事实一致性
-		if (outcome.source === "model" && outcome.verdict !== "ask") {
-			if (probe.result === "hit") shadow.countDivergence(probe.entry.verdict, outcome.verdict);
-			shadow.record(cmdKey, ctxKey, outcome.verdict);
 		}
 
-		if (outcome.verdict === "allow") {
-			if (debug) ctx.ui.notify(`🛡️ allow (classifier): ${outcome.reason}\n  ${action} ${shadowTag(probe)}`, "info");
-			return undefined;
-		}
-		if (outcome.verdict === "deny") {
-			ctx.ui.notify(`🛡️ Auto Mode blocked: ${outcome.reason}\n  ${action}${debug ? " " + shadowTag(probe) : ""}`, "warning");
-			return { block: true, reason: `[auto-mode classifier block] ${outcome.reason}` };
-		}
-
-		// ask:转人工;非交互模式 fail-closed 降级为拦截
-		if (!ctx.hasUI) {
-			ctx.ui.notify(`🛡️ Auto Mode blocked (non-interactive, ask→deny): ${outcome.reason}\n  ${action}`, "warning");
-			return { block: true, reason: `[auto-mode] ask degraded to block in non-interactive mode: ${outcome.reason}` };
-		}
-		const ok = await ctx.ui.confirm("🛡️ Auto Mode confirmation", `${action}\n\nClassifier opinion: ${outcome.reason}\n\nAllow execution?`);
-		if (ok) return undefined;
-		return { block: true, reason: "[auto-mode] user declined" };
+		// 判定管线(零 UI)→ 呈现(source × degraded 模板)
+		const verdict = await adjudicate(state, { toolName: event.toolName, input }, {
+			cwd: ctx.cwd,
+			hasUI: !!ctx.hasUI,
+			getModel: () => resolveClassifier(ctx),
+			complete: completionFor(ctx.modelRegistry, deps.compatLoader),
+			host: ctx.sessionManager,
+			signal: ctx.signal,
+		});
+		return presentVerdict(verdict, action, ctx);
 	});
 }

package/package.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-verdict",
-	"version": "0.6.0",
+	"version": "0.7.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",
-	"main": "extensions/auto-mode.ts",
+	"main": "extensions/pi-verdict.ts",
 	"files": [
-		"extensions/auto-mode.ts",
+		"extensions/pi-verdict.ts",
 		"README.md",
 		"README.zh-CN.md",
 		"LICENSE"