dsh-perm-gate 2.1.0 → 2.6.1

package/docs/rules-format.md

@@ -0,0 +1,279 @@
+# 规则文件格式规范（`permissions` YAML）
+
+> **权威性**：本文件的维度清单与 `src/rule.ts:181` 的 `VALID_KEYS` **逐字一致**。
+> 两者任一变更必须同步；`test/rule.spec.ts` 与 `test/rule-dims.spec.ts` 是运行时护栏。
+> 适用版本：`dsh-perm-gate` **2.4.1**（DSH ≥ 0.1.2-alpha.1）。
+
+---
+
+## 1. 文件位置与加载
+
+| 项 | 说明 |
+|---|---|
+| 默认路径 | `<dataDir>/rules.yml`（`dataDir` 由 `config.resolveDataDir` 解析，默认 `$DSH_HOME/perm-gate/`） |
+| 显式指定 | `config.rulesFile` |
+| 规则链 | 支持多文件链（`rulesChain` / `searchUp` / `fallbackPath` / `badFilePolicy` / `maxRules`），见 `src/rule-chain.ts` |
+| 热重载 | 由 `src/watch.ts`（chokidar）监听生效规则文件，防抖后链级重编译 |
+| 解析失败 | **fail loud**——规则非法直接报错，绝不静默停用门控 |
+
+---
+
+## 2. 顶层结构
+
+```yaml
+defaultAction: ask        # 可选；无任何规则命中时的动作。缺省 = ask
+deny:                     # 动作分区（数组）
+  - <规则条目>
+allow:
+  - <规则条目>
+ask:
+  - <规则条目>
+```
+
+**动作即分区**：条目本身不带 action 字段（写了必须与所在分区一致）。求值顺序固定为
+**deny → allow → ask → defaultAction**，首次匹配胜出（deny wins over allow）。
+黑名单关键词层排在 deny 之前。
+
+`defaultAction` 取值：`allow` | `ask` | `deny`（缺省 `ask`）。
+
+---
+
+## 3. 规则条目可用字段（`VALID_KEYS`）
+
+```
+tools · command · args · paths · params · absent · agents · when · argv · network · branch
+action · reason · enabled
+```
+
+| 字段 | 类型 | 作用 |
+|---|---|---|
+| `tools` | 字符串 / 字符串数组 | 工具名 glob |
+| `command` | 字符串 / 字符串数组 | 命令词，支持 `word#recursive` / `word#force` 后缀 |
+| `args` | 字符串 / 字符串数组 | 参数 token 扫描 |
+| `paths` | 字符串 / 字符串数组 | 工作区相对路径 glob |
+| `params` | 映射 | 参数键 → 值 glob 列表 |
+| `absent` | 字符串 / 字符串数组 | 必须**不存在**的参数键 |
+| `agents` | 字符串 / 字符串数组 | `main` / `subagent` / `preset:<name>` |
+| `when` | 映射 | 环境与平台条件 |
+| `argv` | 映射 | 额外 argv 模式（`pipeline`） |
+| `network` | 映射 | 域名 / IP / 端口 / scheme |
+| `branch` | 映射 | git 分支 / 远程 / 保护分支（仅对 git 命令生效） |
+| `action` | `allow`\|`ask`\|`deny` | 可选；写了必须与所在分区一致 |
+| `reason` | 字符串 | 人类可读理由（进入事件与 UI） |
+| `enabled` | 布尔 | 设 `false` 则跳过该条目 |
+
+**跨维度逻辑 = AND**：一条规则内出现的**多个维度必须全部满足**；
+**维度内 = OR**：某个维度的列表里任一模式命中即可（`params`/`when`/`network` 的子键为 AND，见各节）。
+
+---
+
+## 4. 逐维语义
+
+### 4.1 `tools` — 工具名
+```yaml
+- tools: [shell, pwsh, bash]
+```
+Glob 匹配工具名。列表内 OR。
+
+### 4.2 `command` — 命令词
+```yaml
+- command: [rm#recursive, rm#force]
+```
+命令词来自 argv 分解（`src/shell.ts`）。后缀 `#recursive` / `#force` 分别要求递归 / 强制语义。
+列表内 OR。
+
+### 4.3 `args` — 参数 token
+```yaml
+- args: ["--force", "-rf"]
+```
+对分解后的 token 集合做扫描。**⚠ 语义为 OR**：任意一个 token 匹配任意一个模式即命中。
+它**无法**要求「`push` 与 `--force` 同时存在」，也无法区分
+`git push --force origin main` 与 `git checkout --force main`——需要这种区分时用 `params` 或（未来的）`branch` 维度。
+
+### 4.4 `paths` — 路径
+```yaml
+- paths: ["src/**", "!src/vendor/**"]
+```
+工作区相对路径 glob；`!` 前缀取反。列表内 OR。
+
+### 4.5 `params` — 键定向匹配（**AND over keys**）
+```yaml
+- params:
+    command: ["*--force*", "!*--dry-run*"]
+    flags.mode: ["production"]
+```
+- 每个键的**实际值**必须匹配该键模式列表中的**至少一个**（列表内 OR）
+- **所有列出的键都必须满足**（键之间 AND）
+- 单个 `!` 前缀模式 = 取反（值必须**不**匹配其余部分）
+- 空模式列表 = 该键只需存在（任意值）
+
+这是表达复合条件的主要手段（`args` 做不到的 AND 需求在这里做）。
+
+### 4.6 `absent` — 键必须缺失（AND）
+```yaml
+- absent: [dry_run, force]
+```
+所列参数键必须**全部不存在**。
+
+### 4.7 `agents` — 代理身份
+```yaml
+- agents: ["main", "preset:reviewer"]
+```
+合法取值：`main`、`subagent`、`preset:<name>`（大小写不敏感）。非法值解析期报错。
+候选集由 `src/agent-identity.ts` 从会话 header 提取。列表内 OR。
+
+### 4.8 `when` — 环境与平台（AND）
+```yaml
+- when:
+    env:
+      NODE_ENV: ["production"]
+      CI: ["true", "1"]
+    platform: [linux, win32]
+```
+- `env`：键 → 允许值列表（**列表内 OR**，**键之间 AND**）
+- `platform`：Node.js `process.platform` 取值
+- `nodeVersion`：保留字段（尚未参与判定）
+
+### 4.9 `argv` — 额外 argv 模式
+```yaml
+- argv:
+    pipeline: ["curl*|sh", "wget*|bash"]
+```
+`pipeline` 匹配**整条管道字符串**：各简单命令的**完整 argv**（命令词 + 参数 + 重定向目标）以 `|` 连接，
+例如 `curl https://x.sh | sh` 的匹配串是 `curl https://x.sh|sh`。
+
+**⚠ 模式里的 `|` 是字面量**，所以 `curl|sh` 只匹配参数恰好为空的紧邻形式；要覆盖带参数的常见写法必须写
+`curl*|sh`。（历史缺陷：匹配串曾只取命令词，`curl|sh` 因此对上的是无害的 `curl|sh`，而真正危险的
+`curl https://x.sh | sh` 反而匹配不到。）
+
+### 4.10 `network` — 网络目标（子维度 AND）
+```yaml
+- network:
+    domains: ["*.internal.corp", "github.com"]
+    ips: ["10.0.0.0/8", "192.168.1.1"]
+    ports: ["443", "8000-9000"]
+    schemes: [https, http]
+```
+- 出现的**每个子维度都必须匹配**（子维度之间 AND）；每个子维度内部 OR
+- `domains` 支持 glob；`ips` 支持 CIDR；`ports` 支持区间；`schemes` 为协议名
+
+网络维度有两个生效面：`tools/pre-execute` 的静态 URL 候选检查，以及回环代理拦截真实出站流量
+（`network.enabled` **默认 false**，opt-in）。
+
+### 4.11 `branch` — git 分支 / 远程 / 保护分支（子维度 AND）
+
+```yaml
+- command: [git]
+  args: [push]
+  branch:
+    target: [main, master, "release*"]
+    remote: [origin]
+    shared: true
+```
+
+| 子字段 | 语义 |
+|---|---|
+| `target` | 分支名 glob（`*` **跨** `/`，所以 `release*` 能匹配 `release/1.0`） |
+| `remote` | 远程名 glob |
+| `shared` | 要求目标分支是**保护分支** |
+
+**为什么需要这个维度**：`args` 是 OR 语义（§4.3），它能问「`--force` 出现了吗」，但永远问不出
+「`--force` 是否用在**推送到保护分支**上」。决定性用例是区分两条 token 完全相同的命令：
+
+- `git push --force origin main` → 危险，应命中
+- `git checkout --force main` → 日常操作，**不**应命中
+
+候选来自统一的命令分类器（`src/command-dispatcher.ts` + `src/parsers/git.ts`），因此
+refspec 形式（`HEAD:main`）已被拆解、远程名不会被误当成分支名、标志位也已归一。
+
+**三条必须知道的边界**：
+
+1. **只对 git 命令生效**。非 git 命令（`rm -rf`、`npm install`…）不满足任何 `branch` 子维度，
+   因此带 `branch` 的规则对它们**不匹配**（不会抛错）——这类命令由写路径层与黑名单层负责。
+2. **`shared` 是静态判定**，来自解析器的保护分支清单
+   （`src/parsers/git.ts` 的 `PROTECTED_BRANCHES`：`main` / `master` / `production` / `release` / `stable`）。
+   它**不会**执行 `git branch -r --contains` 之类查询——那会把子进程放上门控决策路径。
+   注意 `shared` 与 `target` 是**并列且各自独立**的子维度：写了 `target: ["release*"]` 时
+   `release/1.0` 满足 `target`，但不满足 `shared`（保护清单是精确匹配）。
+3. **子维度之间 AND，各自内部 OR**；多个简单命令（管道/`&&`）任一满足即可。
+
+---
+
+## 5. 完整示例
+
+```yaml
+defaultAction: ask
+
+deny:
+  # 凭据材料外泄（P0 层另有硬拒绝兜底）
+  - tools: [shell, pwsh]
+    params:
+      command: ["*AWS_SECRET*", "*PRIVATE KEY*"]
+    reason: "credential material in command"
+
+  # 管道下载即执行
+  - argv:
+      pipeline: ["curl*|sh", "wget*|bash"]
+    reason: "piped download-and-execute"
+
+  # 推送到保护分支（args 做不到的区分：同一批 token 的 checkout 不命中）
+  - command: [git]
+    args: [push]
+    branch:
+      target: [main, master, "release*"]
+      shared: true
+    reason: "push to a protected branch"
+
+  # 生产环境下的强制删除
+  - command: [rm#recursive, rm#force]
+    when:
+      env:
+        NODE_ENV: ["production"]
+    reason: "recursive force delete in production"
+
+allow:
+  # 常见只读查询
+  - tools: [read, grep, glob]
+    reason: "read-only workspace queries"
+
+  # 常见开发域名
+  - network:
+      domains: [github.com, "*.githubusercontent.com"]
+      schemes: [https]
+    reason: "common dev hosts"
+
+ask:
+  # 推送需确认（注意：args 是 OR，这里只要求出现 push）
+  - command: [git]
+    args: ["push"]
+    reason: "git push requires confirmation"
+```
+
+同一份示例也随包分发：`examples/permissions.example.yaml`。
+
+---
+
+## 6. 与 CLI dry-run 配合
+
+改完规则**先干跑再上线**：
+
+```powershell
+# 列出已编译规则（默认 ask 分区、规则条数、permissive 策略快照）
+dsh-perm-gate --rules permissions.yaml --list
+
+# 判定一次调用（--args 是 JSON；参数较短时直接内联）
+dsh-perm-gate --rules permissions.yaml --tool read --args "{\"file_path\":\"src/index.ts\"}"
+```
+
+输出为 JSON：`decision`（`allow` / `ask` / `deny`）、`reason`、`audited`。
+
+**两个必须知道的坑**：
+
+1. **黑名单先于规则命中**。`deny-keyword` 层跑在 `deny:` 分区之前，
+   `rm -rf` / `push --force` 这类预设词会在你的规则之前就把调用拦下——
+   dry-run 输出里的 `deny-keyword:` 前缀就是它在起作用，不是你的规则。
+2. **带引号的长参数在 PowerShell 下会被二次解析**（可能报 `--args must be valid JSON`）。
+   稳妥做法：写进临时文件后用 `--args (Get-Content -Raw args.json)`，
+   或直接依赖 `test/rule-dims.spec.ts` 与 `test/evaluate.spec.ts` 的维度覆盖。
+
+CLI 与运行时共用同一判定引擎（`evaluate.ts` + `engine.ts`），输出即真实裁决。

package/docs/ui-gap-analysis-and-branch-permissions.md

@@ -0,0 +1,338 @@
+# dsh-perm-gate UI 缺口分析与分支级权限可行性
+
+> **日期**: 2026-09-16
+> **状态**: 草案
+> **相关讨论**: PerryLink dsh-auto-review 对比分析
+
+---
+
+## 一、现状：后端能力完整，前端 UI 缺失
+
+### 后端已支持的完整 YAML 规则格式
+
+`rules.yml` 支持 10 个维度的分层权限配置：
+
+```yaml
+permissions:
+  deny:
+    - tools: [shell, pwsh]
+      command: [rm#recursive, rm#force]
+      reason: "destructive system command"
+    
+    - args: ["--force"]
+      level: deny
+      reason: "Force flag detected"
+
+  allow:
+    - command: [grep, glob, read]
+      reason: "permissive allowlist"
+    
+    - network:
+        domains: [github.com, api.github.com]
+      reason: "common dev hosts"
+
+  ask:
+    - command: [git]
+      args: ["push"]
+      reason: "Git push requires confirmation"
+```
+
+**VALID_KEYS**: `tools`, `command`, `args`, `paths`, `params`, `absent`, `agents`, `when`, `argv`, `network`, `action`, `reason`, `enabled`
+
+### 前端 UI 面板实际暴露的内容
+
+```
+┌─────────────────────────────────────────────┐
+│  自动审查 (permissive) 开关                  │
+├─────────────────────────────────────────────┤
+│  策略选项                                    │
+│  ☑ trustAutoAllow                           │
+│  ☐ alwaysConfirm                            │
+│  ☐ llmAssist                                │
+├─────────────────────────────────────────────┤
+│  允许列表 (allowlist)                        │
+│  [简单字符串列表，支持批量 textarea 编辑]     │
+│  ⚠️ 只支持前缀匹配，不支持 YAML 分层规则     │
+├─────────────────────────────────────────────┤
+│  拒绝关键词 (denyKeywords)                  │
+│  [同样只支持简单字符串列表]                   │
+└─────────────────────────────────────────────┘
+```
+
+### 缺失的 UI 能力
+
+| 功能 | 后端支持 | UI 支持 | 状态 |
+|------|---------|---------|------|
+| YAML 规则编辑器 | ✅ | ❌ | 需开发 |
+| 维度选择器 (tools/command/args/network 等) | ✅ | ❌ | 需开发 |
+| 规则级别选择 (deny/allow/ask) | ✅ | ❌ | 需开发 |
+| 复合条件编辑 (AND/OR 逻辑) | ✅ | ❌ | 需开发 |
+| 规则测试/预览 | ✅ (CLI dry-run) | ❌ | 需开发 |
+| 规则导入/导出 | ❌ | ❌ | 需开发 |
+
+---
+
+## 二、UI 补全计划草案
+
+### Phase 1: 最小可行方案 (MVP)
+
+**目标**: 在 UI 中暴露完整的 YAML 规则编辑能力
+
+#### 1.1 YAML 编辑器集成
+
+- 集成 Monaco Editor 或 CodeMirror 支持 YAML 语法高亮
+- 支持 `rules.yml` 文件的实时编辑和保存
+- 添加 YAML 语法校验和错误提示
+- 添加规则格式校验（维度名称、值类型等）
+
+#### 1.2 规则模板系统
+
+- 提供常用规则模板（git push、文件删除、网络访问等）
+- 支持从模板快速创建规则
+- 模板库可扩展
+
+#### 1.3 规则测试功能
+
+- 添加"测试规则"按钮
+- 输入命令字符串，预览规则匹配结果
+- 显示哪些维度匹配、哪些不匹配
+- 复用 CLI dry-run 逻辑
+
+### Phase 2: 可视化规则编辑器
+
+**目标**: 提供图形化的规则创建界面，降低 YAML 编写门槛
+
+#### 2.1 维度化规则编辑器
+
+```
+┌─────────────────────────────────────────────┐
+│  新建规则                                    │
+├─────────────────────────────────────────────┤
+│  规则级别: [▼ deny]                         │
+│  原因: [输入框]                              │
+├─────────────────────────────────────────────┤
+│  匹配条件 (AND 逻辑):                        │
+│  [+ 添加条件]                                │
+│                                              │
+│  ┌─────────────────────────────────────┐    │
+│  │ 维度: [▼ command]  模式: [git]      │    │
+│  │ 删除                                  │    │
+│  └─────────────────────────────────────┘    │
+│                                              │
+│  ┌─────────────────────────────────────┐    │
+│  │ 维度: [▼ args]  模式: [--force]     │    │
+│  │ 删除                                  │    │
+│  └─────────────────────────────────────┘    │
+│                                              │
+│  ┌─────────────────────────────────────┐    │
+│  │ 维度: [▼ network]  域名: [example.*] │    │
+│  │ 删除                                  │    │
+│  └─────────────────────────────────────┘    │
+├─────────────────────────────────────────────┤
+│  [预览 YAML]  [保存规则]                     │
+└─────────────────────────────────────────────┘
+```
+
+#### 2.2 规则分组管理
+
+- 支持按用途分组（安全规则、工作流规则等）
+- 支持规则启用/禁用开关
+- 支持规则排序（优先级）
+
+#### 2.3 规则冲突检测
+
+- 检测规则间的冲突（deny vs allow）
+- 提示规则冗余（被更宽泛的规则覆盖）
+- 建议规则优化
+
+### Phase 3: 高级功能
+
+**目标**: 提供生产级规则管理能力
+
+#### 3.1 规则版本控制
+
+- 规则变更历史
+- 支持回滚到历史版本
+- 与 Git 集成（rules.yml 版本追踪）
+
+#### 3.2 规则导入/导出
+
+- 支持从其他 perm-gate 实例导入规则
+- 支持导出规则包
+- 支持从模板库导入
+
+#### 3.3 规则审计日志
+
+- 记录规则创建/修改/删除操作
+- 记录规则匹配历史
+- 支持审计日志查询
+
+---
+
+## 三、分支级权限可行性分析
+
+### 当前 YAML 能否实现 git push 分支级权限？
+
+#### 3.1 args 维度的匹配逻辑
+
+```typescript
+// evaluate.ts 第 76-81 行
+// args dimension: any token matches any args glob.
+if (rule.args.length > 0) {
+  const tokens: string[] = []
+  for (const cmd of commands) tokens.push(...cmd.args, ...cmd.redirects)
+  tokens.push(...pathCands, ...urlCands)
+  if (!tokens.some((tok) => rule.args.some((g) => g.re.test(tok)))) return false
+}
+```
+
+**关键发现：args 是 OR 逻辑，不是 AND 逻辑。**
+
+对于 `git push --force origin main`：
+- tokens = [`push`, `--force`, `origin`, `main`]
+- args 匹配规则：只要**任意一个 token** 匹配**任意一个 glob 模式**，规则就生效
+
+#### 3.2 能做什么
+
+```yaml
+# ✅ 拦截所有带 --force 的命令（不管是不是 push）
+- args: ["--force"]
+  level: deny
+  reason: "Force flag detected"
+
+# ✅ 拦截所有涉及 main 分支的命令
+- args: ["main"]
+  level: deny
+  reason: "Main branch target detected"
+
+# ✅ 拦截所有 git push 命令
+- command: [git]
+  args: ["push"]
+  level: confirm
+  reason: "Git push requires confirmation"
+```
+
+#### 3.3 不能做什么
+
+```yaml
+# ❌ 精确匹配 "git push --force origin main" 这个复合操作
+# 因为 args 是 OR 逻辑，无法要求多个 token 同时存在
+
+# ❌ 区分 "git push --force origin main" 和 "git checkout --force main"
+# 两者都有 --force 和 main，无法区分
+
+# ❌ 动态判断分支是"个人"还是"共享"
+# YAML 是静态 pattern，没有 git 查询能力
+
+# ❌ 匹配分支模式（如 release/*、feature/*）
+# args glob 不支持路径段匹配（segments=false）
+```
+
+#### 3.4 结论
+
+| 能力 | 状态 | 说明 |
+|------|------|------|
+| 拦截 force push | ⚠️ 部分可行 | 只能匹配 `--force` token，无法限定是 push 操作 |
+| 拦截特定分支 | ⚠️ 部分可行 | 只能硬编码分支名，无法判断共享属性 |
+| 复合条件匹配 | ❌ 不可行 | args 是 OR 逻辑，无法要求多个 token 同时存在 |
+| 运行时 git 查询 | ❌ 不可行 | YAML 是静态 pattern，无法调用 git 命令 |
+| 分支模式匹配 | ⚠️ 部分可行 | 可用 `release*` 匹配，但无法匹配路径段 |
+
+### 3.5 要实现真正的分支级权限，需要
+
+#### 方案 A: 新增 `branch` 维度
+
+```yaml
+permissions:
+  deny:
+    - branch:
+        target: "main|master|develop|release/*"
+        shared: true  # 动态判断是否共享
+      reason: "Force push to shared branch"
+```
+
+**实现要求**:
+- 运行时调用 `git branch -r --contains <branch>` 查询分支属性
+- 查询 `git log --format='%ae' <branch>` 获取提交者信息
+- 查询 `git config branch.<name>.remote` 获取远程仓库
+- 缓存查询结果（避免重复调用）
+- 添加超时机制（防止 git 命令卡住）
+
+#### 方案 B: 改造 args 为 AND 逻辑
+
+```yaml
+permissions:
+  deny:
+    - args_match: AND  # 新语法：要求所有条件同时满足
+        - "push"
+        - "--force"
+        - "origin"
+        - "main|master|develop"
+      reason: "Force push to shared branch"
+```
+
+**实现要求**:
+- 修改 args 维度的匹配逻辑（从 OR 改为 AND）
+- 添加新语法支持（`args_match: AND`）
+- 保持向后兼容（旧的 `args` 保持 OR 逻辑）
+
+#### 方案 C: 新增 `shared-branches` 配置
+
+```yaml
+# rules.yml 顶部配置
+shared_branches:
+  - main
+  - master
+  - develop
+  - "release/*"
+
+permissions:
+  deny:
+    - command: [git]
+      args: ["push", "--force"]
+      branch:
+        in: shared_branches  # 引用预定义列表
+      reason: "Force push to shared branch"
+```
+
+**实现要求**:
+- 新增 `shared_branches` 配置项
+- 新增 `branch` 维度，支持 `in` 操作符引用列表
+- 运行时解析分支名，匹配列表中的模式
+
+---
+
+## 四、建议的实施路径
+
+### 短期 (1-2 周)
+
+1. **Phase 1 UI 补全**: 集成 YAML 编辑器，暴露完整的规则编辑能力
+2. **文档更新**: 明确说明 YAML 规则的完整能力边界
+3. **临时方案**: 在文档中提供手动配置分支级权限的方法（硬编码分支名）
+
+### 中期 (1-2 月)
+
+1. **Phase 2 可视化编辑器**: 提供图形化规则创建界面
+2. **args AND 逻辑**: 改造 args 维度，支持复合条件匹配
+3. **规则测试功能**: 支持在 UI 中测试规则匹配结果
+
+### 长期 (3-6 月)
+
+1. **branch 维度**: 实现运行时 git 查询，支持动态分支判断
+2. **规则版本控制**: 支持规则变更历史和回滚
+3. **规则审计日志**: 记录规则匹配历史，支持审计
+
+---
+
+## 五、与 PerryLink dsh-auto-review 的对比总结
+
+| 维度 | dsh-perm-gate | dsh-auto-review | 差距分析 |
+|------|--------------|-----------------|----------|
+| 规则格式 | YAML 静态规则 | cordis patch 配置 | 格式不同，无法直接兼容 |
+| 匹配逻辑 | 模式匹配 (pattern) | AI 语义理解 | 各有优势：模式匹配快，语义理解准 |
+| 分支权限 | 不支持动态判断 | 不支持（无分支维度） | 两者都需要新增能力 |
+| UI 面板 | 简化接口，缺失 YAML 编辑器 | 完整配置面板 | 我们需要补全 UI |
+| 配置入口 | settings.yaml | cordis.patch.yml | 入口不同，无法直接融合 |
+| 执行速度 | < 10ms (静态匹配) | 3-60s (AI 审查) | 我们的速度优势明显 |
+
+**核心结论**: 两者是互补关系，不是替代关系。perm-gate 的静态规则适合确定性拦截（速度优先），auto-review 的 AI 审查适合模糊场景（精度优先）。分支级权限是两者都缺失的能力，需要各自实现。

package/dsh.plugin.json

@@ -0,0 +1,22 @@
+{
+  "id": "dsh-perm-gate",
+  "name": "dsh-perm-gate",
+  "version": "2.6.1",
+  "description": {
+    "en": "Deterministic-first, fail-closed permission gate for DeepSeek Harness 0.1.2+: a P0 hard-deny -> P1 precise session grant -> P2 static allow/deny rule chain -> P3 optional LLM classifier -> P4 ask pipeline over the tools/pre-execute waterfall, with a standalone CLI dry-run evaluator and an auditable decision log. It only vetoes with deny/ask and always delegates otherwise, and unknown or malformed rules fail loud instead of silently standing the gate down.",
+    "zh": "面向 DeepSeek Harness 0.1.2+ 的确定性优先、失败即拒的权限闸门：在 tools/pre-execute 瀑布上串起 P0 硬拒绝 → P1 精确会话授权 → P2 静态 allow/deny 规则链 → P3 可选 LLM 语义分类 → P4 ask，并附带独立 CLI 干跑评估器与可审计的决策日志。只以 deny/ask 否决、其余一律放行，规则未知或非法时直接报错，绝不静默失效。"
+  },
+  "homepage": "https://github.com/drscrewdriver/dsh-perm-gate",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/drscrewdriver/dsh-perm-gate.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "dsh": ">=0.1.2-alpha.1 <0.2.0-0"
+  },
+  "components": {
+    "host": "lib/index.js",
+    "client": "lib/client.js"
+  }
+}

package/examples/permissions.example.yaml

@@ -9,8 +9,23 @@ permissions:
       reason: no direct remote shell
     - paths: [.dsh/**]
       reason: protect harness metadata
+    # `command` matches the decomposed command WORD only (`git`), so the
+    # subcommand belongs in `args`. A multi-word entry such as `git pull` can
+    # never match — see docs/rules-format.md §4.2.
+    - command: [git]
+      args: [push]
+      branch:
+        target: [main, master, "release*"]
+        shared: true
+      reason: no push to a protected branch
   allow:
-    - command: [git pull, pnpm, node, npm run]
+    - command: [pnpm, node]
+      reason: routine project development
+    - command: [git]
+      args: [pull]
+      reason: routine project development
+    - command: [npm]
+      args: [run]
       reason: routine project development
     - command: [curl, wget]
       args: ["https://*.example.com/*"]