@qilin-agent/sandbox-policy 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,79 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/sandbox/sandbox-policy/README.md
+/:
+  en: abf71058974a6f37
+  zh: 45c76c1d645a0e67
+/qilin-sandbox-policy:
+  en: 983c2e8c93e8513a
+  zh: 4c1e0b559820f60c
+/qilin-sandbox-policy/summary:
+  en: 62e1a0a017d6bc07
+  zh: 1d9f86eb54f51b8e
+/qilin-sandbox-policy/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-sandbox-policy/use-this-package:
+  en: a75f214ba848bbd1
+  zh: 8ad35e2513b53bd1
+/qilin-sandbox-policy/use-this-package/when-to-choose-it:
+  en: 6704447e52ec295b
+  zh: 9ed812d9e29d5533
+/qilin-sandbox-policy/use-this-package/minimal-configuration:
+  en: 855079a846f9316b
+  zh: 6ff918f505f09f73
+/qilin-sandbox-policy/use-this-package/switching-a-session-s-mode:
+  en: 957d72691e470e5c
+  zh: c22a3a750af0e4a3
+/qilin-sandbox-policy/use-this-package/failures-and-recovery:
+  en: 9cef5f64a050f468
+  zh: 5dc42c148b2c902d
+/qilin-sandbox-policy/understand-the-implementation:
+  en: 2d560aa6681fcfb8
+  zh: e1c6361a6fa40c63
+/qilin-sandbox-policy/understand-the-implementation/resolution-precedence:
+  en: f1f38b10c23947d2
+  zh: 7a591e743d6793f5
+/qilin-sandbox-policy/understand-the-implementation/the-per-session-store:
+  en: d13dabff02f2acfd
+  zh: f593888b4ffddf36
+/qilin-sandbox-policy/understand-the-implementation/model-visible-text:
+  en: 38f9f9bf72d461b2
+  zh: ac0aa6889e14aea0
+/qilin-sandbox-policy/understand-the-implementation/source-map:
+  en: cc7dd675c9915f7d
+  zh: d719c4f9de39873a
+/qilin-sandbox-policy/further-exploration:
+  en: e00314ec4e49f003
+  zh: 0285b8448cdf6bf1
+/qilin-sandbox-policy/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-sandbox-policy/model-experience/current-file-sandbox-policy:
+  en: 593b59dbbb02bc8c
+  zh: 38fa746346e9bc06
+/qilin-sandbox-policy/model-experience/current-file-sandbox-policy/what-the-model-sees:
+  en: 37d30c86d074bb17
+  zh: 428399379be74def
+/qilin-sandbox-policy/model-experience/current-file-sandbox-policy/what-the-model-sees/read-only:
+  en: 36f15579c9444eb9
+  zh: 289f3c4ce040bfe9
+/qilin-sandbox-policy/model-experience/current-file-sandbox-policy/what-the-model-sees/workspace-write:
+  en: 269d494ad304638d
+  zh: a879c1d7cc03e6ac
+/qilin-sandbox-policy/model-experience/current-file-sandbox-policy/what-the-model-sees/danger-full-access:
+  en: 4e28324a011422a1
+  zh: bf31ffce30f06a09
+/qilin-sandbox-policy/model-experience/current-file-sandbox-policy/token-effect:
+  en: e3387fb6eeba1239
+  zh: 06a47393057d3e9b
+/qilin-sandbox-policy/model-experience/current-file-sandbox-policy/kv-cache-effect:
+  en: a16a657e0e5145fb
+  zh: 4b19263a728990dc
+/qilin-sandbox-policy/known-limitations-and-deferred-work:
+  en: af363d6626eaa9b8
+  zh: 93f8d5f9519db0ae
+/qilin-sandbox-policy/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+---
+description: "The shared per-call sandbox policy resolver and current model context for users and maintainers composing, configuring, or debugging file-effect policy across enforcing capabilities."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/sandbox-policy
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use this package to apply one file-effect policy to every confined bash, filesystem, and terminal call. Deployments choose a default mode and fallback workspace root, while each session can switch modes independently. Session choices survive restart, and all enforcing capabilities use the same mode and workspace for a call. Before each model request, the model receives the effective policy and workspace without an inventory of mounted capabilities.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount this package in any composition where sandbox-enforcing capabilities run: it owns the deployment default and the per-session overrides those capabilities consume, and it contributes the current policy to the model's runtime-context snapshot.
+
+### When to choose it
+
+Choose it for every composition with confined capabilities (bash, filesystem, terminal) so one policy home keeps them from drifting into different modes or workspace roots. Skip it only when nothing enforces sandbox policy — with no consumers, the resolved policy has no effect.
+
+### Minimal configuration
+
+Load the package with a default mode; the fail-safe default is `read-only`, and a deployment that wants a workspace-writable agent opts into `workspace-write` explicitly.
+
+```yaml
+- name: '@qilin-agent/sandbox-policy'
+  config:
+    mode: workspace-write
+    workspaceRoot: /absolute/path/to/workspace
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `mode` | `read-only` | The deployment default mode a session starts from, validated at load |
+| `workspaceRoot` | `process.cwd()` | Absolute fallback root for agentless calls or sessions without a cwd; relative values fail at load. Normal agent calls use the session's immutable cwd |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#qilin-agentsandbox-policy) is the exhaustive source for every accepted field and its JSDoc.
+
+### Switching a session's mode
+
+A session's mode can be switched at runtime through a UI policy control or an explicit switch; the switch is recorded in the session log and takes effect on the session's next confined call. The switch survives restart through replay, and each session keeps its own mode — two sessions never see each other's state. A switched session keeps its immutable workspace cwd as the writable boundary.
+
+### Failures and recovery
+
+An invalid configured mode is rejected when the plugin loads, so a typo fails loud instead of silently changing policy. A session without a cwd, and agentless calls, fall back to the configured workspace root; a call with an approved explicit mode uses that mode for exactly that call.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains policy resolution, the per-session store, and the model-visible contribution; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Resolution precedence
+
+`resolve({ session, mode })` returns one complete per-call policy: an approved explicit mode outranks the session's last `sandbox/mode` event, which outranks the deployment default. The session's immutable `cwd` supplies the workspace root; otherwise the configured fallback applies. Absolute execution-world spelling is preserved. Enforcing providers canonicalize the root on their own filesystem, so remote `symlink/..` paths are never resolved on the Harness host.
+
+### The per-session store
+
+A runtime switch is one log-only `sandbox/mode` event on the session it applies to — the switch IS its event, and nothing mutates mode state out of band. `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 needs no event: the immutable `SessionHeader.cwd` recorded at creation is the root for every call in that session. The event stays log-only; before each request, the owner contributes the current fact to the full runtime-context snapshot, and the agent loop logs that snapshot as a sourced `user/message`.
+
+### Model-visible text
+
+The `sandbox:policy` contribution states the mode's capability-neutral file-effect contract and the recorded session workspace under `workspace-write`. It does not enumerate mounted capabilities; tool plugins retain operation-specific denial and escalation guidance, approval policy contributes separately to the same snapshot, and plan guidance remains `qilin-plan-mode`'s system section.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `SandboxPolicyService`, `Config` schema, policy resolution and context contribution |
+| [`src/session-mode.ts`](src/session-mode.ts) | The `sandbox/mode` event, its fold, and the write path |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Start with the subsystem reference for the shared vocabulary, then the seam contract and the cross-family decision.
+
+- [Process sandbox subsystem](../../../docs/subsystems/sandbox.md) — modes, per-call policy, and enforcement semantics.
+- [Sandbox seam package](../sandbox/README.md) — the confinement contract every enforcing capability implements.
+- [Cross-family file sandbox decision](../../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md) — why one shared policy home exists.
+
+-----
+
+<a id="model-experience"></a>
+## 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 `qilin-plan-mode`'s system section.
+
+##### Read-only
+
+```markdown
+Current QILIN file policy: read-only. Any available operation enforced by the QILIN 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 QILIN file policy: workspace-write. Any available operation enforced by the QILIN file sandbox may modify files under the session workspace: "<workspace root>". Some platform temporary areas may also be writable.
+```
+
+##### Danger-full-access
+
+```markdown
+Current QILIN file policy: danger-full-access. The QILIN 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 recorded 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
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define the policy surface this package provides. They are current package constraints, not a general sandbox comparison or a task backlog.
+
+- **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.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,158 @@
+---
+description: "面向需要在各项负责强制执行的能力之间组合、配置或排查文件操作策略的用户与维护者，提供共享的逐调用沙箱策略解析器与当前模型上下文。"
+kind: "package-reference"
+---
+
+# @qilin-agent/sandbox-policy
+
+[English](README.md) | 中文
+
+## 概述
+
+使用本包可以让每次受限的 bash、文件系统和终端调用遵循同一份文件操作策略。部署方选择默认模式和回退工作区根目录，每个会话则可以独立切换模式。会话选择可跨重启保留，所有强制执行能力在一次调用中使用相同的模式和工作区。每次模型请求前，模型都会收到有效策略和工作区说明，但不会收到已挂载能力的清单。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在任何运行沙箱强制执行能力的组合中挂载此包：它拥有这些能力消费的部署默认值与逐会话覆盖，并把当前策略贡献给模型的运行时上下文快照。
+
+### 何时选择
+
+为每个带受限能力（bash、文件系统、终端）的组合选择它，让单一策略归属位置防止它们漂移到不同的模式或工作区根目录。只有没有任何沙箱策略强制执行时才跳过它——没有消费方时，解析出的策略不起作用。
+
+### 最小配置
+
+用默认模式加载本包；故障安全默认值是 `read-only`，需要 agent（智能体）可写入工作区的部署必须显式选择 `workspace-write`。
+
+```yaml
+- name: '@qilin-agent/sandbox-policy'
+  config:
+    mode: workspace-write
+    workspaceRoot: /absolute/path/to/workspace
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `mode` | `read-only` | 会话起始的部署默认模式，加载时验证 |
+| `workspaceRoot` | `process.cwd()` | 无 agent 调用或没有 cwd 的会话所用的绝对回退根目录；相对值在加载时拒绝。普通 agent 调用使用会话的不可变 cwd |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#qilin-agentsandbox-policy)是每个受支持字段及其 JSDoc 的穷尽式真源。
+
+### 切换会话模式
+
+会话的模式可以在运行时通过 UI 策略控件或显式切换来更改；切换记录在会话日志中，并在该会话的下一次受限调用时生效。切换通过回放跨重启保留，每个会话保持自己的模式——两个会话绝不会看到彼此状态。切换后的会话继续以不可变的工作区 cwd 作为写入边界。
+
+### 失败与恢复
+
+无效的配置模式会在插件加载时被拒绝，因此拼写错误会导致显式报错，而不是静默改变策略。没有 cwd 的会话与无 agent 调用回退到配置的工作区根目录；带已批准显式模式的调用只在该次调用中使用该模式。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释策略解析、逐会话存储与模型可见贡献；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 解析优先级
+
+`resolve({ session, mode })` 返回一份完整的逐调用策略：已批准的显式模式优先于会话最后一条 `sandbox/mode` 事件，后者又优先于部署默认值。会话的不可变 `cwd` 提供工作区根目录；否则使用配置的回退值。执行环境中的绝对路径写法保持不变。执行限制的提供方在自己的文件系统上规范化根目录，因此远端 `symlink/..` 路径绝不会在 Harness 主机上解析。
+
+### 逐会话存储
+
+运行时切换是在对应会话日志中追加的一条仅写入日志的 `sandbox/mode` 事件——切换本身就是事件，任何机制都不会在带外修改模式状态。`effective = explicit grant ?? fold(events) ?? deployment default`，因此覆盖通过回放跨重启保留，两个会话也绝不会看到彼此状态。工作区标识无需事件：创建时记录的不可变 `SessionHeader.cwd` 是该会话每次调用使用的根。事件仍只进入日志；在每次请求前，归属方会把当前事实贡献给完整运行时上下文快照，agent loop（智能体循环）将该快照记录为一条带来源的 `user/message`。
+
+### 模型可见文本
+
+`sandbox:policy` 贡献说明该模式与具体能力无关的文件操作约定，以及 `workspace-write` 下已记录的会话工作区。它不枚举已挂载能力；工具插件保留特定于操作的拒绝与升权引导，批准策略单独贡献给同一份快照，计划引导仍由 `qilin-plan-mode` 的系统段落管理。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：`SandboxPolicyService`、`Config` schema、策略解析与上下文贡献 |
+| [`src/session-mode.ts`](src/session-mode.ts) | `sandbox/mode` 事件、其 fold 与写入路径 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+先从子系统参考文档了解共享词汇，再看 seam 约定与跨家族决策。
+
+- [进程沙箱子系统](../../../docs/subsystems/sandbox.zh.md)——模式、逐调用策略与强制执行语义。
+- [沙箱 seam 包](../sandbox/README.zh.md)——每个强制执行能力实现的隔离约定。
+- [跨家族文件沙箱决策](../../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md)——为何存在统一的共享策略归属位置。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 当前文件沙箱策略
+
+#### 模型看到什么
+
+每个 agent 会话的当前运行时上下文快照中都有一项 `sandbox:policy` 贡献。它不枚举已挂载的能力。工具插件继续负责操作与升权引导，批准策略单独贡献给同一份快照，计划引导仍由 `qilin-plan-mode` 的系统段落管理。
+
+##### 只读
+
+```markdown
+Current QILIN file policy: read-only. Any available operation enforced by the QILIN 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 QILIN file policy: workspace-write. Any available operation enforced by the QILIN file sandbox may modify files under the session workspace: "<workspace root>". Some platform temporary areas may also be writable.
+```
+
+##### 完全访问
+
+```markdown
+Current QILIN file policy: danger-full-access. The QILIN file sandbox does not restrict file modifications by available operations.
+```
+
+#### Token 影响
+
+首次请求和有效策略每次变化时增加一条简洁的持久上下文消息；未变化的请求不增加内容。`workspace-write` 只携带已记录的会话工作区路径；平台特定的临时路径会以摘要表述，不会加入依赖主机的字节。
+
+#### KV Cache 影响
+
+模式切换时，稳定的系统提示词仍逐字节相同。变化后的完整上下文快照会追加到保留的历史之后，从而保留此前已缓存的前缀；后续未变化的请求会复用该保留快照。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制界定了本包提供的策略范围。它们是当前的包级约束，并非通用沙箱对比，也不是待办事项清单。
+
+- **每个会话只有一个主要工作区根目录**——策略解析 `SessionHeader.cwd`；额外可写根目录不属于 `SandboxExecutionPolicy`。
+- **仅限文件操作模式**——`SandboxMode` 管控文件操作；网络和进程策略不在其词汇中，因此这里没有限制它们的旋钮。
+- **有意概述临时区域**——强制执行后端会授予不同的平台临时区域，这些区域在策略解析后才会选定，因此无法在当前上下文中如实枚举。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,159 @@
+import { isAbsolute } from "node:path";
+import { Service } from "@qilin-agent/kylin";
+import { z } from "zod";
+import z$1 from "@qilin-agent/schemastery";
+//#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 = projection state ?? 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 qilin-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 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)
+* — consumers read the shared projection state.
+* @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; the fold is the
+* `sandboxMode` session-projection unit registered here, while the event and
+* write path come 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 @qilin-agent/sandbox-policy
+*/
+/** Preserve execution-world spelling; enforcing providers resolve filesystem identity on their host. */
+function resolveWorkspaceRoot(path) {
+	if (!isAbsolute(path)) throw new Error("sandbox-policy: workspace root must be an absolute execution-world path");
+	return path;
+}
+/** Render the policy without claiming which capabilities are mounted. */
+function renderPolicyContext(policy) {
+	switch (policy.mode) {
+		case "read-only": return "Current QILIN file policy: read-only. Any available operation enforced by the QILIN 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 QILIN file policy: workspace-write. Any available operation enforced by the QILIN 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 QILIN file policy: danger-full-access. The QILIN 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-mode projection's state schema (state equals the public shape). */
+const sandboxModeStateSchema = z.union([
+	z.literal("read-only"),
+	z.literal("workspace-write"),
+	z.literal("danger-full-access")
+]).nullable();
+/**
+* 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$1.object({
+		mode: z$1.union([
+			"read-only",
+			"workspace-write",
+			"danger-full-access"
+		]).default("read-only"),
+		workspaceRoot: z$1.string()
+	});
+	static inject = ["sessionProjections"];
+	/** 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.sessionProjections.register({
+			key: "sandboxMode",
+			stateVersion: 1,
+			stateSchema: sandboxModeStateSchema,
+			init: () => null,
+			apply: (state, event) => event.type === "sandbox/mode" ? event.data.mode : state
+		});
+		ctx.inject(["systemPrompt"], (scope) => {
+			scope.systemPrompt.context({
+				name: "sandbox:policy",
+				order: scope.systemPrompt.getContextOrder("SANDBOX_POLICY"),
+				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 this.ctx.sessionProjections.stateOf(session, "sandboxMode") ?? void 0;
+	}
+};
+//#endregion
+export { SANDBOX_MODES, SandboxPolicyService, SandboxPolicyService as default, setSandboxMode };

package/lib/types/index.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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; the fold is the
+ * `sandboxMode` session-projection unit registered here, while the event and
+ * write path come 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 @qilin-agent/sandbox-policy
+ */
+import { Context, Service } from '@qilin-agent/kylin';
+import { z as zod } from 'zod';
+import z from '@qilin-agent/schemastery';
+import type { SandboxExecutionPolicy, SandboxMode } from '@qilin-agent/sandbox';
+import type { Session } from '@qilin-agent/session';
+export { SANDBOX_MODES, setSandboxMode } from './session-mode.ts';
+declare module '@qilin-agent/kylin' {
+    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;
+    /**
+     * Absolute 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-mode projection's state schema (state equals the public shape). */
+declare const sandboxModeStateSchema: zod.ZodNullable<zod.ZodUnion<readonly [zod.ZodLiteral<"read-only">, zod.ZodLiteral<"workspace-write">, zod.ZodLiteral<"danger-full-access">]>>;
+type SandboxModeState = zod.infer<typeof sandboxModeStateSchema>;
+declare module '@qilin-agent/session-projection/types' {
+    interface SessionProjectionStateMap {
+        /** Last logged sandbox-mode override, or null before one (deployment default applies at resolve time). */
+        sandboxMode: SandboxModeState;
+    }
+}
+/**
+ * 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>;
+    static inject: string[];
+    /** 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/session-mode.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 = projection state ?? 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 qilin-sandbox-policy/session-mode
+ */
+import type { Session } from '@qilin-agent/session';
+import type { SandboxMode } from '@qilin-agent/sandbox';
+declare module '@qilin-agent/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 (folded by the sandboxMode projection unit). `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 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)
+ * — consumers read the shared projection state.
+ * @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

@@ -1,6 +1,52 @@
 {
   "name": "@qilin-agent/sandbox-policy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/sandbox/sandbox-policy"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/sandbox": "3.1.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/system-prompt": "3.1.3",
+    "@qilin-agent/agent": "3.1.3",
+    "@qilin-agent/session-projection": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@qilin-agent/schemastery": "~3.18.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/agent": "3.1.3",
+    "@qilin-agent/system-prompt": "3.1.3",
+    "@qilin-agent/sandbox": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/session-projection": "3.1.3"
+  }
 }