dsh-permission-rules 0.4.2 → 0.5.2

package/README.pt.md

@@ -4,7 +4,7 @@
 
 **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 é.*
+*Regras decidem o 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)
@@ -20,176 +20,219 @@
 
 ---
 
-## O que ele faz
+## Compatibility
 
-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:
+| Surface | Status |
+|---|---|
+| Harness | DeepSeek Harness `0.1.0-rc.5`–`0.1.0-rc.6` |
+| Node | `^22.19.0 || >=24.0.0` |
+| Platforms | Todas (host + cliente web de settings) |
+| Model | Qualquer (razões deny/ask aparecem pelos resultados de ferramenta) |
 
-- **`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.
+## What you get
 
-Cada acerto **e** cada passagem direta é auditado como evento de sessão `permissionRules/decision` (somente registro — nada extra é injetado no contexto do modelo).
+O `dsh-permission-rules` antepõe uma lista ordenada de regras **`allow` / `deny` / `ask`** a cada chamada de ferramenta na cascata `tools/pre-execute` — determinística, instantânea, auditável e escrita por você em YAML puro:
 
-```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__*`), seletores de identidade de agente (`main` / `subagent` / `preset:*`), 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, o cwd do workspace E o resultado final de cada chamada; `/rules decisions` reproduz o rastro na sessão; hosts anteriores ao marcador de envelope de auditoria degradam para auditoria desativada com um aviso único em vez de gravar registros irrecuperáveis (`allowUnmarkedAudit` reativa)
-- ✅ **Implantação em simulação** — `enforce: false` audita o que a política *faria* (ação hipotética + resultado real posterior, marcado com `dryRun`) enquanto deixa todas as chamadas passarem; teste seguro de políticas em produção
-- ✅ **Teste em seco** — `/rules test <tool> <json-args>` avalia as regras ativas sem executar nada, com sobrescritas `--cwd`, `--env`, `--agent` e `--platform` para cada dimensão
-- ✅ **Recarga a quente** — vigilância Chokidar com debounce; uma edição quebrada mantém as regras anteriores, nunca quebra; um arquivo de regras criado no meio da sessão (o do projeto ou o fallback) é adotado automaticamente, sem recarga manual
-- ✅ **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"
+- **`deny`** bloqueia a chamada; a `reason` da regra vira o erro visível para o modelo.
+- **`ask`** usa a costura oficial de aprovação (monte o `dsh-auto-review` para um answerer de segundo modelo, ou um humano responde; sem nenhum, o harness falha fechado).
+- **`allow`** (e sem correspondência) delega estritamente via `next()` — os listeners posteriores nunca são curto-circuitados.
 
-# 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.4.1.tgz
+Cada acerto **e** cada passagem direta é registrada como um evento de sessão `permissionRules/decision` (somente log — nada extra é injetado no contexto do modelo).
 
-# 2. reinicie
-dsh --profile web
-```
+- **Correspondência rica** — globs de nome de ferramenta (incl. `mcp__*`), seletores de identidade de agente (`main` / `subagent` / `preset:*`), globs **ou** regexes de chave/valor de argumentos (com negação `!pattern` e dimensão de chave `absent`), globs de caminho relativos ao workspace em **qualquer profundidade de aninhamento**, e condições de host `when` (variáveis de ambiente, plataforma).
+- **Arquivos de regras hierárquicos** — `searchUp` opcional mescla cada `.dsh/rules.yaml` do cwd da sessão até a raiz do sistema de arquivos, o mais próximo primeiro.
+- **Implantação em dry-run** — `enforce: false` audita o que a política *faria* enquanto deixa cada chamada passar.
+- **Recarga a quente** — vigilância Chokidar com debounce; uma edição quebrada mantém as regras anteriores, nunca falha.
+- **Falha ruidosa** — YAML inválido, ações/campos desconhecidos, globs/regexes ruins, padrões propensos a backtracking ou mais de `maxRules` regras falham a carga.
 
-Depois crie o arquivo de regras do seu projeto e inicie uma sessão nele:
+## Rule syntax
 
 ```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"
+    reason: "No pushes from protected paths"
 
   - match: { tools: [edit, write] }
     action: ask
-    reason: "Escrita de arquivos precisa de confirmação"
+    reason: "File writes need confirmation"
 ```
 
+- **Dimensões de correspondência** — `tools` (globs, incl. `mcp__*`), `agents` (`main` / `subagent` / `preset:<name>`; identidade desconhecida nunca corresponde — falha fechado), `params` (globs ou regexes de chave/valor, negação `!pattern`, dimensão de chave `absent`), `paths` (globs relativos ao workspace extraídos a qualquer profundidade), `when` (globs/regexes de variáveis `env` + lista `platform` fechada), e `network` (`domains` / `ips` / `ports` / `schemes` — globs, curingas, CIDR, faixas de porta).
+- **Ações** — `allow` / `deny` / `ask`, avaliadas em ordem de arquivo, primeira correspondência vence.
+- **Metadados de regra** — `enabled: false` (visível mas inerte), `description`, `tags`; campos desconhecidos falham a carga.
+- **Schema** — um JSON Schema é distribuído em [docs/rules-format.schema.json](docs/rules-format.schema.json) (autocompletar de editor via `# yaml-language-server: $schema=...`); o vocabulário completo e uma linha base de 5 regras vivem em [docs/rules-format.en.md](docs/rules-format.en.md).
+
+## Network policy
+
+Uma **política de rede em nível de processo** estilo Codex: o tráfego de subprocessos de shell flui por um **proxy HTTP/CONNECT** local integrado, e cada conexão é decidida por regras de rede ordenadas ou por três modos mapeados sobre os presets oficiais do sandbox:
+
+- **`deny-all`** — o preset de sandbox somente leitura: bloquear todo o tráfego de saída.
+- **`whitelist`** — o preset workspace-write: permitir destinos listados, `unlisted: ask` (ou `deny`) para o resto.
+- **`allow-all`** — o preset danger-full-access: permitir tudo.
+- **`auto`** (padrão) — segue o preset do sandbox; em hosts sem o serviço de política de sandbox resolve para `autoFallback` (`allow-all`).
+
+- **Correspondência** — `match.network` com `domains` / `ips` / `ports` / `schemes` (globs, curingas, CIDR, faixas de porta; portas YAML numéricas são aceitas). A extração de candidatos URL na rota quente `tools/pre-execute` dispara sobre argumentos de ferramentas web e URLs embutidas em texto de comando bash/pwsh; destinos de loopback podem curto-circuitar regras conforme a política `loopback`.
+- **Auditoria** — conexões negadas anexam `permissionRules/network` à sessão proprietária (a mesma porta adaptativa `ignorable`), com contadores de bloqueio e intercepções recentes em `/rules network` e na página de settings.
+
+## Quick start
+
 ```sh
-dsh --profile web --dump-config | grep -A4 'id: permission-rules'   # verifique a linha
+# 1. install the bundle into your profile
+dsh plugin --profile web add "github:PerryLink/dsh-permission-rules#main"
+
+# or from npm (published releases)
+dsh plugin --profile web add dsh-permission-rules
+
+# 2. restart and verify the row
+dsh --profile web --dump-config | grep -A4 'id: permission-rules'
 ```
 
-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).
+## Install & uninstall
+
+- **canal git** (último `main`): `dsh plugin --profile web add "github:PerryLink/dsh-permission-rules#main"` — o script `prepare` compila apenas com dependências de produção.
+- **canal npm** (versões publicadas): `dsh plugin --profile web add dsh-permission-rules`.
+- **canal tarball**: `pnpm pack` neste repo, depois `dsh plugin --profile web add ./dsh-permission-rules-<version>.tgz`.
+- **desinstalar**: `dsh plugin --profile web remove dsh-permission-rules`.
 
-## Configuração
+## Configuration
 
-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.
+Todos os parâmetros são campos Schemastery `Config` (alteráveis pelo cordis.yml). Uma sobrescrita direcionada por id substitui a linha inteira — reafirme cada chave de que precisa.
 
-| Chave | Padrão | Significado |
+| Key | Default | Meaning |
 |---|---|---|
 | `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) |
+| `fallbackPath` | *(none)* | Arquivo de regras usado quando a detecção por cwd não encontra nada; validado na montagem |
+| `badFilePolicy` | `fail` | Arquivo de regras ruim: `fail` faz a chamada pendente falhar ruidosamente; `ignore-with-warning` avisa e continua vazio |
+| `maxRules` | `256` | Limite rígido de contagem de regras na cadeia fonte efetiva |
+| `maxCachedWorkspaces` | `512` | Limite rígido de cargas de regras por workspace em cache (evicção LRU) |
+| `patternMode` | `glob` | Sabor de padrão `params`/`paths`/`when.env`: `glob` ou `regex` (nomes de ferramenta são sempre 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) |
-| `enforce` | `true` | `false` = modo simulação: acertos deny/ask são apenas registrados na auditoria com um marcador `dryRun` (ação hipotética + resultado real posterior) e todas as chamadas passam — teste uma política antes de aplicá-la |
-| `allowUnmarkedAudit` | `false` | Hosts cujo `Session.append` é anterior ao marcador `ignorable` (a linha `0.1.0-rc.6`) gravam eventos de auditoria sem marcação, tornando as sessões irrecuperáveis em builds mais rígidos: o plugin os detecta e desativa a auditoria do registro da sessão com um aviso único. Defina `true` para reativar o rastro na sessão (repare registros existentes com `scripts/repair-session-logs.mjs`) |
-
-### Comandos de sessão
+| `watchStabilityThresholdMs` | `200` | Janela de debounce de recarga (ms) |
+| `language` | `en` | Idioma de saída de `/rules`: `en`, `zh`, `es`, `pt`, `hi` |
+| `caseInsensitivePaths` | *(win32)* | Padrões `paths` e comparação de raiz do workspace ignoram maiúsculas ASCII; `true` no Windows |
+| `audit` | `all` | Granularidade de auditoria: `all` registra cada acerto E passagem; `hits` omite eventos de passagem |
+| `searchUp` | `false` | Percorrer diretórios pai do cwd e mesclar cada arquivo de regras encontrado, o mais próximo primeiro |
+| `maxGlobStars` | `2` | Limite rígido de quantificadores `*`/`**` não limitados por padrão glob |
+| `enforce` | `true` | `false` = modo dry-run: acertos deny/ask são registrados com marcador `dryRun` e cada chamada passa |
+| `allowUnmarkedAudit` | `false` | Hosts anteriores ao marcador descartam o marcador `ignorable`; o plugin desativa a auditoria de log com um aviso. Ponha `true` para reativar |
+| `network.enabled` | `true` | Interruptor mestre do proxy, da injeção de ambiente e dos padrões de modo de ferramenta web |
+| `network.mode` | `auto` | Modo de política: `auto` segue o preset do sandbox, ou `deny-all` / `whitelist` / `allow-all` |
+| `network.autoFallback` | `allow-all` | Modo usado quando `auto` não tem serviço de política de sandbox |
+| `network.unlisted` | `ask` | Manejo em modo whitelist de destinos sem regra coincidente: `ask` ou `deny` |
+| `network.proxyBind` | `127.0.0.1` | Endereço de vínculo do proxy local (somente loopback) |
+| `network.proxyPort` | `0` | Porta do proxy local; `0` escolhe uma porta efêmera livre |
+| `network.proxyMaxRecent` | `100` | Limite de registros de bloqueio recentes para a página de settings |
+| `network.loopback` | `allow` | Destinos de loopback: `allow` (paridade Codex) ou `policy` |
+| `network.injectEnv` | `true` | Se variáveis de ambiente do proxy são injetadas para subprocessos |
+| `network.noProxy` | `clear` | Manejo de NO_PROXY em subprocessos: `clear` aplica a política ou `preserve` |
+
+## Tools & surfaces
+
+| Surface | Kind | Notes |
+|---|---|---|
+| `tools/pre-execute` | listener | Regras allow/deny/ask de primeira correspondência + extração de candidatos URL de rede |
+| `/rules` | command | `list` · `reload` · `decisions [n]` · `test <tool> <json>` |
+| `permissionRules/decision` | event | Auditoria somente de log para cada acerto e passagem |
+| `permissionRules/network` | event | Auditoria da camada de proxy para conexões bloqueadas |
+| HTTP/CONNECT proxy | service | Proxy local integrado que governa o tráfego de subprocessos de shell |
+| settings page | client | Editor de modo de rede, editor de regras, contadores de bloqueio, intercepções recentes |
 
 ```
-/rules                        lista as regras ativas, seus arquivos de origem e qualquer erro da última recarga
-/rules list                   alias explícito da listagem simples
-/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"}
+/rules                        list the active rules, their source files, and any last-reload error
+/rules list                   explicit alias for the bare listing
+/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
 ```
 
-`/rules test` também aceita sinalizadores iniciais: `--cwd <dir>` avalia contra outro workspace, `--env CHAVE=VALOR` (repetível) sobrescreve o ambiente para `when.env`, `--agent <seletor>` (repetível) fornece candidatos de identidade para a dimensão `agents`, e `--platform <nome>` sobrescreve a plataforma para `when.platform`. Em cadeias de vários arquivos (ex.: `searchUp`), cada linha de regra é atribuída ao seu próprio arquivo de origem.
-
-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).
+`/rules test` também aceita bandeiras iniciais: `--cwd <dir>`, `--env KEY=VALUE` (repetível), `--agent <selector>` (repetível) e `--platform <name>`. Em cadeias multi-arquivo (ex.: `searchUp`), cada linha de regra listada é atribuída ao seu próprio arquivo fonte.
 
-## Colaboração com o dsh-auto-review
+## Permissions & data
 
-- 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.
+- **Permissions**: o manifesto de workshop declara `files:read`, `files:watch`, `files:write`, `session:append` e `network:outbound`. Decisões `ask` usam a costura oficial de aprovação — nada é reimplementado ou contornado.
+- **Data**: arquivos de regras são lidos do disco; nenhum dado de regra é escrito. Sem chamadas de modelo, sem subagentes revisores.
+- **Session log**: `permissionRules/decision` nunca é injetado no contexto do modelo e é anexado com o marcador `ignorable: true` do envelope, de modo que qualquer build do harness carrega o log.
 
-## Limites de segurança
+## Security boundaries
 
-- **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.)
+- **Política, não kernel.** Candidatos `paths` vêm apenas de um conjunto documentado de chaves de argumento (a qualquer profundidade, com limite), e apenas caminhos relativos ao workspace correspondem.
+- **Aqui não há revisor.** O plugin nunca gera subagentes nem chama modelos — produzir uma decisão `ask` é o fim do seu trabalho.
+- **Sem mudanças de sandbox.** A política de sandbox em nível de SO pertence à costura do sandbox, não a este plugin.
+- **Rejeição ruidosa de má configuração.** Campos YAML desconhecidos, ações desconhecidas e padrões ruins são rejeitados na carga.
+- **Limites de backtracking.** Padrões glob são limitados a `maxGlobStars` expansões de estrela não limitadas; padrões regex rejeitam quantificadores aninhados não limitados e alternâncias literais sobrepostas quantificadas.
 
-## Trabalho relacionado
+## Known limitations
 
-- [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.
+- **Marcador de auditoria em hosts anteriores ao marcador.** `permissionRules/decision` é anexado com `ignorable: true`; hosts cujo `Session.append` é anterior ao marcador (a linha `0.1.0-rc.6`) o descartam silenciosamente, então o runtime desativa a auditoria de log com um aviso único. Ponha `allowUnmarkedAudit: true` para reativar; repare logs já escritos com `scripts/repair-session-logs.mjs`.
+- **Candidatos de caminho são heurísticos.** Somente as chaves de argumento documentadas alimentam a correspondência de caminho, e a correspondência relativa ao workspace é insensível a maiúsculas ASCII apenas com `caseInsensitivePaths` ativado.
+- **Globs são um subconjunto conservador.** Sem expansão de chaves — escreva dois padrões, ou use o modo regex.
+- **A guarda de backtracking de regex é estrutural, não exaustiva.** Prefira o modo glob para arquivos não confiáveis.
 
-## Limitações conhecidas
+## Collaborating with dsh-auto-review
 
-- `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 cujo `Session.append` é anterior ao marcador (a linha `0.1.0-rc.6`) o DESCARTAM silenciosamente: o plugin os detecta em tempo de execução (verificação prévia da versão do peer + sonda do envelope anexado) e desativa a auditoria do registro da sessão com um aviso único, mantendo os registros carregáveis em qualquer lugar. Defina `allowUnmarkedAudit: true` para reativar o rastro na sessão; registros já gravados sem o marcador podem ser reparados com `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.
+- O `dsh-permission-rules` produz `ask`; o `dsh-auto-review` responde na cascata `approval/request` com um veredito de segundo modelo somente leitura (ou delega a humanos). Monte ambos para o laço completo fechado.
+- Testado em integração: `permissionRules/decision` → `approval/asked` → `autoReview/verdict` → `approval/decided`, com o revisor substituído por um mock roteirizado.
+- A política de aprovação `never` e toda garantia de falha fechada do harness oficial permanecem intactas.
 
-## Reparo de registros de sessão
+## Session log repair
 
-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:
+Logs de sessão escritos antes de o marcador `ignorable` existir podem ser recusados por builds mais novas do harness (`SessionFormatUnsupportedError`). O `scripts/repair-session-logs.mjs` distribuído reescreve apenas as linhas de auditoria alvo para carregar `ignorable: true`, preservando quadros, com backups:
 
 ```sh
-node scripts/repair-session-logs.mjs scan [--home DIR]      # relata linhas externas, sem alterar
+node scripts/repair-session-logs.mjs scan [--home DIR]      # relata linhas estranhas, não muda nada
 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.
+`--home` por padrão é `$DSH_HOME/sessions` (ou `~/.dsh/sessions`).
 
-## Desenvolvimento
+## Development
 
 ```sh
-pnpm install        # node ^22.19 || >=24
-pnpm run typecheck  # tsc, src + tests
-pnpm run lint       # eslint, src + tests + scripts
-pnpm test           # vitest: 139 tests, 9 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)
+pnpm install            # node ^22.19 || >=24
+pnpm run typecheck      # tsc, src + tests
+pnpm run lint           # eslint, src + tests + scripts
+pnpm test               # vitest: 139 tests, 9 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)
 ```
 
-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`).
+Consulte [VERIFICATION.md](VERIFICATION.md) para o registro de verificação end-to-end sem cabeça.
+
+## Topics
+
+`dsh`, `dsh-plugin`, `deepseek-harness`, `permission`, `policy`, `allow-deny-ask`, `approval`, `safety`, `network`, `network-policy`, `proxy`
+
+## Contributors
+
+- [@PerryLink](https://github.com/PerryLink) — criador e mantenedor: vocabulário e avaliação de regras, runtime, vigilância HMR, auditoria de log de sessão, política de rede + proxy, e a documentação em cinco idiomas.
+- [@22xuan](https://github.com/22xuan) — o relatório detalhado sobre hosts rc.6 descartando silenciosamente o marcador `ignorable` do evento de auditoria ([#2](https://github.com/PerryLink/dsh-permission-rules/issues/2)) e a discussão do harness upstream; a detecção de capacidade de host em runtime v0.4.1 e a correção de documentação se derivaram diretamente dessa análise.
+
+## PerryLink DSH Plugin Family
 
-## Contribuidores
+Este projeto é um dos [15 plugins do DeepSeek Harness](https://github.com/PerryLink) mantidos por [PerryLink](https://github.com/PerryLink). Se este te ajuda, os demais provavelmente também:
 
-- [@PerryLink](https://github.com/PerryLink) — criador e mantenedor: vocabulário e avaliação de regras, runtime, vigilância HMR, auditoria do registro da sessão e documentação em cinco idiomas.
-- [@22xuan](https://github.com/22xuan) — o relatório detalhado sobre hosts rc.6 descartando silenciosamente o marcador `ignorable` dos eventos de auditoria ([#2](https://github.com/PerryLink/dsh-permission-rules/issues/2)) e a discussão no harness upstream; a detecção de capacidade do host da v0.4.1 e a correção da documentação derivam diretamente dessa análise.
+| Plugin | One-liner |
+|---|---|
+| [dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel) | Read-only MCP runtime panel: /mcp command + Settings tab with status, tools and errors |
+| [dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck) | Engineering-discipline guard: requirements grill, test gates, adversary review |
+| [dsh-background-agents](https://github.com/PerryLink/dsh-background-agents) | Durable background child agents with a Web UI sidebar, messaging and interrupt |
+| [dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions) | LSP diagnostics, formatting, completion, code actions and rename over language servers |
+| [dsh-output-styles](https://github.com/PerryLink/dsh-output-styles) | Claude Code outputStyles-equivalent runtime style switching |
+| [dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind) | Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore |
+| **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** | Claude Code-style declarative allow/deny/ask permission rules with audit |
+| [dsh-auto-review](https://github.com/PerryLink/dsh-auto-review) | Second-model auto-review on the approval chain, fail-closed by default |
+| [dsh-memento](https://github.com/PerryLink/dsh-memento) | Approval-gated cross-session memory: ctx.memory seam + SQLite + memory tool |
+| [dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security) | Security-audit skill pack: secret scan, dependency and supply-chain review |
+| [dsh-session-pin](https://github.com/PerryLink/dsh-session-pin) | Pin sessions in the Web sidebar with durable ordering |
+| [dsh-composer-history](https://github.com/PerryLink/dsh-composer-history) | Terminal-style input history for the web composer: arrows, Ctrl+R search |
+| [dsh-github](https://github.com/PerryLink/dsh-github) | GitHub PR/issues integration for DSH, every write gated by approval |
+| [dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide) | Plugin-development knowledge base as an on-demand agent skill |
+| [dsh-claude-move](https://github.com/PerryLink/dsh-claude-move) | Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH |
 
-## Licença
+## License
 
 [Apache License 2.0](LICENSE) © 2026 dsh-permission-rules contributors