JUSTMONIKA2022/dsh-sandbox-escalation-fix
Session-aware sandbox escalation compatibility plugin for DeepSeek Harness/DSH第三方模型会话沙箱升级兼容插件
编辑导读Editor's Brief
## 核心特性
- 根据每个会话实时的 Sandbox Mode 和 Approval Policy，投影模型可见的 bash、pwsh、write 和 edit 工具 schema。
- 当会话已经处于 danger-full-access 或 approval policy 为 never 时，从面向模型的 schema 中移除 sandbox_permissions 和 justification。
- 在允许审批的 read-only 和 workspace-write 会话中，仅暴露真正更宽泛的升级目标。
- 仅当请求模式等于有效模式时，移除执行时的 sandbox_permissions 和 justification 成对字段；降级、未知目标、未配对以及真实升级请求仍交由 DSH 正常校验。
- 当不存在可行升级目标时，从 Shell 工具描述中剥离升级指引，并从 Shell、filesystem、Code Mode 和 job_output 结果中移除不可能的升级提示。
## 使用场景
- All Access 会话中，第三方模型在工具执行前因无效 justification 或非放宽型 sandbox 升级错误而反复失败的场景。
- 使用 approval=never 的会话中，已暴露的升级字段无法成功并可能导致重试循环。
- read-only 或 workspace-write 会话中，模型应只看到严格宽于当前模式的升级目标。
- 使用动态 Preset restrictions 的 Agent，需要 wrapper 可见性随工具可用性变化，而无需重建 Agent。
## 技术细节
- Schema 投影发生在每个 Agent Exact Scope 内，因此 Native tool schemas 和 Code Mode SDK 定义会读取到相同的会话特定结果。
- 插件监听 Agent 创建、销毁、Preset 变更、restrictions 和工具变更，并随着工具面变化恢复或挂起 wrappers。
- 启动校验会检查已安装的 @deepseek-ai/dsh-* 包版本，并拒绝混合或未知的 DSH 版本，而不是继续使用不兼容的工具定义。
- Wrapper 协调使用显式的 Symbol.for('dsh.tool-wrapper.v1') 协议，未知的同名 wrapper 会导致 Agent 注册失败。
## 注意事项
- DSH rc8 已通过 approval=never 运行时指令部分解决该问题，因此 RC8 用户在安装此插件前应先复现所述故障。
- 该插件需要 Node.js ^22.19.0 或 >=24.0.0、@deepseek-ai/cordis 4.0.1，以及 DSH 0.1.0-rc.5 到 0.1.0-rc.8。
- 基于 Git 的安装会执行包的 prepare 脚本，并可能需要在 Profile 的 pnpm-workspace.yaml 中添加 allowBuilds 条目。
## Core Features
- Projects the model-visible tool schema for bash, pwsh, write, and edit from each session's live Sandbox Mode and Approval Policy.
- Removes sandbox_permissions and justification from the model-facing schema when the session is already at danger-full-access or when the approval policy is never.
- Advertises only genuinely wider escalation targets in read-only and workspace-write sessions where approval is allowed.
- Removes an execution-time sandbox_permissions and justification pair only when the requested mode equals the effective mode, while leaving downgrade, unknown-target, unpaired, and genuine escalation requests for normal DSH validation.
- Strips escalation guidance from Shell tool descriptions and removes impossible escalation hints from Shell, filesystem, Code Mode, and job_output results when no viable escalation target exists.
## Use Cases
- All Access sessions where third-party models repeatedly fail on invalid justification or non-widening sandbox escalation errors before tool execution.
- Sessions using approval=never where advertised escalation fields cannot succeed and may cause retry loops.
- read-only or workspace-write sessions where the model should see only escalation targets that are strictly wider than the current mode.
- Agents using dynamic Preset restrictions that require wrapper visibility to follow tool availability without recreating the Agent.
## Technical Details
- Schema projection occurs inside each Agent Exact Scope, so Native tool schemas and Code Mode SDK definitions read the same session-specific result.
- The plugin listens to Agent creation, disposal, Preset changes, restrictions, and tool changes, restoring or suspending wrappers as the tool surface changes.
- Startup verification checks installed @deepseek-ai/dsh-* package versions and rejects mixed or unknown DSH releases instead of continuing with incompatible tool definitions.
- Wrapper coordination uses the explicit Symbol.for('dsh.tool-wrapper.v1') protocol, and unknown same-name wrappers cause Agent registration to fail.
## Notes
- DSH rc8 partially addresses the issue through an approval=never runtime instruction, so RC8 users should reproduce the described failures before installing this plugin.
- The plugin requires Node.js ^22.19.0 or >=24.0.0, @deepseek-ai/cordis 4.0.1, and DSH 0.1.0-rc.5 through 0.1.0-rc.8.
- Git-based installation executes the package prepare script and may require an allowBuilds entry in the Profile's pnpm-workspace.yaml.
安装Install
dsh plugin --profile web add github:JUSTMONIKA2022/dsh-sandbox-escalation-fix把 JUSTMONIKA2022/dsh-sandbox-escalation-fix 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
dsh-sandbox-escalation-fix (RC8 is now supported)
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=neverruntime 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/justificationin All Access sessions, so tools fail before they run. - In
workspace-writesessions, models see two escalation targets even though onlydanger-full-accessis 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:
| Current mode | Approval policy | What the model sees |
|---|---|---|
read-only |
ask |
workspace-write, danger-full-access |
workspace-write |
ask |
danger-full-access only |
danger-full-access |
ask |
no escalation fields |
| any mode | never |
no escalation fields |
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+ requestdanger-full-access→ ignored, tool runs normally;danger-full-access+ requestworkspace-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 availablehints are removed from Shell, filesystem, Code Mode, andjob_outputresults.
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
| Capability | This plugin | Execution-only normalization |
|---|---|---|
| Hide impossible escalation fields from Native tools | yes, per session | no |
| Hide the same fields from the Code Mode SDK | yes, from the same exact-scope definition | no |
| Remove only an exact same-mode redundant request | yes | implementation-dependent |
| Preserve explicit downgrade and invalid requests for DSH validation | yes | not guaranteed |
Preserve missing or blank justification for DSH validation |
yes | not guaranteed |
| Remove impossible advice from descriptions and results | Shell, FS, Code Mode, and job_output |
no |
| React to Agent, Preset, and tool lifecycle changes | yes | implementation-dependent |
Compatibility
- Node.js
^22.19.0or>=24.0.0 @deepseek-ai/dsh-*0.1.0-rc.5,0.1.0-rc.6,0.1.0-rc.7, or0.1.0-rc.8@deepseek-ai/cordis4.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
| Scenario | Plugin behavior |
|---|---|
danger-full-access, or any mode with never |
Model sees no sandbox_permissions / justification |
workspace-write with approval allowed |
Only danger-full-access is advertised |
read-only with approval allowed |
workspace-write and danger-full-access are advertised |
| Model sends the exact current mode as an escalation request | The redundant pair is removed, then the original tool runs |
| Downgrade, unknown target, unpaired arguments, genuine escalation | Left untouched for original DSH validation |
| No viable escalation target | Shell description escalation tail is removed; impossible hints are stripped from denial results |
| A dynamic Preset restricts a target tool | Its Exact Scope wrapper disappears in the same synchronous change |
| The restriction is lifted or the provider returns | The projected wrapper is restored automatically |
| A runtime replacement is incompatible | Only that Agent and target remain unwrapped until a compatible definition appears |
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.
- Select the previously affected OAI model.
- Set Access Mode to All Access.
- Ask the model to run
pwshand print the current directory. - Ask it to create a temporary file with
write. - Ask it to update the file with
edit, then read it back. - Switch workspaces and open existing sessions to confirm normal session restoration.
- 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
| Problem | What to do |
|---|---|
| The plugin does not load | Confirm installation and startup use the same --profile, then inspect --dump-config |
| A Git install cannot build | Add the package to the Profile's allowBuilds map and retry the installation |
| Startup rejects DSH versions | Keep the relevant @deepseek-ai/dsh-* packages on one supported release candidate |
| Agent registration reports a tool conflict | Remove the incompatible same-name wrapper or update it to implement the wrapper protocol |
| A dynamic Preset hides tools | This is expected; the plugin mirrors tools.restrict() and restores wrappers when the restriction is lifted |
| A runtime reconciliation warning appears | Check the named target's replacement definition; other tools and Agents remain active while the plugin waits for a compatible definition |
| Escalation fields remain visible | Test a new session and check whether a later plugin replaces the same tool names |
| Manual installation breaks Scope behavior | Remove the plugin's nested node_modules and verify that package.json is directly under the expected package directory |
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
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
tt-a1i/archify
Agent skill for beautiful, verifiable architecture, workflow, sequence, data-flow, and lifecycle diagrams—self-contained…
-
strukto-ai/mirage
The World's First Unified Virtual Filesystem For AI Agents
-
liustack/modlens
The first vision plugin for DeepSeek Harness, and the vision bridge for every text-only coding agent. Paste an image, ge…
-
omdsh-dev/DSH-better-sidebar
开放的侧边栏底座，支持三方拓展注册新侧边栏页面。内置文件渲染编辑/终端/Git/子代理页面 ｜ Open sidebar foundation, supports third-party extensions to register new…
-
dsh-market/dsh-market
The plugin market inside DeepSeek Harness — browse, search, one-click install · DSH 可视化插件市场
-
GanyuanRan/Aegis
Make AI coding agents architecture-aware: baseline-first, evidence-verified, drift-checked, and safe across long tasks.