@qilin-agent/sandbox 0.0.0-stage → 3.1.4

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,91 @@
+# 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/README.md
+/:
+  en: 4308065a46738364
+  zh: 2eb6ab7314e74976
+/qilin-agent-sandbox:
+  en: a203105ca8ba756f
+  zh: 28f938291d652856
+/qilin-agent-sandbox/summary:
+  en: 3145aff8aac31187
+  zh: c1b6c1f8dc3f93c1
+/qilin-agent-sandbox/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-agent-sandbox/use-this-package:
+  en: 5fbf0b48effb1143
+  zh: 5c570dcc1a17e0ad
+/qilin-agent-sandbox/use-this-package/when-to-choose-it:
+  en: 4ddc504d2626fe3e
+  zh: ceb3dd93fb3835db
+/qilin-agent-sandbox/use-this-package/confining-a-command:
+  en: c5540889017b6a7f
+  zh: 679bfbd5254bf92d
+/qilin-agent-sandbox/use-this-package/modes-and-enforcement:
+  en: ab093e9042b86b99
+  zh: d173df7cb3649446
+/qilin-agent-sandbox/use-this-package/denied-calls-and-escalation:
+  en: ff24616d2a68ff77
+  zh: 49cb99b3d941dab1
+/qilin-agent-sandbox/use-this-package/fail-closed-behavior:
+  en: 6bf240632a7a6bf5
+  zh: ebf414f5cf435875
+/qilin-agent-sandbox/understand-the-implementation:
+  en: 7e13d669ecc96d59
+  zh: b5fe7ae65812d926
+/qilin-agent-sandbox/understand-the-implementation/design-philosophy:
+  en: 0fc96495c192b513
+  zh: 38b51b9b3c208012
+/qilin-agent-sandbox/understand-the-implementation/source-map:
+  en: f58b67217cbc147a
+  zh: b2cbde0342f3f8aa
+/qilin-agent-sandbox/understand-the-implementation/escalation-choreography:
+  en: 1b418d41f571ab3d
+  zh: 62b289cdd6f4d272
+/qilin-agent-sandbox/understand-the-implementation/writable-roots:
+  en: 956d3195cf7a35f8
+  zh: f83d8342e22bb7cd
+/qilin-agent-sandbox/further-exploration:
+  en: d32c98d7d2b8d6b2
+  zh: da0decd6d48b9069
+/qilin-agent-sandbox/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-agent-sandbox/model-experience/confinement-error-indirectly:
+  en: 35e1ea00601f4003
+  zh: 08152430b840ea05
+/qilin-agent-sandbox/model-experience/confinement-error-indirectly/what-the-model-sees:
+  en: 42d3edf30f9d2f52
+  zh: 13ab629a0902581c
+/qilin-agent-sandbox/model-experience/confinement-error-indirectly/what-the-model-sees/exact-error:
+  en: e8b03df128b832a6
+  zh: dc89500c436a39cf
+/qilin-agent-sandbox/model-experience/confinement-error-indirectly/token-effect:
+  en: 8f514efe94edfa8a
+  zh: a46f9f4cd4527f4e
+/qilin-agent-sandbox/model-experience/confinement-error-indirectly/kv-cache-effect:
+  en: 2fbf2175168e8244
+  zh: f681f89596f500f5
+/qilin-agent-sandbox/model-experience/escalation-request-and-outcome:
+  en: 67c621ef55ec8320
+  zh: ae4bb9162a49e9fb
+/qilin-agent-sandbox/model-experience/escalation-request-and-outcome/what-the-model-sees:
+  en: c20128fa8f79c491
+  zh: 96173408d176b9e6
+/qilin-agent-sandbox/model-experience/escalation-request-and-outcome/token-effect:
+  en: 1a7b54d68b045beb
+  zh: 5dc6e824110c8fd8
+/qilin-agent-sandbox/model-experience/escalation-request-and-outcome/kv-cache-effect:
+  en: ea21ed3a768ed4b8
+  zh: 8e2f396a6875420e
+/qilin-agent-sandbox/known-limitations-and-deferred-work:
+  en: 3b0b864cc3a91b26
+  zh: 43f73818d1d2c7e2
+/qilin-agent-sandbox/known-limitations-and-deferred-work/dev-note:
+  en: cc273320f6a1beaf
+  zh: 5c57a312ddc50651
+/qilin-agent-sandbox/known-limitations-and-deferred-work/dev-note/future-consumers-and-environments:
+  en: 9217a1563d34029c
+  zh: 5812ebd9ef7d4f23

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+---
+description: "The process-sandbox service contract for users and maintainers composing, using, or extending same-world subprocess confinement."
+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
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `qilin-sandbox` to run a subprocess and everything it spawns under a per-call file-access policy. A command can run without writes (`read-only`), write only inside its workspace (`workspace-write`), or run unrestricted (`danger-full-access`). If the requested mode cannot be enforced, the call fails with `SANDBOX_UNAVAILABLE` instead of running unconfined. After a denied call, the model can request one strictly wider mode for human approval. This is same-world confinement: the process still shares the host kernel and filesystem; use a container, microVM, or remote executor when the whole environment must be isolated.
+
+## 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
+
+Compose this service with one backend and a confined consumer, and every command the consumer runs executes under the policy you resolve — you see only the confinement result and its enforcement completeness, never the platform runner.
+
+### When to choose it
+
+Choose this package when a composition confines subprocesses on the host: it is the contract the local backends and the confined executors both implement, so mounting `sandbox-local` behind `ctx.sandbox` and a confined executor behind `ctx.shell` gives every bash or pwsh call a confined default. Choose something else when the process must run in an isolated environment — a container, microVM, or remote executor replaces the whole `ctx.shell`/`ctx.fs` capability rather than adding a backend here.
+
+### Confining a command
+
+Mount the service with a backend and a confined executor; the [base bundle](../../bundle/base/cordis.patch.yml) owns the shipped composition.
+
+```yaml
+- id: sandbox
+  name: '@qilin-agent/sandbox-local'     # the per-platform backend provider (ctx.sandbox)
+- id: sandbox-policy
+  name: '@qilin-agent/sandbox-policy'    # the deployment default mode and workspace-write root
+  config:
+    mode: workspace-write                    # the deployment default every session starts from
+    workspaceRoot: !!js process.cwd()        # the boundary workspace-write may write under
+- id: bash
+  name: '@qilin-agent/bash-sandbox'      # the confined executor behind ctx.shell
+```
+
+With this composition, a bash call runs confined under `workspace-write`: writes inside the workspace succeed, writes outside it are denied, and the model can recover through the escalation flow below.
+
+### Modes and enforcement
+
+The mode names the file effects a command may perform; enforcement completeness reports how fully the backend governs them.
+
+| Mode | Effect |
+|---|---|
+| `read-only` | Denies writes except required sinks such as `/dev/null` |
+| `workspace-write` | Allows writes under the workspace root plus a backend-defined temp area |
+| `danger-full-access` | Bypasses confinement; the consumer spawns its original argv |
+
+Enforcement is reported per call: `full` means the backend governs every promised file effect, while `partial` means an active backend or older kernel ABI governs only a subset — the Windows ACL rung and older Landlock ABIs are the current partial cases, so a consumer that requires the absolute boundary can reject or surface them.
+
+### Denied calls and escalation
+
+When a confined call is denied, the operation reports a denial marker naming the mode — `[sandbox: file access denied under <mode> mode]` — and, when the composition advertises escalation, an escalation hint. The model may retry the exact call once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a `justification`; the user sees one approval prompt and can allow once, reject, or cancel. A wider mode requires approval and applies to that one call only. Repeating the call's effective mode succeeds without approval; narrower targets remain invalid.
+
+### Fail-closed behavior
+
+When no backend can enforce the requested mode, the call fails with `SANDBOX_UNAVAILABLE` rather than running unconfined; the error text names the missing platform runner. A backend that fails after starting also reports a structured runner-failure signature, so a broken sandbox is distinguishable from a command failure.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the contract and points at the code that realizes them; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+- **One execution world.** The filesystem, subprocess and sandbox providers operate on the same filesystem and kernel. Remote compositions replace all three providers; confinement resolves asynchronously in that world.
+- **Policy rides the call.** `SandboxPolicy` is carried per call, never fixed on the provider: two consumers may confine under different policies at the same instant, and an escalated retry is a new call with a wider policy. Defaulting and resolution are explicit consumer steps.
+- **Fail closed.** `confine()` resolves to enforcing argv or rejects with `SandboxUnavailableError`; silent unconfined passthrough is forbidden, and functional probes arbitrate multi-runner chains.
+- **One vocabulary for denial and escalation.** The marker and hint texts and the strictly-wider ladder live here so the bash and fs families cannot drift apart.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `SandboxProvider` service, mode/enforcement/policy types, fail-closed error |
+| [`src/escalation.ts`](src/escalation.ts) | Escalation vocabulary: wider-mode ladder, argument validation, denial and hint markers, approval choreography |
+| [`src/roots.ts`](src/roots.ts) | Writable-root derivation shared by the Seatbelt profile and the in-process fs fence |
+
+### Escalation choreography
+
+The ladder is a closed table — `read-only` may escalate to `workspace-write` or `danger-full-access`, `workspace-write` only to `danger-full-access` — checked at execution, never baked into a tool schema, whose enum stays the closed target vocabulary. [`approveEscalation`](src/escalation.ts) returns the current mode without approval when it is repeated, rejects narrower or unsupported targets, and requests approval for wider modes. Callers validate the `sandbox_permissions`/`justification` pairing first.
+
+### Writable roots
+
+`workspace-write` means "the workspace root plus the host temp areas": `writableRoots` derives that allow-list canonically, resolving symlinks and deduplicating, so the Seatbelt profile and the in-process fs fence grant exactly the same roots.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Start with the subsystem reference for the exhaustive contract, then the backends, consumers, and policy source that realize it.
+
+- [Process sandbox subsystem](../../../docs/subsystems/sandbox.md) — the complete vocabulary, per-call policy, and classification dialects.
+- [The subprocess sandbox decision](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) — capability boundary, escalation design, and deferred phases.
+- [Local sandbox backends](../sandbox-local/README.md) — the per-platform runners behind `ctx.sandbox`.
+- [Bash sandbox executor](../../shell/bash-sandbox/README.md) — the confined bash consumer.
+- [Sandbox policy package](../sandbox-policy/README.md) — where the per-call mode and workspace root come from.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Confinement error, indirectly
+
+#### What the model sees
+
+Through [`qilin-bash-sandbox`](../../shell/bash-sandbox/README.md) and [`qilin-tool-bash`](../../shell/tool-bash/README.md), a requested confined mode with no usable backend produces code `SANDBOX_UNAVAILABLE` and the exact error below; an execution-time runner failure appends ` Runner failure: <detail>`.
+
+##### Exact error
+
+```markdown
+sandbox mode "<mode>" is requested but no sandbox backend is usable on this host; refusing to run the command unconfined. Install bubblewrap or run a Landlock-enforcing kernel (Linux), ensure sandbox-exec is usable (macOS), or ensure the ACL restricted-token runner can start (Windows) — otherwise switch the consumer to danger-full-access.
+```
+
+#### Token effect
+
+Conditional error text is visible for that call and retained in history until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV Cache entries.
+
+### Escalation request and outcome
+
+#### What the model sees
+
+A denied call surfaces the marker `[sandbox: file access denied under <mode> mode]` and, where the composition advertises escalation, the hint `[sandbox: escalation available — retry this exact <subject> once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`. The retry carries `sandbox_permissions` and a `justification`; the user's `allowed-once` / `rejected` / `cancelled` decision becomes the call's result text.
+
+#### Token effect
+
+Only the denied call's error and any escalation outcome text are visible; both are retained in history until compaction.
+
+#### KV Cache effect
+
+Append-only; escalation text follows the retained prefix and does not invalidate cached entries.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the seam is a poor fit or needs special operational care. They are current package constraints, not a general sandbox comparison or a task backlog.
+
+- **File effects are the whole policy vocabulary** — the seam expresses no network, process, syscall, device, or credential restrictions.
+- **Same-world confinement only** — containers, microVMs, and remote execution require replacing capability implementations rather than adding a provider here.
+- **Denial reporting is a stderr dialect** — the seam returns backend signatures instead of a typed runtime denial channel, so consumers that need classification infer it from the child process's output.
+- **Runner diagnostics are in-band** — exit status plus stderr evidence cannot prove which process wrote a matching line, so a confined child that deliberately mimics its runner can cause a false availability or diagnostic attribution; this cannot bypass confinement, and an out-of-band runner-status channel is deferred.
+- **One provider per context** — composing different sandbox mechanisms simultaneously requires a provider-level ladder or separate Kylin contexts; callers choose policy per call, not backend identity.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: undecided directions and open questions. It is explicitly non-authoritative — shipped behavior, limits, and accepted rationale live in the sections above, the package code, and the linked Agent Notes.
+
+#### Future: consumers and environments
+
+The [sandbox decision](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) lists deferred phases — an optional `subagent-acp` consumer that confines child agents (unconfined default) and environment-coherent capability group examples. Neither is decided; the Windows chain that note listed as deferred has since shipped through the ACL restricted-token rung of `sandbox-local`.
+
+</details>

package/README.zh.md

@@ -0,0 +1,184 @@
+---
+description: "面向用户与维护者的进程沙箱服务约定，用于组合、使用或扩展与宿主共享文件系统和内核的子进程限制机制。"
+kind: "package-reference"
+---
+
+# @qilin-agent/sandbox
+
+[English](README.md) | 中文
+
+## 概述
+
+使用 `qilin-sandbox`，可以让子进程及其派生的所有进程在逐调用文件访问策略下运行。命令可以禁止写入（`read-only`）、只写入工作区（`workspace-write`），或不受限制地运行（`danger-full-access`）。无法强制执行所请求的模式时，调用以 `SANDBOX_UNAVAILABLE` 失败，绝不会不受限制地运行。调用被拒绝后，模型可以请求一个严格更宽的模式，交由人类批准一次。这种限制只适用于与宿主共享内核和文件系统的进程；需要隔离整个环境时，请使用容器、microVM 或远程执行器。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+将此服务与一个后端和一个受限消费方组合，消费方运行的每条命令都会在你解析的策略下执行——你只看到隔离结果及其强制执行完整度，永远看不到 runner。
+
+### 何时选择
+
+当组合需要在宿主机上隔离子进程时选择本包：本地后端与受限执行器都实现这个约定，因此在 `ctx.sandbox` 后挂载 `sandbox-local`、在 `ctx.shell` 后挂载受限执行器，就能使每次 bash 或 pwsh 调用默认在限制下运行。当进程必须在隔离环境中运行时请另选方案——容器、microVM 或远程执行器会替换整个 `ctx.shell`/`ctx.fs` 能力，而不是在这里添加后端。
+
+### 隔离命令
+
+挂载服务、后端与受限执行器；随附的组合由[基础组合包（base bundle）](../../bundle/base/cordis.patch.yml)定义。
+
+```yaml
+- id: sandbox
+  name: '@qilin-agent/sandbox-local'     # the per-platform backend provider (ctx.sandbox)
+- id: sandbox-policy
+  name: '@qilin-agent/sandbox-policy'    # the deployment default mode and workspace-write root
+  config:
+    mode: workspace-write                    # the deployment default every session starts from
+    workspaceRoot: !!js process.cwd()        # the boundary workspace-write may write under
+- id: bash
+  name: '@qilin-agent/bash-sandbox'      # the confined executor behind ctx.shell
+```
+
+使用该组合时，bash 调用在 `workspace-write` 下受限运行：工作区内写入成功，工作区外写入被拒绝，模型可以通过下面的升权流程恢复。
+
+### 模式与强制执行
+
+模式指明命令可以执行的文件操作；强制执行完整度报告后端对这些操作的管辖程度。
+
+| 模式 | 效果 |
+|---|---|
+| `read-only` | 拒绝写入，必需 sink（如 `/dev/null`）除外 |
+| `workspace-write` | 允许写入工作区根目录及后端定义的临时区域 |
+| `danger-full-access` | 绕过隔离；消费方直接 spawn 原始 argv |
+
+强制执行逐调用报告：`full` 表示后端管辖模式承诺的每个文件操作，`partial` 表示活动后端或较旧的内核 ABI 只管辖子集——Windows ACL 档与较旧的 Landlock ABI 是当前的部分强制执行情形，需要绝对边界的消费方可以拒绝或向上暴露它们。
+
+### 被拒绝的调用与升权
+
+受限调用被拒绝时，操作会报告指明模式的拒绝标记——`[sandbox: file access denied under <mode> mode]`——组合声明升权能力时还会给出升权提示。模型可以用 `sandbox_permissions`（足以放行的最窄更宽模式）加 `justification` 重试一次完全相同的调用；用户会看到一次审批提示，可以选择允许一次、拒绝或取消。更宽的模式需要审批，且只作用于该次调用。重复指定调用的生效模式无需审批即可成功；更窄的目标仍然无效。
+
+### 故障关闭行为
+
+没有后端能强制执行所请求的模式时，调用以 `SANDBOX_UNAVAILABLE` 失败，而不是不受限制地运行；错误文本会指明缺失的平台 runner。启动后失败的后端还会报告结构化的 runner 失败签名，因此损坏的沙箱可以与命令失败区分开。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释约定背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+- **同一执行环境。** 文件系统、子进程与沙箱提供方使用同一文件系统和内核。远端组合替换这三个提供方，并在该环境中异步解析限制。
+- **策略随调用传递。** `SandboxPolicy` 逐调用携带，绝不在提供方上固定：两个消费方可以同时按不同策略隔离，获批的升权重试只是用更宽策略发起的新调用。默认与解析是消费方显式步骤。
+- **故障关闭。** `confine()` 异步返回用于强制执行限制的 argv，或以 `SandboxUnavailableError` 拒绝；绝不允许静默无限制放行，功能探测用于仲裁多 runner 链。
+- **统一的拒绝与升权词汇。** 标记与提示文本以及严格更宽阶梯都放在这里，使 bash 与 fs 家族不会漂移。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：`SandboxProvider` 服务、模式/强制执行/策略类型、故障关闭错误 |
+| [`src/escalation.ts`](src/escalation.ts) | 升权词汇：更宽模式阶梯、参数校验、拒绝与提示标记、审批编排 |
+| [`src/roots.ts`](src/roots.ts) | 可写根目录推导，Seatbelt profile 与进程内 fs 栅栏共享 |
+
+### 升权编排
+
+阶梯是封闭表——`read-only` 可升权到 `workspace-write` 或 `danger-full-access`，`workspace-write` 只能升权到 `danger-full-access`——在执行时检查，绝不写入工具 schema，schema 的枚举保持封闭的目标词汇。[`approveEscalation`](src/escalation.ts) 在请求重复当前模式时无需审批就返回该模式，拒绝更窄或不支持的目标，并为更宽模式请求审批。调用方先校验 `sandbox_permissions`/`justification` 配对。
+
+### 可写根目录
+
+`workspace-write` 意味着「工作区根目录加宿主临时区域」：`writableRoots` 以规范化方式推导该白名单，解析符号链接并去重，使 Seatbelt profile 与进程内 fs 栅栏授予完全相同的根目录。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+先从子系统参考文档了解穷尽式约定，再看实现它的后端、消费方与策略来源。
+
+- [进程沙箱子系统](../../../docs/subsystems/sandbox.zh.md)——完整词汇、逐调用策略与分类方言。
+- [子进程沙箱决策](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md)——能力边界、升权设计与延期阶段。
+- [本地沙箱后端](../sandbox-local/README.zh.md)——`ctx.sandbox` 背后的各平台 runner。
+- [Bash 沙箱执行器](../../shell/bash-sandbox/README.zh.md)——受限的 bash 消费方。
+- [沙箱策略包](../sandbox-policy/README.zh.md)——逐调用模式与工作区根目录的来源。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 间接的限制错误
+
+#### 模型看到什么
+
+通过 [`qilin-bash-sandbox`](../../shell/bash-sandbox/README.zh.md) 和 [`qilin-tool-bash`](../../shell/tool-bash/README.zh.md)，请求的受限模式没有可用后端时会产生错误码 `SANDBOX_UNAVAILABLE` 及下方精确错误；执行期 runner 失败会追加 ` Runner failure: <detail>`。
+
+##### 精确错误
+
+```markdown
+sandbox mode "<mode>" is requested but no sandbox backend is usable on this host; refusing to run the command unconfined. Install bubblewrap or run a Landlock-enforcing kernel (Linux), ensure sandbox-exec is usable (macOS), or ensure the ACL restricted-token runner can start (Windows) — otherwise switch the consumer to danger-full-access.
+```
+
+#### Token 影响
+
+条件性错误文本对该次调用可见，并保留在历史中直到压缩（compaction）。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+### 升权请求与结果
+
+#### 模型看到什么
+
+被拒绝的调用会呈现标记 `[sandbox: file access denied under <mode> mode]`，组合声明升权能力时还会呈现提示 `[sandbox: escalation available — retry this exact <subject> once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`。重试携带 `sandbox_permissions` 与 `justification`；用户的 `allowed-once`／`rejected`／`cancelled` 决定成为该调用的结果文本。
+
+#### Token 影响
+
+只有被拒绝调用的错误与任何升权结果文本可见；两者都会保留在历史中直到压缩。
+
+#### KV Cache 影响
+
+仅追加；升权文本位于保留前缀之后，不会使已缓存条目失效。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明该 seam 何时不合适，或何时需要特别运维。它们是当前包约束，不是通用沙箱对比或任务积压。
+
+- **文件操作是完整的策略词汇**——该 seam 不表达网络、进程、系统调用、设备或凭据限制。
+- **只支持与宿主共享文件系统和内核的限制**——容器、microVM 与远程执行需要替换能力实现，而不是在此添加提供方。
+- **拒绝报告是一种 stderr 方言**——该 seam 返回后端签名，而非类型化运行时拒绝通道，需要分类的消费方必须从子进程输出推断。
+- **Runner 诊断使用带内通道**——退出状态与 stderr 证据无法证明匹配行由哪个进程写入，因此故意模仿 runner 的受限子进程可能造成错误的可用性或诊断归因；这无法绕过隔离，带外 runner 状态通道暂缓实现。
+- **每个上下文只有一个提供方**——同时组合不同沙箱机制需要提供方级阶梯或独立 Kylin 上下文；调用方逐调用选择策略，而非后端标识。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：未决方向与开放问题。它明确不具权威性——已交付的行为、限制与既定理由以上文、包代码和相关 Agent Note 为准。
+
+#### 未来：消费方与环境
+
+[沙箱决策](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md)列出延期阶段——可选的 `subagent-acp` 消费方（隔离子 agent（智能体），默认不隔离）与环境一致的能力组示例。两者均未决定；该笔记列为延期的 Windows 链已通过 `sandbox-local` 的 ACL 受限令牌档交付。
+
+</details>

package/lib/index.js

@@ -0,0 +1,279 @@
+import { Service } from "@qilin-agent/kylin";
+import { HarnessError } from "@qilin-agent/llm";
+import { assertNever } from "@qilin-agent/util-values";
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+//#region lib/types/escalation.js
+/**
+* The escalation vocabulary and choreography shared by every sandbox-enforcing
+* tool family (`@qilin-agent/tool-bash`, `@qilin-agent/tool-fs`): the
+* strictly-wider ladder, the argument-pairing validation, the model-facing
+* denial/hint markers, and {@link approveEscalation} — the ordered fail-closed
+* sequence that resolves a `sandbox_permissions` request through a
+* user-approval channel BEFORE anything executes. One home keeps the two
+* families' approval ordering and verbatim error texts from drifting apart.
+*
+* The channel is a minimal STRUCTURAL function shape ({@link EscalationAsk}),
+* not the approval service type: the tool layer — which owns the agent, the
+* call id, and the tool name — closes over `ctx.approval.request(...)` and
+* hands the closure down, so this package never depends on the approval or
+* agent packages.
+*
+* @module qilin-sandbox/escalation
+*/
+/**
+* The strictly-wider table: what a call whose effective mode is the key may
+* escalate TO. Checked at EXECUTION, never baked into a tool schema — the
+* schema's enum is {@link ESCALATION_TARGETS}, because schemas are
+* registry-global while the effective mode is per-call truth.
+*/
+const WIDER_MODES = {
+	"read-only": ["workspace-write", "danger-full-access"],
+	"workspace-write": ["danger-full-access"]
+};
+/**
+* The closed escalation-target vocabulary — every mode a call could ever
+* escalate TO (`read-only` is the floor; nothing escalates to it). Advertised
+* whenever the mounted capability confines: cutting the enum down to the modes
+* wider than the composition's DEFAULT would strand a session whose effective
+* mode sits below it (a `danger-full-access` default would advertise nothing
+* while a narrower-switched session stays confined with no lever).
+*/
+const ESCALATION_TARGETS = ["workspace-write", "danger-full-access"];
+/**
+* Validate the escalation argument pairing a tool schema cannot express:
+* `sandbox_permissions` and `justification` travel together — an approval
+* prompt without a reason, or a reason driving nothing, is a malformed ask —
+* and the justification must be a non-empty sentence.
+* @param sandboxPermissions - the raw `sandbox_permissions` argument, if given.
+* @param justification - the raw `justification` argument, if given.
+*/
+function validateEscalationArgs(sandboxPermissions, justification) {
+	if (sandboxPermissions !== void 0 && justification === void 0) throw new Error("invalid escalation: sandbox_permissions requires a justification");
+	if (justification !== void 0 && sandboxPermissions === void 0) throw new Error("invalid escalation: justification is only valid together with sandbox_permissions");
+	if (justification !== void 0 && justification.trim().length === 0) throw new Error("invalid justification: expected a non-empty sentence");
+}
+/**
+* The model-facing denial marker — the one vocabulary both enforcing families
+* teach and report, so the model recognizes a policy denial identically
+* whether the kernel refused a bash file effect or the filesystem provider's
+* fence refused a mutation.
+* @param mode - the mode the denied call ran under.
+* @returns the marker line, exactly as the model sees it.
+*/
+function sandboxDenialMarker(mode) {
+	return `[sandbox: file access denied under ${mode} mode]`;
+}
+/**
+* The same-turn escalation hint that rides a denial when the composition
+* advertises the escalation fields — the nudge lives at the decision point so
+* the sanctioned retry does not depend on the model recalling the tool
+* description.
+* @param subject - the family's noun for the denied action (`command` for
+*   bash, `operation` for a filesystem mutation).
+* @returns the hint line, exactly as the model sees it.
+*/
+function escalationHintMarker(subject) {
+	return `[sandbox: escalation available — retry this exact ${subject} once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`;
+}
+/**
+* Resolve a sandbox permission request before execution. Repeating the call's
+* effective mode returns it without approval. A strictly wider mode requires
+* approval and applies only to this call. Narrower or unsupported targets,
+* missing approval services or agents for widening, and non-grant outcomes
+* throw before execution.
+* @param request - the escalation to judge (see {@link EscalationRequest}).
+* @param approval - the approval ingredients the tool holds (see {@link EscalationApproval}).
+* @returns the granted mode, consumed by the one call that asked.
+*/
+async function approveEscalation(request, approval) {
+	const { requestedMode: mode, effectiveMode, justification, subject } = request;
+	if (mode === effectiveMode) return effectiveMode;
+	if (!(WIDER_MODES[effectiveMode] ?? []).includes(mode)) throw new Error(`sandbox escalation to "${mode}" is not strictly wider than this call's current "${effectiveMode}" mode`);
+	if (approval.approver === void 0) throw new Error(`sandbox escalation to "${mode}" requires approval, but no approval service is composed`);
+	if (approval.agent === void 0) throw new Error(`sandbox escalation to "${mode}" requires approval, but the call has no agent to route it through`);
+	const outcome = await approval.approver.request({
+		agent: approval.agent,
+		toolName: approval.toolName,
+		callId: approval.callId,
+		reason: `escalate sandbox to ${mode}: ${justification}`,
+		displayReason: {
+			en: `Allow this operation with ${mode} permissions: ${justification}`,
+			zh: `允许本次操作使用 ${mode} 权限：${justification}`
+		},
+		...approval.signal ? { signal: approval.signal } : {}
+	});
+	switch (outcome) {
+		case "allowed-once": return mode;
+		case "rejected": throw new Error(`the user rejected escalating this ${subject} to "${mode}"`);
+		case "cancelled": throw new Error(`approval for escalating to "${mode}" was cancelled`);
+		case "unavailable": throw new Error(`sandbox escalation to "${mode}" requires approval, but no approval channel is available`);
+		default: return assertNever(outcome, "EscalationOutcome");
+	}
+}
+//#endregion
+//#region lib/types/roots.js
+/**
+* The writable-root derivation shared by every enforcement dialect that
+* expresses a mode as a canonical allow-list: `workspace-write` means "the
+* workspace root plus the platform temp areas", and this module is that
+* meaning's one home. The Seatbelt profile
+* (`@qilin-agent/sandbox-local`) and the in-process filesystem fence
+* (`@qilin-agent/fs-sandbox`) both derive their allow-list here, so "the
+* write tool cannot write /tmp but bash can" asymmetries cannot arise between
+* them. The bwrap and Landlock dialects keep their own grant spellings (an
+* ephemeral `/tmp` mount, launcher-owned flags) — the honest per-runner
+* differences recorded in the sandbox RFC — with parity pinned by test.
+*
+* @module qilin-sandbox/roots
+*/
+/**
+* Resolve a granted root to the path the enforcement layer actually compares:
+* canonical (symlinks resolved), because both Seatbelt filters and the fs
+* fence's containment check match resolved paths — `/tmp` IS `/private/tmp`
+* on darwin, and an as-spelled grant would match nothing.
+* @param path - the root as configured or platform-reported.
+* @returns the canonical path, or the spelling as-is when resolution fails
+*   (a missing root matches nothing until it exists — the conservative
+*   outcome; inventing a fallback would grant a path the caller never named).
+*/
+function canonicalPath(path) {
+	try {
+		return realpathSync.native(path);
+	} catch {
+		return path;
+	}
+}
+/**
+* The roots one confined execution may WRITE under — the mode's meaning as a
+* canonical, deduplicated allow-list. `read-only` allows nothing;
+* `workspace-write` allows the policy's workspace root, the host `/tmp`, and
+* the per-user platform temp dir (`os.tmpdir()` — the real temp area for
+* mkstemp-family tools; omitting it would deny what the mode promises).
+* @param policy - the file-effect policy to derive the allow-list from.
+* @returns the canonical writable roots; empty exactly under `read-only`.
+*/
+function writableRoots(policy) {
+	if (policy.mode !== "workspace-write") return [];
+	return [...new Set([
+		policy.workspaceRoot,
+		"/tmp",
+		tmpdir()
+	].map(canonicalPath))];
+}
+//#endregion
+//#region lib/types/diagnostics.js
+/** Classify observed sandbox runner failures and file-effect denials. */
+/** Node-local spawn codes proven to identify executable resolution or permission failure. */
+const EXECUTABLE_SPAWN_CODES = new Set(["EACCES", "ENOENT"]);
+/** Whether the caller-owned spawn cwd can be entered. */
+function isUsableWorkdir(path) {
+	try {
+		if (!statSync(path).isDirectory()) return false;
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Attribute only Node ENOENT/EACCES failures whose error path equals argv[0]
+* after independently ruling out the caller-owned cwd. A supplied error path
+* must exactly identify the runner; without one, the syscall must. With a
+* usable cwd, these codes describe resolution or execute permission for that
+* argv[0] or its shebang interpreter.
+* The workdir is checked at classification time, not atomically with spawn;
+* concurrent path replacement may change attribution but cannot permit an
+* unconfined execution.
+* @param error - the original spawn rejection.
+* @param runnerProgram - provider argv[0], the executable that establishes confinement.
+* @param workdir - the caller-owned spawn cwd, checked independently for usability.
+* @returns whether the rejection has executable-specific runner evidence.
+*/
+function isRunnerSpawnFailure(error, runnerProgram, workdir) {
+	if (runnerProgram === void 0 || !isUsableWorkdir(workdir)) return false;
+	if (typeof error !== "object" || error === null) return false;
+	const { code, path, syscall } = error;
+	if (typeof code !== "string" || !EXECUTABLE_SPAWN_CODES.has(code)) return false;
+	if (typeof syscall !== "string") return false;
+	const exactSyscall = `spawn ${runnerProgram}`;
+	if (path === void 0) return syscall === exactSyscall;
+	if (typeof path !== "string" || path.length === 0 || path !== runnerProgram) return false;
+	return syscall === "spawn" || syscall === exactSyscall;
+}
+/**
+* Classify one settled process against the selected backend's structured
+* runner-failure rules. Each rule requires a nonzero exit, its optional
+* exit-code gate, and a fatal signature on one stderr line after exact
+* informational lines are excluded.
+* @param exitCode - process exit code; null means signal termination.
+* @param stderr - collected stderr text, left unchanged.
+* @param rules - structured runner-failure rules from the active wrap.
+* @returns the first matching fatal line, or undefined when evidence is insufficient.
+*/
+function classifyRunnerFailure(exitCode, stderr, rules) {
+	if (exitCode === null || exitCode === 0) return void 0;
+	const lines = stderr.split(/\r?\n/);
+	for (const rule of rules) {
+		if (rule.allowedExitCodes !== void 0 && !rule.allowedExitCodes.includes(exitCode)) continue;
+		const informationalLines = new Set((rule.informationalLines ?? []).map((line) => line.toLowerCase()));
+		const fatalSignatures = rule.fatalSignatures.filter((signature) => signature.trim().length > 0).map((signature) => signature.toLowerCase());
+		for (const line of lines) {
+			const lowered = line.toLowerCase();
+			if (informationalLines.has(lowered)) continue;
+			if (fatalSignatures.some((signature) => lowered.includes(signature))) return { detail: line };
+		}
+	}
+}
+/**
+* Match a non-zero exit against case-insensitive stderr signatures.
+* @param exitCode - process exit code; null means signal termination.
+* @param stderr - collected stderr text.
+* @param signatures - substrings identifying the selected backend's dialect.
+* @returns whether this is a non-zero exit whose stderr matches a signature.
+*/
+function matchesSignature(exitCode, stderr, signatures) {
+	if (exitCode === null || exitCode === 0) return false;
+	const lowered = stderr.toLowerCase();
+	return signatures.some((signature) => lowered.includes(signature.toLowerCase()));
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Service Definition for the same-world process-confinement capability seam: wrap exact subprocess argv under a
+* host-path file policy. Containers, microVMs, and remote execution replace the
+* surrounding capability seam instead; this service shares the host kernel and filesystem.
+* @module @qilin-agent/sandbox
+*/
+/**
+* Error code for a requested confined mode when no backend is usable. The
+* provider fails closed, and `HarnessError` carries the code through
+* `tool/result` so callers can distinguish missing confinement from command
+* failure.
+*/
+const SANDBOX_UNAVAILABLE = "SANDBOX_UNAVAILABLE";
+/**
+* Thrown when {@link SandboxProvider.confine} cannot enforce the requested
+* mode. Carries {@link SANDBOX_UNAVAILABLE} through the structured error
+* channel.
+*/
+var SandboxUnavailableError = class extends HarnessError {
+	constructor(mode, detail) {
+		super(`sandbox mode "${mode}" is requested but no sandbox backend is usable on this host; refusing to run the command unconfined. Install bubblewrap or run a Landlock-enforcing kernel (Linux), ensure sandbox-exec is usable (macOS), or ensure the ACL restricted-token runner can start (Windows) — otherwise switch the consumer to danger-full-access.` + (detail === void 0 ? "" : ` Runner failure: ${detail}`), SANDBOX_UNAVAILABLE);
+		this.name = "SandboxUnavailableError";
+	}
+};
+/**
+* Abstract process-sandbox service. {@link confine} must return enforcing argv
+* or fail closed at wrap or runner-execution time; silent unconfined passthrough
+* is forbidden. Functional probes arbitrate multi-runner chains and may be
+* skipped for a sole candidate, whose own refusal remains the fail-closed end.
+*/
+var SandboxProvider = class extends Service {
+	/* v8 ignore next -- abstract service construction is covered through concrete provider packages. */
+	constructor(ctx) {
+		super(ctx, "sandbox");
+	}
+};
+//#endregion
+export { ESCALATION_TARGETS, SANDBOX_UNAVAILABLE, SandboxProvider, SandboxProvider as default, SandboxUnavailableError, WIDER_MODES, approveEscalation, canonicalPath, classifyRunnerFailure, escalationHintMarker, isRunnerSpawnFailure, matchesSignature, sandboxDenialMarker, validateEscalationArgs, writableRoots };

package/lib/types/diagnostics.d.ts

@@ -0,0 +1,42 @@
+import type { RunnerFailureRule } from './index.ts';
+/**
+ * Attribute only Node ENOENT/EACCES failures whose error path equals argv[0]
+ * after independently ruling out the caller-owned cwd. A supplied error path
+ * must exactly identify the runner; without one, the syscall must. With a
+ * usable cwd, these codes describe resolution or execute permission for that
+ * argv[0] or its shebang interpreter.
+ * The workdir is checked at classification time, not atomically with spawn;
+ * concurrent path replacement may change attribution but cannot permit an
+ * unconfined execution.
+ * @param error - the original spawn rejection.
+ * @param runnerProgram - provider argv[0], the executable that establishes confinement.
+ * @param workdir - the caller-owned spawn cwd, checked independently for usability.
+ * @returns whether the rejection has executable-specific runner evidence.
+ */
+export declare function isRunnerSpawnFailure(error: unknown, runnerProgram: string | undefined, workdir: string): boolean;
+/** Fatal runner evidence retained for infrastructure-error detail. */
+interface RunnerFailureMatch {
+    /** The original stderr line that matched a fatal signature. */
+    detail: string;
+}
+/**
+ * Classify one settled process against the selected backend's structured
+ * runner-failure rules. Each rule requires a nonzero exit, its optional
+ * exit-code gate, and a fatal signature on one stderr line after exact
+ * informational lines are excluded.
+ * @param exitCode - process exit code; null means signal termination.
+ * @param stderr - collected stderr text, left unchanged.
+ * @param rules - structured runner-failure rules from the active wrap.
+ * @returns the first matching fatal line, or undefined when evidence is insufficient.
+ */
+export declare function classifyRunnerFailure(exitCode: number | null, stderr: string, rules: readonly RunnerFailureRule[]): RunnerFailureMatch | undefined;
+/**
+ * Match a non-zero exit against case-insensitive stderr signatures.
+ * @param exitCode - process exit code; null means signal termination.
+ * @param stderr - collected stderr text.
+ * @param signatures - substrings identifying the selected backend's dialect.
+ * @returns whether this is a non-zero exit whose stderr matches a signature.
+ */
+export declare function matchesSignature(exitCode: number | null, stderr: string, signatures: readonly string[]): boolean;
+export {};
+//# sourceMappingURL=diagnostics.d.ts.map

package/lib/types/escalation.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The escalation vocabulary and choreography shared by every sandbox-enforcing
+ * tool family (`@qilin-agent/tool-bash`, `@qilin-agent/tool-fs`): the
+ * strictly-wider ladder, the argument-pairing validation, the model-facing
+ * denial/hint markers, and {@link approveEscalation} — the ordered fail-closed
+ * sequence that resolves a `sandbox_permissions` request through a
+ * user-approval channel BEFORE anything executes. One home keeps the two
+ * families' approval ordering and verbatim error texts from drifting apart.
+ *
+ * The channel is a minimal STRUCTURAL function shape ({@link EscalationAsk}),
+ * not the approval service type: the tool layer — which owns the agent, the
+ * call id, and the tool name — closes over `ctx.approval.request(...)` and
+ * hands the closure down, so this package never depends on the approval or
+ * agent packages.
+ *
+ * @module qilin-sandbox/escalation
+ */
+import type { SandboxMode } from './index.ts';
+/**
+ * The strictly-wider table: what a call whose effective mode is the key may
+ * escalate TO. Checked at EXECUTION, never baked into a tool schema — the
+ * schema's enum is {@link ESCALATION_TARGETS}, because schemas are
+ * registry-global while the effective mode is per-call truth.
+ */
+export declare const WIDER_MODES: Record<string, readonly SandboxMode[]>;
+/**
+ * The closed escalation-target vocabulary — every mode a call could ever
+ * escalate TO (`read-only` is the floor; nothing escalates to it). Advertised
+ * whenever the mounted capability confines: cutting the enum down to the modes
+ * wider than the composition's DEFAULT would strand a session whose effective
+ * mode sits below it (a `danger-full-access` default would advertise nothing
+ * while a narrower-switched session stays confined with no lever).
+ */
+export declare const ESCALATION_TARGETS: readonly SandboxMode[];
+/**
+ * Validate the escalation argument pairing a tool schema cannot express:
+ * `sandbox_permissions` and `justification` travel together — an approval
+ * prompt without a reason, or a reason driving nothing, is a malformed ask —
+ * and the justification must be a non-empty sentence.
+ * @param sandboxPermissions - the raw `sandbox_permissions` argument, if given.
+ * @param justification - the raw `justification` argument, if given.
+ */
+export declare function validateEscalationArgs(sandboxPermissions: string | undefined, justification: string | undefined): void;
+/**
+ * The model-facing denial marker — the one vocabulary both enforcing families
+ * teach and report, so the model recognizes a policy denial identically
+ * whether the kernel refused a bash file effect or the filesystem provider's
+ * fence refused a mutation.
+ * @param mode - the mode the denied call ran under.
+ * @returns the marker line, exactly as the model sees it.
+ */
+export declare function sandboxDenialMarker(mode: SandboxMode): string;
+/**
+ * The same-turn escalation hint that rides a denial when the composition
+ * advertises the escalation fields — the nudge lives at the decision point so
+ * the sanctioned retry does not depend on the model recalling the tool
+ * description.
+ * @param subject - the family's noun for the denied action (`command` for
+ *   bash, `operation` for a filesystem mutation).
+ * @returns the hint line, exactly as the model sees it.
+ */
+export declare function escalationHintMarker(subject: string): string;
+/**
+ * The closed outcome vocabulary of one escalation ask — structurally identical
+ * to the approval seam's `ApprovalOutcome` so an `ApprovalService.request`
+ * return is assignable without this package importing it.
+ */
+export type EscalationOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
+/**
+ * The minimal approval-request shape {@link approveEscalation} needs —
+ * structurally the approval seam's `ApprovalService`, generic over the agent
+ * type `A` and call-id type `C` so this package resolves escalations through
+ * `ctx.approval` without importing the approval or agent packages (the tool
+ * layer infers `A`/`C` as its own `Agent`/`ToolCallId`).
+ */
+export interface EscalationApprover<A = object, C = string> {
+    /**
+     * Ask the human to approve one action, resolving to a closed outcome.
+     * @param req - the audit request with optional localized displayReason and presentation lifetime signal.
+     * @returns the human's decision as a closed {@link EscalationOutcome}.
+     */
+    request(req: {
+        agent: A;
+        toolName: string;
+        callId: C;
+        reason: string;
+        displayReason?: {
+            readonly en: string;
+            readonly [locale: string]: string;
+        };
+        signal?: AbortSignal;
+    }): Promise<EscalationOutcome>;
+}
+/**
+ * The approval ingredients an escalating tool hands {@link approveEscalation}:
+ * the approval requester (`ctx.approval`, or `undefined` when none is
+ * composed), the calling agent (or `undefined` for an agent-less execution),
+ * and the call's identity. The tool layer holds all of these; this package
+ * only judges them.
+ */
+export interface EscalationApproval<A = object, C = string> {
+    /** The approval requester (`ctx.approval`), or `undefined` when none is composed. */
+    approver: EscalationApprover<A, C> | undefined;
+    /** The calling agent, or `undefined` for an agent-less execution (fails closed). */
+    agent: A | undefined;
+    /** The tool-call id the approval prompt attaches to. */
+    callId: C;
+    /** The tool name recorded on the approval request. */
+    toolName: string;
+    /** The tool-execution abort signal the approval request rides, when present. */
+    signal?: AbortSignal;
+}
+/** One escalation request, as {@link approveEscalation} judges it. */
+export interface EscalationRequest {
+    /** The requested target mode (schema-pinned to {@link ESCALATION_TARGETS} when advertised). */
+    requestedMode: string;
+    /** The model's one-sentence reason, shown verbatim to the user inside the audit reason. */
+    justification: string;
+    /** The call's effective mode (session override ?? composition default); repeating it needs no approval. */
+    effectiveMode: SandboxMode;
+    /** The family's noun for the escalated action in user-facing texts (`command` for bash, `operation` for fs). */
+    subject: string;
+}
+/**
+ * Resolve a sandbox permission request before execution. Repeating the call's
+ * effective mode returns it without approval. A strictly wider mode requires
+ * approval and applies only to this call. Narrower or unsupported targets,
+ * missing approval services or agents for widening, and non-grant outcomes
+ * throw before execution.
+ * @param request - the escalation to judge (see {@link EscalationRequest}).
+ * @param approval - the approval ingredients the tool holds (see {@link EscalationApproval}).
+ * @returns the granted mode, consumed by the one call that asked.
+ */
+export declare function approveEscalation<A, C>(request: EscalationRequest, approval: EscalationApproval<A, C>): Promise<SandboxMode>;
+//# sourceMappingURL=escalation.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Service Definition for the same-world process-confinement capability seam: wrap exact subprocess argv under a
+ * host-path file policy. Containers, microVMs, and remote execution replace the
+ * surrounding capability seam instead; this service shares the host kernel and filesystem.
+ * @module @qilin-agent/sandbox
+ */
+import { Context, Service } from '@qilin-agent/kylin';
+import { HarnessError } from '@qilin-agent/llm';
+import type { SessionId } from '@qilin-agent/session';
+export { ESCALATION_TARGETS, WIDER_MODES, approveEscalation, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs, } from './escalation.ts';
+export type { EscalationApproval, EscalationApprover, EscalationOutcome, EscalationRequest } from './escalation.ts';
+export { canonicalPath, writableRoots } from './roots.ts';
+/**
+ * File-effect policy for confined processes. `read-only` permits only required
+ * sinks such as `/dev/null`; `workspace-write` also permits the workspace and a
+ * backend-defined temp area; `danger-full-access` bypasses confinement. Network
+ * and process visibility are outside this vocabulary.
+ */
+export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** A confining (non-`danger-full-access`) mode — the modes a {@link SandboxPolicy} can carry. */
+export type ConfinedSandboxMode = Exclude<SandboxMode, 'danger-full-access'>;
+/**
+ * The complete file-effect policy resolved for one capability call. The root
+ * is carried even under modes that do not consume it so callers can resolve
+ * policy once before choosing the enforcement path.
+ */
+export interface SandboxExecutionPolicy {
+    /** The file-effect mode this execution runs under. */
+    mode: SandboxMode;
+    /** Absolute root directory `workspace-write` may write under. */
+    workspaceRoot: string;
+    /**
+     * Opaque identity of the calling session (the branded `qilin-session`
+     * SessionId). Backends key per-session state off it (e.g. windows-acl gives
+     * each live session/workspace pair a random private temp directory and SID,
+     * while the workspace SID and standing grant remain per-workspace); absent
+     * for agentless calls, which fall back to per-call backend state.
+     */
+    sessionId?: SessionId;
+}
+/**
+ * Enforcement completeness for this host. `partial` means an active backend or
+ * older kernel ABI cannot govern every promised file effect; callers requiring
+ * an absolute boundary must not treat it as `full`.
+ */
+export type SandboxEnforcement = 'full' | 'partial';
+/**
+ * What one confined execution is allowed to touch — carried PER CALL, not
+ * fixed on the provider: two consumers may confine under different policies
+ * at the same instant (bash under `read-only` while a confined child agent
+ * needs its state directory writable), and an approved escalated retry is a
+ * new call with a wider policy. Defaulting/resolution is an explicit step at
+ * the consumer boundary; the provider treats the policy as fully specified.
+ */
+export interface SandboxPolicy extends SandboxExecutionPolicy {
+    /** The file-effect mode this execution runs under. */
+    mode: ConfinedSandboxMode;
+}
+/**
+ * Evidence that identifies a sandbox runner failing before it executes the
+ * wrapped command. A consumer first applies {@link allowedExitCodes} when
+ * present, removes {@link informationalLines} by case-insensitive exact line
+ * equality, then matches {@link fatalSignatures} case-insensitively within
+ * each remaining stderr line. Exit status alone never proves runner failure.
+ */
+export interface RunnerFailureRule {
+    /** Nonzero process exit codes on which this rule may match; omitted permits any nonzero exit. */
+    allowedExitCodes?: readonly number[];
+    /** Non-empty substrings identifying a fatal runner diagnostic on one stderr line. */
+    fatalSignatures: readonly string[];
+    /** Benign stderr lines excluded by exact full-line equality before fatal matching. */
+    informationalLines?: readonly string[];
+}
+/**
+ * A {@link SandboxProvider.confine} result: the argv to spawn in place of
+ * the caller's own, plus the enforcement completeness the selected backend
+ * achieves for it.
+ */
+export interface ConfinedArgv {
+    /** The wrapped argv (runner, profile, separator, then the caller's argv). */
+    argv: string[];
+    /** How completely the selected backend enforces the policy's file effects. */
+    enforcement: SandboxEnforcement;
+    /**
+     * The selected backend's denial DIALECT: the case-insensitive stderr
+     * substrings a file effect denied by THIS backend produces (EROFS text
+     * under bwrap's read-only binds, EACCES under Landlock, EPERM under
+     * Seatbelt). A consumer that infers denials from a failed run's stderr
+     * matches against exactly these rather than a cross-backend union — the
+     * union claims denials a given backend never produces.
+     */
+    denialSignatures: readonly string[];
+    /**
+     * Structured runner-failure evidence rules. Consumers require a matching
+     * fatal stderr line (after informational exclusions) and any rule-specific
+     * exit-code gate before checking denial signatures: runner failure means the
+     * command never ran, while denial means confinement worked and blocked it.
+     */
+    runnerFailureRules: readonly RunnerFailureRule[];
+}
+/**
+ * Error code for a requested confined mode when no backend is usable. The
+ * provider fails closed, and `HarnessError` carries the code through
+ * `tool/result` so callers can distinguish missing confinement from command
+ * failure.
+ */
+export declare const SANDBOX_UNAVAILABLE = "SANDBOX_UNAVAILABLE";
+/**
+ * Thrown when {@link SandboxProvider.confine} cannot enforce the requested
+ * mode. Carries {@link SANDBOX_UNAVAILABLE} through the structured error
+ * channel.
+ */
+export declare class SandboxUnavailableError extends HarnessError {
+    constructor(mode: ConfinedSandboxMode, detail?: string);
+}
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        sandbox: SandboxProvider;
+    }
+}
+/**
+ * Abstract process-sandbox service. {@link confine} must return enforcing argv
+ * or fail closed at wrap or runner-execution time; silent unconfined passthrough
+ * is forbidden. Functional probes arbitrate multi-runner chains and may be
+ * skipped for a sole candidate, whose own refusal remains the fail-closed end.
+ */
+export declare abstract class SandboxProvider extends Service {
+    constructor(ctx: Context);
+    /**
+     * Wrap `argv` so it executes confined under `policy` on this host; the
+     * caller spawns the returned argv in place of its own.
+     * @param argv - the exact argv the caller is about to spawn (program plus
+     *   arguments), NOT a shell string — a shell-shaped consumer passes
+     *   `['bash', '-c', command]`.
+     * @param policy - the file-effect policy this execution runs under,
+     *   carried per call (see {@link SandboxPolicy}).
+     * @param signal - cancellation while the provider resolves the policy and runner.
+     * @returns the argv to spawn instead, plus the enforcement completeness
+     *   the selected backend achieves for it.
+     */
+    abstract confine(argv: readonly string[], policy: SandboxPolicy, signal?: AbortSignal): Promise<ConfinedArgv>;
+}
+export default SandboxProvider;
+export { classifyRunnerFailure, isRunnerSpawnFailure, matchesSignature } from './diagnostics.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/roots.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The writable-root derivation shared by every enforcement dialect that
+ * expresses a mode as a canonical allow-list: `workspace-write` means "the
+ * workspace root plus the platform temp areas", and this module is that
+ * meaning's one home. The Seatbelt profile
+ * (`@qilin-agent/sandbox-local`) and the in-process filesystem fence
+ * (`@qilin-agent/fs-sandbox`) both derive their allow-list here, so "the
+ * write tool cannot write /tmp but bash can" asymmetries cannot arise between
+ * them. The bwrap and Landlock dialects keep their own grant spellings (an
+ * ephemeral `/tmp` mount, launcher-owned flags) — the honest per-runner
+ * differences recorded in the sandbox RFC — with parity pinned by test.
+ *
+ * @module qilin-sandbox/roots
+ */
+import type { SandboxExecutionPolicy } from './index.ts';
+/**
+ * Resolve a granted root to the path the enforcement layer actually compares:
+ * canonical (symlinks resolved), because both Seatbelt filters and the fs
+ * fence's containment check match resolved paths — `/tmp` IS `/private/tmp`
+ * on darwin, and an as-spelled grant would match nothing.
+ * @param path - the root as configured or platform-reported.
+ * @returns the canonical path, or the spelling as-is when resolution fails
+ *   (a missing root matches nothing until it exists — the conservative
+ *   outcome; inventing a fallback would grant a path the caller never named).
+ */
+export declare function canonicalPath(path: string): string;
+/**
+ * The roots one confined execution may WRITE under — the mode's meaning as a
+ * canonical, deduplicated allow-list. `read-only` allows nothing;
+ * `workspace-write` allows the policy's workspace root, the host `/tmp`, and
+ * the per-user platform temp dir (`os.tmpdir()` — the real temp area for
+ * mkstemp-family tools; omitting it would deny what the mode promises).
+ * @param policy - the file-effect policy to derive the allow-list from.
+ * @returns the canonical writable roots; empty exactly under `read-only`.
+ */
+export declare function writableRoots(policy: SandboxExecutionPolicy): string[];
+//# sourceMappingURL=roots.d.ts.map

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@qilin-agent/sandbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Abstract process-sandbox seam (ctx.sandbox) for the QiLin: same-world confinement vocabulary and the SandboxProvider contract",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/sandbox/sandbox"
+  },
+  "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/kylin": "~4.0.3",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/session": "3.1.4"
+  },
+  "devDependencies": {
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "dependencies": {
+    "@qilin-agent/util-values": "3.1.4"
+  }
 }