dsh-pwsh-plugin 0.2.18 → 0.2.19

package/README.md

@@ -116,7 +116,7 @@ Three constraints that cost real time to find:
   will hold two of them; registration is keyed by name, and a second `pwsh_run` is a hard error at boot.
   `--dump-config` shows the duplicate plainly — that is the check to run after switching.
 
-The three files in `plugin/` (`index.mjs`, `session.mjs`, `session-server.ps1`) must stay together —
+The files in `plugin/` (`index.mjs`, `config.mjs`, `native-pwsh-guard.mjs`, `session.mjs`, `session-server.ps1`) must stay together —
 `index.mjs` reads the `.ps1` at load time and ships it to the child as `-EncodedCommand`.
 
 ## The tools
@@ -146,6 +146,7 @@ requirements are explicitly refused.
 | `maxSessions` | `4` | Per-plugin process limit, isolated by DSH session ID. If all are busy, new sessions are refused with a retry message. |
 | `maxOutputBytes` | `8388608` | UTF-8 payload budget per call, including record separators; errors have a separate 65536-byte budget. Framing and display labels are excluded. Truncation is reported. |
 | `allowUnconfined` | `false` | `true` = start a session even when the sandbox policy service is missing. |
+| `enforcePwshRun` | `false` | Refuse ordinary native `pwsh` calls before execution and direct the model to `pwsh_run`. |
 
 `allowUnconfined` is the one deliberate escape hatch. In a normal deployment `ctx.sandboxPolicy` is always
 present; when it is missing the composition is incomplete, and the plugin **refuses to start** rather than
@@ -154,6 +155,39 @@ quietly running an unconstrained session.
 Hot reload (`patchReload: live`) re-runs `apply`. Tool registration and process cleanup both hang off
 `ctx.effect`, so it does not trip `tool "pwsh_run" is already registered`.
 
+### Enforce pwsh_run
+
+This is a profile-wide plugin setting. Configure it once for all presets and sessions in that profile;
+do not add it to each preset or insert a second `pwsh-run` entry when the bundle already provides one.
+
+Open **pwsh settings** in the settings sidebar, enable **Require pwsh_run**, then select **Save**. The plugin row's configuration button opens the same form. Changes stay as a draft until saved; leaving the page discards the draft. **Restore configuration default** removes the profile override.
+
+Saving updates only the routing switch through DSH's settings service and preserves running PowerShell processes and session state. The page reports the value accepted by the host, protects against conflicting writes, and disables editing on read-only deployments. It follows the host's Chinese or English language setting.
+
+For hosts without the settings UI, override the existing plugin entry in the profile's `cordis.patch.yml`:
+
+```yaml
+- id: pwsh-run
+  config:
+    enforcePwshRun: true
+```
+
+Ordinary native `pwsh` calls are refused before execution. The response tells the model to move
+`command` into `pwsh_run`'s `script` and preserve `workdir` and `timeoutMs`.
+The command is neither executed first nor replayed automatically. Both native dispatch and
+PTC's `tools.pwsh(...)` pass through this check.
+
+Three native entry points remain available: read-only sessions (unsupported by the persistent
+session), jobs with `run_in_background: true`, and per-call escalation requests with a nonempty
+`justification` and a requested mode strictly wider than the current one. Escalation still needs
+host approval; a same-mode flag does not qualify. The guard resolves the actual session policy
+on each call, so mode changes take effect on the next invocation.
+
+Disabling the option, removing the guard through hot reload, or uninstalling restores native
+`pwsh` behavior. The option defaults to off. Live configuration requires `ctx.tools.guard()`;
+a host without this API is rejected explicitly so enabling the setting cannot silently go unprotected.
+The guard covers the DSH `pwsh` tool entry, not PowerShell launched inside bash, Node or other scripts.
+
 ## Sandbox
 
 The persistent process is wrapped **once, at launch**, in the restricted argv that `ctx.sandbox.confine`
@@ -271,10 +305,15 @@ session — lives in **[docs/runtime-notes.md](docs/runtime-notes.md)**. The sho
 ```
 plugin/
   index.mjs           tool registration, sandbox wiring, timeouts
+  config.mjs          native schema; the routing switch is volatile
+  native-pwsh-guard.mjs  optional native pwsh invocation guard
   session.mjs         the session object: framing, queue, base64 encode, boot argv
   session-server.ps1  the PowerShell side: runspace, stream tagging, sentinels
+client/index.js      localized settings page using DSH native controls
 test/
+  settingstest.mjs    persistence, conflicts, live routing and process preservation
   support.mjs         locates a DSH install; converts Windows paths to /mnt form
+  routingtest.mjs     native/PTC routing, exceptions, unload and reload
   protocoltest.mjs    frame limits, UTF-8 budgets, startup cleanup
   lifecycletest.mjs   policy changes, session pool, cancellation
   itest.mjs           protocol and session core
@@ -296,6 +335,9 @@ FINDINGS.md          every measurement and the reasoning behind the design
 
 ```bash
 cd <checkout>
+pnpm install --ignore-scripts --config.auto-install-peers=false
+node test/settingstest.mjs                  # 19: native settings form, persistence, routing and state
+node test/routingtest.mjs                   # 30: native/PTC routing, exceptions, disable and unload
 node test/protocoltest.mjs                  #  6: frame limits, UTF-8 budgets, startup cleanup
 node test/lifecycletest.mjs                 # 16: policy, pool, concurrency, cancellation, unload
 PWSH_BIN='pwsh' node test/itest.mjs          # 30: protocol and session core
@@ -308,10 +350,11 @@ node test/denialtest.mjs                     # 11: sandbox-denial hint (no spawn
 node test/metatest.mjs                       # 23: plugin-page metadata (no spawn, runs anywhere)
 ```
 
-Ten scripts, **163 assertions**, none of which needs DSH to be running — just node 24, PowerShell 7 and a
+Twelve scripts, **212 assertions**, none of which needs DSH to be running — just node 24, PowerShell 7 and a
 DSH install to borrow `node_modules` from. Tests that need a DSH runtime locate one automatically
 (`DSH_MODULES`, `DSH_MODULES_ASAR`, or by walking up from the working directory) and print a `SKIP` hint
-instead of failing when none is found.
+when none is found. The settings integration test exits unsuccessfully if its host modules are unavailable;
+a release validation must complete every suite without skips.
 
 ### Releasing
 

package/README.zh-CN.md

@@ -101,7 +101,7 @@ $env:DSH_HOME = '<DSH_HOME>'        # 桌面 App 自己用的那个数据根
   合成后的配置树里就有两条；注册按名字查重，第二个 `pwsh_run` 在启动时是硬错误。`--dump-config` 一眼就能看出重复 ——
   切换后跑这一条。
 
-`plugin/` 下三个文件（`index.mjs`、`session.mjs`、`session-server.ps1`）必须放在一起：
+`plugin/` 下的 `index.mjs`、`config.mjs`、`native-pwsh-guard.mjs`、`session.mjs`、`session-server.ps1` 必须放在一起：
 `index.mjs` 在加载时读那个 `.ps1`，再以 `-EncodedCommand` 送给子进程。
 
 ## 工具接口
@@ -129,6 +129,7 @@ Warning、Verbose、Information、Debug 分别带类型前缀，错误和最内
 | `maxSessions` | `4` | 每个插件实例的会话上限，以 DSH session ID 隔离；全部忙时拒绝新会话并提示重试。 |
 | `maxOutputBytes` | `8388608` | 每次调用普通输出正文的 UTF-8 字节预算（含记录换行）；错误另留 65536 字节。协议与显示标签不计入，截断会明确提示。 |
 | `allowUnconfined` | `false` | `true` = 沙箱策略服务缺席时也起会话。 |
+| `enforcePwshRun` | `false` | 开启后，在执行前拒绝普通原生 `pwsh` 调用，提示改用 `pwsh_run`。 |
 
 `allowUnconfined` 是唯一一条「明知故犯」的开关。正常部署下 `ctx.sandboxPolicy` 一定在；缺席说明组合
 不完整，这时插件**拒绝启动**，而不是悄悄跑一个不受约束的会话。
@@ -136,6 +137,35 @@ Warning、Verbose、Information、Debug 分别带类型前缀，错误和最内
 热重载（`patchReload: live`）会重新 `apply`。工具注册与进程清理都挂在 `ctx.effect` 上，不会触发
 `tool "pwsh_run" is already registered`。
 
+### 强制使用 pwsh_run
+
+这是 profile 的公共插件配置：同一 profile 只需设置一次，覆盖其中不同 preset 和会话，
+不需要在每个 preset 中重复添加。插件已由 bundle 加载时，也不要重复插入 `pwsh-run` 条目。
+
+在设置侧栏打开 **pwsh 设置**，开启 **强制使用 pwsh_run**，再点 **保存**。插件列表的配置按钮也会打开同一张表单。编辑只产生草稿，离开页面会丢弃未保存的修改；**恢复配置默认值** 会移除当前 profile 的覆盖。
+
+保存通过 DSH 设置服务热更新路由开关，保留正在运行的 PowerShell 进程和会话状态。页面显示宿主确认的已保存值，校验配置修订冲突，并在只读部署下禁用修改。页面随宿主语言显示中文或英文。
+
+没有设置界面的宿主仍可在 profile 的 `cordis.patch.yml` 中覆盖已有插件条目：
+
+```yaml
+- id: pwsh-run
+  config:
+    enforcePwshRun: true
+```
+
+守卫会在命令执行前拒绝普通原生 `pwsh` 调用，并提示模型把 `command` 改为
+`pwsh_run` 的 `script`；`workdir` 和 `timeoutMs` 保持原值。原生命令不会先执行一次，
+也不会自动重放。原生工具和 PTC 中的 `tools.pwsh(...)` 都经过同一道检查。
+
+三个必要入口仍交给原生工具：只读会话（常驻会话不支持）、`run_in_background: true`
+的后台任务、以及带非空 `justification` 且申请权限确实高于当前模式的逐次提权请求。
+提权仍需宿主审批；同级权限标记不放行。每次按实际会话读取模式，切换权限后立即按新模式判断。
+
+配置关闭、热重载移除守卫或卸载插件后，原生 `pwsh` 恢复原有行为。
+开关默认关闭。热更新配置需要宿主提供 `ctx.tools.guard()`；缺少此 API 时会明确拒绝加载，避免设置开启后实际没有拦截。
+它只管理 DSH 的 `pwsh` 工具入口，不解析 `bash`、Node 或其他脚本内启动的 PowerShell。
+
 ## 沙箱
 
 常驻进程在**启动时**整体包进 `ctx.sandbox.confine` 返回的受限 argv。Windows ACL 沙箱用的是
@@ -239,10 +269,15 @@ Windows 上打，那份文件到手时是 `0644` —— 探测发现它属于当
 ```
 plugin/
   index.mjs           工具注册、沙箱接线、超时
+  config.mjs          宿主配置 schema；路由开关支持热更新
+  native-pwsh-guard.mjs  可选的原生 pwsh 调用守卫
   session.mjs         会话对象：分帧、队列、base64、启动 argv
   session-server.ps1  PowerShell 侧：runspace、流打标、哨兵
+client/index.js      使用宿主原生控件的双语设置页
 test/
+  settingstest.mjs    配置持久化、冲突、即时路由与进程保留
   support.mjs         定位 DSH 安装；Windows 路径转 /mnt 形式
+  routingtest.mjs     原生与 PTC 路由、必要例外及卸载恢复
   protocoltest.mjs    分帧、UTF-8 预算、启动清理
   lifecycletest.mjs   权限切换、会话池与取消
   itest.mjs           协议与会话本体
@@ -264,6 +299,9 @@ FINDINGS.md          全部实测数据与设计理由
 
 ```bash
 cd <检出目录>
+pnpm install --ignore-scripts --config.auto-install-peers=false
+node test/settingstest.mjs                  # 19：原生设置表单、持久化、路由和进程保留
+node test/routingtest.mjs                   # 30：原生/PTC 路由、例外、关闭与卸载
 node test/protocoltest.mjs                  #  6：帧边界、字节预算、启动清理
 node test/lifecycletest.mjs                 # 16：权限切换、池、并发、取消、卸载
 PWSH_BIN='pwsh' node test/itest.mjs          # 30：协议与会话本体
@@ -276,9 +314,10 @@ node test/denialtest.mjs                     # 11：沙箱拒绝提示（不起
 node test/metatest.mjs                       # 23：插件页元数据（不起子进程，哪儿都能跑）
 ```
 
-十份脚本合计 **163 项**，都不需要 DSH 在跑 —— 只要 node 24、PowerShell 7，以及一个能借
+十二份脚本合计 **212 项**，都不需要 DSH 在跑 —— 只要 node 24、PowerShell 7，以及一个能借
 `node_modules` 的 DSH 安装。需要 DSH 运行时的测试会自动找（`DSH_MODULES`、`DSH_MODULES_ASAR`，
-或从工作目录逐级向上），找不到时打一行 `SKIP` 提示而不是失败。
+或从工作目录逐级向上），找不到时打印 `SKIP` 提示。设置集成测试缺少宿主模块时会非零退出；
+发版验收必须跑完全部测试，不能有跳过。
 
 ### 发版
 

package/client/index.js

@@ -0,0 +1,94 @@
+window.__ModuleLoader__.load({
+  id: 'dsh-pwsh-plugin',
+  factory: (require) => {
+    const React = require('react')
+    const { SettingsForm, SettingsFormModel, Switch, Button } = require('@deepseek-ai/dsh-client-ui-primitives')
+    const h = React.createElement
+    const NS = 'pwsh-run'
+    const FIELD = 'enforcePwshRun'
+    const COPY = {
+      zh: {
+        title: 'pwsh 设置', group: '工具路由', label: '强制使用 pwsh_run',
+        summary: '控制模型是否必须使用常驻 PowerShell 工具。',
+        intro: '统一管理当前 profile 的 PowerShell 调用方式。',
+        hint: '开启后，普通 pwsh 调用会在执行前被拒绝，并提示模型改用 pwsh_run。',
+        scope: '对当前 profile 的所有预设和会话生效。保存后立即应用，正在运行的 pwsh_run 任务和常驻状态会保留。',
+        exceptions: '只读会话、明确的后台任务和需要宿主审批的有效提权请求，仍可使用原生 pwsh。',
+        on: '已开启', off: '已关闭', pending: '有尚未保存的修改', inherited: '恢复配置默认值',
+        form: { unavailable: '配置暂不可用，请确认插件已在当前主机加载。', readOnly: '当前部署的配置只读，无法保存修改。', saveFailed: '保存失败，请刷新配置后重试。', save: '保存', saving: '保存中…' },
+      },
+      en: {
+        title: 'pwsh settings', group: 'Tool routing', label: 'Require pwsh_run',
+        summary: 'Choose whether models must use persistent PowerShell.',
+        intro: 'Manage PowerShell routing for the current profile.',
+        hint: 'When enabled, ordinary pwsh calls are blocked before execution and the model is directed to pwsh_run.',
+        scope: 'Applies to every preset and session in this profile. Saving takes effect immediately and preserves running pwsh_run tasks and session state.',
+        exceptions: 'Read-only sessions, explicit background jobs, and valid elevation requests that require Host approval retain native pwsh.',
+        on: 'Enabled', off: 'Disabled', pending: 'Unsaved changes', inherited: 'Restore configuration default',
+        form: { unavailable: 'Configuration unavailable. Check that the plugin is loaded on this Host.', readOnly: 'Configuration is read-only in this deployment.', saveFailed: 'Not saved. Refresh the configuration and try again.', save: 'Save', saving: 'Saving…' },
+      },
+    }
+    const copy = () => (document.documentElement.lang || navigator.language || 'en').toLowerCase().startsWith('zh') ? COPY.zh : COPY.en
+    const style = {
+      page: { display: 'grid', gap: 24, width: '100%', maxWidth: 680, padding: '8px 0' },
+      title: { margin: 0, fontSize: 21, fontWeight: 600, lineHeight: 1.4 },
+      intro: { margin: '8px 0 0', fontSize: 13, opacity: 0.65, lineHeight: 1.65 },
+      section: { display: 'grid', gap: 16 },
+      group: { margin: 0, fontSize: 12, fontWeight: 600, opacity: 0.65 },
+      row: { display: 'flex', alignItems: 'flex-start', justifyContent: 'space-between', gap: 24 },
+      field: { display: 'grid', gap: 6 },
+      label: { fontSize: 14, fontWeight: 500 },
+      note: { margin: 0, fontSize: 13, lineHeight: 1.7, opacity: 0.65 },
+      status: { display: 'flex', alignItems: 'center', flexWrap: 'wrap', gap: 12, fontSize: 12, opacity: 0.65 },
+      reset: { marginLeft: 'auto' },
+    }
+    function SettingsPage(props) {
+      const t = copy()
+      if (props.view === 'summary') return t.summary
+      const state = props.usePwshSettings((value) => value)
+      const disabled = !state.writable || state.saving
+      return h('div', { style: style.page, 'data-pwsh-settings': '' },
+        h('header', null, h('h2', { style: style.title }, t.title), h('p', { style: style.intro }, t.intro)),
+        h(SettingsForm, { labels: t.form, state, onSave: props.save, onDiscard: props.discard },
+          h('section', { style: style.section },
+            h('h3', { style: style.group }, t.group),
+            h('div', { style: style.row },
+              h('div', { style: style.field }, h('span', { style: style.label }, t.label), h('p', { style: style.note }, t.hint)),
+              h(Switch, { label: t.label, checked: state.field.text === 'true', disabled, onChange: (value) => props.edit(FIELD, value ? 'true' : 'false') })),
+            h('div', { style: style.status, role: 'status' },
+              h('span', null, state.accepted ? t.on : t.off),
+              state.dirty ? h('span', null, t.pending) : null,
+              state.field.overridden ? h(Button, { style: style.reset, variant: 'ghost', size: 'sm', disabled, onClick: () => props.resetField(FIELD) }, t.inherited) : null),
+            h('p', { style: style.note }, t.scope),
+            h('p', { style: style.note }, t.exceptions))))
+    }
+    function apply(ctx) {
+      const scope = ctx.configForms.get(NS)
+      const form = new SettingsFormModel(scope, [{
+        field: FIELD,
+        format: (value) => value === true ? 'true' : 'false',
+        parse: (text) => text === 'true' || text === 'false' ? { kind: 'set', value: text === 'true' } : undefined,
+      }])
+      const store = form.bind(() => ({ ...form.shell(), field: form.field(FIELD), accepted: scope.getSnapshot().value?.[FIELD] === true }))
+      const inject = () => ({ hooks: { pwshSettings: store }, ...form.actions() })
+      ctx.effect(() => () => form.dispose(), 'pwsh-run.form')
+      ctx.effect(() => {
+        let dispose = () => {}
+        const register = () => {
+          dispose()
+          dispose = ctx.configForms.whileServed([NS], () => {
+            const section = ctx.slots.inject('settings.section', () => ctx.slots.register({ name: 'settings.section', id: 'pwsh-run', order: 43, label: copy().title, inject }, SettingsPage))
+            const row = ctx.slots.inject('plugins.row.config', () => ctx.slots.register({ name: 'plugins.row.config', key: 'dsh-pwsh-plugin#pwsh-run', inject }, SettingsPage))
+            return () => { row(); section() }
+          })
+        }
+        register()
+        // 导航文字由注册项持有，语言改变时重新登记，让宿主刷新入口标题。
+        const observer = new MutationObserver(register)
+        observer.observe(document.documentElement, { attributes: true, attributeFilter: ['lang'] })
+        return () => { observer.disconnect(); dispose() }
+      }, 'pwsh-run.settings-page')
+    }
+    return { name: 'pwsh-run-settings', inject: ['slots', 'configForms'], apply }
+  },
+})

package/cordis.patch.yml

@@ -13,6 +13,7 @@
         timeoutMs: 120000
         idleMs: 1800000
         maxSessions: 4
+        enforcePwshRun: false
 
     # Windows 上的 bash：官方 persistent bash 依赖 PTY，PTY 后端只支持 linux/darwin，
     # 而官方 bash 工具在 win32 上被禁用，Windows 会话因此没有 bash。这一行补上它，

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pwsh-plugin",
-  "version": "0.2.18",
+  "version": "0.2.19",
   "type": "module",
   "description": "Persistent pwsh session tool (pwsh_run) for DeepSeek Harness: run PowerShell scripts with zero escaping, no 32K command-line cap, and state that survives across calls.",
   "icon": "./icon.svg",
@@ -24,10 +24,12 @@
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./locale/*.json": "./locale/*.json",
     "./icon": "./icon.svg",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./client": "./client/index.js"
   },
   "files": [
     "plugin",
+    "client",
     "wsl",
     "docs",
     "locale",
@@ -42,6 +44,12 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
     }
   },
   "engines": {
@@ -51,7 +59,17 @@
     "@deepseek-ai/dsh": ">=0.2.0-rc.2 <0.3.0"
   },
   "scripts": {
-    "test": "node test/protocoltest.mjs && node test/lifecycletest.mjs && node test/itest.mjs && node test/plugintest.mjs && node test/denialtest.mjs && node test/metatest.mjs",
-    "test:all": "node test/protocoltest.mjs && node test/lifecycletest.mjs && node test/itest.mjs && node test/plugintest.mjs && node test/e2e-real-subprocess.mjs && node test/sandboxtest.mjs && node test/bashtest.mjs && node test/bash-e2e.mjs && node test/denialtest.mjs && node test/metatest.mjs"
+    "test": "node test/settingstest.mjs && node test/routingtest.mjs && node test/protocoltest.mjs && node test/lifecycletest.mjs && node test/itest.mjs && node test/plugintest.mjs && node test/denialtest.mjs && node test/metatest.mjs",
+    "test:all": "node test/settingstest.mjs && node test/routingtest.mjs && node test/protocoltest.mjs && node test/lifecycletest.mjs && node test/itest.mjs && node test/plugintest.mjs && node test/e2e-real-subprocess.mjs && node test/sandboxtest.mjs && node test/bashtest.mjs && node test/bash-e2e.mjs && node test/denialtest.mjs && node test/metatest.mjs"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.19.0"
+  },
+  "devDependencies": {
+    "clsx": "2.1.1",
+    "immer": "10.1.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "zustand": "4.5.7"
   }
 }

package/plugin/config.mjs

@@ -0,0 +1,13 @@
+import Schema from '@deepseek-ai/schemastery'
+import { DEFAULT_MAX_OUTPUT_BYTES, MAX_TIMEOUT_MS } from './session.mjs'
+
+// 只有路由开关热更新；进程参数改变仍交给 Loader 重挂实例。
+export const Config = Schema.object({
+  pwshPath: Schema.string().default('pwsh'),
+  timeoutMs: Schema.number().min(1).max(MAX_TIMEOUT_MS).step(1).default(120000),
+  idleMs: Schema.number().min(1).step(1).default(1800000),
+  maxSessions: Schema.number().min(1).step(1).default(4),
+  maxOutputBytes: Schema.number().min(1).max(2147483647).step(1).default(DEFAULT_MAX_OUTPUT_BYTES),
+  allowUnconfined: Schema.boolean().default(false),
+  enforcePwshRun: Schema.boolean().default(false).volatile(),
+})

package/plugin/index.mjs

@@ -29,6 +29,8 @@
  */
 
 import { readFileSync } from 'node:fs'
+export { Config } from './config.mjs'
+import { installNativePwshGuard } from './native-pwsh-guard.mjs'
 import { DEFAULT_MAX_OUTPUT_BYTES, MAX_TIMEOUT_MS, bootArgv, startSession, validateTimeout, abortable } from './session.mjs'
 
 /** 加载器诊断里显示的插件名。 */
@@ -145,6 +147,12 @@ export function apply(ctx, config) {
     return sandboxPolicy.resolve(session === undefined ? {} : { session })
   }
 
+  installNativePwshGuard(ctx, config?.enforcePwshRun, resolvePolicy)
+  // 页面复用 settings 服务的持久化与 revision 校验，不创建额外的配置文件。
+  ctx.inject?.(['settings'], (child) => {
+    child.effect(() => child.settings.configure({ auto: false }, ctx.fiber), 'pwsh-run.settings-page')
+  })
+
   // 槽位在第一次 await 前登记；同 ID 的创建、边界切换与执行共用队列。
   const sessions = new Map()
   let stopped = false

package/plugin/native-pwsh-guard.mjs

@@ -0,0 +1,43 @@
+const MODE_RANK = new Map([
+  ['read-only', 0], ['workspace-write', 1], ['danger-full-access', 2],
+])
+
+const DENIAL = 'Ordinary native pwsh calls are disabled by config.enforcePwshRun. '
+  + 'Use pwsh_run instead: pass the PowerShell command as script, and keep workdir and timeoutMs when supplied. '
+  + 'The native command was not executed.'
+
+/** 守卫在宿主执行前策略之后检查；不用可被后续监听器改回 allow 的瀑布钩子。 */
+export function installNativePwshGuard(ctx, enabled, resolvePolicy) {
+  const live = enabled !== null && typeof enabled === 'object' && typeof enabled.get === 'function'
+  const readEnabled = () => {
+    const value = live ? enabled.get() : enabled
+    if (value !== undefined && typeof value !== 'boolean') {
+      throw new Error('pwsh_run enforcePwshRun must be a boolean')
+    }
+    return value === true
+  }
+  const initial = readEnabled()
+  if (!live && !initial) return
+  if (typeof ctx.tools.guard !== 'function') {
+    throw new Error('pwsh_run enforcePwshRun requires a DSH host with tools.guard(); '
+      + 'upgrade DSH to use this routing configuration. No routing guard was installed.')
+  }
+
+  ctx.effect(() => ctx.tools.guard((exec) => {
+    // Loader 原地更新 volatile 引用；读取它不会销毁正在使用的常驻进程。
+    if (exec.name !== 'pwsh' || !readEnabled()) return undefined
+    // 后台 job 的句柄与逐次审批由原生工具持有，常驻会话不能代接。
+    const args = exec.arguments
+    if (args?.run_in_background === true) return undefined
+    const mode = resolvePolicy(exec.agent)?.mode
+    if (mode === 'read-only') return undefined
+    const requestedRank = MODE_RANK.get(args?.sandbox_permissions)
+    const currentRank = MODE_RANK.get(mode)
+    if (requestedRank !== undefined && currentRank !== undefined && requestedRank > currentRank
+      && typeof args?.justification === 'string' && args.justification.trim().length > 0) {
+      // 只放行真实的提权请求；是否批准仍由原生工具的审批机制决定。
+      return undefined
+    }
+    return DENIAL
+  }), 'pwsh-run.native-guard')
+}