sjw1231
45db11970c
The working-directory service throws WorkingDirectoryError: WORKING_DIRECTORY_INVALID for an empty cd, WORKING_DIRECTORY_NOT_FOUND for a missing target, and WORKING_DIRECTORY_UNAVAILABLE when the current and original directories are both gone or the service was disposed. The working_directory tool reports a missing Agent as ToolContextUnavailableError and an empty cd as ToolArgsError. sandbox-policy reports a session cwd it cannot use as a workspace root as SandboxInvalidRootError (SANDBOX_INVALID_ROOT), whose constructor now names the role of the rejected path. Refs #7869
description, kind
| description | kind |
|---|---|
| The process-sandbox package group: the confinement seam, per-platform backends, the shared policy resolver, and the Windows write-restriction rung. | package-group |
packages/sandbox
English | 中文
Summary
The sandbox/ group confines subprocess execution to a file-effect policy: commands run read-only, write only under the session workspace (workspace-write), or run unrestricted (danger-full-access). Four packages deliver it: the confinement service (sandbox/), the per-platform backends for Linux, macOS, and Windows (sandbox-local/), the shared policy resolver (sandbox-policy/), and the Windows write-restriction backend (sandbox-windows-acl/). A confined call that a policy denies can retry through a user-approved one-time escalation. Confinement is same-world only: it shares the host kernel and filesystem, while containers, microVMs, and remote executors replace whole capabilities instead of registering here.
Table of Contents
Packages
Four packages play the confinement roles; the subsystem reference owns the exhaustive contracts and the per-call policy semantics.
| Package | Role | ctx key |
|---|---|---|
sandbox/ |
Confinement service contract: modes, enforcement, per-call policy, and the escalation vocabulary | ctx.sandbox |
sandbox-local/ |
Per-platform confinement backends: Linux bwrap then Landlock, macOS Seatbelt, Windows restricted token | registers on ctx.sandbox |
sandbox-policy/ |
Shared policy home: deployment defaults and per-session mode overrides for every enforcing family | ctx.sandboxPolicy |
sandbox-windows-acl/ |
Windows write restriction: confined children may write only in the workspace and a private temp directory | — (mounted by sandbox-local as the win32 backend) |
Related documentation
Start with the subsystem reference for the shared vocabulary, then the confinement decision and its cross-family extension.
- Process sandbox subsystem — modes, per-call policy, wrapped-argv dialects, and fail-closed errors.
- The historical subprocess sandbox decision — the capability boundary, escalation choreography, and deferred phases.
- Cross-family file sandbox reference — the shared policy home and the sandboxed filesystem provider.
- Windows ACL restricted-token sandbox decision — why raw ACL restricted tokens over mxc and AppContainer.
Dev Note
Working context for maintainers — click to expand
None.