dsh-permission-rules 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to dsh-permission-rules are recorded here, newest first.
 
+## v0.4.0 — 2026-08-15
+
+### Hot reload and workspace identity
+
+- **Mid-session rule-file creation is adopted automatically.** Expected-but-absent rule files (the project file when it is not in effect, a fallback deleted after mount) are now watched through their deepest existing ancestor directory (chokidar cannot reliably watch a missing path whose parent is also missing), so creating `.dsh/rules.yaml` — or recreating it after a fallback took over — takes effect without a manual `/rules reload`. Under `searchUp`, only the immediate cwd-level candidate is watched; deeper ancestors still need a reload.
+- The per-workspace cache key is now the resolved cwd, case-folded on Windows: differently-spelled paths to the same workspace share one cache entry and one watcher set instead of doubling both.
+
+### Commands and observability
+
+- `/rules test` accepts `--platform <name>` (one of the closed platform list): the `when.platform` match dimension is now dry-testable on any host, completing the flag coverage of every match dimension.
+- `/rules` lists each rule with its own source file in multi-file chains (`searchUp`), via a localized `src:` attribution token; `/rules list` is an explicit alias for the bare listing.
+- All five output languages carry the new `testBadPlatform` message, the updated usage strings, and the `src` token.
+
+### Engineering
+
+- 133 tests across 8 suites (new coverage: creation-adoption watch paths, fallback recreation, cache-key dedup, `--platform`, `list`, source attribution); coverage gate held. Five-language READMEs, both rules-format references, AGENTS.md, and the `/rules` command hint updated.
+
+## v0.3.0 — 2026-08-14
+
+### Rules vocabulary
+
+- New `match.agents` dimension: selector globs (`main`, `subagent`, `preset:<name>`) matched against the caller's session-header identity, ANDed with the other dimensions; unknown identity never matches (fail closed), so agent-scoped rules cannot leak onto unidentified callers.
+- Path normalization: a candidate equal to the workspace root itself is dropped explicitly, and the root comparison only ignores case when `caseInsensitivePaths` is on.
+
+### Dry-run rollout and audit fidelity
+
+- `enforce: false` dry-run mode: deny/ask hits are audit-logged with a `dryRun` marker — the record keeps the would-be action AND the real downstream outcome — while every call is delegated via `next()`. `/rules` prints a dry-run notice while the mode is active and `/rules decisions` renders `(dry-run → <outcome>)` on such rows. Trial a new policy in production before enforcing it.
+- `permissionRules/decision` events now carry `cwd`, the workspace the rule chain was resolved for.
+
+### Commands and observability
+
+- `/rules test` accepts leading flags: `--cwd <dir>` (evaluate against another workspace's rules), `--env KEY=VALUE` (repeatable; overrides host env for `when.env`), and `--agent <selector>` (repeatable; supplies identity candidates for the `agents` dimension). Quoted JSON argument tails are preserved verbatim.
+- `resolveConfig` validates the closed enums (`badFilePolicy`, `patternMode`, `language`, `audit`) and boolean flags loudly, so plain-JS mounts without the Schemastery loader also fail on bad values instead of crashing later.
+
+### Engineering
+
+- 125 tests across 8 suites; coverage gate held. Five-language READMEs, both rules-format references, the JSON Schema, and the `/rules` command hint updated for `agents` and `enforce`.
+
 ## v0.2.0 — 2026-08-14
 
 ### Rules vocabulary

package/README.es.md

@@ -48,14 +48,15 @@ Un segundo modelo responde *"¿es segura ESTA llamada?"* con criterio, pero cues
 ## Características
 
 - ✅ **Semántica de tres estados** — `allow`, `deny`, `ask`, evaluadas en orden de archivo; gana la primera coincidencia
-- ✅ **Coincidencia rica** — globs de nombre de herramienta (incluido `mcp__*`), globs **o** regex de clave/valor de argumentos (con negación `!pattern` y la dimensión de clave `absent`), globs de rutas relativas al workspace extraídos de claves de argumentos documentadas a **cualquier profundidad de anidamiento**, y condiciones de host `when` (variables de entorno, plataforma)
+- ✅ **Coincidencia rica** — globs de nombre de herramienta (incluido `mcp__*`), selectores de identidad de agente (`main` / `subagent` / `preset:*`), globs **o** regex de clave/valor de argumentos (con negación `!pattern` y la dimensión de clave `absent`), globs de rutas relativas al workspace extraídos de claves de argumentos documentadas a **cualquier profundidad de anidamiento**, y condiciones de host `when` (variables de entorno, plataforma)
 - ✅ **Archivos de reglas jerárquicos** — `searchUp` opcional combina cada `.dsh/rules.yaml` desde el cwd de la sesión hasta la raíz del sistema de archivos, el más cercano primero, para que un proyecto hijo pueda sobrescribir las reglas del padre
 - ✅ **Metadatos de reglas** — `enabled: false`, `description`, `tags`; `/rules` advierte sobre reglas eclipsadas por un catch-all anterior
 - ✅ **Seguro para el waterfall** — `allow`/paso siempre llaman a `next()`; solo `deny`/`ask` cortocircuitan
 - ✅ **Seam de aprobación oficial** — `ask` fluye por `ctx.approval`; nunca reimplementado, nunca eludido
-- ✅ **Auditoría completa** — los eventos `permissionRules/decision` llevan la acción de la regla Y el resultado final de cada llamada; `/rules decisions` reproduce el rastro en la sesión
-- ✅ **Prueba en seco** — `/rules test <tool> <json-args>` evalúa las reglas activas sin ejecutar nada
-- ✅ **Recarga en caliente** — vigilancia Chokidar con debounce; una edición rota conserva las reglas previas, nunca falla
+- ✅ **Auditoría completa** — los eventos `permissionRules/decision` llevan la acción de la regla, el cwd del workspace Y el resultado final de cada llamada; `/rules decisions` reproduce el rastro en la sesión
+- ✅ **Despliegue en simulación** — `enforce: false` audita lo que la política *haría* (acción hipotética + resultado real posterior, marcado `dryRun`) mientras deja pasar todas las llamadas; prueba segura de políticas en producción
+- ✅ **Prueba en seco** — `/rules test <tool> <json-args>` evalúa las reglas activas sin ejecutar nada, con sobrescrituras `--cwd`, `--env`, `--agent` y `--platform` para cada dimensión
+- ✅ **Recarga en caliente** — vigilancia Chokidar con debounce; una edición rota conserva las reglas previas, nunca falla; un archivo de reglas creado a mitad de sesión (el del proyecto o el fallback) se adopta automáticamente, sin recarga manual
 - ✅ **Fallo ruidoso** — YAML inválido, acciones/campos desconocidos, globs/regex incorrectos, patrones propensos a backtracking o > `maxRules` hacen fallar la carga
 - ✅ **Ruta caliente acotada** — matchers precompilados, O(reglas × patrones), limitado por `maxRules`; el grado de backtracking de glob limitado por `maxGlobStars`
 
@@ -67,7 +68,7 @@ dsh plugin --profile web add "github:PerryLink/dsh-permission-rules#main"
 
 # o desde un tarball empaquetado (artefactos compilados, sin permiso de build)
 pnpm pack
-dsh plugin --profile web add ./dsh-permission-rules-0.1.1.tgz
+dsh plugin --profile web add ./dsh-permission-rules-0.4.0.tgz
 
 # 2. reinicia
 dsh --profile web
@@ -112,16 +113,20 @@ Todos los ajustes son campos `Config` de Schemastery (modificables desde cordis.
 | `audit` | `all` | Granularidad de auditoría: `all` registra cada acierto Y cada paso; `hits` omite los eventos de paso |
 | `searchUp` | `false` | Recorre los directorios padre desde el cwd de la sesión y combina cada archivo de reglas encontrado, el más cercano primero |
 | `maxGlobStars` | `2` | Límite duro de cuantificadores `*`/`**` sin límite por patrón glob (cota del grado de backtracking) |
+| `enforce` | `true` | `false` = modo simulación: los aciertos deny/ask solo se registran en auditoría con un marcador `dryRun` (acción hipotética + resultado real posterior) y todas las llamadas pasan — prueba una política antes de aplicarla |
 
 ### Comandos de sesión
 
 ```
 /rules                        lista las reglas activas, sus archivos fuente y cualquier error de la última recarga
+/rules list                   alias explícito del listado simple
 /rules reload                 relee la cadena de archivos de reglas de este workspace
 /rules decisions [n]          muestra las últimas n decisiones de permisos de esta sesión (por defecto 10)
 /rules test <tool> <json>     evalúa en seco las reglas contra una llamada hipotética, p. ej. /rules test bash {"command":"git push origin main"}
 ```
 
+`/rules test` también acepta banderas iniciales: `--cwd <dir>` evalúa contra otro workspace, `--env CLAVE=VALOR` (repetible) sobrescribe el entorno para `when.env`, `--agent <selector>` (repetible) suministra candidatos de identidad para la dimensión `agents`, y `--platform <nombre>` sobrescribe la plataforma para `when.platform`. En cadenas de varios archivos (p. ej. `searchUp`), cada línea de regla se atribuye a su propio archivo fuente.
+
 La salida de los comandos es solo UI: el modelo aprende las reglas únicamente a través de los resultados de herramienta que producen. `language` elige el idioma de salida. Un JSON Schema del archivo de reglas se distribuye en [docs/rules-format.schema.json](docs/rules-format.schema.json) (conéctalo con `# yaml-language-server: $schema=...` para autocompletado en el editor).
 
 ## Colaboración con dsh-auto-review
@@ -168,7 +173,7 @@ node scripts/repair-session-logs.mjs repair [--home DIR] [--dry-run]
 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 test           # vitest: 133 tests, 8 suites
 pnpm run test:coverage  # puerta de cobertura (90/80/90/90)
 pnpm run build      # declaraciones tsc + bundles tsdown (lib/)
 pnpm run pack:check # build + pack (el artefacto publicado)

package/README.hi.md

@@ -48,14 +48,15 @@ tools/pre-execute waterfall                     approval/request waterfall (answ
 ## विशेषताएँ
 
 - ✅ **तीन-अवस्था शब्दार्थ** — `allow`, `deny`, `ask`, फ़ाइल क्रम में मूल्यांकित; पहला मिलान जीतता है
-- ✅ **समृद्ध मिलान** — टूल-नाम globs (`mcp__*` सहित), आर्गुमेंट कुंजी/मान globs **या** regex (`!pattern` निषेध और `absent` कुंजी आयाम के साथ), दस्तावेज़ित आर्गुमेंट कुंजियों से **किसी भी नेस्टिंग गहराई** पर निकाले गए workspace-सापेक्ष पथ globs, और `when` होस्ट शर्तें (env vars, प्लेटफ़ॉर्म)
+- ✅ **समृद्ध मिलान** — टूल-नाम globs (`mcp__*` सहित), एजेंट-पहचान चयनकर्ता (`main` / `subagent` / `preset:*`), आर्गुमेंट कुंजी/मान globs **या** regex (`!pattern` निषेध और `absent` कुंजी आयाम के साथ), दस्तावेज़ित आर्गुमेंट कुंजियों से **किसी भी नेस्टिंग गहराई** पर निकाले गए workspace-सापेक्ष पथ globs, और `when` होस्ट शर्तें (env vars, प्लेटफ़ॉर्म)
 - ✅ **पदानुक्रमित नियम फ़ाइलें** — वैकल्पिक `searchUp` सत्र cwd से फ़ाइलसिस्टम रूट तक हर `.dsh/rules.yaml` को मिलाता है, निकटतम पहले, ताकि चाइल्ड प्रोजेक्ट पैरेंट नियमों को ओवरराइड कर सके
 - ✅ **नियम मेटाडेटा** — `enabled: false`, `description`, `tags`; `/rules` पहले किसी catch-all से छिपे नियमों की चेतावनी देता है
 - ✅ **waterfall-सुरक्षित** — `allow`/पास-थ्रू हमेशा `next()` बुलाते हैं; केवल `deny`/`ask` शॉर्ट-सर्किट करते हैं
 - ✅ **आधिकारिक approval seam** — `ask` `ctx.approval` से होकर जाता है; कभी पुनः-कार्यान्वित नहीं, कभी बायपास नहीं
-- ✅ **पूर्ण ऑडिट** — `permissionRules/decision` इवेंट हर कॉल के लिए नियम क्रिया और अंतिम परिणाम दोनों रखते हैं; `/rules decisions` सत्र में रास्ता फिर चलाता है
-- ✅ **dry-run परीक्षण** — `/rules test <tool> <json-args>` कुछ भी निष्पादित किए बिना सक्रिय नियमों का मूल्यांकन करता है
-- ✅ **हॉट रीलोड** — debounce सहित Chokidar निगरानी; टूटा हुआ संपादन पिछले नियम रखता है, कभी क्रैश नहीं करता
+- ✅ **पूर्ण ऑडिट** — `permissionRules/decision` इवेंट हर कॉल के लिए नियम क्रिया, workspace cwd और अंतिम परिणाम रखते हैं; `/rules decisions` सत्र में रास्ता फिर चलाता है
+- ✅ **dry-run रोलआउट** — `enforce: false` केवल ऑडिट करता है कि नीति *क्या करती* (काल्पनिक क्रिया + वास्तविक डाउनस्ट्रीम परिणाम, `dryRun` चिह्नित) और हर कॉल को पास करता है; उत्पादन में नई नीति का सुरक्षित परीक्षण
+- ✅ **dry-run परीक्षण** — `/rules test <tool> <json-args>` कुछ भी निष्पादित किए बिना सक्रिय नियमों का मूल्यांकन करता है, हर मिलान आयाम के लिए `--cwd`, `--env`, `--agent` और `--platform` ओवरराइड के साथ
+- ✅ **हॉट रीलोड** — debounce सहित Chokidar निगरानी; टूटा हुआ संपादन पिछले नियम रखता है, कभी क्रैश नहीं करता; सत्र के बीच बनाई गई नियम फ़ाइल (प्रोजेक्ट की या fallback) स्वतः अपनाई जाती है, मैनुअल रीलोड की आवश्यकता नहीं
 - ✅ **ज़ोरदार विफलता** — अमान्य YAML, अज्ञात action/फ़ील्ड, ख़राब globs/regex, बैकट्रैकिंग-प्रवण पैटर्न, या `maxRules` से अधिक → लोड विफल
 - ✅ **सीमित हॉट पथ** — पूर्व-संकलित matchers, O(नियम × पैटर्न), `maxRules` द्वारा सीमित; glob बैकट्रैकिंग डिग्री `maxGlobStars` द्वारा सीमित
 
@@ -67,7 +68,7 @@ dsh plugin --profile web add "github:PerryLink/dsh-permission-rules#main"
 
 # या पैक किए गए tarball से (बिल्ट आर्टिफ़ैक्ट, build अनुमति की ज़रूरत नहीं)
 pnpm pack
-dsh plugin --profile web add ./dsh-permission-rules-0.1.1.tgz
+dsh plugin --profile web add ./dsh-permission-rules-0.4.0.tgz
 
 # 2. पुनः आरंभ करें
 dsh --profile web
@@ -112,16 +113,20 @@ dsh --profile web --dump-config | grep -A4 'id: permission-rules'   # पंक
 | `audit` | `all` | ऑडिट विवरण स्तर: `all` हर मिलान और पास-थ्रू लॉग करता है; `hits` पास-थ्रू इवेंट छोड़ता है |
 | `searchUp` | `false` | सत्र cwd से पैरेंट निर्देशिकाओं पर चलकर हर मिली नियम फ़ाइल मिलाता है, निकटतम पहले |
 | `maxGlobStars` | `2` | प्रति glob पैटर्न असीमित `*`/`**` क्वांटिफ़ायर की कठोर सीमा (बैकट्रैकिंग-डिग्री सीमा) |
+| `enforce` | `true` | `false` = dry-run मोड: deny/ask मिलान केवल ऑडिट में `dryRun` चिह्न के साथ दर्ज होते हैं (काल्पनिक क्रिया + वास्तविक डाउनस्ट्रीम परिणाम) और हर कॉल पास होती है — लागू करने से पहले नीति का परीक्षण करें |
 
 ### सेशन कमांड
 
 ```
 /rules                        सक्रिय नियम, उनकी स्रोत फ़ाइलें और अंतिम रीलोड त्रुटि दिखाता है
+/rules list                   सामान्य सूची का स्पष्ट उपनाम
 /rules reload                 इस workspace की नियम-फ़ाइल शृंखला दोबारा पढ़ता है
 /rules decisions [n]          इस सत्र की अंतिम n अनुमति निर्णय दिखाता है (डिफ़ॉल्ट 10)
 /rules test <tool> <json>     काल्पनिक कॉल के विरुद्ध नियमों का dry-मूल्यांकन, जैसे /rules test bash {"command":"git push origin main"}
 ```
 
+`/rules test` शुरुआती फ़्लैग भी स्वीकार करता है: `--cwd <dir>` दूसरे workspace के विरुद्ध मूल्यांकन करता है, `--env KEY=मान` (दोहराने योग्य) `when.env` के लिए होस्ट env ओवरराइड करता है, `--agent <चयनकर्ता>` (दोहराने योग्य) `agents` आयाम के लिए पहचान उम्मीदवार देता है, और `--platform <नाम>` `when.platform` के लिए होस्ट प्लेटफ़ॉर्म ओवरराइड करता है। बहु-फ़ाइल शृंखलाओं (जैसे `searchUp`) में हर नियम पंक्ति अपनी स्रोत फ़ाइल के साथ चिह्नित होती है।
+
 कमांड आउटपुट केवल UI के लिए है — मॉडल नियमों को केवल उनके उत्पन्न टूल परिणामों से ही सीखता है। `language` आउटपुट भाषा चुनता है। नियम फ़ाइल का JSON Schema [docs/rules-format.schema.json](docs/rules-format.schema.json) पर साथ आता है (संपादक पूर्णता के लिए `# yaml-language-server: $schema=...` से जोड़ें)।
 
 ## dsh-auto-review के साथ सहयोग
@@ -168,7 +173,7 @@ node scripts/repair-session-logs.mjs repair [--home DIR] [--dry-run]
 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 test           # vitest: 133 tests, 8 suites
 pnpm run test:coverage  # कवरेज द्वार (90/80/90/90)
 pnpm run build      # tsc डिक्लेरेशन + tsdown bundles (lib/)
 pnpm run pack:check # build + pack (प्रकाशित आर्टिफ़ैक्ट)

package/README.md

@@ -48,14 +48,15 @@ A second model answers *"is THIS call okay?"* with judgment, but costs a round-t
 ## 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)
+- ✅ **Rich matching** — tool-name globs (including `mcp__*`), agent-identity selectors (`main` / `subagent` / `preset:*`), 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
+- ✅ **Full audit** — `permissionRules/decision` events carry the rule action, the workspace cwd, AND the final outcome for every call; `/rules decisions` replays the trail in-session
+- ✅ **Dry-run rollout** — `enforce: false` audits what the policy *would* do (would-be action + real downstream outcome, `dryRun`-marked) while passing every call through; safe policy trialing in production
+- ✅ **Dry-run testing** — `/rules test <tool> <json-args>` evaluates the active rules without executing anything, with `--cwd`, `--env`, `--agent`, and `--platform` overrides for every match dimension
+- ✅ **Hot reload** — Chokidar watch with debounce; a broken edit keeps the previous rules, never crashes; a rule file created mid-session (the project file or the fallback) is adopted automatically, no manual reload
 - ✅ **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`
 
@@ -67,7 +68,7 @@ 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
+dsh plugin --profile web add ./dsh-permission-rules-0.4.0.tgz
 
 # 2. restart
 dsh --profile web
@@ -112,16 +113,20 @@ All tunables are Schemastery `Config` fields (changeable from cordis.yml). An id
 | `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) |
+| `enforce` | `true` | `false` = dry-run mode: deny/ask hits are audit-logged with a `dryRun` marker (would-be action + real downstream outcome) and every call passes through — trial a policy before enforcing it |
 
 ### Session commands
 
 ```
 /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, e.g. /rules test bash {"command":"git push origin main"}
 ```
 
+`/rules test` also accepts leading flags: `--cwd <dir>` evaluates against another workspace, `--env KEY=VALUE` (repeatable) overrides host env for `when.env`, `--agent <selector>` (repeatable) supplies identity candidates for the `agents` dimension, and `--platform <name>` overrides the host platform for `when.platform`. In multi-file chains (e.g. `searchUp`), every listed rule line is attributed to its own source file.
+
 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
@@ -168,7 +173,7 @@ node scripts/repair-session-logs.mjs repair [--home DIR] [--dry-run]
 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 test           # vitest: 133 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)

package/README.pt.md

@@ -48,14 +48,15 @@ Um segundo modelo responde *"ESTA chamada é segura?"* com julgamento, mas custa
 ## 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)
+- ✅ **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 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
+- ✅ **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
+- ✅ **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`
 
@@ -67,7 +68,7 @@ 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
+dsh plugin --profile web add ./dsh-permission-rules-0.4.0.tgz
 
 # 2. reinicie
 dsh --profile web
@@ -112,16 +113,20 @@ Todos os ajustes são campos `Config` do Schemastery (alteráveis no cordis.yml)
 | `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 |
 
 ### Comandos de sessão
 
 ```
 /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 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).
 
 ## Colaboração com o dsh-auto-review
@@ -168,7 +173,7 @@ node scripts/repair-session-logs.mjs repair [--home DIR] [--dry-run]
 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 test           # vitest: 133 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)

package/README.zh.md

@@ -48,14 +48,15 @@ tools/pre-execute waterfall                     approval/request waterfall（ans
 ## 特性
 
 - ✅ **三态语义** — `allow`、`deny`、`ask`，按文件顺序求值，首条命中生效
-- ✅ **丰富匹配** — 工具名 glob（含 `mcp__*`）、参数键值 glob **或** 正则（支持 `!pattern` 否定与 `absent` 键维度）、工作区相对路径 glob（从文档化参数键在**任意嵌套深度**提取候选），以及 `when` 宿主条件（环境变量、平台）
+- ✅ **丰富匹配** — 工具名 glob（含 `mcp__*`）、代理身份选择器（`main` / `subagent` / `preset:*`）、参数键值 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 监视 + 去抖；改坏了保留旧规则，绝不崩溃
+- ✅ **完整审计** — `permissionRules/decision` 事件记录规则动作、工作区 cwd 与最终裁决；`/rules decisions` 可在会话内回放审计轨迹
+- ✅ **干跑上线** — `enforce: false` 只审计策略「本会做什么」（记录本会动作 + 下游真实结果，带 `dryRun` 标记），所有调用照常透传；可在生产环境安全试跑新策略
+- ✅ **干跑测试** — `/rules test <工具> <json-参数>` 不执行任何东西地评估规则命中，支持 `--cwd`、`--env`、`--agent`、`--platform` 覆盖每个匹配维度
+- ✅ **热更新** — Chokidar 监视 + 去抖；改坏了保留旧规则，绝不崩溃；会话中途创建的规则文件（项目文件或 fallback）自动生效，无需手动重载
 - ✅ **响亮失败** — 非法 YAML、未知字段/action、坏 glob/正则、易回溯灾难的模式、超过 `maxRules` 都使加载失败
 - ✅ **热路径有界** — 预编译匹配器，O(规则数 × 模式数)，`maxRules` 封顶；glob 回溯度由 `maxGlobStars` 封顶
 
@@ -67,7 +68,7 @@ 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
+dsh plugin --profile web add ./dsh-permission-rules-0.4.0.tgz
 
 # 2. 重启
 dsh --profile web
@@ -112,16 +113,20 @@ dsh --profile web --dump-config | grep -A4 'id: permission-rules'   # 验证挂
 | `audit` | `all` | 审计粒度：`all` 记录每次命中与透传；`hits` 跳过透传事件 |
 | `searchUp` | `false` | 从会话 cwd 向上逐级查找并合并规则文件，最近的优先 |
 | `maxGlobStars` | `2` | 每个 glob 模式的无界 `*`/`**` 量词数硬上界（回溯度封顶） |
+| `enforce` | `true` | `false` = 干跑模式：deny/ask 命中只写审计（带 `dryRun` 标记，记录本会动作与下游真实结果），所有调用照常透传——先试跑策略再强制执行 |
 
 ### 会话命令
 
 ```
 /rules                        列出当前生效规则、来源文件与最近一次重载错误
+/rules list                   裸列出的显式别名
 /rules reload                 重读本工作区的规则文件链
 /rules decisions [n]          显示本会话最近 n 条权限裁决（默认 10）
 /rules test <工具> <json>     对假设调用干跑评估，如 /rules test bash {"command":"git push origin main"}
 ```
 
+`/rules test` 还支持前置标志：`--cwd <目录>` 换一个工作区评估，`--env 键=值`（可重复）覆盖宿主环境变量以测试 `when.env`，`--agent <选择器>`（可重复）为 `agents` 维度提供身份候选，`--platform <平台名>` 覆盖宿主平台以测试 `when.platform`。多文件链（如 `searchUp`）下，每条规则行都会标注它自己的来源文件。
+
 命令输出只进 UI——模型只通过规则产生的工具结果感知规则。`language` 选择输出语言。规则文件的 JSON Schema 随包发布在 [docs/rules-format.schema.json](docs/rules-format.schema.json)（用 `# yaml-language-server: $schema=...` 启用编辑器补全）。
 
 ## 与 dsh-auto-review 协作
@@ -168,7 +173,7 @@ node scripts/repair-session-logs.mjs repair [--home DIR] [--dry-run]
 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 test           # vitest：133 测试 / 8 套件
 pnpm run test:coverage  # 覆盖率门禁（90/80/90/90）
 pnpm run build      # tsc 声明 + tsdown 打包（lib/）
 pnpm run pack:check # 构建 + pack（发布产物）

package/docs/rules-format.en.md

@@ -17,13 +17,14 @@ rules:        # rule list, evaluated in written order; may be omitted or empty
     reason: ...
 ```
 
-Only `rules` is allowed at the top level; each rule allows only `match`, `action`, `reason`, `enabled`, `description`, `tags`; each `match` allows only `tools`, `params`, `paths`, `absent`, `when`. Any unknown field fails the load loudly — never silently ignored.
+Only `rules` is allowed at the top level; each rule allows only `match`, `action`, `reason`, `enabled`, `description`, `tags`; each `match` allows only `tools`, `agents`, `params`, `paths`, `absent`, `when`. Any unknown field fails the load loudly — never silently ignored.
 
 ## match dimensions (AND)
 
 | Dimension | Type | Semantics |
 |---|---|---|
 | `tools` | `string[]` | Tool-name globs (always globs, regardless of `patternMode`). Empty/absent = unrestricted. Supports prefixes like `mcp__*`. |
+| `agents` | `string[]` | Agent-identity selector globs against the caller's session header candidates: `main` (top-level sessions), `subagent` (subagent children), and `preset:<name>` (when a preset composed the agent). **Any selector matching any candidate** satisfies the dimension; empty/absent = unrestricted. Unknown identity (no candidates) never matches, so agent-scoped rules fail closed. |
 | `params` | `Record<string, string \| number \| boolean \| (…)[]>` | Argument key → pattern (or pattern list). **Every listed key must be present AND match** (AND); absent = unrestricted. Scalars match as strings (numbers/booleans stringified); array elements match any-of; nested objects contribute their scalar leaves (depth-capped at 8). A `!`-prefixed pattern negates: the value must NOT match it; a key with only negations matches when the key is present and no negation hits (quote `!` patterns in YAML: `"!git*"`). `/` is an ordinary character in params patterns — `*` crosses it. |
 | `paths` | `string[]` | Workspace-relative path patterns; any candidate matching any pattern satisfies the dimension. Candidates come from argument values under these keys at ANY nesting depth (depth-capped): `path` `paths` `file` `files` `file_path` `dir` `directory` `directories` `cwd` `workspace` `root` `target` `targets` `output`. Absolute candidates outside the workspace are dropped; relative `../` forms are kept so explicit out-of-root globs still work. In path patterns `*` does not cross `/`; `**` crosses any depth (including zero). With `caseInsensitivePaths` on (Windows default) the root comparison and the patterns ignore ASCII case. |
 | `absent` | `string[]` | Argument keys that must be ABSENT; **every listed key must be missing** (non-object arguments satisfy this trivially). |
@@ -99,7 +100,11 @@ This plugin only produces `ask` decisions; the `ask` goes to the official `ctx.a
 
 ## Loading and hot reload
 
-- Lazily discovered per session cwd and cached on the first `tools/pre-execute` (least-recently-used eviction beyond `maxCachedWorkspaces`).
+- Lazily discovered per session cwd and cached on the first `tools/pre-execute` (least-recently-used eviction beyond `maxCachedWorkspaces`); the cache key is the resolved cwd (case-folded on Windows), so differently-spelled paths share one entry.
 - Invalid YAML, unknown fields/actions, bad globs/regexes, backtracking-prone patterns, and counts over `maxRules` are load-time errors: `badFilePolicy: fail` (default) makes the first tool call in that workspace fail loudly; `ignore-with-warning` warns and degrades to an empty rule set.
 - An absolute `rulesFile` or a configured `fallbackPath` is validated at plugin mount — missing or invalid fails the mount.
 - File changes reload through Chokidar with a debounce (`watch`, `watchStabilityThresholdMs`); a failed reload keeps the previous rules and only warns — never crashes. `/rules reload` triggers the same path manually; `/rules decisions` and `/rules test` inspect the trail and dry-run the rules.
+- Expected-but-absent rule files (the project file when it is not in effect, a fallback after it was deleted) are watched through their deepest existing ancestor directory: creating one mid-session is adopted automatically without a manual reload. Under `searchUp` only the immediate cwd-level candidate is watched — creating a rule file in a deeper ancestor still needs `/rules reload`.
+- `/rules` lists the active rules (with `list` as an explicit alias); in multi-file chains every rule line is attributed to its own source file.
+- `/rules test` accepts leading flags: `--cwd <dir>` evaluates against another workspace (rule discovery AND path normalization), `--env KEY=VALUE` (repeatable) overrides host env for `when.env`, `--agent <selector>` (repeatable) supplies identity candidates for the `agents` dimension, and `--platform <name>` overrides the host platform for `when.platform`.
+- `enforce: false` puts the plugin in dry-run mode: deny/ask hits are audit-logged with a `dryRun` marker (keeping the would-be action and the real downstream outcome) and every call passes through — use it to trial a new policy in production before enforcing it. `/rules` prints a dry-run notice while the mode is active.

package/docs/rules-format.md

@@ -17,13 +17,14 @@ rules:        # 规则列表，按书写顺序求值；可以省略或为空
     reason: ...
 ```
 
-顶层只允许 `rules` 一个键；每条规则只允许 `match`、`action`、`reason`、`enabled`、`description`、`tags` 六个键；`match` 只允许 `tools`、`params`、`paths`、`absent`、`when` 五个键。出现任何未知键都在加载期报错（响亮失败），绝不静默忽略。
+顶层只允许 `rules` 一个键；每条规则只允许 `match`、`action`、`reason`、`enabled`、`description`、`tags` 六个键；`match` 只允许 `tools`、`agents`、`params`、`paths`、`absent`、`when` 六个键。出现任何未知键都在加载期报错（响亮失败），绝不静默忽略。
 
 ## match 维度（全部 AND）
 
 | 维度 | 类型 | 语义 |
 |---|---|---|
 | `tools` | `string[]` | 工具名 glob（始终 glob 解释，与 `patternMode` 无关）。空/缺省 = 不限制。支持 `mcp__*` 等前缀匹配。 |
+| `agents` | `string[]` | 调用方代理身份选择器 glob，匹配会话头推导出的候选：`main`（顶层会话）、`subagent`（子代理会话）、`preset:<name>`（由预设组合的代理）。**任一选择器命中任一候选**即满足该维度；空/缺省 = 不限制。身份未知（无候选）永不命中——面向代理的规则按失败关闭（fail closed）处理。 |
 | `params` | `Record<string, string \| number \| boolean \| (…)[]>` | 参数键 → 模式（或模式列表）。**列出的每个键都必须存在且命中**（AND）；缺省 = 不限制。标量值按字符串匹配（数字/布尔字符串化）；数组任一元素命中即可；嵌套对象贡献其标量叶子（深度上限 8）。`!` 前缀为否定：值必须**不**命中该模式；只含否定的键在键存在且全部否定未命中时命中（YAML 里请给 `!` 模式加引号：`"!git*"`）。params 模式中 `/` 是普通字符，`*` 可跨 `/`。 |
 | `paths` | `string[]` | 工作区相对路径模式，任一候选命中任一模式即可。候选来自参数中下列键的值（**任意嵌套深度**、深度上限）：`path` `paths` `file` `files` `file_path` `dir` `directory` `directories` `cwd` `workspace` `root` `target` `targets` `output`。工作区外的绝对候选被丢弃；相对 `../` 形式保留，可显式匹配工作区外。路径模式中 `*` 不跨 `/`，`**` 跨任意深度（含零层）。`caseInsensitivePaths` 开启时（Windows 默认）根比较与模式匹配忽略 ASCII 大小写。 |
 | `absent` | `string[]` | 必须**缺席**的参数键；**每个列出的键都必须缺失**（非对象参数天然满足）。 |
@@ -97,7 +98,11 @@ rules:
 
 ## 加载与热更新
 
-- 按会话 cwd 惰性发现，首次 `tools/pre-execute` 时加载并缓存（超出 `maxCachedWorkspaces` 逐出最久未用项）。
+- 按会话 cwd 惰性发现，首次 `tools/pre-execute` 时加载并缓存（超出 `maxCachedWorkspaces` 逐出最久未用项）；缓存键为解析后的 cwd（Windows 上折叠大小写），同一目录的不同拼写共享同一条目。
 - 非法 YAML / 未知字段或 action / 坏 glob 与正则 / 易回溯灾难的模式 / 超 `maxRules` 都是加载期错误：`badFilePolicy: fail`（默认）时首个使用该工作区的工具调用响亮失败；`ignore-with-warning` 时告警并降级为空规则集。
 - 绝对 `rulesFile` 或配置的 `fallbackPath` 在插件挂载时即校验，缺失/非法直接挂载失败。
 - 文件变更后经 Chokidar 去抖重读（`watch`、`watchStabilityThresholdMs`）；重读失败保留旧规则、只告警，绝不崩溃。`/rules reload` 手动触发同样路径；`/rules decisions` 回放审计轨迹，`/rules test` 对假设调用干跑规则。
+- 预期存在但缺失的规则文件（未生效的项目文件、被删除后的 fallback）会通过其最近存在祖先目录被监听：会话中途创建即自动采纳，无需手动重载。`searchUp` 下只监听 cwd 层级的候选——更上层祖先新建规则文件仍需 `/rules reload`。
+- `/rules` 列出当前规则（`list` 为显式别名）；多文件链中每条规则行标注自己的来源文件。
+- `/rules test` 支持前置标志：`--cwd <目录>` 换一个工作区求值（规则发现与路径归一化都切换）；`--env 键=值`（可重复）覆盖宿主环境变量以测试 `when.env`；`--agent <选择器>`（可重复）为 `agents` 维度提供身份候选；`--platform <平台名>` 覆盖宿主平台以测试 `when.platform`。
+- `enforce: false` 让插件进入干跑模式：deny/ask 命中只写审计（带 `dryRun` 标记，记录「本会做什么」与下游真实结果），所有调用照常透传——用于在生产环境先试跑新策略再强制执行。激活期间 `/rules` 会打印干跑提示。

package/docs/rules-format.schema.json

@@ -54,6 +54,11 @@
           "type": "array",
           "items": { "type": "string", "minLength": 1 }
         },
+        "agents": {
+          "description": "Agent-identity selector globs (main, subagent, preset:<name>); any selector matching any candidate satisfies the dimension. Unknown identity never matches.",
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
         "params": {
           "description": "Param key to pattern(s). EVERY key must be present and match; a !-prefixed pattern negates. Scalars are stringified; arrays and nested objects contribute their scalar leaves.",
           "type": "object",