dsh-mask 0.1.4 → 0.2.1

package/ARCHITECTURE.md

@@ -6,7 +6,7 @@
 
 ## Roles
 
-- **Consumes public services only**: `commands`, `storageDomain` (hard `inject`); `tools` (registered via `ctx.inject(['tools'], …)` when present). The masking seam is the `agent/pre-step` waterfall.
+- **Consumes public services only**: `commands` (hard `inject`); `storageDomain` (optional `ctx.get` — missing means a memory-only restore table with a one-time warning); `tools` (registered via `ctx.inject(['tools'], …)` when present). The masking seam is the `agent/pre-step` waterfall.
 - **`lib/` is zero-DSH-dependency**: services are wired only at the boundary in `index.mjs`; `lib/` depends only on `node:` built-ins (the single sanctioned exception is `lib/domain.mjs`, which imports `zod` and `@deepseek-ai/dsh-storage-domain` because the domain record schema is a persistence-boundary validator).
 
 ## Module map
@@ -16,7 +16,7 @@
 | `index.mjs` | The single host face: `Config` schema + `resolveConfig`, `probeIgnorableAppend`, the `agent/pre-step` masking listener, the `/mask` command handler, the `mask_test` tool factory, `apply()` |
 | `lib/constants.mjs` | Vocabulary + protocol constants (entity names/labels, modes, scopes, error codes, defaults, bounds) — zero dependency |
 | `lib/errors.mjs` | Structured domain errors (`MaskError` with stable `code` + `details`) |
-| `lib/strip.mjs` | The regex PII detector and `Stripper` (strip/stripInto/restore/mapping/stats/loadMapping) — zero dependency |
+| `lib/strip.mjs` | The regex PII detector (`regexDetect`), the pluggable-detector `Stripper` (strip/stripInto/restore/mapping/stats/loadMapping), and `createStripper` — zero dependency |
 | `lib/mask.mjs` | Message masking: rewrite `UserMessage` text blocks through a `Stripper` — zero dependency |
 | `lib/sanitize.mjs` | Pure display/log redaction (PII entities, secrets, URL credentials, mapping summarization) |
 | `lib/gate.mjs` | Session-event adaptive gate (append only when the host records the type or supports `ignorable`) |
@@ -48,13 +48,17 @@ Ported from Pii-Stripper-Middleware's `core.py`:
 - Overlap resolution sorts by start ascending, then score descending, and keeps only non-overlapping spans (first-come, higher score wins at the same position) — an 18-digit ID card beats a 16–19-digit bank-card match.
 - Same original value reuses the same placeholder; the counter is monotonic per session so placeholders never collide across turns.
 
+## Detector Provider seam
+
+The detector is a pluggable Provider: `Stripper` and `createStripper` accept an optional `detector: (text) => PIIEntity[]`. When omitted, the built-in `regexDetect` (the ported regex set) runs unchanged, so the zero-dependency default path is untouched. An external recognizer (e.g. NER for `person`/`address`) plugs in by supplying that one function; overlap resolution, placeholder reuse, counting, and restore all stay shared.
+
 ## Session events (adaptive gate)
 
 `mask/applied` is declared through `SessionEventMap` declaration merging in `types.d.ts`. At runtime the plugin appends it only when either (a) the host's `KNOWN_SESSION_EVENT_TYPES` already includes the type, or (b) the host `Session.append` supports the `ignorable` envelope (`probeIgnorableAppend`). On `0.1.1-rc.2` neither is true (verified: rc.2 append reads only `surfaceOp`/`sourceEventSeqs` and never stamps `ignorable`), so the gate stays closed and appends are skipped — sessions keep loading. The audit payload is counts + type distribution only, never plaintext or the mapping.
 
 ## Storage domain
 
-The `dsh_mask` domain has one `restore` table keyed by session id. Its record holds `entries: { placeholder: original }` plus `updatedAt`. This is the only place plaintext PII is stored, and only when `persistRestoreTable: true`; the `Stripper` keeps a bounded in-memory copy (`maxRestoreEntriesPerSession`, `maxSessions` with LRU eviction).
+The `dsh_mask` domain has one `restore` table keyed by session id. Its record holds `entries: { placeholder: original }` plus `updatedAt`. This is the only place plaintext PII is stored, and only when `persistRestoreTable: true`; the `Stripper` keeps a bounded in-memory copy (`maxRestoreEntriesPerSession`, `maxSessions` with LRU eviction). `storageDomain` is an optional service: the bundle patch inserts only the `mask` row, so a profile that already composes the storage stack (`web`, via `@deepseek-ai/dsh-web-app`) provides it, while a bare profile without it gets a memory-only restore table (`persistRestoreTable` is a no-op with a one-time warning).
 
 ## Safety boundaries
 
@@ -65,6 +69,6 @@ The `dsh_mask` domain has one `restore` table keyed by session id. Its record ho
 
 ## Reserved seams
 
-- `mode: regex+ner` — external name/address recognition; fails loudly until a recognizer is wired in.
-- `scope: tools` — masking tool arguments (`tools/pre-execute`); reserved.
-- A browser half would consume the restore table to transparently un-mask assistant bubbles; this pure-host form ships the host-side seam only.
+- `mode: regex+ner` — external name/address recognition; fails loudly until a recognizer is wired in (the detector Provider seam above is the plug point).
+- `scope: tools` — implemented as `tools/post-execute` result-content masking. Tool-argument rewriting is deliberately NOT offered upstream: `tools/pre-execute`'s `PreToolDecision` has no input rewrite because logged/rendered arguments must match what ran, so `tools` scope masks the other model-visible tool surface (the result content) instead of the arguments.
+- A browser half would consume the restore table to transparently un-mask assistant bubbles; the host-side restore surface (`/mask restore` + `RestoreStore.restore`) ships, and the browser slot is feature-flagged behind `maskClientEnabled` (default false) pending live slot-catalog verification.

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-08-27
+
+### Fixed
+
+- The bundle patch no longer inserts the storage stack (`@deepseek-ai/dsh-storage` / `dsh-storage-json` / `dsh-storage-domain`), which crashed `dsh web` with `duplicate loader entry id: storage` because `@deepseek-ai/dsh-web-app` already composes the same ids (issue #2). `storageDomain` is now an optional service: a profile that composes the storage stack provides it, while a bare profile without it degrades to a memory-only restore table with a one-time warning instead of hanging on `pending (waiting for service: storageDomain)`.
+
+## [0.2.0] - 2026-08-26
+
+### Added
+
+- **`tools` masking scope.** `scope` now accepts `'messages'` and/or `'tools'` (string or array, default `['messages']`). The `tools` surface masks tool-result text blocks on `tools/post-execute` before they are logged and fed back to the model. Tool-argument rewriting stays out of scope because the upstream `tools/pre-execute` `PreToolDecision` deliberately offers no input rewrite (logged/rendered arguments must match what ran).
+- **Detector Provider seam.** `Stripper`/`createStripper` accept an optional `detector: (text) => PIIEntity[]`; the built-in `regexDetect` remains the zero-dependency default, unchanged, so an external NER recognizer can plug in later without touching the masking pipeline.
+- **`maskClientEnabled` feature flag** (default `false`) for the future browser-half reveal bubble; the host restore surface (`/mask restore` + `RestoreStore.restore`) already backs it.
+
 ## [0.1.4] - 2026-08-23
 
 ### Changed

package/LICENSE

@@ -1,5 +1,3 @@
-Copyright 2026 PerryLink
-
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -34,9 +32,10 @@ Copyright 2026 PerryLink
       not limited to compiled object code, generated documentation,
       and conversions to other media types.
 
-      "Work" shall mean the work of authorship made available under
-      the License, as indicated by a copyright notice that is included in
-      or attached to the work (an example is provided in the Appendix below).
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
 
       "Derivative Works" shall mean any work, whether in Source or Object
       form, that is based on (or derived from) the Work and for which the
@@ -46,21 +45,23 @@ Copyright 2026 PerryLink
       separable from, or merely link (or bind by name) to the interfaces of,
       the Work and Derivative Works thereof.
 
-      "Contribution" shall mean, as submitted to the Licensor for inclusion
-      in the Work by the copyright owner or by an individual or Legal Entity
-      authorized to submit on behalf of the copyright owner. For the purposes
-      of this definition, "submitted" means any form of electronic, verbal,
-      or written communication sent to the Licensor or its representatives,
-      including but not limited to communication on electronic mailing lists,
-      source code control systems, and issue tracking systems that are managed
-      by, or on behalf of, the Licensor for the purpose of discussing and
-      improving the Work, but excluding communication that is conspicuously
-      marked or otherwise designated in writing by the copyright owner as
-      "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any Legal Entity on behalf of
-      whom a Contribution has been received by the Licensor and subsequently
-      incorporated within the Work.
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
 
    2. Grant of Copyright License. Subject to the terms and conditions of
       this License, each Contributor hereby grants to You a perpetual,
@@ -78,47 +79,53 @@ Copyright 2026 PerryLink
       by such Contributor that are necessarily infringed by their
       Contribution(s) alone or by combination of their Contribution(s)
       with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a cross-claim
-      or counterclaim in a lawsuit) alleging that the Work or a Contribution
-      incorporated within the Work constitutes direct or contributory patent
-      infringement, then any patent licenses granted to You under this License
-      for that Work shall terminate as of the date such litigation is filed.
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
 
    4. Redistribution. You may reproduce and distribute copies of the
       Work or Derivative Works thereof in any medium, with or without
       modifications, and in Source or Object form, provided that You
       meet the following conditions:
 
-      (a) You must give any other recipients of the Work or Derivative Works
-          a copy of this License; and
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
 
       (b) You must cause any modified files to carry prominent notices
           stating that You changed the files; and
 
       (c) You must retain, in the Source form of any Derivative Works
           that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work, excluding
-          those notices that do not pertain to any part of the Derivative
-          Works; and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
 
       (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, You must include a readable copy of the attribution
-          notices contained within such NOTICE file, in at least one of the
-          following places: within a NOTICE text file distributed as part of
-          the Derivative Works; within the Source form or documentation, if
-          provided along with the Derivative Works; or, within a display
-          generated by the Derivative Works, if and wherever such third-party
-          notices normally appear. The contents of the NOTICE file are for
-          informational purposes only and do not modify the License. You may
-          add Your own attribution notices within Derivative Works that You
-          distribute, alongside or as an addendum to the NOTICE text from the
-          Work, provided that such additional attribution notices cannot be
-          construed as modifying the License.
-
-      You may add Your own license statement for Your modifications and
-      may provide additional grant of rights to use, copy, modify, merge,
-      publish, distribute, sublicense, and/or sell copies of the Work under
-      terms of Your choice, or to simply not grant those additional rights.
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
 
    5. Submission of Contributions. Unless You explicitly state otherwise,
       any Contribution intentionally submitted for inclusion in the Work
@@ -138,9 +145,8 @@ Copyright 2026 PerryLink
       Contributor provides its Contributions) on an "AS IS" BASIS,
       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
       implied, including, without limitation, any warranties or conditions
-      of TITLE, MERCHANTABILITY, SATISFACTORY QUALITY, NON-INFRINGEMENT,
-      FITNESS FOR A PARTICULAR PURPOSE, or any other warranties or
-      conditions. You are solely responsible for determining the
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
       appropriateness of using or redistributing the Work and assume any
       risks associated with Your exercise of permissions under this License.
 
@@ -149,23 +155,23 @@ Copyright 2026 PerryLink
       unless required by applicable law (such as deliberate and grossly
       negligent acts) or agreed to in writing, shall any Contributor be
       liable to You for damages, including any direct, indirect, special,
-      incidental, or exemplary damages of any character arising as a result
-      of this License or out of the use or inability to use the Work
-      (including but not limited to damages for loss of goodwill, work
-      stoppage, computer failure or malfunction, or all other commercial
-      damages or losses), even if such Contributor has been advised of the
-      possibility of such damages.
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
 
    9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer, and
-      charge a fee for, acceptance of support, warranty, indemnity, or
-      other liability obligations and/or rights consistent with this License.
-      However, in accepting such obligations, You may offer such obligations
-      only on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify, defend,
-      and hold each Contributor harmless for any liability incurred by, or
-      claims asserted against, such Contributor by reason of your accepting
-      any such warranty or additional liability.
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
 
@@ -180,7 +186,7 @@ Copyright 2026 PerryLink
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2026 PerryLink
+   Copyright [yyyy] [name of copyright owner]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.es.md

@@ -74,6 +74,8 @@ dsh --profile web --dump-config | grep -A2 'id: mask'
 - **Canal tarball**: `pnpm pack` y luego `dsh plugin --profile web add ./dsh-mask-<version>.tgz`.
 - **Desinstalar**: `dsh plugin --profile web remove dsh-mask`.
 
+`dsh-mask` ya no incluye la pila de almacenamiento. Los perfiles que ya la componen (el perfil `web` lo hace, vía `@deepseek-ai/dsh-web-app`) aportan `storageDomain`, así que la persistencia funciona de inmediato. En un perfil bare sin almacenamiento el plugin se monta y enmascara igualmente, pero la tabla es solo en memoria (se pierde al reiniciar): compón la pila de almacenamiento en tu parche de perfil, o pon `persistRestoreTable: false`.
+
 ## Configuration
 
 Todas las opciones son campos Schemastery `Config` (modificables desde cordis.yml). `cordis.patch.yml` documenta cada clave.
@@ -83,7 +85,7 @@ Todas las opciones son campos Schemastery `Config` (modificables desde cordis.ym
 | `enabled` | `true` | Interruptor maestro |
 | `mode` | `regex` | Solo `regex` implementado (`regex+ner` reservado) |
 | `entities` | `[phone, email, id-card, bank-card, key]` | Tipos de PII a enmascarar; `ip` opt-in, `person`/`address` requieren NER |
-| `scope` | `messages` | Solo `messages` implementado |
+| `scope` | `[messages]` | Superficies: `messages` (mensajes agent/pre-step) y `tools` (texto de resultados de herramientas). Acepta una cadena o un array, p. ej. `[messages, tools]` |
 | `registerCommand` | `true` | Registra el comando `/mask` |
 | `registerTools` | `true` | Registra la herramienta `mask_test` |
 | `persistRestoreTable` | `true` | Persiste la tabla en el dominio `dsh_mask` |
@@ -134,6 +136,10 @@ pnpm pack
 
 Sin paso de build: ESM puro, `index.mjs` y `lib/` son los artefactos enviados.
 
+### Benchmark
+
+El benchmark de PII (P/R/F1 por tipo sobre 108 muestras sintéticas) está en [`benchmark/RESULTS.md`](benchmark/RESULTS.md); regenéralo con `node benchmark/run.mjs` (sin build, cero dependencias nuevas).
+
 ## Topics
 
 `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `pii`, `mask`, `privacy`, `anonymization`, `security`

package/README.hi.md

@@ -74,6 +74,8 @@ dsh --profile web --dump-config | grep -A2 'id: mask'
 - **tarball चैनल**: `pnpm pack` फिर `dsh plugin --profile web add ./dsh-mask-<version>.tgz`।
 - **अनइंस्टॉल**: `dsh plugin --profile web remove dsh-mask`।
 
+`dsh-mask` अब storage स्टैक बंडल नहीं करता। जो प्रोफ़ाइल इसे पहले से रचते हैं (`web` प्रोफ़ाइल `@deepseek-ai/dsh-web-app` के ज़रिए करती है) वे `storageDomain` देते हैं, इसलिए persistence तुरंत काम करता है। बिना storage वाले bare प्रोफ़ाइल में प्लगइन फिर भी माउंट होता है और मास्क करता है, पर restore तालिका केवल मेमोरी में रहती है (रीस्टार्ट पर खो जाती है): अपने प्रोफ़ाइल पैच में storage स्टैक रचें, या `persistRestoreTable: false` करें।
+
 ## Configuration
 
 सभी विकल्प Schemastery `Config` फ़ील्ड हैं (cordis.yml से बदले जा सकते हैं)। `cordis.patch.yml` हर कुंजी का दस्तावेज़ देता है।
@@ -83,7 +85,7 @@ dsh --profile web --dump-config | grep -A2 'id: mask'
 | `enabled` | `true` | मुख्य स्विच |
 | `mode` | `regex` | केवल `regex` लागू (`regex+ner` आरक्षित) |
 | `entities` | `[phone, email, id-card, bank-card, key]` | PII प्रकार; `ip` opt-in, `person`/`address` को NER चाहिए |
-| `scope` | `messages` | केवल `messages` लागू |
+| `scope` | `[messages]` | सतहें: `messages` (agent/pre-step संदेश) और `tools` (टूल परिणाम पाठ)। स्ट्रिंग या array स्वीकार करता है, जैसे `[messages, tools]` |
 | `registerCommand` | `true` | `/mask` कमांड पंजीकृत करें |
 | `registerTools` | `true` | `mask_test` टूल पंजीकृत करें |
 | `persistRestoreTable` | `true` | तालिका को `dsh_mask` डोमेन में सहेजें |
@@ -134,6 +136,10 @@ pnpm pack
 
 कोई build चरण नहीं: शुद्ध ESM, `index.mjs` और `lib/` ही भेजे गए आर्टिफ़ैक्ट हैं।
 
+### Benchmark
+
+PII बेंचमार्क (108 सिंथेटिक नमूनों पर प्रति-प्रकार P/R/F1) [`benchmark/RESULTS.md`](benchmark/RESULTS.md) में है; `node benchmark/run.mjs` से दोबारा बनाएँ (कोई build नहीं, कोई नई निर्भरता नहीं)।
+
 ## Topics
 
 `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `pii`, `mask`, `privacy`, `anonymization`, `security`

package/README.md

@@ -81,6 +81,8 @@ Then tailor the entity list in your profile patch:
 - **tarball channel**: `pnpm pack` in this repo, then `dsh plugin --profile web add ./dsh-mask-<version>.tgz`.
 - **uninstall**: `dsh plugin --profile web remove dsh-mask` (or remove the row from the profile patch).
 
+`dsh-mask` no longer bundles the storage stack. Profiles that already compose it (the `web` profile does, via `@deepseek-ai/dsh-web-app`) provide `storageDomain`, so persistence works out of the box. On a bare profile without storage the plugin still mounts and masks, but the restore table is memory-only (lost on restart) — compose the storage stack in your profile patch, or set `persistRestoreTable: false`.
+
 ## Configuration
 
 All tunables are Schemastery `Config` fields (changeable from cordis.yml). An id-targeted override replaces the whole row — restate every key you need. `cordis.patch.yml` documents each key inline.
@@ -90,12 +92,13 @@ All tunables are Schemastery `Config` fields (changeable from cordis.yml). An id
 | `enabled` | `true` | Master switch; `false` unregisters the listener, the `/mask` command, and the `mask_test` tool |
 | `mode` | `regex` | Detection mode; only `regex` is implemented (`regex+ner` for name/address recognition is reserved and fails loud) |
 | `entities` | `[phone, email, id-card, bank-card, key]` | Which PII types to mask; `ip` is also regex-capable (opt-in), `person`/`address` require NER |
-| `scope` | `messages` | Masking surface; only `messages` (agent messages) is implemented (`tools` argument masking is reserved) |
+| `scope` | `[messages]` | Masking surface(s); `messages` masks agent/pre-step messages, `tools` masks tool-result text on tools/post-execute. Accepts a string or an array, e.g. `[messages, tools]` |
 | `registerCommand` | `true` | Register the `/mask` command |
 | `registerTools` | `true` | Register the `mask_test` tool when the tools service is present |
 | `persistRestoreTable` | `true` | Persist the restore table to the controlled `dsh_mask` storage domain (`false` = memory only) |
 | `maxRestoreEntriesPerSession` | `500` | Per-session restore entry cap (oldest evicted first) |
 | `maxSessions` | `1000` | In-memory session cap (least-recently-used evicted, mapping reloaded on demand) |
+| `maskClientEnabled` | `false` | Feature flag for the browser half "reveal" bubble (defensive; off by default until the live slot catalog verifies the target slot) |
 
 Example override in your profile patch:
 
@@ -114,6 +117,7 @@ Example override in your profile patch:
 | Surface | Reveals plaintext | Notes |
 |---|---|---|
 | `agent/pre-step` masking | never | Rewrites messages to placeholders before they are logged or sent to the model |
+| `tools/post-execute` masking | never | Rewrites tool-result text blocks to placeholders before they are logged or fed back to the model (scope: `tools`) |
 | `/mask status` | never | Enabled state, total replaced, type distribution |
 | `/mask on` / `/mask off` | never | Runtime toggle (resets to `config.enabled` on restart) |
 | `/mask restore <text>` | yes (explicit) | Unmaps placeholders back to the values stored for this session |
@@ -130,7 +134,7 @@ Example override in your profile patch:
 - **Plaintext never enters the session log.** The masked (placeholder) form is what gets logged and sent to the model, so model-visible content is reconstructable from the log in placeholder form; the originals stay in the restore table.
 - **Sanitize before display/log.** `lib/sanitize.mjs` redacts PII, secrets, and URL credentials before any text reaches the model or the log; `mask_test` and `/mask status` never echo originals.
 - **Controlled restore.** `/mask restore` is the single explicit reveal surface, and it only reads the mapping for the active session.
-- **Fail closed.** Unimplemented `mode` (`regex+ner`), `scope` (`tools`), NER-only entities, and out-of-bounds numbers all fail loudly at load.
+- **Fail closed.** Unimplemented `mode` (`regex+ner`), unknown `scope` values, NER-only entities, and out-of-bounds numbers all fail loudly at load.
 - **Registrations are effects.** The listener, command, tool, and storage-domain close are all Cordis effects — stop/hot-reload removes them.
 
 ## Known limitations
@@ -153,6 +157,10 @@ pnpm pack                                          # the published tarball
 
 There is no build step: pure ESM, `index.mjs` and `lib/` are the shipped artifacts.
 
+### Benchmark
+
+The PII benchmark (per-type P/R/F1 over 108 synthetic samples) is published in [`benchmark/RESULTS.md`](benchmark/RESULTS.md); regenerate it with `node benchmark/run.mjs` (no build step, zero new dependencies).
+
 ## Topics
 
 `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `pii`, `mask`, `privacy`, `anonymization`, `security`

package/README.pt.md

@@ -74,6 +74,8 @@ dsh --profile web --dump-config | grep -A2 'id: mask'
 - **Canal tarball**: `pnpm pack` e depois `dsh plugin --profile web add ./dsh-mask-<version>.tgz`.
 - **Desinstalar**: `dsh plugin --profile web remove dsh-mask`.
 
+`dsh-mask` não inclui mais a pilha de armazenamento. Perfis que já a compõem (o perfil `web` o faz, via `@deepseek-ai/dsh-web-app`) fornecem `storageDomain`, então a persistência funciona imediatamente. Em um perfil bare sem armazenamento o plugin monta e mascara mesmo assim, mas a tabela é só em memória (perdida ao reiniciar): componha a pilha de armazenamento no seu patch de perfil, ou defina `persistRestoreTable: false`.
+
 ## Configuration
 
 Todas as opções são campos Schemastery `Config` (alteráveis via cordis.yml). O `cordis.patch.yml` documenta cada chave.
@@ -83,7 +85,7 @@ Todas as opções são campos Schemastery `Config` (alteráveis via cordis.yml).
 | `enabled` | `true` | Interruptor mestre |
 | `mode` | `regex` | Só `regex` implementado (`regex+ner` reservado) |
 | `entities` | `[phone, email, id-card, bank-card, key]` | Tipos de PII; `ip` opt-in, `person`/`address` exigem NER |
-| `scope` | `messages` | Só `messages` implementado |
+| `scope` | `[messages]` | Superfícies: `messages` (mensagens agent/pre-step) e `tools` (texto de resultados de ferramentas). Aceita string ou array, ex. `[messages, tools]` |
 | `registerCommand` | `true` | Registra o comando `/mask` |
 | `registerTools` | `true` | Registra a ferramenta `mask_test` |
 | `persistRestoreTable` | `true` | Persiste a tabela no domínio `dsh_mask` |
@@ -134,6 +136,10 @@ pnpm pack
 
 Sem etapa de build: ESM puro, `index.mjs` e `lib/` são os artefatos enviados.
 
+### Benchmark
+
+O benchmark de PII (P/R/F1 por tipo em 108 amostras sintéticas) está em [`benchmark/RESULTS.md`](benchmark/RESULTS.md); regenere-o com `node benchmark/run.mjs` (sem build, zero dependências novas).
+
 ## Topics
 
 `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `pii`, `mask`, `privacy`, `anonymization`, `security`

package/README.zh.md

@@ -80,6 +80,8 @@ dsh --profile web --dump-config | grep -A2 'id: mask'
 - **tarball 通道**：在本仓库 `pnpm pack`，再 `dsh plugin --profile web add ./dsh-mask-<version>.tgz`。
 - **卸载**：`dsh plugin --profile web remove dsh-mask`（或从 profile patch 删掉该行）。
 
+`dsh-mask` 不再自带 storage 栈。已组合该栈的 profile（`web` profile 通过 `@deepseek-ai/dsh-web-app` 提供）自带 `storageDomain`，持久化开箱即用。未组合 storage 的 bare profile 仍可正常挂载与遮罩，但恢复表仅存内存（重启丢失）——请在 profile patch 中组合 storage 栈，或将 `persistRestoreTable` 设为 `false`。
+
 ## Configuration
 
 所有可调项都是 Schemastery `Config` 字段（可从 cordis.yml 覆盖）。按 id 覆盖会替换整行——请重述所有需要的键。`cordis.patch.yml` 逐键内联注释。
@@ -89,7 +91,7 @@ dsh --profile web --dump-config | grep -A2 'id: mask'
 | `enabled` | `true` | 总开关；`false` 卸载监听器、`/mask` 命令与 `mask_test` 工具 |
 | `mode` | `regex` | 检测模式；只有 `regex` 实现（`regex+ner` 姓名/地址识别预留并响亮失败） |
 | `entities` | `[phone, email, id-card, bank-card, key]` | 要遮罩的 PII 类型；`ip` 也支持正则（可选），`person`/`address` 需要 NER |
-| `scope` | `messages` | 遮罩作用域；只有 `messages`（agent 消息）实现（`tools` 入参遮罩预留） |
+| `scope` | `[messages]` | 遮罩作用域；`messages` 遮罩 agent/pre-step 消息，`tools` 遮罩 tools/post-execute 工具结果。可为字符串或数组，如 `[messages, tools]` |
 | `registerCommand` | `true` | 注册 `/mask` 命令 |
 | `registerTools` | `true` | tools 服务存在时注册 `mask_test` 工具 |
 | `persistRestoreTable` | `true` | 把恢复表持久化到受控 `dsh_mask` 领域（`false` = 仅内存） |
@@ -152,6 +154,10 @@ pnpm pack                                          # 发布 tarball
 
 无构建步骤：纯 ESM，`index.mjs` 与 `lib/` 即发布产物。
 
+### Benchmark
+
+PII 基准（108 个合成样本的逐类 P/R/F1）见 [`benchmark/RESULTS.md`](benchmark/RESULTS.md)；用 `node benchmark/run.mjs` 复现（无需构建、零新依赖）。
+
 ## Topics
 
 `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `pii`, `mask`, `privacy`, `anonymization`, `security`

package/cordis.patch.yml

@@ -2,20 +2,16 @@
 #
 # Every key below is a Config field (Schemastery schema); invalid values fail
 # the profile load loudly. See README.md "Configuration" for the full table.
+#
+# This patch inserts only the `mask` row. It deliberately does NOT insert the
+# storage stack (`storage` / `storage-json` / `storage-domain`): a profile that
+# already composes it — the `web` profile does, via @deepseek-ai/dsh-web-app —
+# would collide on the duplicate loader entry id `storage` and refuse to boot
+# (issue #2). The plugin treats `storageDomain` as an optional service: when
+# the profile provides it, the restore table persists to the `dsh_mask` domain;
+# on a profile without storage, the restore table is memory-only and
+# `persistRestoreTable: true` is a no-op with a one-time warning.
 - insert:
-    - id: storage
-      name: '@deepseek-ai/dsh-storage'
-
-    - id: storage-json
-      name: '@deepseek-ai/dsh-storage-json'
-      config:
-        root: !!js dshHomePath('storages')
-
-    - id: storage-domain
-      name: '@deepseek-ai/dsh-storage-domain'
-      config:
-        backend: json
-
     - id: mask
       name: dsh-mask
       config:
@@ -36,15 +32,20 @@
           - id-card
           - bank-card
           - key
-        # Masking surface. Only 'messages' (mask agent/pre-step messages before
-        # they enter the model) is implemented; 'tools' (mask tool arguments) is
-        # reserved and fails loud at load.
-        scope: messages
+        # Masking surface(s). 'messages' masks agent/pre-step messages before
+        # they enter the model; 'tools' masks tool-result text on
+        # tools/post-execute before it is logged and fed back to the model
+        # (tool-argument rewriting is blocked upstream — see ARCHITECTURE.md).
+        # Accepts a single string or an array: [messages, tools].
+        scope:
+          - messages
         # Surface switches: register the /mask command and the mask_test tool.
         registerCommand: true
         registerTools: true
         # Persist the placeholder->original restore table to the controlled
-        # dsh_mask storage domain (false = memory only, lost on restart).
+        # dsh_mask storage domain (false = memory only, lost on restart). A
+        # no-op with a one-time warning when the profile composes no storage
+        # stack (storageDomain service absent).
         persistRestoreTable: true
         # Per-session cap on restore entries; the oldest placeholders are
         # evicted first (their responses can no longer be restored).
@@ -52,3 +53,8 @@
         # Cap on in-memory session strippers; least-recently-used sessions are
         # evicted (mapping reloads from the storage domain on demand).
         maxSessions: 1000
+        # Browser half "reveal" bubble (defensive, feature-flagged). The host
+        # restore surface (/mask restore + the in-memory/domain restore table)
+        # already backs it; the client slot ships separately and is off by
+        # default until the live slot catalog verifies the target slot.
+        maskClientEnabled: false

package/index.mjs

@@ -12,8 +12,9 @@
 // - 表面：/mask 命令（status|on|off|restore|help）与 mask_test 工具（试跑一段
 //   文本看替换效果，绝不回显原文）。
 //
-// 只消费公开服务：commands/storageDomain（inject 声明），tools 经 ctx.inject
-// 可选注册；lib/ 零 DSH 依赖，服务只在边界接线。
+// 只消费公开服务：commands（inject 声明）、storageDomain（ctx.get 可选，缺失时
+// 恢复表降级为纯内存并一次性告警），tools 经 ctx.inject 可选注册；lib/ 零 DSH
+// 依赖，服务只在边界接线。
 
 import { Context } from '@deepseek-ai/cordis'
 import Schema from '@deepseek-ai/schemastery'
@@ -34,15 +35,19 @@ import {
 } from './lib/constants.mjs'
 import { badConfig, messageOf, nerModeUnsupported, nerUnsupported, scopeUnsupported } from './lib/errors.mjs'
 import { createStripper } from './lib/strip.mjs'
-import { maskMessages } from './lib/mask.mjs'
+import { maskMessages, maskContentBlocks } from './lib/mask.mjs'
 import { makeEventGate, maybeAppendSessionEvent } from './lib/gate.mjs'
 import { RestoreStore } from './lib/store.mjs'
 import { dshMaskDomainSpec } from './lib/domain.mjs'
 
 export const name = PLUGIN_NAME
 
-/** 必需服务：缺失即加载失败（响亮）。 */
-export const inject = ['commands', 'storageDomain']
+/**
+ * 必需服务：缺失即加载失败（响亮）。storageDomain 是可选服务（apply 内
+ * ctx.get 读取，缺失时恢复表降级为纯内存），不再作为 inject 硬依赖——否则
+ * bare profile 会卡在 `pending (waiting for service: storageDomain)`。
+ */
+export const inject = ['commands']
 
 /**
  * 宿主 append 是否盖章 ignorable 信封（运行时能力探测）。
@@ -78,12 +83,16 @@ export const Config = Schema.object({
   enabled: Schema.boolean().default(DEFAULTS.ENABLED),
   mode: Schema.union([MODES.REGEX, MODES.REGEX_NER]).default(DEFAULTS.MODE),
   entities: Schema.array(Schema.string()).default(DEFAULTS.ENTITIES),
-  scope: Schema.union([SCOPES.MESSAGES, 'tools']).default(DEFAULTS.SCOPE),
+  scope: Schema.union([
+    Schema.array(Schema.union([SCOPES.MESSAGES, SCOPES.TOOLS])),
+    Schema.union([SCOPES.MESSAGES, SCOPES.TOOLS]),
+  ]).default(DEFAULTS.SCOPE),
   registerCommand: Schema.boolean().default(DEFAULTS.REGISTER_COMMAND),
   registerTools: Schema.boolean().default(DEFAULTS.REGISTER_TOOLS),
   persistRestoreTable: Schema.boolean().default(DEFAULTS.PERSIST_RESTORE_TABLE),
   maxRestoreEntriesPerSession: Schema.number().default(DEFAULTS.MAX_RESTORE_ENTRIES_PER_SESSION),
   maxSessions: Schema.number().default(DEFAULTS.MAX_SESSIONS),
+  maskClientEnabled: Schema.boolean().default(DEFAULTS.MASK_CLIENT_ENABLED),
 })
 
 /**
@@ -92,16 +101,18 @@ export const Config = Schema.object({
  * @returns {Required<Config> & {entities: string[]}} 校验后的配置。
  */
 export function resolveConfig(config = {}) {
+  const rawScope = config.scope ?? DEFAULTS.SCOPE
   const resolved = {
     enabled: config.enabled ?? DEFAULTS.ENABLED,
     mode: config.mode ?? DEFAULTS.MODE,
     entities: [...(config.entities ?? DEFAULTS.ENTITIES)],
-    scope: config.scope ?? DEFAULTS.SCOPE,
+    scope: typeof rawScope === 'string' ? [rawScope] : [...rawScope],
     registerCommand: config.registerCommand ?? DEFAULTS.REGISTER_COMMAND,
     registerTools: config.registerTools ?? DEFAULTS.REGISTER_TOOLS,
     persistRestoreTable: config.persistRestoreTable ?? DEFAULTS.PERSIST_RESTORE_TABLE,
     maxRestoreEntriesPerSession: config.maxRestoreEntriesPerSession ?? DEFAULTS.MAX_RESTORE_ENTRIES_PER_SESSION,
     maxSessions: config.maxSessions ?? DEFAULTS.MAX_SESSIONS,
+    maskClientEnabled: config.maskClientEnabled ?? DEFAULTS.MASK_CLIENT_ENABLED,
   }
   if (resolved.enabled === false) return resolved
 
@@ -111,8 +122,19 @@ export function resolveConfig(config = {}) {
   if (resolved.mode !== MODES.REGEX) {
     throw badConfig(`mode ${JSON.stringify(resolved.mode)} must be one of regex|regex+ner`)
   }
-  if (resolved.scope !== SCOPES.MESSAGES) {
-    throw scopeUnsupported(resolved.scope)
+  const scopeSeen = new Set()
+  resolved.scope = resolved.scope.filter((surface) => {
+    if (scopeSeen.has(surface)) return false
+    scopeSeen.add(surface)
+    return true
+  })
+  if (resolved.scope.length === 0) {
+    throw badConfig('scope must list at least one surface (messages and/or tools)')
+  }
+  for (const surface of resolved.scope) {
+    if (surface !== SCOPES.MESSAGES && surface !== SCOPES.TOOLS) {
+      throw scopeUnsupported(surface)
+    }
   }
   const seen = new Set()
   resolved.entities = resolved.entities.filter((entity) => {
@@ -256,13 +278,21 @@ export function apply(ctx, config = {}) {
   const warn = (message) => logger.warn(message)
   const eventGate = makeEventGate(KNOWN_SESSION_EVENT_TYPES, probeIgnorableAppend())
 
-  // --- 恢复表：ctx.storageDomain 领域 'dsh_mask'（异步打开，操作路径 await）。
-  /** @type {Promise<any>} 打开的领域（含 table/close），RestoreStore 按需消费。 */
-  const domainPromise = ctx.storageDomain.open(dshMaskDomainSpec).then((domain) => {
-    ctx.effect(() => () => { void domain.close() }, `${PLUGIN_NAME}.domain.close`)
-    return domain
-  })
-  domainPromise.catch(() => {}) // 消费方各自处理拒绝；此处仅避免未处理拒绝告警。
+  // --- 恢复表：可选 storageDomain 的 'dsh_mask' 领域（异步打开，操作路径 await）。
+  // storageDomain 缺失（bare profile 未组合存储栈）时降级为纯内存恢复表，
+  // persistRestoreTable 视为 no-op 并一次性告警（可选 seam 失败关闭，绝不卡 pending）。
+  const storageDomain = ctx.get('storageDomain')
+  /** @type {Promise<any>|null} 打开的领域（含 table/close），RestoreStore 按需消费。 */
+  let domainPromise = null
+  if (storageDomain !== undefined) {
+    domainPromise = storageDomain.open(dshMaskDomainSpec).then((domain) => {
+      ctx.effect(() => () => { void domain.close() }, `${PLUGIN_NAME}.domain.close`)
+      return domain
+    })
+    domainPromise.catch(() => {}) // 消费方各自处理拒绝；此处仅避免未处理拒绝告警。
+  } else if (resolved.persistRestoreTable) {
+    warn('storageDomain not composed: the restore table is memory-only (lost on restart). Compose the storage stack (storage / storage-json / storage-domain) in the profile, or set persistRestoreTable: false.')
+  }
 
   const store = new RestoreStore({
     entities: resolved.entities,
@@ -277,30 +307,62 @@ export function apply(ctx, config = {}) {
   let runtimeEnabled = true
 
   // --- agent/pre-step 遮罩（waterfall：先 next() 取下游决策，再遮罩其消息）。
-  ctx.on('agent/pre-step', async ({ agent, messages }, next) => {
-    if (!runtimeEnabled) return next()
-    const decision = await next()
-    if (decision.kind !== 'enter') return decision
-    const sessionId = agent?.session?.id
-    if (sessionId === undefined || sessionId === null || sessionId === '') return decision
-    const stripper = store.stripperFor(sessionId)
-    const before = stripper.stats()
-    const { messages: maskedMessages, replaced } = maskMessages(decision.messages, stripper)
-    if (replaced === 0) return decision
-    const after = stripper.stats()
-    const distribution = {}
-    for (const [label, count] of Object.entries(after.distribution)) {
-      const delta = count - (before.distribution[label] ?? 0)
-      if (delta > 0) distribution[label] = delta
-    }
-    void store.persist(sessionId)
-    maybeAppendSessionEvent(agent.session, SESSION_EVENTS.APPLIED, {
-      sessionId,
-      replaced,
-      distribution,
-    }, eventGate, warn)
-    return { kind: 'enter', messages: maskedMessages }
-  })
+  if (resolved.scope.includes(SCOPES.MESSAGES)) {
+    ctx.on('agent/pre-step', async ({ agent, messages }, next) => {
+      if (!runtimeEnabled) return next()
+      const decision = await next()
+      if (decision.kind !== 'enter') return decision
+      const sessionId = agent?.session?.id
+      if (sessionId === undefined || sessionId === null || sessionId === '') return decision
+      const stripper = store.stripperFor(sessionId)
+      const before = stripper.stats()
+      const { messages: maskedMessages, replaced } = maskMessages(decision.messages, stripper)
+      if (replaced === 0) return decision
+      const after = stripper.stats()
+      const distribution = {}
+      for (const [label, count] of Object.entries(after.distribution)) {
+        const delta = count - (before.distribution[label] ?? 0)
+        if (delta > 0) distribution[label] = delta
+      }
+      void store.persist(sessionId)
+      maybeAppendSessionEvent(agent.session, SESSION_EVENTS.APPLIED, {
+        sessionId,
+        replaced,
+        distribution,
+      }, eventGate, warn)
+      return { kind: 'enter', messages: maskedMessages }
+    })
+  }
+
+  // --- tools/post-execute 遮罩（scope: tools）：工具结果 text 块里的 PII 在回喂模型
+  // 与落盘前脱敏为占位符。工具入参本身无法在 pre-execute 改写（上游契约），故 tools
+  // 作用域落在结果这一可改写的模型可见面（见 ARCHITECTURE.md）。
+  if (resolved.scope.includes(SCOPES.TOOLS)) {
+    ctx.on('tools/post-execute', async (exec, result, next) => {
+      if (!runtimeEnabled) return next()
+      const decision = await next()
+      if (decision.kind !== 'accept') return decision
+      const sessionId = exec?.agent?.session?.id
+      if (sessionId === undefined || sessionId === null || sessionId === '') return decision
+      const stripper = store.stripperFor(sessionId)
+      const before = stripper.stats()
+      const { blocks: maskedBlocks, replaced } = maskContentBlocks(result.content, stripper)
+      if (replaced === 0) return decision
+      const after = stripper.stats()
+      const distribution = {}
+      for (const [label, count] of Object.entries(after.distribution)) {
+        const delta = count - (before.distribution[label] ?? 0)
+        if (delta > 0) distribution[label] = delta
+      }
+      void store.persist(sessionId)
+      maybeAppendSessionEvent(exec.agent?.session, SESSION_EVENTS.APPLIED, {
+        sessionId,
+        replaced,
+        distribution,
+      }, eventGate, warn)
+      return { kind: 'accept', content: maskedBlocks }
+    })
+  }
 
   // --- /mask 命令（Consumer）。
   if (resolved.registerCommand) {
@@ -373,6 +435,7 @@ export {
   RestoreStore,
   createStripper,
   maskMessages,
+  maskContentBlocks,
   makeEventGate,
   maybeAppendSessionEvent,
   dshMaskDomainSpec,

package/lib/constants.mjs

@@ -46,10 +46,12 @@ export const MODES = Object.freeze({
   REGEX_NER: 'regex+ner',
 })
 
-// 作用域词汇：messages 是唯一实现（agent/pre-step 消息遮罩）；
-// tools（工具入参遮罩）预留并响亮失败。
+// 作用域词汇：messages = agent/pre-step 入站消息遮罩；
+// tools = tools/post-execute 工具结果遮罩（工具入参改写被上游
+// tools/pre-execute 契约禁止，见 ARCHITECTURE.md）。
 export const SCOPES = Object.freeze({
   MESSAGES: 'messages',
+  TOOLS: 'tools',
 })
 
 // 会话事件类型（插件自有；运行时是否 append 取决于宿主是否收录该类型，
@@ -71,12 +73,13 @@ export const DEFAULTS = Object.freeze({
   ENABLED: true,
   MODE: MODES.REGEX,
   ENTITIES: ['phone', 'email', 'id-card', 'bank-card', 'key'],
-  SCOPE: SCOPES.MESSAGES,
+  SCOPE: [SCOPES.MESSAGES],
   REGISTER_COMMAND: true,
   REGISTER_TOOLS: true,
   PERSIST_RESTORE_TABLE: true,
   MAX_RESTORE_ENTRIES_PER_SESSION: 500,
   MAX_SESSIONS: 1000,
+  MASK_CLIENT_ENABLED: false,
 })
 
 // 配置字段合法性边界（加载期校验，越界响亮失败）。

package/lib/errors.mjs

@@ -55,14 +55,14 @@ export function nerModeUnsupported(mode) {
 }
 
 /**
- * 配置请求了未实现的作用域。
+ * 配置请求了未知作用域。
  * @param {unknown} scope - 配置值。
  * @returns {MaskError} code=SCOPE_UNSUPPORTED。
  */
 export function scopeUnsupported(scope) {
   return new MaskError(
     ERROR_CODES.SCOPE_UNSUPPORTED,
-    `scope ${JSON.stringify(scope)} is not implemented (only "messages" is; tool-argument masking is reserved)`,
+    `scope ${JSON.stringify(scope)} is not a valid surface; expected "messages" and/or "tools"`,
     { scope },
   )
 }

package/lib/mask.mjs

@@ -43,3 +43,28 @@ export function maskMessages(messages, stripper) {
   })
   return { messages: masked, replaced }
 }
+
+/**
+ * 遮罩任意内容块数组（工具结果的 text 块等），非文本块原样保留。
+ * @param {object[]} blocks - 内容块数组（含 {type:'text', text}）。
+ * @param {import('./strip.mjs').Stripper} stripper - 累计脱敏器。
+ * @returns {{blocks: object[], replaced: number}} 遮罩后数组与本次替换数。
+ */
+export function maskContentBlocks(blocks, stripper) {
+  if (!Array.isArray(blocks)) return { blocks, replaced: 0 }
+  let replaced = 0
+  let changed = false
+  const masked = blocks.map((block) => {
+    if (block === null || typeof block !== 'object' || block.type !== 'text' || typeof block.text !== 'string') {
+      return block
+    }
+    const result = stripper.stripInto(block.text)
+    if (result.replaced > 0) {
+      replaced += result.replaced
+      changed = true
+    }
+    return { ...block, text: result.text }
+  })
+  if (!changed) return { blocks, replaced: 0 }
+  return { blocks: masked, replaced }
+}

package/lib/strip.mjs

@@ -31,19 +31,47 @@ export const BUILTIN_PATTERNS = Object.freeze([
  * @typedef {{text: string, entity: string, label: string, start: number, end: number, score: number}} PIIEntity
  */
 
+/**
+ * 内置正则检测器（Provider 默认实现）：在文本上跑全部 pattern，返回实体列表。
+ * 纯函数、零依赖；作为可插拔 detector 的缺省，不改变既有检测语义。
+ * @param {string} text - 待检测文本。
+ * @param {Array<{entity: string, source: RegExp, score: number}>} patterns - 正则 pattern 列表。
+ * @returns {PIIEntity[]} 实体列表。
+ */
+export function regexDetect(text, patterns) {
+  /** @type {PIIEntity[]} */
+  const entities = []
+  for (const pattern of patterns) {
+    for (const match of text.matchAll(pattern.source)) {
+      entities.push({
+        text: match[0],
+        entity: pattern.entity,
+        label: ENTITY_LABELS[pattern.entity] ?? pattern.entity,
+        start: match.index,
+        end: match.index + match[0].length,
+        score: pattern.score,
+      })
+    }
+  }
+  return entities
+}
+
 /**
  * PII 脱敏器：把 PII 替换为 `<LABEL_N>` 占位符，并能按映射还原。
  *
+ * 检测器是可插拔 Provider：`detector` 为 `(text) => PIIEntity[]` 时用它（如
+ * 外部 NER 识别器），否则回退到内置正则 {@link regexDetect}（零依赖默认，行为不变）。
  * 同一会话内跨请求累计（stripInto 不重置），保证同一原文始终复用同一占位符，
  * 使模型在整段历史里看到的占位符语义一致；strip() 是单次模式（每次重置），
  * 供 mask_test 这类"试跑一段文本"的独立场景使用。
  */
 export class Stripper {
   /**
-   * @param {object} options - {patterns: Array<{entity: string, source: RegExp, score: number}>, maxEntries?: number}。
+   * @param {object} options - {patterns: Array<{entity: string, source: RegExp, score: number}>, detector?: (text: string) => PIIEntity[], maxEntries?: number}。
    */
   constructor(options) {
     this.patterns = options.patterns
+    this.detector = options.detector ?? null
     this.maxEntries = options.maxEntries ?? LIMITS.MAX_RESTORE_ENTRIES
     this.reset()
   }
@@ -151,26 +179,12 @@ export class Stripper {
   }
 
   /**
-   * 正则检测全部实体。
+   * 检测全部实体：优先走注入的 detector Provider，否则回退内置正则。
    * @param {string} text - 文本。
    * @returns {PIIEntity[]} 实体列表。
    */
   _detect(text) {
-    /** @type {PIIEntity[]} */
-    const entities = []
-    for (const pattern of this.patterns) {
-      for (const match of text.matchAll(pattern.source)) {
-        entities.push({
-          text: match[0],
-          entity: pattern.entity,
-          label: ENTITY_LABELS[pattern.entity] ?? pattern.entity,
-          start: match.index,
-          end: match.index + match[0].length,
-          score: pattern.score,
-        })
-      }
-    }
-    return entities
+    return this.detector !== null ? this.detector(text) : regexDetect(text, this.patterns)
   }
 
   /**
@@ -245,11 +259,12 @@ export class Stripper {
 
 /**
  * 按启用的实体集创建脱敏器。
- * @param {object} [options] - {entities?: string[], maxEntries?: number}。
+ * @param {object} [options] - {entities?: string[], maxEntries?: number, detector?: (text: string) => PIIEntity[]}。
+ *   detector 为可插拔检测器 Provider；缺省时使用内置正则（零依赖默认）。
  * @returns {Stripper} 配置好的脱敏器。
  */
 export function createStripper(options = {}) {
   const enabled = new Set(options.entities ?? Object.keys(ENTITY_LABELS))
   const patterns = BUILTIN_PATTERNS.filter(pattern => enabled.has(pattern.entity))
-  return new Stripper({ patterns, maxEntries: options.maxEntries })
+  return new Stripper({ patterns, maxEntries: options.maxEntries, detector: options.detector })
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-mask",
   "description": "PII masking middleware for DeepSeek Harness: anonymize names, phones, emails, ID cards, bank cards, keys, and addresses to placeholders before they reach the model, restore them at the display layer, keep the restore table only in memory and a controlled storage domain, never log plaintext, and expose /mask and the mask_test tool",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/PerryLink/dsh-mask.git"
@@ -88,6 +88,7 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-commands": "0.1.1-rc.2",
     "@deepseek-ai/dsh-session": ">=0.1.0-rc.8 <0.2.0",
     "@deepseek-ai/dsh-storage": ">=0.1.0-rc.8 <0.2.0",
     "@deepseek-ai/dsh-storage-domain": ">=0.1.0-rc.8 <0.2.0",
@@ -96,7 +97,6 @@
     "@deepseek-ai/schemastery": "^3.18.0"
   },
   "dependencies": {
-    "typescript": "^5.9.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
@@ -113,7 +113,8 @@
     "@deepseek-ai/dsh-tools": "0.1.1-rc.2",
     "@deepseek-ai/schemastery": "^3.18.0",
     "@types/node": "^22.19.0",
-    "oxlint": "0.18.1"
+    "oxlint": "0.18.1",
+    "typescript": "^5.9.0"
   },
   "scripts": {
     "typecheck": "tsc -p tsconfig.check.json",

package/types.d.ts

@@ -23,8 +23,11 @@ export interface Config {
   mode?: 'regex' | 'regex+ner'
   /** 启用的实体类型；regex 集为 phone/email/id-card/bank-card/key/ip，person/address 需 NER。 */
   entities?: string[]
-  /** 遮罩作用域；只有 'messages'（agent/pre-step 消息）实现，'tools' 预留并响亮失败。 */
-  scope?: 'messages' | 'tools'
+  /**
+   * 遮罩作用域；'messages' = agent/pre-step 入站消息，'tools' = tools/post-execute
+   * 工具结果。可传单个字符串或数组（如 `['messages', 'tools']`）。默认 `['messages']`。
+   */
+  scope?: 'messages' | 'tools' | Array<'messages' | 'tools'>
   /** 注册 /mask 命令（默认 true）。 */
   registerCommand?: boolean
   /** tools 服务存在时注册 mask_test 工具（默认 true）。 */
@@ -35,6 +38,8 @@ export interface Config {
   maxRestoreEntriesPerSession?: number
   /** 内存会话脱敏器上限（LRU 逐出，映射按需从领域回载）。 */
   maxSessions?: number
+  /** 浏览器半自动还原气泡开关（防御性 client slot；默认 false，未启用前对 UI 无副作用）。 */
+  maskClientEnabled?: boolean
 }
 
 /** mask_test 工具规范结果。 */