dsh-bash-guard 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lloydzhou
+
+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.md

@@ -1,3 +1,194 @@
-# Temporary Holding Version
+<h1 align="center">DSH Bash Guard</h1>
+<p align="center"><strong>给 Agent 工作空间，把权限留在你手里。</strong></p>
+<p align="center">4 个范围 × 3 种权限。12 个开关，一个原生菜单。</p>
 
-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.
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <img alt="DSH Web plugin" src="https://img.shields.io/badge/DSH-Web_plugin-555">
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-policy_classifier-3178C6?logo=typescript&logoColor=white">
+  <img alt="Preview" src="https://img.shields.io/badge/status-preview-orange">
+</p>
+
+<p align="center">
+  <a href="#快速开始">快速开始</a> ·
+  <a href="#权限怎么读">权限模型</a> ·
+  <a href="#安全边界">安全边界</a> ·
+  <a href="#来源与致谢">来源与致谢</a>
+</p>
+
+**DSH Bash Guard 是 DeepSeek Harness 的独立 Web 插件。** 它把 Bash Agent / Bash Guard 的四位权限思路带进 DSH 原生权限菜单，让你按范围控制工具操作，而不必在“只读”和“全部放开”之间二选一。
+
+不改宿主源码，不增加一排数字预设，也不用记斜杠命令。展开 `bash-guard 自定义`，直接调整系统、外部、网络和工作区的读、写、执行权限。
+
+> **它是额外的工具权限检查，不是沙箱替代品。** 即使设为 `7777`，DSH 原生沙箱和审批仍然适用。
+
+## 为什么使用它
+
+- **权限看得见。** 四行三列，12 个独立开关，支持全部 4096 种组合。
+- **原生菜单，不打断工作。** 保留原生权限选项、图标和风险确认；修改时菜单保持展开。
+- **从单格到整行。** 点一个格子切换一个权限位；点 scope 名称全选或清空这一行。
+- **配置随会话记住。** 同一 session ID 重开可恢复；切回原生预设停用 Guard，但保留上次数字。
+- **有依据的拒绝。** 支持的操作按 `required` 与 `allowed` 比较，拒绝时说明所需权限位。
+
+## 快速开始
+
+### 从源码安装
+
+需要 Git、Node.js / npm，以及支持插件的 DSH。当前版本针对 DSH Web 集成验证，尚未声明跨宿主版本兼容。
+
+```bash
+git clone https://github.com/lloydzhou/dsh-bash-guard.git
+cd dsh-bash-guard
+npm ci
+npm run build
+
+dsh plugin --profile web add .
+dsh --profile web
+```
+
+在输入框附近打开权限菜单，选择 **bash-guard 自定义**。
+
+目录安装采用链接。更新插件后重新构建；宿主入口或插件配置变化时，重启对应的 DSH 实例。
+
+### npm 发布状态
+
+包名为 `dsh-bash-guard`。本仓库已准备 npm 打包配置，但本说明不表示该包已经发布；发布前请使用上面的源码安装方式。
+
+## 在菜单中操作
+
+| 入口 | 行为 |
+| :--- | :--- |
+| 单个权限格 | 独立切换该范围的读、写或执行位 |
+| 系统 / 外部 / 网络 / 工作区 | 已全选则清空该行，否则全选该行 |
+| 全选 | 当前不是 `7777` 时显示，点击将全部 Guard 位设为 `7777` |
+| 默认 | 当前是 `7777` 时显示，点击恢复 `0477` |
+| 原生权限预设 | 停用 Guard，保留记忆的四位值 |
+
+方向键在矩阵中移动焦点，不修改权限；空格切换当前按钮，Escape 关闭菜单。状态由服务端确认，保存时不插入提示行或改变菜单高度。
+
+**当前默认值有两种用途：** 新会话的初始记忆值是 `0467`，且 Guard 默认不激活；菜单“默认”按钮的恢复值是 `0477`。已有会话不会因升级自动重置。
+
+## 权限怎么读
+
+借鉴 Unix `rwx` 位的表示法，但这是**工具操作策略**，不是文件系统的 `chmod` 权限。
+
+```text
+模式：       0       4       6       7
+范围：     系统     外部     网络    工作区
+           system  external network workspace
+
+每位：读 = 4，写 = 2，执行 = 1
+组合：按位相加，例如 6 = 4 + 2 = 读 + 写
+```
+
+| 数字 | 读 | 写 | 执行 |
+| :---: | :---: | :---: | :---: |
+| `0` | 否 | 否 | 否 |
+| `1` | 否 | 否 | 是 |
+| `2` | 否 | 是 | 否 |
+| `3` | 否 | 是 | 是 |
+| `4` | 是 | 否 | 否 |
+| `5` | 是 | 否 | 是 |
+| `6` | 是 | 是 | 否 |
+| `7` | 是 | 是 | 是 |
+
+### 四个范围
+
+| Scope | 含义 |
+| :--- | :--- |
+| 系统 | 系统路径及敏感路径，例如 `/etc`、`/usr`、`.ssh`、凭据或密钥相关路径；敏感路径即使位于项目内，也可能归入系统范围 |
+| 外部 | 工作区外、不属于系统范围的普通路径 |
+| 网络 | 被分类器识别的网络读取、写入及远程执行操作 |
+| 工作区 | 项目内文件与命令操作；分类器还将直接的可信临时路径纳入这一范围 |
+
+路径分类是词法判断。`/tmp` 等可信路径的特殊规则、敏感名称规则和命令分类，见 [分类器源码](src/classify.ts)。这不是对实际文件系统归属的完整证明。
+
+### 几个容易记住的组合
+
+| 模式 | 表达的策略 |
+| :---: | :--- |
+| `0467` | 系统关闭；外部只读；网络读写；工作区全部 |
+| `0477` | 与上项相比，增加网络执行位；菜单“默认”的恢复值 |
+| `4447` | 系统、外部、网络只读；工作区全部 |
+| `0007` | 仅开放工作区的三个权限位 |
+| `7777` | Guard 全部位开放，**不等于原生完全权限** |
+
+模式不是安全等级排序。请按需要开启具体位，不要仅因为数字更大而认为它更合适。
+
+### 操作如何判定
+
+```text
+Agent 工具调用
+    │
+    ├─ Guard 未激活 / 工具未接管 ─────────► 原生工具路径
+    │
+    └─ Guard 已激活且支持该工具
+         ├─ 累计需要的权限位 required
+         ├─ 不满足 allowed ──────────────► BASH_GUARD_DENIED
+         └─ 全部满足 ────────────────────► 原生工具、沙箱与审批
+```
+
+判定规则是 `(allowed & required) === required`，不是比较数字大小。复合命令会累计多个范围的要求，不会只取一个“最高”范围。
+
+例如，同样执行 `cat /etc/hosts`：
+
+- `0467` 缺少系统读取位，拒绝，`required=4000`。
+- `4467` 满足 Guard 的系统读取要求，之后仍需通过原生执行路径。
+
+这组场景已在实际 DSH Web 会话验证：前者被拒绝，后者在工具原始结果中返回文件内容。
+
+当前分类器接管 `bash`，以及 `read`、`read_image`、`grep`、`glob`、`ls`、`write`、`edit` 等已识别工具名称。读取工具按目标路径检查读权限，写入工具检查写权限。未接管的工具继续走宿主原有策略。
+
+## 安全边界
+
+请在使用前了解这些限制：
+
+- **不是不可绕过的隔离层。** 分类器是保守词法扫描器，不是完整 Bash AST，也无法证明任意脚本或程序的运行时行为。
+- **不提高宿主权限。** 激活时选择原生 `workspace-write` 预设；Guard 放行不绕过底层沙箱和审批。该预设的具体行为由宿主配置决定。
+- **不覆盖所有工具。** 未识别的工具不会自动被本插件拦截，仍依赖宿主策略。
+- **不保证符号链接与动态路径隔离。** 实际文件系统、网络和子进程隔离仍由宿主负责。
+- **不保证子代理继承。** 跨代理任务不能假定自动沿用父会话的 Guard 配置。
+- **不是 Bash Guard Rust 运行时。** 本插件没有集成其 Jev 决策层、Claude/Codex Hook 或审计日志功能，也不宣称相同的安全保证。
+
+需要报告问题？请附上脱敏后的命令、四位模式、预期与实际结果，在 [Issues](https://github.com/lloydzhou/dsh-bash-guard/issues) 中反馈。不要提交凭据或私有文件内容。
+
+## 会话与兼容性
+
+配置保存在 DSH 插件数据域 `bash_guard`，按 session ID 记录模式、激活状态和修订号。写入先持久化再确认；同会话写入串行，修订号防止过时编辑覆盖新状态。
+
+这是插件侧存储，**不是原生会话 JSONL 的一部分**。导出、分叉和历史回退不会自动携带或回放配置。
+
+客户端通过独立 RPC 读写，不使用命令轮询或额外会话写句柄。兼容基线为 DSH `0.2.0-rc.2`，不支持更早的宿主。服务端直接依赖官方 npm 包 `@deepseek-ai/dsh-typert-protocol@0.2.0-rc.2`，不内置或修改宿主协议源码。后续版本沿官方接口适配；协议依赖固定到已验证版本，升级时通过回归测试再更新，不承诺任意未来版本自动兼容。
+
+## 开发
+
+```bash
+npm ci
+npm test
+npm run build
+npm pack --dry-run
+```
+
+- [服务端入口](src/index.ts)：持久化、RPC、原生预设联动及工具拦截。
+- [权限分类器](src/classify.ts)：命令与路径所需权限。
+- [客户端集成](src/client.js)：原生菜单与状态同步。
+- [矩阵编辑器](src/GuardEditor.js)：单格、整行及全局开关。
+- [测试](tests/)：分类器、RPC、原生菜单和矩阵交互。
+
+当前回归测试共 174 项，包括全部 4096 种模式的客户端校验。测试覆盖不代表对任意 Shell 程序的安全证明。npm 打包前会自动构建；构建产物与依赖目录不提交到 Git。
+
+## 来源与致谢
+
+这个项目属于同一条探索路线：让 coding agent 能完成工作，同时让操作权限可表达、可检查。
+
+| 项目 | 与本项目的关系 |
+| :--- | :--- |
+| [lloydzhou/bash-agent](https://github.com/lloydzhou/bash-agent) | 最小化 AI coding agent 运行时；本插件的四范围、四位八进制权限模型与命令分类思路参考其 [Bash 工具权限策略](https://github.com/lloydzhou/bash-agent/blob/main/docs/bash-tool-policy.md) |
+| [lloydzhou/bash-guard](https://github.com/lloydzhou/bash-guard) | 面向 Claude Code / Codex 的独立安全门；本插件借鉴其显式权限、执行前检查和可解释拒绝的方向，针对 DSH 重新实现集成 |
+| DeepSeek Harness / Cordis | 提供插件生命周期、原生权限 UI、数据域和 RPC 接入基础 |
+
+**相同的权限表达，不同的宿主集成。** 请以本仓库实现与限制为准，不要直接套用其他项目的安装命令、环境变量或安全承诺。
+
+## License
+
+[MIT](LICENSE) © lloydzhou。官方协议与其他依赖遵循各自的许可证。

package/client.js

@@ -0,0 +1,386 @@
+window.__ModuleLoader__.load({id:'dsh-bash-guard',factory:(hostRequire)=>{
+const factories={"./client.js": (module,exports,require) => {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.guardRemoteContribution = exports.inject = void 0;
+exports.commandResult = commandResult;
+exports.decodeGuardState = decodeGuardState;
+exports.createGuardTransport = createGuardTransport;
+exports.createPermissionControl = createPermissionControl;
+exports.apply = apply;
+const GuardEditor_js_1 = require("./GuardEditor.js");
+// A missing guard service must never hide the host's native permission choices.
+exports.inject = ['sessions', 'slots', 'remote', 'remote.permissionPresets'];
+function commandResult(reply) {
+    if (!reply?.ok)
+        throw new Error(reply?.error?.message || '权限请求失败');
+    if (!reply.value?.matched)
+        throw new Error('宿主未提供此权限命令');
+    const result = reply.value.result;
+    if (result?.kind === 'error')
+        throw new Error(result.text || '权限请求失败');
+    return result;
+}
+function decodeGuardState(reply) {
+    if (!reply?.ok)
+        throw new Error(reply?.error?.message || 'Bash Guard 不可用');
+    const state = reply.value;
+    if (!/^[0-7]{4}$(?![\s\S])/.test(state?.mode) || typeof state.active !== 'boolean' || !Number.isSafeInteger(state.revision) || state.revision < 0) {
+        throw new Error('Bash Guard 返回了无效状态');
+    }
+    return { mode: state.mode, active: state.active, revision: state.revision };
+}
+function createGuardTransport(remote, sessionId, sessionFor) {
+    const guard = () => {
+        if (!remote.bashGuard)
+            throw new Error('Bash Guard 不可用');
+        return remote.bashGuard;
+    };
+    return {
+        get: async () => decodeGuardState(await guard().get(sessionId)),
+        write: async (action, state, mode) => decodeGuardState(await guard().update(sessionId, {
+            action, revision: state.revision, ...(mode === undefined ? {} : { mode }),
+        })),
+        // Deliberately independent of guard reads, readiness, and failures.
+        preset: async (id) => {
+            const live = sessionFor();
+            if (!live)
+                throw new Error('会话尚未就绪，请稍后重试');
+            return commandResult(await live.command(`/permission ${id}`));
+        },
+        catalog: async () => {
+            const reply = await remote.permissionPresets.catalog();
+            if (!reply?.ok)
+                throw new Error(reply?.error?.message || '权限列表不可用');
+            if (!Array.isArray(reply.value?.options))
+                throw new Error('权限列表无效');
+            return reply.value;
+        },
+        subscribeCatalog: callback => remote.$on?.('permission-presets/catalog-changed', callback),
+    };
+}
+const copy = {
+    'preset.readOnly': '仅可查看', 'preset.workspaceWrite': '工作区内修改', 'preset.fullAccess': '完全权限',
+    'close': '关闭', 'confirm.cancel': '取消',
+    'confirm.title': '确认启用完全权限？',
+    'confirm.description': '启用完全权限后，智能体将减少确认步骤，并且可以直接执行更多操作，包括敏感操作、文件修改或外部命令。仅建议在你信任当前任务时使用。',
+    'confirm.acknowledge': '我已了解风险，并愿意继续', 'confirm.enable': '启用完全权限',
+    'auto.label': 'Auto review', 'auto.badge': 'EXP',
+    'auto.description': '无沙箱运行；每次原生工具调用和 PTC 内层调用前由同一模型进行实验性审查。',
+    'auto.confirm.title': '确认启用 Auto review（实验）？',
+    'auto.confirm.description': 'Auto review 不使用沙箱。每次原生工具调用和 PTC 内层调用前，都会由与当前 agent 相同的模型进行审查；审查拒绝的调用由你批准或拒绝。此功能仍属实验性，可能误放行或误拒绝，并会消耗额外 token。',
+    'auto.confirm.acknowledge': '我已了解这些风险，并愿意继续', 'auto.confirm.enable': '启用 Auto review',
+};
+const labels = { 'read-only': ['preset.readOnly', 'Read Only'], 'workspace-write': ['preset.workspaceWrite', 'Workspace Write'], 'danger-full-access': ['preset.fullAccess', 'Full access'] };
+function createPermissionControl(React, primitives) {
+    const h = React.createElement;
+    const { Menu, RiskConfirmation, PermissionIconReadOnlyRegular, PermissionIconWorkspaceWriteRegular, PermissionIconFullAccessRegular, IconChevronDownOutlineRegular, IconSettingsOutlineRegular } = primitives;
+    const icons = { 'read-only': PermissionIconReadOnlyRegular, 'workspace-write': PermissionIconWorkspaceWriteRegular, 'danger-full-access': PermissionIconFullAccessRegular, 'bash-guard': IconSettingsOutlineRegular };
+    const GuardEditor = (0, GuardEditor_js_1.createGuardEditor)(React, primitives.IconCheckOutlineRegular);
+    return function PermissionControl({ sessionId, transport, locked, useProjection, t = key => copy[key] }) {
+        const selection = useProjection('permissions');
+        const [state, setState] = React.useState(null);
+        const [catalog, setCatalog] = React.useState(null);
+        const [open, setOpen] = React.useState(false);
+        const [pending, setPending] = React.useState(false);
+        const [error, setError] = React.useState('');
+        const [nativeError, setNativeError] = React.useState('');
+        const [confirmation, setConfirmation] = React.useState(null);
+        const [acknowledged, setAcknowledged] = React.useState(false);
+        const [picking, setPicking] = React.useState(false);
+        const epoch = React.useRef(0), request = React.useRef(0), catalogRequest = React.useRef(0);
+        const writing = React.useRef(false), nativeWriting = React.useRef(false);
+        const stateRef = React.useRef(null), api = React.useRef(transport);
+        api.current = transport;
+        const publish = next => { stateRef.current = next; setState(next); };
+        const message = cause => cause instanceof Error ? cause.message : String(cause);
+        const read = async () => {
+            if (writing.current)
+                return;
+            const generation = epoch.current, ticket = ++request.current;
+            setPending(true);
+            try {
+                const next = await api.current.get();
+                if (generation === epoch.current && ticket === request.current) {
+                    publish(next);
+                    setError('');
+                }
+            }
+            catch (cause) {
+                if (generation === epoch.current && ticket === request.current) {
+                    publish(null);
+                    setError(message(cause));
+                }
+            }
+            finally {
+                if (generation === epoch.current && ticket === request.current)
+                    setPending(false);
+            }
+        };
+        const readCatalog = async () => {
+            const generation = epoch.current, ticket = ++catalogRequest.current;
+            try {
+                const next = await api.current.catalog();
+                if (generation === epoch.current && ticket === catalogRequest.current) {
+                    setCatalog(next);
+                    setNativeError('');
+                }
+            }
+            catch (cause) {
+                if (generation === epoch.current && ticket === catalogRequest.current)
+                    setNativeError(message(cause));
+            }
+        };
+        React.useEffect(() => {
+            ++epoch.current;
+            writing.current = false;
+            nativeWriting.current = false;
+            publish(null);
+            setCatalog(null);
+            setOpen(false);
+            setConfirmation(null);
+            setPicking(false);
+            readCatalog();
+            const stop = api.current.subscribeCatalog?.(() => { setCatalog(null); readCatalog(); });
+            return () => { ++epoch.current; stop?.(); };
+        }, [sessionId]);
+        // No polling: refresh on opening and on authoritative permission projection changes.
+        React.useEffect(() => { read(); if (open)
+            readCatalog(); }, [open, sessionId, selection]);
+        React.useEffect(() => {
+            if (locked || (confirmation !== null && catalog !== null && !catalog.options.some(option => option.value === confirmation))) {
+                setOpen(false);
+                setConfirmation(null);
+                setAcknowledged(false);
+            }
+        }, [locked, catalog, confirmation]);
+        const submit = async (action, mode) => {
+            if (locked || writing.current || !stateRef.current)
+                return;
+            const generation = epoch.current;
+            const focusedSegment = document.activeElement?.matches?.('.dsh-bg-level') ? document.activeElement : null;
+            ++request.current;
+            writing.current = true;
+            setPending(true);
+            setError('');
+            try {
+                const next = await api.current.write(action, stateRef.current, mode);
+                if (generation === epoch.current)
+                    publish(next);
+            }
+            catch (cause) {
+                if (generation === epoch.current) {
+                    setError(message(cause));
+                    try {
+                        const next = await api.current.get();
+                        if (generation === epoch.current)
+                            publish(next);
+                    }
+                    catch {
+                        if (generation === epoch.current)
+                            publish(null);
+                    }
+                }
+            }
+            finally {
+                if (generation === epoch.current) {
+                    writing.current = false;
+                    setPending(false);
+                    if (focusedSegment)
+                        requestAnimationFrame(() => {
+                            if (generation === epoch.current && focusedSegment.isConnected && !focusedSegment.disabled && document.activeElement === document.body)
+                                focusedSegment.focus();
+                        });
+                }
+            }
+        };
+        const selectPreset = async (id) => {
+            if (locked || nativeWriting.current)
+                return;
+            const generation = epoch.current;
+            nativeWriting.current = true;
+            setPicking(true);
+            setNativeError('');
+            try {
+                await api.current.preset(id);
+                if (generation === epoch.current) {
+                    publish(null);
+                    ++request.current;
+                    read();
+                }
+            }
+            catch (cause) {
+                if (generation === epoch.current)
+                    setNativeError(message(cause));
+            }
+            finally {
+                if (generation === epoch.current) {
+                    nativeWriting.current = false;
+                    setPicking(false);
+                }
+            }
+        };
+        const choose = id => {
+            if (locked || picking)
+                return;
+            if (id === 'bash-guard') {
+                if (!pending && !state?.active)
+                    submit('activate');
+                return;
+            }
+            if (!catalog?.options.some(option => option.value === id))
+                return;
+            setOpen(false);
+            if (id === selection?.currentValue && !state?.active)
+                return;
+            if (id === 'danger-full-access' || id === 'auto') {
+                setAcknowledged(false);
+                setConfirmation(id);
+                return;
+            }
+            selectPreset(id);
+        };
+        const labelFor = (value, name = value) => {
+            if (value === 'auto')
+                return t('auto.label');
+            const builtin = labels[value];
+            if (builtin && (name === value || name === builtin[1]))
+                return t(builtin[0]);
+            return /^[a-z0-9]+(-[a-z0-9]+)*$/.test(name) ? name.split('-').map(word => word[0].toUpperCase() + word.slice(1)).join(' ') : name;
+        };
+        const icon = id => icons[id] ? h(icons[id]) : undefined;
+        const current = state?.active ? 'bash-guard' : selection?.currentValue;
+        const option = catalog?.options.find(item => item.value === current);
+        const label = current === 'bash-guard' ? `bash-guard ${state.mode}` : labelFor(current || '权限', option?.name);
+        const items = (catalog?.options || []).map(option => ({
+            id: option.value, icon: icon(option.value),
+            label: option.value === 'auto' ? h('span', { className: 'dsh-bg-option-label', 'aria-label': `${t('auto.label')} ${t('auto.badge')}` }, t('auto.label'), h('sup', { className: 'dsh-bg-badge' }, t('auto.badge'))) : labelFor(option.value, option.name),
+            disabled: !!locked || picking,
+        }));
+        items.push({ id: 'guard-separator', type: 'separator' }, {
+            id: 'bash-guard', icon: icon('bash-guard'), disabled: !!locked || !state,
+            label: h('span', null, 'bash-guard 自定义', state && h('span', { className: 'dsh-bg-mode' }, ` ${state.mode}`)),
+        });
+        const closeConfirmation = () => { setConfirmation(null); setAcknowledged(false); };
+        const riskPrefix = confirmation === 'auto' ? 'auto.confirm.' : 'confirm.';
+        return h(React.Fragment, null, h(Menu, { open, items, selectedId: current, onSelect: choose, onClose: () => setOpen(false), side: 'top', portal: true,
+            anchor: h('button', { type: 'button', className: 'dsh-bg-trigger', disabled: !!locked || picking || confirmation !== null,
+                'aria-label': `访问模式，当前：${label}`, 'aria-haspopup': 'menu', 'aria-expanded': open,
+                title: current === 'auto' ? t('auto.description') : option?.description, onClick: () => setOpen(!open),
+            }, icon(current) && h('span', { className: 'dsh-bg-trigger-icon', 'aria-hidden': true }, icon(current)), h('span', { className: 'dsh-bg-trigger-label' }, label), current === 'auto' && h('sup', { className: 'dsh-bg-badge' }, t('auto.badge')), h('span', { className: `dsh-bg-chevron${open ? ' dsh-bg-chevron-open' : ''}`, 'aria-hidden': true }, h(IconChevronDownOutlineRegular))),
+        }, state && h(GuardEditor, { mode: state.mode, active: state.active, pending, locked,
+            onModeChange: mode => submit('mode', mode),
+            onChange: (row, digit) => submit('mode', stateRef.current.mode.slice(0, row) + digit + stateRef.current.mode.slice(row + 1)),
+        }), h('span', { className: 'dsh-bg-sr-only', role: 'status' }, pending ? '正在同步权限' : ''), error && h('div', { className: 'dsh-bg-error', role: 'alert' }, error, h('button', { type: 'button', disabled: pending, onClick: read }, '重试')), nativeError && h('div', { className: 'dsh-bg-error', role: 'alert' }, nativeError, h('button', { type: 'button', onClick: readCatalog }, '重试'))), confirmation !== null && h(RiskConfirmation, { open: true, title: t(`${riskPrefix}title`), description: t(`${riskPrefix}description`),
+            acknowledgeLabel: t(`${riskPrefix}acknowledge`), cancelLabel: t('confirm.cancel'), closeLabel: t('close'), confirmLabel: t(`${riskPrefix}enable`),
+            acknowledged, disabled: !!locked || picking, onAcknowledgedChange: setAcknowledged, onCancel: closeConfirmation,
+            onConfirm: () => { if (!acknowledged || locked || picking)
+                return; const id = confirmation; closeConfirmation(); selectPreset(id); },
+        }));
+    };
+}
+// Client-owned Typert contribution: mount the namespace before rendering the seat.
+// Structural schemas keep this artifact on host modules (no bundled Zod/React).
+exports.guardRemoteContribution = {
+    package: 'dsh-bash-guard',
+    descriptors: ['get', 'update'].map(method => ({
+        id: `dsh-bash-guard#bashGuard/${method}`, service: 'bashGuard', namespace: 'bashGuard', method,
+        invocation: { kind: 'direct' },
+        parameters: [
+            { name: 'sessionId', wire: 'sessionId', source: 'json', codec: { mode: 'strict', typeSymbol: 'dsh-bash-guard#SessionId', create: () => ({ parse(value) {
+                            if (typeof value !== 'string' || !value.trim())
+                                throw new Error('A session ID is required');
+                            return value;
+                        } }) } },
+            ...(method === 'update' ? [{ name: 'request', wire: 'request', source: 'json', codec: { mode: 'strict', typeSymbol: 'dsh-bash-guard#GuardUpdate', create: () => ({ parse(value) {
+                                if (!value || !['activate', 'mode', 'deactivate'].includes(value.action) || !Number.isSafeInteger(value.revision) || value.revision < 0 || (value.mode !== undefined && !/^[0-7]{4}$(?![\s\S])/.test(value.mode)) || (value.action === 'mode' && value.mode === undefined))
+                                    throw new Error('Invalid Bash Guard update');
+                                return { action: value.action, revision: value.revision, ...(value.mode === undefined ? {} : { mode: value.mode }) };
+                            } }) } }] : []),
+        ],
+        result: { mode: 'strict', typeSymbol: 'dsh-bash-guard#GuardRecord', create: () => ({ parse: value => decodeGuardState({ ok: true, value }) }) },
+    })),
+};
+async function apply(ctx) {
+    // Resolve host modules inside apply: the browser loader owns React and styles.
+    const React = require('react');
+    const primitives = require('@deepseek-ai/dsh-client-ui-primitives');
+    const Control = createPermissionControl(React, primitives);
+    const register = (scope, guard) => {
+        // Only the injected child may read the guarded Cordis service. The adapter
+        // also makes missing-guard reads ordinary errors rather than proxy violations.
+        const remote = {
+            bashGuard: guard,
+            permissionPresets: scope.remote.permissionPresets,
+            $on: (event, listener) => scope.remote.$on(event, listener),
+        };
+        scope.slots.inject('conversation.input.permission', () => scope.slots.register({
+            name: 'conversation.input.permission', priority: -100, locale: 'permission.access',
+            inject: sessionId => ({ sessionId, transport: createGuardTransport(remote, sessionId, () => scope.sessions.binding(sessionId)?.session) }),
+        }, Control));
+    };
+    // Leave the host seat intact while the injected guard namespace resolves.
+    // On mount failure, native choices still work through the guard-free adapter.
+    try {
+        await ctx.remote.$mount(exports.guardRemoteContribution);
+    }
+    catch (error) {
+        console.warn('Bash Guard RPC unavailable', error);
+        register(ctx, undefined);
+        return;
+    }
+    ctx.inject(['remote.bashGuard'], child => register(child, child.remote.bashGuard));
+}
+
+},
+"./GuardEditor.js": (module,exports,require) => {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGuardEditor = createGuardEditor;
+// Independent permission bits; the host owns React and the check glyph.
+const scopes = ['系统', '外部', '网络', '工作区'];
+const permissions = [{ label: '读', bit: 4 }, { label: '写', bit: 2 }, { label: '执行', bit: 1 }];
+function createGuardEditor(React, CheckIcon) {
+    const h = React.createElement;
+    return function GuardEditor({ mode, active, pending = false, locked = false, error, onChange, onModeChange }) {
+        if (!active)
+            return null;
+        const disabled = pending || locked;
+        const keydown = (event, row, col) => {
+            const delta = { ArrowUp: [-1, 0], ArrowDown: [1, 0], ArrowLeft: [0, -1], ArrowRight: [0, 1] }[event.key];
+            if (!delta)
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            const root = event.currentTarget.closest('[data-guard-editor]');
+            root?.querySelector(`[data-cell="${Math.max(0, Math.min(3, row + delta[0]))}-${Math.max(0, Math.min(2, col + delta[1]))}"]`)?.focus();
+        };
+        return h('div', { className: 'dsh-bg-editor', 'data-guard-editor': '', 'aria-busy': pending }, h('div', { className: 'dsh-bg-scope dsh-bg-head' }, h('button', {
+            type: 'button', className: 'dsh-bg-scope-label dsh-bg-all-toggle dsh-bg-scope-toggle',
+            disabled: locked, 'aria-disabled': disabled,
+            title: mode === '7777' ? '恢复默认权限 0477' : '开启全部 Guard 权限',
+            onClick: event => { event.stopPropagation(); if (!disabled)
+                onModeChange(mode === '7777' ? '0477' : '7777'); },
+        }, mode === '7777' ? '默认' : '全选'), ...permissions.map(p => h('span', { className: 'dsh-bg-column', key: p.bit }, p.label))), ...scopes.map((scope, row) => h('div', { className: 'dsh-bg-scope', key: row, role: 'group', 'aria-label': `${scope}权限` }, h('button', {
+            type: 'button', className: 'dsh-bg-scope-label dsh-bg-scope-toggle',
+            disabled: locked, 'aria-disabled': disabled,
+            'aria-label': `${scope}：${mode[row] === '7' ? '取消全选' : '全选'}`,
+            title: mode[row] === '7' ? '取消该范围全部权限' : '开启该范围全部权限',
+            onClick: event => { event.stopPropagation(); if (!disabled)
+                onChange(row, mode[row] === '7' ? 0 : 7); },
+        }, scope), ...permissions.map((permission, col) => {
+            const checked = (Number(mode[row]) & permission.bit) !== 0;
+            return h('button', {
+                type: 'button', key: permission.bit, role: 'checkbox', 'aria-checked': checked,
+                'aria-label': `${scope} · ${permission.label}权限`, title: `${scope} · ${permission.label}权限：${checked ? '开启' : '关闭'}`,
+                'data-cell': `${row}-${col}`, disabled: locked, 'aria-disabled': disabled, className: 'dsh-bg-level',
+                onClick: event => { event.stopPropagation(); if (!disabled)
+                    onChange(row, Number(mode[row]) ^ permission.bit); },
+                onKeyDown: event => keydown(event, row, col),
+            }, checked && CheckIcon ? h(CheckIcon, { 'aria-hidden': true }) : null);
+        }))), error ? h('div', { className: 'dsh-bg-error', role: 'alert' }, error) : null);
+    };
+}
+
+}};const cache={};function require(id){if(!factories[id])return hostRequire(id);if(cache[id])return cache[id].exports;const module={exports:{}};cache[id]=module;factories[id](module,module.exports,require);return module.exports;}
+const api=require('./client.js');const original=api.apply;api.apply=(ctx)=>{ctx.effect(()=>{const style=document.createElement('style');style.dataset.plugin='dsh-bash-guard';style.textContent="/* Native permission trigger declarations, namespaced; Menu owns all menu chrome. */\n.dsh-bg-trigger { border-radius: var(--dsw-radius-sm); min-width: 0; max-width: 220px; height: 28px; color: var(--dsw-alias-label-secondary); cursor: pointer; background: transparent; border: none; outline: none; align-items: center; gap: 4px; padding: 0 4px 0 8px; font-size: 13px; font-weight: 500; line-height: 20px; display: inline-flex; }\n.dsh-bg-trigger:hover:not(:disabled) { background: var(--dsw-alias-interactive-bg-hover); }\n.dsh-bg-trigger:focus-visible { box-shadow: 0 0 0 2px var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary)); }\n.dsh-bg-trigger:disabled { color: var(--dsw-alias-label-dimmed); cursor: default; }\n.dsh-bg-trigger-icon { flex: none; display: inline-flex; }\n.dsh-bg-trigger-icon svg { width: 14px; height: 14px; }\n.dsh-bg-trigger-label { text-overflow: ellipsis; white-space: nowrap; min-width: 0; overflow: hidden; }\n.dsh-bg-option-label { align-items: baseline; gap: 4px; min-width: 0; max-width: 100%; display: inline-flex; }\n.dsh-bg-badge { color: var(--dsw-alias-label-tertiary); letter-spacing: .2px; flex: none; align-self: flex-start; margin-top: -1px; font-size: 8px; font-weight: 600; line-height: 10px; }\n.dsh-bg-chevron { color: var(--dsw-alias-label-caption); flex: none; transition: transform .12s; display: inline-flex; }\n.dsh-bg-chevron-open { transform: rotate(180deg); }\n@container (width <= 460px) { .dsh-bg-trigger:has(.dsh-bg-trigger-icon) .dsh-bg-trigger-label { display: none; } }\n.dsh-bg-editor { padding: 0 8px 4px 32px; color: var(--dsw-alias-label-primary); }\n.dsh-bg-scope { display: grid; grid-template-columns: 48px repeat(3, 32px); align-items: center; gap: 8px; min-height: 32px; }\n.dsh-bg-head { min-height: 26px; }\n.dsh-bg-column { text-align: center; font-size: 12px; color: var(--dsw-alias-label-secondary); }\n.dsh-bg-level svg { width: 16px; height: 16px; }\n.dsh-bg-scope-label { width: 42px; flex: 0 0 42px; color: var(--dsw-alias-label-secondary); font-size: 12px; }\n.dsh-bg-scope-toggle { appearance: none; border: 0; background: transparent; border-radius: var(--dsw-radius-sm); box-sizing: border-box; width: max-content; max-width: none; justify-self: start; height: 24px; margin-left: -6px; padding: 0 6px; text-align: left; white-space: nowrap; font-family: inherit; cursor: pointer; }\n.dsh-bg-scope-toggle:hover:not(:disabled) { background: var(--dsw-alias-interactive-bg-hover); color: var(--dsw-alias-label-primary); }\n.dsh-bg-level { appearance: none; border: 1px solid var(--dsw-alias-border-l1); background: transparent; color: var(--dsw-alias-label-secondary); border-radius: var(--dsw-radius-sm); width: 32px; height: 24px; padding: 0; display: inline-flex; align-items: center; justify-content: center; cursor: pointer; }\n.dsh-bg-sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }\n.dsh-bg-level:hover:not(:disabled) { background: var(--dsw-alias-interactive-bg-hover); color: var(--dsw-alias-label-primary); }\n.dsh-bg-level[aria-checked=\"true\"] { background: var(--dsw-alias-interactive-bg-hover-solid); color: var(--dsw-alias-label-primary); }\n.dsh-bg-editor button:focus-visible, .dsh-bg-error button:focus-visible { outline: 2px solid var(--dsw-focus-ring-color, var(--dsw-alias-label-secondary)); outline-offset: 1px; }\n.dsh-bg-editor button:disabled { cursor: default; color: var(--dsw-alias-label-tertiary); }\n.dsh-bg-error, .dsh-bg-status { color: var(--dsw-alias-label-secondary); font-size: 12px; line-height: 18px; padding: 6px 8px; overflow-wrap: anywhere; max-width: 300px; }\n.dsh-bg-error button { margin-left: 8px; padding: 2px 6px; border: 1px solid var(--dsw-alias-border-l1); border-radius: var(--dsw-radius-sm); background: transparent; color: inherit; font: inherit; cursor: pointer; }\n.dsh-bg-mode { font: 12px var(--ds-font-family-code, monospace); color: var(--dsw-alias-label-secondary); font-variant-numeric: tabular-nums; }\n@media (max-width: 360px) { .dsh-bg-editor { padding-left: 24px; } .dsh-bg-level { padding-inline: 4px; } }\n@media (prefers-reduced-motion: reduce) { .dsh-bg-chevron { transition: none; } }\n";document.head.append(style);return ()=>style.remove()});return original(ctx)};return api;}});

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# Bash Guard is an independent knob, never a numeric permission preset.
+- insert:
+    - id: bash-guard
+      name: dsh-bash-guard
+      config:
+        mode: '0467'

package/lib/classify.js

@@ -0,0 +1,327 @@
+/**
+ * Conservative, lexical bash-agent policy scanner, NOT an OS sandbox or a full
+ * shell parser. Requirements are four octal digits: system/external/network/
+ * workspace, each with read=4, write=2, execute=1. Compound calls accumulate
+ * every requirement; callers must grant ALL bits. Real filesystem confinement,
+ * symlink resolution and runtime/network isolation belong to the sandbox.
+ *
+ * Mirrors docs/bash-tool-policy.md and the Go/Rust/bash scanners in bash-agent.
+ * Unlike their whitespace scanner, quoted paths and stderr redirections are
+ * retained. Unresolved shell expansion fails closed rather than guessing a path.
+ */
+import { posix as path } from 'node:path';
+const SCOPES = ['system', 'external', 'network', 'workspace'];
+const VALID_MODE = /^[0-7]{4}$(?![\s\S])/;
+const SYSTEM = /^\/(?:etc|usr|bin|sbin|var|library|system|dev|boot|proc|sys|root)(?:\/|$)/i;
+const SENSITIVE = /(?:^|\/)(?:\.ssh|\.gnupg|\.aws|\.docker)(?:\/|$)|(?:\.env|\.pem|\.key)(?:$|\/)|token|credential|secret/i;
+const READERS = new Set(['cat', 'ls', 'head', 'tail', 'less', 'more', 'grep', 'egrep', 'fgrep', 'rg', 'find', 'stat', 'wc', 'file', 'du', 'readlink', 'realpath', 'sort', 'uniq', 'cut', 'diff', 'cmp', 'sed', 'awk']);
+const MUTATORS = new Set(['mkdir', 'touch', 'cp', 'mv', 'rm', 'rmdir', 'tee', 'chmod', 'chown', 'chgrp', 'truncate', 'install', 'ln', 'dd']);
+const INTERPRETERS = /^(?:ba|z|da|k)?sh$|^(?:python\d*(?:\.\d+)?|node|ruby|perl|php|lua|eval|source|\.)$/;
+const NETWORK = /^(?:curl|wget|http|https|ssh|scp|sftp|rsync|nc|ncat|netcat|telnet|ftp|ping)$/;
+const GIT_WRITE = /^(?:fetch|pull|clone|commit|add|checkout|switch|restore|merge|rebase|stash|cherry-pick|reset|clean|init)$/;
+const GIT_EXEC = /^(?:commit|add|checkout|switch|restore|merge|rebase|stash|cherry-pick)$/;
+const within = (target, root) => target === root || target.startsWith(root === '/' ? '/' : `${root}/`);
+const format = (mask) => mask.toString(8).padStart(4, '0');
+const bit = (scope, permissions) => permissions << ((3 - SCOPES.indexOf(scope)) * 3);
+function context(input) {
+    const options = typeof input === 'string' ? { cwd: input, workspace: input } : input ?? {};
+    const cwd = path.resolve(options.cwd ?? options.workspace ?? process.cwd());
+    return { cwd, workspace: path.resolve(options.workspace ?? cwd), home: options.home ?? process.env.BASH_AGENT_HOME ?? process.env.HOME ?? '' };
+}
+/** Pure lexical classification: never follows symlinks or touches the filesystem. */
+function pathMask(value, permissions, ctx) {
+    if (!value || /^&\d+$/.test(value) || value === '-')
+        return 0;
+    const original = value;
+    value = value.replace(/^~(?=\/|$)|^\$(?:HOME|\{HOME\})(?=\/|$)/, ctx.home || '$UNKNOWN_HOME');
+    if (/[\x00\r\n]/.test(value) || /\$|`|~/.test(value))
+        return bit('system', permissions) | bit('external', permissions) | bit('network', permissions) | bit('workspace', permissions);
+    const trusted = ['/tmp', ...(ctx.home ? [path.join(ctx.home, '.bash-agent/projects')] : [])];
+    // Check BEFORE normalization: /tmp/../etc is explicitly never trusted.
+    if (trusted.some(root => within(value, root)) && value.split('/').includes('..'))
+        return bit('system', permissions);
+    const resolved = path.resolve(ctx.cwd, value);
+    if (resolved === '/dev/null')
+        return 0;
+    if (within(resolved, '/dev/tcp') || within(resolved, '/dev/udp'))
+        return bit('network', permissions);
+    if (trusted.some(root => within(resolved, root)))
+        return bit(value.split('/').includes('..') ? 'system' : 'workspace', permissions);
+    if (resolved === '/' || /^\/[?*\[]/.test(resolved) || SYSTEM.test(resolved) || SENSITIVE.test(original))
+        return bit('system', permissions);
+    return bit(within(resolved, ctx.workspace) ? 'workspace' : 'external', permissions);
+}
+/** One scope's Unix-style permission bit. */
+export function opBit(op) { return op === 'read' ? 4 : op === 'write' ? 2 : 1; }
+/** Invalid modes/scopes never accidentally become an allowed digit. */
+export function scopeDigit(mode, scope) {
+    return VALID_MODE.test(mode) && SCOPES.includes(scope) ? Number(mode[SCOPES.indexOf(scope)]) : -1;
+}
+export function allows(mode, required) {
+    if (!VALID_MODE.test(mode) || !VALID_MODE.test(required))
+        return false;
+    const allowedMask = Number.parseInt(mode, 8);
+    const requiredMask = Number.parseInt(required, 8);
+    return (allowedMask & requiredMask) === requiredMask;
+}
+/** Actual DSH names/arguments; legacy casing is accepted, not required. */
+export function classifyTool(tool, args = {}, input) {
+    const name = tool.toLowerCase();
+    const ctx = context(input);
+    if (name === 'bash') {
+        if (typeof args.command !== 'string')
+            return '7777';
+        const cwd = typeof args.workdir === 'string' ? path.resolve(ctx.cwd, args.workdir) : ctx.cwd;
+        return classifyCommand(args.command, { ...ctx, cwd });
+    }
+    const read = ['read', 'read_image', 'grep', 'glob', 'ls'].includes(name);
+    const write = ['write', 'edit', 'multiedit', 'notebookedit'].includes(name);
+    if (!read && !write)
+        return undefined;
+    const value = args.file_path ?? args.path ?? args.notebook_path;
+    if (value !== undefined && typeof value !== 'string')
+        return '7777';
+    if (name === 'glob' && value === undefined && typeof args.pattern === 'string' && (path.isAbsolute(args.pattern) || args.pattern.split('/').includes('..')))
+        return '4000';
+    return format(pathMask(typeof value === 'string' && value ? value : '.', write ? 2 : 4, ctx));
+}
+/** Quotes group literal paths. Operators are recognized even without whitespace. */
+function tokenize(script) {
+    const result = [];
+    let word = '', active = false, quote = '';
+    const flush = () => { if (active)
+        result.push({ text: word, operator: false }); word = ''; active = false; };
+    for (let i = 0; i < script.length; i += 1) {
+        const ch = script[i];
+        if (ch === '\\' && quote !== "'") {
+            if (i + 1 >= script.length)
+                return undefined;
+            const next = script[++i];
+            if (next !== '\n') {
+                word += next;
+                active = true;
+            }
+            continue;
+        }
+        if (quote) {
+            if (ch === quote)
+                quote = '';
+            else
+                word += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            active = true;
+            continue;
+        }
+        if (ch === '#' && !active) {
+            while (i < script.length && script[i] !== '\n')
+                i += 1;
+            flush();
+            result.push({ text: ';', operator: true });
+            continue;
+        }
+        if (ch === '\n' || /\s/.test(ch)) {
+            flush();
+            if (ch === '\n')
+                result.push({ text: ';', operator: true });
+            continue;
+        }
+        if (';&|<>()'.includes(ch)) {
+            // A numeric word immediately before >/< is an fd, not a path.
+            let fd = '';
+            if ((ch === '>' || ch === '<') && /^\d+$/.test(word)) {
+                fd = word;
+                word = '';
+                active = false;
+            }
+            flush();
+            let op = ch;
+            if (script[i + 1] === ch || (ch === '<' && script[i + 1] === '>') || ('<>'.includes(ch) && script[i + 1] === '&') || (ch === '>' && script[i + 1] === '|'))
+                op += script[++i];
+            result.push({ text: fd + op, operator: true });
+            continue;
+        }
+        word += ch;
+        active = true;
+    }
+    if (quote)
+        return undefined;
+    flush();
+    return result;
+}
+/**
+ * Accumulate command segments, pipelines, path scopes, redirections and execution.
+ * Opaque substitutions/heredocs/dynamic command names fail closed. This cannot
+ * prove the effects of arbitrary programs, aliases, symlinks or shell functions.
+ */
+export function classifyCommand(command, input) {
+    if (!command.trim())
+        return '0000';
+    const ctx = context(input);
+    // Do not pretend to expand arbitrary shell code, variables, or process substitution.
+    if (/\$\(|`|[<>]\(|<<|\$\{|\$(?!HOME(?:\W|$))[A-Za-z_]/.test(command))
+        return '7777';
+    // Branch-dependent cwd and shell control flow cannot be resolved by this scanner.
+    if (/\b(?:if|then|else|elif|fi|for|while|until|case|esac|function)\b|[{}]/.test(command) || /\bcd\b/.test(command) && /\|\||(?:^|[^&])&(?:[^&]|$)|[()]/.test(command))
+        return '7777';
+    const tokens = tokenize(command);
+    if (!tokens)
+        return '7777';
+    let mask = 0;
+    let segment = [];
+    let networkSeen = false, networkExecution = false;
+    let cwd = ctx.cwd;
+    const scan = () => {
+        if (!segment.length)
+            return;
+        const local = { ...ctx, cwd };
+        const words = [];
+        for (let i = 0; i < segment.length; i += 1) {
+            const token = segment[i];
+            if (token.operator && /[<>]/.test(token.text)) {
+                const next = segment[++i];
+                if (!next || next.operator) {
+                    mask |= 0o7777;
+                    continue;
+                }
+                if (token.text.endsWith('&') && /^(?:\d+|-)$/.test(next.text))
+                    continue;
+                const permissions = token.text.includes('<>') ? 6 : token.text.includes('>') ? 2 : 4;
+                mask |= pathMask(next.text, permissions, local);
+            }
+            else if (!token.operator)
+                words.push(token.text);
+        }
+        segment = [];
+        while (words[0] && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])) {
+            // Environment overrides can change executable lookup / shell startup semantics.
+            if (/^(?:PATH|BASH_ENV|ENV|SHELLOPTS|LD_|DYLD_)/.test(words[0]))
+                mask |= 0o7777;
+            words.shift();
+        }
+        while (['command', 'builtin', 'exec', 'env', 'nohup', 'timeout'].includes(words[0] ?? '')) {
+            words.shift();
+            while (words[0]?.startsWith('-') || /^\d+$/.test(words[0] ?? '') || /^[A-Za-z_]\w*=/.test(words[0] ?? ''))
+                words.shift();
+        }
+        if (!words.length)
+            return;
+        if (words[0].startsWith('-') || /[?*\[\]$]/.test(words[0])) {
+            mask |= 0o7777;
+            return;
+        }
+        const executable = words[0];
+        const cmd = path.basename(executable).toLowerCase();
+        const args = words.slice(1);
+        const sub = args.find(arg => !arg.startsWith('-'))?.toLowerCase() ?? '';
+        const git = cmd === 'git';
+        const network = NETWORK.test(cmd) || git && /^(?:clone|fetch|pull|ls-remote|push)$/.test(sub) || args.some(arg => /^https?:\/\//i.test(arg));
+        if (network) {
+            networkSeen = true;
+            if (!(git && sub === 'push'))
+                mask |= bit('network', 4);
+            if (['ssh', 'scp', 'sftp', 'rsync', 'ftp', 'nc', 'ncat', 'netcat', 'telnet'].includes(cmd))
+                mask |= bit('network', 2);
+            if (cmd === 'ssh') {
+                mask |= bit('network', 1);
+                networkExecution = true;
+            }
+            if (git && sub === 'push' || cmd === 'curl' && args.some(arg => /^(?:-[dFTX]|--(?:data|json|form|upload-file|request))(?:$|[=A-Z])/.test(arg)))
+                mask |= bit('network', 2);
+        }
+        if (/^(?:sudo|su|doas|shutdown|reboot|halt|poweroff)$/.test(cmd))
+            mask |= bit('system', 1);
+        if (['sudo', 'su', 'doas'].includes(cmd) && args.length && !['echo', 'printf', 'true', 'false', ':', 'pwd'].includes(args[0])) {
+            // Options such as sudo -u require command-specific parsing; do not guess.
+            mask |= args[0].startsWith('-') ? 0o7777 : Number.parseInt(classifyCommand(args.map(arg => JSON.stringify(arg)).join(' '), local), 8);
+        }
+        if (/^(?:mkfs.*|fdisk|diskutil|mount|umount)$/.test(cmd))
+            mask |= bit('system', 2);
+        const interpreter = INTERPRETERS.test(cmd);
+        if (interpreter) {
+            mask |= pathMask('.', 1, local);
+            networkExecution = true;
+            const inline = args.findIndex(arg => /^-[^-]*c/.test(arg));
+            if (inline >= 0 && args[inline + 1] !== undefined && /^(?:ba|z|da|k)?sh$|^eval$/.test(cmd))
+                mask |= Number.parseInt(classifyCommand(args[inline + 1], local), 8);
+            if (['eval', 'source', '.'].includes(cmd) && args.length)
+                mask |= cmd === 'eval' ? Number.parseInt(classifyCommand(args.join(' '), local), 8) : pathMask(args[0], 1, local);
+        }
+        const build = /^(?:make|gmake|cmake|ninja)$/.test(cmd) || /^(?:npm|pnpm|yarn|bun)$/.test(cmd) && /^(?:run|test|exec|dlx|install|add|publish)$/.test(sub) || /^(?:cargo|go)$/.test(cmd) && /^(?:test|build|run|install)$/.test(sub);
+        const mutation = MUTATORS.has(cmd) || git && GIT_WRITE.test(sub) || build && !/^(?:make|gmake|cmake|ninja)$/.test(cmd) && /^(?:test|build|install|add)$/.test(sub) || cmd === 'sed' && args.some(arg => /^-i|^--in-place/.test(arg)) || cmd === 'find' && args.includes('-delete');
+        if (build || git && GIT_EXEC.test(sub))
+            mask |= pathMask('.', 1, local);
+        if (/^(?:npm|pnpm|yarn|bun|pip\d*|brew|apt(?:-get)?)$/.test(cmd) && /^(?:install|add|publish)$/.test(sub))
+            mask |= bit('network', sub === 'publish' ? 2 : 4);
+        let pathSeen = false;
+        if (executable.includes('/')) {
+            mask |= pathMask(executable, 1, local);
+            pathSeen = true;
+        }
+        // Read/write tools conservatively require both operations on explicit operands,
+        // as in the reference scanner. Redirection destinations are write-only.
+        const permissions = mutation ? 6 : 4;
+        for (let i = 0; i < args.length; i += 1) {
+            let arg = args[i];
+            if (/^https?:\/\//i.test(arg))
+                continue;
+            if ((cmd === 'curl' && /^(?:-o|--output|-T|--upload-file)$/.test(arg)) || cmd === 'wget' && /^(?:-O|--output-document)$/.test(arg)) {
+                const target = args[++i];
+                if (target)
+                    mask |= pathMask(target, /^(?:-T|--upload-file)$/.test(arg) ? 4 : 2, local);
+                continue;
+            }
+            if (arg.startsWith('-')) {
+                const optionPath = arg.match(/=(\/[^\s]*|\.\.?\/[^\s]*)$/)?.[1];
+                if (!optionPath)
+                    continue;
+                arg = optionPath;
+            }
+            if (/^of=/.test(arg)) {
+                mask |= pathMask(arg.slice(3), 2, local);
+                pathSeen = true;
+                continue;
+            }
+            if (/^if=/.test(arg)) {
+                mask |= pathMask(arg.slice(3), 4, local);
+                pathSeen = true;
+                continue;
+            }
+            const explicit = /^(?:\/|\.\.?\/|~|\$HOME)/.test(arg) || SENSITIVE.test(arg);
+            if (explicit || READERS.has(cmd) || MUTATORS.has(cmd)) {
+                // Search expressions without path syntax are not filesystem targets.
+                if (['grep', 'egrep', 'fgrep', 'rg', 'sed', 'awk'].includes(cmd) && i === 0 && !explicit)
+                    continue;
+                mask |= pathMask(arg, permissions, local);
+                pathSeen = true;
+            }
+            if (interpreter && i === 0 && !arg.startsWith('-') && !explicit)
+                mask |= pathMask(arg, 1, local);
+        }
+        if (mutation && !pathSeen)
+            mask |= pathMask('.', 2, local);
+        if (cmd === 'cd') {
+            const target = args[0] ?? ctx.home;
+            mask |= pathMask(target || '$UNKNOWN_HOME', 4, local);
+            if (!/[$~*?\[\]]/.test(target))
+                cwd = path.resolve(cwd, target);
+            else
+                mask |= 0o7777;
+        }
+        // Unknown local programs can execute code; never classify them as mere reads.
+        if (!executable.includes('/') && !READERS.has(cmd) && !MUTATORS.has(cmd) && !interpreter && !build && !git && !NETWORK.test(cmd) && !['echo', 'printf', 'pwd', 'true', 'false', ':', 'test', '[', 'cd'].includes(cmd) && !/^(?:sudo|su|doas|shutdown|reboot|halt|poweroff|mkfs.*|fdisk|diskutil|mount|umount)$/.test(cmd))
+            mask |= pathMask('.', 1, local);
+    };
+    for (const token of tokens) {
+        if (token.operator && /^[;&|()]$|^&&$|^\|\|$/.test(token.text))
+            scan();
+        else
+            segment.push(token);
+    }
+    scan();
+    if (networkSeen && networkExecution)
+        mask |= bit('network', 1);
+    return format(mask || bit('workspace', 4));
+}

package/lib/index.js

@@ -0,0 +1,131 @@
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { allows, classifyTool } from './classify.js';
+export const name = 'bash-guard';
+export const inject = ['storageDomain', 'sessions', 'permissionPresets'];
+export const BASH_GUARD_DENIED = 'BASH_GUARD_DENIED';
+const valid = (value) => typeof value === 'string' && /^[0-7]{4}$(?![\s\S])/.test(value);
+export const recordSchema = {
+    parse(value) {
+        if (!value || !valid(value.mode) || typeof value.active !== 'boolean' || !Number.isSafeInteger(value.revision) || value.revision < 0 || !Number.isSafeInteger(value.presetSeq) || value.presetSeq < -1)
+            throw new Error('Invalid stored Bash Guard configuration');
+        return { mode: value.mode, active: value.active, revision: value.revision, presetSeq: value.presetSeq };
+    },
+};
+function presetBoundary(session) {
+    let boundary = -1;
+    const permissionRuns = new Set();
+    for (const event of session.snapshotEvents()) {
+        // Knob edits also invalidate the guard, even without a preset identity change.
+        if (['permission/preset', 'sandbox/mode', 'approval/policy'].includes(event.type))
+            boundary = event.seq;
+        if (event.type === 'command/run' && event.data.name === 'permission' && event.data.args?.trim())
+            permissionRuns.add(event.data.commandId);
+        if (event.type === 'command/done' && event.data.kind === 'success' && permissionRuns.has(event.data.commandId))
+            boundary = event.seq;
+    }
+    return boundary;
+}
+/** Standard Cordis service + source-mode Typert descriptors; the gateway supplies
+ * the { ok, value } RPC envelope, not these methods. No session command transport. */
+export class BashGuardService extends TypertRemoteService {
+    readState;
+    mutate;
+    constructor(ctx, readState, mutate) {
+        super(ctx, 'bashGuard');
+        this.readState = readState;
+        this.mutate = mutate;
+        // Invoke the installed standard-decorator API explicitly so both the host
+        // transpiler and source-mode test runners discover the same descriptors.
+        for (const method of ['get', 'update']) {
+            Remote(method)(this[method], {
+                kind: 'method', name: method, static: false, private: false,
+                access: { has: (object) => method in object, get: (object) => object[method] },
+                addInitializer: (initialize) => initialize.call(this),
+            });
+        }
+    }
+    get(sessionId) { return this.readState(sessionId); }
+    update(sessionId, request) { return this.mutate(sessionId, request); }
+}
+export async function apply(ctx, config = {}) {
+    const fallback = config.mode ?? '0467';
+    if (!valid(fallback))
+        throw new Error('bash-guard: expected four octal digits');
+    const domain = await ctx.storageDomain.open({ name: 'bash_guard', version: 1, layout: 'per-record', tables: { sessions: { valueSchema: recordSchema } } });
+    ctx.effect(() => () => domain.close());
+    const records = domain.table('sessions');
+    const queues = new Map();
+    const sessionId = (id) => {
+        if (typeof id !== 'string' || !id.trim())
+            throw new Error('A session ID is required');
+        return id;
+    };
+    const read = (id, session = ctx.sessions.get(sessionId(id))) => {
+        const stored = records.get(id);
+        const state = stored === undefined ? { mode: fallback, active: false, revision: 0, presetSeq: -1 } : recordSchema.parse(stored);
+        // A read never resumes a session or acquires its persistence writer. An
+        // unbound session cannot establish that its saved baseline still applies.
+        if (!session)
+            return state.active ? { ...state, active: false, revision: state.revision + 1 } : state;
+        const boundary = presetBoundary(session);
+        return state.active && boundary > state.presetSeq
+            ? { ...state, active: false, revision: state.revision + 1, presetSeq: boundary }
+            : state;
+    };
+    const serialized = (id, action) => {
+        const pending = (queues.get(id) ?? Promise.resolve()).catch(() => { }).then(action);
+        queues.set(id, pending);
+        void pending.finally(() => { if (queues.get(id) === pending)
+            queues.delete(id); }).catch(() => { });
+        return pending;
+    };
+    new BashGuardService(ctx, (id) => read(id), (id, request) => serialized(sessionId(id), async () => {
+        // Resolve inside the queue: never retain a stale binding across mutations.
+        const session = ctx.sessions.get(id);
+        if (!session)
+            throw new Error('Session is not live; open the session before changing Bash Guard');
+        const state = read(id, session);
+        if (!request || !['activate', 'mode', 'deactivate'].includes(request.action))
+            throw new Error('Unknown guard operation');
+        if (!Number.isSafeInteger(request.revision) || request.revision !== state.revision)
+            throw new Error('Guard configuration changed; reopen the permission menu');
+        if (state.revision >= Number.MAX_SAFE_INTEGER)
+            throw new Error('Guard revision exhausted');
+        if (request.action === 'mode' && (!state.active || !valid(request.mode)))
+            throw new Error('An active guard and four octal digits are required');
+        if (request.action === 'activate') {
+            // Installed permissionPresets.set uses canonical sandbox/approval setters.
+            // Never recursively execute a command against an already-running handler.
+            const baseline = ctx.permissionPresets.resolve('workspace-write');
+            if (baseline.sandbox !== 'workspace-write')
+                throw new Error('Workspace baseline must confine writes to the workspace');
+            ctx.permissionPresets.set(session, 'workspace-write');
+            if (ctx.permissionPresets.current(session) !== 'workspace-write')
+                throw new Error('Cannot activate workspace-write baseline');
+        }
+        const next = recordSchema.parse({
+            mode: request.action === 'mode' ? request.mode : state.mode,
+            active: request.action !== 'deactivate', revision: state.revision + 1,
+            presetSeq: presetBoundary(session),
+        });
+        await records.put(id, next);
+        return read(id);
+    }));
+    ctx.on('tools/execute', async (exec, next) => {
+        const session = exec.agent?.session;
+        if (!session)
+            return next();
+        // Observe writes already in flight before making a permission decision.
+        await queues.get(session.id);
+        const state = read(session.id, session);
+        if (!state.active)
+            return next();
+        const workspace = session.header.cwd ?? process.cwd();
+        const args = exec.arguments && typeof exec.arguments === 'object' ? exec.arguments : {};
+        const required = classifyTool(exec.name, args, { workspace, cwd: workspace });
+        if (required === undefined || allows(state.mode, required))
+            return next();
+        const message = `command blocked by bash safety policy (required=${required} allowed=${state.mode}; mode=system/external/network/workspace bits=4:read,2:write,1:execute). Adjust Bash Guard in the permission menu; do not bypass this policy.`;
+        return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true, error: { message, info: { name: 'BashGuardError', code: BASH_GUARD_DENIED } } };
+    });
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "dsh-bash-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "MIT",
+  "author": "lloydzhou (https://github.com/lloydzhou)",
+  "homepage": "https://github.com/lloydzhou/dsh-bash-guard#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lloydzhou/dsh-bash-guard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lloydzhou/dsh-bash-guard/issues"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "plugin",
+    "bash",
+    "permissions"
+  ],
+  "type": "module",
+  "description": "Workspace-based Bash Guard policy with native inline permission controls",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "client.js",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-permission-presets"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepack": "npm run build",
+    "test": "vitest run --config vitest.config.mjs"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.2"
+  }
+}