ChatGPTClaudeGrok / X / CursorGemini

DSH plugin sandbox: per-call policy and confined argv

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessSandboxConfinedArgvFail closed
DSH plugin sandbox: file-effect-only modes, per-call policy resolution, ConfinedArgv stderr classifiers, and fail-closed confinement with no backend.

"The sandbox is on yet commands escape" usually means you read it as network and process isolation. DSH plugin's SandboxMode governs filesystem effects only; network access and process visibility are outside this vocabulary. Set that boundary straight before arguing about policy resolution.

The sandbox governs file effects only

All three modes differ only in whether writing is allowed.(source)

dsh-sandbox wraps subprocess argv in a file-effect policy while sharing the execution environment with the paired subprocess provider, without coupling consumers to a platform runner. dsh-sandbox-local supplies Linux bwrap/Landlock, macOS Seatbelt, and Windows ACL restricted-token backends; dsh-bash-sandbox and dsh-pwsh-sandbox are consumers; dsh-sandbox-ssh executes the same policy through a paired remote backend.

The three mode promises:

  1. read-only — the backend must deny writes. POSIX runners still grant the /dev/null sink their shell needs; Windows ACL runners grant no explicit writable root and report partial enforcement because of environment ACL gaps.
  2. workspace-write — writes allowed under the workspace root, supported extra directories, and temp areas the backend promises.
  3. danger-full-access — isolation bypassed.

Network and process visibility are not defined here. "The sandbox stops the model from curling the internal network" is a wrong expectation; that needs network isolation or a policy layer.

danger-full-access never enters ctx.sandbox

Only the two restricted modes reach a provider.(source)

Consumers of danger-full-access spawn the raw argv directly without calling ctx.sandbox. So "the sandbox plugin was not called in full-access mode" is normal, not broken.

Enforcement is a backend-reported fact with exactly two levels:

  • full — the backend governs every file effect the mode promises;
  • partial — the active backend or an older kernel ABI governs only a subset.

The requirement is firm: consumers needing absolute guarantees must reject partial or surface it upward, never treat it as full. Known partial cases include older Landlock ABIs and the Windows ACL runner's hard links, unrestricted reads, and AppContainer ACL boundaries.

Per-call policy: resolve once, then decide

Policy travels with the call rather than being fixed on the provider.(source)

The complete execution policy resolves and travels with each capability call, including for danger-full-access, so consumers can resolve once and then decide whether to bypass constraints.

Ordinary tool calls derive workspaceRoot from the calling session's immutable cwd; deployment configuration supplies fallbacks for agent-less calls plus shared extra write authorizations; registering a live Session adds directory authorizations for later resolution within the effect lifetime.

The resolver preserves absolute path spelling from the execution environment, while enforcing providers normalize roots at the location where files actually exist. A cwd containing symlinks or .. therefore ends up identifying the directory the paired subprocess provider actually runs in.

SandboxExecutionPolicy has four fields: mode, workspaceRoot, optional additionalWritableRoots, and optional sessionId. sessionId is the opaque calling-session identity backends use for per-session state — Windows ACL, for example, assigns each live session and workspace pair a random private temp directory and SID while workspace SIDs and standing grants stay per workspace; agent-less calls omit it and fall back to per-call state.

resolve priority

An approved explicit mode beats the session log, and the session log beats deployment defaults.(source)

ctx.sandboxPolicy.resolve() takes a live session and, for approved retries, an explicit mode. The service owns precedence and root fallback rules so bash and fs need not reimplement them.

SandboxPolicyRequest has only two fields: optional session and optional mode. Precedence is: approved explicit mode > the session's last sandbox/mode event > deployment defaults.

Workspace root semantics: the session cwd is the workspace-write boundary, and a configured root is the fallback for agent-less calls and sessions without a cwd. Configured extra roots and that Session's active registrations are snapshotted together; existing operations and processes keep their own policy.

registerWritableRoot(session, directory) carries an often-missed limit: the grant is runtime-only and must be re-registered after restore or fork. On Windows only Harness file tools honor extra grants, while process permissions stay unchanged. When the recorded cwd is relative or contains a NUL byte, resolve throws SANDBOX_INVALID_ROOT.

Three things in ConfinedArgv

Wrapped argv, enforcement facts, and two orthogonal stderr classifiers.(source)

ConfinedArgv.argv is "runner, profile, separator, then the caller's own argv." Consumers should spawn that instead of the raw argv.

denialSignatures is the selected backend's denial dialect: EROFS text under bwrap read-only binds, Landlock's EACCES, Seatbelt's EPERM. A consumer inferring denial from a failed run's stderr must match only this dialect, never a cross-backend union — a union claims denials some backend never produces.

runnerFailureRules is the evidence for sandbox infrastructure failure. RunnerFailureRule has optional allowedExitCodes, required fatalSignatures, and optional informationalLines. Classification order is fixed: strip informational exclusions by exact case-insensitive whole-line match first, then match fatal signatures case-insensitively in each remaining line. Exit status alone can never prove a runner failure.

The two failures mean completely different things: a runner failure means the command never ran; a denial means the constraint held and blocked it. Consumers should check runner failure first and report it as sandbox infrastructure trouble, not an ordinary task failure.

No backend means an error, never a quiet downgrade to a bare run.(source)

await ctx.sandbox.confine(argv, policy, signal) resolves policy paths in the execution environment and returns ConfinedArgv. Without a usable backend it rejects with SandboxUnavailableError (SANDBOX_UNAVAILABLE); when a provider cannot prepare host state for the mode it rejects with SandboxPreparationError (SANDBOX_PREPARATION_FAILED, SANDBOX_INVALID_TEMP_ROOT). An optional signal can cancel resolution before launch.

The sentence worth copying: for a restricted policy, silent unconfined pass-through is never legal.

Provider selection, probing, caching, and backend-specific enforcement reporting belong to the local provider; capability probing arbitrates multi-runner chains and may be skipped with a single candidate, whose own rejection is still a fail-closed endpoint. Sandboxed bash consumers own spawn and result attribution, while providers only map runner dialects into rules.

Verification: an out-of-bounds command and a dead provider

Cover both "denied" and "runner died."(source)

  1. Run a file-writing command under read-only and assert stderr matches a denialSignatures dialect with a non-zero exit.
  2. Write inside cwd under workspace-write and assert success; write outside and assert denial.
  3. Call registerWritableRoot for an extra directory, assert it is writable, then restore the session, retry, and assert the grant is gone.
  4. Force a runner that fails at startup and assert runnerFailureRules classifies it as infrastructure failure rather than task failure.
  5. Remove every usable backend, call confine, and assert SANDBOX_UNAVAILABLE with no command spawned.
  6. Run a security-sensitive command on a partial backend and assert the consumer rejects or explicitly surfaces that state.

If step 4 is treated as an ordinary failure, users will edit their command while the sandbox environment is what needs fixing.

For the overall mode differences, see sandbox modes; for the stricter-widening check on escalation retries, see escalation must be strictly wider.

One line to close: modes govern files only, full access never reaches the seam, policy travels per call, denial dialects stay backend-specific, runner failure precedes denial, and no backend means fail-closed.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Does the DSH plugin sandbox restrict network access?

No. DSH plugin's SandboxMode governs filesystem effects only. DSH plugin explicitly excludes network and process visibility from this vocabulary.

Does DSH plugin danger-full-access call ctx.sandbox?

No. DSH plugin has that mode's consumers spawn the raw argv directly. DSH plugin sends only the two restricted modes to a provider.

Can DSH plugin partial enforcement be treated as full?

No. DSH plugin requires the distinction. DSH plugin's partial means the active backend or an older kernel ABI covered only a subset, so consumers needing guarantees must reject or surface it.

Can DSH plugin denialSignatures union every backend?

No. DSH plugin requires the dialect of the selected backend only. DSH plugin notes a union would claim denials a backend never produces, causing misclassification.

Related Terms

SandboxMode
SandboxMode is the file-effect policy for a confined process: read-only, workspace-write, or danger-full-access.— packages/sandbox/sandbox/src/index.ts
SandboxExecutionPolicy
SandboxExecutionPolicy is the complete file-effect policy resolved for one capability call: mode, workspace root, optional extra writable roots.— packages/sandbox/sandbox/src/index.ts
ConfinedArgv
ConfinedArgv is confine's result: wrapped argv, enforcement completeness, and two kinds of stderr classifier.— packages/sandbox/sandbox/src/index.ts
RunnerFailureRule
RunnerFailureRule is structured evidence that a sandbox runner failed before running the command, with exit-code gating and fatal signatures.— packages/sandbox/sandbox/src/index.ts

Sources