dsh-sandbox-param-normalizer 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rengy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# dsh-sandbox-param-normalizer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+按会话实时裁剪 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）沙箱提权参数的宿主插件：模型看不到当前会话里根本不可能生效的 `sandbox_permissions` / `justification`，仍然塞进来的无效提权参数也在执行前被清理掉。
+
+**支持的 dsh 版本**：`0.2.0-rc.2` 起的全部 `0.2.x`（含 `0.2.1-alpha.1`、`0.2.1-alpha.2`）。范围由 `engines.dsh` 与全部 `@deepseek-ai/dsh-*` 的 peer 依赖共同声明。
+
+## 它解决什么问题
+
+dsh 的 `bash`、`pwsh`、`write`、`edit` 在**注册期**静态声明 `sandbox_permissions` 与 `justification` 两个提权字段——只要挂载了 confining 后端，所有模型都能在 schema 里看到它们。但这两个字段能否生效，取决于**每个会话运行期的两个事实**：当前沙箱模式（`read-only` / `workspace-write` / `danger-full-access`）与审批策略（`never` / `ask`）。
+
+于是出现三类必然失败的调用，模型收到报错后换参数重试，又撞上同样的报错，陷入"验证失败 → 重试 → 再失败"的循环：
+
+```
+Error: invalid justification: expected a non-empty sentence
+Error: sandbox escalation to "danger-full-access" is not strictly wider than this call's current "danger-full-access" mode
+Error: sandbox escalation to "workspace-write" is not strictly wider than this call's current "danger-full-access" mode
+```
+
+All Access 会话（`danger-full-access` + `never`）是最典型的场景：当前模式已经最宽，不存在任何"更宽"的合法目标；审批又被禁用，任何提权请求都只会被拒。模型却仍然看得见字段。
+
+## 功能说明
+
+| 能力 | 说明 |
+| --- | --- |
+| 会话感知的 schema 投影 | 按每个 Agent 当前的沙箱模式与审批策略，实时裁剪模型可见的提权字段：整组隐藏，或把 `sandbox_permissions` 的 `enum` 收窄到真正可用的模式 |
+| 执行前参数归一化 | 对仍然抵达执行层的参数做最小处理：摘除同级/降级/畸形的提权字段、清理孤立 `justification`、为确实合法的提权补齐缺失理由 |
+| 按 Agent 隔离 | 同一进程内不同会话可以各自处于不同沙箱模式与审批策略，互不影响；投影在包装器读取 schema 时实时计算，用户中途切换权限立即生效 |
+| 不侵入宿主 | 只在各 Agent 自己的作用域层注册包装定义，不修改 dsh 安装目录、不改任何核心包、不就地改写全局工具定义 |
+| 协作式包装协议 | 通过 `Symbol.for('dsh.tool-wrapper.v1')` 识别同进程内已存在的包装器，优先贡献一层而不是重复包裹 |
+| 装配期契约校验 | 启动与重同步时校验目标工具的提权 schema 形状；契约漂移只记一条按 Agent + 工具去重的 `warn`，并让该工具保持原状——插件最差退化成"没装"，既不会在提示词装配路径上抛错，也不会阻断会话创建 |
+| 运行日志 | 启动一行 `info` 汇总；契约不符或重同步失败按 Agent + 工具去重后记 `warn` |
+
+### 权限真值表
+
+插件把 dsh 的两个运行期事实收敛成一份"可行提权目标"集合，schema 投影与参数归一化共用同一个答案：
+
+| 会话沙箱模式 | 审批策略 | 模型可见的提权目标 |
+| --- | --- | --- |
+| `read-only` | `ask` | `workspace-write`、`danger-full-access` |
+| `read-only` | `never` | 无（两个字段整组隐藏） |
+| `workspace-write` | `ask` | `danger-full-access` |
+| `workspace-write` | `never` | 无 |
+| `danger-full-access` | `ask` | 无（已是最宽，没有更宽目标） |
+| `danger-full-access` | `never` | 无 |
+
+### 参数归一化规则
+
+| 模型提交的提权参数 | 处理方式 |
+| --- | --- |
+| 目标不在可行集合内（同级、降级、非字符串） | 摘除两个提权字段，该次调用按会话标准模式执行 |
+| 只带了孤立的 `justification` | 只摘除 `justification`，其余参数原样保留 |
+| 目标可行，但理由缺失、空白或不是字符串 | 补一句如实说明"理由缺失"的兜底理由，仍走 dsh 原有审批流程 |
+| 目标可行且理由完整 | 原样通过，不做任何改写 |
+
+**不做什么**：不新增、不放大任何提权能力（第二层只会**摘除**或**补齐理由**，绝不把无效请求变成有效请求）；不绕过、不代替 dsh 的审批——合法的真正提权仍完整经过 dsh 的 `approveEscalation` 与用户审批；不处理 `read`、`grep` 等不含提权字段的工具；不覆盖 PTC 模式下的 `run_code`（该工具自带独立的提权参数与执行面，不在本插件的作用域内）；不提供客户端 UI。
+
+## 安装部署
+
+```sh
+# 从 npm 装进 web profile；声明了 dsh.bundle 的包会被自动登记进 dsh.profile.bundles
+dsh plugin --profile web add dsh-sandbox-param-normalizer
+
+# 或本地 tarball
+pnpm build && pnpm pack
+dsh plugin --profile web add ./dsh-sandbox-param-normalizer-0.1.0.tgz
+
+# 开发检出直接装目录
+dsh plugin --profile web add link:/path/to/dsh-sandbox-param-normalizer
+
+# 卸载
+dsh plugin --profile web remove dsh-sandbox-param-normalizer
+```
+
+包内 [`cordis.patch.yml`](./cordis.patch.yml) 是 `dsh.bundle.patch` 指向的补丁层，装配时自动应用，**无需手工编辑 profile 文件**。安装或卸载后需重启 dsh 使补丁层生效。
+
+### 配置项
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `logLevel` | `'silent' \| 'info'` | `'info'` | `silent` 关闭启动提示；契约失败与重同步失败的 `warn` 不受影响 |
+
+## 开发说明
+
+```sh
+pnpm install
+pnpm typecheck       # 类型检查（源码与测试）
+pnpm test            # 单元与集成测试
+pnpm test:coverage   # 覆盖率报告
+pnpm build           # 构建到 lib/（先 typecheck，再 tsdown）
+```
+
+真机验证脚本（真机验证一律在开发容器 `dsh-sandbox-param-normalizer` 中进行）：
+
+```sh
+# 宿主机编排：打包 → 建镜像 → 起容器 → 容器内驱动一轮 GPT 对话 → 判定 → 还原插件状态
+pnpm verify:host
+# 对照组：同上，但先把插件写进用户补丁层临时禁用，应当判定不通过
+pnpm verify:host:without-plugin
+```
+
+判据取自会话日志而非界面：`request/header.data.header.tools` 是**这一轮真正发给模型的工具清单**，其中 `bash` / `write` / `edit` 是否带提权字段就是插件的直接效果；工具结果里是否出现那三条原始报错则是"关插件会炸、开插件不炸"的直接证据。脚本用强制字面量的提示词让模型把注定失败的降级目标发出来，因此不依赖模型自觉。
+
+```
+src/
+  index.ts                插件入口：name / inject / Config / apply
+  policy.ts               由沙箱模式 + 审批策略推出"可行提权目标"集合
+  schema-projection.ts    第一层：按会话投影模型可见的工具参数 schema
+  argument-normalization.ts 第二层：执行前清理/补齐提权参数
+  escalation-fields.ts    提权字段名与参数 schema 的低层读取工具
+  compatibility.ts        目标工具集合与装配期契约校验
+  wrapper.ts              协作式工具包装绑定（schema 投影 + 执行链）
+  wrapper-protocol.ts     包装协议 v1（Symbol.for 全局键）
+  supervisor.ts           按 Agent 装配/重同步/卸载包装器
+scripts/
+  verify.mjs              真机验证：驱动容器内 GUI + 解析会话日志判定
+tests/
+  pure.spec.ts            真值表、投影、归一化、契约校验
+  regression.spec.ts      三条原始报错的回归：钉住上游报错原文，并验证归一化后能通过 dsh 的真实校验
+  wrapper.spec.ts         包装链顺序、委托替换、元数据转发、协议
+  integration.spec.ts     真实 cordis + ToolRuntime + 沙箱策略 + 审批服务的端到端验证
+```
+
+`regression.spec.ts` 直接调用 `@deepseek-ai/dsh-sandbox` 导出的 `validateEscalationArgs` 与 `approveEscalation`：既断言上游此刻仍会抛出那三条原文（同级那条已改为直接放行），也断言经插件归一化的参数能吃下真实校验。上游改措辞或改触发条件时，这里会先失败。
+
+集成测试用真实的 `ToolRuntime`、`SandboxPolicyService`、`ApprovalService`、`SessionStore` 与作用域系统，配合最简的工具替身，覆盖：All Access 会话字段整组隐藏、模式切换后 `enum` 收窄、合法提权原样通过、缺失理由补兜底、同级/孤立/降级参数被摘除、工具被替换或被作用域屏蔽后投影重算、契约漂移时只记 `warn` 且不波及其余工具。
+
+**版本与兼容范围**：版本号唯一来源是 `package.json` 的 `version`；宿主兼容范围由 `engines.dsh` 与全部 `@deepseek-ai/dsh-*` 的 `peerDependencies` 声明，两处必须同源。
+
+## 许可说明
+
+[MIT](./LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# 本插件的 bundle 补丁层。声明 dsh.bundle 后，安装命令会把本包写进
+# $DSH_HOME/profiles/<profile>/package.json 的 dsh.profile.bundles，本文件即作为
+# bundle 层自动应用，不需要再手工编辑 profile 的 cordis.patch.yml。
+#
+# 安装：dsh plugin --profile web add dsh-sandbox-param-normalizer
+# （开发检出装目录时换成 link:<本仓库绝对路径>）
+#
+# 行 id = 包名，重复 id 会被 Loader 静默丢弃，请勿在 preset 与 profile 两处同时挂载。
+- insert:
+    - id: dsh-sandbox-param-normalizer
+      name: dsh-sandbox-param-normalizer
+      config: {}

package/lib/index.d.ts

@@ -0,0 +1,29 @@
+import z from "@deepseek-ai/schemastery";
+import { Context } from "@deepseek-ai/cordis";
+
+//#region src/index.d.ts
+/** 插件配置。 */
+interface Config {
+  /** 启动日志级别；`silent` 关闭本插件的启动提示。 */
+  logLevel?: 'silent' | 'info';
+}
+/** 插件配置 schema（静态声明，供 DSH 配置目录与校验使用）。 */
+declare const Config: z<Config>;
+/** 插件名，也是包装协议里的所有者标识来源。 */
+declare const name = "sandbox-param-normalizer";
+/** 依赖的宿主能力：Agent 注册表、工具注册表、沙箱策略解析与审批策略读取。 */
+declare const inject: string[];
+/**
+ * 启动插件。
+ * @param ctx - 已注入全部依赖的插件上下文。
+ * @param config - 插件配置。
+ */
+declare function apply(ctx: Context, config?: Config): void;
+declare const _default: {
+  name: string;
+  inject: string[];
+  Config: z<Config>;
+  apply: typeof apply;
+};
+//#endregion
+export { Config, apply, _default as default, inject, name };

package/lib/index.js

@@ -0,0 +1,638 @@
+import z from "@deepseek-ai/schemastery";
+import { WIDER_MODES } from "@deepseek-ai/dsh-sandbox";
+
+//#region src/escalation-fields.ts
+/** DSH 提权请求的目标模式字段名。 */
+const SANDBOX_PERMISSIONS = "sandbox_permissions";
+/** DSH 提权请求的一句理由字段名，必须与 {@link SANDBOX_PERMISSIONS} 成对出现。 */
+const JUSTIFICATION = "justification";
+/** 两个提权字段的固定顺序，用于成对校验与整组摘除。 */
+const ESCALATION_FIELDS = [SANDBOX_PERMISSIONS, JUSTIFICATION];
+/**
+* 判断一个值是不是可枚举属性的普通对象记录（排除 `null` 与数组）。
+* @param value - 待判断的值。
+* @returns 是普通对象记录时为 `true`。
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* 读取工具参数 schema 的 `properties` 映射。
+* @param parameters - 工具参数 schema。
+* @returns `properties` 记录，形状不符时为 `undefined`。
+*/
+function parameterProperties(parameters) {
+	if (parameters.type !== "object" || !isRecord(parameters.properties)) return void 0;
+	return parameters.properties;
+}
+
+//#endregion
+//#region src/argument-normalization.ts
+/**
+* 模型提交了合法提权请求却漏写理由时补上的兜底句子。
+*
+* 这句会原样进入审批提示（`escalate sandbox to <mode>: <justification>`），
+* 因此必须如实说明"理由缺失"，不能伪造一个看起来像模型判断的理由。
+*/
+const FALLBACK_JUSTIFICATION = "The assistant requested a one-shot sandbox escalation without a reason; approve only if this single operation should run with wider access.";
+/**
+* 执行前的提权参数归一化——插件第二层，也是最小回退。
+*
+* 第一层投影只改变模型**看到**的 schema；DSH 的参数校验是开放根对象，
+* 模型仍可能（例如沿用上一轮的参数、或从旧的工具清单里抄）把提权字段塞进来，
+* 于是这些参数会穿过 schema 直接进入工具执行前的 `validateEscalationArgs` /
+* `approveEscalation`，触发三类必然失败的报错：
+* - `invalid justification: expected a non-empty sentence`
+* - `sandbox escalation to "<x>" is not strictly wider than this call's current "<y>" mode`
+* - `the user rejected escalating ...`（`never` 策略下审批必然被拒）
+*
+* 归一化只处理**注定失败**的请求，且只动提权字段本身，其余参数原样保留：
+* - 请求不是"当前模式下可行的严格更宽目标"（同级、降级、非字符串、审批被禁用）→ 整组摘除；
+* - 只带了孤立的 `justification` → 只摘除该字段；
+* - 请求确实合法但理由缺失或空白 → 补上 {@link FALLBACK_JUSTIFICATION}，
+*   让真正需要的提权仍走 DSH 原有审批流程，只是提示里如实标注理由缺失。
+*
+* 入参是注册表深冻结的调用参数，因此任何改动都返回新的浅拷贝对象；
+* 无需改动时原样返回入参本身，便于调用方与测试判定"未触碰"。
+* @param args - 模型提交的工具参数（任意形状）。
+* @param viableTargets - 该调用所属会话真正可行的提权目标集合。
+* @returns 归一化后的参数；无需改动时与入参同一引用。
+*/
+function normalizeEscalationArguments(args, viableTargets) {
+	if (!isRecord(args)) return args;
+	const hasPermissions = Object.hasOwn(args, SANDBOX_PERMISSIONS);
+	if (!hasPermissions && !Object.hasOwn(args, JUSTIFICATION)) return args;
+	const requested = args[SANDBOX_PERMISSIONS];
+	if (!(hasPermissions && typeof requested === "string" && viableTargets.includes(requested))) {
+		const normalized = { ...args };
+		if (!hasPermissions) delete normalized[JUSTIFICATION];
+		else {
+			delete normalized[SANDBOX_PERMISSIONS];
+			delete normalized[JUSTIFICATION];
+		}
+		return normalized;
+	}
+	const justification = args[JUSTIFICATION];
+	if (typeof justification === "string" && justification.trim().length > 0) return args;
+	return {
+		...args,
+		[JUSTIFICATION]: FALLBACK_JUSTIFICATION
+	};
+}
+
+//#endregion
+//#region src/compatibility.ts
+/**
+* 本插件投影与归一化的目标工具集合。
+*
+* 只有真正**声明了提权字段**的工具才需要处理：DSH 的 shell 家族（`bash` / `pwsh`）
+* 与文件家族（`write` / `edit`）在挂载了 confining 后端时都会声明
+* `sandbox_permissions` + `justification`。
+*/
+const TARGET_TOOL_NAMES = [
+	"bash",
+	"pwsh",
+	"write",
+	"edit"
+];
+/** PTC 模式的保留传输工具名；它带自己的提权参数，且禁止被任何插件遮蔽。 */
+const RESERVED_PTC_TOOL_NAME = "run_code";
+/**
+* 判断工具名是否在本插件的目标集合内。
+* @param name - 工具名。
+* @returns 是目标工具时为 `true`。
+*/
+function isTargetToolName(name$1) {
+	return TARGET_TOOL_NAMES.includes(name$1);
+}
+function incompatibility(message) {
+	return /* @__PURE__ */ new Error(`sandbox-param-normalizer: ${message}`);
+}
+function requireRecord(value, label) {
+	if (!isRecord(value)) throw incompatibility(`${label} must be an object`);
+	return value;
+}
+/**
+* 校验一个目标工具的运行时契约是否仍是本插件投影所假设的形状。
+*
+* 这一步在**装配期**执行（而不是模型消息装配期），把契约漂移转成一条可见的启动/重同步
+* 失败，避免投影函数在提示词装配路径上抛错。校验覆盖三类事实：
+* 1. 工具身份：目标集合内、且不是 PTC 保留名；
+* 2. 提权字段：两个字段要么都在、要么都不在；都在时 `sandbox_permissions` 必须是
+*    非空字符串枚举、`justification` 必须是字符串；
+* 3. `execute` 与 `output` 契约：包装后的定义要重新注册，必须能通过注册表校验。
+* @param definition - 目标工具当前的可见定义。
+* @throws 任一契约不满足时抛出带插件前缀的错误。
+*/
+function validateTargetTool(definition) {
+	const name$1 = definition.name;
+	if (name$1 === RESERVED_PTC_TOOL_NAME) throw incompatibility(`reserved tool "${RESERVED_PTC_TOOL_NAME}" cannot be wrapped`);
+	if (!isTargetToolName(name$1)) throw incompatibility(`unsupported target tool "${name$1}"`);
+	if (typeof definition.description !== "string" || typeof definition.execute !== "function") throw incompatibility(`tool "${name$1}" has an incompatible definition`);
+	const properties = parameterProperties(requireRecord(definition.parameters, `tool "${name$1}" parameters`));
+	if (properties === void 0) throw incompatibility(`tool "${name$1}" parameters must be an object schema with properties`);
+	const declared = ESCALATION_FIELDS.filter((field) => Object.hasOwn(properties, field));
+	if (declared.length === 1) throw incompatibility(`tool "${name$1}" must expose sandbox_permissions and justification together or omit both`);
+	if (declared.length === 2) validateEscalationSchema(name$1, properties);
+	const output = requireRecord(definition.output, `tool "${name$1}" output`);
+	if (typeof output.render !== "function" || !isRecord(output.schema)) throw incompatibility(`tool "${name$1}" output contract is incompatible`);
+}
+function validateEscalationSchema(name$1, properties) {
+	const permissions = requireRecord(properties[SANDBOX_PERMISSIONS], `tool "${name$1}" sandbox_permissions schema`);
+	const targets = permissions.enum;
+	if (permissions.type !== "string" || !Array.isArray(targets) || targets.length === 0 || !targets.every((target) => typeof target === "string")) throw incompatibility(`tool "${name$1}" sandbox_permissions must be a non-empty string enum`);
+	if (requireRecord(properties[JUSTIFICATION], `tool "${name$1}" justification schema`).type !== "string") throw incompatibility(`tool "${name$1}" justification must be a string`);
+}
+
+//#endregion
+//#region src/policy.ts
+/**
+* 计算当前模式下真正可行的提权目标集合。
+*
+* 两个约束必须同时满足，缺一即不可行：
+* 1. 目标模式必须**严格宽于**当前模式（DSH 执行期校验此点，同级或降级一律抛错）；
+* 2. 审批策略不能是 `never`（该策略下审批请求在服务内部直接判 `rejected`，没有渠道可走）。
+* @param effectiveMode - 会话当前生效的沙箱模式。
+* @param approvalPolicy - 会话当前生效的审批策略。
+* @returns 可行目标；不可行时为空数组。
+*/
+function viableEscalationTargets(effectiveMode, approvalPolicy) {
+	if (approvalPolicy === "never") return [];
+	return WIDER_MODES[effectiveMode] ?? [];
+}
+/**
+* 解析某个 Agent 所在会话的提权可行性视图。
+* @param ctx - 插件上下文，需已装配 `sandboxPolicy` 与 `approval`。
+* @param agent - 目标会话所属的 Agent。
+* @returns 该会话当前的沙箱模式、审批策略与可行提权目标。
+*/
+function escalationPolicyFor(ctx, agent) {
+	const effectiveMode = ctx.sandboxPolicy.resolve({ session: agent.session }).mode;
+	const approvalPolicy = ctx.approval.overrideOf(agent.session) ?? ctx.approval.config.policy ?? "ask";
+	return {
+		effectiveMode,
+		approvalPolicy,
+		viableTargets: viableEscalationTargets(effectiveMode, approvalPolicy)
+	};
+}
+
+//#endregion
+//#region src/schema-projection.ts
+/**
+* 按会话当前的可行提权目标，投影一份工具参数 schema 给模型看。
+*
+* 这是插件的第一层机制：DSH 的工具 schema 是注册期静态声明、跨会话共享的，而
+* "能提权到哪" 是会话运行期事实。投影在**模型消息装配期**按 Agent 生效，因此：
+* - 没有可行目标（`danger-full-access` 会话，或审批策略为 `never`）时整组摘除两个字段，
+*   模型从源头看不到提权入口，不会再发起必然失败的调用；
+* - 有可行目标时把 `sandbox_permissions` 的 `enum` 收窄到真正可用的模式，
+*   避免模型选到同级或降级目标后触发 DSH 的严格变宽校验错误。
+*
+* 本函数是**全函数**：形状不像 DSH 工具 schema 时原样返回，绝不在模型装配期抛错
+* （形状问题由装配期的 {@link validateTargetTool} 提前拦截）。
+* @param parameters - 目标工具当前的参数 schema。
+* @param viableTargets - 该会话真正可行的提权目标集合。
+* @returns 投影后的参数 schema；无可投影内容时原样返回入参。
+*/
+function projectEscalationParameters(parameters, viableTargets) {
+	const properties = parameterProperties(parameters);
+	if (properties === void 0) return parameters;
+	const hasPermissions = Object.hasOwn(properties, SANDBOX_PERMISSIONS);
+	const hasJustification = Object.hasOwn(properties, JUSTIFICATION);
+	if (!hasPermissions && !hasJustification) return parameters;
+	if (!hasPermissions || !hasJustification) return parameters;
+	const projected = structuredClone(parameters);
+	const projectedProperties = parameterProperties(projected);
+	/* v8 ignore next -- projected is a clone of a parameters value whose properties were readable above. */
+	if (projectedProperties === void 0) return parameters;
+	if (viableTargets.length === 0) {
+		delete projectedProperties[SANDBOX_PERMISSIONS];
+		delete projectedProperties[JUSTIFICATION];
+		stripRequired(projected);
+		return projected;
+	}
+	const permissions = projectedProperties[SANDBOX_PERMISSIONS];
+	if (!isRecord(permissions)) return parameters;
+	permissions.enum = [...viableTargets];
+	return projected;
+}
+/** 把提权字段从 `required` 中摘掉；摘空后连同 `required` 一起删除。 */
+function stripRequired(parameters) {
+	const required = parameters.required;
+	if (!Array.isArray(required)) return;
+	const kept = required.filter((value) => value !== SANDBOX_PERMISSIONS && value !== JUSTIFICATION);
+	if (kept.length === 0) delete parameters.required;
+	else parameters.required = kept;
+}
+
+//#endregion
+//#region src/wrapper-protocol.ts
+/**
+* 协作式工具包装协议的注册键。
+*
+* 用 `Symbol.for` 而不是模块私有 `Symbol`：同一进程内可能加载同一插件的多个副本，
+* 协议必须靠全局键互相识别，否则会出现"包装器套包装器"的重复投影与重复归一化。
+*/
+const TOOL_WRAPPER_PROTOCOL = Symbol.for("dsh.tool-wrapper.v1");
+/**
+* 读取一个工具定义上的包装协议。
+* @param definition - 待检查的工具定义。
+* @returns 协议对象；未携带时为 `undefined`。
+* @throws 协议存在但形状非法时抛错，避免静默退化成重复包装。
+*/
+function protocolOf(definition) {
+	const protocol = definition[TOOL_WRAPPER_PROTOCOL];
+	if (protocol === void 0) return void 0;
+	if (protocol.version !== 1 || typeof protocol.owner !== "string" || typeof protocol.name !== "string" || typeof protocol.contribute !== "function") throw new Error(`sandbox-param-normalizer: tool "${definition.name}" exposes an invalid wrapper protocol`);
+	return protocol;
+}
+
+//#endregion
+//#region src/wrapper.ts
+/** 本插件在包装协议里的所有者标识，也是 `WrapperLayer.owner`。 */
+const PLUGIN_OWNER = "dsh-sandbox-param-normalizer";
+/**
+* 需要从当前委托原样转发给注册表的可选**数据**成员。
+*
+* DSH 的 `ToolDefinition` 除 schema 与 `execute` 外，还带执行/展示元数据。包装器必须把
+* 它们一并转发，否则包装后的工具会丢失超时保护与延迟加载声明。数据成员用取值器实时读取
+* 当前委托，因此替换委托后新声明或变更的元数据都能生效。
+*/
+const FORWARDED_DATA_MEMBERS = ["deferLoading", "timeoutMs"];
+/**
+* 需要转发给注册表的可选**方法**成员。
+*
+* 无条件定义为转发函数：调用时取当前委托的同名方法（绑定委托自身为接收者），
+* 当前委托未声明该成员时返回 `undefined`。这与"未声明"在 DSH 注册表侧的语义一致——
+* 并发分类只认精确的 `true`，展示与内容收尾回调返回 `undefined` 即保持原行为。
+*/
+const FORWARDED_METHOD_MEMBERS = [
+	"isConcurrencySafe",
+	"presentCall",
+	"presentResult",
+	"projectContent",
+	"finalizeContent"
+];
+function sortedLayers(layers) {
+	return [...layers.values()].sort((left, right) => left.priority - right.priority || left.owner.localeCompare(right.owner));
+}
+/**
+* 建立一个工具包装绑定。
+*
+* 包装器只替换 `description` / `parameters` / `execute` 三处语义，其余成员一律转发
+* 给当前委托，因此它对 DSH 而言仍是一个完全正常的工具定义——模型可见 schema 由层链
+* 实时投影，执行时参数由层链依次归一化后交给真实工具。
+* @param initialDelegate - 首次包装的真实工具定义。
+* @param ownLayer - 本绑定自带的层。
+* @returns 可注册、可增量贡献层、可切换委托的绑定。
+*/
+function createWrapperBinding(initialDelegate, ownLayer$1) {
+	let currentDelegate = initialDelegate;
+	const layers = new Map([[ownLayer$1.owner, ownLayer$1]]);
+	const context = { toolName: initialDelegate.name };
+	const delegate = () => currentDelegate;
+	const projectParameters = () => sortedLayers(layers).reduce((value, layer) => layer.projectParameters?.(value, context) ?? value, delegate().parameters);
+	const execute = (args, exec) => {
+		const target = delegate();
+		const active = sortedLayers(layers).filter((layer) => layer.execute !== void 0);
+		const dispatch = (index, current) => {
+			const layer = active[index];
+			if (layer === void 0) return Reflect.apply(target.execute, target, [current, exec]);
+			let called = false;
+			return layer.execute(current, exec, (nextArgs) => {
+				if (called) throw new Error(`${PLUGIN_OWNER}: wrapper "${layer.owner}" called next() more than once for tool "${context.toolName}"`);
+				called = true;
+				return dispatch(index + 1, nextArgs);
+			});
+		};
+		return dispatch(0, args);
+	};
+	const protocol = {
+		version: 1,
+		owner: PLUGIN_OWNER,
+		name: initialDelegate.name,
+		contribute(layer) {
+			if (layers.has(layer.owner)) throw new Error(`${PLUGIN_OWNER}: wrapper owner "${layer.owner}" is already registered for "${initialDelegate.name}"`);
+			layers.set(layer.owner, layer);
+			let active = true;
+			return () => {
+				if (!active) return;
+				active = false;
+				layers.delete(layer.owner);
+			};
+		}
+	};
+	const definition = {};
+	Object.defineProperties(definition, {
+		name: {
+			value: initialDelegate.name,
+			enumerable: true
+		},
+		description: {
+			enumerable: true,
+			get: () => delegate().description
+		},
+		parameters: {
+			enumerable: true,
+			get: projectParameters
+		},
+		output: {
+			enumerable: true,
+			get: () => delegate().output
+		},
+		execute: {
+			value: execute,
+			enumerable: true
+		}
+	});
+	Object.defineProperty(definition, TOOL_WRAPPER_PROTOCOL, { value: protocol });
+	for (const member of FORWARDED_DATA_MEMBERS) Object.defineProperty(definition, member, {
+		enumerable: true,
+		configurable: true,
+		get: () => propertyOf(delegate(), member)
+	});
+	for (const member of FORWARDED_METHOD_MEMBERS) Object.defineProperty(definition, member, {
+		enumerable: true,
+		configurable: true,
+		value: (...args) => {
+			const owner = delegate();
+			const current = propertyOf(owner, member);
+			return typeof current === "function" ? Reflect.apply(current, owner, args) : void 0;
+		}
+	});
+	return {
+		definition,
+		updateDelegate(next) {
+			if (next.name !== initialDelegate.name) throw new Error(`${PLUGIN_OWNER}: delegate name changed from "${initialDelegate.name}" to "${next.name}"`);
+			currentDelegate = next;
+		},
+		contribute(layer) {
+			return protocol.contribute(layer);
+		},
+		releaseOwnLayer() {
+			layers.delete(ownLayer$1.owner);
+		}
+	};
+}
+function propertyOf(definition, member) {
+	return definition[member];
+}
+
+//#endregion
+//#region src/supervisor.ts
+/** 本插件自带层的优先级（数值小者先执行）。 */
+const OWN_LAYER_PRIORITY = 100;
+function describeError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* 本插件自带的投影层：模型消息装配期收窄 schema，工具派发期归一化参数。
+*
+* `execute` 用**本次调用**的 Agent 解析策略（复合工具可能代别的 Agent 派发），
+* 投影则固定用被包装的那个 Agent——因为作用域注册本身就绑定了它。
+*/
+function ownLayer(ctx, agent) {
+	return {
+		owner: PLUGIN_OWNER,
+		priority: OWN_LAYER_PRIORITY,
+		projectParameters(value) {
+			return projectEscalationParameters(value, escalationPolicyFor(ctx, agent).viableTargets);
+		},
+		execute(args, exec, next) {
+			const { viableTargets } = escalationPolicyFor(ctx, exec.agent ?? agent);
+			return next(normalizeEscalationArguments(args, viableTargets));
+		}
+	};
+}
+/**
+* 按 Agent 调度工具包装：为每个存活的会话维护它自己的目标工具投影视图。
+*
+* DSH 的工具定义是**注册期静态、跨会话共享**的（模型可见 schema 通过 `ctx.tools.schemas(scope)`
+* 按作用域解析），而提权可行性是**每会话事实**。因此插件不能就地改全局定义，只能在
+* 各 Agent 自己的作用域层里注册一份包装定义去遮蔽继承来的原定义。
+*
+* 生命周期与 DSH 的真实时序对齐：Agent 创建时装配，Agent 销毁时撤下；preset 在创建后
+* 才注册工具、或工具集合在运行期变化（`tools/change`）时重新对账。
+*/
+var Supervisor = class {
+	states = /* @__PURE__ */ new Map();
+	/** 重入计数：非 0 时表示正在对账，期间到达的 `tools/change` 合并成一次补偿对账。 */
+	reconciling = 0;
+	/** 本插件自身注册/注销引发的 `tools/change` 配额，避免自触发无限对账。 */
+	expectedToolChanges = 0;
+	reconcilePending = false;
+	/**
+	* @param ctx - 已装配 `agents` / `tools` / `sandboxPolicy` / `approval` 的插件上下文。
+	*/
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	/**
+	* 订阅生命周期事件并对账当前已有的全部 Agent。
+	* @returns 供 `ctx.effect` 使用的清理函数。
+	*/
+	start() {
+		const stopCreated = this.ctx.on("agent/created", ({ agent }) => {
+			this.install(agent);
+		});
+		const stopDisposed = this.ctx.on("agent/disposed", ({ agent }) => {
+			try {
+				this.remove(agent);
+			} catch (error) {
+				this.warn(agent, `cleanup failed: ${describeError(error)}`);
+			}
+		});
+		const stopPreset = this.ctx.on("agent-preset/selected", (sessionId) => {
+			const agent = this.ctx.agents.get(sessionId);
+			if (agent !== void 0) this.reconcileAgent(agent);
+		});
+		const stopTools = this.ctx.on("tools/change", () => {
+			if (this.expectedToolChanges > 0) {
+				this.expectedToolChanges -= 1;
+				return;
+			}
+			if (this.reconciling > 0) {
+				this.reconcilePending = true;
+				return;
+			}
+			this.reconcileAll();
+		});
+		for (const agent of this.ctx.agents.list()) this.install(agent);
+		return () => {
+			stopTools();
+			stopPreset();
+			stopDisposed();
+			stopCreated();
+			const states = [...this.states.values()];
+			this.states.clear();
+			for (const state of states) try {
+				this.coordinate(() => this.disposeState(state));
+			} catch (error) {
+				this.warn(state.agent, `cleanup failed: ${describeError(error)}`);
+			}
+			return Promise.resolve();
+		};
+	}
+	install(agent) {
+		if (this.states.has(agent)) return;
+		const state = {
+			agent,
+			targets: new Map(TARGET_TOOL_NAMES.map((name$1) => [name$1, {
+				name: name$1,
+				attachment: { kind: "dormant" }
+			}]))
+		};
+		this.states.set(agent, state);
+		this.coordinate(() => this.reconcileState(state));
+	}
+	remove(agent) {
+		const state = this.states.get(agent);
+		if (state === void 0) return;
+		this.states.delete(agent);
+		this.coordinate(() => this.disposeState(state));
+	}
+	reconcileAgent(agent) {
+		if (this.reconciling > 0) return;
+		const state = this.states.get(agent);
+		if (state === void 0) return;
+		this.coordinate(() => this.reconcileState(state));
+	}
+	reconcileAll() {
+		if (this.reconciling > 0) return;
+		this.coordinate(() => {
+			for (const state of this.states.values()) this.reconcileState(state);
+		});
+	}
+	/** 逐个目标工具对账；失败按 Agent + 工具去重上报，不影响其余工具。 */
+	reconcileState(state) {
+		for (const target of state.targets.values()) try {
+			this.reconcileTarget(state.agent, target);
+		} catch (error) {
+			this.reportFailure(state.agent, target, error);
+		}
+	}
+	/**
+	* 对齐一个目标工具：先撤下上次的挂载，再按**当前可见的**定义重新挂载。
+	*
+	* 关键在于先撤后读：本插件的包装定义注册在同一作用域层里，`ctx.tools.get(name, agent)`
+	* 会优先返回它。撤下之后读到的才是继承来的真实定义。
+	*/
+	reconcileTarget(agent, target) {
+		this.detachTarget(target);
+		const delegate = this.ctx.tools.get(target.name, agent);
+		if (delegate === void 0) {
+			delete target.lastReportedError;
+			return;
+		}
+		try {
+			validateTargetTool(delegate);
+			const protocol = protocolOf(delegate);
+			if (protocol !== void 0) target.attachment = {
+				kind: "cooperative",
+				release: protocol.contribute(ownLayer(this.ctx, agent))
+			};
+			else {
+				const binding = target.binding ?? createWrapperBinding(delegate, ownLayer(this.ctx, agent));
+				if (target.binding === void 0) target.binding = binding;
+				else binding.updateDelegate(delegate);
+				const registrationCtx = agent.ctx.extend({ fiber: this.ctx.fiber });
+				target.attachment = {
+					kind: "owned",
+					unregister: this.mutateTools(() => registrationCtx.tools.register(binding.definition))
+				};
+			}
+			delete target.lastReportedError;
+		} catch (error) {
+			target.attachment = {
+				kind: "incompatible",
+				reason: describeError(error)
+			};
+			throw error;
+		}
+	}
+	detachTarget(target) {
+		const attachment = target.attachment;
+		if (attachment.kind === "dormant") return;
+		if (attachment.kind === "incompatible") {
+			target.attachment = { kind: "dormant" };
+			return;
+		}
+		if (attachment.kind === "owned") this.mutateTools(attachment.unregister);
+		else attachment.release();
+		target.attachment = { kind: "dormant" };
+	}
+	disposeState(state) {
+		const errors = [];
+		for (const target of [...state.targets.values()].reverse()) try {
+			this.detachTarget(target);
+		} catch (error) {
+			errors.push(error);
+		}
+		if (errors.length > 0) throw new AggregateError(errors, `agent "${state.agent.id}" cleanup failed`);
+	}
+	reportFailure(agent, target, error) {
+		const message = describeError(error);
+		if (target.lastReportedError === message) return;
+		target.lastReportedError = message;
+		this.warn(agent, `tool "${target.name}" dynamic reconciliation failed: ${message}`);
+	}
+	warn(agent, message) {
+		this.ctx.logger.warn(`sandbox-param-normalizer: agent "${agent.id}" ${message}`);
+	}
+	/** 执行一段会触发 `tools/change` 的对账动作，并合并期间挂起的补偿对账。 */
+	coordinate(action) {
+		this.reconciling += 1;
+		try {
+			action();
+		} finally {
+			this.reconciling -= 1;
+			if (this.reconciling === 0 && this.reconcilePending) {
+				this.reconcilePending = false;
+				this.reconcileAll();
+			}
+		}
+	}
+	/** 标记紧随其后的 `tools/change` 是本插件自己造成的，消费掉这一配额。 */
+	mutateTools(action) {
+		this.expectedToolChanges += 1;
+		const expected = this.expectedToolChanges;
+		try {
+			return action();
+		} finally {
+			if (this.expectedToolChanges === expected) this.expectedToolChanges -= 1;
+		}
+	}
+};
+
+//#endregion
+//#region src/index.ts
+/** 插件配置 schema（静态声明，供 DSH 配置目录与校验使用）。 */
+const Config = z.object({ logLevel: z.union(["silent", "info"]).default("info") });
+/** 插件名，也是包装协议里的所有者标识来源。 */
+const name = "sandbox-param-normalizer";
+/** 依赖的宿主能力：Agent 注册表、工具注册表、沙箱策略解析与审批策略读取。 */
+const inject = [
+	"agents",
+	"tools",
+	"sandboxPolicy",
+	"approval"
+];
+/**
+* 启动插件。
+* @param ctx - 已注入全部依赖的插件上下文。
+* @param config - 插件配置。
+*/
+function apply(ctx, config = {}) {
+	const supervisor = new Supervisor(ctx);
+	ctx.effect(() => supervisor.start(), "sandbox-param-normalizer.lifecycle()");
+	if ((config.logLevel ?? "info") !== "silent") ctx.logger.info("sandbox-param-normalizer: session-aware escalation schema projection enabled");
+}
+var src_default = {
+	name,
+	inject,
+	Config,
+	apply
+};
+
+//#endregion
+export { Config, apply, src_default as default, inject, name };

package/package.json

@@ -1,6 +1,91 @@
 {
   "name": "dsh-sandbox-param-normalizer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "会话感知的沙箱提权参数归一化插件：按会话的沙箱模式与审批策略裁剪模型可见的 sandbox_permissions/justification，并在执行前清理无法生效的提权参数",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rengy/dsh-sandbox-param-normalizer.git"
+  },
+  "homepage": "https://github.com/rengy/dsh-sandbox-param-normalizer",
+  "bugs": {
+    "url": "https://github.com/rengy/dsh-sandbox-param-normalizer/issues"
+  },
+  "keywords": [
+    "deepseek",
+    "harness",
+    "dsh",
+    "sandbox",
+    "escalation",
+    "plugin"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": "^0.2.0-rc.2 || ^0.2.1-alpha.1"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.4 || ^4.0.5-alpha.1",
+    "@deepseek-ai/dsh-agent": "^0.2.0-rc.2 || ^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.2.0-rc.2 || ^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "^0.2.0-rc.2 || ^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.2.0-rc.2 || ^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-scope": "^0.2.0-rc.2 || ^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.2.0-rc.2 || ^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2 || ^0.2.1-alpha.1",
+    "@deepseek-ai/dsh-user-approval": "^0.2.0-rc.2 || ^0.2.1-alpha.1",
+    "@deepseek-ai/schemastery": "^3.18.4"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-scope": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-user-approval": "0.2.1-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.4",
+    "@types/node": "^22.20.0",
+    "tsdown": "^0.15.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit && tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "verify:host": "node scripts/verify.mjs --host",
+    "verify:host:without-plugin": "node scripts/verify.mjs --host --without-plugin",
+    "verify:schema": "docker cp scripts/schema-probe.mjs dsh-sandbox-param-normalizer:/tmp/schema-probe.mjs && docker exec dsh-sandbox-param-normalizer node /tmp/schema-probe.mjs"
+  }
 }