dsh-tool-folder 0.1.2 → 0.1.6

package/README.md

@@ -20,6 +20,18 @@ replaced object is authoritative (model-selection plugin does the same).
 Execution is NOT gated on the current turn's tools — folded tools still
 resolve through the full registry — so folding never removes capability.
 
+Feedback and the firewall bind to the *execution* events, not the prompt
+assembly:
+- `tools/pre-execute` — listener receives `(exec, next)`. Return
+  `{ kind: "deny", reason }` to refuse the call, or call `next()` to allow.
+  `exec = { callId, name, arguments, agent, signal }` (there is no `.deny()`
+  method on exec — the contract is the returned decision object).
+- `tools/post-execute` — listener receives `(exec, result, next)` and fires
+  once per executed tool; `exec.name` / `exec.arguments` feed heat counting,
+  exfil-chain detection, coverage recording and session persistence.
+  (`agent/pre-step` carries `{ messages, position, signal }` only — no
+  toolCalls — so it cannot drive feedback; verified against dsh-agent-loop.)
+
 ## Six layers — all implemented
 
 | Layer | Mechanism | Status |
@@ -35,12 +47,18 @@ resolve through the full registry — so folding never removes capability.
 | Segment | Content | Cost |
 |---|---|---|
 | core | per-agent core + heat-promoted tools, full schema | small, constant |
-| dyn | BM25 top-K for the current query + CN-alias server tools | small, per request |
+| dyn | BM25 top-K for the current query + CN-alias server top-K | small, per request |
 | folded | everything else — dropped from the schema | zero |
 
-Optionally (`catalogEnabled: true`) folded tools are listed as a one-line
-catalog section so the model still knows they exist and can call them by name
-(execution-side fallback still works).
+An alias hit no longer pulls the whole server in: the matched server's tools
+are ranked by BM25 (with the matched alias keywords bridged into the query to
+cross the CN/EN gap) and the top `min(3, serverSize)` are loaded. When the
+query yields no lexical signal at all, a stable name-order subset is loaded so
+the alias still helps.
+
+Optionally (`catalogEnabled: true`, default) folded tools are listed as a
+one-line catalog section so the model still knows they exist and can call them
+by name (execution-side fallback still works).
 
 ## Install
 
@@ -77,26 +95,144 @@ were never unregistered, so nothing else changes.
 | enabled | true | master switch |
 | perAgent | {} | `{agentId: {core: [...]}}` overrides |
 | core | [] | always-loaded tools (fallback for unknown agents) |
+| deny | [] | never inject + refuse execution: exact name, or `prefix*` matches a whole server. Deny wins over core, include and the catalog too. |
 | topK | 6 | BM25 dynamic segment size |
 | hotThreshold | 3 | folded tool called N times → auto-promote to core |
-| catalogEnabled | false | append one-line catalog section for folded tools |
+| catalogEnabled | true | append one-line catalog section for folded tools (fold safety net) |
+| schemaToolEnabled | true | register the `tools_schema` meta tool (full parameter schema of one tool by name) |
+| compressLevel | off | L1 compression tier: `off` \| `light` \| `standard` \| `aggressive`. `standard` trims descriptions to 200 chars + param descriptions to 120; `aggressive` additionally drops optional parameters (required ⊆ properties guaranteed constructively). Applies to dyn segment only — core/hot never trimmed. |
+| compressEnabled | false | deprecated compat: `compressLevel: off` + `compressEnabled: true` is treated as `standard` |
+| normalizeDescriptions | false | dyn-segment description hygiene: injection-marker removal + whitespace normalization + first-sentence keep + 300-char cap |
+| category | {} | intent routing `{ "记忆/回忆/remember": ["mcp__viking"], ... }`. Key words are `/`-separated (OR). Category wins over aliases; each matched server loads per-server top-3. |
+| include | [] | whitelist: exact name or `prefix*`. Non-empty → only matching tools are injected (meta tools exempt; deny still wins). Execution is NOT gated by include. |
+| toonifyResults | false | compact long JSON results after execution (drop empty fields + truncate strings; only when the text block is >2000 chars and parses as JSON) |
 | maxFoldMs | 50 | hard cap; beyond this keep the full list |
 | feedbackFile | '' | feedback JSON path (default `$DSH_HOME/logs/tool-folder/`) |
-| aliases | built-in | CN-intent keyword → server prefix table |
+| aliases | built-in | CN-intent keyword → server prefix table (per-server top-K) |
 
 ## Files
 
 - `lib/bm25.js` — zero-dep BM25 (k1=1.2, b=0.75; CN bigrams + EN tokens)
+- `lib/schema.js` — L1 tiered compression (`compressLevel`) + description normalization + lossless-JSON sanitizer
+- `lib/category.js` — P1-1 intent-category routing (pure function, unit-testable)
+- `lib/toonify.js` — P2-2 long JSON result compaction (pure function)
 - `lib/index.js` — assemble hook, three-segment fold, heat feedback, safety
 - `cordis.patch.yml` — bundle insert declaration
 - `test.js` — simulated-cordis harness: `node test.js`
 
 ## Known limits
 
-- BM25 cannot cross the CN-query / EN-description language gap; the alias
-  table covers common CN intents. A future query-rewrite leg (ARK LLM, proven
-  in the GPT Researcher smart retriever) removes this entirely.
-- `catalogEnabled` render behavior needs one runtime verification pass.
+- BM25 cannot cross the CN-query / EN-description language gap on its own; the
+  alias table covers common CN intents and now bridges its EN keywords into the
+  per-server BM25 scoring. A future query-rewrite leg (ARK LLM, proven in the
+  GPT Researcher smart retriever) removes this entirely.
+- Alias hits load the server's top-3 relevant tools, not the whole server. A
+  server whose most relevant tool ranks low on a bridged CN query may miss it —
+  the `tools_search` meta-tool and heat promotion are the recovery paths.
+- `catalogEnabled` render behavior needs one runtime verification pass
+  (section render is verified; the catalog text itself is standard).
+- `toonifyResults` mutation of the result object in the host's post-execute
+  waterfall is not yet proven end-to-end (the listener's return is a gate, not
+  the result body) — the pure function + unit tests are in; runtime propagation
+  needs one verification pass. Default off until then.
+- `aggressive` compression hides optional parameters from the model, so a
+  model that would have used them can't (execution still validates against the
+  registry's original schema — C6). `standard` is the safe default tier;
+  `aggressive` is opt-in.
+
+## Changelog
+
+### v0.1.6 — settings UI schema (2026-08-25)
+1. **`Config` schema exported (schemastery)**: every toggle now renders as a
+   native form in the DSH settings UI — no more hand-editing YAML. The schema
+   mirrors `DEFAULTS` one-to-one (18 fields: enabled / core / deny / topK /
+   hotThreshold / catalogEnabled / compressLevel / compressEnabled /
+   schemaToolEnabled / normalizeDescriptions / category / include /
+   toonifyResults / toolSearchEnabled / firewallEnabled / maxFoldMs /
+   feedbackFile / aliases), with per-field Chinese descriptions and range
+   constraints (topK 0-50, hotThreshold ≥1, maxFoldMs 0-1000). Invalid values
+   are rejected with precise messages ("expected off | light | standard |
+   aggressive but got X"). Same pattern as @deepseek-ai/dsh-tool-todo
+   (`z.object` + `.default()`, schemastery `~standard` bridge).
+2. **Dependencies**: `@deepseek-ai/schemastery` + `zod` (both `dependencies`,
+   matching the official plugin pattern — the zod adapter is required by the
+   `~standard` bridge).
+
+### v0.1.5 — tools_schema + tiered compression + intent routing (2026-08-25)
+1. **P0-1 `tools_schema` meta tool**: model-driven full-schema discovery for one
+   tool by name (complement to `tools_search`). Output is `{schema:{type:"json"}}`
+   (host contract C3 — a strict object schema would reject arbitrary tool
+   schemas with "is not a declared property"). Its return value is deep-washed
+   by `sanitizeLossless` (C4: `const:-0`/NaN can never leak). Meta tools are now
+   managed by a shared `META_TOOLS` block that keeps both `tools_search` and
+   `tools_schema` always visible.
+2. **P0-2 `compressLevel` tiers**: `light`/`standard`/`aggressive` replace the
+   single conservative trim. `aggressive` drops optional parameters and rebuilds
+   `properties` from `required`, so `required ⊆ properties` holds constructively
+   (C8). Required properties are never dropped; `$ref`/`oneOf`/`items` deep
+   structure is never touched; non object-root parameter schemas get
+   description-only trimming. `compressEnabled: true` remains as a deprecated
+   compat alias for `standard`.
+3. **P1-1 `category` intent routing**: `{ "记忆/回忆": ["mcp__viking"] }` routes a
+   query to explicit server prefixes (per-server top-3, BM25-bridged) and wins
+   over the alias table. Default `{}` = zero behavior change.
+4. **P1-2 `normalizeDescriptions`**: dyn-segment descriptions are sanitized
+   (prompt-injection markers removed), whitespace-collapsed, first-sentence
+   kept, and capped at 300 chars. Core/hot descriptions are never touched.
+5. **P2-1 `include` whitelist**: exact name or `prefix*`; non-empty → only
+   matching tools enter the injection pool. Meta tools are exempt (a whitelist
+   can never hide the discovery tools), deny still wins, and execution is never
+   gated by include (C5).
+6. **P2-2 `toonifyResults`** (default off): post-execute compaction of long JSON
+   text blocks (>2000 chars) — drop empty fields, truncate long strings. Any
+   parse/compact failure leaves the original result untouched. Pure function in
+   `lib/toonify.js`; host waterfall propagation still to be confirmed at runtime
+   (see Known limits).
+7. **Tests**: 33 → comprehensive suite (~50+ checks) covering every new feature
+   plus regression guards for the red lines ($ref untouched, core untouched,
+   required ⊆ properties, lossless JSON, deny-wins-over-include).
+
+### v0.1.4 — audit fixes (2026-08-25)
+1. **P0 firewall contract fixed** (`tools/pre-execute`): the listener now
+   returns `{ kind: "deny", reason }` to refuse (host contract verified:
+   `prepareExecution` reads `gate.kind` / `gate.reason`; `exec` has
+   `{ callId, name, arguments, agent, signal }` — the old `payload.deny()`
+   call and `toolName/argv` fields never existed, so high-risk blocks silently
+   never fired).
+2. **P0 feedback loop revived** (`tools/post-execute`): heat counting,
+   exfil-chain recording, coverage and session persistence moved off
+   `agent/pre-step` (whose payload has no toolCalls) onto `tools/post-execute`
+   (fires per executed tool with `exec.name`/`exec.arguments`). Feedback now
+   actually persists and heat-promotes across restarts.
+3. **P0 ESM crash removed**: `require("node:fs")` under `"type": "module"`
+   threw ReferenceError and silently killed all feedback persistence; replaced
+   with top-level `import fs` / `import path`. Also fixed a parameter-shadow
+   bug (`path` param hid the `node:path` module in `persistFeedback`).
+4. **P1 alias whole-server pull fixed**: alias hits now load a per-server
+   BM25 top-K (`min(3, serverSize)`) with alias keywords bridged into the
+   query, instead of dragging in every tool of a matched server.
+5. **P1 deny config added**: `deny: []` (exact name or `prefix*`) removes a
+   tool from the injected surface AND refuses its execution at
+   `tools/pre-execute`. Deny wins over core and the catalog.
+6. **P2 stopword over-removal fixed**: `list/get/set/make/use(ing)` removed
+   from the EN stopword set — they are tool-name/description high-frequency
+   terms (`list_sessions`, `get_config`) and were eroding retrieval signal.
+7. **P2 -0 defense**: metrics now normalize `-0` → `0` (DSH lossless JSON
+   rejects `-0`).
+8. **P2 default flip**: `catalogEnabled` defaults to `true` (fold safety net —
+   the model can see that hidden tools exist). `compressEnabled` stays off
+   (L1 not fully verified).
+9. **Tests**: suite extended 15 → 29 checks, covering the deny-return
+   contract, `tools/post-execute` receiving `exec.name`, deny config
+   (inject + execution), alias per-server top-K, no-`require` ESM hygiene, and
+   no-`-0` metric outputs.
+10. **NEW-1 (QA finding, LOW)**: three backslash-sensitive firewall regexes
+    (`HKLM\SAM`, `\system32\config`, `\Run`) silently never matched when argv
+    reached `verdict()` JSON-encoded (single backslash → `\\`). Changed `\\`
+    to `\\+` so both raw-string and JSON-encoded paths are blocked. Added 4
+    regression checks (suite now 33).
+
+### v0.1.3 — initial release (2026-08-24)
 
 ## Quality check (2026-08-24, real 45-tool set)
 
@@ -106,16 +242,15 @@ Full-pipeline test with the REAL tool list (converted to DSH public names
 | query | result | verdict |
 |---|---|---|
 | delegate a coding task to openhands | 7 openhands tools | ✅ |
-| 帮我记住这个事实 / 查记忆 记住 回忆 | all 15 viking tools (alias) | ✅ |
+| 帮我记住这个事实 / 查记忆 记住 回忆 | top-3 viking tools (alias, per-server top-K) | ✅ |
 | fetch library documentation | 2 context7 tools | ✅ |
-| start a learning session | all 13 deeptutor tools (alias) | ✅ |
+| start a learning session | top-3 deeptutor tools (alias, per-server top-K) | ✅ |
 | 复杂推理任务 深度思考 | deeptutor deep_* + reasonix + openhands | ✅ |
 | 搜索代码 semantic search | viking grep/glob + reasonix code | ✅ |
 
 - Fold ratio: 45 tools → 2-18 visible per query (avg ~8) ≈ **-82% schema tokens**
-- Known trade-off: an alias hit pulls the WHOLE server in. Fine while servers
-  stay ≤15 tools; a large server (e.g. GitHub MCP ~60) needs the v2 per-server
-  top-K refinement.
+- v0.1.4: alias hits are capped at the server's top-3 by relevance instead of
+  pulling the whole server in (the v2 per-server top-K refinement is now live).
 - BM25 shows minor lexical noise on some queries (e.g. `cancel_watch` on an
   openhands query) — the model filters this during synthesis.
 

package/cordis.patch.yml

@@ -36,6 +36,20 @@
         topK: 6
         # Folded tool called this many times auto-promotes into core.
         hotThreshold: 3
+        # v0.1.5 — meta tool: full parameter schema of one tool by name.
+        schemaToolEnabled: true
+        # L1 compression tier: off | light | standard | aggressive.
+        compressLevel: off
+        # Deprecated compat: compressLevel "off" + compressEnabled true → "standard".
+        compressEnabled: false
+        # Normalize dyn descriptions (injection sanitize + first sentence + 300 chars).
+        normalizeDescriptions: false
+        # Intent routing: { "记忆/回忆": ["mcp__viking"] } — category wins over aliases.
+        category: {}
+        # Whitelist: ["mcp__openhands*", "mcp__viking__remember"]; empty = all (minus deny).
+        include: []
+        # Compact long JSON tool results (drop empty fields + truncate long strings).
+        toonifyResults: false
         # One-line catalog section for folded tools (model knows they exist).
         # Off until section render behavior is verified at runtime.
         catalogEnabled: false

package/lib/bm25.js

@@ -22,7 +22,6 @@ const EN_STOP = new Set([
   "it", "this", "that", "these", "those", "i", "you", "he", "she", "we",
   "they", "do", "does", "did", "have", "has", "had", "not", "no", "yes",
   "will", "would", "can", "could", "should", "may", "might", "must",
-  "use", "used", "using", "get", "gets", "got", "set", "make", "list",
   "your", "my", "our", "their", "its", "all", "any", "some", "each",
 ]);
 

package/lib/category.js

@@ -0,0 +1,34 @@
+/**
+ * category.js — P1-1 intent-category routing for the dynamic tool segment.
+ *
+ * Operator-configurable `category` map: `{ "记忆/回忆/remember": ["mcp__viking"], ... }`
+ * The key is a `/`-separated list of intent words (OR semantics — any word
+ * contained in the query matches). The value is a list of server prefixes to
+ * load per-server top-K tools from.
+ *
+ * Pure function, zero dependencies, unit-testable without the plugin context.
+ */
+
+/**
+ * Match a lowercased query against the category map.
+ * @param {string} queryLower  pre-lowercased user query
+ * @param {object} category    `{ "word1/word2": ["serverPrefix", ...], ... }`
+ * @returns {{matched: boolean, matches: Array<{server: string, keywords: string[]}>}}
+ *   `matches` entries carry the server prefix and the hit keywords (used to
+ *   bridge CN intent words into the per-server BM25 scoring).
+ */
+export function matchCategory(queryLower, category) {
+  const matches = [];
+  for (const [key, servers] of Object.entries(category || {})) {
+    const keywords = String(key)
+      .split(/[/,，、]/)
+      .map((s) => s.trim().toLowerCase())
+      .filter(Boolean);
+    const hit = keywords.filter((k) => queryLower.includes(k));
+    if (hit.length === 0 || !Array.isArray(servers)) continue;
+    for (const server of servers) {
+      matches.push({ server: String(server), keywords: hit });
+    }
+  }
+  return { matched: matches.length > 0, matches };
+}

package/lib/chainguard.js

@@ -0,0 +1,93 @@
+// ChainGuard — session-level tool-call firewall (ported from xiaowan tool_firewall T3).
+//
+// Two layers:
+//  1. ChainGuard.check()  — high-risk command verdict (AEGIS-style hard block list).
+//  2. ChainGuard.record() — session window of tool calls; ChainGuard.checkChain()
+//     detects "sensitive read → external exfil" chains (Invariant-style: a single
+//     call is harmless, the SEQUENCE is the attack).
+//
+// Zero dependencies, pure regex + window buffer. Runs in the cordis plugin sandbox.
+
+const HIGH_RISK_PATTERNS = [
+  // destructive filesystem
+  [/rm\s+-rf\s+[\\/]?[A-Za-z]:[\\/]|rm\s+-rf\s+\/|rm\s+-rf\s+[*?]/i, "recursive root delete"],
+  [/format\s+[A-Za-z]:|format\s+\/q/i, "disk format"],
+  [/del\s+\/f\s+\/s\s+\/q/i, "force recursive delete"],
+  // download → execute chain
+  [/(wget|curl|powershell|pwsh).{0,80}(\||;|&&).{0,30}(sh|bash|powershell|pwsh|cmd|start)\b/i, "download-pipe-execute"],
+  [/invoke-expression|iex\s*\(|iwr\s+.*\|.*iex/i, "powershell download-exec"],
+  // credential / exfil
+  // NOTE: `\\+` (one-or-more literal backslashes) instead of `\\` — argv text
+  // reaches verdict() both as a raw string (single backslash) and as
+  // JSON.stringify(object) (backslash escaped to `\\`). A bare `\\` only
+  // matches the raw path, silently missing JSON-encoded calls (NEW-1).
+  [/(net\s+user|whoami\s+\/all|reg\s+query\s+HKLM\\+SAM)/i, "credential harvest"],
+  [/copy\s+.*\\+system32\\+config|type\s+.*\\+(ntuser\.dat|SAM|SYSTEM)/i, "system file exfil"],
+  // shadow / persistence
+  [/schtasks\s+\/create|reg\s+add\s+.*\\+run/i, "persistence install"],
+];
+
+// Tools that READ sensitive local state (file system, memory, secrets).
+const SENSITIVE_READ = new Set([
+  "read", "glob", "grep", "edit",
+  "mcp__viking__find", "mcp__viking__glob", "mcp__viking__read",
+  "ssh_download", "ssh_list", "job_output", "describe_image", "read_image",
+]);
+
+// Tools that SEND data to an external surface (network, memory writes, uploads).
+const EXTERNAL_SEND = new Set([
+  "mcp__viking__remember", "mcp__viking__add_resource", "mcp__viking__forget",
+  "ssh_upload", "send_message", "web_search",
+  "mcp__openhands__openhands_create_conversation",
+]);
+
+export function verdict(argvText) {
+  if (!argvText) return null;
+  for (const [re, label] of HIGH_RISK_PATTERNS) {
+    if (re.test(argvText)) {
+      return { blocked: true, label, pattern: String(re) };
+    }
+  }
+  return { blocked: false };
+}
+
+export class ChainGuard {
+  constructor({ window = 30 } = {}) {
+    this.window = window;
+    this.history = []; // [{tool, argv, ts}]
+  }
+
+  record(tool, argv = "") {
+    this.history.push({ tool, argv: String(argv || "").slice(0, 300), ts: Date.now() });
+    if (this.history.length > this.window) {
+      this.history.splice(0, this.history.length - this.window);
+    }
+  }
+
+  // Sensitive read followed within 3 steps by an external send → exfil chain.
+  checkChain() {
+    if (this.history.length < 2) return null;
+    for (let i = 0; i < this.history.length; i++) {
+      const h = this.history[i];
+      if (!SENSITIVE_READ.has(h.tool)) continue;
+      const lookahead = this.history.slice(i + 1, i + 4);
+      for (let j = 0; j < lookahead.length; j++) {
+        if (EXTERNAL_SEND.has(lookahead[j].tool)) {
+          return {
+            risk: "high",
+            label: "sensitive-read → external-send chain",
+            chain: [
+              `${h.tool}:${String(h.argv).slice(0, 60)}`,
+              ...lookahead.slice(0, j + 1).map((x) => `${x.tool}:${String(x.argv).slice(0, 60)}`),
+            ],
+          };
+        }
+      }
+    }
+    return null;
+  }
+
+  reset() {
+    this.history = [];
+  }
+}

package/lib/index.js

@@ -17,27 +17,79 @@
  *   buildRequest uses assembly.tools as the ONLY source of the API tools field.
  *   Execution is NOT gated on the current turn's tools, so folding never
  *   removes capability.
+ *   `tools/pre-execute`  — listener receives (exec, next); return
+ *     { kind: "deny", reason } to refuse, or call next() to allow.
+ *     exec = { callId, name, arguments, agent, signal } (no .deny() method).
+ *   `tools/post-execute` — listener receives (exec, result, next); fires once
+ *     per executed tool. exec.name/exec.arguments feed the L3/L4 feedback
+ *     loop. (`agent/pre-step` carries { messages, position, signal } only —
+ *     no toolCalls — so it is useless for feedback.)
  *
  * Safety: any error falls back to the untouched assembly. Performance: BM25
  * in-memory + sync; a maxFoldMs hard cap keeps the full list if we overrun.
  */
+import fs from "node:fs";
+import path from "node:path";
+import z from "@deepseek-ai/schemastery";
 import { buildIndex, search } from "./bm25.js";
-import { compressTool } from "./schema.js";
+import { compressTool, normalizeDescription, sanitizeLossless } from "./schema.js";
 import { selectionCoverage } from "./metrics.js";
+import { ChainGuard, verdict } from "./chainguard.js";
+import { matchCategory } from "./category.js";
+import { toonifyValue } from "./toonify.js";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 
 export const name = "tool-folder";
 export const inject = ["systemPrompt", "agents", "tools"];
 
+/**
+ * Schemastery configuration schema — renders the plugin's settings form in the
+ * DSH settings UI (per cordis `runtime.Config["~standard"]`). Mirrors DEFAULTS
+ * below; the UI exposes every toggle/knob this plugin has.
+ * Same pattern as @deepseek-ai/dsh-tool-todo (z.object + .default()).
+ */
+const COMPRESS_LEVELS = ["off", "light", "standard", "aggressive"];
+export const Config = z.object({
+  enabled: z.boolean().default(true).description("总开关：启用工具折叠"),
+  core: z.array(z.string()).default([]).description("每轮恒显示的工具（平台核心，永不折叠）"),
+  perAgent: z.dict(z.object({
+    core: z.array(z.string()).default([]).description("该 agent 的常驻工具覆盖（未列出 agent 回退到全局 core）"),
+  })).default({}).description("按 agent 覆盖常驻工具：{\"standard\": {\"core\": [...]}}"),
+  deny: z.array(z.string()).default([]).description("禁用工具：精确名或 prefix* 前缀，命中不注入+拒绝执行"),
+  topK: z.number().min(0).max(50).default(6).description("BM25 动态检索每轮最多注入的工具数"),
+  hotThreshold: z.number().min(1).default(3).description("被折叠工具调用几次后自动晋升为常驻"),
+  catalogEnabled: z.boolean().default(true).description("折叠安全网：把被藏工具列表写进提示词，模型知道它们存在"),
+  compressLevel: z.union(COMPRESS_LEVELS).default("off").description("L1 schema 压缩级别：off 不压缩 / light 裁描述 / standard 裁描述+参数说明 / aggressive 删可选参数"),
+  compressEnabled: z.boolean().default(false).description("兼容开关：compressLevel=off 且此开=true 时按 standard 处理"),
+  schemaToolEnabled: z.boolean().default(true).description("注册 tools_schema 元工具：按名称展开任意工具的完整参数 schema"),
+  normalizeDescriptions: z.boolean().default(false).description("描述标准化：注入消毒+首句提取+300 字符（只作用于动态段）"),
+  category: z.dict(z.array(z.string())).default({}).description("意图路由：{\"记忆/回忆\": [\"mcp__viking\"]}，优先级 category > aliases > BM25"),
+  include: z.array(z.string()).default([]).description("白名单：[\"mcp__openhands*\"]，空=全部（deny 仍优先，meta 工具豁免）"),
+  toonifyResults: z.boolean().default(false).description("长 JSON 结果紧凑化（删空字段/截长串，默认关）"),
+  toolSearchEnabled: z.boolean().default(true).description("注册 tools_search 元工具：检索被折叠的工具目录"),
+  firewallEnabled: z.boolean().default(true).description("ChainGuard 防火墙：高危命令硬拦截+外泄链检测"),
+  maxFoldMs: z.number().min(0).max(1000).default(50).description("折叠超时上限（ms），超时回退完整工具列表"),
+  feedbackFile: z.string().default("").description("反馈数据落盘路径（空=DSH_HOME/logs/tool-folder/）"),
+  aliases: z.dict(z.array(z.string())).default({}).description("中文意图→server 别名表"),
+});
+
 const DEFAULTS = {
   enabled: true,
   perAgent: {},
   core: [],
+  deny: [], // never inject + refuse execution (exact name or "prefix*")
   topK: 6,
   hotThreshold: 3,
-  catalogEnabled: false,
-  compressEnabled: false,
+  catalogEnabled: true, // safety net: folded tools stay discoverable by name
+  compressEnabled: false, // deprecated compat: compressLevel "off" + true → "standard"
+  compressLevel: "off", // "off" | "light" | "standard" | "aggressive"
+  schemaToolEnabled: true, // P0-1: register the tools_schema meta tool
+  normalizeDescriptions: false, // P1-2: sanitize+first-sentence+300 dyn descriptions
+  category: {}, // P1-1: { "记忆/回忆": ["mcp__viking"], ... } intent routing
+  include: [], // P2-1: whitelist ("prefix*" or exact name); empty = all (minus deny)
+  toonifyResults: false, // P2-2: compact long JSON results (default off)
   toolSearchEnabled: true,
+  firewallEnabled: true, // ChainGuard: high-risk hard block + exfil chain warn
   maxFoldMs: 50,
   feedbackFile: "",
   aliases: {
@@ -64,26 +116,35 @@ function feedbackPath(cfg) {
   }
 }
 
-function loadFeedback(path, log) {
+function loadFeedback(file, log) {
   try {
-    const fs = require("node:fs");
-    if (fs.existsSync(path)) return JSON.parse(fs.readFileSync(path, "utf8"));
+    if (fs.existsSync(file)) return JSON.parse(fs.readFileSync(file, "utf8"));
   } catch (e) {
     log?.warn?.("feedback load failed (%s) — starting empty", e?.message);
   }
   return { calls: {}, sessions: [] };
 }
 
-function persistFeedback(path, fb, log) {
+function persistFeedback(file, fb, log) {
   try {
-    const fs = require("node:fs");
-    require("node:fs").mkdirSync(require("node:path").dirname(path), { recursive: true });
-    fs.writeFileSync(path, JSON.stringify(fb, null, 2), "utf8");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(fb, null, 2), "utf8");
   } catch (e) {
     log?.warn?.("feedback persist failed (%s) — non-fatal", e?.message);
   }
 }
 
+/** Serialize an exec.arguments payload (object) into text for firewall verdicts. */
+function execArgumentsText(args) {
+  if (args == null) return "";
+  if (typeof args === "string") return args;
+  try {
+    return JSON.stringify(args);
+  } catch {
+    return String(args);
+  }
+}
+
 function extractQuery(context) {
   const signal = context && context.signal;
   if (!signal) return "";
@@ -116,6 +177,19 @@ function catalogText(tools) {
 
 export function apply(ctx, config) {
   const cfg = { ...DEFAULTS, ...(config || {}) };
+
+  // T01: normalize the v0.1.5 config surface right after the DEFAULTS merge.
+  //   - compressLevel accepts only the four valid tiers; anything else → "off".
+  //   - compressEnabled is the deprecated compat switch: "off" + true → "standard".
+  //   - include patterns are trimmed/non-empty; empty list = include-all.
+  //   - category must be a plain object; malformed values are ignored.
+  const VALID_LEVELS = ["off", "light", "standard", "aggressive"];
+  const compressLevel = VALID_LEVELS.includes(cfg.compressLevel) ? cfg.compressLevel : "off";
+  const effectiveLevel = compressLevel !== "off" ? compressLevel : (cfg.compressEnabled ? "standard" : "off");
+  const includePatterns = (cfg.include || []).map((n) => String(n).trim()).filter(Boolean);
+  const includeAll = includePatterns.length === 0;
+  const categoryCfg = (cfg.category && typeof cfg.category === "object") ? cfg.category : {};
+
   const logger = ctx.logger("tool-folder");
   if (!cfg.enabled) {
     logger.info("disabled by config");
@@ -129,21 +203,81 @@ export function apply(ctx, config) {
   let allTools = [];
   let lastVisible = { agentId: "", names: [], ts: 0 };
   const disposers = [];
+  const chain = new ChainGuard({ window: 30 }); // firewall: exfil-chain + high-risk
 
-  const serverOf = (name) => name.split("__")[0];
+  // "mcp__viking__remember" → "mcp__viking"; plain tools ("tool-bash") stay
+  // as themselves (single segment survives slice(0,2)).
+  const serverOf = (name) => String(name).split("__").slice(0, 2).join("__");
+
+  // Pattern matching shared by deny (P0) and include (P2-1): exact name or
+  // "prefix*" matches any tool starting with that prefix.
+  function matchesAnyPattern(name, patterns) {
+    if (!name || !patterns || patterns.length === 0) return false;
+    const n = String(name);
+    for (const p of patterns) {
+      if (p.endsWith("*")) {
+        if (n.startsWith(p.slice(0, -1))) return true;
+      } else if (n === p) {
+        return true;
+      }
+    }
+    return false;
+  }
+  // deny config: exact name, or "prefix*" matches any tool starting with it.
+  // Deny wins over core, include and the catalog (a denied tool is not listed).
+  const denyPatterns = (cfg.deny || []).map((n) => String(n).trim()).filter(Boolean);
+  const isDenied = (n) => matchesAnyPattern(n, denyPatterns);
+
+  // Per-server top-K: rank the matched server's tools by BM25 relevance with
+  // the matched intent keywords bridged into the query. When there is no
+  // lexical signal at all, fall back to a stable name-order subset so the
+  // intent route still helps. Used by both aliases and category routing.
+  function addPerServerTopK(dyn, tools, serverPrefix, bridgedQuery, maxK) {
+    const serverIndices = [];
+    for (let i = 0; i < tools.length; i++) {
+      if (tools[i].name.startsWith(serverPrefix)) serverIndices.push(i);
+    }
+    if (serverIndices.length === 0) return;
+    const k = Math.min(maxK, serverIndices.length);
+    let ranked = [];
+    if (index) {
+      ranked = search(index, bridgedQuery, serverIndices.length, {
+        filter: (i) => tools[i].name.startsWith(serverPrefix),
+      });
+    }
+    if (ranked.length === 0) {
+      // No lexical signal at all → stable name order so the route still helps.
+      serverIndices.sort((a, b) => (tools[a].name < tools[b].name ? -1 : 1));
+      for (const i of serverIndices.slice(0, k)) dyn.add(tools[i].name);
+    } else {
+      for (const i of ranked.slice(0, k)) dyn.add(tools[i].name);
+    }
+  }
 
   function buildDynamicSet(tools, query) {
     const dyn = new Set();
-    if (query && cfg.topK > 0 && index) {
-      for (const i of search(index, query, cfg.topK)) dyn.add(tools[i].name);
-    }
-    if (query) {
+    if (!query) return dyn;
+    const q = query.toLowerCase();
+    // P1-1: category wins over aliases. When a category key matches, only the
+    // category's servers are routed per-server top-K; the aliases branch is
+    // skipped. The generic BM25 leg is still merged as a union afterwards.
+    const cat = matchCategory(q, categoryCfg);
+    if (cat.matched) {
+      for (const m of cat.matches) {
+        addPerServerTopK(dyn, tools, m.server, `${query} ${m.keywords.join(" ")}`, 3);
+      }
+    } else {
+      // aliases fallback (existing behavior preserved verbatim)
       for (const [prefix, keywords] of Object.entries(cfg.aliases || {})) {
-        if (keywords.some((k) => query.toLowerCase().includes(k.toLowerCase()))) {
-          for (const t of tools) if (t.name.startsWith(prefix)) dyn.add(t.name);
-        }
+        const matched = keywords.filter((k) => q.includes(String(k).toLowerCase()));
+        if (matched.length === 0) continue;
+        addPerServerTopK(dyn, tools, prefix, `${query} ${matched.join(" ")}`, 3);
       }
     }
+    // Generic BM25 last as a union (result set unchanged vs. previous order).
+    if (cfg.topK > 0 && index) {
+      for (const i of search(index, query, cfg.topK)) dyn.add(tools[i].name);
+    }
     return dyn;
   }
 
@@ -212,13 +346,79 @@ export function apply(ctx, config) {
     }
   }
 
+  // L4: `tools_schema` — model-driven full-schema discovery for one tool.
+  // Complementary to tools_search: search narrows candidates, this returns the
+  // exact parameter schema + full description of one named tool.
+  // RED LINE (C3): output MUST be `{ schema: { type: "json" } }` — the return
+  // value is an arbitrary tool schema, and a strict object schema with
+  // additionalProperties:false would fail the host's "declared property"
+  // validation (ToolOutputError). The `type:"json"` annotation schema only
+  // checks lossless JSON (C4).
+  if (cfg.schemaToolEnabled) {
+    const schemaTool = defineTool({
+      name: "tools_schema",
+      description:
+        "Get the complete parameter schema of one tool by name. Use after " +
+        "tools_search narrows candidates, or before calling a tool whose exact " +
+        "arguments you need. Returns the full JSON schema of parameters plus the " +
+        "full description.",
+      parameters: {
+        name: {
+          type: "string",
+          required: true,
+          description: "Exact tool name, e.g. 'mcp__viking__remember'.",
+        },
+      },
+      output: {
+        schema: { type: "json" },
+        render: (_a, v) => [{ type: "text", text: JSON.stringify(v, null, 2) }],
+      },
+      isConcurrencySafe: () => true,
+      async execute(args) {
+        const name = String(args?.name || "");
+        const t = allTools.find((x) => x.name === name);
+        if (!t) return { name, found: false, reason: "unknown tool" }; // never throw
+        return {
+          name: t.name,
+          found: true,
+          server: serverOf(t.name),
+          description: t.description || "",
+          // C4 defense: even a schema containing `const: -0` must come back as
+          // lossless JSON.
+          parameters: sanitizeLossless(t.parameters ?? {}),
+          required: Array.isArray(t.parameters?.required) ? t.parameters.required : [],
+        };
+      },
+    });
+    try {
+      ctx.tools.register(schemaTool);
+      logger.info("tools_schema registered");
+    } catch (e) {
+      logger.warn("tools_schema register failed: %s", e?.message);
+    }
+  }
+
   disposers.push(
     ctx.on("system-prompt/assemble", async (assembly, context, next) => {
     const t0 = Date.now();
     try {
       const assembled = await next();
-      const tools = assembled.tools || [];
-      if (!Array.isArray(tools) || tools.length === 0) return assembled;
+      const assembledTools = assembled.tools || [];
+      if (!Array.isArray(assembledTools)) return assembled;
+      // P2-1 include whitelist + deny config remove tools from the injected
+      // surface BEFORE folding. Semantics: include non-empty → whitelist mode,
+      // only matching tools enter the pool (injection surface + catalog +
+      // tools_search/tools_schema search scope); execution is NOT gated here
+      // (C5 — pre-execute only checks deny + firewall). Deny still wins.
+      // Meta tools are exempt from include so a whitelist can never hide the
+      // discovery tools themselves (that would break the always-visible loop).
+      const isMetaTool = (n) => n === "tools_search" || n === "tools_schema";
+      const tools = assembledTools.filter(
+        (t) =>
+          !isDenied(t?.name) &&
+          (isMetaTool(t?.name) || includeAll || matchesAnyPattern(t?.name, includePatterns)),
+      );
+      if (tools.length === 0) return { ...assembled, tools };
 
       const agentId = context?.agent?.id || "default";
       const coreNames = new Set(cfg.perAgent?.[agentId]?.core || cfg.core || []);
@@ -244,19 +444,46 @@ export function apply(ctx, config) {
       // L5: stable ordering — core by config order, hot by name, dyn by name.
       // A deterministic byte order keeps the prompt prefix cacheable.
       const coreTools = tools.filter((t) => coreNames.has(t.name));
-      const hotTools = tools.filter((t) => !coreNames.has(t.name) && hotNames.has(t.name)).sort((a, b) => (a.name < b.name ? -1 : 1));
-      const dynTools = tools.filter((t) => !coreNames.has(t.name) && !hotNames.has(t.name) && dynNames.has(t.name)).sort((a, b) => (a.name < b.name ? -1 : 1));
+      const hotTools = tools
+        .filter((t) => !coreNames.has(t.name) && hotNames.has(t.name))
+        .sort((a, b) => (a.name < b.name ? -1 : 1));
+      const dynTools = tools
+        .filter(
+          (t) =>
+            !coreNames.has(t.name) &&
+            !hotNames.has(t.name) &&
+            dynNames.has(t.name),
+        )
+        .sort((a, b) => (a.name < b.name ? -1 : 1));
 
-      // L1: conservative schema trim on the dynamic segment only.
-      const trimmed = cfg.compressEnabled ? dynTools.map((t) => compressTool(t)) : dynTools;
+      // L1: schema compression + description normalization on the dynamic
+      // segment only. core/hot never pass through this pipe (P0 red line).
+      const trimmed =
+        effectiveLevel !== "off" || cfg.normalizeDescriptions
+          ? dynTools.map((t) => {
+              let out = t;
+              if (cfg.normalizeDescriptions && typeof t.description === "string") {
+                out = { ...out, description: normalizeDescription(t.description) };
+              }
+              return effectiveLevel !== "off"
+                ? compressTool(out, { level: effectiveLevel })
+                : out;
+            })
+          : dynTools;
 
       const visible = [...coreTools, ...hotTools, ...trimmed];
 
-      // The meta-tool must always stay visible or the model can never ask
-      // for folded tools (it would be hidden by its own fold).
-      if (cfg.toolSearchEnabled && !visible.some((t) => t.name === "tools_search")) {
-        const meta = tools.find((t) => t.name === "tools_search");
-        if (meta) visible.push(meta);
+      // The meta-tools must always stay visible or the model can never ask
+      // for folded tools (they would be hidden by their own fold).
+      const META_TOOLS = [
+        { name: "tools_search", enabled: cfg.toolSearchEnabled },
+        { name: "tools_schema", enabled: cfg.schemaToolEnabled },
+      ];
+      for (const m of META_TOOLS) {
+        if (m.enabled && !visible.some((t) => t.name === m.name)) {
+          const meta = tools.find((t) => t.name === m.name);
+          if (meta) visible.push(meta);
+        }
       }
 
       const visibleNames = visible.map((t) => t.name);
@@ -265,7 +492,11 @@ export function apply(ctx, config) {
       let sections = assembled.sections;
       if (cfg.catalogEnabled) {
         const folded = tools.filter(
-          (t) => !coreNames.has(t.name) && !hotNames.has(t.name) && !dynNames.has(t.name),
+          (t) =>
+            !isMetaTool(t.name) &&
+            !coreNames.has(t.name) &&
+            !hotNames.has(t.name) &&
+            !dynNames.has(t.name),
         );
         if (folded.length > 0) {
           sections = [...(assembled.sections || []), {
@@ -293,22 +524,65 @@ export function apply(ctx, config) {
   );
 
   // L3 + L4: heat feedback, coverage recording, and folded-call detection.
+  // Bound to `tools/post-execute` — payload = (exec, result), exec.name /
+  // exec.arguments are available. (`agent/pre-step` was the original hook but
+  // its payload is { messages, ...position, signal } — no toolCalls — so the
+  // feedback loop had no data. Verified against dsh-agent-loop preStep().)
+  // This listener is deliberately side-effect only: it always returns next()
+  // and never throws, so a feedback bug can never turn a tool result into
+  // an isError (postExecute wraps a throwing listener as failure).
   disposers.push(
-    ctx.on("agent/pre-step", (payload, next) => {
+    ctx.on("tools/post-execute", (exec, _result, next) => {
       try {
-        const calls = payload?.step?.toolCalls ?? payload?.toolCalls;
-        if (!Array.isArray(calls) || calls.length === 0) return next?.();
-        const names = calls.map((c) => (typeof c === "string" ? c : c?.name)).filter(Boolean);
+        const name = exec?.name;
+        if (!name) return next();
+
+        // P2-2 toonify (opt-in, default off): compact long JSON text blocks in
+        // the result (drop empty fields + truncate long strings). Only fires
+        // when the text block is >2000 chars AND parses as JSON; any failure
+        // leaves the original block untouched — a compaction bug can never
+        // corrupt a tool result.
+        if (cfg.toonifyResults && _result && Array.isArray(_result.content)) {
+          _result.content = _result.content.map((block) => {
+            if (
+              block?.type !== "text" ||
+              typeof block.text !== "string" ||
+              block.text.length <= 2000
+            ) {
+              return block;
+            }
+            try {
+              const v = JSON.parse(block.text);
+              const compact = JSON.stringify(toonifyValue(v), null, 2);
+              return compact.length < block.text.length ? { ...block, text: compact } : block;
+            } catch {
+              return block;
+            }
+          });
+        }
 
         // Heat counting (L4 feedback).
-        let changed = false;
-        for (const n of names) {
-          feedback.calls[n] = (feedback.calls[n] || 0) + 1;
-          changed = true;
+        feedback.calls[name] = (feedback.calls[name] || 0) + 1;
+
+        // Firewall: record the call sequence and flag exfil chains.
+        if (cfg.firewallEnabled !== false) {
+          chain.record(name, execArgumentsText(exec?.arguments));
+          const exfil = chain.checkChain();
+          if (exfil) {
+            logger.warn(
+              "[firewall] %s: %s",
+              exfil.label, exfil.chain.join(" → "),
+            );
+            feedback.firewall = feedback.firewall || [];
+            feedback.firewall.push({ ts: Date.now(), ...exfil });
+            if (feedback.firewall.length > 20) {
+              feedback.firewall.splice(0, feedback.firewall.length - 20);
+            }
+          }
         }
 
         // Folded-call detection: did the model call something we hid?
-        const cov = selectionCoverage(lastVisible.names, names);
+        const cov = selectionCoverage(lastVisible.names, [name]);
         if (cov.uncovered.length > 0) {
           logger.warn(
             "folded tools called (coverage=%.2f): %s — promoting via heat",
@@ -321,17 +595,47 @@ export function apply(ctx, config) {
           ts: Date.now(),
           agent: lastVisible.agentId,
           visible: lastVisible.names,
-          calls: names,
+          calls: [name],
           coverage: cov.coverage,
           uncovered: cov.uncovered,
         });
         if (feedback.sessions.length > 50) feedback.sessions.splice(0, feedback.sessions.length - 50);
 
-        if (changed) persistFeedback(fbPath, feedback, logger);
+        persistFeedback(fbPath, feedback, logger);
       } catch (e) {
-        logger.warn("pre-step hook error (%s) — best-effort", e?.message);
+        logger.warn("post-execute hook error (%s) — best-effort", e?.message);
       }
-      return next?.();
+      return next();
+    }),
+  );
+
+  // Firewall hard-block + deny config: refuse execution at tools/pre-execute.
+  // Host contract (dsh-tools prepareExecution): the waterfall's gate is the
+  // last value; return { kind: "deny", reason } to refuse, or next() to allow.
+  // exec carries { callId, name, arguments, agent, signal } — no .deny().
+  disposers.push(
+    ctx.on("tools/pre-execute", (exec, next) => {
+      try {
+        const name = exec?.name;
+
+        // deny config: refuse execution regardless of firewallEnabled.
+        if (isDenied(name)) {
+          logger.warn("[deny] tool disabled by config: %s", name);
+          return { kind: "deny", reason: `[tool-folder] 工具 ${name} 已被禁用（deny 配置）。` };
+        }
+
+        if (cfg.firewallEnabled !== false) {
+          const argvText = execArgumentsText(exec?.arguments);
+          const v = verdict(argvText);
+          if (v?.blocked) {
+            logger.warn("[firewall] BLOCKED %s: %s", name, v.label);
+            return { kind: "deny", reason: `[tool-folder firewall] 高危命令已拦截（${v.label}）。如需执行请人工确认。` };
+          }
+        }
+      } catch (e) {
+        logger.warn("pre-execute hook error (%s) — best-effort", e?.message);
+      }
+      return next();
     }),
   );
 

package/lib/metrics.js

@@ -16,6 +16,16 @@ function norm(s) {
   return String(s || "").toLowerCase().replace(/[?#].*$/, "");
 }
 
+/**
+ * Round to 3 decimals and normalize -0 to +0. DSH's lossless JSON validation
+ * rejects -0 (a value that survives JSON round-trips as "0" but fails a
+ * strict Object.is check), so every public metric must never emit -0.
+ */
+function round3(x) {
+  const r = Math.round(x * 1000) / 1000;
+  return r === 0 ? 0 : r;
+}
+
 export function retrievalMetrics(relevant, retrieved, k = null) {
   const top = k ? retrieved.slice(0, k) : retrieved;
   const rel = relevant.map(norm).filter(Boolean);
@@ -31,10 +41,10 @@ export function retrievalMetrics(relevant, retrieved, k = null) {
   const recall = tp / rel.length;
   const f1 = precision + recall > 0 ? (2 * precision * recall) / (precision + recall) : 0;
   return {
-    precision: Math.round(precision * 1000) / 1000,
-    recall: Math.round(recall * 1000) / 1000,
+    precision: round3(precision),
+    recall: round3(recall),
     hit: tp > 0,
-    f1: Math.round(f1 * 1000) / 1000,
+    f1: round3(f1),
     n: top.length,
   };
 }
@@ -45,7 +55,7 @@ export function selectionCoverage(visibleNames, calledNames) {
   if (calls.length === 0) return { coverage: 1, uncovered: [] };
   const uncovered = calls.filter((c) => !vis.has(c));
   return {
-    coverage: Math.round(((calls.length - uncovered.length) / calls.length) * 1000) / 1000,
+    coverage: round3((calls.length - uncovered.length) / calls.length),
     uncovered,
   };
 }

package/lib/schema.js

@@ -1,38 +1,129 @@
 /**
- * schema.js — L1 conservative schema compression.
+ * schema.js — L1 schema compression + description normalization.
  *
  * DO NOT deduplicate with JSON $ref: OpenAI/ARK function-calling providers do
  * not reliably resolve $ref in tool parameters, so a broken schema would
  * silently kill a tool. Instead we trim what is provably redundant:
- *   - tool description beyond `descLimit` chars
- *   - parameter description beyond `paramDescLimit` chars
- * Both limits are conservative (500/120) so the selection signal survives —
- * this is the TSCG "conservative tier" idea, not aggressive compression.
+ *   - tool description beyond the level's `descLimit`
+ *   - parameter description beyond the level's `paramDescLimit`
+ *   - `aggressive` additionally drops OPTIONAL parameters — properties are
+ *     rebuilt from the required list, so `required ⊆ properties` holds
+ *     constructively (host contract C8: providers reject a schema whose
+ *     required names are not all declared in properties).
  *
- * Applied ONLY to dynamically-loaded tools; core tools are operator-chosen
- * and left untouched. Off by default (`compressEnabled: false`).
+ * Compression applies ONLY to dynamically-loaded tools; core tools are
+ * operator-chosen and left untouched. Off by default (`compressLevel: "off"`).
+ *
+ * normalizeDescription() sanitizes injection markers, normalizes whitespace,
+ * keeps the first sentence, and truncates at 300 chars. It also applies only
+ * to the dynamic segment (core/hot descriptions are never rewritten).
  */
 
-export function compressTool(tool, opts = {}) {
-  const descLimit = opts.descLimit ?? 500;
-  const paramDescLimit = opts.paramDescLimit ?? 120;
+const LEVELS = {
+  light: { descLimit: 500, paramDescLimit: Infinity, dropOptional: false },
+  standard: { descLimit: 200, paramDescLimit: 120, dropOptional: false },
+  aggressive: { descLimit: 120, paramDescLimit: 60, dropOptional: true },
+};
+
+/**
+ * Compress one tool's schema at a given level.
+ * @param {object} tool  tool definition {name, description, parameters, ...}
+ * @param {{level?: "off"|"light"|"standard"|"aggressive"}} [opts]
+ * @returns {object} a shallow copy of the tool; the original is never mutated.
+ */
+export function compressTool(tool, { level = "off" } = {}) {
+  if (level === "off") return tool;
+  const t = LEVELS[level] ?? LEVELS.standard;
   const out = { ...tool };
 
-  if (typeof out.description === "string" && out.description.length > descLimit) {
-    out.description = out.description.slice(0, descLimit) + " …";
+  if (typeof out.description === "string" && out.description.length > t.descLimit) {
+    out.description = out.description.slice(0, t.descLimit) + " …";
   }
 
   const params = out.parameters;
-  if (params && typeof params === "object" && params.properties) {
-    const props = {};
-    for (const [key, raw] of Object.entries(params.properties)) {
-      const p = { ...raw };
-      if (typeof p.description === "string" && p.description.length > paramDescLimit) {
-        p.description = p.description.slice(0, paramDescLimit) + " …";
-      }
-      props[key] = p;
+  if (
+    !params ||
+    typeof params !== "object" ||
+    !params.properties ||
+    typeof params.properties !== "object"
+  ) {
+    // Non object-root (array-root / no properties): trim the description only.
+    return out;
+  }
+
+  const required = Array.isArray(params.required)
+    ? params.required.filter((n) => typeof n === "string")
+    : [];
+  // Constructive guarantee (C8): properties are rebuilt from the required list
+  // under `dropOptional`, so `required ⊆ properties` holds by construction.
+  // Required properties are NEVER dropped (missing required → ToolArgsError).
+  const keep = new Set(t.dropOptional ? required : Object.keys(params.properties));
+  const props = {};
+  for (const [key, raw] of Object.entries(params.properties)) {
+    if (!keep.has(key)) continue;
+    const p = { ...raw }; // never touch $ref/oneOf/items/properties deep structure
+    if (typeof p.description === "string" && p.description.length > t.paramDescLimit) {
+      p.description = p.description.slice(0, t.paramDescLimit) + " …";
     }
-    out.parameters = { ...params, properties: props };
+    props[key] = p;
+  }
+  out.parameters = { ...params, properties: props };
+  if (t.dropOptional) {
+    // C3d / C8: malformed inputs may list `required` names that name no
+    // property at all (JSON Schema allows it, e.g. required:["ghost"] with
+    // properties:{real:{...}}). After the aggressive rebuild those names are
+    // gone from properties, so an unfiltered required would violate
+    // `required ⊆ properties` and providers (ARK/OpenAI) could reject the
+    // tool. Filter the emitted required list down to the kept property names
+    // so the guarantee holds for ANY input, well-formed or not.
+    out.parameters.required = required.filter((n) => Object.hasOwn(props, n));
   }
   return out;
 }
+
+/** Injection / prompt-leak markers removed from tool descriptions. */
+const INJECTION_MARKERS = [
+  /\bignore\s+(all\s+)?(previous|prior|above)\b/i,
+  /\bsystem\s*:/,
+  /\[\s*\/?\s*system\s*\]/i,
+  /^\s*(你|you)\s*(现在|现在开始|are)\b/i,
+];
+
+/**
+ * Normalize a tool description: strip injection markers, collapse whitespace,
+ * keep the first sentence, truncate at 300 chars.
+ * @param {string} desc
+ * @param {{firstSentence?: boolean}} [opts]
+ * @returns {string}
+ */
+export function normalizeDescription(desc, { firstSentence = true } = {}) {
+  let s = String(desc || "");
+  for (const re of INJECTION_MARKERS) s = s.replace(re, " "); // injection sanitize
+  s = s.replace(/\s+/g, " ").replace(/[。．.!！]{2,}/g, "。").trim();
+  if (firstSentence) {
+    const m = s.match(/^.{1,120}?[。.!?；;]/);
+    if (m) s = m[0];
+  }
+  return s.length > 300 ? s.slice(0, 300) + " …" : s;
+}
+
+/**
+ * Deep-sanitize a value into lossless JSON (host contract C4: -0/NaN/Infinity
+ * are rejected by the host's lossless JSON validation). Numbers are mapped to
+ * a finite non-negative-zero value; plain objects/arrays are walked; strings,
+ * booleans, null pass through untouched.
+ * @param {unknown} v
+ * @returns {unknown} a plain JSON-safe projection
+ */
+export function sanitizeLossless(v) {
+  if (typeof v === "number") {
+    return Number.isFinite(v) && !Object.is(v, -0) ? v : 0;
+  }
+  if (Array.isArray(v)) return v.map(sanitizeLossless);
+  if (v && typeof v === "object" && Object.getPrototypeOf(v) === Object.prototype) {
+    const out = {};
+    for (const k of Object.keys(v)) out[k] = sanitizeLossless(v[k]);
+    return out;
+  }
+  return v; // string / boolean / null / undefined (undefined never enters a plain object walk)
+}

package/lib/toonify.js

@@ -0,0 +1,37 @@
+/**
+ * toonify.js — P2-2 long JSON result compaction (opt-in, default off).
+ *
+ * Recursively drops empty fields (null/undefined/""/[]/{}) and truncates
+ * strings longer than `maxStr`. Keys are NEVER shortened — renaming keys
+ * would break consumer semantics, so the default behavior only shrinks
+ * values. Output is built from plain literals, so it stays lossless JSON
+ * (no -0 / NaN / sparse arrays, host contract C4).
+ */
+
+/**
+ * Compact a JSON value: drop empty fields, truncate long strings.
+ * @param {unknown} value
+ * @param {{maxStr?: number}} [opts]
+ * @returns {unknown} `undefined` signals "drop this field"; otherwise a
+ *   lossless-JSON-safe projection.
+ */
+export function toonifyValue(value, { maxStr = 200 } = {}) {
+  if (value === null || value === undefined) return undefined; // drop empty
+  if (typeof value === "string") {
+    const s = value.trim();
+    return s.length === 0 ? undefined : s.length > maxStr ? s.slice(0, maxStr) + "…" : s;
+  }
+  if (Array.isArray(value)) {
+    const out = value.map((v) => toonifyValue(v, { maxStr })).filter((v) => v !== undefined);
+    return out.length === 0 ? undefined : out;
+  }
+  if (typeof value === "object") {
+    const out = {};
+    for (const k of Object.keys(value)) {
+      const v = toonifyValue(value[k], { maxStr });
+      if (v !== undefined) out[k] = v;
+    }
+    return Object.keys(out).length === 0 ? undefined : out;
+  }
+  return value; // number / boolean unchanged (no -0 arithmetic here)
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-tool-folder",
-  "version": "0.1.2",
-  "description": "Fold the DSH tool surface per request: per-agent core + BM25 dynamic loading + heat feedback. Shrinks schema tokens 80-90% while keeping selection accuracy.",
+  "version": "0.1.6",
+  "description": "Fold the DSH tool surface per request + ChainGuard firewall (high-risk block + exfil-chain detection). Shrinks schema tokens 80-90% while keeping selection accuracy. v0.1.6 adds a zod Config schema so every toggle renders in the DSH settings UI.",
   "keywords": [
     "dsh-plugin",
     "dsh",
@@ -27,6 +27,10 @@
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"