@deepseek-ai/dsh-sandbox-policy 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/sandbox/sandbox-policy/README.md
+README.md: b2512790c5cf5b3a06523cf91b50dd5d288b1522
+README.zh.md: 58354adf55a55951cad1ea9adb88aea2457c7f7b

package/README.md

@@ -0,0 +1,69 @@
+# dsh-sandbox-policy — the sandbox policy home (`ctx.sandboxPolicy`)
+
+English | [中文](README.zh.md)
+
+The single owner of sandbox-policy resolution: the deployment's default [`SandboxMode`](../sandbox/README.md) and fallback root, plus each session's durable mode override and immutable workspace root. Every enforcing capability receives one resolved mode-and-root policy per call; before each request, the model receives the current policy without a separate capability inventory.
+
+## Why a shared home
+
+Filesystem tools, one-shot bash commands, and terminal sessions may enforce the same mode vocabulary in different combinations. If each resolved its own `mode` + `workspaceRoot`, they could drift into a split world, exactly what [the sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) warns against. Each enforcing backend consumes the complete owner-resolved policy, while the current context describes only what that policy means for any available operation the DSH file sandbox enforces. The [cross-family fs sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md) records the shared-policy decision.
+
+## Config
+
+- `mode` — the deployment default `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`), validated at load. Default `read-only` (fail-safe).
+- `workspaceRoot` — the fallback directory `workspace-write` may write under for agentless calls or sessions without a cwd. Default `process.cwd()`, resolved to its absolute filesystem identity either way. A normal agent call uses its session header's immutable `cwd` instead.
+
+## Surface
+
+- `ctx.sandboxPolicy.resolve({ session?, mode? })` — resolves one complete per-call policy. An explicit approved mode outranks the session's last `sandbox/mode` event, which outranks `defaultMode`; the session's immutable `cwd` is canonicalized with filesystem semantics before becoming `workspaceRoot`, otherwise the configured fallback applies. Canonicalization precedes lexical normalization so `symlink/..` agrees with process working-directory resolution.
+- `ctx.sandboxPolicy.defaultMode` / `ctx.sandboxPolicy.workspaceRoot` — the deployment default and fallback root used by `resolve()`.
+- `sandbox:policy` — a request-time cache-safe context contribution derived directly from `resolve({ session })`. It states the mode's capability-neutral file-effect contract and the canonical session workspace under `workspace-write`; tool owners retain operation-specific denial and escalation guidance.
+- `effectiveSandboxMode(events)` — the pure fold of a session's `sandbox/mode` events (the last switch wins, or `undefined`), used inside `resolve()`.
+- `setSandboxMode(session, mode)` — THE write path for a per-session override: appends exactly one `sandbox/mode` event. The switch IS its event; nothing mutates the mode out of band.
+- `SANDBOX_MODES` — every mode, for option advertisement and runtime validation.
+
+The optional `./invariant` companion rejects a forged durable `sandbox/mode` event whose value falls outside that closed vocabulary; Session and its companion own the surrounding storage and core execution-enclosure rules. The agent loop logs the assembled full runtime-context snapshot as a sourced `user/message`, so exact policy input remains reconstructable without an in-memory “last told” mirror.
+
+## The per-session store
+
+A runtime switch is one log-only `sandbox/mode` event on the session it applies to. `effective = explicit grant ?? fold(events) ?? deployment default`, so an override survives restart by replay and two sessions never see each other's state. Workspace identity does not need another event: the immutable `SessionHeader.cwd` recorded at creation is the root for every call in that session. The event stays log-only; before the next request, the owner contributes the current fact to the full runtime-context snapshot.
+
+## Model Experience
+
+### Current file sandbox policy
+
+#### What the model sees
+
+One `sandbox:policy` contribution in the current runtime-context snapshot for every agent session. It does not enumerate mounted capabilities. Tool plugins retain operation and escalation guidance, approval policy contributes separately to the same snapshot, and plan guidance remains `dsh-plan-mode`'s system section.
+
+##### Read-only
+
+```markdown
+Current DSH file policy: read-only. Any available operation enforced by the DSH file sandbox cannot modify files in the standing mode. Do not refuse a required modification from this policy alone: try an available tool normally and follow any denial and escalation guidance it returns.
+```
+
+##### Workspace-write
+
+```markdown
+Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: "<workspace root>". Some platform temporary areas may also be writable.
+```
+
+##### Danger-full-access
+
+```markdown
+Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.
+```
+
+#### Token effect
+
+One concise durable context message on the first request and each effective policy change; unchanged requests add nothing. `workspace-write` carries only the canonical session workspace path; platform-specific temporary paths are summarized without adding host-dependent bytes.
+
+#### KV Cache effect
+
+The stable system prompt remains byte-identical across mode changes. A changed full context snapshot is appended after retained history, preserving the prior cached prefix; subsequent unchanged requests reuse that retained snapshot.
+
+## Known Limitations and Deferred Work
+
+- **One primary workspace root per session** — policy resolves `SessionHeader.cwd`; extra writable roots are not part of `SandboxExecutionPolicy`.
+- **File-effect modes only** — `SandboxMode` governs file effects; network and process policy are outside its vocabulary, so no knob here restricts them.
+- **Temporary areas are deliberately summarized** — enforcing backends grant different platform temporary areas, which are selected after policy resolution and therefore cannot be enumerated truthfully in the current context.

package/README.zh.md

@@ -0,0 +1,69 @@
+# dsh-sandbox-policy：沙箱策略归属位置（`ctx.sandboxPolicy`）
+
+[English](README.md) | 中文
+
+沙箱策略解析的唯一归属位置：部署默认 [`SandboxMode`](../sandbox/README.md) 与回退根目录，加上每个会话的持久模式覆盖和不可变工作区根目录。每项负责强制执行的能力在每次调用时都会收到一项解析完成的模式与根目录策略；模型在每次请求前会收到当前策略，而不会另收一份能力清单。
+
+## 为何需要共享归属位置
+
+文件系统工具、一次性 bash 命令和终端会话可以用不同组合强制执行同一套模式词汇。如果各自解析 `mode` + `workspaceRoot`，就可能漂移成分裂世界，正是[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)所警告的情况。每个强制执行后端都会消费归属方解析出的完整策略，而当前上下文只说明该策略对于任何受 DSH 文件沙箱强制执行的可用操作有何含义。[跨家族 fs 沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)记录了共享策略决策。
+
+## 配置
+
+- `mode`：部署默认 `SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`），加载时验证。默认为 `read-only`（故障安全）。
+- `workspaceRoot`：无 agent（智能体）的调用或没有 cwd 的会话在 `workspace-write` 下可写入的回退目录。默认为 `process.cwd()`；无论显式配置还是采用默认值，都会解析为其绝对文件系统标识。普通 agent 调用改用其会话头中不可变的 `cwd`。
+
+## 接口
+
+- `ctx.sandboxPolicy.resolve({ session?, mode? })`：解析一项完整的逐调用策略。显式批准的模式优先于会话最后一条 `sandbox/mode` 事件，后者又优先于 `defaultMode`；会话不可变的 `cwd` 会先按文件系统语义规范化，再成为 `workspaceRoot`，否则使用配置的回退值。规范化先于词法归一化，因此 `symlink/..` 与进程工作目录解析保持一致。
+- `ctx.sandboxPolicy.defaultMode`／`ctx.sandboxPolicy.workspaceRoot`：`resolve()` 使用的部署默认值与回退根目录。
+- `sandbox:policy`：直接派生自 `resolve({ session })` 的请求时缓存安全上下文贡献。它说明该模式中与具体能力无关的文件操作约定，以及 `workspace-write` 下规范化的会话工作区；工具归属方仍负责特定于操作的拒绝与升权引导。
+- `effectiveSandboxMode(events)`：会话 `sandbox/mode` 事件的纯 fold（最后一次切换胜出，没有则为 `undefined`），在 `resolve()` 内使用。
+- `setSandboxMode(session, mode)`：逐会话覆盖的唯一写入路径：恰好追加一条 `sandbox/mode` 事件。切换本身就是事件；不会在带外修改模式。
+- `SANDBOX_MODES`：所有模式，用于选项展示与运行时验证。
+
+可选的 `./invariant` 配套组件会拒绝伪造的持久 `sandbox/mode` 事件，只要其值不在该封闭词汇中；Session 与其配套组件负责相关存储与核心执行封闭规则。agent loop（智能体循环）会将组装后的完整运行时上下文快照记录为一条带来源的 `user/message`，因此无需内存中的「上次告知」镜像，也能重建确切的策略输入。
+
+## 逐会话存储
+
+运行时切换是在对应会话日志中追加的一条 `sandbox/mode` 事件。`effective = explicit grant ?? fold(events) ?? deployment default`，因此覆盖会通过回放跨重启保留，两个会话也绝不会看到彼此状态。工作区标识无需另一条事件：创建时记录的不可变 `SessionHeader.cwd` 是该会话每次调用使用的根。该事件仍只进入日志；在下一次请求前，归属方会将当前事实贡献给完整运行时上下文快照。
+
+## 模型体验
+
+### 当前文件沙箱策略
+
+#### 模型看到的内容
+
+每个 agent 会话的当前运行时上下文快照中都有一项 `sandbox:policy` 贡献。它不枚举已装载的能力。工具插件继续负责操作与升权引导，批准策略单独贡献给同一份快照，计划引导仍由 `dsh-plan-mode` 的系统段落管理。
+
+##### 只读
+
+```markdown
+Current DSH file policy: read-only. Any available operation enforced by the DSH file sandbox cannot modify files in the standing mode. Do not refuse a required modification from this policy alone: try an available tool normally and follow any denial and escalation guidance it returns.
+```
+
+##### 工作区写入
+
+```markdown
+Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: "<workspace root>". Some platform temporary areas may also be writable.
+```
+
+##### 完全访问
+
+```markdown
+Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.
+```
+
+#### Token 影响
+
+首次请求和有效策略每次变化时增加一条简洁的持久上下文消息；未变化的请求不增加内容。`workspace-write` 只携带规范化的会话工作区路径；平台特定的临时路径会以摘要表述，不会加入依赖主机的字节。
+
+#### KV Cache 影响
+
+模式切换时，稳定的系统提示词仍逐字节相同。变化后的完整上下文快照会追加到保留的历史之后，从而保留此前已缓存的前缀；后续未变化的请求会复用该保留快照。
+
+## 已知限制与暂缓事项
+
+- **每个会话只有一个主要工作区根目录**：策略解析 `SessionHeader.cwd`；额外可写根目录不属于 `SandboxExecutionPolicy`。
+- **仅限文件操作模式**：`SandboxMode` 管控文件操作；网络和进程策略不在其词汇中，因此这里没有限制它们的旋钮。
+- **有意概述临时区域**：强制执行后端会授予不同的平台临时区域，这些区域在策略解析后才会选定，因此无法在当前上下文中如实枚举。

package/lib/index.js

@@ -0,0 +1,156 @@
+import { resolve } from "node:path";
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { canonicalPath } from "@deepseek-ai/dsh-sandbox";
+//#region lib/types/session-mode.js
+/**
+* Per-session sandbox-mode override: the session log as the store. A runtime
+* switch (a UI policy control or test scenario) is recorded as one
+* `sandbox/mode` event on the session it applies to;
+* `effective = fold(events) ?? the deployment default`, so an override
+* survives restart by replay, two sessions can never see each other's state,
+* and there is no external config store. The event is log-only (the
+* `approval/*` precedent): the policy owner projects the fold into each model
+* request, while enforcing tools report operation-specific boundary markers.
+* EXECUTION honors the same fold through `ctx.sandboxPolicy.resolve()` — it
+* stamps the mode together with the calling session's workspace root onto each
+* capability call, weakest-precedence beneath an escalation grant.
+*
+* The override is policy state shared by every enforcing family (bash and
+* filesystem alike), so it lives here in the policy package rather than in any
+* one capability's seam.
+*
+* @module dsh-sandbox-policy/session-mode
+*/
+/** Every {@link SandboxMode}, for option advertisement and runtime validation of untrusted mode strings. */
+const SANDBOX_MODES = [
+	"read-only",
+	"workspace-write",
+	"danger-full-access"
+];
+/**
+* The session's sandbox-mode override: the last `sandbox/mode` event in the
+* log, or undefined when the session never switched (callers apply the
+* deployment default). The pure fold — resume needs no catch-up machinery
+* because replaying the log IS the state.
+* @param events - session events in log order (other event types are skipped).
+* @returns the mode of the last switch event, or undefined without one.
+*/
+function effectiveSandboxMode(events) {
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const event = events[index];
+		if (event.type === "sandbox/mode") return event.data.mode;
+	}
+}
+/**
+* THE write path for a session's sandbox-mode override: appends exactly one
+* `sandbox/mode` event — the switch IS its event; nothing mutates mode state
+* out of band. Takes effect on the session's next confined call (bash or fs)
+* — the consumers fold on every read.
+* @param session - the session the override belongs to.
+* @param mode - the mode every subsequent confined call in this session runs
+*   under (until the next switch).
+*/
+function setSandboxMode(session, mode) {
+	session.append("sandbox/mode", { mode });
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* The sandbox POLICY home (`ctx.sandboxPolicy`): the single owner of the
+* deployment's sandbox fallbacks plus per-session resolution: the file-effect
+* {@link SandboxMode}, the `workspace-write` root, and the override kit (the
+* `sandbox/mode` event, its fold, and its write path, from `./session-mode.ts`).
+* Before each agent request, the owner also contributes the resolved policy to
+* the cache-safe runtime-context snapshot. The agent loop logs that snapshot as
+* model history, so replay reconstructs the same mode and root the enforcing
+* consumers resolve without rewriting the stable system prompt.
+*
+* Enforcing filesystem, one-shot bash, and terminal backends read the SAME
+* resolved policy here. The context describes that policy without inventorying
+* capabilities, while each backend retains its own enforcement dialect and each
+* tool owns its operation-specific denial and escalation guidance. The service
+* reads session state once at each operation boundary; executors and providers
+* remain session-free.
+*
+* @module @deepseek-ai/dsh-sandbox-policy
+*/
+/** Resolve filesystem identity before lexical normalization can erase symlink-sensitive components. */
+function resolveWorkspaceRoot(path) {
+	return resolve(canonicalPath(path));
+}
+/** Render the policy without claiming which capabilities are mounted. */
+function renderPolicyContext(policy) {
+	switch (policy.mode) {
+		case "read-only": return "Current DSH file policy: read-only. Any available operation enforced by the DSH file sandbox cannot modify files in the standing mode. Do not refuse a required modification from this policy alone: try an available tool normally and follow any denial and escalation guidance it returns.";
+		case "workspace-write": return `Current DSH file policy: workspace-write. Any available operation enforced by the DSH file sandbox may modify files under the session workspace: ${JSON.stringify(policy.workspaceRoot)}. Some platform temporary areas may also be writable.`;
+		case "danger-full-access": return "Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.";
+		/* v8 ignore next 4 -- SandboxMode is a typed same-process closed union; this branch is only the static exhaustiveness guard. */
+		default: {
+			const mode = policy.mode;
+			throw new Error(`unreachable sandbox mode: ${String(mode)}`);
+		}
+	}
+}
+/**
+* The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment
+* default mode, fallback workspace root, and current request-time policy
+* section. Tool layers call {@link resolve} for each execution so a session's
+* mode log and immutable cwd travel together to every enforcing capability.
+*/
+var SandboxPolicyService = class extends Service {
+	static Config = z.object({
+		mode: z.union([
+			"read-only",
+			"workspace-write",
+			"danger-full-access"
+		]).default("read-only"),
+		workspaceRoot: z.string()
+	});
+	/** The deployment default mode — the fallback beneath a session override. */
+	defaultMode;
+	/** The absolute `workspace-write` fallback root for calls without a session cwd. */
+	workspaceRoot;
+	constructor(ctx, config) {
+		super(ctx, "sandboxPolicy");
+		this.defaultMode = config.mode;
+		this.workspaceRoot = resolveWorkspaceRoot(config.workspaceRoot ?? process.cwd());
+		ctx.inject(["systemPrompt"], (scope) => {
+			scope.systemPrompt.context({
+				name: "sandbox:policy",
+				order: 110,
+				text: (context) => {
+					const session = context.agent?.session;
+					return session === void 0 ? "" : renderPolicyContext(this.resolve({ session }));
+				}
+			});
+		});
+	}
+	/**
+	* Resolve the complete policy for one capability call. An approved explicit
+	* mode outranks the session's last `sandbox/mode` event, which outranks the
+	* deployment default. A session cwd is its workspace-write boundary; the
+	* configured root is the fallback for agentless calls and sessions without a
+	* cwd.
+	* @param request - optional session and approved mode override.
+	* @returns the fully resolved per-call mode and absolute workspace root.
+	*/
+	resolve(request = {}) {
+		const { session } = request;
+		return {
+			mode: request.mode ?? (session === void 0 ? void 0 : this.overrideOf(session)) ?? this.defaultMode,
+			workspaceRoot: resolveWorkspaceRoot(session?.header.cwd ?? this.workspaceRoot),
+			...session === void 0 ? {} : { sessionId: session.id }
+		};
+	}
+	/**
+	* Read the session override without applying the deployment default.
+	* @param session - session whose log supplies the override.
+	* @returns the last logged mode, or `undefined` without one.
+	*/
+	overrideOf(session) {
+		return effectiveSandboxMode(session.events);
+	}
+};
+//#endregion
+export { SANDBOX_MODES, SandboxPolicyService, SandboxPolicyService as default, effectiveSandboxMode, setSandboxMode };

package/lib/invariant.js

@@ -0,0 +1,55 @@
+//#region lib/types/session-mode.js
+/**
+* Per-session sandbox-mode override: the session log as the store. A runtime
+* switch (a UI policy control or test scenario) is recorded as one
+* `sandbox/mode` event on the session it applies to;
+* `effective = fold(events) ?? the deployment default`, so an override
+* survives restart by replay, two sessions can never see each other's state,
+* and there is no external config store. The event is log-only (the
+* `approval/*` precedent): the policy owner projects the fold into each model
+* request, while enforcing tools report operation-specific boundary markers.
+* EXECUTION honors the same fold through `ctx.sandboxPolicy.resolve()` — it
+* stamps the mode together with the calling session's workspace root onto each
+* capability call, weakest-precedence beneath an escalation grant.
+*
+* The override is policy state shared by every enforcing family (bash and
+* filesystem alike), so it lives here in the policy package rather than in any
+* one capability's seam.
+*
+* @module dsh-sandbox-policy/session-mode
+*/
+/** Every {@link SandboxMode}, for option advertisement and runtime validation of untrusted mode strings. */
+const SANDBOX_MODES = [
+	"read-only",
+	"workspace-write",
+	"danger-full-access"
+];
+//#endregion
+//#region lib/types/invariant.js
+/** Package-owned session-event invariants for sandbox policy. @module @deepseek-ai/dsh-sandbox-policy/invariant */
+const PACKAGE_NAME = "@deepseek-ai/dsh-sandbox-policy";
+/** Cordis companion plugin name. */
+const name = "sandbox-policy-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** Validate the package-owned event fields and ignore unrelated events. */
+function validateEvent(event, fail) {
+	if (event.type === "sandbox/mode" && !SANDBOX_MODES.includes(event.data.mode)) fail(`sandbox/mode carries unknown mode ${JSON.stringify(event.data.mode)}`);
+}
+/** Install validation for loaded and newly appended sandbox modes. */
+const install = Object.assign((ctx, fail) => {
+	for (const session of ctx.sessions.list()) for (const event of session.events) validateEvent(event, fail);
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "session/event") return;
+		const event = args[1];
+		validateEvent(event, fail);
+	}, { global: true });
+}, { inject: ["sessions"] });
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The sandbox POLICY home (`ctx.sandboxPolicy`): the single owner of the
+ * deployment's sandbox fallbacks plus per-session resolution: the file-effect
+ * {@link SandboxMode}, the `workspace-write` root, and the override kit (the
+ * `sandbox/mode` event, its fold, and its write path, from `./session-mode.ts`).
+ * Before each agent request, the owner also contributes the resolved policy to
+ * the cache-safe runtime-context snapshot. The agent loop logs that snapshot as
+ * model history, so replay reconstructs the same mode and root the enforcing
+ * consumers resolve without rewriting the stable system prompt.
+ *
+ * Enforcing filesystem, one-shot bash, and terminal backends read the SAME
+ * resolved policy here. The context describes that policy without inventorying
+ * capabilities, while each backend retains its own enforcement dialect and each
+ * tool owns its operation-specific denial and escalation guidance. The service
+ * reads session state once at each operation boundary; executors and providers
+ * remain session-free.
+ *
+ * @module @deepseek-ai/dsh-sandbox-policy
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type SandboxExecutionPolicy, type SandboxMode } from '@deepseek-ai/dsh-sandbox';
+import type { Session } from '@deepseek-ai/dsh-session';
+export { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from './session-mode.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        sandboxPolicy: SandboxPolicyService;
+    }
+}
+/**
+ * Plugin config: the deployment's sandbox default. All optional — `Config`
+ * supplies the defaults (`mode: 'read-only'` is the fail-safe default; a
+ * deployment that wants a workspace-writable agent opts in explicitly). The
+ * runner choice is NOT here (it is the `ctx.sandbox` provider's config), nor
+ * is any per-family knob: this is the one shared policy home.
+ */
+export interface Config {
+    /** File-sandbox mode a session starts from (default: `read-only`). */
+    mode?: SandboxMode;
+    /**
+     * Fallback root for agentless calls and sessions without a cwd (default:
+     * `process.cwd()`). Normal agent calls use their session cwd instead.
+     */
+    workspaceRoot?: string;
+}
+/** Inputs that select the sandbox policy for one capability call. */
+export interface SandboxPolicyRequest {
+    /** Calling session; its immutable cwd becomes the workspace boundary. */
+    session?: Session;
+    /** Explicit approved mode override, which outranks session policy. */
+    mode?: SandboxMode;
+}
+/**
+ * The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment
+ * default mode, fallback workspace root, and current request-time policy
+ * section. Tool layers call {@link resolve} for each execution so a session's
+ * mode log and immutable cwd travel together to every enforcing capability.
+ */
+export declare class SandboxPolicyService extends Service {
+    static Config: z<Config>;
+    /** The deployment default mode — the fallback beneath a session override. */
+    readonly defaultMode: SandboxMode;
+    /** The absolute `workspace-write` fallback root for calls without a session cwd. */
+    readonly workspaceRoot: string;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Resolve the complete policy for one capability call. An approved explicit
+     * mode outranks the session's last `sandbox/mode` event, which outranks the
+     * deployment default. A session cwd is its workspace-write boundary; the
+     * configured root is the fallback for agentless calls and sessions without a
+     * cwd.
+     * @param request - optional session and approved mode override.
+     * @returns the fully resolved per-call mode and absolute workspace root.
+     */
+    resolve(request?: SandboxPolicyRequest): SandboxExecutionPolicy;
+    /**
+     * Read the session override without applying the deployment default.
+     * @param session - session whose log supplies the override.
+     * @returns the last logged mode, or `undefined` without one.
+     */
+    overrideOf(session: Session): SandboxMode | undefined;
+}
+export default SandboxPolicyService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned session-event invariants for sandbox policy. @module @deepseek-ai/dsh-sandbox-policy/invariant */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "sandbox-policy-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/session-mode.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Per-session sandbox-mode override: the session log as the store. A runtime
+ * switch (a UI policy control or test scenario) is recorded as one
+ * `sandbox/mode` event on the session it applies to;
+ * `effective = fold(events) ?? the deployment default`, so an override
+ * survives restart by replay, two sessions can never see each other's state,
+ * and there is no external config store. The event is log-only (the
+ * `approval/*` precedent): the policy owner projects the fold into each model
+ * request, while enforcing tools report operation-specific boundary markers.
+ * EXECUTION honors the same fold through `ctx.sandboxPolicy.resolve()` — it
+ * stamps the mode together with the calling session's workspace root onto each
+ * capability call, weakest-precedence beneath an escalation grant.
+ *
+ * The override is policy state shared by every enforcing family (bash and
+ * filesystem alike), so it lives here in the policy package rather than in any
+ * one capability's seam.
+ *
+ * @module dsh-sandbox-policy/session-mode
+ */
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * The session's sandbox mode was switched — log-only (like `approval/*`;
+         * NOT a surface event, carries no `surfaceOp`): durable and replayable,
+         * never in the model transcript. The LAST such event is the session's
+         * override ({@link effectiveSandboxMode}). `source: 'delegation'` marks
+         * an override seeded into a child; an absent source is a runtime switch.
+         */
+        'sandbox/mode': {
+            mode: SandboxMode;
+            /** Marks an override seeded into a child at delegation. */
+            source?: 'delegation';
+        };
+    }
+}
+/** Every {@link SandboxMode}, for option advertisement and runtime validation of untrusted mode strings. */
+export declare const SANDBOX_MODES: readonly SandboxMode[];
+/**
+ * The session's sandbox-mode override: the last `sandbox/mode` event in the
+ * log, or undefined when the session never switched (callers apply the
+ * deployment default). The pure fold — resume needs no catch-up machinery
+ * because replaying the log IS the state.
+ * @param events - session events in log order (other event types are skipped).
+ * @returns the mode of the last switch event, or undefined without one.
+ */
+export declare function effectiveSandboxMode(events: readonly SessionEvent[]): SandboxMode | undefined;
+/**
+ * THE write path for a session's sandbox-mode override: appends exactly one
+ * `sandbox/mode` event — the switch IS its event; nothing mutates mode state
+ * out of band. Takes effect on the session's next confined call (bash or fs)
+ * — the consumers fold on every read.
+ * @param session - the session the override belongs to.
+ * @param mode - the mode every subsequent confined call in this session runs
+ *   under (until the next switch).
+ */
+export declare function setSandboxMode(session: Session, mode: SandboxMode): void;
+//# sourceMappingURL=session-mode.d.ts.map

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@deepseek-ai/dsh-sandbox-policy",
+  "description": "Per-call sandbox policy resolver and current model context: deployment fallbacks plus each session's mode and workspace root, shared by every enforcing capability family",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/sandbox/sandbox-policy"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-sandbox": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}