npm - @xth26/dsh-plan-build-mode - Versions diffs - 0.4.0 → 0.5.0 - Mend

@xth26/dsh-plan-build-mode 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/README.zh.md CHANGED Viewed

@@ -1,143 +1,237 @@
-# dsh-plan-build-mode
-OpenCode 风格的 Plan / Build 硬权限模型插件。
-本插件为 DSH 增加一个独立的 Plan/Build 模式切换，不影响 DSH 原生的 `/plan` 软提示模式：
-- **Plan 模式**：强制 `read-only` 沙箱，并拦截写工具（`write`、`edit`）。
-- **Build 模式**：恢复 `workspace-write`，允许编辑。
-写工具拦截仅在 Plan 模式配置为 `read-only` 时生效。首次使用或未切换时，默认处于 Build 模式。
-## 版本兼容性
-| 插件版本 | DSH 版本 | 说明 |
-|---|---|---|
-| `0.4.x` | `>= 0.1.5-rc.1` | 使用 `session.snapshotEvents()`；DSH 0.1.5 移除了 `session.events` 快照 getter。 |
-| `<= 0.3.1` | `0.1.0-rc.x` | 旧版本；在 DSH 0.1.5+ 上因上述 API 变更无法工作。 |
-## 安装
-DSH 插件通过 DSH profile 加载。把它装到你实际使用的 profile 里：
-```bash
-# 装到 web profile
-dsh plugin --profile web add @xth26/dsh-plan-build-mode
-# 装到 TUI profile
-dsh plugin --profile dsh-tui add @xth26/dsh-plan-build-mode
-```
-插件自带的 `cordis.patch.yml` 会在 DSH profile 加载时自动注入。
-## 让 Web 和 TUI 共享同一个 Plan/Build 模式
-Plan/Build 模式状态存在会话事件日志里（`sandbox/mode` 事件）。`dsh web` 和 `dsh --profile <名称>` 只有在共用同一个 profile、同一个 session ID 时，才会读写同一个会话事件流。
-- **同一个 profile**：比如 `dsh web --profile web` 和 `dsh --profile web` 启动的两个入口，会共享 session 事件，因此模式切换会同步生效。
-- **不同 profile**：默认 `web` 和 `dsh-tui` 是两个独立 profile，会话目录也分开。在一处切换不会影响另一处。
-想让 web 和 TUI 共享模式状态，最简单的方法是**两个入口都使用同一个 profile**：
-```bash
-# 两个入口都用 web profile
-dsh web --profile web
-dsh --profile web
-```
-如果你确实想用不同 profile，但只想共享会话存储，可以在每个 profile 的 `cordis.patch.yml` 里把 session root 指向同一个目录：
-```yaml
-- id: session-root
-  config:
-    root: /path/to/shared/sessions
-```
-注意：跨 profile 共享会话目录要求两个 profile 挂载的服务组合兼容，否则事件解释可能出现差异。
-## 本地开发 / link 试用
-想在发布前从本地源码试用：
-```bash
-# 在插件目录
-cd /path/to/dsh-plan-build-mode
-pnpm link --global
-# 在你的 DSH profile 目录
-pnpm link --global @xth26/dsh-plan-build-mode
-```
-然后启动 DSH。插件 `package.json` 里的 `dsh.bundle.patch` 会自动生效。
-## 更新
-对于 `0.x` 版本，semver 范围 `^0.1.0` 只会匹配 `0.1.x`，**永远不会**自动更新到 `0.2.0`。升级时必须显式提升声明并重启 DSH 进程：
-```bash
-# 在目标 profile 中提升已安装版本
-# （这条命令需要在非沙箱的终端里执行；DSH agent 无法写入 profile 目录）
-dsh plugin --profile dsh-tui add @xth26/dsh-plan-build-mode@0.4.0
-# 重启使用该 profile 的 DSH 进程
-# （旧的 Node 进程仍缓存着旧插件代码）
-Stop-Process -Name dsh -Force   # PowerShell
-# 或: taskkill /IM dsh.exe /F   # CMD
-```
-然后重新启动 `dsh web` 或 `dsh tui`。如果想始终安装最新发布版本：
-```bash
-dsh plugin --profile dsh-tui add @xth26/dsh-plan-build-mode@latest
-```
-## 使用
-| 命令 | 效果 |
-|---|---|
-| `/plan-build` | 在 Plan 与 Build 模式之间切换 |
-| `/plan-build status` | 显示当前模式 |
-| `/plan-build switch plan` | 进入 Plan 模式（只读） |
-| `/plan-build switch build` | 进入 Build 模式（可写） |
-| `/plan-build switch` | 同 `/plan-build`，切换当前模式 |
-## 配置
-```yaml
-- id: plan-build-mode
-  name: '@xth26/dsh-plan-build-mode'
-  config:
-    planSandbox: read-only
-    buildSandbox: workspace-write
-    denyWriteTools: true
-    section: true
-```
-`planSandbox` 和 `buildSandbox` 必须不同。
-## Plan 模式：命令行 Python 做数据检查
-Plan 模式只读并拦截 `write`/`edit` 工具，但**鼓励**在命令行里跑简短、只读的 Python 片段来读数据和验证假设。例如：
-```bash
-python -B -c "import json, sys; data = json.load(open('data/sample.json')); print(len(data))"
-python -B -c "import pandas as pd; print(pd.read_csv('data.csv').describe())"
-pytest -p no:cacheprovider -q tests/test_sanity.py
-```
-使用 `-B`（或设置 `PYTHONDONTWRITEBYTECODE=1`）以及 `pytest -p no:cacheprovider`，避免写入 `__pycache__` 或 `.pytest_cache`。read-only 沙箱仍是最终防线，任何试图写文件的命令仍会在沙箱层被拒绝。
-## 本地集成验证
-安装或 link 插件到 DSH profile 后：
-1. 启动 DSH。
-2. 输入 `/plan-build`，应提示进入 Plan 模式。
-3. 让 agent 调用 `write` 工具，应被拒绝。
-4. 再次输入 `/plan-build`，应提示进入 Build 模式。
-5. 再次让 agent 调用 `write`，应允许执行。
-6. 输入 `/plan-build status`，可只查看当前模式而不切换。
-## 许可证
-MIT
+# dsh-plan-build-mode
+OpenCode 风格的 Plan / Build 硬权限模型插件（DeepSeek Harness）。
+本插件为 DSH 增加一个独立的 Plan/Build 模式切换，并用 OpenCode 风格权限引擎
+（`allow | ask | deny`）对工具访问做门禁，不影响 DSH 原生的 `/plan` 软提示模式：
+- **Plan 模式按策略只读**：所有写类工具都被拒绝，唯一例外是写入配置的
+  plans 目录（`.opencode/plans/`）——这样 agent 在其余位置保持只读时，仍能持久化
+  计划文件。
+- **Build 模式可写**：可以执行已批准的计划。
+- **两种模式下读取都不受限**，包括工作区之外的文件——与 DSH 一致，读取在每种
+  沙箱模式下都放行。只有**修改**会被门禁（对应 OpenCode 的 `external_directory`）。
+- DSH 自带的 `/plan` 软提示模式保持原样。
+随附的 `cordis.patch.yml` 把两个沙箱都配置为 `workspace-write`；Plan 模式的
+“只读”由权限门禁而不是沙箱强制——这正是计划文件能写到 `.opencode/plans/`、
+其余位置保持只读的原因。
+## 版本兼容性
+| 插件版本 | DSH 版本 | 说明 |
+|---|---|---|
+| `0.5.x` | `>= 0.1.5-rc.1` | 新增 OpenCode 权限门禁与 `/permission`；模式由 `plan-build/mode` 会话事件承载（旧会话从 `sandbox/mode` 推断）。 |
+| `0.4.x` | `>= 0.1.5-rc.1` | 使用 `session.snapshotEvents()`；DSH 0.1.5 移除了 `session.events` 快照 getter。 |
+| `<= 0.3.1` | `0.1.0-rc.x` | 旧版本；在 DSH 0.1.5+ 上因上述 API 变更无法工作。 |
+## 安装
+DSH 插件通过 DSH profile 加载。把它装到你实际使用的 profile 里：
+```bash
+# 装到 web profile
+dsh plugin --profile web add @xth26/dsh-plan-build-mode
+# 装到 TUI profile
+dsh plugin --profile dsh-tui add @xth26/dsh-plan-build-mode
+```
+插件自带的 `cordis.patch.yml` 会在 DSH profile 加载时自动注入。
+## 让 Web 和 TUI 共享同一个 Plan/Build 模式
+Plan/Build 模式状态存在会话事件日志里（插件专属的 `plan-build/mode` 事件，
+以及用于沙箱执行的 `sandbox/mode` 事件）。`dsh web` 和 `dsh --profile <名称>`
+只有在共用同一个 profile、同一个 session ID 时，才会读写同一个会话事件流。
+- **同一个 profile**：比如 `dsh web --profile web` 和 `dsh --profile web` 启动的两个入口，会共享 session 事件，因此模式切换会同步生效。
+- **不同 profile**：默认 `web` 和 `dsh-tui` 是两个独立 profile，会话目录也分开。在一处切换不会影响另一处。
+想让 web 和 TUI 共享模式状态，最简单的方法是**两个入口都使用同一个 profile**：
+```bash
+# 两个入口都用 web profile
+dsh web --profile web
+dsh --profile web
+```
+如果你确实想用不同 profile，但只想共享会话存储，可以在每个 profile 的 `cordis.patch.yml` 里把 session root 指向同一个目录：
+```yaml
+- id: session-root
+  config:
+    root: /path/to/shared/sessions
+```
+注意：跨 profile 共享会话目录要求两个 profile 挂载的服务组合兼容，否则事件解释可能出现差异。
+## 本地开发 / link 试用
+想在发布前从本地源码试用：
+```bash
+# 在插件目录
+cd /path/to/dsh-plan-build-mode
+pnpm link --global
+# 在你的 DSH profile 目录
+pnpm link --global @xth26/dsh-plan-build-mode
+```
+然后启动 DSH。插件 `package.json` 里的 `dsh.bundle.patch` 会自动生效。
+## 更新
+对于 `0.x` 版本，semver 范围 `^0.1.0` 只会匹配 `0.1.x`，**永远不会**自动更新到 `0.2.0`。升级时必须显式提升声明并重启 DSH 进程：
+```bash
+# 在目标 profile 中提升已安装版本
+# （这条命令需要在非沙箱的终端里执行；DSH agent 无法写入 profile 目录）
+dsh plugin --profile dsh-tui add @xth26/dsh-plan-build-mode@0.5.0
+# 重启使用该 profile 的 DSH 进程
+# （旧的 Node 进程仍缓存着旧插件代码）
+Stop-Process -Name dsh -Force   # PowerShell
+# 或: taskkill /IM dsh.exe /F   # CMD
+```
+然后重新启动 `dsh web` 或 `dsh tui`。如果想始终安装最新发布版本：
+```bash
+dsh plugin --profile dsh-tui add @xth26/dsh-plan-build-mode@latest
+```
+### 升级说明（0.4.x → 0.5.x）
+- `planSandbox` 与 `buildSandbox` **现在可以相等**（随附补丁两者都用
+  `workspace-write`）；Plan 模式的只读策略由权限门禁强制。旧的“必须不同”限制已移除。
+- 模式状态迁移到插件专属的 `plan-build/mode` 事件。只有 `sandbox/mode` 事件的旧
+  会话会在加载时被推断并在会话开始时固定为真实的 `plan-build/mode` 事件，历史不丢失。
+- 旧的 `denyWriteTools` 选项仍然有效：设为 `false` 允许 agent 在 Plan 模式写入
+  （等价于覆盖 `modes.plan.edit = allow`）。
+## 使用
+| 命令 | 效果 |
+|---|---|
+| `/plan-build` | 在 Plan 与 Build 模式之间切换 |
+| `/plan-build status` | 显示当前模式 |
+| `/plan-build switch plan` | 进入 Plan 模式（策略只读） |
+| `/plan-build switch build` | 进入 Build 模式（可写） |
+| `/plan-build switch` | 同 `/plan-build`，切换当前模式 |
+| `/permission status` | 显示外部路径默认值、规则与本次会话的 allowlist |
+| `/permission allow <pattern>` | 把模式加入本次会话 allowlist（OpenCode 的 “always”） |
+| `/permission deny <pattern>` | 从本次会话 allowlist 移除该模式 |
+## 配置
+```yaml
+- id: plan-build-mode
+  name: '@xth26/dsh-plan-build-mode'
+  config:
+    planSandbox: workspace-write
+    buildSandbox: workspace-write
+    denyWriteTools: true
+    section: true
+    plansDirectory: .opencode/plans
+    externalDirectory:
+      default: allow   # allow | ask | deny —— 工作区之外的读取
+```
+`planSandbox` 和 `buildSandbox` 可以相等，也可以不同。不同时，模式切换还会联动
+沙箱（`read-only` ↔ `workspace-write` 等）；相等时（随附默认），Plan 模式的策略由
+权限门禁强制。
+### 权限模型
+每个工具映射到一个类别：
+| 类别 | 工具 |
+|---|---|
+| `read` | `read`、`read_image`、`pdf_read`、`docx_read`、`pptx_read`、`xlsx_read` |
+| `edit` | `write`、`edit`、`pdf_create`、`docx_create`、`pptx_create`、`xlsx_write`、`xlsx_edit` |
+| `glob` | `glob` |
+| `grep` | `grep` |
+| `bash` | `bash` |
+| `pwsh` | `pwsh` |
+| `webfetch` | `web_fetch` |
+| `websearch` | `web_search` |
+类别值可以是标量（`allow | ask | deny`），也可以是带顺序的对象规则，和 OpenCode 一致：
+```yaml
+permission:
+  read:
+    '*': allow
+    '**/.env': deny
+    '**/.env.*': deny
+    '**/.env.example': allow   # 最后匹配的规则生效
+  bash: ask
+  edit: deny
+```
+模式支持 OpenCode 通配符（`*` 匹配任意字符、含 `/`；`?` 恰好匹配一个字符；
+`**` 与 `*` 相同）以及 `~`/`$HOME` 展开。规则按“最后匹配者胜出”求值。默认规则对齐
+OpenCode：大多数类别 `allow`；`.env*` 读取被拒绝（`.env.example` 恢复为允许）。
+Plan 模式覆盖默认值（除非被 `modes.plan` 或 `denyWriteTools: false` 覆盖）：
+`edit: deny`、`bash: ask`、`pwsh: ask`——对应 OpenCode plan agent 的默认值。
+`modes.plan` / `modes.build` 按模式覆盖全局权限，类似 OpenCode 的 agent 级覆盖。
+```yaml
+modes:
+  plan:
+    bash: deny   # 替代默认的 ask
+  build:
+    read: allow
+```
+### Plans 目录例外
+在 Plan 模式下，写入 `plansDirectory`（默认 `.opencode/plans/`，相对会话工作区）
+下的 `edit` 类工具**始终允许**，保证 `/plan-build` 与计划文件正常工作。Plan 模式下
+其它所有写入都会被拒绝，理由中包含 `forbidden in Plan Mode`。
+### 外部路径
+- **读取**工作区之外的文件在两种模式下默认都允许（`externalDirectory.default:
+  allow`）。设为 `ask` 可获得完整的 OpenCode 行为：对外部读取发起审批请求。
+- **写入**工作区之外由沙箱决定。在 `workspace-write` 下无法放行，因此插件不会
+  弹审批（那也会在沙箱层失败），而是直接拒绝并给出升级提示——用
+  `sandbox_permissions` + `justification` 重试同一个工具。
+- `/permission allow <pattern>` 会加入一个会话级 allowlist 条目（OpenCode
+  “always”），仅在该会话内存中保留。
+## Plan 模式：命令行 Python 做数据检查
+Plan 模式拒绝 `write`/`edit` 工具，但**鼓励**在命令行里跑简短、只读的 Python
+片段来读数据和验证假设。例如：
+```bash
+python -B -c "import json, sys; data = json.load(open('data/sample.json')); print(len(data))"
+python -B -c "import pandas as pd; print(pd.read_csv('data.csv').describe())"
+pytest -p no:cacheprovider -q tests/test_sanity.py
+```
+使用 `-B`（或设置 `PYTHONDONTWRITEBYTECODE=1`）以及 `pytest -p no:cacheprovider`，
+避免写入 `__pycache__` 或 `.pytest_cache`。权限门禁与沙箱是最终防线：任何试图写文件的
+操作都会在门禁（Plan 模式）或沙箱层（Build 模式）被拦截。
+## 本地集成验证
+安装或 link 插件到 DSH profile 后：
+1. 启动 DSH。
+2. 输入 `/plan-build`，应提示进入 Plan 模式（策略只读）。
+3. 让 agent 对 `src/x.ts` 调用 `write`，应被拒绝，理由包含 `forbidden in Plan Mode`。
+4. 让 agent 对 `.opencode/plans/x.md` 调用 `write`，应**允许**（plans 目录例外）。
+5. 再次输入 `/plan-build`，应提示进入 Build 模式。
+6. 让 agent 对 `src/x.ts` 调用 `write`，应允许执行。
+7. 让 agent 读取工作区之外的文件，应无需提示直接放行（默认 `external_directory: allow`）。
+8. 输入 `/permission status` 查看门禁状态；可尝试 `/permission allow ~/projects/**` 添加会话 allowlist。
+9. 输入 `/plan-build status`，可只查看当前模式而不切换。
+## 许可证
+MIT

package/cordis.patch.yml CHANGED Viewed

@@ -1,10 +1,22 @@
 # Profile patch for dsh-plan-build-mode.
 # Loaded automatically when the package is installed in a DSH profile.
+#
+# OpenCode-aligned defaults (v0.5.0):
+# - planSandbox == buildSandbox == workspace-write: "read-only" in Plan mode is
+#   enforced by the permission gate (deny every write except the plans
+#   directory), not by the sandbox — so plan files can be persisted under
+#   .opencode/plans/.
+# - externalDirectory.default: allow — reading files outside the workspace
+#   stays permitted in both modes; only writes are gated. Set to 'ask' for
+#   full OpenCode behavior (external access prompts).
 - insert:
     - id: plan-build-mode
       name: '@xth26/dsh-plan-build-mode'
       config:
-        planSandbox: read-only
+        planSandbox: workspace-write
         buildSandbox: workspace-write
         denyWriteTools: true
         section: true
+        plansDirectory: .opencode/plans
+        externalDirectory:
+          default: allow

package/lib/helpers.d.ts CHANGED Viewed

@@ -12,6 +12,10 @@ export declare const DEFAULT_PLAN_SANDBOX: SandboxMode;
 export declare const DEFAULT_BUILD_SANDBOX: SandboxMode;
 /** Tools forbidden while in Plan mode. */
 export declare const WRITE_TOOLS: Set<string>;
+/** The durable Plan/Build mode event owned by this plugin. */
+export declare const MODE_EVENT: "plan-build/mode";
+/** A session's Plan/Build mode. */
+export type PlanBuildMode = 'plan' | 'build';
 /**
  * Return the most recently written sandbox mode for a session, or undefined
  * when the session has never switched.
@@ -22,15 +26,24 @@ export declare const WRITE_TOOLS: Set<string>;
  */
 export declare function currentSandboxMode(session: Session): SandboxMode | undefined;
 /**
- * Whether the session is currently in OpenCode Plan mode.
- * Plan mode is defined as the current sandbox mode matching the configured
- * planSandbox (read-only by default).
+ * The session's durable Plan/Build mode: the last `plan-build/mode` event, or
+ * an inference from the last `sandbox/mode` event against `planSandbox` for
+ * sessions created before the mode event existed. Returns undefined only when
+ * the session log carries neither.
+ */
+export declare function currentPlanBuildMode(session: Session, planSandbox: SandboxMode): PlanBuildMode | undefined;
+/**
+ * Whether the session is currently in OpenCode Plan mode. The plugin's own
+ * `plan-build/mode` event is authoritative; legacy sessions (only
+ * `sandbox/mode` events) fall back to "current sandbox equals planSandbox".
  */
 export declare function isPlanModeActive(session: Session, planSandbox: SandboxMode): boolean;
 /**
- * Append a `sandbox/mode` event to switch between Plan and Build mode.
+ * Append the durable `plan-build/mode` event to switch between Plan and Build
+ * mode, and — only when the target sandbox actually differs from the current
+ * one — the `sandbox/mode` event for sandbox enforcement.
  */
-export declare function setPlanBuildMode(agent: Agent, mode: 'plan' | 'build', planSandbox: SandboxMode, buildSandbox: SandboxMode): void;
+export declare function setPlanBuildMode(agent: Agent, mode: PlanBuildMode, planSandbox: SandboxMode, buildSandbox: SandboxMode): void;
 /**
  * Compute a denial reason if a tool call should be blocked in Plan mode.
  * Returns `undefined` when the call is allowed.
@@ -39,6 +52,9 @@ export declare function setPlanBuildMode(agent: Agent, mode: 'plan' | 'build', p
  * configured as read-only. If Plan mode is configured to a writable sandbox,
  * the plugin still tracks the mode but does not block tools — the real
  * protection is the read-only sandbox.
+ *
+ * Kept for backward compatibility; the plugin's full permission gate
+ * (`permissions.ts`) supersedes this check.
  */
 export declare function planModeDenial(exec: ToolExecution, planSandbox: SandboxMode, writeTools?: ReadonlySet<string>): string | undefined;
 //# sourceMappingURL=helpers.d.ts.map

package/lib/helpers.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAG3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;~~AAE3D~~,sDAAsD;AACtD,eAAO,MAAM,oBAAoB,EAAE,WAAyB,CAAA;AAE5D,uDAAuD;AACvD,eAAO,MAAM,qBAAqB,EAAE,WAA+B,CAAA;AAEnE,0CAA0C;AAC1C,eAAO,MAAM,WAAW,aAA6B,CAAA;AAErD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAS5E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAEpF;AAED~~;;GAEG~~;AACH,wBAAgB,gBAAgB,~~CAAC~~,KAAK,EAAE,KAAK,~~EAAE~~,IAAI,EAAE,~~MAAM~~,~~GAAG~~,~~OAAO,EAAE,~~WAAW,EAAE,WAAW,~~EAAE~~,YAAY,EAAE,WAAW,~~GAAG~~,IAAI,~~CAGhI~~;AAED~~;;;;;;;;GAQG~~;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,aAAa,EACnB,WAAW,EAAE,WAAW,EACxB,UAAU,GAAE,WAAW,CAAC,MAAM,CAAe,GAC5C,MAAM,GAAG,SAAS,CAQpB"}
1	+ {"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAG3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAI3D,sDAAsD;AACtD,eAAO,MAAM,oBAAoB,EAAE,WAAyB,CAAA;AAE5D,uDAAuD;AACvD,eAAO,MAAM,qBAAqB,EAAE,WAA+B,CAAA;AAEnE,0CAA0C;AAC1C,eAAO,MAAM,WAAW,aAA6B,CAAA;AAErD,8DAA8D;AAC9D,eAAO,MAAM,UAAU,EAAG,iBAA0B,CAAA;AAEpD,mCAAmC;AACnC,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,CAAA;AAE5C;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAS5E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,GAAG,aAAa,GAAG,SAAS,CAe1G;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,aAAa,EACnB,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,WAAW,GACxB,IAAI,CAMN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,aAAa,EACnB,WAAW,EAAE,WAAW,EACxB,UAAU,GAAE,WAAW,CAAC,MAAM,CAAe,GAC5C,MAAM,GAAG,SAAS,CAQpB"}

package/lib/helpers.js CHANGED Viewed

@@ -8,6 +8,8 @@ export const DEFAULT_PLAN_SANDBOX = 'read-only';
 export const DEFAULT_BUILD_SANDBOX = 'workspace-write';
 /** Tools forbidden while in Plan mode. */
 export const WRITE_TOOLS = new Set(['write', 'edit']);
+/** The durable Plan/Build mode event owned by this plugin. */
+export const MODE_EVENT = 'plan-build/mode';
 /**
  * Return the most recently written sandbox mode for a session, or undefined
  * when the session has never switched.
@@ -27,19 +29,46 @@ export function currentSandboxMode(session) {
     return undefined;
 }
 /**
- * Whether the session is currently in OpenCode Plan mode.
- * Plan mode is defined as the current sandbox mode matching the configured
- * planSandbox (read-only by default).
+ * The session's durable Plan/Build mode: the last `plan-build/mode` event, or
+ * an inference from the last `sandbox/mode` event against `planSandbox` for
+ * sessions created before the mode event existed. Returns undefined only when
+ * the session log carries neither.
+ */
+export function currentPlanBuildMode(session, planSandbox) {
+    const events = session.snapshotEvents();
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        const event = events[i];
+        if (event.type === MODE_EVENT) {
+            return event.data.mode;
+        }
+    }
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        const event = events[i];
+        if (event.type === 'sandbox/mode') {
+            return event.data.mode === planSandbox ? 'plan' : 'build';
+        }
+    }
+    return undefined;
+}
+/**
+ * Whether the session is currently in OpenCode Plan mode. The plugin's own
+ * `plan-build/mode` event is authoritative; legacy sessions (only
+ * `sandbox/mode` events) fall back to "current sandbox equals planSandbox".
  */
 export function isPlanModeActive(session, planSandbox) {
-    return currentSandboxMode(session) === planSandbox;
+    return currentPlanBuildMode(session, planSandbox) === 'plan';
 }
 /**
- * Append a `sandbox/mode` event to switch between Plan and Build mode.
+ * Append the durable `plan-build/mode` event to switch between Plan and Build
+ * mode, and — only when the target sandbox actually differs from the current
+ * one — the `sandbox/mode` event for sandbox enforcement.
  */
 export function setPlanBuildMode(agent, mode, planSandbox, buildSandbox) {
+    agent.session.append(MODE_EVENT, { mode });
     const target = mode === 'plan' ? planSandbox : buildSandbox;
-    agent.session.append('sandbox/mode', { mode: target });
+    if (currentSandboxMode(agent.session) !== target) {
+        agent.session.append('sandbox/mode', { mode: target });
+    }
 }
 /**
  * Compute a denial reason if a tool call should be blocked in Plan mode.
@@ -49,6 +78,9 @@ export function setPlanBuildMode(agent, mode, planSandbox, buildSandbox) {
  * configured as read-only. If Plan mode is configured to a writable sandbox,
  * the plugin still tracks the mode but does not block tools — the real
  * protection is the read-only sandbox.
+ *
+ * Kept for backward compatibility; the plugin's full permission gate
+ * (`permissions.ts`) supersedes this check.
  */
 export function planModeDenial(exec, planSandbox, writeTools = WRITE_TOOLS) {
     if (exec.agent === undefined)

package/lib/helpers.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;~~AASH~~,sDAAsD;AACtD,MAAM,CAAC,MAAM,oBAAoB,GAAgB,WAAW,CAAA;AAE5D,uDAAuD;AACvD,MAAM,CAAC,MAAM,qBAAqB,GAAgB,iBAAiB,CAAA;AAEnE,0CAA0C;AAC1C,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA;AAErD;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,MAAM,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAA;IACvC,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAE,CAAA;QACxB,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YAClC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAA;QACxB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,WAAwB;IACzE,OAAO,~~kBAAkB~~,CAAC,OAAO,CAAC,KAAK,~~WAAW~~,CAAA;~~AACpD~~,CAAC;AAED~~;;GAEG~~;AACH,MAAM,UAAU,gBAAgB,~~CAAC~~,KAAY,~~EAAE~~,~~IAAsB~~,~~EAAE~~,WAAwB,~~EAAE~~,YAAyB;~~IACxH~~,MAAM,MAAM,GAAgB,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,CAAA;IACxE,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAA;~~AACxD~~,CAAC;AAED~~;;;;;;;;GAQG~~;AACH,MAAM,UAAU,cAAc,CAC5B,IAAmB,EACnB,WAAwB,EACxB,aAAkC,WAAW;IAE7C,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IAC9C,IAAI,WAAW,KAAK,WAAW;QAAE,OAAO,SAAS,CAAA;IACjD,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC;QAAE,OAAO,SAAS,CAAA;IACxE,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,OAAO,SAAS,IAAI,CAAC,IAAI,qHAAqH,CAAA;IAChJ,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC"}
1	+ {"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts CHANGED Viewed

@@ -1,16 +1,23 @@
 /**
  * Host half of `dsh-plan-build-mode`.
  *
- * Implements an OpenCode-style Plan / Build mode that is independent from
- * DSH's built-in `/plan` soft-guidance mode:
+ * Implements an OpenCode-style Plan / Build mode with a tool permission gate:
  *
  * - `/plan-build`             -> Toggle between Plan and Build modes
  * - `/plan-build status`      -> Show the current mode
- * - `/plan-build switch plan`  -> Plan mode + read-only sandbox
- * - `/plan-build switch build` -> Build mode + workspace-write sandbox
- * - Blocks `write`/`edit` tool calls while in Plan mode
+ * - `/plan-build switch plan`  -> Plan mode (read-only by policy)
+ * - `/plan-build switch build` -> Build mode (writable)
+ * - `/permission status|allow|deny` -> Inspect / adjust the permission gate
+ * - Denies write-category tools while in Plan mode (OpenCode `edit` permission)
+ * - Permits reads outside the workspace (DSH reads pass through every mode);
+ *   external writes stay gated by the sandbox unless `external_directory` is
+ *   configured to `ask`
  * - Injects a `plan-build:policy` system prompt section
  *
+ * Mode state lives in the plugin-owned `plan-build/mode` session event; the
+ * `sandbox/mode` event is still written for sandbox enforcement whenever the
+ * target sandbox actually differs.
+ *
  * @module dsh-plan-build-mode
  */
 import type { Context } from '@deepseek-ai/cordis';
@@ -21,21 +28,11 @@ export declare const name = "dsh-plan-build-mode";
 /**
  * Service dependencies for the host half. `commands` is injected optionally at
  * runtime via ctx.inject(['commands'], ...) so headless assemblies stay
- * unaffected; the hard services are systemPrompt and tools.
+ * unaffected; `approval` is read optionally via ctx.get('approval').
  */
 export declare const inject: readonly ["tools", "systemPrompt"];
 /** Configuration schema. */
-export declare const Config: z<Schemastery.ObjectS<{
-    planSandbox: z<"read-only" | "workspace-write" | "danger-full-access", "read-only" | "workspace-write" | "danger-full-access">;
-    buildSandbox: z<"read-only" | "workspace-write" | "danger-full-access", "read-only" | "workspace-write" | "danger-full-access">;
-    denyWriteTools: z<boolean, boolean>;
-    section: z<boolean, boolean>;
-}>, Schemastery.ObjectT<{
-    planSandbox: z<"read-only" | "workspace-write" | "danger-full-access", "read-only" | "workspace-write" | "danger-full-access">;
-    buildSandbox: z<"read-only" | "workspace-write" | "danger-full-access", "read-only" | "workspace-write" | "danger-full-access">;
-    denyWriteTools: z<boolean, boolean>;
-    section: z<boolean, boolean>;
-}>>;
+export declare const Config: z;
 /**
  * Plugin entry point.
  * @param ctx - Cordis context carrying the injected services.

package/lib/index.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA~~;;;;;;;;;;;;;;GAcG~~;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;~~AAClD~~,OAAO,CAAC,MAAM,0BAA0B,CAAA;~~AAmBxC~~,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD,0BAA0B;AAC1B,eAAO,MAAM,IAAI,wBAAwB,CAAA;AACzC;;;;GAIG;AACH,eAAO,MAAM,MAAM,oCAAqC,CAAA;~~AACxD~~,4BAA4B;AAC5B,eAAO,MAAM,MAAM~~;;;;;;;;;;GAajB~~,CAAA;~~AAEF~~;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,mBAAwB,GAAG,IAAI,~~CAgG1E~~"}
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AA0CxC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD,0BAA0B;AAC1B,eAAO,MAAM,IAAI,wBAAwB,CAAA;AACzC;;;;GAIG;AACH,eAAO,MAAM,MAAM,oCAAqC,CAAA;AAOxD,4BAA4B;AAC5B,eAAO,MAAM,MAAM,EAeF,CAAC,CAAA;AAElB;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,mBAAwB,GAAG,IAAI,CAyK1E"}