dsh-perm-gate 0.2.0

package/README.md

@@ -0,0 +1,209 @@
+# dsh-perm-gate
+
+- [English README](./README.md)
+- [中文 README](./README.zh.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+> **Compatibility note:** v0.1.0 ships `ja` / `ko` dictionaries, but official DSH exposes
+> only `zh` / `en` through `LocaleRuntime` (`LOCALE_IDS = ["zh", "en"]`). On stock DSH,
+> selecting `ja` / `ko` fails with `locale "<id>" is not registered`. Use a DSH fork that
+> updates `LOCALE_IDS` (locale-settings.ts) and `LOCALES` labels (client/index.ts), then
+> rebuild.
+
+Version **0.1.0** — see the [Changelog](./CHANGELOG.md).
+
+A single, self-sufficient, deterministic-first, fail-closed permission gate for DeepSeek Harness.
+
+`dsh-perm-gate` decides every tool call through a fixed priority chain:
+
+| Stage | Decision | What it is |
+| ---- | ---- | ---- |
+| **P0** | `deny` | deterministic hard-deny: credential material, protected-path mutation, dangerous shell |
+| **P1** | `allow` | a precise, bounded **session grant** |
+| **P2** | `deny/allow/ask` | static rule chain: blacklist first, then allow, then ask |
+| **P3** | `allow/deny/ask` | optional LLM semantic classifier (default **off**) |
+| **P4** | `ask` | official approval seam |
+
+Strictly fail-closed: a P0 decision is never overridden by a grant, a rule, the classifier, or a human.
+
+## Why
+
+The DSH safety ecosystem splits this across several plugins (`dsh-permission-rules`,
+`dsh-auto-mode`, `dsh-auto-review`, `dsh-movein-permissions`). `dsh-perm-gate` merges the
+gate + approval + (optional) classifier into one package, with one audit trail and no
+cross-plugin version coupling.
+
+## Features
+
+- **Command whitelist / blacklist** — matched on an **argv decomposition** (not a raw string),
+  with recursive descent into `sh -c`/`bash -c`, pipeline detection, redirect-target
+  checking, and recursive/force (`rm -rf`) recognition.
+- **Deny priority** — a matching deny rule wins over any allow rule.
+- **Session grants** — precise `(tool, canonical fingerprint)` grants with `TTL` + `maxUses`;
+  re-running with a different target never reuses authority. Sub-agents inherit but cannot mint.
+- **Pure-function rule engine** — glob/regex compilation with a ReDoS bound, loud fail on
+  malformed rules, and source-hash compile caching.
+- **Audit** — every decision is logged as an `{ignorable:true}` event with its `callId`; the
+  model-visible reason matches the recorded outcome.
+- **Permissive tier** — an **independent approval mode** (separate from read-only, full-access
+  and whitelist tiers) that is neither "auto-approve" nor blanket trust. Front-end exposes a
+  **single switch** (`permissive`); the three backend strategies are **combinable** and driven
+  by plugin settings — still fail-closed against P0.
+- **Risk-graded `llmAssist`** — a custom OpenAI-compatible LLM grades each `ask` as
+  `safe` / `risky:<category>`; hard categories (deletion, credential, remote, system, bulk)
+  **always ask**, neutral enters verdict learning, and every failure stays fail-closed.
+- **Verdict learning** — neutral-risk asks that the human approves and that actually execute
+  count up; after the threshold, the *exact same operation* (fingerprint-matched) auto-allows.
+- **Decision event feed** — every decision is appended to a JSONL feed and surfaced by the
+  browser half as a notice strip above the conversation input.
+
+## Install
+
+Requires an existing [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) installation.
+
+```sh
+dsh plugin --profile web add dsh-perm-gate
+```
+
+Full install, upgrade, migration and troubleshooting steps live in the
+[Installation guide](./INSTALL.md) — also available in
+[中文](./INSTALL.zh.md) / [日本語](./INSTALL.ja.md) / [한국어](./INSTALL.ko.md).
+
+## Configuration
+
+Add the plugin to `cordis.yml`:
+
+```yaml
+- id: dsh-perm-gate
+  name: dsh-perm-gate
+  config:
+    rulesFile: ./permissions.yaml   # optional; empty = allow everything per defaultAction
+    dshHome: $DSH_HOME              # root pinned for protected-target checks
+    defaultAction: ask              # allow | ask | deny
+```
+
+### Rules file
+
+```yaml
+permissions:
+  defaultAction: ask
+  deny:
+    - command: [rm#recursive]
+      reason: no recursive rm
+    - command: [ssh]
+      reason: no direct ssh
+    - paths: [.dsh/**]
+      reason: protect harness metadata
+  allow:
+    - command: [pnpm, node]
+      reason: dev tools
+    - command: [curl, wget]
+      args: ["https://*.example.com/*"]
+      reason: allowed endpoint
+  ask:
+    - command: [bash, sh]
+      reason: ask shells
+```
+
+A command entry `word#flag` matches the command word (`word`) with the modifier `recursive` or
+`force` — so `rm#recursive` matches `rm -rf`, `env rm -rf`, and `sh -c "rm -rf /"`.
+
+## Permissive mode
+
+Permissive is an **independent approval tier** in the DSH permission picker, parallel to
+Read Only / Workspace Write / Full access / Whitelist. It is **not** "auto-approval" and never
+mints blanket authority: it only narrows or widens the seam *before* the human/LLM step while
+P0 hard-deny stays monotonic and non-negotiable.
+
+In `cordis.yml`:
+
+```yaml
+- id: dsh-perm-gate
+  name: dsh-perm-gate
+  config:
+    rulesFile: ./permissions.yaml
+    defaultAction: ask
+    permissive: true            # single front-facing switch (independent tier on)
+    permissiveStrategies:        # backend, combinable
+      trustAutoAllow: true       # in-scope safe ops auto-allow; dangerous/unknown ask
+      alwaysConfirm: false       # every crossing asks; allow-controls add repeat-allow / wl-migrate buttons
+      llmAssist: false           # LLM classify first, human fallback on ask/failure
+```
+
+`trustAutoAllow` is the baseline middle tier (rule-allow auto-passes). `alwaysConfirm` surfaces
+the approval panel for every crossing; its "allow controls" add two extended buttons — 
+**repeat-allow this type this session** (a bounded session grant) and **allow every occurrence**
+(which persists the command word into the `permissions.yaml` allow whitelist via
+`approveAllowEverywhere`). `llmAssist` consults a real, configurable LLM (`classifierEndpoint` /
+`classifierModel`, any OpenAI-compatible API) to auto-decide an `ask`, and falls back to the
+human seam on `ask`/error — always fail-closed. When `permissive` is off, the gate behaves
+exactly as before.
+
+### Risk-graded llmAssist, verdict learning, and the event feed
+
+When `llmAssist` is on, the configured LLM (any OpenAI-compatible endpoint — point
+`classifierEndpoint` / `classifierModel` / `classifierApiKey` at your own API) grades one
+`ask` at a time with a structured protocol:
+
+- `safe` → the ask is auto-allowed (audited as the `classifier` source).
+- `risky` + a **hard category** (`deletion`, `credential`, `remote`, `system`, `bulk`) →
+  the ask **always** reaches the human; hard risks are never auto-allowed and never learned.
+- `risky:neutral` → with `riskLearning` enabled (Settings card, off by default), each human
+  approval that actually executes (settled via the host's `tools/result` event) counts toward
+  a `tool|category` key; once the count reaches `riskThreshold` (default 3) **and** the new
+  call's operation fingerprint (command word + target basename) matches a confirmed sample,
+  the exact same operation auto-allows. A different target never reuses that authority.
+- Timeouts (`riskTimeoutMs`, default 20 s, one retry), transport failures, and off-protocol
+  model output leave the ask untouched — the gate never guesses.
+
+Learning state persists to a plugin-owned JSON (`$DSH_HOME/perm-gate/learning.json`, or
+`learningFile`), never into your YAML rules file. Every decision is appended to
+`$DSH_HOME/perm-gate/events.jsonl` (or `eventsFile`) and served at
+`GET /api/dsh-perm-gate/events?sessionId=&since=`; the browser half polls it and shows the
+latest decision as a notice strip above the conversation input (asks stay visible until the
+next event). The Permissive tier keeps its shield icon in the permission picker — on both the
+menu item and the collapsed picker trigger.
+
+### A selectable session tier
+
+`cordis.patch.yml` extends the DSH `permission.config.presets` with a `permissive` preset
+(`sandbox: workspace-write`, `approval: ask`, name **Permissive**) between Workspace Write and
+Full access — the same mechanism the Auto mode uses. So the session permission picker offers
+Permissive as an independent selectable approval tier, not an "auto-approval" mode.
+
+### Configurable in the UI
+
+The tier is also adjustable at runtime from **Settings → Plugins → Permissive approval tier**
+(a `settings.plugins.tab` page rendered by the plugin's browser client): one switch toggles
+`permissive`, and three toggles edit the backend `permissiveStrategies`. The host reads the
+namespace live, so a change applies to the next tool call without a restart. This is an
+independent approval class, NOT the DSH "auto-approval" mode.
+
+## CLI
+
+Dry-run one call against a rules file (no harness needed):
+
+```sh
+dsh-perm-gate --rules permissions.yaml --tool bash --args '{"command":"pnpm install"}'
+dsh-perm-gate --rules permissions.yaml --list
+```
+
+## Development
+
+```sh
+npm run typecheck
+npm test
+npm run build
+```
+
+## License
+
+[MIT](./LICENSE)

package/README.zh.md

@@ -0,0 +1,144 @@
+# dsh-perm-gate
+
+- [English README](./README.md)
+- [中文 README](./README.zh.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [Installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+
+> **兼容性说明：** v0.1.0 自带 `ja` / `ko` 字典，但官方 DSH 的 `LocaleRuntime`
+> 只暴露 `zh` / `en`（`LOCALE_IDS = ["zh", "en"]`）。在原版 DSH 上选择 `ja` / `ko`
+> 会报 `locale "<id>" is not registered`。请使用更新了 `LOCALE_IDS`
+> （locale-settings.ts）与 `LOCALES` 标签（client/index.ts）的 DSH fork 并重新构建。
+
+版本 **0.1.0** —— 变更见 [Changelog](./CHANGELOG.md)。
+
+一个**单一自足、确定性优先、fail-closed** 的 DeepSeek Harness 权限门插件。
+
+对每个工具调用按固定优先级链裁决：
+
+| 阶段 | 决策 | 含义 |
+| ---- | ---- | ---- |
+| **P0** | `deny` | 确定性硬拒：凭据材料 / 受保护路径改写 / 危险 shell |
+| **P1** | `allow` | 精确、有界的**会话放行** grant |
+| **P2** | `deny/allow/ask` | 静态规则链：黑名单优先，其次 allow，再 ask |
+| **P3** | `allow/deny/ask` | 可选 LLM 语义分类器（默认**关闭**） |
+| **P4** | `ask` | 官方 approval seam |
+
+严格 fail-closed：P0 永不因 grant / 规则 / 分类器 / 人工而放行。
+
+## 特性
+
+- **命令白/黑名单** — 基于 **argv 分解**匹配（非裸字符串），递归下钻 `sh -c`/`bash -c`、识别管道、重定向目标、递归/强制（`rm -rf`）。
+- **deny 优先** — 命中黑名单即拒绝，胜过任何 allow。
+- **会话放行** — 精确的 `(工具, 规范化 fingerprint)` grant，带 `TTL` + `maxUses`；换目标绝不复用。子代理继承但不可自授。
+- **纯函数规则引擎** — glob/regex 编译 + ReDoS 上限、坏规则 loud fail、按源内容哈希缓存。
+- **审计** — 每次决策写为 `{ignorable:true}` 事件并带 `callId`；模型可见理由与记录一致。
+- **Permissive 档位** — 一个**独立审批模式**（区别于只读、完全权限与白名单档），既不是"自动审批"，也不授予泛化权限。前端只暴露**一个开关**（`permissive`），后台三个审批策略**可组合**、由插件设置决定——仍对 P0 保持 fail-closed。
+
+## 安装
+
+需要先安装 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)。
+
+```sh
+dsh plugin --profile web add dsh-perm-gate
+```
+
+完整的安装、升级、迁移与排查步骤见[中文安装指南](./INSTALL.zh.md)（另有
+[English](./INSTALL.md) / [日本語](./INSTALL.ja.md) / [한국어](./INSTALL.ko.md)）。
+
+## 配置
+
+`cordis.yml`：
+
+```yaml
+- id: dsh-perm-gate
+  name: dsh-perm-gate
+  config:
+    rulesFile: ./permissions.yaml
+    dshHome: $DSH_HOME
+    defaultAction: ask
+```
+
+规则示例：见 [examples/permissions.example.yaml](./examples/permissions.example.yaml)。
+
+## Permissive 档位
+
+Permissive 是权限下拉框里一个**独立审批档**，与 Read Only / Workspace Write / Full access /
+Whitelist 平行。它**不叫"自动审批"**、也不授予泛化权限：只会在人类/LLM 接缝**之前**收窄或放宽决策，
+P0 硬拒绝始终单调且不可协商。
+
+`cordis.yml`：
+
+```yaml
+- id: dsh-perm-gate
+  name: dsh-perm-gate
+  config:
+    rulesFile: ./permissions.yaml
+    defaultAction: ask
+    permissive: true            # 前端唯一的开关（启用独立档）
+    permissiveStrategies:        # 后台策略，可组合
+      trustAutoAllow: true       # 作用域内安全操作自动放行；危险/未知转 ask
+      alwaysConfirm: false       # 一律逐次 ask；允许控件附带重复允许/迁白名单按钮
+      llmAssist: false           # 先由 LLM 分类裁决；ask/无分类器时回退到人工
+```
+(llmAssist 的真实接收 LLM 在设置页填 `classifierEndpoint` / `classifierModel`，OpenAI 兼容的自定义 API
+均可。)
+
+`trustAutoAllow` 是中间档基线（rule-allow 自动放行）。`alwaysConfirm` 让每次越界都走审批面板，其
+「允许控件」含两个扩展按钮：**本会话重复允许该类**（会话限次 grant，`approveRepeat`）与
+**允许所有类型**（把命令词持久写进 `permissions.yaml` 的 allow 白名单，`approveAllowEverywhere`）。
+`llmAssist` 调用配置的真实 LLM（任意 OpenAI 兼容 API）自动裁决 `ask`，结果不确定/出错时回退人工
+接缝——始终 fail-closed。`permissive` 关闭时，门禁行为与之前完全一致。
+
+### 权限下拉里可选档位
+
+`cordis.patch.yml` 通过扩展 DSH 的 `permission.config.presets` 加入了 `permissive` preset
+（`sandbox: workspace-write`、`approval: ask`、名称 **Permissive**），位于 Workspace Write 与
+Full access 之间——与 Auto 档同一机制。因此会话权限下拉里会出现 Permissive 这个**独立可选审批档**，
+而不是"auto-approval"档。
+
+### 在 UI 里可配置
+
+该档位也可在运行时从 **设置 → 插件 → Permissive 审批档** 调整（插件浏览器端渲染的
+`settings.plugins.tab` 页面）：一个开关切换 `permissive`，三个开关编辑后台
+`permissiveStrategies`。host 端 live 读取该命名空间，改动对下一条工具调用即时生效，无需重启。
+这是一个独立审批类，**不是** DSH 的"auto-approval"档。
+
+### 风险分级 llmAssist、裁决学习与事件流
+
+开启 `llmAssist` 后，自定义 LLM（任何 OpenAI 兼容端点——把 `classifierEndpoint` /
+`classifierModel` / `classifierApiKey` 指向你自己的 API）按结构化协议逐条评估 `ask`：
+
+- `safe` → 自动放行（审计来源为 `classifier`）。
+- `risky` + **硬风险类别**（`deletion`、`credential`、`remote`、`system`、`bulk`）→ 一律转人工；硬风险永不自动放行、也永不进入学习。
+- `risky:neutral` → 若开启 `riskLearning`（设置卡片内，默认关闭），人工批准且真实执行的 neutral 风险会按 `tool|类别` 计数；计数达到 `riskThreshold`（默认 3）且新调用的操作指纹（命令词 + 目标基名）命中已确认样本时，**同一操作**自动放行。不同目标永不复用该放行。
+- 超时（`riskTimeoutMs`，默认 20s，重试 1 次）、传输失败与协议外输出均维持原 `ask`——门禁绝不猜测。
+
+学习状态持久化在插件自有 JSON（`$DSH_HOME/perm-gate/learning.json` 或 `learningFile`），不写入你的 YAML 规则文件。每次决策都会追加到 `$DSH_HOME/perm-gate/events.jsonl`（或 `eventsFile`），并经 `GET /api/dsh-perm-gate/events?sessionId=&since=` 提供；浏览器端轮询该接口，在输入框上方以提示条展示最新决策（ask 常驻至下一条事件）。Permissive 档在权限选择器中保留盾形图标——菜单项与折叠触发按钮均有图标。
+
+
+## CLI（独立 dry-run）
+
+```sh
+dsh-perm-gate --rules permissions.yaml --tool bash --args '{"command":"pnpm install"}'
+dsh-perm-gate --rules permissions.yaml --list
+```
+
+## 开发
+
+```sh
+npm run typecheck
+npm test
+npm run build
+```
+
+## 许可证
+
+[MIT](./LICENSE)

package/assets/README.md

@@ -0,0 +1,5 @@
+# assets
+
+Screenshots and diagrams referenced by the README documentation. Add a `.gitkeep`
+in this directory to keep it in the repository; place images (e.g. `readme/*.png`)
+used by `README.md` / `README.zh.md` / `README.ja.md` / `README.ko.md` here.

package/cordis.patch.yml

@@ -0,0 +1,35 @@
+# dsh-perm-gate profile patch.
+#
+# The DSH bundle patch REPLACES the whole `permission.config.presets` map (it
+# does not merge per key), so this file MUST restate every preset that should
+# survive — the built-ins AND the `auto` tier contributed by dsh-auto-mode.
+# Omitting any of them silently disables that tier on the next profile load.
+# 1) Add an independent "Permissive" session approval tier to the DSH permission
+#    picker (same mechanism Auto uses).
+# 2) Insert the plugin itself (host half) into the profile.
+- id: permission
+  config:
+    presets:
+      read-only:
+        sandbox: read-only
+        approval: ask
+      workspace-write:
+        sandbox: workspace-write
+        approval: ask
+      permissive:
+        sandbox: workspace-write
+        approval: ask
+        name: Permissive
+        description: Independent approval tier — safe in-scope ops auto-allow, dangerous crossings ask (approval strengths tunable under Settings → Plugins → Permissive approval tier).
+      auto:
+        sandbox: workspace-write
+        approval: ask
+        name: Auto
+        description: Workspace-sandboxed execution with automatic review and one-shot approval for wider access.
+      danger-full-access:
+        sandbox: danger-full-access
+        approval: never
+
+- insert:
+    - id: dsh-perm-gate
+      name: dsh-perm-gate

package/examples/permissions.example.yaml

@@ -0,0 +1,20 @@
+permissions:
+  defaultAction: ask
+  deny:
+    - command: [rm#recursive, rm#force]
+      reason: no recursive/forced destructive deletion
+    - command: [sudo]
+      reason: no privilege escalation
+    - command: [ssh]
+      reason: no direct remote shell
+    - paths: [.dsh/**]
+      reason: protect harness metadata
+  allow:
+    - command: [git pull, pnpm, node, npm run]
+      reason: routine project development
+    - command: [curl, wget]
+      args: ["https://*.example.com/*"]
+      reason: allowed package/registry endpoint
+  ask:
+    - command: [bash, sh, pwsh]
+      reason: stateful or unlisted shell — semantic review

package/lib/allowlist.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Append one command pattern as a new `allow` entry in the rules file.
+ * Returns false (leaving the file untouched) on any I/O or shape error.
+ * @param rulesFile - absolute or relative path to the permissions YAML.
+ * @param pattern - command word (glob) to whitelist, e.g. `git push`.
+ * @param reason - human-readable reason recorded on the allow entry.
+ */
+export declare function appendAllowCommand(rulesFile: string, pattern: string, reason?: string): boolean;
+/** The allow-list command patterns currently in the rules file (read-only). */
+export declare function listAllowCommands(rulesFile: string): string[];
+/**
+ * Replace the rules file's `allow` whitelist with exactly the given command
+ * patterns (one allow entry per pattern). Other sections (deny / ask /
+ * defaultAction) are preserved. Returns false on any I/O or shape error.
+ * @param rulesFile - absolute or relative path to the permissions YAML.
+ * @param patterns - exact command-pattern list to set; empty clears the whitelist.
+ * @param reason - reason recorded on each generated allow entry.
+ */
+export declare function replaceAllowCommands(rulesFile: string, patterns: readonly string[], reason?: string): boolean;

package/lib/allowlist.js

@@ -0,0 +1,97 @@
+/**
+ * Durable allowlist (whitelist) writes for dsh-perm-gate.
+ *
+ * The "allow everywhere" approval action appends a matched command pattern to
+ * the rules file's `allow` list and reloads, so a human-approved command is
+ * persistently whitelisted across sessions — not just granted once.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { parse, stringify } from 'yaml';
+/**
+ * Append one command pattern as a new `allow` entry in the rules file.
+ * Returns false (leaving the file untouched) on any I/O or shape error.
+ * @param rulesFile - absolute or relative path to the permissions YAML.
+ * @param pattern - command word (glob) to whitelist, e.g. `git push`.
+ * @param reason - human-readable reason recorded on the allow entry.
+ */
+export function appendAllowCommand(rulesFile, pattern, reason = 'permissive allow-everywhere') {
+    try {
+        const text = readFileSafe(rulesFile);
+        const root = text === '' ? undefined : parse(text);
+        const doc = root ?? {};
+        const perms = doc['permissions'];
+        const section = (perms === undefined ? doc : perms);
+        if (typeof section !== 'object' || section === null || Array.isArray(section))
+            return false;
+        const allow = Array.isArray(section['allow']) ? section['allow'] : [];
+        allow.push({ command: [pattern], reason });
+        section['allow'] = allow;
+        writeFileSync(rulesFile, stringify(doc), 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The allow-list command patterns currently in the rules file (read-only). */
+export function listAllowCommands(rulesFile) {
+    try {
+        const text = readFileSafe(rulesFile);
+        if (text === '')
+            return [];
+        const root = parse(text);
+        const perms = root['permissions'];
+        const section = perms === undefined ? root : perms;
+        const allow = Array.isArray(section['allow']) ? section['allow'] : [];
+        const out = [];
+        for (const entry of allow) {
+            if (typeof entry !== 'object' || entry === null)
+                continue;
+            const command = entry['command'];
+            if (!Array.isArray(command))
+                continue;
+            for (const c of command)
+                if (typeof c === 'string')
+                    out.push(c);
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Replace the rules file's `allow` whitelist with exactly the given command
+ * patterns (one allow entry per pattern). Other sections (deny / ask /
+ * defaultAction) are preserved. Returns false on any I/O or shape error.
+ * @param rulesFile - absolute or relative path to the permissions YAML.
+ * @param patterns - exact command-pattern list to set; empty clears the whitelist.
+ * @param reason - reason recorded on each generated allow entry.
+ */
+export function replaceAllowCommands(rulesFile, patterns, reason = 'permissive allowlist') {
+    try {
+        if (rulesFile === '')
+            return false;
+        const text = readFileSafe(rulesFile);
+        const root = text === '' ? undefined : parse(text);
+        const doc = root ?? {};
+        const perms = doc['permissions'];
+        const section = (perms === undefined ? doc : perms);
+        if (typeof section !== 'object' || section === null || Array.isArray(section))
+            return false;
+        section['allow'] = patterns.map((pattern) => ({ command: [pattern], reason }));
+        writeFileSync(rulesFile, stringify(doc), 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readFileSafe(p) {
+    try {
+        return readFileSync(p, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}

package/lib/audit.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Audit for dsh-perm-gate: a typed, ignorable-marked event log plus the
+ * invariant that whatever is model-visible (the reason text surfaced into the
+ * tool result) is ALSO recorded with the same `callId`/`outcome`.
+ *
+ * The `ignorable` marker is what lets hosts treat these events as log-only,
+ * never re-injected into the model context. Hosts that predate the marker
+ * (return value of the append proves it) make the runtime degrade to an
+ * in-memory mirror instead of failing.
+ */
+export type AuditOutcome = 'allow' | 'deny' | 'ask' | 'delegated';
+export type DecisionSource = 'hard-deny' | 'grant' | 'rule' | 'default' | 'ask' | 'classifier' | 'permissive';
+export interface AuditEntry {
+    readonly kind: 'permissionGate/decision';
+    readonly marker: 'ignorable';
+    readonly callId: string;
+    readonly tool: string;
+    readonly outcome: AuditOutcome;
+    readonly source: DecisionSource;
+    readonly reason: string;
+    readonly at: number;
+}
+export interface AuditSink {
+    append(entry: AuditEntry): {
+        markerSupported: boolean;
+    };
+}
+/** The on-disk/on-host append contract a DSH session `append` should honor. */
+export declare class MemoryAuditMirror implements AuditSink {
+    readonly entries: AuditEntry[];
+    append(entry: AuditEntry): {
+        markerSupported: boolean;
+    };
+    count(kind?: AuditOutcome): number;
+}
+/** The invariant pairing the model-visible reason with its recorded event. */
+export declare function assertInvariant(visible: {
+    callId: string;
+} | undefined, entry: AuditEntry): boolean;
+/**
+ * Detect whether a host honors the `ignorable` marker before the first append,
+ * by probing the append surface's return value.
+ */
+export declare function probeHost(append: (entry: AuditEntry) => unknown): boolean;
+export declare function makeEntry(input: Omit<AuditEntry, 'kind' | 'marker'>): AuditEntry;

package/lib/audit.js

@@ -0,0 +1,34 @@
+/** The on-disk/on-host append contract a DSH session `append` should honor. */
+export class MemoryAuditMirror {
+    entries = [];
+    append(entry) {
+        this.entries.push(entry);
+        return { markerSupported: true };
+    }
+    count(kind) {
+        return kind === undefined ? this.entries.length : this.entries.filter((e) => e.outcome === kind).length;
+    }
+}
+/** The invariant pairing the model-visible reason with its recorded event. */
+export function assertInvariant(visible, entry) {
+    // The visible reason must carry the same callId that was logged; otherwise a
+    // model-visible decision could exist with no audit trace.
+    return visible === undefined || visible.callId === entry.callId;
+}
+/**
+ * Detect whether a host honors the `ignorable` marker before the first append,
+ * by probing the append surface's return value.
+ */
+export function probeHost(append) {
+    try {
+        const probe = append({ kind: 'permissionGate/decision', marker: 'ignorable', callId: '__probe__', tool: '__probe__', outcome: 'ask', source: 'ask', reason: 'probe', at: Date.now() });
+        const boxed = probe;
+        return boxed.markerSupported !== false;
+    }
+    catch {
+        return false;
+    }
+}
+export function makeEntry(input) {
+    return { kind: 'permissionGate/decision', marker: 'ignorable', ...input };
+}