dsh-permission-rules 0.2.0

package/README.md

@@ -0,0 +1,182 @@
+<div align="center">
+
+# 🛡️ dsh-permission-rules
+
+**Claude Code-style declarative permission rules for DeepSeek Harness.**
+
+*Rules decide what is known. A reviewer model decides what is not.*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-permission-rules/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-permission-rules/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-permission-rules?label=version)](https://github.com/PerryLink/dsh-permission-rules/releases)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+## What it does
+
+`dsh-permission-rules` puts an ordered **`allow` / `deny` / `ask`** rule list in front of every tool call on the `tools/pre-execute` waterfall — deterministic, instant, auditable, and written by you in plain YAML:
+
+- **`deny`** blocks the call. The rule's `reason` becomes the model-visible error, so the agent learns *why* instead of retrying blindly.
+- **`ask`** rides the official approval seam. Mount `dsh-auto-review` alongside and the question is settled by a second model; otherwise a human answers; with neither, the harness fails closed.
+- **`allow`** (and no-match) strictly delegates via `next()` — downstream listeners are never short-circuited.
+
+Every hit **and** every passthrough is audit-logged as a `permissionRules/decision` session event (log-only — nothing extra is injected into the model context).
+
+```text
+tools/pre-execute waterfall                     approval/request waterfall (answerer chain)
+        │                                                   │
+  dsh-permission-rules                                dsh-auto-review answerer
+   · first-match rules in file order       ┌───────────────┴──────────────┐
+   · deny/ask claim the call               │ AI verdict (second model)     │ no ── next() ──▶ human UI
+   · allow/passthrough → next()            └───────────────┬──────────────┘
+        │ deny ──▶ denied tool result                     │ allowed-once / rejected
+        │ ask  ──▶ ctx.approval ──────────────────────────┘
+        │
+   audit: permissionRules/decision → approval/asked → autoReview/verdict → approval/decided
+```
+
+## Why rules *and* a reviewer?
+
+A second model answers *"is THIS call okay?"* with judgment, but costs a round-trip and can be wrong. Declarative rules answer deterministically, instantly, and without a model — but only cover what an admin wrote down. Combined, you get the **"rules first, AI backstop"** loop: rules decide the known, the reviewer decides the unknown.
+
+## Features
+
+- ✅ **Three-state semantics** — `allow`, `deny`, `ask`, evaluated in file order, first match wins
+- ✅ **Rich matching** — tool-name globs (including `mcp__*`), argument key/value globs **or** regexes (with `!pattern` negation and an `absent` key dimension), workspace-relative path globs extracted from documented argument keys at **any nesting depth**, and `when` host conditions (env vars, platform)
+- ✅ **Hierarchical rule files** — optional `searchUp` merges every `.dsh/rules.yaml` from the session cwd to the filesystem root, nearest first, so a child project can override parent rules
+- ✅ **Rule metadata** — `enabled: false`, `description`, `tags`; `/rules` warns about rules shadowed by an earlier catch-all
+- ✅ **Waterfall-safe** — `allow`/passthrough always call `next()`; only `deny`/`ask` short-circuit
+- ✅ **Official approval seam** — `ask` flows through `ctx.approval`; never re-implemented, never bypassed
+- ✅ **Full audit** — `permissionRules/decision` events carry the rule action AND the final outcome for every call; `/rules decisions` replays the trail in-session
+- ✅ **Dry-run testing** — `/rules test <tool> <json-args>` evaluates the active rules without executing anything
+- ✅ **Hot reload** — Chokidar watch with debounce; a broken edit keeps the previous rules, never crashes
+- ✅ **Fail loud** — invalid YAML, unknown actions/fields, bad globs/regexes, backtracking-prone patterns, or > `maxRules` fail the load
+- ✅ **Bounded hot path** — precompiled matchers, O(rules × patterns), capped by `maxRules`; glob backtracking degree capped by `maxGlobStars`
+
+## Quick start
+
+```sh
+# 1. install the bundle into your profile
+dsh plugin --profile web add "github:PerryLink/dsh-permission-rules#main"
+
+# or from a packed tarball (built artifacts, no build permission needed)
+pnpm pack
+dsh plugin --profile web add ./dsh-permission-rules-0.1.1.tgz
+
+# 2. restart
+dsh --profile web
+```
+
+Then create the rules file for your project and start a session in it:
+
+```yaml
+# <project>/.dsh/rules.yaml
+rules:
+  - match: { tools: [bash, pwsh], params: { command: "git push*" }, paths: ["**/secrets/**"] }
+    action: deny
+    reason: "No pushes from protected paths"
+
+  - match: { tools: [edit, write] }
+    action: ask
+    reason: "File writes need confirmation"
+```
+
+```sh
+dsh --profile web --dump-config | grep -A4 'id: permission-rules'   # verify the row
+```
+
+A complete 5-rule security baseline and the full schema live in [docs/rules-format.en.md](docs/rules-format.en.md).
+
+## Configuration
+
+All tunables are Schemastery `Config` fields (changeable from cordis.yml). An id-targeted override replaces the whole row — restate every key you need.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `rulesFile` | `.dsh/rules.yaml` | Rule file location; relative = resolved against the calling session's cwd, absolute = global and validated at mount |
+| `fallbackPath` | *(none)* | Rule file used when per-cwd discovery finds nothing; validated at mount |
+| `badFilePolicy` | `fail` | Bad rule file: `fail` errors the pending tool call loudly (reloads keep the previous rules); `ignore-with-warning` warns and continues empty |
+| `maxRules` | `256` | Hard cap on rule count across the effective source chain; larger files fail the load |
+| `maxCachedWorkspaces` | `512` | Hard cap on cached per-workspace rule loads; the least-recently-used workspace (and its watcher) is evicted beyond it |
+| `patternMode` | `glob` | `params`/`paths`/`when.env` pattern flavor: `glob` or `regex` (tool names are always globs) |
+| `watch` | `true` | Chokidar watch + reload on change |
+| `watchStabilityThresholdMs` | `200` | Reload debounce window (ms) |
+| `language` | `en` | `/rules` output language: `en`, `zh`, `es`, `pt`, `hi` (`en`/`zh` are the reference translations) |
+| `caseInsensitivePaths` | *(win32)* | `paths` patterns and workspace-root comparison ignore ASCII case; defaults to `true` on Windows, `false` elsewhere |
+| `audit` | `all` | Audit granularity: `all` logs every hit AND passthrough; `hits` skips passthrough events |
+| `searchUp` | `false` | Walk parent directories from the session cwd and merge every found rule file, nearest first |
+| `maxGlobStars` | `2` | Hard cap on unbounded `*`/`**` quantifiers per glob pattern (backtracking-degree bound) |
+
+### Session commands
+
+```
+/rules                        list the active rules, their source files, and any last-reload error
+/rules reload                 re-read the rule-file chain for this workspace
+/rules decisions [n]          show the last n permission decisions of this session (default 10)
+/rules test <tool> <json>     dry-evaluate the rules against a hypothetical call, e.g. /rules test bash {"command":"git push origin main"}
+```
+
+Command output is UI-only — the model learns the rules only through the tool results they produce. `language` picks the output language. A JSON Schema for the rule file ships at [docs/rules-format.schema.json](docs/rules-format.schema.json) (wire it up with `# yaml-language-server: $schema=...` for editor completion).
+
+## Collaborating with dsh-auto-review
+
+- `dsh-permission-rules` produces `ask`; `dsh-auto-review` answers on the `approval/request` waterfall with a read-only second-model verdict (or delegates to humans). Mount both for the full closed loop.
+- Integration-tested (`test/integration.spec.ts`): `permissionRules/decision` → `approval/asked` → `autoReview/verdict` → `approval/decided`, with the reviewer replaced by a scripted mock.
+- The `never` approval policy and every fail-closed guarantee of the [official harness](https://github.com/deepseek-ai/deepseek-harness) stay untouched.
+
+## Security boundaries
+
+- **Policy, not a kernel.** `paths` candidates come only from a documented set of argument keys (at any nesting depth, depth-capped), and only workspace-relative paths match.
+- **No reviewer here.** The plugin never spawns subagents or calls models — producing an `ask` decision is the end of its work.
+- **No sandbox changes.** OS-level sandbox policy belongs to the sandbox seam, not this plugin.
+- **Loud misconfiguration.** Unknown YAML fields, unknown actions, and bad patterns are rejected at load, never silently ignored.
+- **Backtracking bounds.** Glob patterns are capped at `maxGlobStars` unbounded star expansions; regex-mode patterns reject nested unbounded quantifiers and quantified overlapping literal alternations. (Regex chains like `\d+\.\d+\.\d+` stay allowed — regex mode is the escape hatch, glob mode is the guarded default.)
+
+## Related work
+
+- [Andy8647/dsh-auto-approval](https://github.com/Andy8647/dsh-auto-approval) — two-state allow/deny classifier with its own file-log audit; this plugin adds the full three-state semantics, declarative YAML rules, session-log audit, and `next()`-safe delegation.
+- `Drifter-yh/dsh-tool-policy` — deny-by-default tool policy; documented here to avoid duplicate implementation.
+- `dsh-auto-review` — the AI-backstop half of the loop this plugin fronts.
+
+## Known limitations
+
+- `permissionRules/decision` is appended with the envelope's `ignorable: true` marker, so any harness build loads the log — readers that do not know the out-of-repo type simply skip the audit record instead of refusing the session. (rc.6 hosts accept and ignore the marker, keeping the exact pre-marker behavior; sessions written on rc.6 hosts lack the marker and may need `scripts/repair-session-logs.mjs` before loading on hosts with required-on-read semantics.)
+- `paths` candidates are heuristic: only the documented argument keys feed path matching, and workspace-relative matching is ASCII-case-insensitive only when `caseInsensitivePaths` is on.
+- Globs are a conservative subset (no brace expansion) — write two patterns, or use regex mode.
+- The regex backtracking guard is structural, not exhaustive: alternation-ambiguity cases without literal prefixes (e.g. crafted lookarounds) are the author's responsibility; prefer glob mode for untrusted files.
+
+## Session log repair
+
+Session logs written before the `ignorable` marker existed can be refused by newer harness builds (`SessionFormatUnsupportedError`). The shipped `scripts/repair-session-logs.mjs` rewrites only the targeted audit rows to carry `ignorable: true`, frame-preserving, with backups:
+
+```sh
+node scripts/repair-session-logs.mjs scan [--home DIR]      # report foreign rows, change nothing
+node scripts/repair-session-logs.mjs repair [--home DIR] [--dry-run]
+```
+
+`--home` defaults to `$DSH_HOME/sessions` (or `~/.dsh/sessions`). See the script header for the full contract.
+
+## Development
+
+```sh
+pnpm install        # node ^22.19 || >=24
+pnpm run typecheck  # tsc, src + tests
+pnpm run lint       # eslint, src + tests + scripts
+pnpm test           # vitest: 106 tests, 8 suites
+pnpm run test:coverage  # coverage gate (90/80/90/90)
+pnpm run build      # tsc declarations + tsdown bundles (lib/)
+pnpm run pack:check # build + pack (the published artifact)
+node scripts/check-readme-sync.mjs  # five-language README sync gate (also in CI)
+```
+
+See [VERIFICATION.md](VERIFICATION.md) for the headless end-to-end verification record (deny blocking a shell tool, ask routing through the approval seam, `--dump-config`).
+
+## License
+
+[Apache License 2.0](LICENSE) © 2026 dsh-permission-rules contributors

package/README.pt.md

@@ -0,0 +1,182 @@
+<div align="center">
+
+# 🛡️ dsh-permission-rules
+
+**Regras de permissão declarativas estilo Claude Code para o DeepSeek Harness.**
+
+*As regras decidem o que é conhecido. Um modelo revisor decide o que não é.*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-permission-rules/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-permission-rules/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-permission-rules?label=version)](https://github.com/PerryLink/dsh-permission-rules/releases)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+## O que ele faz
+
+O `dsh-permission-rules` coloca uma lista ordenada de regras **`allow` / `deny` / `ask`** na frente de cada chamada de ferramenta no waterfall `tools/pre-execute` — determinístico, instantâneo, auditável e escrito por você em YAML puro:
+
+- **`deny`** bloqueia a chamada. O `reason` da regra vira o erro visível para o modelo, para que o agente aprenda o *porquê* em vez de tentar de novo às cegas.
+- **`ask`** usa o seam de aprovação oficial. Monte o `dsh-auto-review` junto e a pergunta é decidida por um segundo modelo; caso contrário, um humano responde; sem nenhum dos dois, o harness falha fechado (fail-closed).
+- **`allow`** (e a ausência de correspondência) delega estritamente via `next()` — os listeners seguintes nunca são curto-circuitados.
+
+Cada acerto **e** cada passagem direta é auditado como evento de sessão `permissionRules/decision` (somente registro — nada extra é injetado no contexto do modelo).
+
+```text
+waterfall tools/pre-execute                     waterfall approval/request (cadeia de answerers)
+        │                                                   │
+  dsh-permission-rules                                answerer dsh-auto-review
+   · primeira correspondência em ordem ┌───────────────────┴──────────────┐
+   · deny/ask reivindicam a chamada    │ veredito de IA (segundo modelo)    │ não ── next() ──▶ UI humana
+   · allow/passagem → next()           └───────────────────┬──────────────┘
+        │ deny ──▶ resultado negado                     │ allowed-once / rejected
+        │ ask  ──▶ ctx.approval ────────────────────────┘
+        │
+   auditoria: permissionRules/decision → approval/asked → autoReview/verdict → approval/decided
+```
+
+## Por que regras *e* um revisor?
+
+Um segundo modelo responde *"ESTA chamada é segura?"* com julgamento, mas custa uma ida e volta e pode errar. Regras declarativas respondem de forma determinística, instantânea e sem modelo — mas só cobrem o que um administrador escreveu. Combinados, você obtém o ciclo **"regras primeiro, IA de apoio"**: as regras decidem o conhecido, o revisor decide o desconhecido.
+
+## Funcionalidades
+
+- ✅ **Semântica de três estados** — `allow`, `deny`, `ask`, avaliadas na ordem do arquivo; a primeira correspondência vence
+- ✅ **Correspondência rica** — globs de nome de ferramenta (incluindo `mcp__*`), globs **ou** regex de chave/valor de argumentos (com negação `!pattern` e a dimensão de chave `absent`), globs de caminhos relativos ao workspace extraídos de chaves de argumentos documentadas em **qualquer profundidade de aninhamento**, e condições de host `when` (variáveis de ambiente, plataforma)
+- ✅ **Arquivos de regras hierárquicos** — `searchUp` opcional combina cada `.dsh/rules.yaml` do cwd da sessão até a raiz do sistema de arquivos, o mais próximo primeiro, para que um projeto filho possa sobrescrever regras do pai
+- ✅ **Metadados de regras** — `enabled: false`, `description`, `tags`; `/rules` avisa sobre regras encobertas por um catch-all anterior
+- ✅ **Seguro para o waterfall** — `allow`/passagem sempre chamam `next()`; somente `deny`/`ask` curto-circuitam
+- ✅ **Seam de aprovação oficial** — `ask` flui por `ctx.approval`; nunca reimplementado, nunca contornado
+- ✅ **Auditoria completa** — os eventos `permissionRules/decision` carregam a ação da regra E o resultado final de cada chamada; `/rules decisions` reproduz o rastro na sessão
+- ✅ **Teste em seco** — `/rules test <tool> <json-args>` avalia as regras ativas sem executar nada
+- ✅ **Recarga a quente** — vigilância Chokidar com debounce; uma edição quebrada mantém as regras anteriores, nunca quebra
+- ✅ **Falha ruidosa** — YAML inválido, ações/campos desconhecidos, globs/regex ruins, padrões propensos a backtracking ou > `maxRules` fazem a carga falhar
+- ✅ **Caminho quente limitado** — matchers pré-compilados, O(regras × padrões), limitado por `maxRules`; o grau de backtracking de glob limitado por `maxGlobStars`
+
+## Início rápido
+
+```sh
+# 1. instale o bundle no seu perfil
+dsh plugin --profile web add "github:PerryLink/dsh-permission-rules#main"
+
+# ou a partir de um tarball empacotado (artefatos compilados, sem permissão de build)
+pnpm pack
+dsh plugin --profile web add ./dsh-permission-rules-0.1.1.tgz
+
+# 2. reinicie
+dsh --profile web
+```
+
+Depois crie o arquivo de regras do seu projeto e inicie uma sessão nele:
+
+```yaml
+# <project>/.dsh/rules.yaml
+rules:
+  - match: { tools: [bash, pwsh], params: { command: "git push*" }, paths: ["**/secrets/**"] }
+    action: deny
+    reason: "Sem push a partir de caminhos protegidos"
+
+  - match: { tools: [edit, write] }
+    action: ask
+    reason: "Escrita de arquivos precisa de confirmação"
+```
+
+```sh
+dsh --profile web --dump-config | grep -A4 'id: permission-rules'   # verifique a linha
+```
+
+Uma linha de base de segurança completa com 5 regras e o esquema completo estão em [docs/rules-format.en.md](docs/rules-format.en.md).
+
+## Configuração
+
+Todos os ajustes são campos `Config` do Schemastery (alteráveis no cordis.yml). Uma sobrescrita direcionada por id substitui a linha inteira — reescreva todas as chaves que você precisa.
+
+| Chave | Padrão | Significado |
+|---|---|---|
+| `rulesFile` | `.dsh/rules.yaml` | Local do arquivo de regras; relativo = resolvido contra o cwd da sessão, absoluto = global e validado na montagem |
+| `fallbackPath` | *(nenhum)* | Arquivo de regras usado quando a descoberta por cwd não encontra nada; validado na montagem |
+| `badFilePolicy` | `fail` | Arquivo ruim: `fail` faz a chamada pendente falhar ruidosamente (recargas mantêm as regras anteriores); `ignore-with-warning` avisa e segue vazio |
+| `maxRules` | `256` | Limite rígido de regras em toda a cadeia de fontes efetiva; arquivos maiores falham a carga |
+| `maxCachedWorkspaces` | `512` | Limite rígido de cargas de regras por workspace em cache; além dele o menos usado recentemente (e seu watcher) é expulso |
+| `patternMode` | `glob` | Sabor dos padrões de `params`/`paths`/`when.env`: `glob` ou `regex` (nomes de ferramenta sempre são globs) |
+| `watch` | `true` | Vigilância Chokidar + recarga ao mudar |
+| `watchStabilityThresholdMs` | `200` | Janela de debounce da recarga (ms) |
+| `language` | `en` | Idioma da saída do `/rules`: `en`, `zh`, `es`, `pt`, `hi` (`en`/`zh` são as traduções de referência) |
+| `caseInsensitivePaths` | *(win32)* | Padrões de `paths` e comparação com a raiz do workspace ignoram maiúsculas ASCII; por padrão `true` no Windows, `false` nos demais |
+| `audit` | `all` | Granularidade da auditoria: `all` registra cada acerto E passagem; `hits` pula eventos de passagem |
+| `searchUp` | `false` | Percorre os diretórios pais a partir do cwd da sessão e combina cada arquivo de regras encontrado, o mais próximo primeiro |
+| `maxGlobStars` | `2` | Limite rígido de quantificadores `*`/`**` ilimitados por padrão glob (cota do grau de backtracking) |
+
+### Comandos de sessão
+
+```
+/rules                        lista as regras ativas, seus arquivos de origem e qualquer erro da última recarga
+/rules reload                 relê a cadeia de arquivos de regras deste workspace
+/rules decisions [n]          mostra as últimas n decisões de permissão desta sessão (padrão 10)
+/rules test <tool> <json>     avalia em seco as regras contra uma chamada hipotética, ex.: /rules test bash {"command":"git push origin main"}
+```
+
+A saída dos comandos é somente UI — o modelo aprende as regras apenas pelos resultados de ferramenta que elas produzem. `language` escolhe o idioma da saída. Um JSON Schema do arquivo de regras é distribuído em [docs/rules-format.schema.json](docs/rules-format.schema.json) (conecte-o com `# yaml-language-server: $schema=...` para autocompletar no editor).
+
+## Colaboração com o dsh-auto-review
+
+- O `dsh-permission-rules` produz `ask`; o `dsh-auto-review` responde no waterfall `approval/request` com um veredito de um segundo modelo somente leitura (ou delega para humanos). Monte os dois para o ciclo completo.
+- Testado em integração (`test/integration.spec.ts`): `permissionRules/decision` → `approval/asked` → `autoReview/verdict` → `approval/decided`, com o revisor substituído por um mock.
+- A política de aprovação `never` e todas as garantias fail-closed do [harness oficial](https://github.com/deepseek-ai/deepseek-harness) permanecem intactas.
+
+## Limites de segurança
+
+- **Política, não kernel.** Os candidatos de `paths` vêm apenas de um conjunto documentado de chaves de argumentos, e somente caminhos relativos ao workspace correspondem.
+- **Nenhum revisor aqui.** O plugin nunca lança subagentes nem chama modelos — produzir uma decisão `ask` é o fim do seu trabalho.
+- **Sem mudanças de sandbox.** A política de sandbox no nível do SO pertence ao seam de sandbox, não a este plugin.
+- **Configuração errada ruidosa.** Campos YAML desconhecidos, ações desconhecidas e padrões ruins são rejeitados na carga, nunca ignorados em silêncio.
+- **Limites de backtracking.** Padrões glob são limitados a `maxGlobStars` expansões de estrela ilimitadas; padrões em modo regex rejeitam quantificadores aninhados ilimitados e alternâncias literais sobrepostas quantificadas. (Cadeias regex como `\d+\.\d+\.\d+` permanecem permitidas — o modo regex é a válvula de escape, o modo glob é o padrão protegido.)
+
+## Trabalho relacionado
+
+- [Andy8647/dsh-auto-approval](https://github.com/Andy8647/dsh-auto-approval) — classificador allow/deny de dois estados com auditoria em arquivo próprio; este plugin adiciona a semântica completa de três estados, regras YAML declarativas, auditoria no log de sessão e delegação segura com `next()`.
+- `Drifter-yh/dsh-tool-policy` — política de ferramentas deny-by-default; documentada aqui para evitar implementação duplicada.
+- `dsh-auto-review` — a metade de apoio de IA do ciclo que este plugin lidera.
+
+## Limitações conhecidas
+
+- `permissionRules/decision` é anexado com o marcador de envelope `ignorable: true`, então qualquer build do harness carrega o log — leitores que não conhecem o tipo fora do repositório simplesmente pulam o registro de auditoria em vez de recusar a sessão. (Hosts rc.6 aceitam e ignoram o marcador, mantendo exatamente o comportamento anterior; sessões gravadas em hosts rc.6 não têm o marcador e podem precisar de `scripts/repair-session-logs.mjs` antes de carregar em hosts com semântica required-on-read.)
+- Os candidatos de `paths` são heurísticos: apenas as chaves de argumentos documentadas alimentam a correspondência de caminhos, e a correspondência relativa ao workspace ignora maiúsculas ASCII somente quando `caseInsensitivePaths` está ativo.
+- Os globs são um subconjunto conservador (sem expansão de chaves) — escreva dois padrões ou use o modo regex.
+- O guard de backtracking de regex é estrutural, não exaustivo: casos de ambiguidade por alternância sem prefixos literais (ex.: lookarounds elaborados) são responsabilidade do autor; prefira o modo glob para arquivos não confiáveis.
+
+## Reparo de registros de sessão
+
+Registros de sessão gravados antes do marcador `ignorable` podem ser recusados por builds mais novos do harness (`SessionFormatUnsupportedError`). O `scripts/repair-session-logs.mjs` incluído reescreve apenas as linhas de auditoria alvo para adicionar `ignorable: true`, preservando os frames, com backups:
+
+```sh
+node scripts/repair-session-logs.mjs scan [--home DIR]      # relata linhas externas, sem alterar
+node scripts/repair-session-logs.mjs repair [--home DIR] [--dry-run]
+```
+
+`--home` por padrão é `$DSH_HOME/sessions` (ou `~/.dsh/sessions`). O contrato completo está no cabeçalho do script.
+
+## Desenvolvimento
+
+```sh
+pnpm install        # node ^22.19 || >=24
+pnpm run typecheck  # tsc, src + tests
+pnpm run lint       # eslint, src + tests + scripts
+pnpm test           # vitest: 106 tests, 8 suites
+pnpm run test:coverage  # portão de cobertura (90/80/90/90)
+pnpm run build      # declarações tsc + bundles tsdown (lib/)
+pnpm run pack:check # build + pack (o artefato publicado)
+node scripts/check-readme-sync.mjs  # portão de sincronização dos READMEs em cinco idiomas (também na CI)
+```
+
+Veja [VERIFICATION.md](VERIFICATION.md) para o registro de verificação headless de ponta a ponta (deny bloqueando uma ferramenta de shell, ask roteado pelo seam de aprovação, `--dump-config`).
+
+## Licença
+
+[Apache License 2.0](LICENSE) © 2026 dsh-permission-rules contributors

package/README.zh.md

@@ -0,0 +1,182 @@
+<div align="center">
+
+# 🛡️ dsh-permission-rules
+
+**DeepSeek Harness 的 Claude Code 式声明式权限规则。**
+
+*规则裁决已知，reviewer 模型裁决未知。*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-permission-rules/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-permission-rules/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-permission-rules?label=version)](https://github.com/PerryLink/dsh-permission-rules/releases)
+
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
+
+</div>
+
+---
+
+## 它能做什么
+
+`dsh-permission-rules` 在 `tools/pre-execute` waterfall 上为每一次工具调用放置一个有序的 **`allow` / `deny` / `ask`** 规则列表——确定性、零延迟、可审计，规则用你写的普通 YAML 声明：
+
+- **`deny`** 阻止调用。规则的 `reason` 成为模型可见的错误，让 agent 知道*为什么*而不是盲目重试。
+- **`ask`** 走官方审批 seam。同时挂载 `dsh-auto-review` 时由第二模型裁决；否则人类审批；两者都没有时 harness fail-closed。
+- **`allow`**（以及无命中）严格通过 `next()` 委托——绝不短路下游监听器。
+
+每次命中**和**每次透传都会以 `permissionRules/decision` 会话事件审计落盘（log-only，不向模型上下文注入任何额外内容）。
+
+```text
+tools/pre-execute waterfall                     approval/request waterfall（answerer 链）
+        │                                                   │
+  dsh-permission-rules                                dsh-auto-review answerer
+   · 按文件顺序首条命中                    ┌───────────────┴──────────────┐
+   · deny/ask 认领调用                    │ 第二模型裁决                  │ 否 ── next() ──▶ 人类 UI
+   · allow/透传 → next()                 └───────────────┬──────────────┘
+        │ deny ──▶ 被拒工具结果                         │ allowed-once / rejected
+        │ ask  ──▶ ctx.approval ────────────────────────┘
+        │
+   审计：permissionRules/decision → approval/asked → autoReview/verdict → approval/decided
+```
+
+## 为什么既要有规则又要有 reviewer？
+
+第二模型回答*"这次调用行不行"*有判断力，但每次都要一次模型往返，也可能判错。声明式规则确定性、即时、不跑模型——但只能覆盖管理员写下来的情形。两者组合就是 **"规则先行、AI 兜底"** 闭环：规则裁决已知，reviewer 裁决未知。
+
+## 特性
+
+- ✅ **三态语义** — `allow`、`deny`、`ask`，按文件顺序求值，首条命中生效
+- ✅ **丰富匹配** — 工具名 glob（含 `mcp__*`）、参数键值 glob **或** 正则（支持 `!pattern` 否定与 `absent` 键维度）、工作区相对路径 glob（从文档化参数键在**任意嵌套深度**提取候选），以及 `when` 宿主条件（环境变量、平台）
+- ✅ **分层规则文件** — 可选 `searchUp` 从会话 cwd 向上逐级合并每份 `.dsh/rules.yaml`（最近的优先），子项目可覆盖父级规则
+- ✅ **规则元数据** — `enabled: false`、`description`、`tags`；`/rules` 会告警被前面通配规则遮蔽的规则
+- ✅ **waterfall 安全** — `allow`/透传一律 `next()`；只有 `deny`/`ask` 短路
+- ✅ **官方审批 seam** — `ask` 走 `ctx.approval`；不重复实现、绝不绕过
+- ✅ **完整审计** — `permissionRules/decision` 事件同时记录规则动作与最终裁决；`/rules decisions` 可在会话内回放审计轨迹
+- ✅ **干跑测试** — `/rules test <工具> <json-参数>` 不执行任何东西地评估规则命中
+- ✅ **热更新** — Chokidar 监视 + 去抖；改坏了保留旧规则，绝不崩溃
+- ✅ **响亮失败** — 非法 YAML、未知字段/action、坏 glob/正则、易回溯灾难的模式、超过 `maxRules` 都使加载失败
+- ✅ **热路径有界** — 预编译匹配器，O(规则数 × 模式数)，`maxRules` 封顶；glob 回溯度由 `maxGlobStars` 封顶
+
+## 快速开始
+
+```sh
+# 1. 把 bundle 装进 profile
+dsh plugin --profile web add "github:PerryLink/dsh-permission-rules#main"
+
+# 或从打包好的 tarball 安装（预构建产物，无需构建许可）
+pnpm pack
+dsh plugin --profile web add ./dsh-permission-rules-0.1.1.tgz
+
+# 2. 重启
+dsh --profile web
+```
+
+然后在你的项目里创建规则文件，并在其中启动会话：
+
+```yaml
+# <project>/.dsh/rules.yaml
+rules:
+  - match: { tools: [bash, pwsh], params: { command: "git push*" }, paths: ["**/secrets/**"] }
+    action: deny
+    reason: "禁止从受保护路径 push"
+
+  - match: { tools: [edit, write] }
+    action: ask
+    reason: "写文件需要确认"
+```
+
+```sh
+dsh --profile web --dump-config | grep -A4 'id: permission-rules'   # 验证挂载行
+```
+
+完整的 5 条安全基线示例与完整 schema 见 [docs/rules-format.md](docs/rules-format.md)。
+
+## 配置
+
+所有可调参数都是 Schemastery `Config` 字段（可在 cordis.yml 修改）。按 id 的覆盖会整行替换——覆盖时请重写所有需要的键。
+
+| 键 | 默认 | 含义 |
+|---|---|---|
+| `rulesFile` | `.dsh/rules.yaml` | 规则文件位置；相对值 = 按调用会话 cwd 解析，绝对值 = 全局生效并在挂载时校验 |
+| `fallbackPath` | 无 | cwd 发现不到时使用的回退规则文件；挂载时校验 |
+| `badFilePolicy` | `fail` | 坏规则文件处理：`fail` 让待处理工具调用响亮失败（重读保留旧规则）；`ignore-with-warning` 告警后以空集继续 |
+| `maxRules` | `256` | 生效规则链的总规则数硬上界，超限加载失败 |
+| `maxCachedWorkspaces` | `512` | 按工作区缓存的规则装载硬上界；超出时逐出最久未用工作区（连同其 watcher） |
+| `patternMode` | `glob` | `params`/`paths`/`when.env` 模式类型：`glob` 或 `regex`（工具名始终是 glob） |
+| `watch` | `true` | Chokidar 监视并在变更时重读 |
+| `watchStabilityThresholdMs` | `200` | 重读去抖窗口（毫秒） |
+| `language` | `en` | `/rules` 输出语言：`en`、`zh`、`es`、`pt`、`hi`（`en`/`zh` 为参考译文） |
+| `caseInsensitivePaths` | *（win32）* | `paths` 模式与工作区根比较忽略 ASCII 大小写；Windows 默认 `true`，其余平台默认 `false` |
+| `audit` | `all` | 审计粒度：`all` 记录每次命中与透传；`hits` 跳过透传事件 |
+| `searchUp` | `false` | 从会话 cwd 向上逐级查找并合并规则文件，最近的优先 |
+| `maxGlobStars` | `2` | 每个 glob 模式的无界 `*`/`**` 量词数硬上界（回溯度封顶） |
+
+### 会话命令
+
+```
+/rules                        列出当前生效规则、来源文件与最近一次重载错误
+/rules reload                 重读本工作区的规则文件链
+/rules decisions [n]          显示本会话最近 n 条权限裁决（默认 10）
+/rules test <工具> <json>     对假设调用干跑评估，如 /rules test bash {"command":"git push origin main"}
+```
+
+命令输出只进 UI——模型只通过规则产生的工具结果感知规则。`language` 选择输出语言。规则文件的 JSON Schema 随包发布在 [docs/rules-format.schema.json](docs/rules-format.schema.json)（用 `# yaml-language-server: $schema=...` 启用编辑器补全）。
+
+## 与 dsh-auto-review 协作
+
+- `dsh-permission-rules` 产出 `ask`；`dsh-auto-review` 在 `approval/request` waterfall 上用只读第二模型裁决（或转交人类）。两者同挂载即完整闭环。
+- 已做集成测试（`test/integration.spec.ts`）：`permissionRules/decision` → `approval/asked` → `autoReview/verdict` → `approval/decided`，reviewer 以脚本化 mock 替代。
+- [官方 harness](https://github.com/deepseek-ai/deepseek-harness) 的 `never` 审批策略与全部 fail-closed 保证不受影响。
+
+## 安全边界
+
+- **是策略，不是内核。**`paths` 候选只来自文档化的参数键集合（任意嵌套深度、深度封顶），且只匹配工作区相对路径。
+- **不自己起 reviewer。**本插件不 spawn 子代理、不调模型——产出 `ask` 决定就是它工作的终点。
+- **不改沙箱。**OS 级沙箱策略属于 sandbox seam，不属于本插件。
+- **响亮拒绝错误配置。**未知 YAML 字段、未知 action、坏模式在加载期被拒绝，绝不静默忽略。
+- **回溯有界。**glob 模式的无界星号量词数由 `maxGlobStars` 封顶；regex 模式拒绝嵌套无界量词与量化重叠字面量交替。（`\d+\.\d+\.\d+` 这类独立量词链仍然放行——regex 模式是逃生舱，glob 模式是受守护的默认。）
+
+## 相关实现
+
+- [Andy8647/dsh-auto-approval](https://github.com/Andy8647/dsh-auto-approval) — 二态 allow/deny 分类器，审计走自有文件日志；本插件补齐三态语义、声明式 YAML 规则、会话日志审计与 `next()` 安全委托。
+- `Drifter-yh/dsh-tool-policy` — deny-by-default 工具策略；在此声明差异化，避免重复实现。
+- `dsh-auto-review` — 本插件所前置的"AI 兜底"半环。
+
+## 已知局限
+
+- `permissionRules/decision` 以信封 `ignorable: true` 标记写入，任何 harness 构建都能加载日志——不认识该仓库外类型的第一方读取器会跳过这条审计记录而不是拒绝整个会话。（rc.6 宿主会接受并忽略该标记，行为与打标前完全一致；rc.6 宿主写出的日志没有该标记，在 required-on-read 语义的宿主上加载前可能需要 `scripts/repair-session-logs.mjs`。）
+- `paths` 候选是启发式的：只有文档化的参数键进入路径匹配；工作区相对匹配仅在 `caseInsensitivePaths` 开启时忽略 ASCII 大小写。
+- glob 是保守子集（不支持花括号展开）——写两条模式，或用 regex 模式。
+- regex 回溯守卫是结构性的而非穷尽的：不含字面量前缀的交替歧义（如精心构造的环视）由作者自负其责；不可信文件请优先用 glob 模式。
+
+## 会话日志修复
+
+`ignorable` 标记出现之前的会话日志可能被较新的 harness 构建拒绝（`SessionFormatUnsupportedError`）。随包发布的 `scripts/repair-session-logs.mjs` 只改写目标审计行、补上 `ignorable: true`，帧边界保留并自动备份：
+
+```sh
+node scripts/repair-session-logs.mjs scan [--home DIR]      # 只报告外来行，不改动
+node scripts/repair-session-logs.mjs repair [--home DIR] [--dry-run]
+```
+
+`--home` 默认为 `$DSH_HOME/sessions`（或 `~/.dsh/sessions`）。完整约定见脚本头注释。
+
+## 开发
+
+```sh
+pnpm install        # node ^22.19 || >=24
+pnpm run typecheck  # tsc，src + tests
+pnpm run lint       # eslint，src + tests + scripts
+pnpm test           # vitest：106 测试 / 8 套件
+pnpm run test:coverage  # 覆盖率门禁（90/80/90/90）
+pnpm run build      # tsc 声明 + tsdown 打包（lib/）
+pnpm run pack:check # 构建 + pack（发布产物）
+node scripts/check-readme-sync.mjs  # 五语 README 同步门禁（CI 同步执行）
+```
+
+headless 端到端验证记录（deny 阻止 shell 工具、ask 走审批 seam、`--dump-config`）见 [VERIFICATION.md](VERIFICATION.md)。
+
+## License
+
+[Apache License 2.0](LICENSE) © 2026 dsh-permission-rules contributors

package/cordis.patch.yml

@@ -0,0 +1,16 @@
+# dsh-permission-rules bundle patch: mount the declarative permission-rule
+# listener. `name` is the package name, resolved through the profile's
+# node_modules. An id-targeted override replaces the whole config row —
+# restate every key when overriding. Full schema and config vocabulary:
+# README.md and docs/rules-format.schema.json.
+- insert:
+    - id: permission-rules
+      name: dsh-permission-rules
+      config:
+        # Rule file discovered per session cwd (<cwd>/.dsh/rules.yaml);
+        # see docs/rules-format.md for the full rule vocabulary.
+        rulesFile: .dsh/rules.yaml
+        badFilePolicy: fail
+        maxRules: 256
+        patternMode: glob
+        watch: true