@xth26/dsh-plan-build-mode 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# dsh-plan-build-mode
+
+OpenCode-style Plan / Build hard permission model for DeepSeek Harness.
+
+This plugin adds an independent Plan/Build mode switch to DSH:
+
+- **Plan mode** enforces a `read-only` sandbox and blocks mutating tools (`write`, `edit`).
+- **Build mode** restores `workspace-write` and allows edits.
+- DSH's built-in `/plan` soft-guidance mode is left untouched.
+
+The tool denial only takes effect when Plan mode is configured as `read-only`. When the session has not been switched, Build mode is active by default.
+
+## Installation
+
+DSH plugins are loaded through a DSH profile. Install the plugin into the profile(s) you use:
+
+```bash
+# For the web profile
+dsh plugin --profile web add @xth26/dsh-plan-build-mode
+
+# For the TUI profile
+dsh plugin --profile dsh-tui add @xth26/dsh-plan-build-mode
+```
+
+The plugin ships with a `cordis.patch.yml` that auto-injects the required row
+when the package is loaded by a DSH profile.
+
+## Using the same Plan/Build mode in both web and TUI
+
+Plan/Build mode state is stored in the session event log (`sandbox/mode` event). Both `dsh web` and `dsh --profile <name>` use the same session store when they share the same profile and session ID.
+
+- **Same profile**: if you run `dsh web --profile web` and `dsh --profile web`, the mode is shared because the session events are shared.
+- **Different profiles**: by default `web` and `dsh-tui` are separate profiles with separate session directories. Switching in one does **not** affect the other.
+
+To make web and TUI share the same mode and session history, use the **same profile** for both:
+
+```bash
+# Use the web profile for both interfaces
+dsh web --profile web
+dsh --profile web
+```
+
+Or, if you prefer to keep separate profiles but want to share only the session store, override the session root in each profile's `cordis.patch.yml` to point to the same directory:
+
+```yaml
+- id: session-root
+  config:
+    root: /path/to/shared/sessions
+```
+
+Note: sharing session directories across profiles requires both profiles to mount compatible service bundles; otherwise event interpretation may differ.
+
+## Local development / link
+
+To try the plugin from a local checkout without publishing:
+
+```bash
+# From the plugin checkout
+cd /path/to/dsh-plan-build-mode
+pnpm link --global
+
+# From your DSH profile directory
+pnpm link --global @xth26/dsh-plan-build-mode
+```
+
+Then start DSH with that profile. The `dsh.bundle.patch` field in the plugin's
+`package.json` makes the patch apply automatically.
+
+## Usage
+
+| Command | Effect |
+|---|---|
+| `/plan-build` | Show the current mode |
+| `/plan-build switch plan` | Enter Plan mode (read-only) |
+| `/plan-build switch build` | Enter Build mode (writable) |
+| `/plan-build switch` | Toggle between plan and build |
+
+## Configuration
+
+```yaml
+- id: plan-build-mode
+  name: '@xth26/dsh-plan-build-mode'
+  config:
+    planSandbox: read-only
+    buildSandbox: workspace-write
+    denyWriteTools: true
+    section: true
+```
+
+## Local integration check
+
+After installing/linking the plugin in a DSH profile:
+
+1. Start DSH with that profile.
+2. Run `/plan-build switch plan`. You should see a confirmation that Plan mode
+   is active.
+3. Ask the agent to call the `write` tool. It should be denied with a reason.
+4. Run `/plan-build switch build`. You should see a confirmation that Build mode
+   is active.
+5. Ask the agent to call `write` again. It should now be allowed.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,99 @@
+# 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 插件通过 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` 会自动生效。
+
+## 使用
+
+| 命令 | 效果 |
+|---|---|
+| `/plan-build` | 显示当前模式 |
+| `/plan-build switch plan` | 进入 Plan 模式（只读） |
+| `/plan-build switch build` | 进入 Build 模式（可写） |
+| `/plan-build switch` | 切换当前模式 |
+
+## 配置
+
+```yaml
+- id: plan-build-mode
+  name: '@xth26/dsh-plan-build-mode'
+  config:
+    planSandbox: read-only
+    buildSandbox: workspace-write
+    denyWriteTools: true
+    section: true
+```
+
+## 本地集成验证
+
+安装或 link 插件到 DSH profile 后：
+
+1. 启动 DSH。
+2. 输入 `/plan-build switch plan`，应提示进入 Plan 模式。
+3. 让 agent 调用 `write` 工具，应被拒绝。
+4. 输入 `/plan-build switch build`，应提示进入 Build 模式。
+5. 再次让 agent 调用 `write`，应允许执行。
+
+## 许可证
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# Profile patch for dsh-plan-build-mode.
+# Loaded automatically when the package is installed in a DSH profile.
+- insert:
+    - id: plan-build-mode
+      name: '@xth26/dsh-plan-build-mode'
+      config:
+        planSandbox: read-only
+        buildSandbox: workspace-write
+        denyWriteTools: true
+        section: true

package/lib/helpers.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure helpers for OpenCode-style Plan/Build mode switching.
+ * @module dsh-plan-build-mode/helpers
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+/** Default sandbox mode while Plan mode is active. */
+export declare const DEFAULT_PLAN_SANDBOX: SandboxMode;
+/** Default sandbox mode while Build mode is active. */
+export declare const DEFAULT_BUILD_SANDBOX: SandboxMode;
+/** Tools forbidden while in Plan mode. */
+export declare const WRITE_TOOLS: Set<string>;
+/**
+ * Return the most recently written sandbox mode for a session, or undefined
+ * when the session has never switched.
+ */
+export declare function currentSandboxMode(events: readonly SessionEvent[]): 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).
+ */
+export declare function isPlanModeActive(events: readonly SessionEvent[], planSandbox: SandboxMode): boolean;
+/**
+ * Append a `sandbox/mode` event to switch between Plan and Build mode.
+ */
+export declare function setPlanBuildMode(agent: Agent, mode: 'plan' | 'build', 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.
+ *
+ * Write tools are denied only when Plan mode is active AND Plan mode is
+ * 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.
+ */
+export declare function planModeDenial(exec: ToolExecution, planSandbox: SandboxMode, writeTools?: ReadonlySet<string>): string | undefined;
+//# sourceMappingURL=helpers.d.ts.map

package/lib/helpers.d.ts.map

@@ -0,0 +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,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAC5D,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;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,WAAW,GAAG,SAAS,CAQ3F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAEnG;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"}

package/lib/helpers.js

@@ -0,0 +1,60 @@
+/**
+ * Pure helpers for OpenCode-style Plan/Build mode switching.
+ * @module dsh-plan-build-mode/helpers
+ */
+/** Default sandbox mode while Plan mode is active. */
+export const DEFAULT_PLAN_SANDBOX = 'read-only';
+/** Default sandbox mode while Build mode is active. */
+export const DEFAULT_BUILD_SANDBOX = 'workspace-write';
+/** Tools forbidden while in Plan mode. */
+export const WRITE_TOOLS = new Set(['write', 'edit']);
+/**
+ * Return the most recently written sandbox mode for a session, or undefined
+ * when the session has never switched.
+ */
+export function currentSandboxMode(events) {
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        const event = events[i];
+        if (event.type === 'sandbox/mode') {
+            return event.data.mode;
+        }
+    }
+    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).
+ */
+export function isPlanModeActive(events, planSandbox) {
+    return currentSandboxMode(events) === planSandbox;
+}
+/**
+ * Append a `sandbox/mode` event to switch between Plan and Build mode.
+ */
+export function setPlanBuildMode(agent, mode, planSandbox, buildSandbox) {
+    const target = mode === 'plan' ? planSandbox : buildSandbox;
+    agent.session.append('sandbox/mode', { mode: target });
+}
+/**
+ * Compute a denial reason if a tool call should be blocked in Plan mode.
+ * Returns `undefined` when the call is allowed.
+ *
+ * Write tools are denied only when Plan mode is active AND Plan mode is
+ * 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.
+ */
+export function planModeDenial(exec, planSandbox, writeTools = WRITE_TOOLS) {
+    if (exec.agent === undefined)
+        return undefined;
+    if (planSandbox !== 'read-only')
+        return undefined;
+    if (!isPlanModeActive(exec.agent.session.events, planSandbox))
+        return undefined;
+    if (writeTools.has(exec.name)) {
+        return `Tool '${exec.name}' is forbidden in Plan Mode. Leave Plan Mode with /plan-build switch build before editing files.`;
+    }
+    return undefined;
+}
+//# sourceMappingURL=helpers.js.map

package/lib/helpers.js.map

@@ -0,0 +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;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAA+B;IAChE,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,MAA+B,EAAE,WAAwB;IACxF,OAAO,kBAAkB,CAAC,MAAM,CAAC,KAAK,WAAW,CAAA;AACnD,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,CAAC,MAAM,EAAE,WAAW,CAAC;QAAE,OAAO,SAAS,CAAA;IAC/E,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,OAAO,SAAS,IAAI,CAAC,IAAI,kGAAkG,CAAA;IAC7H,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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:
+ *
+ * - `/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
+ * - Injects a `plan-build:policy` system prompt section
+ *
+ * @module dsh-plan-build-mode
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { PlanBuildModeConfig } from './types.ts';
+/** Cordis plugin name. */
+export declare const name = "dsh-plan-build-mode";
+/** Service dependencies for the host half. */
+export declare const inject: readonly ["agents", "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>;
+}>>;
+/**
+ * Plugin entry point.
+ * @param ctx - Cordis context carrying the injected services.
+ * @param config - Validated deployment configuration.
+ */
+export declare function apply(ctx: Context, config?: PlanBuildModeConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;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,8CAA8C;AAC9C,eAAO,MAAM,MAAM,8CAA+C,CAAA;AAClE,4BAA4B;AAC5B,eAAO,MAAM,MAAM;;;;;;;;;;GAajB,CAAA;AAEF;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,mBAAwB,GAAG,IAAI,CAkG1E"}

package/lib/index.js

@@ -0,0 +1,130 @@
+/**
+ * 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:
+ *
+ * - `/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
+ * - Injects a `plan-build:policy` system prompt section
+ *
+ * @module dsh-plan-build-mode
+ */
+import z from '@deepseek-ai/schemastery';
+import { DEFAULT_BUILD_SANDBOX, DEFAULT_PLAN_SANDBOX, isPlanModeActive, planModeDenial, setPlanBuildMode, WRITE_TOOLS, } from "./helpers.js";
+/** Cordis plugin name. */
+export const name = 'dsh-plan-build-mode';
+/** Service dependencies for the host half. */
+export const inject = ['agents', 'tools', 'systemPrompt'];
+/** Configuration schema. */
+export const Config = z.object({
+    planSandbox: z.union([
+        z.const('read-only'),
+        z.const('workspace-write'),
+        z.const('danger-full-access'),
+    ]).required(false),
+    buildSandbox: z.union([
+        z.const('read-only'),
+        z.const('workspace-write'),
+        z.const('danger-full-access'),
+    ]).required(false),
+    denyWriteTools: z.boolean().default(true),
+    section: z.boolean().default(true),
+});
+/**
+ * Plugin entry point.
+ * @param ctx - Cordis context carrying the injected services.
+ * @param config - Validated deployment configuration.
+ */
+export function apply(ctx, config = {}) {
+    const planSandbox = config.planSandbox ?? DEFAULT_PLAN_SANDBOX;
+    const buildSandbox = config.buildSandbox ?? DEFAULT_BUILD_SANDBOX;
+    if (planSandbox === buildSandbox) {
+        throw new Error(`planSandbox and buildSandbox must be different, but both are '${planSandbox}'.`);
+    }
+    const denyWriteTools = config.denyWriteTools !== false;
+    const enableSection = config.section !== false;
+    ctx.effect(() => {
+        const disposers = [];
+        // Align existing sessions on load (resumed sessions may already have
+        // sandbox/mode events).
+        for (const _agent of ctx.agents.list()) {
+            // No-op on load: state is already in the log; we only react to commands.
+        }
+        // Inject a system prompt section describing the current mode.
+        if (enableSection) {
+            disposers.push(ctx.systemPrompt.section({
+                name: 'plan-build:policy',
+                order: 56,
+                text(context) {
+                    const agent = context.agent;
+                    if (agent === undefined)
+                        return '';
+                    return isPlanModeActive(agent.session.events, planSandbox)
+                        ? 'You are in OpenCode Plan Mode. You are READ-ONLY. You may read files, search code, browse directories, and ask questions. You MUST NOT create, modify, or delete files; run commands that change the system; install packages; run tests/builds; or delegate to subagents/workflows. Present a complete plan and use /plan-build switch build before implementing.'
+                        : 'You are in OpenCode Build Mode. You may edit files, run commands, and execute the approved plan. Make minimal changes, run tests/verification after changes, and ask for confirmation before destructive git operations or system-wide changes.';
+                },
+            }));
+        }
+        // Block mutating tool calls while in Plan mode.
+        disposers.push(ctx.on('tools/pre-execute', async (exec, next) => {
+            if (!denyWriteTools)
+                return next();
+            const reason = planModeDenial(exec, planSandbox, WRITE_TOOLS);
+            if (reason !== undefined)
+                return { kind: 'deny', reason };
+            return next();
+        }));
+        // User-facing slash command to check or switch Plan/Build mode.
+        // Activates only when a command registry is composed (headless assemblies stay unaffected).
+        ctx.inject(['commands'], (commandCtx) => {
+            disposers.push(commandCtx.commands.register({
+                name: 'plan-build',
+                description: 'Switch between OpenCode Plan and Build modes',
+                input: { hint: '[switch [plan|build]]' },
+                handler: ({ agent, rawInput }) => {
+                    const arg = rawInput.trim().toLowerCase();
+                    const active = isPlanModeActive(agent.session.events, planSandbox);
+                    if (arg === '') {
+                        return {
+                            kind: 'success',
+                            text: active
+                                ? 'Plan mode is active (read-only). Use /plan-build switch build to enter Build mode.'
+                                : 'Build mode is active. Use /plan-build switch plan to enter Plan mode.',
+                        };
+                    }
+                    if (!arg.startsWith('switch')) {
+                        return {
+                            kind: 'error',
+                            text: 'Usage: /plan-build, /plan-build switch, /plan-build switch plan, or /plan-build switch build.',
+                        };
+                    }
+                    const target = arg.slice('switch'.length).trim().toLowerCase();
+                    if (target === '') {
+                        const next = active ? 'build' : 'plan';
+                        setPlanBuildMode(agent, next, planSandbox, buildSandbox);
+                        return { kind: 'success', text: `Switched to ${next} mode.` };
+                    }
+                    if (target !== 'plan' && target !== 'build') {
+                        return {
+                            kind: 'error',
+                            text: 'Usage: /plan-build switch plan, or /plan-build switch build.',
+                        };
+                    }
+                    const targetActive = target === 'plan';
+                    if (active === targetActive) {
+                        return { kind: 'success', text: `Already in ${target} mode.` };
+                    }
+                    setPlanBuildMode(agent, target, planSandbox, buildSandbox);
+                    return { kind: 'success', text: `Switched to ${target} mode.` };
+                },
+            }));
+        });
+        return () => {
+            for (const dispose of disposers)
+                dispose();
+        };
+    });
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAWxC,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,WAAW,GACZ,MAAM,cAAc,CAAA;AAGrB,0BAA0B;AAC1B,MAAM,CAAC,MAAM,IAAI,GAAG,qBAAqB,CAAA;AACzC,8CAA8C;AAC9C,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,cAAc,CAAU,CAAA;AAClE,4BAA4B;AAC5B,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC;QACnB,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC;QACpB,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC;QAC1B,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC;KAC9B,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;IAClB,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC;QACpB,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC;QACpB,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC;QAC1B,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC;KAC9B,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;IAClB,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACzC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CACnC,CAAC,CAAA;AAEF;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,GAAY,EAAE,SAA8B,EAAE;IAClE,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,oBAAoB,CAAA;IAC9D,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,qBAAqB,CAAA;IACjE,IAAI,WAAW,KAAK,YAAY,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,iEAAiE,WAAW,IAAI,CAAC,CAAA;IACnG,CAAC;IACD,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,KAAK,KAAK,CAAA;IACtD,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,KAAK,KAAK,CAAA;IAE9C,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE;QACd,MAAM,SAAS,GAAmB,EAAE,CAAA;QAEpC,qEAAqE;QACrE,wBAAwB;QACxB,KAAK,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,EAAiC,EAAE,CAAC;YACtE,yEAAyE;QAC3E,CAAC;QAED,8DAA8D;QAC9D,IAAI,aAAa,EAAE,CAAC;YAClB,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,OAAO,CAAC;gBACtC,IAAI,EAAE,mBAAmB;gBACzB,KAAK,EAAE,EAAE;gBACT,IAAI,CAAC,OAAwB;oBAC3B,MAAM,KAAK,GAAI,OAA4C,CAAC,KAAK,CAAA;oBACjE,IAAI,KAAK,KAAK,SAAS;wBAAE,OAAO,EAAE,CAAA;oBAClC,OAAO,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC;wBACxD,CAAC,CAAC,oWAAoW;wBACtW,CAAC,CAAC,iPAAiP,CAAA;gBACvP,CAAC;aACF,CAAC,CAAC,CAAA;QACL,CAAC;QAED,gDAAgD;QAChD,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,mBAAmB,EAAE,KAAK,EAAE,IAAmB,EAAE,IAAoC,EAA4B,EAAE;YACvI,IAAI,CAAC,cAAc;gBAAE,OAAO,IAAI,EAAE,CAAA;YAClC,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,CAAC,CAAA;YAC7D,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAA;YACzD,OAAO,IAAI,EAAE,CAAA;QACf,CAAC,CAAC,CAAC,CAAA;QAEH,gEAAgE;QAChE,4FAA4F;QAC5F,GAAG,CAAC,MAAM,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,EAAE;YACtC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAC1C,IAAI,EAAE,YAAY;gBAClB,WAAW,EAAE,8CAA8C;gBAC3D,KAAK,EAAE,EAAE,IAAI,EAAE,uBAAuB,EAAE;gBACxC,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAqB,EAAiB,EAAE;oBACjE,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;oBAEzC,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;oBAElE,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;wBACf,OAAO;4BACL,IAAI,EAAE,SAAS;4BACf,IAAI,EAAE,MAAM;gCACV,CAAC,CAAC,oFAAoF;gCACtF,CAAC,CAAC,uEAAuE;yBAC5E,CAAA;oBACH,CAAC;oBAED,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;wBAC9B,OAAO;4BACL,IAAI,EAAE,OAAO;4BACb,IAAI,EAAE,+FAA+F;yBACtG,CAAA;oBACH,CAAC;oBAED,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;oBAC9D,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;wBAClB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAA;wBACtC,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,YAAY,CAAC,CAAA;wBACxD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,IAAI,QAAQ,EAAE,CAAA;oBAC/D,CAAC;oBAED,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;wBAC5C,OAAO;4BACL,IAAI,EAAE,OAAO;4BACb,IAAI,EAAE,8DAA8D;yBACrE,CAAA;oBACH,CAAC;oBAED,MAAM,YAAY,GAAG,MAAM,KAAK,MAAM,CAAA;oBACtC,IAAI,MAAM,KAAK,YAAY,EAAE,CAAC;wBAC5B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,MAAM,QAAQ,EAAE,CAAA;oBAChE,CAAC;oBAED,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,CAAC,CAAA;oBAC1D,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,MAAM,QAAQ,EAAE,CAAA;gBACjE,CAAC;aACF,CAAC,CAAC,CAAA;QACL,CAAC,CAAC,CAAA;QAEF,OAAO,GAAG,EAAE;YACV,KAAK,MAAM,OAAO,IAAI,SAAS;gBAAE,OAAO,EAAE,CAAA;QAC5C,CAAC,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/lib/invariant.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Package-owned invariant companion for `dsh-plan-build-mode`.
+ *
+ * This plugin stores its state entirely in the existing `sandbox/mode` event
+ * (owned by `@deepseek-ai/dsh-sandbox-policy`), so there is no custom event
+ * type to validate. The companion is kept as a no-op installer so downstream
+ * deployments can still mount `dsh-plan-build-mode/invariant` if desired.
+ *
+ * @module dsh-plan-build-mode/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "dsh-plan-build-mode-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: readonly ["invariants"];
+/**
+ * Register the plan-build-mode invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context & {
+    invariants: unknown;
+}) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAGlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,kCAAkC,CAAA;AACnD,2EAA2E;AAC3E,eAAO,MAAM,MAAM,yBAA0B,CAAA;AAO7C;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAS,OAAO,GAAG;IAAE,UAAU,EAAE,OAAO,CAAA;CAAE,KAAG,OAAO,CAAC,MAAM,IAAI,CAM9E,CAAA"}

package/lib/invariant.js

@@ -0,0 +1,25 @@
+/**
+ * Package-owned invariant companion for `dsh-plan-build-mode`.
+ *
+ * This plugin stores its state entirely in the existing `sandbox/mode` event
+ * (owned by `@deepseek-ai/dsh-sandbox-policy`), so there is no custom event
+ * type to validate. The companion is kept as a no-op installer so downstream
+ * deployments can still mount `dsh-plan-build-mode/invariant` if desired.
+ *
+ * @module dsh-plan-build-mode/invariant
+ */
+/** Cordis companion plugin name. */
+export const name = 'dsh-plan-build-mode-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/** No-op installer: state lives in sandbox/mode, validated by dsh-sandbox-policy. */
+const install = Object.assign(() => {
+    // Intentionally empty: this plugin does not introduce new session event types.
+}, { inject: [] });
+/**
+ * Register the plan-build-mode invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register('dsh-plan-build-mode', install));
+//# sourceMappingURL=invariant.js.map

package/lib/invariant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.js","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,oCAAoC;AACpC,MAAM,CAAC,MAAM,IAAI,GAAG,+BAA+B,CAAA;AACnD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,YAAY,CAAU,CAAA;AAE7C,qFAAqF;AACrF,MAAM,OAAO,GAAuB,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE;IACrD,+EAA+E;AACjF,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAA;AAElB;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,GAAsC,EAAuB,EAAE,CACnF,OAAO,CAAC,OAAO,CACZ,GAAG,CAAC,UAAoF,CAAC,QAAQ,CAChG,qBAAqB,EACrB,OAAO,CACR,CACF,CAAA"}

package/lib/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared types for `dsh-plan-build-mode`.
+ * @module dsh-plan-build-mode/types
+ */
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
+declare module '@deepseek-ai/dsh-session/types' {
+}
+/**
+ * Deployment configuration for the Plan/Build mode plugin.
+ */
+export interface PlanBuildModeConfig {
+    /**
+     * Sandbox mode enforced while Plan mode is active.
+     * @default 'read-only'
+     */
+    planSandbox?: SandboxMode;
+    /**
+     * Sandbox mode enforced while Build mode is active.
+     * @default 'workspace-write'
+     */
+    buildSandbox?: SandboxMode;
+    /**
+     * Whether to deny known write tools while in Plan mode + read-only sandbox.
+     * @default true
+     */
+    denyWriteTools?: boolean;
+    /**
+     * Whether to inject the `plan-build:policy` system prompt section.
+     * @default true
+     */
+    section?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAE3D,OAAO,QAAQ,gCAAgC,CAAC;CAG/C;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB;;;OAGG;IACH,YAAY,CAAC,EAAE,WAAW,CAAA;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB"}

package/lib/types.js

@@ -0,0 +1,6 @@
+/**
+ * Shared types for `dsh-plan-build-mode`.
+ * @module dsh-plan-build-mode/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@xth26/dsh-plan-build-mode",
+  "description": "OpenCode-style Plan / Build hard permission model for DSH",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-agent": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-commands": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-invariants": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-sandbox": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-sandbox-policy": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-system-prompt": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    },
+    "@deepseek-ai/schemastery": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "link:../deepseek-harness/vendor/cordis",
+    "@deepseek-ai/dsh-agent": "link:../deepseek-harness/packages/core/agent",
+    "@deepseek-ai/dsh-commands": "link:../deepseek-harness/packages/interaction/commands",
+    "@deepseek-ai/dsh-invariants": "link:../deepseek-harness/packages/runtime-diagnostics/invariants",
+    "@deepseek-ai/dsh-sandbox": "link:../deepseek-harness/packages/sandbox/sandbox",
+    "@deepseek-ai/dsh-sandbox-policy": "link:../deepseek-harness/packages/sandbox/sandbox-policy",
+    "@deepseek-ai/dsh-session": "link:../deepseek-harness/packages/core/session",
+    "@deepseek-ai/dsh-system-prompt": "link:../deepseek-harness/packages/core/system-prompt",
+    "@deepseek-ai/dsh-tools": "link:../deepseek-harness/packages/core/tools",
+    "@deepseek-ai/schemastery": "link:../deepseek-harness/vendor/schemastery",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}