feat(pwsh): mirror the bash sandbox surface — denial rendering, escalation, and the ConstrainedLanguage contract

tool-pwsh now renders sandbox denial facts (denial marker + same-turn escalation hint, runner-failed notice on background reads) and advertises the sandbox_permissions/justification escalation pair resolved through ctx.approval before execution — the shared fail-closed sequence from dsh-sandbox, with the tool name 'pwsh'. The description teaches the ConstrainedLanguage contract under the Windows sandbox (both confined modes run pwsh in CLM: Add-Type, non-core .NET statics, COM, and reflection fail; the mode cannot be lifted — probe-verified, pinned by LANGMODE assertions in the runner suite and description assertions in the tool suite). The stale pwsh-sandbox JSDoc ('the tool owns approval') and the parity notes' superseded 'minus sandbox' claims are corrected.

packages/bash/pwsh-sandbox/src/index.ts

@@ -6,8 +6,9 @@
  * enforcement, and denial facts. Positive runner-launch evidence means the
  * command never ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while
  * background processes carry `runnerFailed`; other spawn rejections retain
- * local-executor semantics. The tool owns approval and passes a complete
- * per-call policy.
+ * local-executor semantics. The tool layer owns the escalation approval flow
+ * through `ctx.approval`; this executor reports the sandbox facts the tool
+ * renders.
  * @module @deepseek-ai/dsh-pwsh-sandbox
  */
 
@@ -40,10 +41,12 @@ export type Config = LocalConfig
 
 /**
  * Registers as `ctx.bash` in place of the local pwsh executor and requires a
- * `ctx.sandbox` provider plus `ctx.sandboxPolicy`; the tool layer is
- * unchanged. Tool calls pass the calling session's resolved policy; direct
- * calls fall back to deployment policy. `result.sandbox` reports the mode and
- * enforcement actually used.
+ * `ctx.sandbox` provider plus `ctx.sandboxPolicy`; the tool layer carries the
+ * sandbox denial rendering and escalation surface (see the
+ * pwsh-tool-and-executor Agent Note). Tool calls pass the calling session's
+ * resolved policy; direct calls fall back to deployment policy.
+ * `result.sandbox` reports the mode, enforcement, and denial facts the tool
+ * renders.
  */
 /* jscpd:ignore-start -- deliberate call-for-call mirror of bash-sandbox's executor (pwsh-tool-and-executor Agent Note) */
 export class SandboxPwshExecutor extends PwshLocalExecutor {

packages/bash/tool-pwsh/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/tool-pwsh/README.md
-README.md: 78eb161f77b9524bc577b273abe59db6b931727c
-README.zh.md: 17696fe6d908838aaaca12e8179f2ad9cb780210
+README.md: c0c253fe24bd7eaa4f4d814141e17a67f10f4fb8
+README.zh.md: 7e672bfb4fbda8f683cab3dbb018624d43b2a6d2

packages/bash/tool-pwsh/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The model-facing `pwsh` tool registered over the `ctx.bash` executor seam. Intended for Windows compositions where a PowerShell executor (e.g. `@deepseek-ai/dsh-pwsh-local`) backs `ctx.bash`; the tool contract is PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables. Behavior mirrors `dsh-tool-bash` call-for-call minus the sandbox surface — foreground and `run_in_background` execution through the generic task runtime, the managed `DSH_*` environment through the shared `bash-env` registry, and the bash marker/truncation rendering story (a clean exit produces no marker).
+The model-facing `pwsh` tool registered over the `ctx.bash` executor seam. Intended for Windows compositions where a PowerShell executor (e.g. `@deepseek-ai/dsh-pwsh-local`) backs `ctx.bash`; the tool contract is PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables. Behavior mirrors `dsh-tool-bash` call-for-call — foreground and `run_in_background` execution through the generic task runtime, the managed `DSH_*` environment through the shared `bash-env` registry, the sandbox denial rendering with the same-turn `sandbox_permissions` escalation surface, and the bash marker/truncation rendering story (a clean exit produces no marker).
 
 Requires a loaded executor implementation and the `bash-env` plugin; the tool stays pending until both exist (`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`).
 
@@ -21,6 +21,8 @@ The plugin also contributes the `tool:pwsh` prompt section (order 105): non-zero
 | `timeoutMs` | number | Timeout override in milliseconds. The executor applies its configured default and cap. |
 | `workdir` | string | Working directory for this call. Defaults to the calling agent's session cwd (`session.header.cwd`) so each session runs in its own workspace; a relative `workdir` is resolved against that same identity. |
 | `run_in_background` | boolean | Return a task id immediately; no timeout applies. |
+| `sandbox_permissions` | string enum | Advertised only when a sandboxing executor is mounted (`ctx.bash.sandboxMode` defined). The wider sandbox mode for a one-shot retry of a command the sandbox just denied — the narrowest wider mode that suffices, requiring `justification` and user approval through `ctx.approval` BEFORE execution. A non-widening or unapprovable request fails closed without running anything. |
+| `justification` | string | Required with `sandbox_permissions`: one sentence for the user explaining why this exact command needs the wider access. |
 
 `command`, `workdir`, and `timeoutMs` are resolved against the executor's config defaults via `ctx.bash.resolve()` before execution. The workdir default is applied in the tool layer from the calling agent's `session.header.cwd` BEFORE `resolve()` — the per-session cwd must come from `exec.agent`, since N sessions share one executor; only when no session cwd is available does the executor fall back to its own config / `process.cwd()`.
 
@@ -28,9 +30,9 @@ The plugin also contributes the `tool:pwsh` prompt section (order 105): non-zero
 
 Every foreground and background model pwsh call receives a freshly collected trusted `DSH_*` environment through the shared [`dsh-bash-env`](../bash-env/) registry: `DSH_HOME` (the absolute Harness home), `DSH_SHELL=1`, the agent's `DSH_SESSION_ID`, and `DSH_SESSION_JSONL` when the active persistence backend locates one. Plugins contributing `DSH_*` facts to `ctx.bashEnv` apply to pwsh calls exactly as they do to bash calls. The snapshot passes through the dedicated `BashExecRequest.dshEnv` channel; `process.env` is never modified. The description teaches the generic `$env:DSH_*` convention rather than naming persistence-specific variables.
 
-Result text contains stdout, an optional `[stderr]` section, then applicable truncation, timeout, signal, and exit markers. A clean exit (0, no signal) produces no marker; an empty body renders as `(no output)`. Truncation links a safe complete spill file or reports it unavailable. Timeout is reported independently of final exit status; nonzero exit remains a model-interpreted result rather than `isError`. Windows reports forced termination as exit 1 without a signal, so `[killed by signal: …]` is POSIX-only there. Only infrastructure failures — spawn errors and aborts (`tool call aborted`) — produce `isError`.
+Result text contains stdout, an optional `[stderr]` section, then applicable truncation, sandbox-denial (with the same-turn escalation hint when the composition advertises escalation), timeout, signal, and exit markers. A clean exit (0, no signal) produces no marker; an empty body renders as `(no output)`. Truncation links a safe complete spill file or reports it unavailable. Timeout is reported independently of final exit status; nonzero exit remains a model-interpreted result rather than `isError`. Windows reports forced termination as exit 1 without a signal, so `[killed by signal: …]` is POSIX-only there. Only infrastructure failures — spawn errors and aborts (`tool call aborted`) — produce `isError`.
 
-The canonical success is `{ kind: 'foreground', ...BashRunResult }` for a completed foreground process or `{ kind: 'background', taskId }` for a published task. The renderer preserves exactly `started background task <id>` for background acks; programmatic consumers use the typed fields without parsing the rendered text.
+The canonical success is `{ kind: 'foreground', ...BashRunResult }` for a completed foreground process (with the executor's `sandbox` facts — `mode`/`denied`, optional `enforcement`/`runnerFailed` — projected when present) or `{ kind: 'background', taskId }` for a published task. The renderer preserves exactly `started background task <id>` for background acks; programmatic consumers use the typed fields without parsing the rendered text.
 
 When `run_in_background` is true, this plugin preflights `ctx.tasks.start()` before spawning, registers the calling agent as owner, and adapts the returned `BashProcess` handle into generic cancel/done/incremental-output hooks. The task runtime owns ids, cross-session isolation, completion notices, waiting, and disposal cleanup; this plugin only maps pwsh exit facts into task output and outcome detail. `enableRunInBackground: false` removes the parameter and rejects a forced background call at execution time.
 
@@ -78,7 +80,7 @@ Prefix-stable while visibility and the tool definition are unchanged. A restrict
 
 #### What the model sees
 
-The renderer emits the data-dependent stdout tail, then optional `[stderr]` and the stderr tail. Conditional lines are exactly `[output truncated; full output: <path>]`, `[timed out after <timeoutMs>ms]`, `[killed by signal: <signal>]`, and `[exit code: <exitCode>]` (nonzero exits only); an empty body renders as `(no output)`.
+The renderer emits the data-dependent stdout tail, then optional `[stderr]` and the stderr tail. Conditional lines are exactly `[output truncated; full output: <path>]`, `[sandbox: file access denied under <mode> mode]` plus the escalation hint `[sandbox: escalation available — …]` (only when the composition advertises escalation), `[timed out after <timeoutMs>ms]`, `[killed by signal: <signal>]`, and `[exit code: <exitCode>]` (nonzero exits only); an empty body renders as `(no output)`.
 
 #### Token effect
 
@@ -106,7 +108,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 #### What the model sees
 
-Validation and infrastructure failures are normalized as `Error: <message>`. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got <value>`, `run_in_background is disabled for this deployment (enableRunInBackground: false)`, `background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks`, and `tool call aborted`.
+Validation and infrastructure failures are normalized as `Error: <message>`. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got <value>`, `invalid escalation: sandbox_permissions requires a justification`, `invalid escalation: justification is only valid together with sandbox_permissions`, `invalid justification: expected a non-empty sentence`, `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`, the shared escalation failures (not strictly wider / no approval service / no agent to route / no approval channel / user rejected / was cancelled), `run_in_background is disabled for this deployment (enableRunInBackground: false)`, `background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks`, and `tool call aborted`.
 
 #### Token effect
 
@@ -118,7 +120,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
-- **No sandbox escalation** — `sandbox_permissions`/`justification` are absent; escalation waits for a Windows-confining executor (the bash tool's sandbox surface is not mirrored).
+- **ConstrainedLanguage under the Windows sandbox** — when the [Windows ACL sandbox](../../sandbox/sandbox-windows-acl/README.md) confines a call (read-only or workspace-write), the restricted token puts pwsh into ConstrainedLanguage mode: `Add-Type`, non-core .NET statics (`[System.IO.*]::`, `[math]::`), COM objects, and reflection fail with "only core types" errors, and the mode cannot be lifted from inside. The tool description teaches this contract to the model; the backend README owns the full limitation.
 - **No persistent shell or PTY** — every call starts a fresh `pwsh -Command`; the PTY backends are Linux/macOS-only today, and a Windows ConPTY persistent shell is roadmap work.
 - **PowerShell-dialect contract** — the model must write PowerShell (native paths, `$env:` variables), not bash; there is no dialect translation.
-- **Session-cwd identity is not canonicalized** — the workdir base is the session header cwd as-is, unlike the bash tool's sandbox-root-canonicalized identity; only the sandbox-less case applies here.
+- **Session-cwd identity is not canonicalized** — the workdir base is the session header cwd as-is, unlike the bash tool's sandbox-root-canonicalized identity. Under a confining executor the policy's workspace root IS canonicalized (by the shared policy service), so the workdir and the confinement root can diverge when the raw session cwd differs from its canonical form — a parity gap deferred to the shared shell-tool base extraction.

packages/bash/tool-pwsh/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-注册在 `ctx.bash` 执行器 seam 之上的模型可见 `pwsh` 工具。面向由 PowerShell 执行器（如 `@deepseek-ai/dsh-pwsh-local`）支撑 `ctx.bash` 的 Windows 组合；工具契约是 PowerShell 方言：原生 `C:\...` 路径与 `$env:NAME` 变量。行为与 `dsh-tool-bash` 逐调用对齐、减去 sandbox 面——通过通用任务运行时执行前台与 `run_in_background`、通过共享 `bash-env` 注册表管理 `DSH_*` 环境、以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。
+注册在 `ctx.bash` 执行器 seam 之上的模型可见 `pwsh` 工具。面向由 PowerShell 执行器（如 `@deepseek-ai/dsh-pwsh-local`）支撑 `ctx.bash` 的 Windows 组合；工具契约是 PowerShell 方言：原生 `C:\...` 路径与 `$env:NAME` 变量。行为与 `dsh-tool-bash` 逐调用对齐——通过通用任务运行时执行前台与 `run_in_background`、通过共享 `bash-env` 注册表管理 `DSH_*` 环境、sandbox 拒绝渲染与同轮次 `sandbox_permissions` 升级面、以及 bash 的 marker/截断渲染故事（干净退出不产生 marker）。
 
 需要已加载的执行器实现与 `bash-env` 插件；两者都存在前工具保持 pending（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。
 
@@ -21,6 +21,8 @@
 | `timeoutMs` | number | 超时覆盖值（毫秒）。执行器应用其配置的默认值与上限。 |
 | `workdir` | string | 本次调用的工作目录。默认取调用 agent（智能体）的会话 cwd（`session.header.cwd`），使每个会话在自己的工作区运行；相对 `workdir` 基于同一身份解析。 |
 | `run_in_background` | boolean | 立即返回 task id；不适用超时。 |
+| `sandbox_permissions` | string enum | 仅当已挂载 sandbox 执行器时才会公开（`ctx.bash.sandboxMode` 已定义）。用于对刚被 sandbox 拒绝的命令做一次性重试的更宽 sandbox 模式——取刚好足够的最窄更宽模式，要求 `justification` 并在执行**之前**经 `ctx.approval` 获得用户批准。未拓宽或无法获批的请求 fail-closed，不运行任何内容。 |
+| `justification` | string | 必须与 `sandbox_permissions` 一同提供：用一句话向用户解释为何正是这条命令需要更宽的访问。 |
 
 `command`、`workdir` 与 `timeoutMs` 在执行前经 `ctx.bash.resolve()` 按执行器配置默认值解析。workdir 默认值在工具层于 `resolve()` 之前从调用 agent 的 `session.header.cwd` 取得——每次会话的 cwd 必须来自 `exec.agent`，因为 N 个会话共享一个执行器；仅当没有会话 cwd 时执行器才回退到自己的配置 / `process.cwd()`。
 
@@ -28,9 +30,9 @@
 
 每次前台与后台模型 pwsh 调用都会通过共享的 [`dsh-bash-env`](../bash-env/) 注册表收到一份新收集的受信任 `DSH_*` 环境：`DSH_HOME`（Harness 主目录绝对路径）、`DSH_SHELL=1`、agent 的 `DSH_SESSION_ID`，以及活跃持久化后端定位到 JSONL 时的 `DSH_SESSION_JSONL`。向 `ctx.bashEnv` 贡献 `DSH_*` 事实的插件对 pwsh 调用与 bash 调用一视同仁。快照通过专用的 `BashExecRequest.dshEnv` 通道传递；`process.env` 永不被修改。描述只教授通用的 `$env:DSH_*` 约定，而不是点名持久化相关的变量。
 
-结果文本包含 stdout、可选的 `[stderr]` 段，然后是适用的截断、超时、signal 与退出 marker。干净退出（0、无 signal）不产生 marker；空体渲染为 `(no output)`。截断会链接一个安全的完整 spill 文件，或报告其不可用。超时独立于最终退出状态报告；非零退出仍是模型解读的结果而非 `isError`。Windows 上强制终止以无 signal 的 exit 1 结算，因此 `[killed by signal: …]` 在那里仅存在于 POSIX。只有基础设施失败——spawn 错误与中止（`tool call aborted`）——产生 `isError`。
+结果文本包含 stdout、可选的 `[stderr]` 段，然后是适用的截断、sandbox 拒绝（组合公开升级能力时带同轮次升级提示）、超时、signal 与退出 marker。干净退出（0、无 signal）不产生 marker；空体渲染为 `(no output)`。截断会链接一个安全的完整 spill 文件，或报告其不可用。超时独立于最终退出状态报告；非零退出仍是模型解读的结果而非 `isError`。Windows 上强制终止以无 signal 的 exit 1 结算，因此 `[killed by signal: …]` 在那里仅存在于 POSIX。只有基础设施失败——spawn 错误与中止（`tool call aborted`）——产生 `isError`。
 
-规范成功形态是已完成前台进程的 `{ kind: 'foreground', ...BashRunResult }` 或已发布任务的 `{ kind: 'background', taskId }`。渲染器对后台 ack 精确保留 `started background task <id>`；编程消费者使用类型化字段而不解析渲染文本。
+规范成功形态是已完成前台进程的 `{ kind: 'foreground', ...BashRunResult }`（存在时投影执行器的 `sandbox` 事实——`mode`/`denied`、可选的 `enforcement`/`runnerFailed`）或已发布任务的 `{ kind: 'background', taskId }`。渲染器对后台 ack 精确保留 `started background task <id>`；编程消费者使用类型化字段而不解析渲染文本。
 
 当 `run_in_background` 为 true 时，本插件在 spawn 前预检 `ctx.tasks.start()`，把调用 agent 注册为 owner，并将返回的 `BashProcess` 句柄适配为通用的 cancel/done/增量输出钩子。任务运行时拥有 id、跨会话隔离、完成通知、等待与清理；本插件只把 pwsh 退出事实映射进任务输出与结果明细。`enableRunInBackground: false` 会移除参数并在执行时拒绝强制的后台调用。
 
@@ -78,7 +80,7 @@ Non-zero exits are reported as `[exit code: N]` markers; investigate failures be
 
 #### What the model sees
 
-渲染器输出数据相关的 stdout 尾部，然后是可选的 `[stderr]` 与 stderr 尾部。条件行精确为 `[output truncated; full output: <path>]`、`[timed out after <timeoutMs>ms]`、`[killed by signal: <signal>]` 与 `[exit code: <exitCode>]`（仅非零退出）；空体渲染为 `(no output)`。
+渲染器输出数据相关的 stdout 尾部，然后是可选的 `[stderr]` 与 stderr 尾部。条件行精确为 `[output truncated; full output: <path>]`、`[sandbox: file access denied under <mode> mode]` 加升级提示 `[sandbox: escalation available — …]`（仅当组合公开升级能力时）、`[timed out after <timeoutMs>ms]`、`[killed by signal: <signal>]` 与 `[exit code: <exitCode>]`（仅非零退出）；空体渲染为 `(no output)`。
 
 #### Token effect
 
@@ -106,7 +108,7 @@ ack 是固定短行；任务输出按读取有界。
 
 #### What the model sees
 
-校验与基础设施失败规范化为 `Error: <message>`。本包的稳定消息包括 `invalid command: expected a non-empty string`、`invalid description: expected a non-empty string`、`invalid timeoutMs: expected a positive number, got <value>`、`run_in_background is disabled for this deployment (enableRunInBackground: false)`、`background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks` 与 `tool call aborted`。
+校验与基础设施失败规范化为 `Error: <message>`。本包的稳定消息包括 `invalid command: expected a non-empty string`、`invalid description: expected a non-empty string`、`invalid timeoutMs: expected a positive number, got <value>`、`invalid escalation: sandbox_permissions requires a justification`、`invalid escalation: justification is only valid together with sandbox_permissions`、`invalid justification: expected a non-empty sentence`、`sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`、共享的升级失败（非严格更宽、无审批服务、无 agent 可路由、无审批通道、用户拒绝、已取消）、`run_in_background is disabled for this deployment (enableRunInBackground: false)`、`background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks` 与 `tool call aborted`。
 
 #### Token effect
 
@@ -118,7 +120,7 @@ ack 是固定短行；任务输出按读取有界。
 
 ## Known Limitations and Deferred Work
 
-- **无 sandbox 升级** — 没有 `sandbox_permissions`/`justification`；升级等待 Windows-confining 执行器（bash 工具的 sandbox 面不被镜像）。
+- **Windows sandbox 下的 ConstrainedLanguage** — 当 [Windows ACL sandbox](../../sandbox/sandbox-windows-acl/README.md) 隔离某次调用（read-only 或 workspace-write）时，受限令牌使 pwsh 进入 ConstrainedLanguage 模式：`Add-Type`、非核心 .NET 静态调用（`[System.IO.*]::`、`[math]::`）、COM 对象与反射都会以“only core types”错误失败，且该模式无法从内部解除。工具描述把这一契约教给模型；后端 README 负责完整的限制说明。
 - **无持久 shell 或 PTY** — 每次调用都启动全新的 `pwsh -Command`；PTY 后端目前仅限 Linux/macOS，Windows ConPTY 持久 shell 属于路线图工作。
 - **PowerShell 方言契约** — 模型必须写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
-- **会话 cwd 身份不做规范化** — workdir 基座直接取会话头 cwd 原值，不同于 bash 工具经 sandbox-root 规范化的身份；此处只涉及无 sandbox 场景。
+- **会话 cwd 身份不做规范化** — workdir 基座直接取会话头 cwd 原值，不同于 bash 工具经 sandbox-root 规范化的身份。在隔离执行器下，策略的工作区根**会**被规范化（由共享的策略服务完成），因此当原始会话 cwd 与其规范化形态不同时，workdir 与隔离根可能不一致——这一 parity 差距留待共享 shell 工具基座提取时解决。

packages/bash/tool-pwsh/package.json

@@ -35,6 +35,7 @@
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "@deepseek-ai/dsh-tasks": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
+    "@deepseek-ai/dsh-user-approval": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
@@ -56,6 +57,7 @@
     "@deepseek-ai/dsh-tasks-local": "workspace:^",
     "@deepseek-ai/dsh-tool-tasks": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-approval": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }

packages/bash/tool-pwsh/src/index.ts

@@ -4,15 +4,17 @@
  * `@deepseek-ai/dsh-pwsh-local`) backs `ctx.bash`; the tool contract is
  * PowerShell-dialect: native `C:\...` paths and `$env:NAME` variables.
  *
- * Behavior mirrors `dsh-tool-bash` call-for-call minus the escalation
- * surface: foreground and `run_in_background` execution (background handles
- * register with the generic `ctx.tasks` runtime), the managed `DSH_*`
- * environment through the shared `bash-env` registry, the per-call sandbox
- * policy resolution (the calling session's mode and cwd travel to the
- * confining executor), and the bash marker/truncation rendering story. UI
- * presentation mirrors the bash tool's too: a completed
- * foreground call is a terminal card with the parsed exit-status pill, using
- * the shared exit-status parse from `@deepseek-ai/dsh-bash`.
+ * Behavior mirrors `dsh-tool-bash` call-for-call: foreground and
+ * `run_in_background` execution (background handles register with the
+ * generic `ctx.tasks` runtime), the managed `DSH_*` environment through the
+ * shared `bash-env` registry, the per-call sandbox policy resolution (the
+ * calling session's mode and cwd travel to the confining executor), the
+ * sandbox-denial rendering with the same-turn escalation surface
+ * (`sandbox_permissions` + `justification` resolved through
+ * `ctx.approval`), and the bash marker/truncation rendering story. UI
+ * presentation mirrors the bash tool's too: a completed foreground call is
+ * a terminal card with the parsed exit-status pill, using the shared
+ * exit-status parse from `@deepseek-ai/dsh-bash`.
  *
  * @module @deepseek-ai/dsh-tool-pwsh
  */
@@ -27,12 +29,15 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tasks'
 import type {} from '@deepseek-ai/dsh-bash-env'
-import type { SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox'
+import type {} from '@deepseek-ai/dsh-user-approval'
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import { ESCALATION_TARGETS, approveEscalation, validateEscalationArgs } from '@deepseek-ai/dsh-sandbox'
 import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import type { BashRunResult } from '@deepseek-ai/dsh-bash'
 import { parseExitStatus } from '@deepseek-ai/dsh-bash'
 import { processOutcome } from './background.ts'
 import { renderPwshProcessRead, renderPwshResult } from './render.ts'
+import type { RenderablePwshResult } from './render.ts'
 
 declare module '@deepseek-ai/dsh-tasks' {
   interface TaskKindMap {
@@ -61,6 +66,8 @@ interface PwshToolArgs {
   timeoutMs?: number
   workdir?: string
   run_in_background?: boolean
+  sandbox_permissions?: string
+  justification?: string
 }
 
 /** The canonical foreground result of one pwsh call (the `output.schema` value shape). */
@@ -73,6 +80,7 @@ interface PwshForegroundResult {
   timeoutMs: number
   stdout: { text: string; truncated: boolean; spillPath?: string }
   stderr: { text: string; truncated: boolean; spillPath?: string }
+  sandbox?: { mode: string; denied: boolean; enforcement?: string; runnerFailed?: boolean }
 }
 
 /* jscpd:ignore-start -- minimal mirror of dsh-tool-bash's validation and execute plumbing (Agent Note). */
@@ -86,21 +94,41 @@ function validatePwshArgs(args: PwshToolArgs): void {
   if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
     throw new Error(`invalid timeoutMs: expected a positive number, got ${JSON.stringify(args.timeoutMs)}`)
   }
+  // The escalation pairing (sandbox_permissions ⇔ justification, non-empty) is
+  // the shared rule both enforcing families validate identically.
+  validateEscalationArgs(args.sandbox_permissions, args.justification)
 }
 /* jscpd:ignore-end */
 
-function pwshDescription(backgroundEnabled: boolean): string {
+function pwshDescription(backgroundEnabled: boolean, escalationModes: readonly SandboxMode[]): string {
   const background = backgroundEnabled
     ? 'Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.'
     : 'Background execution is not available; long-running commands must finish within the timeout.'
-  return 'Execute a PowerShell command (`pwsh -Command`) and return its stdout/stderr. '
+  const base = 'Execute a PowerShell command (`pwsh -Command`) and return its stdout/stderr. '
     + 'Each call runs in a fresh pwsh process: no state (cwd, variables, functions) persists between calls — '
     + 'pass `workdir` instead of using `cd`. Paths use native Windows form (`C:\\...`); read environment '
     + 'variables with `$env:NAME`. Non-zero exits are reported as `[exit code: N]`. '
     + 'Current harness environment facts are exposed through managed `$env:DSH_*` variables; inspect them when needed. '
+    + 'Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. '
     + 'Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. '
     + 'On Windows a force-killed command settles as `[exit code: 1]` without a signal marker — treat it as an interruption, not a command failure. '
     + background
+  if (escalationModes.length === 0) return base
+  return base + ' Under the Windows sandbox, pwsh runs in PowerShell ConstrainedLanguage mode (read-only and '
+    + 'workspace-write): prefer cmdlets and core types (`[string]`, `[datetime]`, `[regex]`, `[guid]`); '
+    + '.NET static calls (`[System.IO.*]::`, `[math]::`), `Add-Type`, COM objects, and reflection fail '
+    + 'with "only core types" errors. `-f` formatting, property access, and core cmdlets work. '
+    + 'Attempting a command the sandbox may deny is safe and expected: run it and read the '
+    + 'marker rather than assuming the denial. When a command is denied and a wider mode would let it '
+    + 'succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry '
+    + 'the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) '
+    + 'plus a one-sentence `justification`. Do not detour through chat to ask permission first — the '
+    + 'approval prompt raised by that retry is how the user consents. If the session states approval '
+    + 'prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. '
+    + 'Never escalate speculatively: ground the request in a real denial — normally the one this command '
+    + 'just hit; escalating up front is fine only when this session already denied the same access. '
+    + 'A rejected escalation is final for that command — stop and explain, never work around '
+    + 'it — but it does not forbid attempting or escalating other commands later.'
 }
 
 /**
@@ -133,6 +161,14 @@ function canonicalPwshResult(result: BashRunResult): PwshForegroundResult {
     /* jscpd:ignore-start -- the canonical projection and background-handle shape mirror dsh-tool-bash's by design (Agent Note). */
     stdout: output(result.stdout),
     stderr: output(result.stderr),
+    ...result.sandbox !== undefined ? {
+      sandbox: {
+        mode: result.sandbox.mode,
+        denied: result.sandbox.denied,
+        ...result.sandbox.enforcement !== undefined ? { enforcement: result.sandbox.enforcement } : {},
+        ...result.sandbox.runnerFailed !== undefined ? { runnerFailed: result.sandbox.runnerFailed } : {},
+      },
+    } : {},
   }
 }
 
@@ -143,17 +179,56 @@ const BACKGROUND_OUTPUT_PROPERTIES = {
 } as const
 /* jscpd:ignore-end */
 
+/* jscpd:ignore-start -- deliberate mirror of dsh-tool-bash's apply() preamble (pwsh-tool-and-executor Agent Note). */
 export function apply(ctx: Context, config: Config = {}): void {
   const backgroundEnabled = config.enableRunInBackground ?? true
   const defaultMode = ctx.bash.sandboxMode
+  const escalationModes: readonly SandboxMode[] = defaultMode === undefined ? [] : ESCALATION_TARGETS
   const sandboxPolicy: SandboxPolicyService | undefined = defaultMode === undefined ? undefined : ctx.get('sandboxPolicy')
   if (defaultMode !== undefined && sandboxPolicy === undefined) {
     throw new Error('tool-pwsh: the mounted bash executor confines but ctx.sandboxPolicy is missing')
   }
+  /* jscpd:ignore-end */
   /** Resolve the complete standing policy for this call when a confining executor is mounted. */
   const resolveSandboxPolicy = (exec: ToolExecution): SandboxExecutionPolicy | undefined =>
     sandboxPolicy?.resolve(exec.agent === undefined ? {} : { session: exec.agent.session })
 
+  /* jscpd:ignore-start -- deliberate mirror of dsh-tool-bash's escalation resolver (pwsh-tool-and-executor Agent Note). */
+  /**
+   * Resolve a sandbox-escalation request through `ctx.approval` BEFORE
+   * anything executes, delegating the shared fail-closed sequence (strict
+   * widening, channel resolution, outcome mapping) to
+   * {@link approveEscalation}. This tool contributes only the composition
+   * guard (the fields are unadvertised without a sandboxing executor, yet
+   * schema validation checks advertised keys only, so an unadvertised
+   * `sandbox_permissions` still reaches execute) and the approval
+   * ingredients. The shared policy resolver is required whenever the
+   * executor advertises confinement, so a split composition fails at
+   * tool-plugin load.
+   */
+  const approvePwshEscalation = (
+    mode: string,
+    justification: string,
+    exec: ToolExecution,
+    standingPolicy: SandboxExecutionPolicy | undefined,
+  ): Promise<SandboxMode> => {
+    if (escalationModes.length === 0) {
+      throw new Error('sandbox_permissions is not available in this composition (no sandboxing executor to escalate)')
+    }
+    const effectiveMode = (standingPolicy as SandboxExecutionPolicy).mode
+    return approveEscalation(
+      { requestedMode: mode, justification, effectiveMode, subject: 'command' },
+      {
+        approver: ctx.get('approval'),
+        agent: exec.agent,
+        callId: exec.callId,
+        toolName: 'pwsh',
+        signal: exec.signal,
+      },
+    )
+  }
+  /* jscpd:ignore-end */
+
   ctx.systemPrompt.section({
     name: 'tool:pwsh',
     order: 105,
@@ -163,7 +238,8 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   ctx.tools.register(defineTool({
     name: 'pwsh',
-    description: pwshDescription(backgroundEnabled),
+    description: pwshDescription(backgroundEnabled, escalationModes),
+    /* jscpd:ignore-start -- deliberate mirror of dsh-tool-bash's parameter surface (pwsh-tool-and-executor Agent Note). */
     parameters: {
       command: { type: 'string', required: true, description: 'The PowerShell command to execute.' },
       description: {
@@ -178,7 +254,19 @@ export function apply(ctx: Context, config: Config = {}): void {
       ...backgroundEnabled ? {
         run_in_background: { type: 'boolean' as const, description: 'Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies.' },
       } : {},
+      ...escalationModes.length > 0 ? {
+        sandbox_permissions: {
+          type: 'string' as const,
+          enum: [...escalationModes],
+          description: 'The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.',
+        },
+        justification: {
+          type: 'string' as const,
+          description: 'Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access.',
+        },
+      } : {},
     },
+    /* jscpd:ignore-end */
     output: {
       // The foreground result wire shape mirrors dsh-tool-bash's by contract —
       // consumers of one must accept the other (see the pwsh-tool-and-executor
@@ -221,6 +309,16 @@ export function apply(ctx: Context, config: Config = {}): void {
                   spillPath: { type: 'string' },
                 },
               },
+              sandbox: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  mode: { type: 'string', required: true },
+                  denied: { type: 'boolean', required: true },
+                  enforcement: { type: 'string' },
+                  runnerFailed: { type: 'boolean' },
+                },
+              },
             },
           },
         ],
@@ -230,7 +328,7 @@ export function apply(ctx: Context, config: Config = {}): void {
         type: 'text',
         text: value.kind === 'background'
           ? `started background task ${value.taskId}`
-          : renderPwshResult(value),
+          : renderPwshResult(value as RenderablePwshResult, escalationModes),
       }],
     },
     /* jscpd:ignore-start -- the execute path mirrors dsh-tool-bash's by design (see the pwsh-tool-and-executor Agent Note). */
@@ -238,13 +336,19 @@ export function apply(ctx: Context, config: Config = {}): void {
       validatePwshArgs(args)
       // Description is display metadata; workdir defaults to the caller's session.
       const standingPolicy = resolveSandboxPolicy(exec)
+      const approvedMode = args.sandbox_permissions !== undefined && args.justification !== undefined
+        ? await approvePwshEscalation(args.sandbox_permissions, args.justification, exec, standingPolicy)
+        : undefined
+      const policy = approvedMode === undefined
+        ? standingPolicy
+        : { ...(standingPolicy as SandboxExecutionPolicy), mode: approvedMode }
       const workdir = resolveWorkdir(args.workdir, exec)
       const request = {
         command: args.command,
         ...workdir !== undefined ? { workdir } : {},
         ...args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {},
         dshEnv: ctx.bashEnv.collect(exec),
-        ...standingPolicy !== undefined ? { sandboxPolicy: standingPolicy } : {},
+        ...policy !== undefined ? { sandboxPolicy: policy } : {},
       }
       if (args.run_in_background === true) {
         // Undeclared keys are allowed, so schema omission also needs enforcement.
@@ -256,15 +360,11 @@ export function apply(ctx: Context, config: Config = {}): void {
           throw new Error('background tasks unavailable: load @deepseek-ai/dsh-tasks and @deepseek-ai/dsh-tool-tasks')
         }
         // The caller owns cancellation until ctx.tasks commits detached ownership.
-        /* v8 ignore start -- the bash twin's branch is exercised by its sandbox-approval mid-call abort;
-           pwsh has no approval surface, and the tool registry's pre-dispatch abort check intercepts
-           already-aborted signals first, so this mirror-only guard has no reachable trigger. */
         if (exec.signal.aborted) {
           const error = new HarnessError('tool call aborted', TOOL_ABORTED)
           error.name = 'AbortError'
           throw error
         }
-        /* v8 ignore end */
         // Task preflight finishes before the starter can spawn a process.
         const id = tasks.start({
           kind: 'pwsh',
@@ -275,7 +375,7 @@ export function apply(ctx: Context, config: Config = {}): void {
             return {
               cancel: () => void proc.kill(),
               done: proc.done.then(() => processOutcome(proc)),
-              readOutput: () => renderPwshProcessRead(proc.readOutput()),
+              readOutput: () => renderPwshProcessRead(proc.readOutput(), proc.sandbox, escalationModes),
             }
           },
         })

packages/bash/tool-pwsh/src/render.ts

@@ -1,17 +1,20 @@
 /**
  * Model-facing result rendering for the pwsh tool — the PowerShell twin of
- * `dsh-tool-bash`'s renderer minus the sandbox surface: stdout, a marked
- * stderr section, truncation notices with spill paths, then exit-status
- * markers. Non-zero exits are reported, not errored — the model decides how to
- * react; only infrastructure failures (spawn errors, aborts) surface as
- * isError results.
+ * `dsh-tool-bash`'s renderer: stdout, a marked stderr section, sandbox
+ * denial/runner-failure markers (with the same-turn escalation hint), and
+ * truncation notices with spill paths, then exit-status markers. Non-zero
+ * exits are reported, not errored — the model decides how to react; only
+ * infrastructure failures (spawn errors, aborts) surface as isError
+ * results.
  *
  * @module @deepseek-ai/dsh-tool-pwsh/render
  */
 
-import type { BashProcessRead, CollectedOutput } from '@deepseek-ai/dsh-bash'
+import type { BashProcessRead, BashSandboxInfo, CollectedOutput } from '@deepseek-ai/dsh-bash'
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
+import { escalationHintMarker, sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox'
 
-/* jscpd:ignore-start -- deliberate twin of dsh-tool-bash/render.ts minus the sandbox surface (Agent Note). */
+/* jscpd:ignore-start -- deliberate twin of dsh-tool-bash/render.ts (Agent Note). */
 
 /** Append the truncation notice (with the full-output spill path) to a stream's text. */
 function streamText(output: CollectedOutput): string {
@@ -27,6 +30,7 @@ export interface RenderablePwshResult {
   timeoutMs: number
   stdout: CollectedOutput
   stderr: CollectedOutput
+  sandbox?: BashSandboxInfo
 }
 
 /**
@@ -34,9 +38,15 @@ export interface RenderablePwshResult {
  * stderr section, then exit-status markers, matching the bash tool's story —
  * a clean exit (0, no signal) produces no marker.
  * @param result - the completed foreground run from the executor.
+ * @param escalationModes - the escalation targets this composition advertises;
+ *   non-empty adds the same-turn escalation hint after a denial marker
+ *   (default `[]`: no hint).
  * @returns the model-facing text: output body (or `(no output)`), then any timeout/signal/exit markers, each on its own line.
  */
-export function renderPwshResult(result: RenderablePwshResult): string {
+export function renderPwshResult(
+  result: RenderablePwshResult,
+  escalationModes: readonly SandboxMode[] = [],
+): string {
   const out = streamText(result.stdout)
   const err = streamText(result.stderr)
 
@@ -49,6 +59,14 @@ export function renderPwshResult(result: RenderablePwshResult): string {
   if (body.length === 0) body = '(no output)'
 
   const markers: string[] = []
+  // Keep the exit marker last because parseExitStatus anchors there.
+  if (result.sandbox?.denied) {
+    markers.push(sandboxDenialMarker(result.sandbox.mode))
+    // Hint only when the composition exposes escalation, before the final exit marker.
+    if (escalationModes.length > 0) {
+      markers.push(escalationHintMarker('command'))
+    }
+  }
   // A command may trap the termination and exit 0 after timeout; still report interruption.
   if (result.timedOut) markers.push(`[timed out after ${result.timeoutMs}ms]`)
   if (result.signal !== null) {
@@ -67,14 +85,28 @@ export function renderPwshResult(result: RenderablePwshResult): string {
  * sees: the incremental delta, plus the lossy-read notice (with full-stream
  * spill paths) when in-memory truncation dropped unread bytes.
  * @param read - one incremental read from the process handle.
- * @returns the delta text with any loss notice appended.
+ * @param sandbox - settled sandbox facts, when this was a confined process.
+ * @param escalationModes - escalation targets advertised by this composition.
+ * @returns the delta text with any loss or sandbox notice appended.
  */
-export function renderPwshProcessRead(read: BashProcessRead): string {
+export function renderPwshProcessRead(
+  read: BashProcessRead,
+  sandbox?: BashSandboxInfo,
+  escalationModes: readonly SandboxMode[] = [],
+): string {
   const notices: string[] = []
   if (read.lossy) {
     const paths = [read.stdoutSpillPath, read.stderrSpillPath].filter((path): path is string => path !== undefined)
     notices.push(`[some output was dropped from memory; full output: ${paths.length > 0 ? paths.join(', ') : '(unavailable)'}]`)
   }
+  if (sandbox?.runnerFailed) {
+    notices.push(`[sandbox: the sandbox runner itself failed under ${sandbox.mode} mode — the command did not run; this is a sandbox problem, not a command failure]`)
+  } else if (sandbox?.denied) {
+    notices.push(sandboxDenialMarker(sandbox.mode))
+    if (escalationModes.length > 0) {
+      notices.push(escalationHintMarker('command'))
+    }
+  }
   if (notices.length === 0) return read.delta
   return `${read.delta}${read.delta.length > 0 && !read.delta.endsWith('\n') ? '\n' : ''}${notices.join('\n')}`
 }

packages/bash/tool-pwsh/tests/tools.spec.ts

@@ -5,11 +5,12 @@
  * text, truncation, timeout, abort, nonzero exits, background handles — so
  * these tests verify the schema, argument validation, workdir derivation,
  * managed `DSH_*` collection, abort translation, canonical result projection,
- * rendering, background task wiring, and the UI presenters. Real-pwsh behavior
+ * sandbox denial rendering with the escalation surface, rendering,
+ * background task wiring, and the UI presenters. Real-pwsh behavior
  * is pinned separately in integration.spec.ts.
  */
 
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { mkdtempSync, realpathSync } from 'node:fs'
 import { tmpdir } from 'node:os'
@@ -22,6 +23,8 @@ import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
+import ApprovalService from '@deepseek-ai/dsh-user-approval'
+import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval'
 import { BashExecutor } from '@deepseek-ai/dsh-bash'
 import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash'
 import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
@@ -155,9 +158,12 @@ async function setupWithTasks(toolConfig: Partial<ToolPwsh.Config> = {}, dshHome
  * A CONFINING fake executor (`sandboxMode` advertised): the tool must resolve
  * the calling session's standing policy and stamp it on the request, exactly
  * like the bash tool — the per-session sandbox-policy regression surface.
+ * Records each confined mode and returns scriptable sandbox facts so the
+ * escalation and rendering surfaces are testable without a real backend.
  */
 class ConfiningFakeBash extends BashExecutor {
   requests: BashExecRequest[] = []
+  modes: Array<string | undefined> = []
 
   override get sandboxMode() {
     return 'read-only' as const
@@ -176,29 +182,73 @@ class ConfiningFakeBash extends BashExecutor {
     }
   }
 
-  override async run(_spec: BashExecSpec): Promise<BashRunResult> {
-    return runResult('ok\n')
+  override async run(spec: BashExecSpec): Promise<BashRunResult> {
+    this.modes.push(spec.sandboxPolicy?.mode)
+    return runResult('ok\n', {
+      sandbox: {
+        mode: spec.sandboxPolicy?.mode ?? 'read-only',
+        denied: false,
+        ...spec.command === 'without optional sandbox facts'
+          ? {}
+          : { enforcement: 'full' as const, runnerFailed: false },
+      },
+    })
   }
 
-  override start(_spec: BashExecSpec): BashProcess {
+  override start(spec: BashExecSpec): BashProcess {
+    this.modes.push(spec.sandboxPolicy?.mode)
     return fakeProcess()
   }
 }
 
-/** Sandboxed composition: the shared policy service + a confining executor + the pwsh tool. */
-async function setupSandboxed(toolConfig: Partial<ToolPwsh.Config> = {}) {
+/** Sandboxed composition: the shared policy service + a confining executor + the pwsh tool (+ optional approval). */
+async function setupSandboxed(withApproval = false) {
   const ctx = new Context()
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(AgentRegistry)
+  await ctx.plugin(LocalTaskService)
+  await ctx.plugin(ToolTasks)
   await ctx.plugin(BashEnvPlugin)
   await ctx.plugin(SandboxPolicyService, {})
   await ctx.plugin(ConfiningFakeBash)
-  await ctx.plugin(ToolPwsh, toolConfig)
+  if (withApproval) await ctx.plugin(ApprovalService)
+  await ctx.plugin(ToolPwsh)
   const bash = ctx.bash as ConfiningFakeBash
   return { ctx, bash }
 }
 
+/**
+ * Build a fake {@link Agent} whose session log carries the sandbox-policy
+ * mode-override event the escalation flow evaluates against, with an
+ * appendable log (the approval service records decisions through
+ * `session.append`).
+ */
+function sandboxAgent(
+  mode?: 'read-only' | 'workspace-write' | 'danger-full-access',
+  ctx?: Context,
+  onAppend?: (type: string) => void,
+): Agent {
+  const events: Array<{ type: string; data?: Record<string, unknown> }> = [{ type: 'turn/start' }]
+  if (mode !== undefined) events.push({ type: 'sandbox/mode', data: { mode } })
+  const id = SessionId('sandbox-session')
+  return {
+    id,
+    ...ctx === undefined ? {} : { ctx: ctx.plugin(() => {}).ctx },
+    session: {
+      id,
+      header: { version: 0, id, createdAt: 0 },
+      events,
+      append: (type: string, data: Record<string, unknown>) => {
+        const event = { type, data }
+        events.push(event)
+        onAppend?.(type)
+        return event
+      },
+    },
+  } as unknown as Agent
+}
+
 /**
  * Build a fake {@link Agent} with the shared agent/session identity, give it a
  * dedicated lifecycle fiber for `Agent.ctx`, and register it in `ctx.agents`.
@@ -494,6 +544,154 @@ describe('per-call sandbox policy resolution', () => {
   })
 })
 
+describe('sandbox escalation through ctx.approval', () => {
+  const escalate = {
+    command: 'Write-Output ok',
+    description: 'test escalation',
+    sandbox_permissions: 'workspace-write',
+    justification: 'the command needs workspace writes',
+  }
+
+  it('advertises the sandbox fields, the escalation clause, and the ConstrainedLanguage contract', async () => {
+    const { ctx } = await setupSandboxed()
+    const schema = ctx.tools.schemas().find(item => item.name === 'pwsh')!
+    const properties = schema.parameters.properties as Record<string, { enum?: string[] }>
+    expect(properties['sandbox_permissions']?.enum).toEqual(['workspace-write', 'danger-full-access'])
+    expect(schema.description).toContain('approval prompt')
+    expect(schema.description).toContain('ConstrainedLanguage')
+
+    for (const args of [
+      { command: 'Write-Output ok', description: 'd', sandbox_permissions: 'workspace-write' },
+      { command: 'Write-Output ok', description: 'd', justification: 'why' },
+      { command: 'Write-Output ok', description: 'd', sandbox_permissions: 'workspace-write', justification: ' ' },
+    ]) {
+      expect((await call(ctx, 'pwsh', args)).isError).toBe(true)
+    }
+  })
+
+  it('the escalation fields and the ConstrainedLanguage clause stay out of sandbox-less compositions', async () => {
+    const { ctx } = await setup()
+    const schema = ctx.tools.schemas().find(item => item.name === 'pwsh')!
+    expect(schema.description).not.toContain('ConstrainedLanguage')
+    expect(schema.description).not.toContain('sandbox_permissions')
+    expect(schema.parameters.properties).not.toHaveProperty('sandbox_permissions')
+  })
+
+  it('rejects injected escalation without a sandbox and non-widening escalation without prompting', async () => {
+    const plain = await setup()
+    expect(text(await call(plain.ctx, 'pwsh', escalate))).toContain('not available in this composition')
+
+    const { ctx } = await setupSandboxed(true)
+    const prompted = vi.fn()
+    ctx.on('approval/request', () => { prompted(); return Promise.resolve<ApprovalOutcome>('allowed-once') })
+    const result = await call(ctx, 'pwsh', { ...escalate, sandbox_permissions: 'workspace-write' }, sandboxAgent('workspace-write'))
+    expect(text(result)).toContain('not strictly wider')
+    expect(prompted).not.toHaveBeenCalled()
+
+    const malformed = sandboxAgent()
+    ;(malformed.session.events as unknown as Array<{ type: string; data: { mode: string } }>).push({
+      type: 'sandbox/mode',
+      data: { mode: 'unknown-mode' },
+    })
+    expect(text(await call(ctx, 'pwsh', escalate, malformed))).toContain('not strictly wider')
+  })
+
+  it('fails closed when approval cannot be routed', async () => {
+    const withoutService = await setupSandboxed()
+    expect(text(await call(withoutService.ctx, 'pwsh', escalate, sandboxAgent()))).toContain('no approval service')
+
+    const withService = await setupSandboxed(true)
+    expect(text(await call(withService.ctx, 'pwsh', escalate))).toContain('no agent to route')
+    expect(text(await call(withService.ctx, 'pwsh', escalate, sandboxAgent()))).toContain('no approval channel')
+  })
+
+  it.each([
+    ['rejected', 'user rejected'],
+    ['cancelled', 'was cancelled'],
+  ] as const)('maps an approval %s to its distinct failure', async (outcome, message) => {
+    const { ctx, bash } = await setupSandboxed(true)
+    ctx.on('approval/request', () => Promise.resolve<ApprovalOutcome>(outcome))
+    const result = await call(ctx, 'pwsh', escalate, sandboxAgent())
+    expect(text(result)).toContain(message)
+    expect(bash.modes).toEqual([])
+  })
+
+  it('runs a granted foreground or background call under the approved mode', async () => {
+    const { ctx, bash } = await setupSandboxed(true)
+    ctx.on('approval/request', () => Promise.resolve<ApprovalOutcome>('allowed-once'))
+    const agent = sandboxAgent(undefined, ctx)
+    ctx.agents.register(agent)
+    const foreground = await ctx.tools.execute({
+      callId: CallId('sandbox-signal'),
+      name: 'pwsh',
+      arguments: escalate,
+      agent,
+      signal: new AbortController().signal,
+    })
+    expect(foreground.isError).toBe(false)
+    const background = await call(ctx, 'pwsh', { ...escalate, run_in_background: true }, agent)
+    expect(text(background)).toBe('started background task pwsh-1')
+    expect(bash.modes).toEqual(['workspace-write', 'workspace-write'])
+  })
+
+  it('does not publish detached work when cancellation follows the escalation grant', async () => {
+    const { ctx, bash } = await setupSandboxed(true)
+    const controller = new AbortController()
+    const agent = sandboxAgent(undefined, ctx, (type) => {
+      if (type === 'approval/decided') controller.abort()
+    })
+    ctx.agents.register(agent)
+    ctx.on('approval/request', () => Promise.resolve<ApprovalOutcome>('allowed-once'))
+    const start = vi.spyOn(bash, 'start')
+
+    const result = await ctx.tools.execute({
+      callId: CallId('cancelled-escalation-background'),
+      name: 'pwsh',
+      arguments: { ...escalate, run_in_background: true },
+      agent,
+      signal: controller.signal,
+    })
+
+    expect(result.error).toEqual({
+      message: 'tool call aborted',
+      info: { name: 'AbortError', code: TOOL_ABORTED },
+    })
+    expect(text(result)).toBe('Error: tool call aborted')
+    expect(start).not.toHaveBeenCalled()
+  })
+
+  it('uses the session override for ordinary calls and evaluates widening against it', async () => {
+    const { ctx, bash } = await setupSandboxed(true)
+    const agent = sandboxAgent('workspace-write')
+    await call(ctx, 'pwsh', { command: 'Write-Output hi', description: 'ordinary' }, agent)
+    ctx.on('approval/request', () => Promise.resolve<ApprovalOutcome>('allowed-once'))
+    await call(ctx, 'pwsh', { ...escalate, sandbox_permissions: 'danger-full-access' }, agent)
+    expect(bash.modes).toEqual(['workspace-write', 'danger-full-access'])
+  })
+
+  it('omits sandbox facts the executor did not acquire from the canonical result', async () => {
+    const { ctx } = await setupSandboxed()
+    const result = await call(ctx, 'pwsh', {
+      command: 'without optional sandbox facts',
+      description: 'exercise optional sandbox facts',
+    })
+    if (result.isError) throw new Error('expected foreground pwsh success')
+    expect(result.value).toMatchObject({
+      kind: 'foreground',
+      sandbox: { mode: 'read-only', denied: false },
+    })
+    expect((result.value as { sandbox: object }).sandbox).not.toHaveProperty('enforcement')
+    expect((result.value as { sandbox: object }).sandbox).not.toHaveProperty('runnerFailed')
+  })
+
+  it('keeps the exhaustiveness backstop for a rogue approval implementation', async () => {
+    const { ctx } = await setupSandboxed(true)
+    ctx.approval.request = () => Promise.resolve('rogue' as ApprovalOutcome)
+    const result = await call(ctx, 'pwsh', escalate, sandboxAgent())
+    expect(text(result)).toContain('unreachable variant in EscalationOutcome')
+  })
+})
+
 describe('background execution through the task runtime', () => {
   it('run_in_background acks with the task id, readable through the REAL task_output tool', async () => {
     const { ctx } = await setupWithTasks()
@@ -738,6 +936,35 @@ describe('UI presentation', () => {
   })
 })
 
+describe('renderPwshResult sandbox markers', () => {
+  const base = {
+    exitCode: 0,
+    signal: null,
+    timedOut: false,
+    timeoutMs: 1000,
+    stdout: { text: 'out\n', truncated: false },
+    stderr: { text: '', truncated: false },
+  }
+
+  it('a denied run reports the denial marker before the exit marker', () => {
+    expect(renderPwshResult({ ...base, exitCode: 2, sandbox: { mode: 'read-only', denied: true } }))
+      .toBe('out\n[sandbox: file access denied under read-only mode]\n[exit code: 2]')
+  })
+
+  it('hints only when the composition advertises escalation', () => {
+    const denied = { ...base, sandbox: { mode: 'read-only' as const, denied: true } }
+    expect(renderPwshResult(denied, ['workspace-write'])).toBe(
+      'out\n[sandbox: file access denied under read-only mode]\n'
+      + '[sandbox: escalation available — retry this exact command once with sandbox_permissions '
+      + '(the narrowest wider mode that suffices) + justification; the approval prompt asks the user]',
+    )
+  })
+
+  it('a confined run without a denial adds no sandbox marker', () => {
+    expect(renderPwshResult({ ...base, sandbox: { mode: 'read-only', denied: false } })).toBe('out\n')
+  })
+})
+
 describe('renderPwshProcessRead', () => {
   const base: BashProcessRead = { delta: 'out\n', lossy: false }
 
@@ -774,6 +1001,20 @@ describe('renderPwshProcessRead', () => {
     expect(renderPwshProcessRead({ delta: 'tail\n', lossy: true }))
       .toBe('tail\n[some output was dropped from memory; full output: (unavailable)]')
   })
+
+  it('appends the runner-failed notice (denial outranked)', () => {
+    expect(renderPwshProcessRead({ delta: 'x', lossy: false }, { mode: 'read-only', denied: true, runnerFailed: true }))
+      .toBe('x\n[sandbox: the sandbox runner itself failed under read-only mode — the command did not run; this is a sandbox problem, not a command failure]')
+  })
+
+  it('appends the denial marker and hints only when escalation is advertised', () => {
+    expect(renderPwshProcessRead({ delta: 'x', lossy: false }, { mode: 'read-only', denied: true }))
+      .toBe('x\n[sandbox: file access denied under read-only mode]')
+    expect(renderPwshProcessRead({ delta: 'x', lossy: false }, { mode: 'read-only', denied: true }, ['workspace-write']))
+      .toBe('x\n[sandbox: file access denied under read-only mode]\n'
+        + '[sandbox: escalation available — retry this exact command once with sandbox_permissions '
+        + '(the narrowest wider mode that suffices) + justification; the approval prompt asks the user]')
+  })
 })
 
 describe('processOutcome', () => {

packages/bash/tool-pwsh/tsconfig.json

@@ -38,6 +38,12 @@
     {
       "path": "../../core/system-prompt"
     },
+    {
+      "path": "../../bash/bash-env"
+    },
+    {
+      "path": "../../ui/user-approval"
+    },
     {
       "path": "../../sandbox/sandbox"
     },