pi-verdict 0.5.2 → 0.6.1

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
@@ -22,24 +22,53 @@ pi-verdict adds the missing gate: a model decides whether each call should run,
 
 ## Why three states
 
-**verdict is an adjudication, not a switch.** Most classifiers in this space output a binary allow/block. Three states matter: `ask` routes genuinely ambiguous actions to a human (and degrades to `deny` in non-interactive sessions), so "not sure" never silently becomes "go ahead".
+**verdict is an adjudication, not a switch.** Most classifiers in this space output a binary allow/block. Three states matter: `ask` routes genuinely ambiguous actions to a human (and degrades to `deny` in non-interactive sessions), so "not sure" never silently becomes "go ahead" — the goal is safe automation, not maximum automation: both approval fatigue and silent unsafe execution lose.
+
+## Design principles
+
+- **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** — 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)
 
 ## Quick start
 
 ```bash
-# install from npm:
+# install from npm (pi):
 pi install npm:pi-verdict
 
+# install from npm (oh-my-pi / omp):
+omp plugin install npm:pi-verdict
+
 # or directly from git — try it once
 pi --extension ./extensions/auto-mode.ts
 
 ```
 
+### Hosts
+
+pi-verdict runs on both [pi](https://github.com/badlogic/pi-mono) and [oh-my-pi](https://github.com/can1357/oh-my-pi) (omp) — it self-anchors to whichever agent tree it is installed in, and follows the extension copy's own location on dual-install machines. On omp 18 the classifier's completion call falls back to the pi-ai compat API (still fail-closed). Details: [docs/configuration.md](docs/configuration.md#host-notes-pi-and-oh-my-pi).
+
+| | pi | omp |
+|---|---|---|
+| install | `pi install npm:pi-verdict` | `omp plugin install npm: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` |
+
 - `/automode` — show current status: on/off + shadow-cache stats for the session
 - `/automode on`
 - `/automode off`
@@ -68,26 +97,18 @@ pi --extension ./extensions/auto-mode.ts
 ```
 
 - `allow`/`deny` are JS regex arrays; **`deny` wins over `allow`**, both beat the classifier
-- `denyPaths` are plain paths (not regexes) you declare **protected**: any tool call touching them — file tools via their path, bash via path tokens extracted from the command string — triggers a **terminal ask** you adjudicate (non-interactive sessions degrade to deny). Not affected by `builtinDenyFloor: false`.
-  The classifier only ever learns that protected paths *exist*; the paths themselves never leave your machine, and a matched path shows **only** in the local confirm dialog.
-- `builtinDenyFloor: false` turns the built-in danger/path floor off entirely (risk accepted by you; the classifier and your rules remain — the self-protection layer below always stays on)
-- `classifierModel: "provider/model-id"` sets the classifier model (e.g. a fast flash-class model); precedence is flag > env > config > session model (self-reflection); an invalid value falls back to the session model with a one-time warning
-- the spec accepts pi's native `--model` thinking suffix: `"zai/glm-5.3-flash:low"` sets classifier thinking to effort low (default without suffix: thinking explicitly off)
-- `toggleShortcut` rebinds the master-switch toggle key (`null` or empty disables it, not persisted)
-- first run generates a template at `~/.pi/agent/config/pi-verdict.json` (honors `PI_CODING_AGENT_DIR`)
+- `denyPaths` are plain paths you declare **protected** — touches trigger a terminal ask you adjudicate (non-interactive → deny); the classifier never learns the paths themselves, only that they exist
+- `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)
 
-**Why no built-in allowlist?** Bypass testing of the rule layer ([writeup](research/rule-layer-security-audit.md)) showed that allowlist robustness is very limited. The built-in layer only makes **deny** claims (the sound direction); allow claims are yours.
+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).
 
 ### Self-protection (the gate guards itself — [ADR-0001](docs/adr/0001-self-protection-layer.md))
 
-The gate's own files — `config/pi-verdict.json` and the installed extension copy under `<agentDir>/extensions/` (anchored at runtime via `import.meta.url`; covers both single-file and npm-dir installs) — are **user-editable only**:
+The gate's own files — the config and the installed extension copy — are **user-editable only**: writes from inside the gate hard-deny (reads pass); your editor never passes through the gate, the sudoers/visudo precedent.
 
-- `write`/`edit` onto them → hard **deny** (realpath-normalized comparison, symlink indirection included); reads pass
-- bash/powershell commands touching them → **deny** (substring regex over literal/`~`/`$HOME`/`$PI_CODING_AGENT_DIR` spellings — honestly obfuscatable, see the backstop below)
-- **not disableable by any config**: `builtinDenyFloor: false` does not turn this off, and no user `allow` rule can override it. Rationale: user sovereignty is about the risk to *your system*, not about the integrity of the gate itself — a gate its own guarded object can switch off cannot honestly promise "risk accepted by you"
-- **tamper detection** (defense in depth): watched files are snapshotted at `session_start` and re-verified before every verdict, with differential disposal — the installed **extension copy** being changed (or any change in a headless session) is **auto-restored** from the snapshot and the session goes **fail-closed** (all tools denied) until restart; only the **config** changing in an interactive session offers a two-way select whose options state the action themselves: *Accept the new version* (re-baseline and continue — your edit survives, applies next session as usual) / *Decline* (restore the session baseline — revert + fail-closed); dismissing the dialog counts as Decline (safe side). Unconditional auto-restore would mean you can never edit the config while pi runs; warn-only would let a missed warning hand the next session to a tampered config — the rare, stern confirm is the middle path
-
-Since everything inside the gate is by definition agent-initiated, denying writes is exactly "only the user can modify" — your editor never passes through the gate. The sudoers/visudo precedent is the closest analogue.
+- **Not disableable by any config** — `builtinDenyFloor: false` and user `allow` rules cannot touch this layer
+- **Tamper detection** as the backstop: watched files are snapshotted at `session_start` and re-verified before every verdict — a changed extension copy is auto-restored and the session goes fail-closed; a changed config gets one explicit keep/restore confirm ([ADR-0001](docs/adr/0001-self-protection-layer.md) for the differential-disposal rationale)
 
 Requires pi ≥ 0.84. Works in interactive and non-interactive (`-p`/json/rpc) sessions; in non-interactive modes `ask` degrades to `deny`.
 
@@ -102,9 +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 (~1.2k lines and growing by features, still one file on purpose), and the measurement habit — every design decision in this repo is backed by shipped research.
-
-The single-file, zero-dependency shape is deliberate — the whole extension is one readable [file](extensions/auto-mode.ts), ~1.2k lines and growing with features.
+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.
 
 ## Pipeline
 
@@ -112,42 +131,28 @@ The single-file, zero-dependency shape is deliberate — the whole extension is
 tool_call
   │
   ├─ 0. Self-protection layer (ADR-0001; not disableable by any config)
-  │     ├─ write/edit/bash touching the gate's own files
-  │     │   (config/pi-verdict.json + installed extension copy) → deny
-  │     │   reads pass; user edits outside pi never pass through the gate
-  │     └─ tamper detection: re-verify watched files before every verdict;
-  │         extension copy changed / headless → auto-restore from snapshot
-  │         + fail-closed (deny all) for the rest of the session;
-  │         config changed + interactive → one keep/restore confirm
+  │     ├─ write/edit/bash touching the gate's own files → deny; reads pass
+  │     └─ tamper detection: re-verify before every verdict →
+  │         auto-restore + fail-closed, or one keep/restore confirm
   │
   ├─ 1. Rule layer (deterministic, zero latency)
-  │     ├─ built-in deny floor: bash danger regexes (full-string, capped at 8192 chars) +
-  │     │   path sensitivity S0–S5 (secrets/system/.git meta → deny;
-  │     │   dual-form matching — lexical + realpath, symlink aliases resolve)
-  │     ├─ your rules: user deny beats user allow (regex, see below)
-  │     ├─ denyPaths (ADR-0002): user-declared protected paths, tool-owned
-  │     │   normalization (~, $HOME, relative, .., symlink, case on
-  │     │   macOS/Windows) → terminal ask,
+  │     ├─ built-in deny floor: bash danger regexes + path sensitivity S0–S5
+  │     ├─ your rules: user deny beats user allow
+  │     ├─ denyPaths (ADR-0002): protected paths → terminal ask,
   │     │   before user allow; classifier sees an existence hint only
   │     └─ no built-in allowlist — every "always allow" claim is yours to make
   │
   ├─ 2. Gray zone → model classifier (defaults to session model — "self-reflection")
-  │     ├─ input: CC-style <transcript> (last 5 user messages + last 10 tool calls,
-  │     │        action under review always last) — user intent is evidence
-  │     ├─ output contract: <verdict>allow|ask|deny</verdict> prefix-anchored
-  │     ├─ existence hint when denyPaths are configured: the classifier knows
-  │     │   protected paths exist (never what they are) and judges
-  │     │   copy-then-read/archiving/indirection strictly
-  │     ├─ thinking explicitly disabled (thinkingEnabled: false) + retry 512→1024
-  │     └─ configurable via --auto-mode-model
+  │     ├─ input: CC-style <transcript> — recent user intent + tool calls,
+  │     │        action under review always last
+  │     └─ output contract: <verdict>allow|ask|deny</verdict> prefix-anchored
   │
   └─ 3. Three-state adjudication
         ├─ allow → pass
         ├─ deny  → block, reason returned to the agent
-        └─ ask   → human confirm (ctx.ui.confirm); non-interactive modes degrade to deny
+        └─ ask   → human confirm; non-interactive modes degrade to deny
 
-  [shadow cache] (observe-only, runs alongside 2/3, never changes a verdict)
-        replays a double-key LRU(128) to measure would-be hit rate
+  [shadow cache] observe-only telemetry alongside 2/3, never changes a verdict
 ```
 
 **fail-closed**: classifier exception / timeout (25s) / contract violation → deny. Never silently allow.

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,24 +22,54 @@ pi-verdict 补上这道缺失的门禁, 由模型基于上下文和你的意图
 
 ## 为什么是三态
 
-**verdict 是裁决,不是开关。** 本品类的分类器大多只输出二值 allow/block。三态有意义的地方在:`ask` 把真正含糊的动作转交人类确认(非交互会话中降级为 `deny`),「不确定」永远不会静默变成「放行」。
+**verdict 是裁决,不是开关。** 本品类的分类器大多只输出二值 allow/block。三态有意义的地方在:`ask` 把真正含糊的动作转交人类确认(非交互会话中降级为 `deny`),「不确定」永远不会静默变成「放行」——目标是安全的自动化而非最大的自动化:审批疲劳与静默危险执行都是危险。
+
+## 设计原则
+
+- **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)
 
 ## 快速开始
 
 ```bash
-# 从 npm 安装:
+# 从 npm 安装(pi):
 pi install npm:pi-verdict
 
+# 从 npm 安装(oh-my-pi / omp):
+omp plugin install npm:pi-verdict
+
 # 或直接从源码 —— 试用一次
 pi --extension ./extensions/auto-mode.ts
 
 ```
 
+### 宿主
+
+pi-verdict 同时支持 [pi](https://github.com/badlogic/pi-mono) 与 [oh-my-pi](https://github.com/can1357/oh-my-pi)(omp)——扩展按自身安装位置自锚定到所在宿主的目录树,双宿主并存的机器上跟随扩展副本自身的位置。omp 18 下分类器的模型调用经 pi-ai compat API 降级(仍然 fail-closed)。细节见 [docs/configuration.md](docs/configuration.md#host-notes-pi-and-oh-my-pi)。
+
+| | pi | omp |
+|---|---|---|
+| 安装 | `pi install npm:pi-verdict` | `omp plugin install npm: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` |
+
 - `/automode` —— 显示当前状态:开/关 + 本会话影子缓存统计
 - `/automode on`
 - `/automode off`
@@ -68,26 +98,18 @@ pi --extension ./extensions/auto-mode.ts
 ```
 
 - `allow`/`deny` 为 JS 正则数组;**`deny` 优先于 `allow`**,两者都优先于分类器
-- `denyPaths` 是你声明**受保护**的普通路径列表(非正则):任何触碰它们的工具调用——文件类工具取其路径、bash 从命令串提取路径 token——触发**终局 ask**,由你裁决(非交互会话降级 deny)。不受 `builtinDenyFloor: false` 影响
-  分类器只被告知受保护路径**存在**,路径明文永不出本机, 命中的路径**只**出现在本地确认弹窗。
-- `builtinDenyFloor: false` 可整体关闭内置危险/路径拦截(风险自担;分类器与你的规则仍在——下方自保护层永远开启)
-- `classifierModel: "provider/model-id"` 指定分类器模型(如轻量 flash 类);优先级 flag > env > config > 自省;无效值回退会话模型并一次性警告
-- spec 支持 pi 原生 `--model` 思考级别后缀:`"zai/glm-5.3-flash:low"` 将分类器思考设为 effort low(无后缀缺省 = 显式关思考)
-- `toggleShortcut` 重绑主开关快捷键(`null` 或空串禁用, 非持久化)
-- 首次运行自动生成模板 `~/.pi/agent/config/pi-verdict.json`(尊重 `PI_CODING_AGENT_DIR`)
+- `denyPaths` 是你声明**受保护**的普通路径列表:触碰触发**终局 ask** 由你裁决(非交互降级 deny);分类器只被告知路径**存在**,路径明文永不出本机
+- `builtinDenyFloor: false` 整体关闭内置危险/路径拦截(风险自担;下方自保护层永远开启)
+- `classifierModel` 指定分类器模型,如 `"zai/glm-5.3-flash:low"`(支持思考后缀;缺省 = 会话模型且显式关思考)
 
-**为什么没有内置白名单?**对规则层的绕过测试(见 [`research/rule-layer-security-audit.md`](research/rule-layer-security-audit.md))证明白名单的健壮性非常有限。因此内置层只做 **deny** 声明(方向健全),allow 声明归你。
+没有内置白名单——每一条「永远放行」声明都归你([为什么](docs/configuration.md#why-no-built-in-allowlist))。完整参考:[docs/configuration.md](docs/configuration.md)。
 
 ### 自保护(门禁守护自身——[ADR-0001](docs/adr/0001-self-protection-layer.md))
 
-门禁自身的文件——`config/pi-verdict.json` 与 `<agentDir>/extensions/` 下的扩展安装副本(运行时经 `import.meta.url` 自锚定,覆盖单文件与 npm 目录两种安装形态)——**仅用户可改**:
-
-- `write`/`edit` 触碰 → 硬 **deny**(realpath 归一化比对,含符号链接间接路径);读放行
-- bash/powershell 命令串触碰 → **deny**(字面量/`~`/`$HOME`/`$PI_CODING_AGENT_DIR` 拼写的子串正则——诚实声明:可被混淆绕过,见下方兜底)
-- **不可经任何配置关闭**:`builtinDenyFloor: false` 关不掉它,任何用户 `allow` 规则也越不过它。理由:用户主权豁免的对象是「我的系统的风险」,不是门禁自身的完整性——一个能被其守护对象关掉的门禁,无法诚实兑现「风险自担」的承诺
-- **变更检测**(纵深兜底):受保护文件在 `session_start` 快照、每次裁决前复核,处置按文件差分——**扩展副本**被改(或 headless 会话中的任何变更)→ 从快照**自动还原** + 本会话 **fail-closed**(全量拦截)直至重启;交互会话中仅**配置文件**被改 → 弹一次双选,选项文案即动作本身:*接受新版本*(重建基线、会话照常——你的编辑得以保留,照旧下一会话生效)/*拒绝*(还原会话基线:回滚 + fail-closed);关闭对话框等同拒绝(安全侧)。无条件自动还原等于「pi 运行期间你永远改不了配置」;纯警告则可能让被忽略的警告把下一会话交给被篡改的配置——罕见而郑重的一次确认是中间道路
+门禁自身的文件——配置与扩展安装副本——**仅用户可改**:门禁之内的写入一律硬 deny(读放行);你的编辑器修改不经门禁,最近的同构先例是 sudoers 必须经 visudo。
 
-门禁之内的一切写入按定义均由 agent 发发——deny 写入即等价于「仅用户可改」,你的编辑器修改不经门禁。最近的同构先例是 sudoers 必须经 visudo。
+- **不可经任何配置关闭**——`builtinDenyFloor: false` 与用户 `allow` 规则都动不了这一层
+- **变更检测**作纵深兜底:受保护文件在 `session_start` 快照、每次裁决前复核——扩展副本被改 → 自动还原 + 本会话 fail-closed;配置被改 → 一次明确的双选确认(差分处置的完整语义见 [ADR-0001](docs/adr/0001-self-protection-layer.md))
 
 需要 pi ≥ 0.84。交互与非交互(`-p`/json/rpc)会话均支持;非交互模式下 `ask` 降级为 `deny`。
 
@@ -102,9 +124,7 @@ pi --extension ./extensions/auto-mode.ts
 
 完整全景:[`research/pi-permission-landscape.md`](research/pi-permission-landscape.md) · 与最近架构亲缘的收敛分析:[`research/pi-automode-convergence.md`](research/pi-automode-convergence.md)。
 
-诚实地说:pi-automode 与 pi-verdict 在**架构上已收敛**(deny floor → 用户规则 → 分类器,fail-closed——见收敛分析)。这里仍然不同的是:分类器能说 `ask`(运行时人工介入,而非仅由规则预声明)、内置 floor 可以关(`builtinDenyFloor`——用户主权)、任何配置都关不掉的自保护层([ADR-0001](docs/adr/0001-self-protection-layer.md)——门禁完整性)、零依赖单文件(~1.2k 行,随功能增长,仍刻意单文件)、以及测量的习惯——本仓库每个设计决策都有随库研究背书。
-
-零依赖单文件形态是有意为之——整个扩展就是一个可通读的[单文件](extensions/auto-mode.ts),~1.2k 行,随功能增长。
+诚实地说:pi-automode 与 pi-verdict 在**架构上已收敛**(deny floor → 用户规则 → 分类器,fail-closed——见收敛分析)。这里仍然不同的是:分类器能说 `ask`(运行时人工介入,而非仅由规则预声明)、内置 floor 可以关(`builtinDenyFloor`——用户主权)、任何配置都关不掉的自保护层([ADR-0001](docs/adr/0001-self-protection-layer.md)——门禁完整性)、零依赖的[可通读单文件](extensions/auto-mode.ts)(仍刻意单文件)、以及测量的习惯——本仓库每个设计决策都有随库研究背书。
 
 ## 管线
 
@@ -112,39 +132,28 @@ pi --extension ./extensions/auto-mode.ts
 tool_call
   │
   ├─ 0. 自保护层(ADR-0001;不可经任何配置关闭)
-  │     ├─ write/edit/bash 触碰门禁自身文件
-  │     │   (config/pi-verdict.json + 扩展安装副本)→ deny
-  │     │   读放行;用户在 pi 之外的编辑不经门禁
-  │     └─ 变更检测:每次裁决前复核受保护文件;
-  │         扩展副本被改 / headless → 从会话快照自动还原
-  │         + 本会话 fail-closed(全量拦截);
-  │         仅配置被改且有 UI → 一次保留/还原确认
+  │     ├─ write/edit/bash 触碰门禁自身文件 → deny;读放行
+  │     └─ 变更检测:每次裁决前复核 →
+  │         自动还原 + fail-closed,或一次保留/还原确认
   │
   ├─ 1. 规则层(确定性,零延迟)
-  │     ├─ 内置 deny floor:bash 危险正则(完整命令串,截断上限 8192 字符)+ 路径敏感度 S0–S5
-  │     │   (双形匹配 —— 词法 + realpath,符号链接别名会被解析)
-  │     ├─ 用户规则:deny 优先于 allow(正则,见下)
-  │     ├─ denyPaths(ADR-0002):用户声明的受保护路径,工具负责归一化
-  │     │   (~、$HOME、相对、..、symlink、macOS/Windows 大小写)→ 终局 ask,先于用户 allow;
+  │     ├─ 内置 deny floor:bash 危险正则 + 路径敏感度 S0–S5
+  │     ├─ 用户规则:deny 优先于 allow
+  │     ├─ denyPaths(ADR-0002):受保护路径 → 终局 ask,先于用户 allow;
   │     │   分类器只见存在性话术
   │     └─ 无内置白名单 —— 「永远放行」的声明由你自己做
   │
   ├─ 2. 灰区 → 模型分类器(默认继承会话模型 —— "自省")
-  │     ├─ 输入:CC 风格 <transcript>(最近 5 条用户消息 + 最近 10 次工具调用,
-  │     │        待审动作固定在末尾)—— 用户意图是证据
-  │     ├─ 输出契约:<verdict>allow|ask|deny</verdict> 前缀锚定
-  │     ├─ 配置了 denyPaths 时注入存在性话术:分类器知道受保护路径存在
-  │     │   (永不知其内容),对先拷贝再读取/打包/间接引用从紧裁决
-  │     ├─ 显式关思考(thinkingEnabled: false)+ 两档重试 512→1024
-  │     └─ 可用 --auto-mode-model 配置
+  │     ├─ 输入:CC 风格 <transcript> —— 近期用户意图 + 工具调用,
+  │     │        待审动作固定在末尾
+  │     └─ 输出契约:<verdict>allow|ask|deny</verdict> 前缀锚定
   │
   └─ 3. 三态裁决
         ├─ allow → 放行
         ├─ deny  → 拦截,理由回传 agent
-        └─ ask   → 人工确认(ctx.ui.confirm);非交互模式降级为 deny
+        └─ ask   → 人工确认;非交互模式降级为 deny
 
-  [影子缓存](observe-only,与 2/3 并行,永不改变裁决)
-        回放双键 LRU(128)测量 would-be 命中率
+  [影子缓存] observe-only 遥测,与 2/3 并行,永不改变裁决
 ```
 
 **fail-closed**:分类器异常 / 超时(25s)/ 输出违反契约 → 拦截,绝不静默放行。

package/extensions/auto-mode.ts

@@ -204,8 +204,46 @@ interface UserRules {
 
 const EMPTY_RULES: UserRules = { allow: [], deny: [], denyPaths: [], builtinDenyFloor: true, classifierModel: null, toggleShortcut: DEFAULT_TOGGLE_SHORTCUT };
 
+/** This module's own file location (import.meta.url resolved; null = unresolvable). */
+const OWN_FILE_PATH: string | null = (() => {
+	try {
+		return fileURLToPath(import.meta.url);
+	} catch {
+		return 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/…
+ *      anchors to <home>/<dot-dir>/agent. Covers the pi forms
+ *      (~/.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
+ *      unanchored location.
+ * Both the lexical and the realpath form of ownFile are tried (symlinked
+ * agent trees, macOS firmlink homes).
+ */
+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 m = f.match(anchor);
+			if (m) return path.join(home, m[2], "agent");
+		}
+	}
+	return path.join(home, ".pi", "agent");
+}
+
 function agentDirPath(): string {
-	return process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent");
+	return resolveAgentDir(OWN_FILE_PATH, os.homedir(), process.env.PI_CODING_AGENT_DIR);
 }
 
 function userConfigPath(): string {
@@ -298,7 +336,7 @@ function expandHome(p: string): string {
 // the occasional false positive fails toward deny (safe direction).
 const S0_SECRET = [
 	/\.ssh(\/|$)/i, /\.aws(\/|$)/i, /\.gnupg(\/|$)/i, /(^|\/)\.env(\.|$)/i, /credentials?(\.|\/|$)/i,
-	/(^|\/)id_rsa/i, /\.pem$/i, /_history$/i, /\.config\/gh(\/|$)/i, /\.pi\/agent\/auth\.json$/i,
+	/(^|\/)id_rsa/i, /\.pem$/i, /_history$/i, /\.config\/gh(\/|$)/i, /\.(?:pi|omp)\/agent\/auth\.json$/i,
 	// V8(安全审计):常见明文凭证文件补全
 	/(^|\/)\.netrc$/i, /(^|\/)\.npmrc$/i, /(^|\/)\.pypirc$/i, /(^|\/)\.envrc$/i, /(^|\/)\.vault-token$/i,
 	/\.kube(\/|$)/i, /\.docker\/config\.json$/i, /\.gem\/credentials$/i,
@@ -469,8 +507,9 @@ function hitDenyPaths(toolName: string, input: Record<string, unknown>, cwd: str
 // 门禁自身的完整性不受任何配置豁免:builtinDenyFloor:false 只关危险正则与路径
 // 敏感度,关不掉本层;用户 allow 规则亦不可越过。保护对象:
 //   - <agentDir>/config/pi-verdict.json(用户规则 = 门禁的判定输入)
-//   - 本扩展的安装副本(<agentDir>/extensions/ 下;自锚定 import.meta.url,
-//     覆盖单文件与 npm 包目录两种安装形态;dev checkout 不在此列)
+//   - 本扩展的安装副本(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 变体,可被混淆
@@ -517,8 +556,10 @@ function escapeRegExp(s: string): string {
 /**
  * 构建受保护集合。
  * ownFile:本模块文件路径(import.meta.url 解析;null = 不可解析,仅保护配置)。
- * 仅当 ownFile 位于 <agentDir>/extensions/ 之下才视为安装副本加以保护:
- * dev checkout(cwd 内源码)不保护——项目内开发写入是合法日常(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>();
@@ -572,14 +613,32 @@ 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;
-		const extRoots = new Set([path.join(agentDir, "extensions"), tryRealpath(path.join(agentDir, "extensions"))]);
+		// 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([agentDir, tryRealpath(agentDir)]);
+		const configRootBases = new Set([...agentBases].map((b) => path.dirname(b)));
+		for (const seg of [["extensions"], ["plugins", "node_modules"]]) {
+			const bases = seg.length === 2 ? new Set([...agentBases, ...configRootBases]) : agentBases;
+			for (const base of bases) {
+				const root = path.join(base, ...seg);
+				extRoots.add(root);
+				extRoots.add(tryRealpath(root));
+			}
+		}
 		const ownForms = new Set([ownFile, tryRealpath(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]);
+				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 pathForms(target)) {
 					(singleFile ? exact : prefixes).add(f);
 					extTargets.add(f);
@@ -840,9 +899,60 @@ const CLASSIFIER_TIMEOUT_MS = 25_000; // 本网关 CC 分类器分布 p90=19.8s(
 const CLASSIFIER_MAX_TOKENS = 512;
 const CLASSIFIER_RETRY_MAX_TOKENS = 1024; // 防御重试档:覆盖无视 reasoning:off 或轻思考仍超预算的模型
 
+/**
+ * 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
+ * a functionally identical `complete`. Options pass through verbatim on both
+ * hosts (thinkingEnabled/effort/cacheRetention included — see
+ * research/thinking-param-blackhole.md for why API-native fields matter).
+ */
+export type CompletionFn = (
+	model: NonNullable<ExtensionContext["model"]>,
+	context: { systemPrompt?: string; messages: unknown[] },
+	options?: Record<string, unknown>,
+) => Promise<{ content: Array<{ type: string; text: string }>; stopReason?: string }>;
+
+type CompatLoader = () => Promise<{ complete: CompletionFn }>;
+
+/**
+ * Bind the host runtime's completion capability (#35): registry.complete when
+ * present (pi), else the pi-ai compat module (omp 18). The literal dynamic
+ * import specifier must stay inline — omp's legacy compat rewrites exactly
+ * this literal to its bundled pi-ai; the ./compat subpath also exists on pi,
+ * so resolution is safe on both hosts. The loader promise is cached; any
+ * rejection propagates to the caller (the classifier's fail-closed path owns it).
+ */
+export function bindCompletion(
+	registry: { complete?: unknown },
+	compatLoader: CompatLoader = () => import("@earendil-works/pi-ai/compat") as Promise<{ complete: CompletionFn }>,
+): CompletionFn {
+	if (typeof registry.complete === "function") {
+		const complete = registry.complete as CompletionFn;
+		return (m, c, o) => complete.call(registry, m, c, o);
+	}
+	let compat: Promise<{ complete: CompletionFn }> | undefined;
+	return async (m, c, o) => {
+		compat ??= compatLoader();
+		const { complete } = await compat;
+		return complete(m, c, o);
+	};
+}
+
+// Session-lifetime cache keyed by registry instance: resolve once per registry.
+const completionCache = new WeakMap<object, CompletionFn>();
+function completionFor(registry: { complete?: unknown }, compatLoader?: CompatLoader): CompletionFn {
+	let fn = completionCache.get(registry);
+	if (!fn) {
+		fn = bindCompletion(registry, compatLoader);
+		completionCache.set(registry, fn);
+	}
+	return fn;
+}
+
 /** 单次分类器调用:显式 reasoning:"off"(见下方注释),失败返回错误串而非抛出 */
 async function callClassifierOnce(
 	ctx: ExtensionContext,
+	complete: CompletionFn,
 	model: NonNullable<ExtensionContext["model"]>,
 	userMessage: string,
 	maxTokens: number,
@@ -852,7 +962,7 @@ async function callClassifierOnce(
 	const signals = [AbortSignal.timeout(CLASSIFIER_TIMEOUT_MS)];
 	if (ctx.signal) signals.push(ctx.signal);
 	try {
-		const response = await ctx.modelRegistry.complete(
+		const response = await complete(
 			model,
 			{
 				systemPrompt,
@@ -862,14 +972,25 @@ async function callClassifierOnce(
 				signal: AbortSignal.any(signals),
 				maxTokens,
 				temperature: 0,
-				// 思考参数必须用 API 原生字段(thinkingEnabled/effort),而非 reasoning
-				// (API 层 complete() 无此字段,宽类型索引签名静默放行后运行时丢弃——见
-				// research/thinking-param-blackhole.md)。
-				// 缺省 off = 显式关思考(实证送达 thinking:{"type":"disabled"},GLM 降为
-				// effort low 轻思考);后缀级别经 adaptive effort 送达(minimal→low 映射)。
+				// 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 }
-					: { thinkingEnabled: true, effort: thinking === "minimal" ? ("low" as const) : thinking }),
+					? { thinkingEnabled: false, disableReasoning: true }
+					: {
+							thinkingEnabled: true,
+							effort: thinking === "minimal" ? ("low" as const) : thinking,
+							reasoning: thinking === "minimal" ? ("low" as const) : thinking,
+						}),
 				cacheRetention: "short",
 				sessionId: ctx.sessionManager.getSessionId(),
 			},
@@ -878,7 +999,7 @@ async function callClassifierOnce(
 			.filter((b) => b.type === "text")
 			.map((b) => b.text)
 			.join("");
-		return { ok: true, text, stopReason: response.stopReason };
+		return { ok: true, text, stopReason: response.stopReason ?? "unknown" };
 	} catch (err) {
 		return { ok: false, error: err instanceof Error ? err.message : String(err) };
 	}
@@ -892,6 +1013,7 @@ async function callClassifierOnce(
  */
 async function classifyWithModel(
 	ctx: ExtensionContext,
+	complete: CompletionFn,
 	model: NonNullable<ExtensionContext["model"]>,
 	actionLine: string,
 	thinking: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" = "off",
@@ -904,7 +1026,7 @@ async function classifyWithModel(
 	const failures: string[] = [];
 	for (const [n, maxTokens] of attempts) {
 		if (ctx.signal?.aborted) break; // 用户已取消,不再重试
-		const r = await callClassifierOnce(ctx, model, userMessage, maxTokens, thinking, systemPrompt);
+		const r = await callClassifierOnce(ctx, 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") {
@@ -1044,7 +1166,12 @@ function shadowTag(probe: ShadowProbe): string {
 // 扩展主体
 // ============================================================================
 
-export default function autoMode(pi: ExtensionAPI) {
+/** Optional dependency injection for tests (#35): fake the compat fallback loader. */
+export interface AutoModeDeps {
+	compatLoader?: CompatLoader;
+}
+
+export default function autoMode(pi: ExtensionAPI, deps: AutoModeDeps = {}) {
 	pi.registerFlag("auto-mode", { description: "Enable Auto Mode (rules + model classifier gating for tool calls)", type: "boolean", default: true });
 	pi.registerFlag("auto-mode-model", { description: "Classifier model as provider/id[:thinking] (pi --model syntax; default: inherit session model)", type: "string" });
 	pi.registerFlag("auto-mode-debug", { description: "Notify every verdict incl. allows, with shadow-cache annotation", type: "boolean", default: false });
@@ -1063,15 +1190,9 @@ export default function autoMode(pi: ExtensionAPI) {
 		return denyPathBases;
 	};
 
-	// 自保护层(ADR-0001):受保护集合自锚定 + 变更检测基线(会话内存态)
-	const ownFilePath = (() => {
-		try {
-			return fileURLToPath(import.meta.url);
-		} catch {
-			return null;
-		}
-	})();
-	const prot = buildProtectedSet(agentDirPath(), ownFilePath);
+	// 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;
 
@@ -1303,7 +1424,7 @@ export default function autoMode(pi: ExtensionAPI) {
 		const ctxKey = shadowContextKey(ctx);
 		const probe = shadow.probe(cmdKey, ctxKey);
 
-		const outcome = await classifyWithModel(ctx, model, action, classifierThinking, userRules.denyPaths.length > 0);
+		const outcome = await classifyWithModel(ctx, completionFor(ctx.modelRegistry, deps.compatLoader), model, action, classifierThinking, userRules.denyPaths.length > 0);
 
 		// 影子回记:真实模型 allow/deny 入缓存;ask 与 fail-closed 不入(#5 定案);
 		// 命中且本次为可缓存裁决时,对比反事实一致性

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-verdict",
-	"version": "0.5.2",
+	"version": "0.6.1",
 	"description": "A minimal permission gate for Pi in the style of Claude Code's auto mode",
 	"author": "Jesset (https://github.com/jesset)",
 	"type": "module",