@dsh-cc/permission-rules 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/interaction/permission-rules/README.md
+README.md: 61fa514bd8c7b7a45c9c7f2502c173fcb83a9a2a
+README.zh.md: cd5e4eed56f8e29aa72e5ee811b9a304b6a04031

package/README.md

@@ -0,0 +1,86 @@
+# @dsh-cc/permission-rules
+
+English | [中文](README.zh.md)
+
+Claude Code-compatible permission-rule engine. Parses `ToolName` and `ToolName(content)` rules, folds a mode-aware decision on the `tools/pre-execute` waterfall, and enforces bypass-immune content rules through the monotonic `guard()` layer so neither a mode switch nor `bypassPermissions` can override them. Rules fail loud at load; settings hot-reload by rebuilding merged state and re-registering guards.
+
+## Rule syntax
+
+A rule is `ToolName` (whole tool) or `ToolName(content)` (content-scoped). `content` may escape `(`/`)`/`\` with a backslash, use `*` as a wildcard, or end in `:*` to declare a prefix rule.
+
+| Rule | Meaning |
+|---|---|
+| `Bash` | whole-tool rule for every `Bash` call |
+| `Bash(npm install)` | prefix rule: any command starting with `npm install` |
+| `Bash(npm publish:*)` | prefix rule on the stem `npm publish:` |
+| `Edit(foo/*.json)` | wildcard: commands/paths matching `foo/*.json` (a `*` matches any run) |
+| `Bash(python -c "print\(1\)")` | literal parens inside content |
+
+Malformed rules (unclosed paren, content after the closing paren, content with no tool name) throw a `TypeError` at load — fail loud. `escapeRuleContent`/`unescapeRuleContent` round-trip content safely (`\` first, then parens).
+
+## Evaluation order
+
+The plugin registers a `tools/pre-execute` listener and folds one decision per call:
+
+1. **Bypass-immune** content rules (e.g. `.git` internals, shell-config paths) always deny — registered as monotonic **guards**, never overridable by a mode switch or `bypassPermissions`.
+2. **Risk classifier** (when `classifierEnabled`, default on): catastrophic shell commands (`rm -rf /`, `sudo`, `dd of=/dev`, `kill -9 1`, piping curl/wget into sh, redirecting into system paths) are a hard **deny in every mode**; writes to protected files (`.bashrc`, `.ssh/**`, credentials) are also hard denies; writes that escape the working directory scope are **ask** outside `bypassPermissions` (allowed under it).
+3. **whole-tool deny** → deny.
+4. **whole-tool ask** → ask (a sandboxed, confining `Bash` is exempt and allowed instead when `exemptSandboxedBashFromToolAsk` is set).
+5. **content-level allow/deny/ask** rules by source priority (highest source first; first rule to match decides).
+6. **mode** short-circuits: `bypassPermissions` allows everything (unless `disableBypassPermissionsMode`); `acceptEdits` auto-allows file-edit tools; `plan` auto-allows read-only tools. `auto` is not an evaluate short-circuit — it evaluates identically to `default`, with the risk classifier proxying asks at the plugin layer.
+7. **whole-tool allow** is the coarse default for that tool when nothing more specific matched.
+8. **no match** → passthrough to downstream listeners (ultimately the approval seam), which may still `ask`.
+9. **plan wrap**: leftover `ask`/`passthrough` on a non-read-only call becomes a deny with `plan mode is read-only; submit via exit_plan_mode`. Matching allow/deny rules still stand.
+
+## Config
+
+```ts
+import PermissionRules from '@dsh-cc/permission-rules'
+
+await ctx.plugin(PermissionRules, {
+  rules: {
+    deny: ['Bash(rm -rf)', 'Edit(.git*)'],
+    bypassImmune: ['Edit(~/.bashrc)', 'Edit(~/.zshrc)'],
+  },
+  bashToolName: 'Bash',           // default
+  fileEditTools: ['edit'],        // auto-allowed under acceptEdits
+  readOnlyTools: ['read'],        // auto-allowed under plan
+  exemptSandboxedBashFromToolAsk: false,
+  defaultMode: 'default',
+  classifierEnabled: true,        // risk-classifier escalation stage
+})
+```
+
+All fields are optional; the service schema applies the illustrated defaults. Rule strings are parsed with source `config`.
+
+## Settings and hot reload
+
+When `ctx.settings` is mounted, the plugin registers the `permissions` namespace (`permissions.allow` / `permissions.deny` / `permissions.ask` / `permissions.defaultMode`, plus `additionalDirectories` / `protectedFiles` / `dangerousPatterns` feeding the risk classifier, and the optional `autoMode` section — `autoMode.soft_deny` prose rules (with `$defaults` expansion) and `autoMode.classifier` (`enabled` / `route` / `timeoutMs` / `cacheMaxEntries`) arming the opt-in LLM risk-classifier stage for `auto` mode; an absent `autoMode` key stays absent, so the stage remains disarmed). Settings rules carry the `settingsSource` label (default `userSettings`) and merge with Config `rules` by source priority — settings rules win. A stored change re-runs the merge and re-registers guards immediately (hot reload); a malformed settings rule fails loud at the settings boundary. When `ctx.settings` is absent, only the Config `rules` are in force (the classifier uses its curated defaults).
+
+## Sources and modes
+
+Every rule carries a `PermissionRuleSource` (`session` > `cliArg` > `policySettings` > `flagSettings` > `localSettings` > `projectSettings` > `userSettings` > `config`) used for content-rule priority. The engine resolves the effective mode at call time: plan activation (from `@deepseek-ai/dsh-plan-mode`) overlays first, then the session's recorded `permission/mode` override (`foldPermissionMode`), falling back to `defaultMode`.
+
+Modes are **durable** — `setMode(agent, mode)` appends a last-wins `permission/mode` session event (registered into `KNOWN_SESSION_EVENT_TYPES` at plugin load so persistence resumes it). `plan` is owned by plan-mode and throws here. Entering `bypassPermissions` pins the session sandbox to `danger-full-access` and records `resumeSandbox`; leaving restores the recorded (or `workspace-write` fallback) confinement. Under `auto`, the risk classifier proxies every `ask`: classifier-LOW calls auto-allow, classifier-MEDIUM still asks. When the LLM classifier stage is armed, read-only tool calls are exempt — they never reach the model (zero added latency on read traffic). Verdict parsing is strict and fail-closed: a malformed model output yields the constant reason `classifier output unparseable` (model output is never shown; audit records are digest-only). A per-route consecutive-failure circuit breaker (threshold 3, keyed `provider/model`) opens the stage for a failing lane — no further classifier calls on that route, one warn per process, one `breaker` audit event per session; `rebuild()` (a settings change) resets the breaker state and re-arms.
+
+## Switching modes
+
+`permissionRules.setMode(agent, mode)` switches durably (see above); the `/permissions <mode>` command (in `@dsh-cc/command-permissions`) drives it for `default | acceptEdits | plan | auto | bypassPermissions`. A human-facing notice is injected into the session's model transcript on each switch.
+
+## Pure exports for host UI
+
+- `parseRuleString(rule)`, `parseRule(rule, behavior, source)`, `escapeRuleContent`/`unescapeRuleContent` — parse rules to `PermissionRule`.
+- `evaluatePermission(input)` — fold a `PermissionDecision` for a call (`allow` / `deny` / `ask` / `passthrough`) given tool, subject, rule set, mode, and exemption flags. Use it to preview what a rule hits without mounting the plugin.
+- `mergeRuleSets(...sets)` — merge rule sets by source priority.
+- `foldPermissionMode(events)`, `foldResumeSandbox(events)`, `setPermissionMode(session, mode, resumeSandbox?)` — read/write the durable `permission/mode` override. `setPermissionMode` rejects `plan` and unknown modes; other plugins can fold a session's recorded mode via `foldPermissionMode`.
+- `assessBashCommand(command, patterns?)` — risk-classify a shell command (`LOW`/`HIGH`).
+- `assessFilePath(filePath, opts)` — risk-classify a file write (`LOW`/`MEDIUM`/`HIGH`).
+- `PERMISSION_MODES`, `SOURCE_PRIORITY` — closed vocabularies.
+
+Rule parsing and evaluation are browser-safe (pure string logic), so the type/parser/evaluate modules import cleanly into UI previews.
+
+## Invariant companion
+
+`@dsh-cc/permission-rules/invariant` validates `permission/mode` session events at the session boundary: `mode` must be switchable (never `plan`), and `resumeSandbox` — when present — must be a known sandbox mode (`read-only` | `workspace-write` | `danger-full-access`).
+
+See the [Agent Note](../../../.agents/notes/implemented/feature/2026-08-14-cc-permission-rules.md).

package/README.zh.md

@@ -0,0 +1,86 @@
+# @dsh-cc/permission-rules
+
+[English](README.md) | 中文
+
+Claude Code 兼容的权限规则引擎。解析 `ToolName` 与 `ToolName(content)` 规则，在 `tools/pre-execute` waterfall 上收敛出感知模式的判定，并通过单调的 `guard()` 层强制执行 bypass-immune 内容规则——任何模式切换或 `bypassPermissions` 都无法翻盘。规则在加载期 fail loud；settings 通过重建合并状态并重注册 guard 实现热更新。
+
+## 规则语法
+
+规则形如 `ToolName`（整工具）或 `ToolName(content)`（内容级）。`content` 可用反斜杠转义 `(`/`)`/`\`，可用 `*` 作为通配符，也可用 `:*` 结尾声明前缀规则。
+
+| 规则 | 含义 |
+|---|---|
+| `Bash` | 覆盖所有 `Bash` 调用的整工具规则 |
+| `Bash(npm install)` | 前缀规则：任何以 `npm install` 开头的命令 |
+| `Bash(npm publish:*)` | 对主干 `npm publish:` 的前缀规则 |
+| `Edit(foo/*.json)` | 通配符：匹配 `foo/*.json` 的命令/路径（`*` 匹配任意片段） |
+| `Bash(python -c "print\(1\)")` | 内容中的字面括号 |
+
+畸形规则（括号未闭合、结束括号后有内容、只有内容没有工具名）在加载期抛出 `TypeError`——fail loud。`escapeRuleContent`/`unescapeRuleContent` 可安全往返内容（先 `\`，再括号）。
+
+## 评估顺序
+
+插件注册一个 `tools/pre-execute` 监听器，为每次调用收敛一个判定：
+
+1. **Bypass-immune** 内容规则（例如 `.git` 内部、shell 配置文件路径）始终 deny——注册为单调 **guard**，模式切换或 `bypassPermissions` 都不能覆盖。
+2. **风险分类器**（`classifierEnabled` 开启时，默认开）：灾难性 shell 命令（`rm -rf /`、`sudo`、`dd of=/dev`、`kill -9 1`、将 curl/wget 管道接入 sh、重定向到系统路径）在所有模式下**硬 deny**；写入受保护文件（`.bashrc`、`.ssh/**`、凭据）同样硬 deny；写文件逃逸出工作目录作用域时在 `bypassPermissions` 之外 **ask**（在它之下放行）。
+3. **整工具 deny** → deny。
+4. **整工具 ask** → ask（当设置了 `exemptSandboxedBashFromToolAsk` 时，被沙箱限制的 `Bash` 豁免并直接 allow）。
+5. **内容级 allow/deny/ask** 规则按来源优先级评估（最高优先级先；首个命中规则决定）。
+6. **模式**短路：`bypassPermissions` 放行一切（除非 `disableBypassPermissionsMode`）；`acceptEdits` 自动放行文件编辑工具；`plan` 自动放行只读工具。`auto` 不是 evaluate 短路——它与 `default` 评估一致，审批由插件层的风险分类器代理。
+7. **整工具 allow** 是该工具的粗略默认——没有更具体的规则命中时放行。
+8. **无命中** → passthrough 给下游监听器（最终到审批缝），后者仍可能 `ask`。
+9. **plan 收口**：非只读调用上残留的 `ask`/`passthrough` 变成 deny，理由是 `plan mode is read-only; submit via exit_plan_mode`。命中的 allow/deny 规则仍然生效。
+
+## 配置
+
+```ts
+import PermissionRules from '@dsh-cc/permission-rules'
+
+await ctx.plugin(PermissionRules, {
+  rules: {
+    deny: ['Bash(rm -rf)', 'Edit(.git*)'],
+    bypassImmune: ['Edit(~/.bashrc)', 'Edit(~/.zshrc)'],
+  },
+  bashToolName: 'Bash',           // default
+  fileEditTools: ['edit'],        // auto-allowed under acceptEdits
+  readOnlyTools: ['read'],        // auto-allowed under plan
+  exemptSandboxedBashFromToolAsk: false,
+  defaultMode: 'default',
+  classifierEnabled: true,        // 风险分类器升级阶段
+})
+```
+
+所有字段可选；服务 schema 应用图示默认值。规则字符串以 `config` 来源解析。
+
+## settings 与热更新
+
+当 `ctx.settings` 挂载时，插件注册 `permissions` 命名空间（`permissions.allow` / `permissions.deny` / `permissions.ask` / `permissions.defaultMode`，另加供风险分类器使用的 `additionalDirectories` / `protectedFiles` / `dangerousPatterns`，以及可选的 `autoMode` 小节——`autoMode.soft_deny` 文字规则（支持 `$defaults` 展开）与 `autoMode.classifier`（`enabled` / `route` / `timeoutMs` / `cacheMaxEntries`）共同驱动 `auto` 模式下可选择性开启的 LLM 风险分类器阶段；`autoMode` 键缺席即保持缺席，该阶段保持解除武装）。settings 规则携带 `settingsSource` 标签（默认 `userSettings`），并按来源优先级与 Config `rules` 合并——settings 规则优先。存储变更会立即重跑合并并重注册 guard（热更新）；畸形 settings 规则在 settings 边界 fail loud。当 `ctx.settings` 缺席时，仅 Config `rules` 生效（分类器使用其精选默认值）。
+
+## 来源与模式
+
+每条规则携带 `PermissionRuleSource`（`session` > `cliArg` > `policySettings` > `flagSettings` > `localSettings` > `projectSettings` > `userSettings` > `config`），用于内容规则的优先级。引擎在调用时解析生效模式：plan 激活（来自 `@deepseek-ai/dsh-plan-mode`）最先覆盖，然后是会话记录的 `permission/mode` 覆盖（`foldPermissionMode`），否则回退到 `defaultMode`。
+
+模式是**持久的**——`setMode(agent, mode)` 追加一条 last-wins 的 `permission/mode` 会话事件（插件加载时注册进 `KNOWN_SESSION_EVENT_TYPES`，持久化可恢复它）。`plan` 归 plan-mode 所有，在这里会抛错。进入 `bypassPermissions` 会把会话沙箱钉到 `danger-full-access` 并记录 `resumeSandbox`；离开时恢复记录（或回退 `workspace-write`）的约束。在 `auto` 下，风险分类器代理每次 `ask`：LOW 风险调用自动放行，MEDIUM 风险仍会询问。LLM 分类器阶段武装时，只读工具调用豁免——完全不经过模型（读流量零额外延迟）。判定解析保持严格并 fail-closed：模型输出畸形时返回常量原因 `classifier output unparseable`（模型输出永不展示；审计记录只含摘要）。按路由的连续失败熔断器（阈值 3，按 `provider/model` 键控）会为故障车道打开断路——该路由不再调用分类器，每进程一次 warn、每会话一条 `breaker` 审计事件；`rebuild()`（设置变更）重置熔断状态并重新武装。
+
+## 切换模式
+
+`permissionRules.setMode(agent, mode)` 持久切换（见上）；`/permissions <mode>` 命令（在 `@dsh-cc/command-permissions`）为 `default | acceptEdits | plan | auto | bypassPermissions` 驱动它。每次切换都会向会话的模型转录注入一条面向人的提示。
+
+## 供宿主 UI 使用的纯导出
+
+- `parseRuleString(rule)`、`parseRule(rule, behavior, source)`、`escapeRuleContent`/`unescapeRuleContent`——解析规则为 `PermissionRule`。
+- `evaluatePermission(input)`——为一次调用收敛 `PermissionDecision`（`allow` / `deny` / `ask` / `passthrough`），给定工具、subject、规则集、模式与豁免标志。无需挂载插件即可预览某规则会命中什么。
+- `mergeRuleSets(...sets)`——按来源优先级合并规则集。
+- `foldPermissionMode(events)`、`foldResumeSandbox(events)`、`setPermissionMode(session, mode, resumeSandbox?)`——读写持久的 `permission/mode` 覆盖。`setPermissionMode` 拒绝 `plan` 与未知模式；其他插件可用 `foldPermissionMode` 折叠某会话的记录模式。
+- `assessBashCommand(command, patterns?)`——对 shell 命令做风险分级（`LOW`/`HIGH`）。
+- `assessFilePath(filePath, opts)`——对文件写入做风险分级（`LOW`/`MEDIUM`/`HIGH`）。
+- `PERMISSION_MODES`、`SOURCE_PRIORITY`——封闭词汇表。
+
+规则解析与评估是浏览器安全的（纯字符串逻辑），因此类型/解析/评估模块可干净地导入 UI 预览。
+
+## Invariant 伴生插件
+
+`@dsh-cc/permission-rules/invariant` 在会话边界校验 `permission/mode` 会话事件：`mode` 必须是可切换的（绝不能是 `plan`），且 `resumeSandbox`——若存在——必须是已知沙箱模式（`read-only` | `workspace-write` | `danger-full-access`）。
+
+参见 [Agent Note](../../../.agents/notes/implemented/feature/2026-08-14-cc-permission-rules.md)。

package/lib/approval-listener.d.ts

@@ -0,0 +1,50 @@
+/**
+ * WS3 approval-seam listener: auto-approves sandbox escalations in `auto`
+ * mode when the operation is attributable to the session workspace.
+ *
+ * WS0 verified that sandbox escalation prompts travel a separate
+ * `approval/request` seam, independent of permission modes — so a mode-based
+ * override cannot suppress them. This listener registers on that seam's
+ * waterfall (before any UI listener) and resolves the request itself when
+ * ALL of the following hold:
+ *
+ * 1. the request carries a reason identifying it as a sandbox escalation
+ *    ({@link isSandboxEscalation});
+ * 2. the effective permission mode for the requesting session is `auto`;
+ * 3. the session has a resolvable workspace root (the per-call sandbox policy
+ *    is derived from the session cwd — WS3 — so a known workspace root is
+ *    exactly the boundary the escalation was evaluated against).
+ *
+ * Otherwise the request falls through to `next()` and the normal approval
+ * flow proceeds. Every auto-approval is audit-logged to the session log as a
+ * `permission/session-allow` record with `scope: 'sandbox-auto'`.
+ *
+ * @module @dsh-cc/permission-rules/approval-listener
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ApprovalOutcome, ApprovalRequest } from '@deepseek-ai/dsh-user-approval';
+import type { PermissionMode } from './types.ts';
+/** Seams the listener reads off its configuring context; all injectable for tests. */
+export interface SandboxApprovalListenerConfig {
+    /** The effective permission mode for the requesting session. */
+    modeOf(agent: Agent): PermissionMode;
+    /**
+     * The session's workspace root, or undefined when none is known. An
+     * undefined workspace root can never be auto-approved (the listener cannot
+     * verify the operation is in scope) and falls through to the next provider.
+     */
+    workspaceOf(agent: Agent): string | undefined;
+}
+/**
+ * Whether an approval request's reason identifies a sandbox escalation.
+ * Case-insensitive substring match on `sandbox` — the escalation reasons are
+ * produced by the sandbox runtime and always name the mechanism.
+ */
+export declare function isSandboxEscalation(reason: string | undefined): boolean;
+/**
+ * Build the `approval/request` waterfall listener. Register the returned
+ * listener ahead of the UI provider so an eligible sandbox escalation never
+ * reaches the modal queue.
+ */
+export declare function createSandboxApprovalListener(config: SandboxApprovalListenerConfig): (req: ApprovalRequest, next: () => Promise<ApprovalOutcome>) => Promise<ApprovalOutcome>;
+//# sourceMappingURL=approval-listener.d.ts.map

package/lib/approval-listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-listener.d.ts","sourceRoot":"","sources":["../src/approval-listener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAA;AAEtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD,sFAAsF;AACtF,MAAM,WAAW,6BAA6B;IAC5C,gEAAgE;IAChE,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,cAAc,CAAA;IACpC;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,CAAA;CAC9C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEvE;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,6BAA6B,GAAG,CACpF,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,KACjC,OAAO,CAAC,eAAe,CAAC,CAe5B"}

package/lib/approval-listener.js

@@ -0,0 +1,58 @@
+/**
+ * WS3 approval-seam listener: auto-approves sandbox escalations in `auto`
+ * mode when the operation is attributable to the session workspace.
+ *
+ * WS0 verified that sandbox escalation prompts travel a separate
+ * `approval/request` seam, independent of permission modes — so a mode-based
+ * override cannot suppress them. This listener registers on that seam's
+ * waterfall (before any UI listener) and resolves the request itself when
+ * ALL of the following hold:
+ *
+ * 1. the request carries a reason identifying it as a sandbox escalation
+ *    ({@link isSandboxEscalation});
+ * 2. the effective permission mode for the requesting session is `auto`;
+ * 3. the session has a resolvable workspace root (the per-call sandbox policy
+ *    is derived from the session cwd — WS3 — so a known workspace root is
+ *    exactly the boundary the escalation was evaluated against).
+ *
+ * Otherwise the request falls through to `next()` and the normal approval
+ * flow proceeds. Every auto-approval is audit-logged to the session log as a
+ * `permission/session-allow` record with `scope: 'sandbox-auto'`.
+ *
+ * @module @dsh-cc/permission-rules/approval-listener
+ */
+import { appendSessionAllow } from "./session-allowlist.js";
+/**
+ * Whether an approval request's reason identifies a sandbox escalation.
+ * Case-insensitive substring match on `sandbox` — the escalation reasons are
+ * produced by the sandbox runtime and always name the mechanism.
+ */
+export function isSandboxEscalation(reason) {
+    return reason !== undefined && /sandbox/i.test(reason);
+}
+/**
+ * Build the `approval/request` waterfall listener. Register the returned
+ * listener ahead of the UI provider so an eligible sandbox escalation never
+ * reaches the modal queue.
+ */
+export function createSandboxApprovalListener(config) {
+    return async (req, next) => {
+        if (!isSandboxEscalation(req.reason))
+            return next();
+        const agent = req.agent;
+        if (agent === undefined)
+            return next();
+        if (config.modeOf(agent) !== 'auto')
+            return next();
+        if (config.workspaceOf(agent) === undefined)
+            return next();
+        appendSessionAllow(agent.session, {
+            scope: 'sandbox-auto',
+            toolName: req.toolName,
+            timestamp: Date.now(),
+            ...req.reason === undefined ? {} : { reason: req.reason },
+        });
+        return 'allowed-once';
+    };
+}
+//# sourceMappingURL=approval-listener.js.map

package/lib/approval-listener.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-listener.js","sourceRoot":"","sources":["../src/approval-listener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAe3D;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA0B;IAC5D,OAAO,MAAM,KAAK,SAAS,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,6BAA6B,CAAC,MAAqC;IAIjF,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACzB,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,EAAE,CAAA;QACnD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAA;QACvB,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,EAAE,CAAA;QACtC,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,MAAM;YAAE,OAAO,IAAI,EAAE,CAAA;QAClD,IAAI,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,SAAS;YAAE,OAAO,IAAI,EAAE,CAAA;QAC1D,kBAAkB,CAAC,KAAK,CAAC,OAAO,EAAE;YAChC,KAAK,EAAE,cAAc;YACrB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,GAAG,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE;SAC1D,CAAC,CAAA;QACF,OAAO,cAAc,CAAA;IACvB,CAAC,CAAA;AACH,CAAC"}

package/lib/auto-stage.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The async LLM-classifier stage for `auto` mode: owns arming (per call, from
+ * the live `permissions.autoMode` settings slice), the memoized
+ * `createLlmClassifier` instance, and the `permission/classifier` session
+ * audit event. The plugin's `tools/pre-execute` listener (index.ts) only
+ * wires this stage — the escalate-only decision flow lives here.
+ *
+ * Arming predicate (§4.4): `autoMode.classifier.enabled === true` AND an llm
+ * stream capability is wired AND the alias route resolves. Enabled but
+ * unarmable ⇒ disarm with ONE warning per process (plus an `unarmed` audit
+ * event when a session is available) and the legacy decision path runs.
+ *
+ * @module @dsh-cc/permission-rules/auto-stage
+ */
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+import type { ToolExecution } from '@dsh-cc/tools';
+import type { DecidedCall } from './decide.ts';
+/** `permissions.autoMode.classifier` — the plugin-local hand-mirror of the shared AutoModeClassifierSchema. */
+export interface AutoModeClassifierSettings {
+    /** Master switch for the LLM risk classifier stage (default `false`). */
+    enabled?: boolean;
+    /** Model route used for classification (default `'haiku'`). */
+    route?: string;
+    /** Per-call timeout in milliseconds (default `8000`). */
+    timeoutMs?: number;
+    /** Verdict cache size in entries (default `256`). */
+    cacheMaxEntries?: number;
+}
+/** `permissions.autoMode` — the plugin-local hand-mirror of the shared AutoModeSchema. */
+export interface AutoModeSettings {
+    /**
+     * Soft-deny hints evaluated by the classifier, in CC's snake_case spelling.
+     * `$defaults` expansion happens at consumption time — the schema never
+     * expands it.
+     */
+    soft_deny?: string[];
+    /** LLM risk classifier configuration; absent when the section omits it. */
+    classifier?: AutoModeClassifierSettings;
+}
+/** The session event type carrying one classifier verdict audit record. */
+export declare const CLASSIFIER_EVENT = "permission/classifier";
+/** Consecutive per-route classifier failures before that route's breaker opens (module constant — no settings knob by design). */
+export declare const CLASSIFIER_BREAKER_THRESHOLD = 3;
+/** The `permission/classifier` payload. The raw classifier input NEVER appears — only its digest. */
+export interface ClassifierAuditEventData {
+    /** The tool the verdict is about. */
+    tool: string;
+    /** sha256 of the rendered classifier input (absent on the arming `unarmed` record). */
+    digest?: string;
+    verdict: 'allow' | 'ask';
+    failure?: 'timeout' | 'error' | 'malformed' | 'unarmed' | 'breaker' | 'cancelled';
+    route?: string;
+    provider?: string;
+    model?: string;
+    latencyMs: number;
+    cacheHit: boolean;
+}
+/**
+ * Append one `permission/classifier` audit record through the widened session
+ * append face (same cross-pin strategy as `./mode.ts` and
+ * `./session-allowlist.ts`).
+ */
+export declare function appendSessionClassifier(session: Session, data: ClassifierAuditEventData): void;
+/**
+ * Fold a session log into the classifier verdict records it carries, in log
+ * order. Foreign event types are skipped; resume/replay reconstructs why a
+ * call did or did not prompt.
+ */
+export declare function foldClassifiers(events: readonly SessionEvent[]): ClassifierAuditEventData[];
+/**
+ * Structural dependency face the service supplies. `stream` is the llm
+ * adapter (undefined when the llm service is not mounted); `resolveRoute`
+ * resolves the configured alias route per call (undefined when unresolvable).
+ */
+export type AutoStageDeps = {
+    /** The live `permissions` settings section (re-read on every call). */
+    settingsRead(): {
+        autoMode?: AutoModeSettings;
+    };
+    /**
+     * One-shot text completion over the auxiliary lane; `undefined` when no llm
+     * service is mounted (the stage then disarms).
+     */
+    stream: ((opts: {
+        provider: string;
+        model: string;
+        system: string;
+        prompt: string;
+        maxTokens: number;
+        signal?: AbortSignal;
+    }) => Promise<string>) | undefined;
+    /** Resolve the configured classifier route for this call's session. */
+    resolveRoute(exec: ToolExecution): {
+        provider: string;
+        model: string;
+    } | undefined;
+    /** Process logger for the one-time disarm warning. */
+    warn(message: string): void;
+    /** Durable audit sink (session append face, listener-owned). */
+    audit(session: Session, event: ClassifierAuditEventData): void;
+    /**
+     * Optional env-gated process-log sink for raw classifier output (R5) —
+     * never session events; wired only when DSH_PERMISSION_CLASSIFIER_DEBUG=1.
+     */
+    debug?: (message: string) => void;
+};
+/** The stage's contribution to one pre-execute decision: allow, an escalated ask, or nothing (legacy path). */
+export type StageOutcome = 'allow' | {
+    kind: 'ask';
+    reason: string;
+};
+export type AutoStage = {
+    /** Drop the memoized classifier so the next armed call rebuilds it (settings onChange). */
+    rebuild(): void;
+    /**
+     * Maybe escalate one verbose decision. Returns a final decision only for
+     * the armed + `auto` + LOW + `ask`/`passthrough` slice (§4.1); every other
+     * shape returns undefined and the listener applies the legacy mapping
+     * unchanged — the LLM is then never invoked (I1–I3, I5).
+     */
+    maybeEscalate(decided: DecidedCall, exec: ToolExecution): Promise<StageOutcome | undefined>;
+};
+/**
+ * Trailing consecutive per-route failure streak over attributed classifier
+ * audit records (R3, pure fold — unit-testable). Only events carrying
+ * `provider`/`model` attribution matching `routeKey` count (unattributed
+ * legacy events predate route keying — skipped entirely); a parsed verdict or
+ * cache hit resets the streak; malformed/error/timeout increment it; other
+ * tags (`cancelled`, `breaker`, `unarmed`) are neutral. Capped at `threshold`.
+ */
+export declare function trailingRouteFailureStreak(events: readonly ClassifierAuditEventData[], routeKey: string, threshold: number): number;
+/**
+ * Build the stage. The classifier instance is memoized per autoMode slice:
+ * `rebuild()` (wired to the plugin's settings onChange/reload) drops it, and
+ * the next armed call rebuilds from the fresh slice — never per call.
+ */
+export declare function createAutoStage(deps: AutoStageDeps): AutoStage;
+//# sourceMappingURL=auto-stage.d.ts.map