dsh-perm-gate 2.1.2 → 4.0.0

package/README.ja.md

@@ -45,7 +45,7 @@
 > メソッドであるため、`typeof` プロブで読み取り、欠落時やエラー時には「ポリシー
 > 不明」にフォールバックします。
 
-バージョン **2.1.2** — 変更履歴は [日本語 changelog](./CHANGELOG.ja.md) を参照。
+バージョン **2.4.1** — 変更履歴は [日本語 changelog](./CHANGELOG.ja.md) を参照。
 
 DeepSeek Harness 向けの、単一・自己完結・決定論優先・fail-closed な権限ゲートです。
 
@@ -202,7 +202,16 @@ DSH **自身**の通信 —— 組み込みネットワークツールと LLM
 自动审查は権限ピッカーの中で 読み取り専用 / ワークスペース内変更 / 完全権限 /
 許可リストと並ぶ**独立した承認ティア**です。汎用の「自動承認」ではなく、包括的な権限を
 発行することもありません。人間/LLM のシーム**の前**で判定を狭めたり広めたりする
-だけで、P0 ハード拒否は単調かつ交渉不能のままです。
+だけで、P0 ハード拒否は**ゲート自身のスコープ内で**単調かつ交渉不能のままです。
+
+> **P0 はスコープ付きであり、グローバルではありません。** このゲートはセッションの権限プリセットが
+> `gatePresets`(既定は `permissive` / `permissive-full`)のいずれかである間だけ動作します。それ以外の
+> プリセット —— 読み取り専用 / ワークスペース内変更 / 完全権限 —— では **P0 ハード拒否を含むゲート
+> 全体が停止**し、選択されたティア自身のポリシーがそのセッションを統治します。これは意図的な設計です
+> (設定表の `gatePresets` を参照)が、「P0 は交渉不能」は**ゲートのティア内**で成立するものであり、
+> すべてのティアに跨るものではありません。停止は**沈黙しません**: セッション/プリセットの遷移ごとに
+> `stand-down` イベントを 1 件記録し、ブラウザは入力欄の上に **GATE OFF** の常駐ストリップを表示します。
+> `gatePresets: ['*']` に設定すると P0 は再びグローバルになります。
 
 **2 つのバリアントを同梱します。** プリセットの `sandbox` と `approval` は**独立した**ノブであり、
 両者を結び付けると悪いトレードオフを強いられるためです。
@@ -296,8 +305,10 @@ never` パススルー — は人手に変更なく委譲されるため、将
 ゲートが動作するのは **`gatePresets` に列挙したティアの中だけ**です（既定
 `['permissive', 'permissive-full']`、このプラグインが追加する 2 つのティア）。それ以外のティア（Read Only / Workspace Write /
 Full access / `custom`）では、ゲートの判定フローは**一切実行されません**——許可も、ask も、
-拒否も、P0 ハード拒否も、拒否キーワードの遮断も、監査イベントの記録も行いません。選択された
-ティア自身の方針が呼び出しを決めます。`danger-full-access` の定義は「承認プロンプトなしの
+拒否も、P0 ハード拒否も、拒否キーワードの遮断も行いません。選択された
+ティア自身の方針が呼び出しを決めます。ただし**沈黙はしません**: セッション/プリセットの遷移ごとに
+`stand-down` イベントを 1 件だけ記録し（判定ではなく通知です）、ブラウザは入力欄の上に
+**GATE OFF** の常駐ストリップを表示します。`danger-full-access` の定義は「承認プロンプトなしの
 フルアクセス」であり、そこを ask で上書きしても意味がありません（その方針では DSH の承認シームが
 **どの answerer よりも先に** `rejected` を返し、転送された ask はパネルを一度も表示せず
 `the user rejected tool "..."` にしかなりません）。ハード拒否で上書きするのも、ユーザーが選んだ
@@ -319,7 +330,8 @@ Full access / `custom`）では、ゲートの判定フローは**一切実行
 `llmAssist` 有効時、設定された LLM（OpenAI 互換エンドポイントなら任意——`classifierEndpoint` / `classifierModel` / `classifierApiKey` を自分の API に向けてください）が構造化プロトコルで `ask` を 1 件ずつ判定します。**判定はゲートの `tools/pre-execute` ウォーターフォール内、決定がホストへ返る前に行われます**：`safe` はそのまま委譲されるため承認パネルは一切表示されず、本当に判断できない判定だけが人手に回ります。
 
 - `safe` → 自動許可（監査ソースは `classifier`）。パネルは表示されません。
-- `risky` + **ハードリスクカテゴリ**（`deletion`、`credential`、`remote`、`system`、`bulk`）→ **自動拒否**、パネルなし。ハードリスクは自動許可も学習もされません。
+- `risky` + **ハードリスクカテゴリ**（`deletion`、`credential`、`remote`、`system`、`bulk`）→ **人間への確認（ask）を維持**します。分類器は**決して拒否しません**。拒否は決定論的レイヤー（P0 ハード拒否、拒否キーワードのブラックリスト、明示的な `deny:` ルール）だけに属するため、誤判定されたカテゴリは常に交渉可能で、異議を唱えられないブロックにはなりません。ハードカテゴリが `neutral` と異なる重要な点は一つだけです: **決して学習されない**ため、承認を繰り返しても自動許可に沈殿しません。
+  （モデルの判断を拒否の根拠にした結果は実測済みです: 無害な `git commit -F …` が `remote` と判定され、パネルも再試行用の grant もない自動拒否が発生しました。）
 - `risky:neutral` → `riskLearning` 有効時（設定カード内、既定オフ）、人手で承認され実際に実行された neutral リスクは `tool|カテゴリ` ごとにカウントされ、`riskThreshold`（既定 3）到達かつ新呼び出しの操作指紋（コマンド語＋対象の基底名）が確認済みサンプルに一致した場合、**同一操作のみ**自動許可されます。学習沈殿（`riskSediment`、既定オン）を有効にすると、しきい値に達したキーの確認サンプルは**決定論的な許可ルール**になります：指紋の正確一致は LLM を経由せず自動許可——llmAssist オフでも継続し、沈殿ルールは設定カードで確認・管理（終止 / サンプル削除）できます。
 - タイムアウト（`riskTimeoutMs`、既定 20 秒、1 回リトライ）、通信失敗、プロトコル外出力は元の `ask` を維持します。
 

package/README.ko.md

@@ -43,7 +43,7 @@
 > 모두에서 user-approval 서비스의 **개인** 메소드이므로 `typeof` 프로브를 통해
 > 읽으며, 누락되거나 예외 발생 시 "정책_unknown"으로 후퇴합니다.
 
-버전 **2.1.2** — 변경 내역은 [한국어 changelog](./CHANGELOG.ko.md)를 참고하세요.
+버전 **2.4.1** — 변경 내역은 [한국어 changelog](./CHANGELOG.ko.md)를 참고하세요.
 
 DeepSeek Harness용 단일·자족적·결정론 우선·fail-closed 권한 게이트입니다.
 
@@ -196,8 +196,17 @@ DSH **자신**의 트래픽 —— 내장 네트워크 도구와 LLM 전송 —
 
 自动审查는 권한 선택기에서 읽기 전용 / 워크스페이스 내 수정 / 완전 권한 / 허용 목록과
 나란한 **독립 승인 티어**입니다. 범용 "자동 승인"이 아니며 포괄적 권한을 발행하지도 않습니다.
-사람/LLM 심 **이전에** 판정을 좁히거나 넓힐 뿐이고, P0 하드 거부는 단조롭고 협상
-불가능하게 유지됩니다.
+사람/LLM 심 **이전에** 판정을 좁히거나 넓힐 뿐이고, P0 하드 거부는 **게이트 자체 범위 안에서**
+단조롭고 협상 불가능하게 유지됩니다.
+
+> **P0는 범위가 있으며 전역이 아닙니다.** 이 게이트는 세션 권한 프리셋이 `gatePresets`(기본값
+> `permissive` / `permissive-full`) 중 하나일 때만 동작합니다. 그 밖의 프리셋 —— 읽기 전용 /
+> 워크스페이스 내 수정 / 완전 권한 —— 에서는 **P0 하드 거부를 포함한 게이트 전체가 정지**하고,
+> 선택된 티어 자체의 정책이 그 세션을 통치합니다. 의도된 설계이지만(설정 표의 `gatePresets` 참조),
+> "P0는 협상 불가"는 **게이트의 티어 안에서** 성립하는 것이지 모든 티어에 걸친 것이 아닙니다.
+> 정지는 **침묵하지 않습니다**: 세션/프리셋 전환마다 `stand-down` 이벤트 1건을 기록하고 브라우저는
+> 입력창 위에 **GATE OFF** 상시 표시줄을 띄웁니다. `gatePresets: ['*']`로 설정하면 P0는 다시
+> 전역이 됩니다.
 
 **두 가지 변형을 함께 제공합니다.** 프리셋의 `sandbox`와 `approval`은 **독립된** 노브이며, 둘을
 묶으면 나쁜 트레이드오프를 강요받기 때문입니다.
@@ -294,8 +303,10 @@ never` 패스스루 — 는 사람에 그대로 위임되므로 향후 DSH 변
 게이트가 동작하는 범위는 **`gatePresets`에 나열한 티어 안뿐**입니다(기본
 `['permissive', 'permissive-full']`, 이 플러그인이 추가하는 두 티어). 그 밖의 티어(Read Only / Workspace Write / Full access /
 `custom`)에서는 게이트의 판정 흐름이 **전혀 실행되지 않습니다** — 허용도, ask도, 거부도,
-P0 하드 거부도, 거부 키워드 차단도, 감사 이벤트 기록도 하지 않습니다. 선택한 티어의 자체 정책이
-호출을 결정합니다. `danger-full-access`의 정의는 "승인 프롬프트 없는 전체 접근"이며, 이를 ask로
+P0 하드 거부도, 거부 키워드 차단도 하지 않습니다. 선택한 티어의 자체 정책이
+호출을 결정합니다. 다만 **침묵하지는 않습니다**: 세션/프리셋 전환마다 `stand-down` 이벤트를 1건만
+기록하고(판정이 아니라 알림입니다), 브라우저는 입력창 위에 **GATE OFF** 상시 표시줄을 띄웁니다.
+`danger-full-access`의 정의는 "승인 프롬프트 없는 전체 접근"이며, 이를 ask로
 덮어써도 의미가 없습니다(그 정책에서는 DSH 승인 시임이 **어떤 answerer보다도 먼저** `rejected`를
 반환해 전달된 ask는 패널을 한 번도 띄우지 못하고 `the user rejected tool "..."`만 남습니다).
 하드 거부로 덮어쓰는 것 역시 사용자가 고른 티어를 조용히 뒤집는 일입니다.
@@ -315,7 +326,8 @@ host는 네임스페이스를 live로 읽으므로 변경은 재시작 없이
 `llmAssist`가 켜져 있으면 설정된 LLM(OpenAI 호환 엔드포인트라면 무엇이든 — `classifierEndpoint` / `classifierModel` / `classifierApiKey`을 자신의 API로 지정)이 구조화된 프로토콜로 `ask`를 하나씩 판정합니다. **판정은 게이트의 `tools/pre-execute` 워터폴 안에서, 결정이 호스트로 반환되기 전에 이루어집니다**: `safe`는 곧바로 위임되므로 승인 패널이 아예 표시되지 않고, 정말로 판단할 수 없는 판정만 사람에게 전달됩니다.
 
 - `safe` → 자동 허용(감사 소스 `classifier`), 패널 없음.
-- `risky` + **하드 위험 카테고리**(`deletion`, `credential`, `remote`, `system`, `bulk`) → **자동 거부**, 패널 없음. 하드 위험은 자동 허용도 학습도 되지 않습니다.
+- `risky` + **하드 위험 카테고리**(`deletion`, `credential`, `remote`, `system`, `bulk`) → **사람 확인(ask)을 유지**합니다. 분류기는 **결코 거부하지 않습니다**. 거부는 결정론적 계층(P0 하드 거부, 거부 키워드 블랙리스트, 명시적 `deny:` 규칙)에만 속하므로, 잘못 판정된 카테고리는 언제나 협상 가능하며 이의를 제기할 수 없는 차단이 되지 않습니다. 하드 카테고리가 `neutral`과 다른 중요한 점은 하나뿐입니다: **결코 학습되지 않으므로** 승인을 반복해도 자동 허용으로 침전되지 않습니다.
+  (모델의 판단을 거부 근거로 삼은 결과는 실측되었습니다: 무해한 `git commit -F …`가 `remote`로 판정되어 패널도, 재시도용 grant도 없는 자동 거부가 발생했습니다.)
 - `risky:neutral` → `riskLearning` 활성 시(설정 카드, 기본 꺼짐), 사람이 승인하고 실제 실행된 neutral 위험은 `tool|카테고리` 키로 카운트되며, `riskThreshold`(기본 3) 도달 및 새 호출의 작업 지문(명령어 단어 + 대상 기본 이름)이 확인된 샘플과 일치하면 **동일 작업만** 자동 허용됩니다. 학습 침전(`riskSediment`, 기본 켜짐)을 사용하면 임계값에 도달한 키의 확인 샘플이 **결정론적 허용 규칙**이 됩니다: 지문이 정확히 일치하면 LLM 호출 없이 바로 허용——llmAssist가 꺼져도 유지되며, 침전 규칙은 설정 카드에서 확인·관리(종료 / 샘플 삭제)할 수 있습니다.
 - 시간 초과(`riskTimeoutMs`, 기본 20초, 1회 재시도), 전송 실패, 프로토콜 외 출력은 원래 `ask`를 유지합니다.
 

package/README.md

@@ -42,7 +42,7 @@
 > **private** method of the user-approval service on both, so it is read behind a
 > `typeof` probe and degrades to “policy unknown” when absent or throwing.
 
-Version **2.1.2** — see the [Changelog](./CHANGELOG.md).
+Version **3.0.0** — see the [Changelog](./CHANGELOG.md).
 
 A single, self-sufficient, deterministic-first, fail-closed permission gate for DeepSeek Harness.
 
@@ -229,7 +229,16 @@ proxy liveness, env-injection state, block counters, recent blocks).
 自动审查 is an **independent approval tier** in the DSH permission picker, parallel to
 Read Only / Workspace Write / Full access / Whitelist. It is **not** generic "auto-approval" and
 never mints blanket authority: it only narrows or widens the seam *before* the human/LLM step
-while P0 hard-deny stays monotonic and non-negotiable.
+while P0 hard-deny stays monotonic and non-negotiable **within the gate's own scope**.
+
+> **P0 is scoped, not global.** The gate acts only while the session's permission preset is one
+> of `gatePresets` (default `permissive` / `permissive-full`). Under any other preset — Read Only,
+> Workspace Write, or Full access — the **entire** gate stands down, P0 hard-deny included,
+> because the selected tier's own policy governs that session. This is deliberate (see
+> `gatePresets` in the configuration table), but it means "P0 is non-negotiable" holds *inside*
+> the gate's tiers rather than across every tier. A stand-down is not silent: the gate records one
+> `stand-down` event per session/preset transition and the browser shows a sticky **GATE OFF**
+> strip above the input. Set `gatePresets: ['*']` to make P0 global again.
 
 **Two variants ship**, because a preset's `sandbox` and `approval` are independent knobs and
 coupling them forced a bad trade:
@@ -326,7 +335,13 @@ optionally overridden with `classifierProvider` / `classifierModel`). A **health
 
 - `safe` → the call is auto-allowed (audited as the `classifier` source); no panel is shown.
 - `risky` + a **hard category** (`deletion`, `credential`, `remote`, `system`, `bulk`) → the call
-  is **auto-denied** without a panel; hard risks are never auto-allowed and never learned.
+  **keeps the human ask**. The classifier **never denies**: the deny path belongs to the
+  deterministic layers alone (P0 hard-deny, the deny-keyword blacklist, explicit `deny:` rules), so
+  a misgraded category is always negotiable instead of an unappealable block. Hard categories stay
+  distinct from `neutral` in one way that matters: they are **never learned**, so repeated
+  approvals can never sediment them into an auto-allow.
+  (Denying on the model's word was measured live: a benign `git commit -F …` graded `remote`
+  produced an auto-deny with no panel and no grant to retry with.)
 - `risky:neutral` → with `riskLearning` enabled (Settings card, off by default), each human
   approval that actually executes (settled via the host's `tools/result` event) counts toward
   a `tool|category` key; once the count reaches `riskThreshold` (default 3) **and** the new
@@ -393,6 +408,21 @@ The tier is also adjustable at runtime from **Settings → Plugins → 自动审
 namespace live, so a change applies to the next tool call without a restart. This is an
 independent approval class, NOT a generic "auto-approval" mode.
 
+### Rule test (dry-run)
+
+The same page carries a **Rule test** panel: type a tool name and a command, press Test, and the
+gate judges that call against the ruleset it currently has loaded — without running anything and
+without writing any rule. You get the verdict, the matched rule (index and action), the dimensions
+that rule constrains, and the reason.
+
+It reports the effective verdict (the whole P0 → P1 → P2 → P3 → P4 chain) *and* the rule layer's own
+answer, which are not the same thing: a P0 hard-deny or a preset deny-keyword fires before the rule
+chain and leaves no rule index behind, so the panel says "no rule matched" rather than naming an
+unrelated rule. A `0 rules loaded` note means the `rulesFile` path resolved to nothing.
+
+The panel talks to `POST /api/dsh-perm-gate/dry-run`, which is **read-only by construction** — it
+has no write form at all, so testing a rule can never change it.
+
 ## CLI
 
 Dry-run one call against a rules file (no harness needed):

package/README.zh.md

@@ -39,7 +39,7 @@
 > 线上都是 user-approval 服务的**私有**方法，因此通过 `typeof` 探测读取，缺失
 > 或抛错时降级为「策略未知」。
 
-版本 **2.1.2** —— 变更见 [Changelog](./CHANGELOG.md)。
+版本 **2.4.1** —— 变更见 [Changelog](./CHANGELOG.md)。
 
 一个**单一自足、确定性优先、fail-closed** 的 DeepSeek Harness 权限门插件。
 
@@ -151,7 +151,14 @@ DSH **自身**的网络流量 —— 内建网络工具与 LLM 传输 —— 刻
 
 自动审查是权限下拉框里一个**独立审批档**，与只读 / 工作区内修改 / 完全权限 / 白名单平行。
 它不是泛化的"自动审批"、也不授予泛化权限：只会在人类/LLM 接缝**之前**收窄或放宽决策，
-P0 硬拒绝始终单调且不可协商。
+P0 硬拒绝在**本门禁自身的档位作用域内**始终单调且不可协商。
+
+> **P0 是档位作用域内的，不是全局的。** 门禁只在会话权限档位属于 `gatePresets`
+> （默认 `permissive` / `permissive-full`）时生效。其他档位 —— 只读、工作区内修改、完全权限
+> —— 下**整个门禁停用，包括 P0 硬拒绝**，因为该档位自身的策略接管了这个会话。这是刻意设计
+> （见配置表的 `gatePresets`），但也就意味着「P0 不可协商」成立于**门禁的档位之内**，而非所有档位。
+> 停用**不是静默的**：每次会话档位切换会记录一条 `stand-down` 事件，浏览器在输入框上方常驻一条
+> **GATE OFF** 提示条。把 `gatePresets` 设为 `['*']` 可让 P0 重新变成全局。
 
 **提供两个变体** —— 因为预设的 `sandbox` 与 `approval` 是两根**独立**旋钮，把它们绑死会逼出
 一个糟糕的取舍：
@@ -252,7 +259,8 @@ LLM 评定为 `safe` 且门禁自动放行的调用因此仍会弹出确认。
 开启 `llmAssist` 后，接收 LLM（自定义 OpenAI 兼容端点，或 DSH 宿主模型组——见上文）按结构化协议逐条评估 `ask`。**判定发生在门禁的 `tools/pre-execute` 瀑布内部、决策返回宿主之前**：`safe` 直接放行，审批面板根本不会出现；只有真正无法确定的判定才会弹到你面前。
 
 - `safe` → 自动放行（审计来源为 `classifier`），不弹面板。
-- `risky` + **硬风险类别**（`deletion`、`credential`、`remote`、`system`、`bulk`）→ **自动拒绝**、不弹面板；硬风险永不自动放行、也永不进入学习。
+- `risky` + **硬风险类别**（`deletion`、`credential`、`remote`、`system`、`bulk`）→ **维持人工确认（ask）**。分类器**永不拒绝**：拒绝只属于确定性层（P0 硬拒绝、黑名单关键词、显式 `deny:` 规则），所以被误判的类别永远可协商，而不会变成无法申诉的封禁。硬类别与 `neutral` 仅保留一条关键区别：**永不进入学习**，因此反复确认也不可能把它沉淀成自动放行。
+  （拿模型的判断当拒绝依据是实测出来的问题：一条无害的 `git commit -F …` 被判 `remote`，直接自动拒绝——没有面板、也没有可重试的授权入口。）
 - `risky:neutral` → 若开启 `riskLearning`（设置卡片内，默认关闭），人工批准且真实执行的 neutral 风险会按 `tool|类别` 计数；计数达到 `riskThreshold`（默认 3）且新调用的操作指纹（命令词 + 目标基名）命中已确认样本时，**同一操作**自动放行。不同目标永不复用该放行。开启学习沉淀（`riskSediment`，默认开）后，满阈值 key 的确认样本会成为**确定性放行规则**：指纹精确命中即直接放行、无需再过 LLM——即使关闭 llmAssist 也继续生效；沉淀规则在设置卡片中可见、可管理（终止学习 / 删除样本）。
 - 超时（`riskTimeoutMs`，默认 20s，重试 1 次）、传输失败与协议外输出均维持原 `ask`——门禁绝不猜测。
 

package/docs/baseline-guard.md

@@ -0,0 +1,56 @@
+# Baseline Snapshot: feat/capability-absorption
+
+> Captured at T0.3/T0.4 on 2026-09-15
+>
+> **为什么这份快照留在仓库里**：下面那 30 个测试文件是能力吸收（6 维度 / 网络执行面 / 热重载）
+> 落地**之前**的既有覆盖，充当回归护栏——新增行为**不得**靠修改它们来适配。
+> 原位置 `.agents/baseline-snapshot.md` 未入库（`.agents/` 是仓库惯例的本地目录），
+> 2026-09-17 迁到 `docs/` 以便随包分发、可追溯。
+> 注意：仓库当前已有 **40** 个测试文件；本列表是**护栏基线**，不是当前全量清单。
+
+## Gate Status
+
+| Gate | Status | Notes |
+|------|--------|-------|
+| typecheck | ✅ 0 errors | After pre-existing fix commit |
+| test | ✅ 278/278 | 30 spec files |
+| build | ✅ tsc + tsdown | client.js 99.95 kB |
+| lint | ✅ 0 errors | — |
+
+## Pre-existing Fixes (committed)
+
+- `src/risk.ts:137-138` — cast `req.args` to `Record<string, unknown>` (was `{}`)
+- `src/runtime.ts:26` — add `import { decomposeShellCommand } from './shell.js'`
+
+## Test File List (30 files, DO NOT modify to accommodate new behavior)
+
+1. audit.spec.ts
+2. auto-allow-tools.spec.ts
+3. compiler.spec.ts
+4. custom-llm.spec.ts
+5. data-home.spec.ts
+6. deny-keywords.spec.ts
+7. deny-keywords-scope.spec.ts
+8. engine.spec.ts
+9. evaluate.spec.ts
+10. events.spec.ts
+11. feature.spec.ts
+12. grant.spec.ts
+13. host-llm.spec.ts
+14. learning.spec.ts
+15. manual-approval.spec.ts
+16. patch-presets.spec.ts
+17. permissive.spec.ts
+18. pre-execute.spec.ts
+19. preset-scope.spec.ts
+20. review.spec.ts
+21. risk.spec.ts
+22. rule.spec.ts
+23. runtime.spec.ts
+24. runtime-risk.spec.ts
+25. sediment.spec.ts
+26. session-resolution.spec.ts
+27. session-sweep.spec.ts
+28. session-sweep-apply.spec.ts
+29. shell.spec.ts
+30. write-path.spec.ts

package/docs/rules-format.en.md

@@ -0,0 +1,294 @@
+# Rules File Format (`permissions` YAML)
+
+> **Authority**: the dimension list below is byte-for-byte identical to `VALID_KEYS` in
+> `src/rule.ts:181`. A change to either must be mirrored; `test/rule.spec.ts` and
+> `test/rule-dims.spec.ts` are the runtime guards.
+> Applies to `dsh-perm-gate` **2.4.1** (DSH ≥ 0.1.2-alpha.1).
+
+---
+
+## 1. Location and loading
+
+| Item | Description |
+|---|---|
+| Default path | `<dataDir>/rules.yml` (`dataDir` resolved by `config.resolveDataDir`, default `$DSH_HOME/perm-gate/`) |
+| Explicit | `config.rulesFile` |
+| Rule chain | Multi-file chains supported (`rulesChain` / `searchUp` / `fallbackPath` / `badFilePolicy` / `maxRules`) — see `src/rule-chain.ts` |
+| Hot reload | `src/watch.ts` (chokidar) watches the effective files and recompiles the whole chain after a debounce |
+| Parse failure | **fail loud** — invalid rules raise, they never silently stand the gate down |
+
+---
+
+## 2. Top level
+
+```yaml
+defaultAction: ask        # optional; used when nothing matches. Default: ask
+deny:                     # action partitions (arrays)
+  - <rule entry>
+allow:
+  - <rule entry>
+ask:
+  - <rule entry>
+```
+
+**The action IS the partition**: entries carry no `action` field (if present it must agree with its
+partition). Evaluation order is fixed: **deny → allow → ask → defaultAction**, first match wins
+(deny wins over allow). The keyword blacklist runs ahead of `deny`.
+
+`defaultAction` accepts `allow` | `ask` | `deny` (default `ask`).
+
+---
+
+## 3. Entry fields (`VALID_KEYS`)
+
+```
+tools · command · args · paths · params · absent · agents · when · argv · network · branch
+action · reason · enabled
+```
+
+| Field | Type | Purpose |
+|---|---|---|
+| `tools` | string / string[] | Tool-name glob |
+| `command` | string / string[] | Command word, with `word#recursive` / `word#force` suffixes |
+| `args` | string / string[] | Argument token scan |
+| `paths` | string / string[] | Workspace-relative path glob |
+| `params` | mapping | Parameter key → value glob list |
+| `absent` | string / string[] | Parameter keys that must NOT be present |
+| `agents` | string / string[] | `main` / `subagent` / `preset:<name>` |
+| `when` | mapping | Environment and platform conditions |
+| `argv` | mapping | Extra argv patterns (`pipeline`) |
+| `network` | mapping | Domain / IP / port / scheme |
+| `branch` | mapping | Git branch / remote / protected branch (git commands only) |
+| `action` | `allow`\|`ask`\|`deny` | Optional; must agree with its partition |
+| `reason` | string | Human-readable rationale (lands in events and the UI) |
+| `enabled` | boolean | `false` skips the entry |
+
+**Across dimensions = AND**: every dimension present in one entry must be satisfied.
+**Within a dimension = OR**: any single pattern in the list suffices (`params` / `when` /
+`network` use AND across their sub-keys — see below).
+
+---
+
+## 4. Dimension semantics
+
+### 4.1 `tools` — tool name
+```yaml
+- tools: [shell, pwsh, bash]
+```
+Glob match. OR within the list.
+
+### 4.2 `command` — command word
+```yaml
+- command: [rm#recursive, rm#force]
+```
+Words come from argv decomposition (`src/shell.ts`). The `#recursive` / `#force` suffixes
+require the corresponding semantics. OR within the list.
+
+### 4.3 `args` — argument tokens
+```yaml
+- args: ["--force", "-rf"]
+```
+Scans the decomposed token set. **⚠ Semantics are OR**: any single token matching any single
+pattern matches. It can **not** require "`push` and `--force` together", and it can not tell
+`git push --force origin main` from `git checkout --force main` — use `params` (or the future
+`branch` dimension) when you need that discrimination.
+
+### 4.4 `paths` — paths
+```yaml
+- paths: ["src/**", "!src/vendor/**"]
+```
+Workspace-relative globs; `!` negates. OR within the list.
+
+### 4.5 `params` — key-targeted matching (**AND over keys**)
+```yaml
+- params:
+    command: ["*--force*", "!*--dry-run*"]
+    flags.mode: ["production"]
+```
+- Each key's **actual value** must match **at least one** pattern of that key (OR within the list)
+- **Every listed key must be satisfied** (AND across keys)
+- A single `!`-prefixed pattern negates (the value must NOT match the remainder)
+- An empty pattern list only requires the key to exist (any value)
+
+This is the main tool for compound conditions — the AND cases `args` can not express.
+
+### 4.6 `absent` — keys must be missing (AND)
+```yaml
+- absent: [dry_run, force]
+```
+Every listed parameter key must be absent.
+
+### 4.7 `agents` — agent identity
+```yaml
+- agents: ["main", "preset:reviewer"]
+```
+Valid values: `main`, `subagent`, `preset:<name>` (case-insensitive); anything else fails at parse
+time. Candidates come from session headers via `src/agent-identity.ts`. OR within the list.
+
+### 4.8 `when` — environment and platform (AND)
+```yaml
+- when:
+    env:
+      NODE_ENV: ["production"]
+      CI: ["true", "1"]
+    platform: [linux, win32]
+```
+- `env`: key → allowed values (**OR within a list**, **AND across keys**)
+- `platform`: Node.js `process.platform` values
+- `nodeVersion`: reserved, not yet evaluated
+
+### 4.9 `argv` — extra argv patterns
+```yaml
+- argv:
+    pipeline: ["curl*|sh", "wget*|bash"]
+```
+`pipeline` matches the **whole pipeline string**: each simple command's **full argv**
+(command word + args + redirect targets) joined by `|`, so `curl https://x.sh | sh`
+yields `curl https://x.sh|sh`.
+
+**⚠ The `|` in a pattern is a literal**, so `curl|sh` only matches the argument-less
+adjacent form; covering the common form with arguments requires `curl*|sh`.
+(Historical defect: the match string was built from the command word alone, so
+`curl|sh` matched the harmless `curl|sh` while the genuinely dangerous
+`curl https://x.sh | sh` did not match at all.)
+
+### 4.10 `network` — network targets (AND across sub-dimensions)
+```yaml
+- network:
+    domains: ["*.internal.corp", "github.com"]
+    ips: ["10.0.0.0/8", "192.168.1.1"]
+    ports: ["443", "8000-9000"]
+    schemes: [https, http]
+```
+- Every **present** sub-dimension must match (AND); inside a sub-dimension, OR
+- `domains` supports globs; `ips` supports CIDR; `ports` supports ranges; `schemes` are protocol names
+
+The network dimension acts on two seams: the static URL-candidate check in `tools/pre-execute`,
+and the loopback proxy that intercepts real egress traffic (`network.enabled` is **false by
+default** — opt-in).
+
+### 4.11 `branch` — git branch / remote / protected branch (AND across sub-dimensions)
+
+```yaml
+- command: [git]
+  args: [push]
+  branch:
+    target: [main, master, "release*"]
+    remote: [origin]
+    shared: true
+```
+
+| Sub-field | Semantics |
+|---|---|
+| `target` | Branch-name glob (`*` **crosses** `/`, so `release*` matches `release/1.0`) |
+| `remote` | Remote-name glob |
+| `shared` | Require the target branch to be a **protected** branch |
+
+**Why this dimension exists**: `args` is OR-over-tokens (§4.3). It can ask "does `--force`
+appear?" but never "does `--force` appear **on a push to a protected branch**?". The decisive
+case is telling two commands with identical tokens apart:
+
+- `git push --force origin main` → dangerous, must match
+- `git checkout --force main` → routine, must **not** match
+
+Candidates come from the shared command classifier (`src/command-dispatcher.ts` +
+`src/parsers/git.ts`), so `refspec` forms (`HEAD:main`) are already split, a remote name is
+never mistaken for a branch name, and flags are normalized.
+
+**Three boundaries worth knowing**:
+
+1. **Git commands only.** A non-git command (`rm -rf`, `npm install`, …) satisfies no `branch`
+   sub-dimension, so a rule that names a branch simply does not match it (and never throws) —
+   those commands are covered by the write-path layer and the blacklist.
+2. **`shared` is static.** It comes from the parser's protected-branch list
+   (`PROTECTED_BRANCHES` in `src/parsers/git.ts`: `main` / `master` / `production` / `release` /
+   `stable`). It does **not** run `git branch -r --contains` — that would put a subprocess on the
+   decision path. Note `shared` and `target` are independent sub-dimensions: with
+   `target: ["release*"]`, `release/1.0` satisfies `target` but not `shared` (the protected list
+   matches exactly).
+3. **AND across sub-dimensions, OR within each**; any one of several simple commands
+   (pipeline / `&&`) may satisfy it.
+
+---
+
+## 5. Complete example
+
+```yaml
+defaultAction: ask
+
+deny:
+  # Credential material in a command (P0 hard-deny also backs this up)
+  - tools: [shell, pwsh]
+    params:
+      command: ["*AWS_SECRET*", "*PRIVATE KEY*"]
+    reason: "credential material in command"
+
+  # Download-and-execute via a pipe
+  - argv:
+      pipeline: ["curl*|sh", "wget*|bash"]
+    reason: "piped download-and-execute"
+
+  # Push to a protected branch (the distinction `args` can not make:
+  # the same tokens on a checkout do not match)
+  - command: [git]
+    args: [push]
+    branch:
+      target: [main, master, "release*"]
+      shared: true
+    reason: "push to a protected branch"
+
+  # Forced recursive delete in production
+  - command: [rm#recursive, rm#force]
+    when:
+      env:
+        NODE_ENV: ["production"]
+    reason: "recursive force delete in production"
+
+allow:
+  # Common read-only queries
+  - tools: [read, grep, glob]
+    reason: "read-only workspace queries"
+
+  # Common dev hosts
+  - network:
+      domains: [github.com, "*.githubusercontent.com"]
+      schemes: [https]
+    reason: "common dev hosts"
+
+ask:
+  # Push needs confirmation (note: args is OR, so this only requires `push` to appear)
+  - command: [git]
+    args: ["push"]
+    reason: "git push requires confirmation"
+```
+
+The same sample ships with the package: `examples/permissions.example.yaml`.
+
+---
+
+## 6. Pairing with the CLI dry-run
+
+Dry-run before you go live:
+
+```powershell
+# List the compiled rules (default action, rule count, permissive-strategy snapshot)
+dsh-perm-gate --rules permissions.yaml --list
+
+# Evaluate one call (--args is JSON; short values can be inlined)
+dsh-perm-gate --rules permissions.yaml --tool read --args "{\"file_path\":\"src/index.ts\"}"
+```
+
+The output is JSON: `decision` (`allow` / `ask` / `deny`), `reason`, `audited`.
+
+**Two gotchas worth knowing**:
+
+1. **The blacklist fires before your rules.** The `deny-keyword` layer runs ahead of the `deny:`
+   partition, so preset words like `rm -rf` or `push --force` are vetoed before your rules are
+   consulted — a `deny-keyword:` prefix in the dry-run output means that layer decided, not your rule.
+2. **Long quoted arguments get re-parsed by PowerShell** (you may see
+   `--args must be valid JSON`). Safe options: write the JSON to a file and pass
+   `--args (Get-Content -Raw args.json)`, or lean on the dimension coverage in
+   `test/rule-dims.spec.ts` and `test/evaluate.spec.ts`.
+
+The CLI and the runtime share one decision engine (`evaluate.ts` + `engine.ts`), so its output is
+the real verdict.