dsh-sandbox-escalation-fix

一句话定位

这是一个 DSH 兼容插件,按当前 Session 的沙箱权限和审批策略,实时调整模型可见的工具参数和说明,解决在 All Access 下 OAI 系列模型反复触发 sandbox_permissions / justification 升级校验失败而陷入重试循环的问题。

核心能力

• 动态隐藏无效升级字段:按 Session 当前的 Sandbox Mode 和 Approval Policy,把模型不需要也不应该看到的 sandbox_permissions 与 justification 参数从工具 Schema 中剔除
• 精确同模式参数归一化:仅在模型发来与当前模式完全一致的冗余升级请求时,静默删除这对参数并按普通调用放行,不改变更窄/更宽等其它请求
• 同步清理描述和结果中的升级提示:从 Shell 工具说明尾部、文件工具结果以及 job_output 中过滤已不再可执行的"升级可用"提示
• 监听 Agent/Preset/工具生命周期,自动接入和退出包装,限制解除后无需重建 Agent 即可恢复
• 启动时校验 DSH 包版本一致性,避免混装导致运行期行为不一致
• 与实现 dsh.tool-wrapper.v1 协作协议的同类包装插件按优先级链式协作

技术实现

• 语言: TypeScript
• 关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-agent、@deepseek-ai/dsh-sandbox、@deepseek-ai/dsh-sandbox-policy、@deepseek-ai/dsh-tools
• 架构模式: Cordis 插件,启动时通过 cordis.patch.yml 将自身注册为 sandbox-escalation-fix 节点;Supervisor 监听 agent/created、agent/disposed、agent-preset/selected、tools/change 事件,按 Agent 维护一个 bash / pwsh / write / edit 的包装绑定,优先尝试协作协议 Symbol.for('dsh.tool-wrapper.v1'),否则回退到自有 WrapperBinding 注册到 agent.ctx.tools 精确作用域
• 入口文件: src/index.ts(构建产物 lib/index.mjs)

适用场景

DSH 用户使用 OAI 系列第三方模型(典型如 GPT)在 All Access(danger-full-access + approval=never)或权限边界会话中执行 bash、pwsh、write、edit 工具时,模型反复发送同模式/空 justification 升级请求导致工具失败并陷入重试循环。Code Mode 与 Native Tool Call 表现不一致,或者 Preset 动态调用 agent.ctx.tools.restrict() 后需要 Agent 重建才能恢复包装时,本插件通过 Schema 投影的方式让模型在请求阶段就看不到这些不可能成功的参数,从根源上消除循环。

前置依赖与兼容性

安装方式

dsh plugin --profile web add --allow-build=dsh-sandbox-escalation-fix github:JUSTMONIKA2022/dsh-sandbox-escalation-fix

配置项

常见问题

Q: 安装后还需要修改任何配置吗?

A: 不需要,本插件是零配置设计。安装到当前 DSH Profile 后重启 DSH 即可,插件会按每个 Session 当前的 Sandbox Mode 与 Approval Policy 自动调整模型可见的工具参数。

Q: 它会修改 DSH 的安全校验逻辑吗?

A: 不会。严格变宽检查、审批流程、一次性授权语义都保持原样,插件只做模型可见面的参数投影和最小兼容处理,不会自动批准任何升级请求,也不会为缺失或空白的 justification 填占位内容。

Q: 卸载插件的命令是什么?

A: 在安装使用的同一 Profile 下执行 dsh plugin --profile <profile> remove dsh-sandbox-escalation-fix,卸载后重启 DSH 即可恢复原始工具行为,所有包装层会随插件生命周期自动释放。

Q: 0.1.1-rc.1 用户还需要这个插件吗?

A: 官方 0.1.1-rc.1 在 approval=never 路径上做了部分运行时改善,但仍使用相同的静态升级 Schema 和执行期校验。如果你仍然看到 invalid justification、同模式 danger-full-access 等错误或模型陷入重试循环,可以安装本插件从 Schema 层面进一步收敛。

Q: 多个 Agent 各自权限不同时,会不会互相影响?

A: 不会。插件按 Agent Exact Scope 独立包装,不同 Session 即使在同一进程内各自按自己的权限状态计算参数,互相不会污染;中途切换权限后,下一次模型请求的工具 Schema 会立即按新状态重新计算。

Q: 启动时报版本错误怎么办?

A: Profile 内的 @deepseek-ai/dsh-* 包必须保持版本一致,且必须落在白名单 0.1.0-rc.5、0.1.0-rc.6、0.1.0-rc.7、0.1.0-rc.8 或 0.1.1-rc.1 中的某一个。混装或未知版本会被插件拒绝启动,错误信息会列出实际检测到的版本组合。

Q: 另一个插件也包装了 bash/pwsh/write/edit 怎么办?

A: 取决于对方是否实现 Symbol.for('dsh.tool-wrapper.v1') 协作协议。已实现的可以按 priority + owner 稳定排序链式协作;未实现的同名工具注册会被本插件明确拒绝,避免静默改变包装顺序或产生错误语义,此时需要卸载其中一个插件。

Q: 升级字段仍然出现怎么办?

A: 确认查看的是安装后新建 Session 的 Schema(旧 Session 沿用安装前的工具定义),并通过 dsh --profile <profile> --dump-config 确认 sandbox-escalation-fix 层与 Bundle 行都存在;若仍有后加载的插件替换同名工具,按上一个问题处理。

上手难度

入门 — 零配置、零运行期干预,安装到 Profile 并重启 DSH 即可生效,失败时仅在启动日志或协调警告中给出明确错误信息。

已知问题与限制

• 仅包装四个内置工具:bash、pwsh、write、edit;其它工具不在覆盖范围
• 目标工具必须满足 Schema 约束:同时声明 sandbox_permissions 和 justification 两个字段,或同时省略,只声明其中一个会在注册时被拒绝
• 运行期被替换为不兼容定义(缺字段、output 契约残缺)的目标工具,仅让对应 Agent 的对应工具进入休眠并记录警告,不会终止 Host 进程;兼容定义恢复后自动重新接入
• 仅支持 DSH 0.1.0-rc.5 至 0.1.1-rc.1 之间且版本一致的部署,其它版本会拒绝启动
• 当 approval 策略为 never 时,任何升级目标都会被隐藏,模型走不到审批流程(此为既有安全语义,非本插件引入)
• 暂未发现源码内 TODO/FIXME 标记的未解决问题

English | 中文

[!IMPORTANT] This is an independent community plugin. It is not published, maintained, or endorsed by DeepSeek, and it does not modify DeepSeek Harness core packages.

[!CAUTION] DSH rc8 partially improves this issue through an approval=never runtime instruction, but tool schemas may still advertise escalation fields that the current Session cannot use, and real-world reliability is not yet clear. RC8 users should first observe the built-in behavior and install this plugin only after reproducing the same-mode escalation, blank justification, or retry-loop failures described below.

dsh-sandbox-escalation-fix is a zero-configuration compatibility plugin that directly resolves the issue of third-party models like GPT failing to call tools such as bash, pwsh, write, and edit under DSH All Access, resulting in repeated retries due to incorrect sandbox escalation parameter prompts.

If you've encountered the following errors, this plugin is designed for them:

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

Contents

• What It Does
• The Problem It Solves
• Before and After
• Why This Plugin
• This Plugin vs. Execution-Only Normalization
• Compatibility
• Quick Start
• Release One-Click Install and Uninstall
• Upgrade
• Install From GitHub
• Manual Windows Installation
• Behavior at a Glance
• Verify the Fix
• Wrapper Conflicts
• Troubleshooting
• Uninstall
• Development
• License

What It Does

This plugin makes DeepSeek Harness show the model only the sandbox escalation options that the current session can actually use.

In an All Access session (danger-full-access + never), the stock DSH tools still advertise sandbox_permissions and justification on bash, pwsh, write, and edit. But in that state:

• the session is already at the highest sandbox mode, so no wider mode exists;
• the approval policy is never, so every escalation request is rejected.

When a model fills in those parameters, the call fails before it runs. The model may then retry with different values and get stuck in a loop.

This plugin projects the model-visible tool schema per session, based on the live Sandbox Mode and Approval Policy. It also adds a minimal execution-time fallback for redundant same-mode requests.

The Problem It Solves

• Models still see and send sandbox_permissions / justification in All Access sessions, so tools fail before they run.
• In workspace-write sessions, models see two escalation targets even though only danger-full-access is genuinely wider.
• With approval=never, models are still told escalation is possible when every request will be rejected.
• Tool descriptions and denial results keep saying “escalation available,” which pushes the model to retry.
• Native Tool Call and Code Mode SDK can show inconsistent capability surfaces.

Why It Happens

DSH tools expose static escalation fields when they are registered, while the modes that can actually be requested depend on each session's current Sandbox Mode and Approval Policy. The original model-visible schema is not projected from that live session state before the request is built, so a model can receive escalation parameters that cannot succeed. Tool validation then rejects those requests before execution, which can start a retry loop.

Before and After

Without the plugin, affected All Access sessions can repeatedly fail before the requested operation runs. The model alternates between an empty justification, a same-mode danger-full-access request, and even a downgrade request that DSH correctly rejects as not strictly wider.

Before: Repeated Validation and Escalation Errors

After: Tools Complete the Workflow

After installation, the same model can continue through Edit, Read, Pwsh, formatting, tests, lint, and type checking without entering the invalid escalation loop.

Why This Plugin

It fixes the root cause, not just the error

Some fixes only delete the arguments after the model has already received a broken schema. Calls stop failing, but the model keeps seeing and sending the same unusable parameters.

This plugin projects the model-visible schema from the session's real permission state:

When the model cannot see a parameter that cannot succeed, it stops reaching for it.

It won't fix Native Tool Call but leave Code Mode broken

Projection happens on the tool definition inside each Agent Exact Scope, so Native tool schemas and the Code Mode SDK read the same result:

• Native tool schemas omit impossible escalation fields;
• Code Mode TypeScript/Python SDKs omit them too;
• behavior stays identical across both modes.

It won't silently swallow a downgrade request

The execution fallback is deliberately narrow: it removes sandbox_permissions and justification only when requestedMode === effectiveMode, treating that pair as an idempotent duplicate.

Downgrade or invalid requests are left untouched and go through normal DSH validation:

• danger-full-access + request danger-full-access → ignored, tool runs normally;
• danger-full-access + request workspace-write → not executed as Full access;
• read-only + a wider request → enters the normal approval flow.

It will not trade a clear error for silently running a call with broader access than the caller asked for.

It won't invent an approval reason

For genuine escalation requests, the plugin does not fill in a fake or placeholder justification. Missing, blank, or invalid reasons still go through DSH's own validation, so the approval flow sees honest, auditable input.

It won't say “don't escalate” while results say “escalation available”

When the session has no viable escalation target, the plugin also cleans up the natural-language side:

• the escalation guidance tail is removed from Shell tool descriptions;
• impossible escalation available hints are removed from Shell, filesystem, Code Mode, and job_output results.

The model no longer receives contradictory instructions from the parameter schema, the description, and the failure output.

It won't modify or bypass DSH's security core

approveEscalation() keeps its strictly-wider check, approval flow, and one-shot authorization semantics. The plugin only projects the model-visible surface and removes one redundant same-mode pair before delegating:

• no removal of the strictly-wider check;
• no auto-approval when approval=never;
• no extra permissions;
• no changes to DSH installation or core packages.

It won't treat every session the same

Wrapping happens per Agent/Session, never on the global tool registry. In the same process:

Session A = read-only + ask              → sees two escalation targets
Session B = danger-full-access + never   → sees no escalation fields

Each session is independent. If a session switches permission state mid-flight, the next model request gets a freshly projected schema.

It won't leave stale wrappers behind

The plugin listens to Agent creation, disposal, Preset changes, restrictions, and tool changes. When a dynamic Preset calls agent.ctx.tools.restrict(), the corresponding Exact Scope wrappers disappear synchronously with the restricted parent tools. Lifting the restriction restores the projected wrappers; tools absent during Agent creation are wrapped when they later become visible. Each Agent is coordinated independently, and disposed Agents or unloaded plugins restore the original definitions.

It won't lock you to a single DSH release

The plugin supports DSH 0.1.0-rc.5, 0.1.0-rc.6, 0.1.0-rc.7, and 0.1.0-rc.8. At startup it verifies that the installed @deepseek-ai/dsh-* packages are consistent and supported. Incompatible tool definitions fail explicitly instead of producing silent misbehavior.

It won't add configuration burden

Zero configuration. Install it into the Profile you actually use and start DSH as before. The test suite contains 28 tests built on real DSH packages, covering schema projection, Code Mode SDK generation, dynamic restrictions, multi-Agent isolation, delegate and wrapper-protocol replacement, internal timeout-budget forwarding, failure-hint cleanup, and unload behavior.

This Plugin vs. Execution-Only Normalization

Compatibility

• Node.js ^22.19.0 or >=24.0.0
• @deepseek-ai/dsh-* 0.1.0-rc.5, 0.1.0-rc.6, 0.1.0-rc.7, or 0.1.0-rc.8
• @deepseek-ai/cordis 4.0.1

The plugin checks the installed DSH package versions at startup. Mixed rc.5/rc.6/rc.7/rc.8 installations and unknown DSH versions fail explicitly. An initially visible target with partial escalation fields or an incompatible output definition rejects that Agent's registration; a target that omits both escalation fields is accepted as already safe. During runtime, a Preset restriction or stable provider removal makes the wrapper dormant, while an incompatible replacement is isolated to that Agent and target tool and reported without terminating the Host process. A later compatible definition is wrapped automatically.

Quick Start

The plugin is a zero-configuration fix. Install it into the Profile that runs the affected sessions, then start DSH normally:

dsh --profile <profile>

You do not need to change the model configuration, Sandbox Mode, Approval Policy, or Agent Preset. The plugin projects the model-visible parameters from each Session's current permission state.

Release One-Click Install and Uninstall

The 0.1.2 Release uses the DSH CLI, so no manual Profile patch editing is required. Download and extract dsh-sandbox-escalation-fix-release.zip; it contains the tarball, one-click install and uninstall scripts, and a concise Chinese usage guide.

Close DSH before installing or removing the plugin. Ensure that dsh is available on PATH and that the running DSH version is rc5, rc6, rc7, or rc8. RC8 users should install only after reproducing the affected behavior.

Install into the default Web Profile

powershell -NoProfile -ExecutionPolicy Bypass -File ".\install-release.ps1"

The script runs dsh plugin --profile web add <tgz-absolute-path>.

Install or remove another Profile

For example, use headless instead of the default web Profile:

powershell -NoProfile -ExecutionPolicy Bypass -File ".\install-release.ps1" -Profile headless
powershell -NoProfile -ExecutionPolicy Bypass -File ".\uninstall-release.ps1" -Profile headless

Remove from the default Web Profile

powershell -NoProfile -ExecutionPolicy Bypass -File ".\uninstall-release.ps1"

The removal script runs dsh plugin --profile web remove dsh-sandbox-escalation-fix. Restart DSH after installation or removal.

Build the Release ZIP

powershell -NoProfile -ExecutionPolicy Bypass -File ".\build-release.ps1"

The script builds lib, packages the npm tarball, then creates dsh-sandbox-escalation-fix-release.zip in release/. The generated directory is ignored by Git; upload only this ZIP as the GitHub Release asset.

Upgrade

Close DSH before upgrading. The plugin package name, Bundle ID, and Profile patch row are unchanged, so an existing installation does not need another cordis.patch.yml entry.

GitHub Commit Installation

Run the same installation command with the new reviewed commit SHA:

dsh plugin --profile <profile> add github:<owner>/dsh-sandbox-escalation-fix#<new-commit-sha>

This updates the Profile dependency and rebuilds the package. Keep the existing allowBuilds entry when pnpm requires it, inspect --dump-config, then restart DSH.

Manual Web Profile Installation

Use the repository or packaged source that contains the new built lib directory. Open Windows PowerShell in that plugin directory and run:

powershell -NoProfile -ExecutionPolicy Bypass -File ".\deploy-web-profile.ps1"

The script uses $DSH_HOME when set, otherwise %USERPROFILE%\.dsh. It replaces only the eight published lib artifacts, compares every SHA-256 hash, and prints Deployment verified. only when the installed Web Profile exactly matches the new build. It does not modify the Profile patch or copy node_modules. Restart DSH after verification.

Install From GitHub

Install into the exact Profile that runs the affected sessions. Pin a reviewed commit SHA, because a Git dependency executes this package's prepare script during installation:

dsh plugin --profile <profile> add github:<owner>/dsh-sandbox-escalation-fix#<commit-sha>

pnpm 10 blocks Git dependency build scripts until the Profile explicitly allows them. If the first installation reports a blocked build, add this entry to $DSH_HOME/profiles/<profile>/pnpm-workspace.yaml:

allowBuilds:
  dsh-sandbox-escalation-fix: true

Run the installation command again, then inspect the composed configuration:

dsh --profile <profile> --dump-config

The output should contain a dsh-sandbox-escalation-fix bundle layer and the sandbox-escalation-fix plugin row. Start DSH normally after verification:

dsh --profile <profile>

Manual Windows Installation

A detailed Windows walkthrough — Profile paths, folder layout, nested node_modules, and the correct replacement for an empty [] patch — is available in README.zh.md.

For a compact file-by-file walkthrough, see Tutorials that even Peppa Pig can understand. The original Chinese layout is preserved in 奶龙也能看懂的食用说明.txt.

The minimum manual layout is:

<profile-directory>\
├── cordis.patch.yml
└── node_modules\
    └── dsh-sandbox-escalation-fix\
        ├── package.json
        ├── cordis.patch.yml
        ├── README.md
        ├── README.zh.md
        └── lib\
            ├── index.mjs
            ├── index.d.mts
            ├── wrapper-protocol.mjs
            └── wrapper-protocol.d.mts

Merge this block into the Profile's cordis.patch.yml; do not overwrite unrelated Profile patches:

- insert:
    - id: sandbox-escalation-fix
      name: dsh-sandbox-escalation-fix

Do not copy this repository's node_modules into the Profile. Multiple Cordis or DSH module instances can break Scope and Service identity.

To update an existing installation, follow Upgrade; do not repeat the Profile patch step.

Behavior at a Glance

Verify the Fix

After installing or updating the plugin, fully restart DSH and create a new session.

A successful Web startup proves that the Profile composes and the plugin loads without a process-level failure. For a source checkout, this command starts the Web profile directly:

node --import tsx/esm apps/cli/src/bin.ts web

Run it with a supported Node.js version available on PATH. Wait for dsh web: http://127.0.0.1:3080, then perform the behavior checks below. Startup alone does not prove dynamic restriction behavior.

1. Select the previously affected OAI model.
2. Set Access Mode to All Access.
3. Ask the model to run pwsh and print the current directory.
4. Ask it to create a temporary file with write.
5. Ask it to update the file with edit, then read it back.
6. Switch workspaces and open existing sessions to confirm normal session restoration.
7. If the Preset uses agent.ctx.tools.restrict(), enter its restricted state and confirm hidden tools disappear; lift the restriction and confirm they return without recreating the Agent.

The calls should complete without sandbox_permissions argument errors or impossible escalation advice. Existing sessions should remain visible, workspace switching should work, and new sessions should be created in the selected workspace. The complete manual acceptance checklist is in README.zh.md.

Wrapper Conflicts

The plugin owns the bash, pwsh, write, and edit names inside each Agent Exact Scope. Another plugin may share those names only through the explicit Symbol.for('dsh.tool-wrapper.v1') protocol. Cooperative layers are ordered by priority and owner.

An unknown same-name wrapper causes Agent registration to fail explicitly. In that case, remove one of the conflicting plugins rather than relying on an undefined load order.

Protocol types are exported from:

import {
  TOOL_WRAPPER_PROTOCOL,
  type WrapperLayer,
  type ToolWrapperProtocolV1,
} from 'dsh-sandbox-escalation-fix/wrapper-protocol'

Troubleshooting

Uninstall

dsh plugin --profile <profile> remove dsh-sandbox-escalation-fix

The plugin lifecycle removes its wrapper hosts, wrapper layers, and result filters. Confirm that --dump-config no longer lists the bundle after removal.

Development

npm install
npm test
npm run build
npm pack --dry-run

Git installation builds from source through the self-contained prepare script. Registry or tarball distribution may ship the generated lib files instead.

License

MIT